Documentation
¶
Overview ¶
Package cmdmeta is the single source of truth for command metadata that the policy engine, the hook selector, and help rendering consume. It wraps the existing cmdutil annotations (risk_level, supportedIdentities) and adds the "domain" axis that the hook selector and Rule path globs need, plus the affordance ref (service, method id) that lets service-method and shortcut help share one usage-guidance lookup path.
Three axes:
- Domain - business domain ("im", "docs", "contact", ...). Inherited from the nearest ancestor when not set on the command itself. Stored on a new annotation key (the cmdutil risk_level / supportedIdentities keys are left untouched for backward compatibility).
- Risk - "read" | "write" | "high-risk-write". Inherited like Domain. Reuses cmdutil.SetRisk / GetRisk under the hood.
- Identities - allowed identity set. Child explicit override semantics: the first ancestor (including self) with a non-nil set wins. Reuses cmdutil.SetSupportedIdentities / GetSupportedIdentities.
Missing values are returned as the zero value with ok=false (where the signature exposes it). Interpretation is up to the consumer: the policy engine treats a missing risk as fail-closed when a Rule is registered without AllowUnannotated=true, and as allow otherwise. Identities still defaults to ALLOW. Do not synthesise defaults here -- let each consumer decide.
Index ¶
- func AffordanceRef(cmd *cobra.Command) (service, method string, ok bool)
- func Apply(cmd *cobra.Command, m Meta)
- func Domain(cmd *cobra.Command) string
- func Generated(cmd *cobra.Command) bool
- func Identities(cmd *cobra.Command) []string
- func Risk(cmd *cobra.Command) (level string, ok bool)
- func SetAffordanceRef(cmd *cobra.Command, service, method string)
- func SetDomain(cmd *cobra.Command, domain string)
- func SetSource(cmd *cobra.Command, source Source, generated bool)
- type Meta
- type Source
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AffordanceRef ¶ added in v1.0.67
AffordanceRef returns the command's own affordance overlay coordinates. ok is false when the command carries no ref.
func Apply ¶
Apply writes metadata onto a cobra command. Empty fields are skipped: pass the value via the underlying cmdutil setter if you need to write an empty string / empty slice explicitly.
func Domain ¶
Domain returns the nearest-ancestor domain for the command. Empty string when no ancestor has the annotation -- this is the "unknown" state the policy engine must treat as ALLOW.
func Generated ¶ added in v1.0.56
Generated returns the nearest generated annotation. An explicit false on a child command stops inheritance from a generated parent.
func Identities ¶
Identities returns the first non-nil identity set found while walking up the parent chain. nil signals "unknown" -- the policy engine treats this as ALLOW.
cmdutil.GetSupportedIdentities returns nil when the annotation is absent or empty; an explicit non-empty set (even ["user"] alone) stops the walk.
func Risk ¶
Risk returns the nearest-ancestor risk level (via cmdutil.GetRisk). ok=false signals "unknown" -- the policy engine treats this as fail-closed (deny with risk_not_annotated) whenever a Rule without AllowUnannotated=true is active, and as allow otherwise.
func SetAffordanceRef ¶ added in v1.0.67
SetAffordanceRef records which affordance overlay entry (service, method id) a command maps to, so help rendering can look up its usage guidance. Stored on the command itself (no inheritance): each method / shortcut owns its ref. A no-op if either coordinate is empty.
Types ¶
type Meta ¶
Meta groups the three command-level metadata axes consumed by the policy engine and hook selectors.
func Get ¶
Get resolves the effective metadata for a command, walking up the parent chain for Domain, Risk, and Identities. All three axes use the same nearest-ancestor-wins rule.
Identities note: cmdutil.GetSupportedIdentities collapses both the "annotation absent" and "annotation set to empty string" cases to nil. A child cannot therefore express "deny inheritance" with an empty annotation; the walk simply continues up the parent chain when nil is returned. To override a parent, the child must set a non-empty slice (e.g. ["bot"]).
Source Files