execverb

type CaptureRunner func(ctx context.Context, bin string, argv, env []string) (stdout, stderr []byte, exitCode int, err error)

type Config struct {
	// Guardfile is the parsed exec-dialect policy.
	Guardfile *Guardfile

	// Wrap adapts a verb.Spec into a guarded cli.ActionFunc (the audit + argv
	// pipeline). nil mounts the bare action, for doc rendering only.
	Wrap func(verb.Spec) cli.ActionFunc

	// Providers registers the value resolvers a guardfile `env` source names;
	// umbra merges its built-ins (env, file, literal). Resolved at exec time.
	Providers map[string]valuesource.Provider

	// EmbeddedFiles maps each build-time `embed` source to the absolute runtime
	// path materialized by umbra. Missing or relative entries fail closed.
	EmbeddedFiles map[string]string

	// Run fires the command. nil execs for real.
	Run Runner

	// RunCapture fires an action step and captures its output (the streamed Run
	// seam cannot feed step data-flow). nil execs for real. Injected for tests.
	RunCapture CaptureRunner

	// Host resolves `shell <cmd>` selectors for wrap-level guards. nil execs for
	// real (cli/exec). Injected for tests.
	Host HostResolver
}

type DefaultAllow struct {
	Declared bool
	Reason   string
}

type EmbeddedArg struct {
	Index  int
	Source string
}

type EnvVar struct {
	Name     string
	Provider string // value-source provider name (env|file|literal|consumer-registered)
	Address  string // provider-specific address (SSM path, env var name, literal value)
}

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

type FlagPin struct {
	Flag  string
	Value string
}

type GateSpec struct {
	Name     string   // registry key; consumers register their own gates
	Patterns []string // gate-specific deny globs; empty = gate defaults
	Allow    []string // explicit allow globs
	// Options holds every other `<key> "<value>"` child. The gate's builder
	// rejects a key it does not know, so an unknown node still fails closed.
	Options map[string][]string
}

type Grant struct {
	Subcommand []string // e.g. ["admin", "user", "list"]
	Wildcard   bool     // `can run *`: the whole binary passes through
	AllowFlags []string // non-empty -> strict flag allowlist
	DenyFlags  []string // default-allow minus these
	ValueFlags []string // long flags whose value is a separate argv token

	// ResolveFlags are long flags whose caller value umbra resolves through
	// pkg/valuesource and spills to a file. See docs/execverb.md.
	ResolveFlags []string

	// Pins fix a flag's value: umbra supplies it and refuses a caller who
	// passes a different one. See docs/execverb.md.
	Pins     []FlagPin
	Gates    []GateSpec
	Whens    []WhenClause
	Describe string

	// Argv is the per-grant `argv` override: tokens appended after argv-prefix
	// in place of Subcommand. ArgvSet marks an explicit (maybe empty) override.
	Argv    []string
	ArgvSet bool
	// EmbeddedArgs identifies symbolic argv slots compiled into the binary.
	// Runtime mounting resolves each slot to an absolute path before execution.
	EmbeddedArgs []EmbeddedArg

	// Sealed forbids trailing caller args: the pinned `argv` forwards exactly,
	// with no caller-supplied tokens appended. Requires ArgvSet (parse-enforced).
	Sealed bool

	// Bin overrides the wrap binary for this grant only (multi-binary pipelines),
	// still fixed at parse: the caller can never substitute it. See docs/.
	Bin string
	// contains filtered or unexported fields
}

type GrantInfo struct {
	Name       string   `json:"name"`                  // dotted audit name, e.g. <cli>.ops.<tool>.<sub>.<verb>
	Subcommand []string `json:"subcommand,omitempty"`  // e.g. ["s3","ls"]; empty for the wildcard
	Bin        string   `json:"bin,omitempty"`         // the funnel's own binary, set only for an inspect-list (`allow`) leaf
	Exec       []string `json:"exec,omitempty"`        // tokens appended after the binary: the argv override when set, else the subcommand
	Wildcard   bool     `json:"wildcard"`              // `can run *`: the whole binary passes through
	Sealed     bool     `json:"sealed,omitempty"`      // `sealed`: pinned argv forwards exactly, no trailing caller args
	Describe   string   `json:"describe,omitempty"`    // Guardfile describe note
	AllowFlags []string `json:"allow_flags,omitempty"` // non-empty: strict flag allowlist
	DenyFlags  []string `json:"deny_flags,omitempty"`  // default-allow minus these
	Gates      []string `json:"gates,omitempty"`       // registered preflight gate names
	Guards     []string `json:"guards,omitempty"`      // rendered when/deny-when guards
}

