Documentation
¶
Overview ¶
Package cmdregistry derives the deterministic command registry document (contract:cli.command-registry v1) from a cobra tree, the declared canon data and the JSON data-type map.
Purpose: one machine-readable description of the CLI command surface. Inputs: a cobra root (read only), *canon.File, a map of registered JSON
data types keyed by command path without "nself ", BuildOptions.
Outputs: *Registry, marshalled with Marshal (2-space indent, no HTML
escaping, trailing newline). Field names and order are a cross-repo contract; a rename after merge is a v2.
Constraints: stdlib + cobra + pflag + internal/canon only. Build never
mutates the tree and does not import compat (the caller passes compat.V15() as BuildOptions.V15).
Index ¶
- Constants
- func ApplyFlagEnv(reg *Registry, flagEnv map[string]map[string]string, moves []PathMove, ...) error
- func EffectiveOutput(cmd *Command, set map[string]bool) string
- func EffectiveSideEffect(cmd *Command, set map[string]bool) string
- func RoutePath(path string) string
- func ToolName(path string) string
- func V14Path(canonical string, moves []PathMove) string
- func ValidateToolNames(reg *Registry) error
- type Arg
- type BuildOptions
- type Command
- type Confirm
- type Counts
- type Flag
- type PathMove
- type PlanForm
- type Registry
- type Root
Constants ¶
const RootBindingPath = "."
RootBindingPath is the FlagEnv key of the root command's own flags.
const SchemaVersion = "1"
SchemaVersion is the registry document version.
Variables ¶
This section is empty.
Functions ¶
func ApplyFlagEnv ¶
func ApplyFlagEnv(reg *Registry, flagEnv map[string]map[string]string, moves []PathMove, v15 bool) error
ApplyFlagEnv sets Flag.env on every flag named in flagEnv. flagEnv is keyed by canonical command path (RootBindingPath for the root) then flag name. In v1.4 mode (v15 false) the paths are translated through moves first. All violations are returned in one error.
func EffectiveOutput ¶
EffectiveOutput selects stream when a set flag declares a stream override.
func EffectiveSideEffect ¶
EffectiveSideEffect is the highest class produced by set flag overrides.
func ValidateToolNames ¶
ValidateToolNames rejects invalid or colliding generated tool identifiers.
Types ¶
type Arg ¶
type Arg struct {
Name string `json:"name"`
Required bool `json:"required"`
Variadic bool `json:"variadic"`
Secret bool `json:"secret"`
}
Arg is one positional argument parsed from the command's Use string.
type BuildOptions ¶
type BuildOptions struct {
// V15 selects ExitCodesV15 and enables V15OnlyEnvelope paths. The caller
// passes compat.V15().
V15 bool
// V15OnlyEnvelope lists paths (without "nself ") whose registered data
// type reports json envelope only when V15 is true (EPIC D8).
V15OnlyEnvelope map[string]bool
}
BuildOptions selects the compat mode and the v1.5-only envelope paths.
type Command ¶
type Command struct {
Path string `json:"path"`
Name string `json:"name"`
Parent string `json:"parent"`
Summary string `json:"summary"`
Hidden bool `json:"hidden"`
Deprecated *string `json:"deprecated"`
Aliases []string `json:"aliases"`
Group *string `json:"group"`
Runnable bool `json:"runnable"`
Args []Arg `json:"args"`
Flags []Flag `json:"flags"`
Canon string `json:"canon"`
Plugin *string `json:"plugin,omitempty"`
Target *string `json:"target"`
SideEffect string `json:"side_effect"`
Output string `json:"output"`
JSON string `json:"json"`
DataSchema *string `json:"data_schema"`
ExitCodes map[string]string `json:"exit_codes"`
Confirm *Confirm `json:"confirm"`
Surface string `json:"surface"`
}
Command is one non-root cobra command.
type Counts ¶
type Counts struct {
Commands int `json:"commands"`
TopLevel int `json:"top_level"`
Core int `json:"core"`
Pending int `json:"pending"`
DeprecatedShims int `json:"deprecated_shims"`
Plugin int `json:"plugin,omitempty"`
CoreMissing []string `json:"core_missing"`
JSONEnvelope int `json:"json_envelope"`
JSONLegacy int `json:"json_legacy"`
}
Counts are the derived totals.
type Flag ¶
type Flag struct {
Name string `json:"name"`
Shorthand *string `json:"shorthand"`
Type string `json:"type"`
Default string `json:"default"`
Usage string `json:"usage"`
Hidden bool `json:"hidden"`
Deprecated *string `json:"deprecated"`
Required bool `json:"required"`
Persistent bool `json:"persistent"`
Env *string `json:"env"`
SideEffect *string `json:"side_effect"`
JSON *string `json:"json"`
Output *string `json:"output"`
CLIOnly bool `json:"cli_only"`
Secret bool `json:"secret"`
}
Flag is one flag declared on a command (or on the root).
type PathMove ¶
type PathMove struct{ From, To string }
PathMove is one canon move row: the v1.4 spelling From became the canonical path To (both without the leading "nself ", words joined by one space).
type Registry ¶
type Registry struct {
SchemaVersion string `json:"schema_version"`
Verbs []string `json:"verbs"`
Root Root `json:"root"`
Commands []Command `json:"commands"`
Counts Counts `json:"counts"`
// contains filtered or unexported fields
}
Registry is the whole document.
func Build ¶
func Build(root *cobra.Command, c *canon.File, dataTypes map[string]any, opts BuildOptions) (*Registry, error)
Build derives the registry from root, the declared canon data c and the registered JSON data types (keys are command paths without the leading "nself "; values are only tested for presence). It never mutates the cobra tree. Every violated rule is collected into one *canon.ValidationError that names each offending path; on error the registry is nil.
func (*Registry) Lookup ¶
Lookup finds a command by its full path ("nself config get"); the path without the root name ("config get") is accepted too.
func (*Registry) Marshal ¶
Marshal renders the registry as the published JSON document: 2-space indent, no HTML escaping, trailing newline.
Source Files