Documentation
¶
Overview ¶
Package humancli implements muster's operator subcommands (agents, inbox, send, tasks) that read/drive the bus from a plain shell.
Index ¶
- Variables
- func Dispatch(args []string, out io.Writer) error
- func HelpFor(name string, out io.Writer) error
- func IsHelpArg(s string) bool
- func ManPage() string
- func ResolveTarget(agents []enrichedAgent, given, caller string) (string, error)
- func Usage(out io.Writer)
- type Command
- type Group
- type UsageError
Constants ¶
This section is empty.
Variables ¶
var Registry []Command
Registry is every muster subcommand, operator-facing and plumbing alike. Do not add a command anywhere else: Dispatch, Usage, HelpFor, and the man renderer all walk this slice, so an entry here is the only thing required for a command to show up consistently everywhere.
Built in init() rather than as a var literal on purpose: several Run closures below call HelpFor, which (via lookup) reads Registry itself. Go's package-initialization-cycle check is a static, conservative approximation that follows every function a var initializer references, transitively — it can't tell that HelpFor is only ever called long after init(), so a `var Registry = []Command{...Run: closureThatCallsHelpFor...}` literal trips a false-positive "initialization cycle for Registry" at compile time. Assigning inside init() sidesteps that check entirely: it's ordinary sequential code, not a variable initializer expression.
Functions ¶
func Dispatch ¶
Dispatch routes an operator subcommand. args[0] is the subcommand name. It also owns muster's help/version surface (`help`, `-h`, `--help`, `version`, `--version`) — cmd/muster's main() routes anything that isn't serve/mcp/debug here, and those three special-case help themselves before ever reaching Dispatch (see cmd/muster/main.go), so this is the one place that needs to recognize them.
func HelpFor ¶ added in v0.7.0
HelpFor writes one command's full usage (synopsis, description, flags with defaults) to out. An unknown name is a UsageError listing valid commands.
func IsHelpArg ¶ added in v0.7.0
IsHelpArg reports whether s is a help flag/word muster recognizes at the front of a command's arguments.
func ManPage ¶ added in v0.7.0
func ManPage() string
ManPage renders muster's man(1) page as roff, generated from the same Registry that drives `muster help` — the man page is never hand-maintained and never committed (see justfile's `man` recipe and .github/workflows/release.yml), so it cannot drift from the CLI's actual commands.
func ResolveTarget ¶
ResolveTarget maps a user-supplied target to a unique agent alias, scoped to caller's project. This is a thin CLI-side wrapper over internal/resolve.Target — the ONE canonical resolver, shared with the daemon's own send_message/task_create validation (see that package's doc comment for the full precedence rules and the black-hole incident it closes). agents carries live tmux-refreshed labels (enrichAgents); a departed row still resolves by exact alias but never by label, exactly like the daemon's roster check.
Types ¶
type Command ¶ added in v0.7.0
type Command struct {
// Name is the subcommand word, e.g. "send".
Name string
// Synopsis is the argument shape shown after the name in usage output,
// e.g. `send <target> "body" [--from <alias>] ...`. It does NOT repeat
// "muster " or the command name.
Synopsis string
// Summary is the one-line description shown in grouped usage listings.
Summary string
// Help is one or more longer paragraphs shown by `muster help <cmd>` /
// `muster <cmd> -h`, below the synopsis. May be empty.
Help string
// Group buckets this command for display.
Group Group
// NewFlags builds a fresh *flag.FlagSet declaring this command's flags,
// for `PrintDefaults`-driven help/man rendering. It is the SAME
// constructor the command's real Run function calls to parse its own
// args (see e.g. newSendFlags) — one declaration, not a help-text copy
// that can drift from the real flags. nil means the command takes no
// flags.
NewFlags func() *flag.FlagSet
// Run executes the command. nil for serve/mcp/debug, which cmd/muster's
// main() owns directly (see the Command doc comment above).
Run func(args []string, out io.Writer) error
}
Command is one row of muster's command registry — the single table that drives bare `muster` / `muster help` (grouped usage), `muster help <cmd>` and `muster <cmd> -h/--help` (per-command usage), and the generated man page. There is deliberately no second list anywhere: cmd/muster's main() routes serve/mcp/debug itself (they need process-level setup this package has no business doing — daemon startup, stdio protocol framing) but still declares a Registry row so help/man rendering covers them; Run is nil for exactly those three, everything else is dispatched through Dispatch.
type Group ¶ added in v0.7.0
type Group int
Group buckets a Command for the grouped bare/`help` listing and the man page's SECTION headings. Order matters: groupOrder below is the only place display order is decided, so adding a group means updating both here and groupOrder.
The four command groups, in the order the operator sees them everywhere (bare usage, `muster help`, the man page): talk first (the thing you do most), watch second, identity third, plumbing last (daemon/dev internals, rarely typed by hand).
type UsageError ¶ added in v0.7.0
type UsageError struct {
// contains filtered or unexported fields
}
UsageError marks a Dispatch error as an operator mistake (unknown command, missing required argument) rather than a runtime failure (a daemon call that failed, a bad flag value). cmd/muster's main() checks for it to decide between exit code 2 (usage) and 1 (everything else) — the conventional split, and the same code bare-invocation-with-no-args already used.
func (*UsageError) Error ¶ added in v0.7.0
func (e *UsageError) Error() string
Error implements the error interface.
Source Files