type Guardfile struct {
	// Description is the optional top-level `description "..."` prose (sibling of
	// `wrap`): standing context in describe + the ref doc. See docs/value-providers.md.
	Description string

	Group      []string     // command path, e.g. ["<cli>", "git"]
	Bin        string       // the real binary, fixed at parse; bare names stay the default, absolute paths only when intentionally pinned
	ArgvPrefix []string     // unoverridable leading argv (remote-exec transport)
	Env        []EnvVar     // environment vars set on the wrapped process
	Grants     []Grant      // mounted leaves
	Whens      []WhenClause // wrap-level passthrough guards (never pass/only pass), enforced on every leaf - the host gate

	// Allow lists bare binaries that each mount as an independent open-passthrough
	// funnel: inspect-list sugar, mutually exclusive with exec/can run (docs/execverb.md).
	Allow []string

	// WrapWhens are wrap-level when/deny-when guards applied to every `allow`
	// funnel - the read-only floor over the whole inspect list (allow only).
	WrapWhens []WhenClause

	// Replace installs the generated binary under the wrapped tool's own name,
	// ahead of it on PATH. See docs/execverb-replacement.md.
	Replace bool

	// Occlude is the name a replacement is installed under, resolved at parse.
	// Empty unless Replace is set.
	Occlude string

	// Withheld are `withhold` stubs: verbs stated as refused so a caller can
	// tell policy from an unimplemented feature. See docs/execverb.md.
	Withheld []WithheldStub

	// NeverRules are `never run` paths, refused ahead of every grant.
	NeverRules []NeverRule

	// DefaultAllow inverts the default: an unnamed verb is forwarded to the
	// wrapped binary rather than refused. See docs/execverb-default-allow.md.
	DefaultAllow DefaultAllow

	// Actions are declared ordered call sequences over granted exec leaves. See
	// docs/execverb.md.
	Actions []guardfile.Action

	// ProviderDecls are consumer-declared value resolvers shared with the spec
	// dialect: `provider <name> { exec ... }`. See docs/value-providers.md.
	ProviderDecls []guardfile.ProviderDecl
	// contains filtered or unexported fields
}

type HostResolver func(ctx context.Context, cmd []string) (string, error)

type NeverRule struct {
	Subcommand []string
}

type Runner func(ctx context.Context, bin string, argv, env []string) error

type Surface struct {
	Group       []string    `json:"group"`                 // command path, e.g. ["<cli>","ops","<tool>"]
	Description string      `json:"description,omitempty"` // the guardfile's top-level `description` prose, "" when none
	Bin         string      `json:"bin"`                   // the wrapped binary, fixed at parse; empty for an inspect list
	ArgvPrefix  []string    `json:"argv_prefix,omitempty"` // unoverridable leading argv
	Env         []string    `json:"env,omitempty"`         // env injections as "NAME = provider address" (source, never the resolved value)
	Inspect     bool        `json:"inspect,omitempty"`     // the `allow` inspect-list shape: each grant funnels its own binary, no single Bin
	Guards      []string    `json:"guards,omitempty"`      // wrap-level guards (the passthrough host gate), applied to every leaf
	Grants      []GrantInfo `json:"grants"`                // every mounted leaf, in mount order

	// DefaultAllow is the `default-allow` reason, empty when the wrap is closed.
	// Without it a reader reads the grants as the whole surface.
	DefaultAllow string `json:"default_allow,omitempty"`
}

type WhenClause struct {
	// Selector names the argv slot: flag name, `any-arg`, or `argN`. Empty when
	// SourceCmd is set (the value comes from a shell fact, not argv).
	Selector string

	// SourceCmd is the ambient `shell <cmd>` selector source: exec'd once, its
	// trimmed stdout is the value. nil means the value comes from argv (Selector).
	SourceCmd []string

	// Patterns are globs matched case-insensitively against the value(s).
	Patterns []string

	// Deny is true for `deny-when` / `never pass` (refuse on match), false for
	// `when` / `only pass` (refuse on no match).
	Deny bool

	// Describe is the optional teaching note rendered in the describe surface.
	Describe string
}

type WithheldStub struct {
	Subcommand  []string
	Reason      string
	Alternative []string
}