cli

type Code = protocol.Code

type Command struct {
	// Name is the first argv word that selects the command.
	Name string
	// Args is the argv summary shown after the name in help, without the
	// global flags.
	Args string
	// Summary is the one-line description shown by `brigade help`.
	Summary string
	// Hidden keeps the command out of `brigade help` but not out of
	// `brigade help --all` or `brigade help <name>` (6.4).
	Hidden bool
	// MultiCall marks the entrypoints internal/app intercepts before the
	// human command table: `hook`, `watch` and `adapter`.
	MultiCall bool
	// Task names the plan task that implements the command. It is set only
	// while the command is still a placeholder, and is what the
	// not-implemented message points the caller at. No entry carries one
	// since P5-9 filled `inbox`; the mechanism stays for the next one.
	Task string
	// Flags registers the command's own flags. The global flags are added
	// separately, so a command must not register --json or --log-level.
	Flags func(fs *flag.FlagSet)
	// Raw hands Run everything after the command word verbatim instead of
	// parsing it: the terminal pass-through commands (`team`, `profile`)
	// forward adapter flags the harness has never heard of, so their
	// grammar is their own (6.4). The global flags BEFORE the command
	// word still apply, --json is honoured wherever it appears, and the
	// poison scan runs first as for every command.
	Raw bool
	// Run executes the command. It is nil exactly when Task is set.
	Run func(cx *Context, args []string) error
}

type Context struct {
	Streams
	// Environ is the process environment in os.Environ() form. Commands
	// read configuration from here, never from os.Getenv, so a test can
	// hand a command an environment without mutating its own (3.2, 7.3).
	Environ []string
	// JSON is the global --json flag: the protocol envelope on stdout
	// instead of human output.
	JSON bool
	// LogLevel is the global --log-level flag, validated against LogLevels.
	LogLevel string
	// Command is the resolved command name.
	Command string
	// Flags is the command's own parsed flag set.
	Flags *flag.FlagSet
}

type Error struct {
	// Code selects the exit status and appears as `error.code`.
	Code Code
	// Message is short, human-readable and safe to show to a model: no raw
	// server text, no SQL, no tokens (4.3).
	Message string
	// RetryAfterMS is emitted only when non-zero (rate_limited).
	RetryAfterMS int
	// Details is optional and adapter-specific (4.3).
	Details map[string]string
	// Command names the command for the one-line stderr form. Empty when
	// the failure happened before a command was resolved.
	Command string
}

type Streams struct {
	In  io.Reader
	Out io.Writer
	Err io.Writer
}

type SyncAdapterFunc func(args []string, stdin io.Reader, stdout, stderr io.Writer, environ []string) int