cli

type App struct {
	// Args is os.Args[1:] — the program name is not included.
	Args []string
	// Env is os.Environ()'s "NAME=value" form.
	Env []string

	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer

	// Now is the only clock the program has. Tests pin it.
	Now func() time.Time

	// HTTP replaces the transport internal/payload would otherwise build. A
	// test points it at an httptest.Server; production leaves it nil.
	HTTP http.RoundTripper

	// Dirs overrides the §4.1 directory layout wholesale. A zero value is
	// derived from Env.
	Dirs config.Paths

	// WorkDir is the directory project discovery (§4.3) walks up from.
	WorkDir string

	// Terminal facts. False is the safe answer: PayCLI never changes output
	// shape based on a TTY (§10), it only uses these for the interactive
	// confirmation prompt (§12.2) and the "you typed a key on a terminal"
	// warning (§5.1 step 3).
	StdinIsTTY  bool
	StdoutIsTTY bool
	StderrIsTTY bool

	// NoSignals disables the SIGINT/SIGTERM handler. Tests set it; the
	// in-process handler would otherwise leak across `go test`.
	NoSignals bool
}

type ArgSpec struct {
	Name       string   `json:"name"`
	Required   bool     `json:"required"`
	Type       string   `json:"type"`
	ValuesFrom string   `json:"values_from,omitempty"`
	Values     []string `json:"values,omitempty"`
	Example    string   `json:"example,omitempty"`
}

type Check struct {
	Name   string `json:"name"`
	Status string `json:"status"`
	Detail string `json:"detail"`
	Hint   string `json:"hint,omitempty"`
	Value  any    `json:"value,omitempty"`
}

type CommandSpec struct {
	Path        []string   `json:"path"`
	Short       string     `json:"short"`
	Args        []ArgSpec  `json:"args"`
	Flags       []FlagSpec `json:"flags"`
	Subcommands []string   `json:"subcommands,omitempty"`
	Output      OutputSpec `json:"output"`
	ExitCodes   []int      `json:"exit_codes"`
	Examples    []Example  `json:"examples"`
	Mistakes    []Mistake  `json:"common_mistakes,omitempty"`
	SeeAlso     []string   `json:"see_also,omitempty"`
}

type Deps struct {
	// RT is the shared runtime.
	RT *Runtime
	// Client is the configured Payload REST client.
	Client *payload.Client
	// Manifest is the discovery index, or nil when discovery could not answer.
	// A nil manifest disables every client-side rejection rather than inventing
	// one, which is §9.3's tri-state rule applied at the top.
	Manifest *discovery.Manifest
	// FetchURL downloads a remote upload source (§13). It is a field so unit
	// tests never reach the network.
	FetchURL func(ctx context.Context, rawurl string) (body io.ReadCloser, contentType string, size int64, err error)
	// contains filtered or unexported fields
}

type DiscoverOptions struct {
	Deep             bool
	AllowWriteProbes bool
	NoLabels         bool
	NoProbes         bool
}

type Example struct {
	Why string `json:"why"`
	Cmd string `json:"cmd"`
}

type FieldMode string

type FlagInfo struct {
	Grammar    string   `json:"grammar,omitempty"`
	Operators  []string `json:"operators,omitempty"`
	Values     []string `json:"values,omitempty"`
	Repeatable bool     `json:"repeatable,omitempty"`
	Min        *int     `json:"min,omitempty"`
	Max        *int     `json:"max,omitempty"`
	// Note is printed in the FLAGS section, e.g. "no-op on this project:
	// localization is disabled".
	Note string `json:"note,omitempty"`
}

type FlagSpec struct {
	Name       string   `json:"name"`
	Shorthand  string   `json:"shorthand,omitempty"`
	Type       string   `json:"type"`
	Repeatable bool     `json:"repeatable"`
	Default    any      `json:"default"`
	Usage      string   `json:"usage"`
	Grammar    string   `json:"grammar,omitempty"`
	Operators  []string `json:"operators,omitempty"`
	Values     []string `json:"values,omitempty"`
	Min        *int     `json:"min,omitempty"`
	Max        *int     `json:"max,omitempty"`
}

type Handler func(ctx context.Context, rt *Runtime, args []string) (*output.Envelope, error)

type Help struct {
	// Synopsis lines are printed verbatim under SYNOPSIS, metavariables and
	// all.
	Synopsis []string

	// Long is optional prose printed under the one-line Short.
	Long string

	// Discovered renders section 3 for this command. Returning nil falls back
	// to the shared collection inventory when Collections is true.
	Discovered func(rt *Runtime, m *discovery.Manifest) []string

	// Collections asks for the shared "collections in this project" block in
	// section 3.
	Collections bool
	// Globals asks for the globals inventory in section 3.
	Globals bool

	// Where and Sort switch on sections 4 and 5. They belong on any command
	// that accepts --where or --sort.
	Where bool
	Sort  bool

	// Args documents the positional arguments for §10.4.
	Args []ArgSpec
	// FlagInfo adds §10.4 detail (grammar, operators, bounds) that pflag
	// cannot express, keyed by flag name.
	FlagInfo map[string]FlagInfo

	Output    OutputSpec
	ExitCodes []int
	Examples  []Example
	Mistakes  []Mistake
	SeeAlso   []string

	// Notes are extra bullet lines printed after FLAGS. Use them for the
	// "this flag is a no-op on this project" callouts §10.5 item 6 requires.
	Notes []string
}

type Mistake struct {
	Wrong string `json:"wrong"`
	Right string `json:"right"`
}

type OutputSpec struct {
	Kind      output.DataKind `json:"data_kind"`
	Paginated bool            `json:"paginated,omitempty"`
	Skeleton  string          `json:"skeleton,omitempty"`
}

type Runtime struct {
	App App

	// Env is the environment snapshot every layer reads from.
	Env config.Env
	// Paths is the resolved §4.1 layout.
	Paths config.Paths
	// Project is the detected Payload project (§4.3), never nil.
	Project *config.Project
	// UserFile and ProjectFile are the two config layers, never nil.
	UserFile    *config.File
	ProjectFile *config.File
	// Cfg is the resolved configuration. Nil until the persistent pre-run has
	// executed, which is why every command handler receives it already set.
	Cfg *config.Resolved

	// Command is the dotted command path of the command being run ("auth
	// login"), used for envelope.command and the audit log.
	Command string

	// Out renders envelopes. Commands must not write to App.Stdout directly.
	Out *output.Writer
	// Log is the structured logger; never nil.
	Log *slog.Logger

	// Flags is the parsed root flag state, exposed so a command can tell
	// "flag not given" from "flag given the default value".
	Flags *rootFlags
	// contains filtered or unexported fields
}