shortcut

type Availability string

type Constraint struct {
	Kind        ConstraintKind `json:"kind"`
	Flags       []string       `json:"flags"`
	Description string         `json:"description,omitempty"`
	// PresenceOnly permits explicit empty values in partial-update constraints.
	PresenceOnly bool `json:"presence_only,omitempty"`
}

type ConstraintKind string

type Flag struct {
	// Name is the long flag name (kebab-case), e.g. "user-ids".
	Name string `json:"name"`
	// Shorthand is the optional one-character CLI spelling, e.g. "o" for --output.
	Shorthand string `json:"shorthand,omitempty"`
	// Type is the value type; defaults to FlagString when empty.
	Type FlagType `json:"type"`
	// Default is the default value rendered as a string.
	Default string `json:"default"`
	// Desc is the help text shown in --help.
	Desc string `json:"description"`
	// Required, when true, makes the framework error if the flag is not set.
	Required bool `json:"required"`
	// RequiredWhen publishes a conditional-required rule that Required cannot
	// express, e.g. "identity=bot" for a credential only mandatory under one
	// identity. It is published Schema metadata so an Agent can predict the
	// failure; enforcement stays in Validate, which remains authoritative.
	RequiredWhen string `json:"required_when,omitempty"`
	// Enum, when non-empty, restricts the accepted values (string flags only).
	Enum []string `json:"enum"`
	// Hidden hides the flag from --help while keeping it usable.
	Hidden bool `json:"-"`
	// Aliases are hidden executable flag spellings for compatibility. They do
	// not create additional Schema parameters; validation and value fallback
	// remain attached to the canonical Name. AliasesVisible is a narrow
	// compatibility escape hatch for aliases that were historically public.
	Aliases        []string `json:"-"`
	AliasesVisible bool     `json:"-"`
	// Input declares extra input sources for a string flag beyond the literal
	// command-line value: "file" enables @path (value replaced by the file
	// content), "stdin" enables - (value replaced by stdin). "@@value" escapes
	// to the literal "@value". Resolution happens before Required/Enum/Validate
	// checks. Empty = flag value only.
	Input []string `json:"input,omitempty"`
}

type FlagType string

type HelpTier string

type Risk string

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

type SemanticDisposition string

type Shortcut struct {
	// OutputRollout selects the single active output contract for this exact
	// command in the current release. It is internal release metadata, never a
	// user/Agent flag.
	OutputRollout output.RolloutState
	// Service is the top-level command group, e.g. "contact". Multiple
	// shortcuts sharing a Service are mounted under the same parent command.
	Service string
	// Command is the leaf name including its "+" prefix, e.g. "+search-user".
	Command string
	// Aliases are hidden, compatibility-only Cobra spellings for the same
	// command identity. Agent-facing Skill and Schema examples must continue to
	// use Command; reviewed Schema aliases are declared separately in the
	// CommandRegistry.
	Aliases []string
	// SinglePositionalAliasFor optionally treats one positional argument as the
	// value of the named string flag. It is intended only for unambiguous search
	// compatibility such as `+chat-search "群名"`; it never changes the
	// canonical flag-based contract published to Agents.
	SinglePositionalAliasFor string
	// Product is the canonical MCP product id used to build the invocation.
	// Defaults to Service when empty.
	Product string
	// Description is the one-line help shown in --help.
	Description string
	// Intent is a fuller natural-language description of what the command does
	// and WHEN to reach for it. Unlike the terse Description, it is written for
	// human discovery and AI-agent intent matching (e.g. "当你只知道某人姓名、需要
	// 拿到其 userId 以便后续发消息或指派任务时使用"). Surfaced in `--help` (as the
	// long description) and in `dws shortcut list`.
	Intent string
	// Risk classifies the side effect; defaults to RiskRead when empty.
	// Kept as the runtime confirmation source when Safety is empty.
	Risk Risk
	// Safety is an optional explicit Schema/runtime safety declaration. When
	// non-empty it overrides Risk expansion in FromShortcut; otherwise Risk
	// still drives ConfirmSafety so existing Execute bodies stay unchanged.
	Safety contract.SafetySpec
	// Contract is the final Agent Contract overlay (selection/interface/dry-run).
	// Empty fails Catalog assembly; every Shortcut must declare Contract.
	Contract corecmd.ContractDecl
	// Flags are the command-specific flags. Global flags are injected separately.
	Flags []Flag
	// Constraints publish and enforce relationships that individual flags cannot
	// express, such as "exactly one of --group and --user". Custom constraints
	// describe checks implemented by Validate.
	Constraints []Constraint
	// Tips are optional usage examples appended to --help.
	Tips []string
	// Hidden hides the command from listings while keeping it invocable.
	Hidden bool
	// CompatibilityVisible preserves a historically visible CLI command while
	// keeping it out of the Agent/public Shortcut catalog. Such a command is
	// shown only by `dws shortcut list --all`; Availability independently says
	// whether the historical execution path remains callable.
	CompatibilityVisible bool
	// Disposition is the reviewed semantic relation to the Runtime Schema leaf
	// surface. It determines default Agent discovery independently from live
	// fixture evidence.
	Disposition SemanticDisposition
	// SemanticDelta explains the concrete value added beyond renaming a leaf.
	SemanticDelta string
	// HelpTier controls whether this public Shortcut is featured on the product
	// root help or remains discoverable through Schema/shortcut list/exact help.
	// Compatibility and unavailable tiers are never shown on the product root.
	HelpTier HelpTier
	// Availability describes whether the implementation is shipped and
	// callable; it does not encode the current account's permissions.
	Availability Availability
	// PrimaryCommand links aliases/internal compatibility entries to their
	// preferred semantic entry.
	PrimaryCommand string
	// SemanticReviewed is true only when the disposition and visibility came
	// from the reviewed semantic catalog.
	SemanticReviewed bool
	// UserDefined identifies shortcuts loaded from the user's config
	// directory. Distribution-owned Schema and interface snapshots exclude
	// these runtime extensions even if another root loaded them earlier.
	UserDefined bool

	// Validate optionally checks resolved flag values before execution. Return a
	// non-nil error to abort with a validation message. Runs after built-in
	// Required/Enum checks.
	Validate func(rt *RuntimeContext) error
	// Execute performs the shortcut. It is required. Typically it builds a
	// params map from rt's flags, calls rt.CallMCP, and rt.Output's the result.
	Execute func(rt *RuntimeContext) error
}