cli

type Command struct {
	// Name identifies the command. It must start with a letter and contain only letters, digits,
	// dashes, or underscores.
	Name string

	// Usage overrides the generated usage line. Angle brackets usually mark required arguments,
	// square brackets optional arguments, and an ellipsis repeated arguments.
	//
	//	Usage: "echo [flags] <text>..."
	Usage string

	// Summary is the one-line description used in command lists and, when Description is empty, in
	// the command's help.
	Summary string

	// Description is the command's longer help text. Its first line is used in command lists when
	// Summary is empty.
	Description string

	// Help overrides the generated help for --help and [UsageErrorf] errors on this command.
	Help func(*Command) string

	// Flags holds this command's [flag.FlagSet]. Subcommands inherit these flags unless they are
	// marked [FlagConfig.Local].
	Flags *flag.FlagSet

	// FlagConfigs adds behavior to flags already defined in Flags. Each config must name a flag in
	// Flags.
	FlagConfigs []FlagConfig

	// SubCommands are the commands available below this command. A command that only groups
	// subcommands may leave Exec nil.
	SubCommands []*Command

	// Exec runs the selected command. Return [UsageErrorf] for invalid arguments or flag
	// combinations so [Run] prints the command's help.
	Exec func(ctx context.Context, s *State) error
	// contains filtered or unexported fields
}

type FlagConfig struct {
	// Name is the flag's registered name.
	Name string

	// Short is a one-letter alias, such as "v" for --verbose.
	Short string

	// Required makes [Parse] fail unless the user explicitly sets the flag.
	Required bool

	// Local prevents subcommands from inheriting the flag.
	Local bool
}

type FlagName[T any] string

type RunOptions struct {
	// Nil fields default to the corresponding os stream.
	Stdin          io.Reader
	Stdout, Stderr io.Writer
}

type State struct {
	// Args holds positional arguments. Anything after "--" is included as-is.
	Args []string

	// Stdin, Stdout, and Stderr are the command's streams.
	Stdin          io.Reader
	Stdout, Stderr io.Writer

	// Cmd is the selected command.
	Cmd *Command
	// contains filtered or unexported fields
}