registry

type Aliaser interface {
	AliasOf() string
}

type Command interface {
	Name() string
	Description() string
	Execute(ctx any, args args.Args) tea.Cmd
}

type CommandSpec struct {
	// Usage is the positional usage, e.g. "[command]" or "" for none.
	Usage string
	// Detail is optional prose rendered under USAGE — explain modes,
	// e.g. that running with no flags starts an interactive flow.
	Detail string
	// Flags is the accepted-flag allow-list for strict validation.
	Flags []FlagSpec
	// Examples are full example invocations, incl. the leading ':'.
	Examples []string

	// Passthrough disables both help interception and strict flag
	// validation for this command: every argument reaches Execute
	// unchanged. Intended only for delegating/unavailable stubs (e.g.
	// the OSS bootstrap stub) that must keep their own messaging and
	// must not document Pro internals in the OSS repo.
	Passthrough bool
}

type CommandWithAliases struct {
	Command
	Aliases []string
}

type CommandWithSpec interface {
	Spec() CommandSpec
}

type FlagSpec struct {
	Name        string // long flag, without leading "--" (e.g. "node-id")
	Short       string // optional single-char alias without "-"; "" = none
	TakesValue  bool   // false ⇒ boolean (--force); true ⇒ --host <value>
	Placeholder string // usage value placeholder, e.g. "<host>"; used only if TakesValue
	Description string
}