guardfile

type Action struct {
	Name     string
	Describe string
	Inputs   []Input
	Poll     *Poll
	Calls    []Call // ordered multi-call sequence; mutually exclusive with Poll
	Collect  *Collect
	FailWhen string // JMESPath over the bindings; truthy => non-zero exit

	// RejectEmpty refuses an action that answered with nothing. Exec dialect
	// only, refused at build time over http. See docs/execverb-occlusion.md.
	RejectEmpty bool

	// MountVerb/MountResource: the two-arg `action <verb> <resource>` mount form
	// shadows that leaf path. Empty for `action <name>`. See specverb-actions.md.
	MountVerb     string
	MountResource string
}

type ArgBind struct {
	Name  string
	Value string // `$input` reference or a literal
}

type Auth struct {
	Scheme string
	Header string
	Prefix string // trailing space is significant, e.g. "token "
	Value  ValueChain

	// Params are the query-param scheme's ordered secrets, each injected as a
	// query parameter (Trello's ?key=&token=). Empty for the header schemes.
	Params []QueryAuthParam
}

type Call struct {
	Verb     string
	Resource string
	Args     []ArgBind
	As       string // binding name for this call's response
}

type Collect struct {
	Verb         string
	Resource     string
	Args         []ArgBind
	PageParam    string
	LimitParam   string
	Limit        string
	DefaultLimit string
	As           string
	// Cache, when set, is the TTL string (e.g. "10m") serving the accumulated
	// array from the on-disk ttl cache. Collect-only (see docs/specverb-actions.md).
	Cache string
}

type Fetch struct {
	Name     string
	Leaf     string
	Describe string
	Method   string
	Path     string
	Output   string
	Env      []FetchEnv
	Headers  []FetchHeader
	Whens    []FetchWhen
}

type FetchEnv struct {
	Name  string
	Value ValueChain
}

type FetchHeader struct {
	Name  string
	Value string
}

type FetchWhen struct {
	Selector string
	Globs    []string
}

type Grant struct {
	Modal      string
	Verb       string
	Resource   string
	Qualifiers []string

	// Props are KDL key=value node properties: structured scoping constraints
	// like `org=acme`. Positional bareword qualifiers stay in Qualifiers.
	Props map[string]string

	// Op is the spec operationId (grant-body `op "..."`). Optional: an empty Op is
	// resolved by convention (specverb.resolveOp); set it to override. Deny ignores it.
	Op string

	// OpMethod and OpPath address an operation by method+path, for a spec whose
	// operations carry no operationId. See docs/specverb-resolution.md.
	OpMethod string
	OpPath   string

	// FixedBody is the grant-body `body key=value...` map: a state-toggle leaf that
	// always sends this exact JSON and mounts no body flags. Keeps KDL-native types.
	FixedBody map[string]any

	// Message is the grant-body `message "..."` shown when a deny blocks an
	// invocation - the teaching error. Only meaningful on cannot/never.
	Message string

	// Describe is the optional grant-body `describe "..."` note that enriches
	// the thin upstream spec; it flows into help and the describe verb.
	Describe string

	// Wildcard is set when the resource was authored as the `"*"` sentinel: the
	// engine expands it to one concrete grant per spec resource exposing the verb.
	Wildcard bool

	// Override is set for an `override can <verb> <resource>` grant: the sole
	// construct that crosses an inherited `never`. It carries Modal "can".
	Override bool
}

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. ["ward", "ops", "forgejo"]
	Spec    string
	BaseURL string
	// BaseURLValue resolves the base-url at request time (block form
	// `base-url { value ... }`), exclusive with BaseURL. See specverb-policy.md.
	BaseURLValue ValueChain
	Auth         Auth
	Grants       []Grant
	Restrict     []Restriction
	Actions      []Action
	Fetches      []Fetch

	// AllowMeta names the path params opted out of the shell-metacharacter
	// gate by `allow-metacharacters <param>...`. See docs/specverb-request.md.
	AllowMeta []string

	// Providers are consumer-declared value resolvers: `provider <name> { exec ... }`.
	// umbra ships no store SDK, so a store-backed source is an exec contract.
	ProviderDecls []ProviderDecl
}

type Input struct {
	Name       string
	Positional bool   // true: a positional arg; false: a --flag
	Required   bool   // enforced at invocation
	Help       string // one-line help, "" if none
	// Default is a JMESPath pre-flight binding for an absent input (poll actions
	// only); mutually exclusive with Required. See specverb-actions.md.
	Default string
	// Array makes the input repeatable, projected as a JSON array coerced to the
	// element type the bound leaf field declares. Flags only. See specverb-actions.md.
	Array bool
	// Matches constrains the bound value: on an `array` each entry demands at
	// least one matching element. See specverb-actions.md.
	Matches []InputMatch
}

type InputMatch struct {
	Globs   []string
	Message string
}

type Poll struct {
	Verb     string
	Resource string
	Args     []ArgBind
	Until    string // JMESPath; truthy ends the loop
	Every    string // sample interval, e.g. "10s" (quoted: KDL rejects bare 10s)
	Timeout  string // wall-clock bound, e.g. "30m"
	As       string // binding name for the final response
}

type ProviderDecl struct {
	Name string
	Exec []string
}

type QueryAuthParam struct {
	Name  string
	Value ValueChain
}

type Restriction struct {
	Param string
	Globs []string
}

type ValueChain []ValueSource

type ValueSource struct {
	Provider string
	Address  string
}