cli

type Command struct {
	// Name is the command. A help request is NameHelp whatever way it was asked for.
	Name Name
	// PlanPath is the --plan file; set only for PlanFile.
	PlanPath string
	// PlanJSON is the --plan-json text; set only for PlanInline.
	PlanJSON string
	// BaseDir is --base-dir; set only for PlanStdin and PlanInline.
	BaseDir string
	// Output is -o/--output, relative to the working directory; empty when the plan names the output.
	Output string
	// FitTo is the optional portrait target, overriding the plan declaration.
	FitTo    assembly.FitTarget
	Progress ProgressMode
	// ReportPath is --report for build and check, relative to the working directory.
	ReportPath string
	// ReportFile is the saved report that the report command reads.
	ExpectAttempt string
	ReportFile    string
	// Part is --part, the id of one contribution.
	Part string
	// View is --view: "parts" or "diagnostics".
	View string
	// SchemaName is the schema command's operand: "plan", "report" or "response".
	SchemaName string
	// HelpFor is the command a help request is about; empty for the root help.
	HelpFor Name
	// Operands are the direct PDF paths and --blank directives in command-line order, for PlanOperands.
	// Each Position is the operand's zero-based index in the arguments, excluding the executable.
	Operands []assembly.Operand
	// Page is --page, a 1-based output page; HasPage preserves explicit zero.
	Page int64
	// Offset and Limit page a View; HasOffset and HasLimit say whether they were given.
	Offset int64
	Limit  int64
	// Jobs is --jobs; 0 means unset, and an explicit value is at least 1.
	Jobs int
	// Format is the rendering requested with --format; JSON unless a valid --format text was given.
	Format Format
	// PlanSource selects which of PlanPath, PlanJSON, and Operands carries the instructions.
	PlanSource PlanSource
	// Details is --details: the complete result for build and check, full records for report.
	Details bool
	// Overwrite is --overwrite.
	Overwrite bool
	// HasPage, HasOffset and HasLimit distinguish a given 0 from an absent option.
	HasPage, HasOffset, HasLimit bool
}

type Format uint8

type HelpCommand struct {
	Name    Name   `json:"name"`
	Summary string `json:"summary"`
}

type HelpDoc struct {
	Next           *[]string      `json:"next"`
	ExecutableFrom string         `json:"executable_from,omitempty"`
	NextArgs       []string       `json:"next_args,omitempty"`
	Templates      []HelpTemplate `json:"templates,omitempty"`
	// Kind is always "help".
	Kind string `json:"kind"`
	// Command is the command described; absent for the root help.
	Command Name   `json:"command,omitempty"`
	Summary string `json:"summary"`
	// Example illustrates command grammar; Next carries runtime executable authority.
	Example string   `json:"example"`
	Usage   []string `json:"usage"`
	// Commands lists the commands; present only in the root help.
	Commands []HelpCommand `json:"commands,omitempty"`
	// Options lists exactly the options that apply.
	Options       []HelpOption `json:"options"`
	Notes         []string     `json:"notes,omitempty"`
	FormatVersion int          `json:"format_version"`
	NextOmitted   bool         `json:"next_omitted,omitzero"`
}

type HelpOption struct {
	Name    string `json:"name"`
	Short   string `json:"short,omitempty"`
	Value   string `json:"value,omitempty"`
	Summary string `json:"summary"`
}

type HelpTemplate struct {
	Description string   `json:"description"`
	Argv        []string `json:"argv"`
}

type Name string

type PlanSource uint8

type ProgressMode string

type UsageError struct {
	// Command is the command being parsed; empty when none was recognized.
	Command Name
	// Diagnostics are the located problems, each with stage "usage".
	Diagnostics []report.Diagnostic
	// Format is how to render the failure: text only when a valid --format text came before the fault.
	Format Format
}