Documentation
¶
Index ¶
- func RunPreParse(root *cobra.Command, engine *Engine)
- type Context
- type Correction
- type Engine
- func (e *Engine) HandlerCount() int
- func (e *Engine) Handlers(phase Phase) []Handler
- func (e *Engine) HasHandlers(phase Phase) bool
- func (e *Engine) Register(h Handler)
- func (e *Engine) RegisterAll(handlers ...Handler)
- func (e *Engine) Run(ctx *Context) error
- func (e *Engine) RunPhase(phase Phase, ctx *Context) error
- type FlagInfo
- type Handler
- type Phase
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RunPreParse ¶
RunPreParse resolves the target command from the raw args, extracts flag names from the Cobra command tree, and runs all PreParse handlers. The corrected args are set back on the root command via SetArgs so that Cobra's subsequent ExecuteC uses the corrected values.
If the target command cannot be resolved (e.g. the user typed a non-existent command), PreParse is skipped silently and Cobra will handle the error.
Types ¶
type Context ¶
type Context struct {
// Args is the raw argv slice (available from PreParse onward).
// PreParse handlers may rewrite this in place.
Args []string
// Command is the resolved product.tool canonical path
// (available from PostParse onward).
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
// Corrections records every correction applied by handlers,
// enabling downstream logging and debugging.
Corrections []Correction
}
Context carries mutable state through the handler chain. Each phase populates additional fields; earlier-phase fields remain available in later phases so that handlers can correlate raw input with structured parameters.
type 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
}
Correction records a single input correction applied by a handler.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine manages handler registration and executes the pipeline chain. Handlers are grouped by phase and executed in registration order within each phase. The engine is safe to use concurrently for reads after all handlers have been registered; registration itself is not concurrent-safe and should be done at startup.
func NewEngine ¶
func NewEngine() *Engine
NewEngine creates a pipeline engine with no registered handlers.
func (*Engine) HandlerCount ¶
HandlerCount returns the total number of registered handlers across all phases.
func (*Engine) Handlers ¶
Handlers returns the registered handlers for a given phase, in registration order. The returned slice must not be modified.
func (*Engine) HasHandlers ¶
HasHandlers reports whether at least one handler is registered for the given phase.
func (*Engine) Register ¶
Register adds a handler to its declared phase. Handlers within the same phase execute in registration order.
func (*Engine) RegisterAll ¶
RegisterAll registers multiple handlers at once.
func (*Engine) Run ¶
Run executes all phases in order: Register → PreParse → PostParse → PreRequest → PostResponse. Each phase runs its handler chain completely before the next phase begins.
Callers typically do not use Run directly — the CLI integration calls RunPhase at each stage of the execution flow. Run is provided for testing and for cases where the full pipeline must be exercised in one shot.
type FlagInfo ¶
type FlagInfo struct {
// Name is the canonical kebab-case flag name (e.g. "user-id").
Name 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
}
FlagInfo describes a single CLI flag derived from a tool's input schema. PreParse handlers use this to recognise valid flag names when performing fuzzy matching or alias resolution.
func FlagInfoFromCommand ¶
FlagInfoFromCommand extracts FlagInfo entries from a Cobra command's registered flags (both local and inherited).
JSON Schema "format" and "enum" hints injected via pflag annotations (x-cli-format / x-cli-enum, see internal/compat/dynamic_commands.go) are surfaced on FlagInfo so PreParse handlers can validate sticky-split candidates against the actual schema, not just the pflag type.
type Handler ¶
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
}
Handler is the core abstraction for pipeline extensions. Each handler declares the phase it belongs to and provides a Handle method that receives a mutable context. Handlers are executed in registration order within a phase; each handler's output becomes the next handler's input.
A handler that returns a non-nil error aborts the chain — no further handlers in the same phase (or subsequent phases) will run.
type Phase ¶
type Phase int
Phase represents a named stage in the CLI execution pipeline. Handlers are grouped by phase and executed in chain order within each phase. Phases themselves execute in a fixed order defined by the engine.
const ( // Register runs at CLI startup when the Cobra command tree is // being built. Handlers can add, remove, or modify commands. Register Phase = iota // PreParse runs before Cobra parses the raw argv. Handlers // receive the raw argument slice and can rewrite it — for // example to fix flag-name typos or split glued values. PreParse // PostParse runs after Cobra has successfully parsed flags and // args. Handlers receive structured parameters plus the tool // schema, enabling value-level corrections such as date format // normalisation. PostParse // PreRequest runs after validation, just before the JSON-RPC // call is dispatched. Handlers can inspect or mutate the final // payload. PreRequest // PostResponse runs after the transport returns a result and // before the output is written to stdout. PostResponse )
Source Files
Directories