cmdmeta

Documentation

Overview

Package cmdmeta is the single source of truth for command metadata that the policy engine and the hook selector both consume. It wraps the existing cmdutil annotations (risk_level, supportedIdentities) and adds the "domain" axis that the hook selector and Rule path globs need.

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 Apply(cmd *cobra.Command, m Meta)
• func Domain(cmd *cobra.Command) string
• func Identities(cmd *cobra.Command) []string
• func Risk(cmd *cobra.Command) (level string, ok bool)
• func SetDomain(cmd *cobra.Command, domain string)
• type Meta
  • func Get(cmd *cobra.Command) Meta

Functions

func Apply

func Apply(cmd *cobra.Command, m Meta)

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

func Domain(cmd *cobra.Command) string

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 Identities

func Identities(cmd *cobra.Command) []string

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

func Risk(cmd *cobra.Command) (level string, ok bool)

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 SetDomain

func SetDomain(cmd *cobra.Command, domain string)

SetDomain stores the domain annotation on a single command (no inheritance is performed on write).

Types

type Meta

type Meta struct {
	Domain     string
	Risk       string
	Identities []string
}

Meta groups the three command-level metadata axes consumed by the policy engine and hook selectors.

func Get

func Get(cmd *cobra.Command) Meta

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"]).