surface

Documentation

Overview

Package surface describes the build-local command surface presented by one Cobra tree. It is deliberately independent from policy enforcement: a denied command may remain visible, or an opt-in distribution may conceal it.

Index

• type CommandID
• type CommandState
• type Plan
  • func NewPlan(states map[CommandID]CommandState) *Plan
  • func (p *Plan) CanReference(id CommandID) bool
  • func (p *Plan) IsConcealed(id CommandID) bool
  • func (p *Plan) State(id CommandID) CommandState

Types

type CommandID

type CommandID string

CommandID is a command's canonical slash-separated path relative to the binary root, for example "auth/login" or "config/strict-mode".

const (
	CommandAuthLogin         CommandID = "auth/login"
	CommandConfig            CommandID = "config"
	CommandConfigInit        CommandID = "config/init"
	CommandConfigBind        CommandID = "config/bind"
	CommandConfigStrictMode  CommandID = "config/strict-mode"
	CommandConfigPolicyShow  CommandID = "config/policy/show"
	CommandConfigPluginsShow CommandID = "config/plugins/show"
	CommandProfile           CommandID = "profile"
	CommandProfileAdd        CommandID = "profile/add"
	CommandProfileList       CommandID = "profile/list"
	CommandSchema            CommandID = "schema"
	CommandUpdate            CommandID = "update"
	CommandSkills            CommandID = "skills"
	CommandSkillsRead        CommandID = "skills/read"
)

Canonical framework command IDs. Centralizing these paths keeps recovery, notices, diagnostics, and flag projection on the same exact-path vocabulary.

type CommandState

type CommandState uint8

CommandState describes how one command is presented by a distribution.

const (
	// CommandAvailable is the default for paths absent from a Plan.
	CommandAvailable CommandState = iota
	// CommandDeniedVisible keeps the command and references to it visible while
	// policy enforcement rejects execution.
	CommandDeniedVisible
	// CommandConcealed presents the command as absent from this distribution.
	CommandConcealed
)

type Plan

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

Plan is an immutable, build-local snapshot of command presentation states.

NewPlan defensively copies its input and Plan exposes no mutator, so a Plan can safely be captured by the renderers belonging to one Cobra tree. The zero value (and a nil *Plan) describes the default, fully visible surface.

func NewPlan

func NewPlan(states map[CommandID]CommandState) *Plan

NewPlan returns an immutable snapshot of states. Paths omitted from states are CommandAvailable.

func (*Plan) CanReference

func (p *Plan) CanReference(id CommandID) bool

CanReference reports whether user-facing output may point at id. Denied-visible commands remain valid recovery targets because following the reference produces the existing, policy-rich denial. Concealed commands do not.

func (*Plan) IsConcealed

func (p *Plan) IsConcealed(id CommandID) bool

IsConcealed reports whether id or any canonical ancestor is concealed. Ancestor concealment dominates an explicit child state: a child cannot be presented through a parent that the distribution presents as absent.

func (*Plan) State

func (p *Plan) State(id CommandID) CommandState

State returns the state explicitly recorded for id. It intentionally does not infer a child state from an ancestor; use IsConcealed or CanReference when effective presentation is required.