cli

type ArgSchema struct {
	// Name is the argument name.
	Name string `json:"name"`

	// Required indicates whether the argument is mandatory.
	Required bool `json:"required"`

	// Description explains the argument.
	Description string `json:"description"`
}

type CLIError struct {
	// Code is the process exit code.
	Code int

	// Kind is a machine-readable error classifier such as
	// "invalid_args" or "connection_error".
	Kind string

	// Message is the human-readable error description.
	Message string

	// Inner is the wrapped cause, if any.
	Inner error
}

type CommandSchema struct {
	// Name is the command name (e.g. "services").
	Name string `json:"name"`

	// FullPath is the fully qualified command path
	// (e.g. "aperturecli services list").
	FullPath string `json:"full_path"`

	// Description is the short description of the command.
	Description string `json:"description"`

	// LongDescription is the detailed description, if available.
	LongDescription string `json:"long_description,omitempty"`

	// Args describes the positional arguments.
	Args []ArgSchema `json:"args,omitempty"`

	// Flags lists all flags accepted by this command.
	Flags []FlagSchema `json:"flags,omitempty"`

	// Subcommands lists child commands, if any.
	Subcommands []CommandSchema `json:"subcommands,omitempty"`

	// ExitCodes documents the semantic exit codes.
	ExitCodes map[int]string `json:"exit_codes,omitempty"`
}

type FlagSchema struct {
	// Name is the long flag name (without --).
	Name string `json:"name"`

	// Short is the single-character shorthand, if any.
	Short string `json:"short,omitempty"`

	// Type is the value type (string, bool, int, etc.).
	Type string `json:"type"`

	// Default is the default value as a string.
	Default string `json:"default,omitempty"`

	// Description explains the flag.
	Description string `json:"description"`
}