cli

Documentation

Overview

Package cli is the native, channel-agnostic command dispatcher. It holds declared contracts.Cmd values keyed by their namespace Path and resolves an argv invocation to one. It imports only contracts: a command's Run may close over anything (a gateway client, a backend), but the registry never sees it.

Index

• func FlagArg(name, value string) []string
• type Registry
  • func (r *Registry) Add(c contracts.Cmd) error
  • func (r *Registry) Dispatch(ctx context.Context, args []string) (string, error)
  • func (r *Registry) Help() string
  • func (r *Registry) Intercept(prefix []string, wrap func(cmd contracts.Cmd, next Runner) Runner)
  • func (r *Registry) Run(ctx context.Context, path []string, in contracts.Input) (string, error)
  • func (r *Registry) Specs() []Spec
• type Runner
• type Spec

Functions

func FlagArg

func FlagArg(name, value string) []string

FlagArg spells a flag and its value as the tokens a dispatch should carry.

parse takes the token after a flag as that flag's value only when it does not itself begin with "--", so a value that does needs the inline "--name=value" form. Free text is where this happens: a task, a typed message, anything an operator or an agent wrote rather than chose.

The inline form is used only where it is needed, and that restraint is the point. The two-token form is what every released daemon parses, and an attached CLI dials a daemon it may predate; switching every argv to a shape an older parser reads as one unknown flag would break every message to buy back the one that was already broken.

Types

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry collects commands and dispatches argv to them.

func (*Registry) Add

func (r *Registry) Add(c contracts.Cmd) error

Add registers a command. It rejects an empty path or a duplicate path.

func (*Registry) Dispatch

func (r *Registry) Dispatch(ctx context.Context, args []string) (string, error)

Dispatch resolves args to the command whose Path is the longest prefix of args, parses the remainder into an Input (--flag value pairs into Args, or --flag=value where the value would itself read as a flag; a valueless optional boolean param becomes "true", while an optional ValueRequired param still needs a following value; anything left over goes to Rest), checks required params, and runs it. It returns the handler's output string.

func (*Registry) Help

func (r *Registry) Help() string

Help renders one usage line per command, sorted by path, for the root help.

func (*Registry) Intercept

func (r *Registry) Intercept(prefix []string, wrap func(cmd contracts.Cmd, next Runner) Runner)

Intercept wraps the handler of every registered command whose Path starts with prefix. wrap receives the command as declared and its current handler, and returns the handler to run in its place; returning next leaves the command untouched. Commands added afterwards are not wrapped, so a caller installs its interceptors once the registry is complete.

func (*Registry) Run

func (r *Registry) Run(ctx context.Context, path []string, in contracts.Input) (string, error)

Run invokes the command at an exact path with a pre-built Input, skipping argv parsing. It is the typed seam for programmatic callers (e.g. the hub's typed SessionControl methods) so they never assemble stringly-typed flag argv that could silently drift from the declared params. Required params are still checked, so a typed caller gets the same validation as the CLI.

func (*Registry) Specs

func (r *Registry) Specs() []Spec

Specs returns every registered command's shape, sorted by path. It exists so a frontend's command menu is derived from what the daemon actually dispatches rather than re-typed beside it: a hand-kept list is a list that silently falls behind, which is how a palette ends up advertising seven of twenty-nine verbs.

type Runner

type Runner func(context.Context, contracts.Input) (string, error)

Runner is a command's handler, named so a caller can wrap one.

type Spec

type Spec struct {
	Path   []string          `json:"path"`
	Help   string            `json:"help,omitempty"`
	Params []contracts.Param `json:"params,omitempty"`
}

Spec is one command's declared shape, without its Run. Help() renders the same facts as a paragraph for a human; a frontend that draws its own menu needs them apart, and handing it the contracts.Cmd would hand it the closure too.