corecmd

package
v1.0.63 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 3, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package corecmd is the shared, dispatch-agnostic base for building commands. It concentrates typed group policy, flag registration, the alias/env/default effective value fallback chain, required validation, cross-flag constraint declaration checks + runtime enforcement, SafetySpec-driven confirmation, toolArgs assembly, and Agent Runtime Schema projection.

Declaration vs execution (framework rule):

  • Declare = Spec data fields (Flags, Constraints, Safety, ConstParams, Use/Short/Long/Example). New registers, validates, confirms, and embeds those facts into dws.schema.*.
  • Execute = Validate / Invoke / Orchestrate / RunE / PostMount. Hooks consume assembled args; they must not invent the CLI surface.
  • Annotate = explicit cobra annotations when a fact is not (yet) a Contract field (e.g. a cross-flag constraint or parameter metadata fact). Inference-only Schema/help is forbidden.
  • Selection / product routing prose is declared on ContractDecl / ProductDecl (delivered as contract_final). schema_hints/ is retired. Identity is collected from ContractFinal.Identity on the live leaves. Interface / dry-run reviewed sources must not create CLI flags.

Full ToolSpec field authority: RFC §5.0.4 / homology §1.4.

It is deliberately dispatch-agnostic: it never calls an MCP tool. LeafSpec (internal/helpers) and Shortcut (internal/shortcut) wrap these primitives and supply dispatch. Invoke / Orchestrate / Ctx are the #830 transitional dispatch API still used in production; the RFC target is mcpbind + Handler (do not treat removal of Invoke/Orchestrate as already landed).

Behavioral contract: flag registration, value fallback, required/constraint semantics, confirmation behavior, and schema projection stay shared across Leaf and Shortcut. Evidence is split: check-generated-drift proves build-time projection; runtime pipeline order is covered by this package's tests plus leaf/risk/constraint unit tests.

Index

Constants

View Source 
const (
	// InputFile allows the flag value @path to be replaced by the file content.
	InputFile = "file"
	// InputStdin allows the flag value - to be replaced by the stdin content.
	InputStdin = "stdin"
)

FlagSpec.Input source constants. They declare extra input sources for a KindString flag beyond the literal command-line value, mirroring the lark-cli Flag.Input capability so large payloads (markdown, JSON, CSV) never need shell quoting.

View Source 
const ConfirmFirstAnnotation = "dws.contract.confirm_first"

ConfirmFirstAnnotation marks commands whose Spec declared ConfirmFirst. The delivery gate reads it to tell a declared guard-first command apart from an accidental confirm-before-validate inversion: guard-first is only legitimate when the declaration says so.

View Source 
const DefaultWaitTimeoutSecs = defaultWaitTimeoutS

DefaultWaitTimeoutSecs is the framework default for --wait-timeout when the declaration carries no reviewed default.

Variables

This section is empty.

Functions

func AnnotateConstraints 

func AnnotateConstraints(cmd *cobra.Command, constraints []Constraint)

