pipeline

type BoolValueConflictError struct {
	Command string
	Flag    string
	Values  []string
}

type CommandPathFallback struct {
	From       string
	Mode       string
	To         string
	Candidates []string
}

type CommandPathFallbackLookup func(path string) (CommandPathFallback, bool)

type Context struct {
	// Args is the raw argv slice (available from PreParse onward).
	// PreParse handlers may rewrite this in place.
	Args []string

	// Command identifies the resolved command. RunPreParse fills it with
	// Cobra's raw CommandPath() (e.g. "dws chat message send-by-bot") so
	// PreParse handlers can key per-command tables; the PostParse pipeline
	// fills it with the resolved product.tool canonical path. The two phases
	// use independent Context instances, so the differing forms never mix.
	Command string

	// Params holds structured key→value parameters after Cobra
	// parsing (available from PostParse onward). Handlers may
	// mutate values or add/remove keys.
	Params map[string]any

	// Schema is the JSON Schema for the resolved tool's input
	// (available from PostParse onward). Handlers must treat this
	// as read-only.
	Schema map[string]any

	// Payload is the merged, validated payload ready to be sent
	// over the wire (available from PreRequest onward).
	Payload map[string]any

	// Response is the JSON-RPC result returned by the server
	// (available from PostResponse onward). Handlers may mutate
	// the response before it is written to stdout.
	Response map[string]any

	// FlagSpecs provides the list of known flag names for the
	// current tool, derived from the input schema. PreParse
	// handlers use this to match against raw argv tokens.
	FlagSpecs []FlagInfo

	// ProtectedFlags carries reviewed semantic guard decisions across the
	// complete PreParse chain. Keys are morphed flag names. Sticky and fuzzy
	// handlers must not reinterpret a name classified as blocked or ambiguous
	// by the semantic alias table.
	ProtectedFlags map[string]FlagProtection

	// Corrections records every correction applied by handlers,
	// enabling downstream logging and debugging.
	Corrections []Correction
}

type Correction struct {
	// Handler is the name of the handler that applied the correction.
	Handler string

	// Phase is the pipeline phase in which the correction occurred.
	Phase Phase

	// Field identifies the affected flag or parameter name.
	Field string

	// Original is the value before correction.
	Original string

	// Corrected is the value after correction.
	Corrected string

	// Kind classifies the correction (e.g. "alias", "sticky", "case").
	Kind string
}

type Engine struct {
	// contains filtered or unexported fields
}

type FlagConflictError struct {
	Command   string
	Canonical string
	Spellings []string
}

type FlagInfo struct {
	// Name is the canonical kebab-case flag name (e.g. "user-id").
	Name string

	// Shorthand is the optional single-character pflag shorthand (e.g. "y"
	// for --yes). PreParse uses exact shorthand tokens when normalising
	// explicit boolean values; shorthand clusters retain native pflag syntax.
	Shorthand string

	// PropertyName is the original schema property key (e.g. "userId").
	PropertyName string

	// Type is the JSON Schema / pflag type ("string", "integer",
	// "bool", "stringSlice", "duration", etc.).
	Type string

	// Format carries the JSON Schema "format" hint when present —
	// e.g. "date", "date-time", "duration", "email", "uri", "ipv4".
	// PreParse handlers use this to decide whether a suffix in a
	// glued token (e.g. "--starttime1") looks like a plausible value.
	Format string

	// Enum carries the JSON Schema "enum" string values when present.
	// PreParse handlers use this for sticky-split validation: a glued
	// suffix is accepted only if it matches one of the enum entries.
	Enum []string
}

type FlagProtection string

type FlagProtectionResolver interface {
	ResolveFlagProtection(rawCommandPath, morphedFlag string) (FlagProtection, bool)
}

type Handler interface {
	// Name returns a short, unique identifier for the handler
	// (e.g. "sticky", "alias", "date-normalise"). Used in
	// correction records and log output.
	Name() string

	// Phase returns the pipeline phase this handler belongs to.
	Phase() Phase

	// Handle processes the context and returns an error to abort
	// the chain, or nil to continue.
	Handle(ctx *Context) error
}

type HandlerError struct {
	Phase   Phase
	Handler string
	Cause   error
}

type Phase int

type StickyFlagPair struct {
	Flag   string
	Value  string
	Inline bool
}