tools

Documentation

Overview

Package tools discovers and runs user-defined scripts from ~/.config/stool/tools/. Each script is a standalone executable file; metadata (scope/target) is declared via "# stool:key=value" header comments rather than a separate registry file.

Index

• Constants
• func Delete(path string) error
• func Dir() (string, error)
• func New(name string, scope Scope, target Target) (string, error)
• func ReadScript(t Tool) (string, error)
• func SeedBuiltins() error
• func Substitute(script string, p Placeholders) string
• func SubstituteAnswers(script string, answers map[string]string) string
• type Choice
  • func PublicKeys() []Choice
• type Placeholders
• type Question
  • func ParseQuestions(script string) []Question
• type Scope
• type Target
• type Tool
  • func List() ([]Tool, error)

Constants

const (
	ScopeSingle Scope = "single"
	ScopeMulti  Scope = "multi"

	TargetLocal  Target = "local"
	TargetRemote Target = "remote"
)

Functions

func Delete

func Delete(path string) error

Delete removes a tool script file.

func Dir

func Dir() (string, error)

func New

func New(name string, scope Scope, target Target) (string, error)

New creates a new tool script file with a shebang and header comments, marked executable, ready to be opened in an editor.

func ReadScript

func ReadScript(t Tool) (string, error)

ReadScript returns the raw, unsubstituted contents of a tool file.

func SeedBuiltins

func SeedBuiltins() error

SeedBuiltins writes the bundled starter tools into ~/.config/stool/tools/ on startup, but never overwrites a file that already exists — so the user's own edits (or deletions) are preserved across upgrades. This is how the `go install`-ed binary ships ready-made tools: they're embedded in the binary and materialized on first run.

func Substitute

func Substitute(script string, p Placeholders) string

Substitute replaces {{domain}}/{{domains}}/{{host}}/{{ip}} in script with the values in p. Tools receive their data this way (placeholders in the script body) rather than as positional arguments.

func SubstituteAnswers

func SubstituteAnswers(script string, answers map[string]string) string

SubstituteAnswers replaces every interactive placeholder (and the special {{sshpubkey}} token) with the collected answers.

Types

type Choice

type Choice struct {
	Label string // shown to the user
	Value string // substituted into the script when chosen
}

Choice is one option for a multiple-choice question.

func PublicKeys

func PublicKeys() []Choice

PublicKeys lists the user's available public keys as choices whose value is the key's full contents. It gathers them from two sources, deduped:

• ~/.ssh/*.pub files
• the running ssh-agent via `ssh-add -L` (covers 1Password, gpg-agent, and others that hold keys without a .pub file on disk)

type Placeholders

type Placeholders struct {
	Domain  string // single domain (scope=single)
	Domains string // all domains, space-joined (scope=multi)
	Host    string // ssh target alias or user@ip; "" for local
	IP      string // resolved IP if known
}

Placeholders are the substitution tokens available inside a tool script.

type Question

type Question struct {
	Key     string
	Prompt  string
	Choices []Choice
}

Question is something stool asks the user before running a tool, then substitutes the answer back into the script. Free-text when Choices is nil.

func ParseQuestions

func ParseQuestions(script string) []Question

ParseQuestions scans a tool script for interactive placeholders and returns the distinct questions to ask (deduplicated by key, first prompt wins, in order of first appearance).

type Scope

type Scope string

type Target

type Target string

type Tool

type Tool struct {
	Name   string
	Path   string
	Scope  Scope
	Target Target
}

func List

func List() ([]Tool, error)

List scans the tools directory and returns every executable script found, parsing its "# stool:" header comments for scope/target metadata.