AnnotateConstraints records executable relationship constraints for Schema assembly: exactly_one decomposes into require_one_of + mutually_exclusive (matching the handwritten commands' use of AnnotateRuntimeConstraints).

When a group still has hidden siblings, the full declared flag list is retained here (not collapsed to a single visible "required"). ValidateConstraints accepts any member of the declared group — including hidden — so marking the sole visible flag required would falsely claim declare ≡ execute. Final Schema assembly separately canonicalizes reviewed aliases and projects this executable contract onto published inputs.

func AnnotateFlagAlias added in v1.0.59 

func AnnotateFlagAlias(cmd *cobra.Command, aliasName, canonicalName string)

AnnotateFlagAlias records framework-owned evidence that aliasName is a hidden compatibility alias for canonicalName. It is for commands that already own their Cobra flag registration outside FlagSpec but still need the same interface-snapshot alias contract as FlagSpec.Aliases.

func ApplyGroupPolicy added in v1.0.60 

func ApplyGroupPolicy(cmd *cobra.Command, policy GroupPolicy)

ApplyGroupPolicy is the sole declaration API for non-leaf command behavior. Invalid declarations panic because they are framework construction bugs, matching the fail-closed behavior of Spec flag/constraint declarations.

Navigation-only groups receive the shared help/unknown-command RunE. Hybrid groups retain their existing RunE; when they reject positionals, a wrapper sends non-empty args to the same unknown-command resolver before invoking business execution. When recovery is enabled, rejecting positionals deliberately compiles to cobra.ArbitraryArgs: Cobra must not intercept the token with a generic error before command resolution can produce bounded guidance. RecoveryDisabled instead compiles rejection to cobra.NoArgs.

func AttachContract 

func AttachContract(cmd *cobra.Command, safety contract.SafetySpec, decl ContractDecl, short, long string)

AttachContract registers a ContractFinal overlay on an existing leaf without replacing its RunE/Execute body. Used to migrate reviewed facts onto helpers while keeping execution substance frozen. Overwrites any prior ContractFinal on cmd; does not alter an already-installed ConfirmSafety closure.

Production registration always goes through contractfinal.RegisterRuntimeContractFinal (annotate + store). Do not call the store/Register APIs except via contractfinal — no cli-root wrapper exists.

Title/Description stored on the payload are the declared Contract values only. Catalog assembly may prefer Cobra Long for delivered description (Short never enters description) and must stamp provenance to the real winner (cobra_help vs contract_final). Declared Title still wins over Short.

Contract.Wait is rejected here: this overlay path has no Spec, so there is nowhere to pair the WaitPoll / WaitEvents hooks, register --wait / --wait-timeout, or run the wait phase — publishing the declaration would advertise a capability the CLI rejects at flag parse (declaration ⇄ runtime drift). Commands that declare wait must be built through the managed New construction, which validates the pairing and owns the wait phase.

func BoolFlag 

func BoolFlag(cmd *cobra.Command, name string) bool

BoolFlag robustly reads a bool flag that may live on the command, its inherited flags, or the root's persistent flags (e.g. root-injected global --yes / --dry-run).

It ORs across flagsets, matching confirmationBypass. Returning the first resolving flagset instead let a leaf-local --dry-run (default false) shadow a root persistent --dry-run=true, so confirmation could be bypassed as a dry run while Ctx.DryRun() reported false — a real write with no confirmation.

func BuildArgs 

func BuildArgs(cmd *cobra.Command, flags []FlagSpec) (map[string]any, error)

BuildArgs assembles toolArgs from the flag set by binding relationship.

func ConfirmSafety 

func ConfirmSafety(cmd *cobra.Command, safety contract.SafetySpec) error

ConfirmSafety enforces the command's declared confirmation requirement. Effect, risk and idempotency are metadata only and never imply confirmation. Semantics:

  • read-only, --dry-run, --yes, or --user-say-yes → nil (proceed);
  • interactive yes/y → nil;
  • interactive decline → validation "用户取消了操作" (existing command path);
  • no interactive answer (EOF / closed stdin) → confirmation_required.

EOF must not be treated as decline: that silently drops writes in agent/CI. Prompt text is terminal-gated; a readable piped answer is still honored for non-Sheet leaves. Sheet destructive commands keep a separate --yes-only outer gate (helpers.protectSheetMutationCommand) so agents cannot authorize those via stdin alone.

func ConstraintHelp 

func ConstraintHelp(constraints []Constraint) string

ConstraintHelp renders the --help "参数约束" section, matching the shortcut leaf help shape; returns "" when there are no constraints.

func EffectiveValue 

func EffectiveValue(cmd *cobra.Command, flag FlagSpec) string

EffectiveValue reads the value by "explicit main flag → alias → env → registration default" order (string form, integers uniformly formatted); Trim TrimSpace's the result.

func ExecuteCForTest added in v1.0.63 

func ExecuteCForTest(cmd *cobra.Command) (*cobra.Command, error)

ExecuteCForTest is ExecuteForTest with Cobra's executed-command result. Preparation-contract tests should call PrepareCommandTree directly instead.

func ExecuteContextCForTest added in v1.0.63 

func ExecuteContextCForTest(cmd *cobra.Command, ctx context.Context) (*cobra.Command, error)

ExecuteContextCForTest preserves ExecuteContextC context assignment semantics.

func ExecuteContextForTest added in v1.0.63 

func ExecuteContextForTest(cmd *cobra.Command, ctx context.Context) error

ExecuteContextForTest prepares and executes with the supplied Cobra context.

func ExecuteForTest added in v1.0.63 

func ExecuteForTest(cmd *cobra.Command) error

ExecuteForTest prepares standalone test commands as the app factory does, then executes them. Reusing a prepared command preserves Cobra flag state; tests of independent invocations must construct fresh commands. Production must prepare during assembly and call Cobra directly.

func HasDeclaredConfirmFirst 

func HasDeclaredConfirmFirst(cmd *cobra.Command) bool

HasDeclaredConfirmFirst reports whether cmd was built from a Spec that declared ConfirmFirst.

func InterfaceBoolConstParams added in v1.0.59 

func InterfaceBoolConstParams(cmd *cobra.Command) map[string]bool

InterfaceBoolConstParams returns a clone of framework-owned boolean ConstParams evidence. Callers cannot mutate the private registry.

func New 

func New(spec Spec) *cobra.Command

NewCommand builds a cobra command from a Spec. It is the single orchestration path: dispatch declaration check → flag registration → constraint declaration checks → Runtime Schema projection → constraint help → PostMount → generated RunE{ [ConfirmFirst: ConfirmSafety →] required → constraints → Validate → BuildArgs → ConfirmSafety → Invoke/Orchestrate }.

Behavior matches the former helpers.NewLeafCommand, which always dispatched (Call → Server → callMCPTool) and therefore could not express a dispatcher-less spec. Here that is a programming error caught at construction time, so a malformed spec can never run the pipeline — write-confirmation prompt included — and then silently exit 0 having done nothing.

func PrepareCommandTree added in v1.0.63 

func PrepareCommandTree(root *cobra.Command) error

PrepareCommandTree installs the framework's Cobra adapters once, after all built-in, edition and plugin commands and flag handlers have been mounted. It snapshots effective handlers before modifying any node, preserving Cobra's nearest-handler semantics without capturing already adapted ancestors.

Commands must not be mounted or have their hooks replaced after preparation; transparent lifecycle decorators may chain the installed handlers. Repeated execution retains Cobra's flag values and Changed bits: construct a new tree for independent invocations. Repeated preparation is a construction error.

func RegisterFlag 

func RegisterFlag(cmd *cobra.Command, kind FlagKind, name, def, usage string)

RegisterFlag registers one flag by Kind. Default is applied at registration for every kind so --help DefValue matches the declared fallback. Malformed KindInt / KindBool Default values panic at registration (fail-closed) instead of silently degrading to 0 / false.

func RegisterFlags 

func RegisterFlags(cmd *cobra.Command, flags []FlagSpec)

RegisterFlags registers every flag (plus hidden aliases and MarkFlagRequired) declared by the spec set onto cmd.

func ValidateConstraintDecls 

func ValidateConstraintDecls(use string, flags []FlagSpec, constraints []Constraint)

ValidateConstraintDecls validates constraint declarations at build time: an unknown kind, an under-sized flag group, or a reference to an undeclared flag is a programming error and panics so any test/startup path fails immediately rather than at user runtime. use is only used for the panic message.

func ValidateConstraints 

func ValidateConstraints(cmd *cobra.Command, flags []FlagSpec, constraints []Constraint) error

ValidateConstraints enforces the relationship constraints. Error wording matches the shortcut framework's RuntimeContext.AtLeastOne/ExactlyOne/ MutuallyExclusive verbatim, so atomic commands and smart shortcuts fail identically for users and agents.

func ValidateEnums 

func ValidateEnums(cmd *cobra.Command, flags []FlagSpec) error

ValidateEnums enforces the accepted values declared on changed flags. A registration default does not trigger validation, matching Shortcut's historical behavior.

func ValidateGroupPolicy added in v1.0.60 

func ValidateGroupPolicy(p GroupPolicy) error

ValidateGroupPolicy rejects partial declarations, unknown enum values, and combinations whose parsing semantics would be ambiguous.

func ValidateRequired 

func ValidateRequired(cmd *cobra.Command, flags []FlagSpec) error

ValidateRequired reproduces the handwritten required semantics: plain Required flags report a unified "missing required flag(s)" error; Required flags with EnvVar/RequiredHint report their hint separately. The plain group is checked before the env group to preserve the handwritten order. Both groups use the declared "main flag → alias → env" fallback: a compatible alias counts as provided. Shortcut mode keeps its stricter contract: it demands an explicit token, so the main flag or an alias must be Changed on the command line — a registration default does not satisfy it.

func WithValidation added in v1.0.63 

func WithValidation(validate, next func(*cobra.Command, []string) error) func(*cobra.Command, []string) error

WithValidation compiles a validation boundary into an execution step. A validation failure stops the continuation; continuation errors pass through unchanged. Both managed commands and metadata-only migration wrappers use this function so callers do not reimplement failure/continuation ordering.

Types

type Constraint 

type Constraint struct {
	Kind  ConstraintKind
	Flags []string
	// PresenceOnly counts explicitly supplied flags, including empty strings
	// used to clear values in a partial update. Defaults remain unchanged.
	PresenceOnly bool
	// Description, when non-empty, replaces the constraint's default help text.
	Description string
}

Constraint declares a relationship over a group of flags. It is enforced after required validation and before the framework's Validate hook; "provided" reuses the effective-value fallback chain (explicit main flag → alias → env), so passing a compatible alias counts as provided — a capability the shortcut framework's bare Changed check lacks. The constraint is also projected into the Agent Runtime Schema (mutually_exclusive / require_one_of) and rendered into the --help "参数约束" section.

type ConstraintKind 

type ConstraintKind string

ConstraintKind is the type of a cross-flag relationship constraint. Values match the shortcut framework's ConstraintKind verbatim. 

const (
	// AtLeastOne requires at least one of Flags to be provided.
	AtLeastOne ConstraintKind = "at_least_one"
	// ExactlyOne requires exactly one of Flags to be provided.
	ExactlyOne ConstraintKind = "exactly_one"
	// MutuallyExclusive allows at most one of Flags.
	MutuallyExclusive ConstraintKind = "mutually_exclusive"
	// Custom documents validation implemented by Spec.Validate. command
	// validates the declaration and renders its help, but does not infer the
	// command-specific runtime rule.
	Custom ConstraintKind = "custom"
)

type ContractDecl 

type ContractDecl struct {
	Title       string
	Description string // required at construction; Catalog may prefer Cobra Long
	Positionals []contract.RuntimeSchemaPositional
	Parameters  []contract.ParamDecl
	DryRun      *contract.DryRunSpec
	Wait        *contract.WaitSpec
	Result      *contract.ResultSpec
	Pagination  *contract.PaginationSpec
	Interface   *contract.InterfaceSpec
	Selection   contract.SelectionSpec
	Identity    contract.ToolIdentitySpec
}

ContractDecl is the authoring-time leaf contract declaration.

Naming: this is not a Catalog / ToolSpec "Schema" object. Authors declare leaf Contract facts (selection / interface / parameters / dry-run / identity prose). AttachContract converts once into contract.ContractFinalPayload; Catalog assembly pass-throughs that payload. Nested fields reuse contract.* types directly so authoring cannot drift from the registry model.

Description declare vs delivery (not dual authority, not "declare = wire"):

  • Construction requires Description (declaration evidence / fail-closed).
  • Catalog delivery: Cobra Long wins when present → provenance cobra_help; without Long, declared Description is delivered → contract_final.
  • Title: declared Title/ContractFinal first, then Cobra Short, then MCP.

The payload stores the declared text; assembly stamps the real winner.

func (ContractDecl) Empty 

func (s ContractDecl) Empty() bool

Empty reports whether no ContractDecl field was authored.

type Ctx 

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

Ctx is the framework-neutral execution context handed to Invoke/Orchestrate. It deliberately knows nothing about MCP or any other backend: it exposes the command, its positional args, and typed flag access that reuses the declared alias → env → default fallback chain, so a consumer reading a flag through Ctx gets exactly the value the required/constraint checks saw.

func (*Ctx) Args 

func (c *Ctx) Args() []string

Args returns the positional arguments.

func (*Ctx) Bool 

func (c *Ctx) Bool(name string) bool

Bool returns a boolean flag's value.

func (*Ctx) Changed 

func (c *Ctx) Changed(name string) bool

Changed reports whether the user explicitly passed the flag.

func (*Ctx) Command 

func (c *Ctx) Command() *cobra.Command

Command returns the running cobra command.

func (*Ctx) DryRun 

func (c *Ctx) DryRun() bool

DryRun reports the effective global --dry-run.

func (*Ctx) Int 

func (c *Ctx) Int(name string) int

Int returns a flag's effective integer value; an unparseable or undeclared value yields 0 (BuildArgs reports the precise parse error for Invoke specs).

func (*Ctx) Str 

func (c *Ctx) Str(name string) string

Str returns a flag's effective string value (explicit → alias → env → default). An undeclared name yields "".

func (*Ctx) StrSlice 

func (c *Ctx) StrSlice(name string) []string

StrSlice returns a list flag's effective elements (trimmed, empties dropped).

func (*Ctx) Wait added in v1.0.63 

func (c *Ctx) Wait() bool

Wait reports the effective --wait flag. It is false on commands that did not declare the capability: the flag is not registered there, so passing it is an unknown-flag error rather than a silently ignored value.

func (*Ctx) WaitTimeoutSecs added in v1.0.63 

func (c *Ctx) WaitTimeoutSecs() int

WaitTimeoutSecs reports the effective --wait-timeout in seconds (flag value, then the declared default, then the framework default).

func (*Ctx) Yes 

func (c *Ctx) Yes() bool

Yes reports the effective global --yes.

type FlagKind 

type FlagKind int

FlagKind is the value type of a flag. 

const (
	// KindString is a string flag (default).
	KindString FlagKind = iota
	// KindInt is an integer flag (registered as cobra Int); it enters toolArgs
	// only when the value is non-zero, matching the handwritten "putInt only
	// when non-zero" semantics (e.g. devapp app-group-id).
	KindInt
	// KindBool is a boolean flag (registered as cobra Bool); it enters toolArgs
	// only when the user explicitly provided it (Changed), matching the
	// handwritten "transmit on Changed, explicit false is still sent" semantics.
	// Booleans do not participate in the alias/env fallback chain.
	KindBool
	// KindStringSlice is a string-list flag (registered as cobra StringSlice);
	// it enters toolArgs only when a non-empty element exists, elements are
	// always TrimSpace'd and empties dropped.
	KindStringSlice
)

type FlagSpec 

type FlagSpec struct {
	Name      string   // flag name (kebab-case)
	Shorthand string   // optional one-character Cobra shorthand
	Usage     string   // registration usage text
	Kind      FlagKind // value type, defaults to KindString
	Default   string   // registration default for every Kind; also the fallback-chain tail when aliases/env are empty
	Hidden    bool     // hide the real flag from help/Schema while keeping it invocable

	// Required, when true, validates a non-empty effective value in RunE. Plain
	// Required flags aggregate into a cmdutil.ValidateRequiredFlags-compatible
	// error; when EnvVar is configured the env var is a fallback and, still
	// empty, RequiredHint (or a default hint) is reported.
	Required       bool
	ValidationMode FlagValidationMode
	RequiredError  string // exact missing-token error for ValidationShortcut
	RequiredHint   string
	// MarkRequired, when true, calls cobra MarkFlagRequired (the hard floor for
	// the catalog required projection); cobra errors before RunE. It cannot be
	// combined with Aliases (RegisterFlags panics on that declaration).
	MarkRequired bool

	Aliases []string // hidden aliases, registered with the main flag's Kind; used in order when the main flag is not explicitly provided
	EnvVar  string   // environment variable consulted when the effective value is empty (an integer flag's env value must be parseable)
	// ArgDefault covers the case where the registration default is empty but
	// toolArgs still needs a fallback. For KindString it is used when the
	// effective value is empty. For KindInt it is also the floor: when the
	// resolved integer is < 1, ArgDefault is emitted instead (cursor page-size
	// semantics).
	ArgDefault string
	// Bind is the toolArgs key; empty uses Name.
	Bind string
	// Transform converts a string effective value into the arg value; nil sends
	// it as-is. Returning (nil, nil) skips the key (for "nullable numeric: skip
	// on empty or parse failure" semantics).
	Transform func(raw string) (any, error)
	// OmitEmpty, when true, drops an empty effective value from toolArgs (KindInt
	// is always "non-zero only" and ignores this field).
	OmitEmpty bool
	// Trim, when true, TrimSpace's the effective value (main flag/alias/env
	// alike) and makes a whitespace-only value count as empty in required checks.
	Trim bool

	// Input declares extra input sources for a KindString flag beyond the
	// literal command-line value: InputFile enables @path (value replaced by
	// the file content), InputStdin enables - (value replaced by stdin).
	// "@@value" always escapes to the literal "@value". Only explicit CLI
	// tokens are resolved; EnvVar fallback and registration defaults pass
	// through unchanged. Resolution runs before required/enum/constraint/
	// Validate checks, so they see the payload content. Empty = flag value only.
	Input []string

	// Schema parameter final facts (embedded to dws.schema.*; assembly pass-through).
	Enum              []string // accepted values
	Format            string   // machine-readable format (e.g. uri)
	Example           string   // representative CLI value
	RequiredWhen      string   // conditional required expression (descriptive)
	SchemaDescription string   // Schema description; empty uses Usage
}

FlagSpec declares how a flag is registered and bound into MCP toolArgs. Its fields intentionally mirror the former helpers.LeafFlag one-for-one so that helpers can alias to it without touching any call site.

type FlagValidationMode 

type FlagValidationMode string

FlagValidationMode selects runtime validation semantics for a flag.

The zero value keeps LeafSpec's fallback-aware effective-value semantics. ValidationShortcut preserves Shortcut's declaration-order checks: Required means the user must explicitly provide the flag token (even with a default), followed immediately by that flag's Enum validation. 

const ValidationShortcut FlagValidationMode = "shortcut"

ValidationShortcut is the declaration-order explicit-token mode described on FlagValidationMode.

type GroupMode added in v1.0.60 

type GroupMode string

GroupMode declares whether a command with children is navigation-only or also owns business execution. The zero value means the command is a leaf. 

const (
	// GroupNavigationOnly is a parent whose own invocation only renders help.
	GroupNavigationOnly GroupMode = "navigation_only"
	// GroupHybrid is a runnable business command that also owns children.
	GroupHybrid GroupMode = "hybrid"
)

type GroupPolicy added in v1.0.60 

type GroupPolicy struct {
	Mode        GroupMode
	Positionals PositionalsPolicy
	Recovery    RecoveryPolicy
}

GroupPolicy is the typed declaration for every non-leaf command.

Its zero value deliberately means "leaf": callers must declare all three fields together for a group. ApplyGroupPolicy compiles the declaration to Cobra behavior and private framework metadata; command authors must not author parallel kind annotations themselves.

func GroupPolicyFor added in v1.0.60 

func GroupPolicyFor(cmd *cobra.Command) (GroupPolicy, bool, error)

GroupPolicyFor reads the typed declaration compiled onto cmd. The boolean is false only for a leaf. Malformed private metadata is returned as an error so tree assembly can fail closed instead of silently treating a group as a leaf.

func (GroupPolicy) IsZero added in v1.0.60 

func (p GroupPolicy) IsZero() bool

IsZero reports whether p is the leaf declaration.

type ParameterProjectionMode 

type ParameterProjectionMode string

ParameterProjectionMode selects how declared flags are embedded into Runtime Schema annotations. The zero value makes the declaration the final parameter authority (the LeafSpec/command default). 

const (
	// ProjectCobraParameters preserves Cobra usage/type/default provenance and
	// annotates only facts Cobra cannot express: Required and Enum. Shortcut
	// uses this mode to converge its runtime without rewriting Catalog facts.
	ProjectCobraParameters ParameterProjectionMode = "cobra"
)

type PositionalsPolicy added in v1.0.60 

type PositionalsPolicy string

PositionalsPolicy declares whether a group may consume positional values. 

const (
	// PositionalsReject makes every unmatched positional token eligible for
	// command-resolution recovery rather than business execution.
	PositionalsReject PositionalsPolicy = "reject"
	// PositionalsAllow reserves positional values for the group's business
	// execution. Recovery must therefore be disabled to avoid ambiguity.
	PositionalsAllow PositionalsPolicy = "allow"
)

type RecoveryPolicy added in v1.0.60 

type RecoveryPolicy string

RecoveryPolicy declares the search scope for unknown-command recovery. 

const (
	// RecoverySibling suggests only direct children of the current group.
	RecoverySibling RecoveryPolicy = "sibling"
	// RecoveryDeep may search all descendants of the current group.
	RecoveryDeep RecoveryPolicy = "deep"
	// RecoveryDisabled leaves positional handling entirely to Cobra or the
	// command's business execution.
	RecoveryDisabled RecoveryPolicy = "disabled"
)

type Spec 

type Spec struct {
	Use           string
	Short         string
	Long          string
	Example       string
	Hidden        bool
	OutputRollout output.RolloutState

	Flags       []FlagSpec
	Constraints []Constraint
	// ParameterProjection controls whether parameter facts are final
	// declaration annotations or Cobra-backed compatibility facts.
	ParameterProjection ParameterProjectionMode
	// Safety is the command's single safety source. The same contract.SafetySpec
	// is used for runtime confirmation and the published Schema. A completely
	// empty value keeps the historical read-only default; a non-empty value
	// must declare effect/risk/confirmation/idempotency together.
	Safety contract.SafetySpec
	// ConfirmFirst runs the Safety confirmation before required/constraint/
	// Validate checks instead of after them. Use it where the legacy semantics
	// were guard-first (a write without --yes fails fast with
	// confirmation_required regardless of parameter completeness). The default
	// preserves the shortcut order (checks first, confirmation just before the
	// backend call).
	ConfirmFirst bool
	// ConstParams are fixed toolArgs merged after flag assembly (e.g. precheckOnly).
	// They are payload declaration, not user flags, never satisfy Required, and
	// require an Invoke or ResultInvoke dispatcher that consumes assembled args.
	ConstParams map[string]any
	// Contract is the authoring-time leaf contract declaration (selection /
	// interface / parameters / dry-run / identity). When non-empty, embed
	// converts it once to ContractFinal for Catalog pass-through.
	Contract ContractDecl

	// Validate is the cross-flag validation hook, run after required/constraint
	// checks and before args assembly; nil skips it. Not a declaration surface.
	Validate func(cmd *cobra.Command, args []string) error
	// PostMount adjusts the built command after flag registration and before
	// RunE is set (Args/DisableAutoGenTag/annotate/…); always runs. Business
	// flags belong in Flags, not here.
	PostMount func(cmd *cobra.Command)
	// RunE fully replaces the generated body (escape hatch).
	RunE func(cmd *cobra.Command, args []string) error
	// Invoke executes a single-step command with the assembled toolArgs.
	Invoke func(c *Ctx, toolArgs map[string]any) error
	// ResultInvoke executes once and returns an immutable framework 2.0 result.
	ResultInvoke func(c *Ctx, toolArgs map[string]any) (output.CommandResult, error)
	// Orchestrate executes a multi-step command; it assembles whatever payloads
	// it needs from the Ctx.
	Orchestrate func(c *Ctx) error
	// WaitPoll executes one poll of the declared Contract.Wait capability.
	// Exactly one poll is one call; cadence, status extraction, and outcome
	// mapping belong to the framework wait phase. Required for poll/auto
	// declarations — a declared capability without a runtime implementation
	// can never honor --wait, so New rejects the pairing at construction.
	// ctx is the wait-phase deadline (--wait-timeout); leaf I/O must honor
	// it so a blocked poll cannot outlive the declared timeout.
	WaitPoll func(ctx context.Context, c *Ctx) (wait.PollDoc, error)
	// WaitEvents opens the push subscription of the declared Contract.Wait
	// capability (event/auto modes). The framework owns correlation and
	// status mapping; the leaf owns the transport. Auto mode falls back to
	// WaitPoll when the stream ends before a terminal status. ctx is the
	// same wait-phase deadline as WaitPoll; subscription setup must honor
	// it so --wait-timeout can cancel a blocked subscribe.
	WaitEvents func(ctx context.Context, c *Ctx) (wait.EventStream, error)
}

Spec is the single typed definition of a leaf command, shared by the LeafSpec and (via FromShortcut) Shortcut frameworks.

Declaration surface is the final Schema data source for managed leaves: 

Flags (+ parameter Schema fields), Constraints, Safety, ConstParams,
Use/Short/Long/Example, Contract (ToolSpec groups)

Schema assembly pass-throughs embedded dws.schema.* — no reviewed/hints parallel authority for declared fields. Safety uses contract.SafetySpec directly: confirmation drives the runtime gate, while effect/risk/idempotency are published unchanged. No safety field is inferred from another.

Execution surface (hooks — not declaration):

  • RunE — full escape hatch: the framework only registers flags/constraints/ help and hands control over.
  • Invoke — #830 transitional single-step dispatch: runs after required/ constraint/Validate checks, args assembly and the Safety confirmation gate, receiving the assembled toolArgs. Target: mcpbind Bind.
  • Orchestrate — #830 transitional multi-step dispatch: same checks and confirmation, receives only the Ctx. Target: Handler / orchestration.
  • Validate / PostMount — orchestration only; must not register business flags or assemble business params that belong in Flags/ConstParams.

Exactly one of RunE / Invoke / ResultInvoke / Orchestrate must be set; New validates this at construction time. Non-leaf commands are declared separately through ApplyGroupPolicy so leaf execution fields can never be configured and then silently ignored. corecmd stays dispatch-agnostic and never calls a backend: the adapters (FromLeafSpec / FromShortcut) supply the body.

Source Files

View all Source files

Directories

Path Synopsis
Package commandstore ties framework metadata to the lifetime of a live Cobra command without keeping discarded command trees alive.
 Package commandstore ties framework metadata to the lifetime of a live Cobra command without keeping discarded command trees alive.
Package contract owns command-framework declaration DTOs and the ProductDecl registry.
 Package contract owns command-framework declaration DTOs and the ProductDecl registry.
Package contractfinal owns the Cobra-keyed ContractFinal runtime store and the annotate+store registration seam.
 Package contractfinal owns the Cobra-keyed ContractFinal runtime store and the annotate+store registration seam.
Package runtimeannotate owns Cobra dws.schema.* annotation writers and the RuntimeSchemaConstraints helpers used by the command framework.
 Package runtimeannotate owns Cobra dws.schema.* annotation writers and the RuntimeSchemaConstraints helpers used by the command framework.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.