cli

type Command struct {
	Name  string // command word
	Short string // one-line summary for SYNOPSIS and cross-references
	Long  string // multi-paragraph DESCRIPTION body; plain text, no roff markup
	Usage string // SYNOPSIS line, e.g. "magus run <target> [flags] [project...]"

	// Description is the ~120-155 char meta-description emitted into the
	// generated docs page's YAML frontmatter (used for search index + <meta
	// name="description">). Falls back to Short if empty.
	Description string
	// Tags list keywords for the docs page's YAML frontmatter (search index).
	// Auto-augmented with the canonical "cli, magus <name>, <name>" if empty.
	Tags []string

	// Flags are the command-specific flags, as DATA rather than as a closure that
	// registers them.
	//
	// The closure this replaced could only ever be REPLAYED into a FlagSet, so the
	// only question anything could ask of it was "what did you just register" - the
	// answer arrived at runtime, one FlagSet at a time. Nothing could ask for the
	// names ahead of time, which is why a flag name reached the rest of the binary
	// as a string literal, and why the man page's copy of the list could disagree
	// with the CLI's until a test noticed. A slice can be read at generate time, so
	// the names become constants and the two lists become one.
	//
	// Do NOT declare global flags here (--output, -v, --concurrency, --root, --config).
	Flags []Flag

	Examples []Example // EXAMPLES section entries
	Children []Command // navigational subcommands (e.g. "github" under "ci")
	Targets  []Target  // project-scoped targets dispatched by this command

	// ExitStatus documents the codes this command exits with, in ascending order.
	// Empty renders no section at all, which is the right answer for a command that
	// only ever follows the CLI-wide contract (0 success, 1 failure, 2 misuse) - a
	// section repeating that on ninety pages teaches nobody anything.
	//
	// Populate it where a reader would otherwise guess WRONG: a code carrying a
	// command-specific meaning, or a code a neighbouring tool has trained them to
	// expect and this one does not use.
	ExitStatus []ExitCode
}

type Example struct {
	Comment string // e.g. "Build all Go projects"
	Command string // e.g. "magus run build"
}

type ExitCode struct {
	Code    int    // the process exit status
	Meaning string // what it tells the caller; plain text, no roff or Markdown markup
}

type Flag struct {
	Name string   // without leading dashes, e.g. "no-cache"
	Kind FlagKind // which FlagSet method binds it
	Doc  string   // one-line help text

	// Default is the zero value the flag takes when unset: bool, string, int, or
	// time.Duration, matching Kind. A nil Default means the kind's zero value.
	Default any

	// DefaultAtBind means the real default is a runtime value the caller supplies,
	// and Default is only what the docs should show.
	//
	// Some defaults are not literals: --max-shards falls back to the configured
	// ci.max_shards, --budget to a package constant. Written as data, those became
	// hardcoded numbers in the generated binder that DISAGREED with the live
	// binding, silently dropping config support for anything that adopted it. A
	// generated binder for such a command takes a <Command>Defaults argument, so
	// the caller cannot forget to supply the value - leaving it out is a compile
	// error rather than a wrong default nobody notices.
	//
	// Default should still carry the documented value (usually the config default),
	// because the man page has to print something and printing 0 would be a lie.
	DefaultAtBind bool

	// Modes lists the sub-modes that accept this flag; empty means the command's
	// base invocation.
	//
	// `magus affected` is one command with four parses: the run itself, --plan,
	// --impact and --bisect. They are not a base set plus extras - each binds its
	// own set, overlapping the others (--base is accepted by three of them,
	// --max-shards only by --plan). Declared as one merged list, a generated
	// binder for the base parse would accept --max-shards and ignore it, turning
	// a caught mistake into a silent one.
	//
	// A flag accepted by several modes lists them, so it is still DECLARED once.
	// The generator emits one binder per mode.
	Modes []string

	// AliasOf names the flag this one is a second spelling of: --test is AliasOf
	// "t", -b is AliasOf "base". Both names stay real flags and both keep their own
	// help line; what the alias does NOT get is its own value.
	//
	// This is the difference between documenting a shorthand and binding one. The
	// hand-written CLI binds a pair to ONE variable, so -t and --test are the same
	// switch. Modeled as two independent flags, a generated binder gave them two
	// destinations, and setting one left the other false - the shorthand parsed and
	// then did nothing. Every generated struct field is a GROUP: the primary plus
	// its aliases, bound to a single address.
	AliasOf string
}

type FlagKind string

type Page struct {
	Name    string
	Content []byte
}

type Target struct {
	Name  string
	Short string
}