complete

type Action struct {
	Args                []string // preceding positional args from the shell
	Complete            string   // dynamic completion type (--@complete value)
	InstallCompletion   bool
	PrintCompletion     bool
	Shell               string // resolved shell name
	UnknownFlags        []string
	UninstallCompletion bool
}

type CompletionFlags struct {
	Complete            string
	Shell               string
	InstallCompletion   bool
	UnknownFlags        []string
	UninstallCompletion bool
	PrintCompletion     bool
}

type FlagMeta struct {
	Alias               string   // command invoked by this alias command
	Aliases             []string // flag aliases
	Complete            string   // completion directive
	CompleteWhenHidden  bool     // still offer this flag in completions even when hidden from help
	Default             string   // default value for non-enum flags (rendered as " (default: X)" suffix)
	Enum                []string // enum values
	EnumDefault         string   // default value annotation for enum display
	EnumHighlight       []string // highlight hint substrings (parallel to Enum)
	EnumTerse           []string // short descriptions for enum values (parallel to Enum)
	Extension           string   // file extension filter for completion (e.g. "yaml" or "yaml,yml")
	Forward             bool     // forward this flag's value to dynamic completion handlers
	Group               string   // help section group
	HasArg              bool     // true if the flag takes a value (non-bool)
	Help                string   // help text for --help output
	HideDefault         bool     // suppress the default-value annotation in help output
	Hidden              bool     // hidden flag
	HideLong            bool     // hide the long flag from help output
	HideShort           bool     // hide the short flag from help output
	Order               Order    // completion ordering mode
	InversePrefix       string   // prefix for negated flag (default "no-")
	IsArg               bool     // true if this is a positional argument
	IsCSV               bool     // true if the field type is CSVFlag or *CSVFlag
	IsSlice             bool     // true if the field type is a slice
	Name                string   // flag name
	Negatable           bool     // true if the flag supports --no- prefix
	NegativeOnly        bool     // advertise only the --no- variant in help
	NegativeDesc        string   // explicit description for --no- variant
	NoIndent            bool     // suppress short-flag alignment indent in help
	Optional            bool     // true if arg is optional
	Origin              string   // where this metadata came from (e.g. struct field name)
	Persistent          bool     // true if the flag remains available on descendant subcommands
	Placeholder         string   // placeholder like <value>
	PlaceholderOverride bool     // true if placeholder was set via clib tag
	PositiveDesc        string   // explicit description for positive variant (negatable flags)
	PositiveOnly        bool     // advertise only the positive variant in help
	Short               string   // short flag letter
	Terse               string   // very short description for completions
	ValueHint           string   // value type hint for completion (file, dir, command, user, host, url, email)
}

type Generator struct {
	AppName              string
	DynamicArgs          []string // per-position dynamic completion; final entry repeats for additional positional args
	HasMaxPositionalArgs bool
	IncludeHidden        bool // offer hidden flags as completions instead of omitting them
	MaxPositionalArgs    int
	Order                Order
	Specs                []Spec
	Subs                 []SubSpec
}

type Handler func(shell, kind string, args []string)

type Option func(*Generator)

type Order string

type PreflightOption func(*preflightConfig)

type ShellFunc func(g *Generator) (string, error)

type Spec struct {
	CommaList  bool        // comma-separated multi-value (e.g. --columns)
	Dynamic    string      // dynamic completion type (e.g. "author" -> "<app> --@complete=author")
	Extension  string      // file extension filter for completion (e.g. "yaml" or "yaml,yml")
	Forward    bool        // forward this flag's value to dynamic completion handlers
	HasArg     bool        // flag takes a value
	Hidden     bool        // hidden from completions
	LongFlag   string      // e.g. "author" (no dashes)
	Order      Order       // completion ordering mode
	Persistent bool        // true if the flag remains available on descendant subcommands
	ShortFlag  string      // e.g. "a" (no dash)
	Terse      string      // very short description for tab completion
	ValueDescs []ValueDesc // static values with descriptions (takes precedence over Values)
	ValueHint  string      // value type hint: file, dir, command, user, host, url, email
	Values     []string    // static completion values (from enum)
}

type SubSpec struct {
	Aliases              []string // command aliases (e.g. ["up"] for "update")
	DynamicArgs          []string // per-position dynamic completion; final entry repeats for additional positional args
	HasMaxPositionalArgs bool
	MaxPositionalArgs    int
	Name                 string    // subcommand name (e.g. "bump")
	PathArgs             bool      // enable file completion for positional args
	Specs                []Spec    // subcommand-specific flag specs
	Subs                 []SubSpec // nested subcommands
	Terse                string    // short description for tab completion
}

type ValueDesc struct {
	Value string
	Desc  string
}