opcore

type ArgBinder struct {
	PathVals []string

	Query   neturl.Values
	BodyObj map[string]any
	// contains filtered or unexported fields
}

type Args struct {
	Path        map[string]string
	Query       map[string]string
	QueryValues map[string]any
	Body        map[string]any
}

type BodyMapping struct {
	SourcePath []string
	Target     string
	// Type is the JSON type the leaf projects, defaulting to string. A mapped
	// leaf used to be string-only in every configuration. See umbra#312.
	Type string
	// Items is the element type when Type is "array".
	Items string
}

type Database struct {
	Driver string
	DSN    guardfile.ValueChain
}

type Descriptor struct {
	VerbName       string         // dotted audit name, e.g. ward.ops.forgejo.repo.create
	Group          string         // CLI group noun, e.g. repo
	Leaf           string         // CLI leaf verb, e.g. create
	Method         string         // HTTP method
	Path           string         // path template, e.g. /repos/{owner}/{repo}
	PathParams     []string       // ordered positional args drawn from the path
	BodyFlags      []Field        // request-body fields, including nested object/array shapes
	BodyMappings   []BodyMapping  // required input paths projected onto fresh top-level body keys
	QueryFlags     []Field        // query params, including typed scalar-array shapes
	QueryExclusive [][]string     // local query-name groups where at most one may be supplied
	FormFlags      []Field        // formData params, where "file" types take a path
	FixedBody      map[string]any // pinned body keys, alone for a state toggle or seeding a mapped body
	// ReturnFields is the optional `returns` declaration a successful response
	// is pruned to before Execute hands it back. See docs/opcore-returns.md.
	ReturnFields []Field
	Destructive  bool     // leaf mutates irreversibly (delete)
	Grant        string   // the authorizing grant sentence, e.g. "can delete repos"
	Describe     string   // optional Guardfile describe "..." note, "" if none
	FailWhen     string   // optional JMESPath response postcondition; truthy rejects a successful call
	Proxy        *Proxy   // non-nil for an inline MCP proxy grant
	GraphQL      *GraphQL // non-nil for a `graphql` grant; owns the whole body
	SQL          *SQL     // non-nil for a `sql` grant; reaches a database, not a URL
	MCP          *MCPCall // non-nil for an `mcp` dialect leaf; reaches a session, not a URL
	// Meta is upstream `_meta`, kept verbatim and never interpreted. A served
	// surface forwards it; MCP Apps addresses its widget there.
	Meta map[string]any
	// RawResponse marks a success response offering no JSON, written through
	// untouched. See docs/specverb-request.md.
	RawResponse bool
	// MethodInferred marks a Method guessed from an unrecognised verb rather
	// than looked up or stated. See docs/opcore-inline.md.
	MethodInferred bool
}

type Field struct {
	Name         string // local input name and the default outgoing field or parameter name
	UpstreamName string // outgoing query parameter name when it differs from Name
	Type         string // swagger type: string|boolean|integer|number|array|object
	Items        string // scalar element type when Type is "array" and Item is nil
	Item         *Field // nested element schema when Type is "array" and Item is object/array
	Fields       []Field
	Raw          bool
	Required     bool // required in the schema, enforced at request assembly
	Desc         string
	Enum         []any    // permitted values, when the upstream schema names a closed set
	Minimum      *float64 // inclusive numeric lower bound
	Maximum      *float64 // inclusive numeric upper bound
	MinItems     *int     // inclusive array-length lower bound
	MaxItems     *int     // inclusive array-length upper bound
	// ArrayEncode is "" or "repeat" for the bare repeated name, "brackets" for
	// the []-suffixed form. docs/specverb-request.md (umbra#7013).
	ArrayEncode string
	// Keyed marks an object whose key set is the caller's, not a fixed
	// named list. See docs/opcore-body-variants.md.
	Keyed       bool
	EntrySchema *Field
	// Variant is a discriminated union: exactly one Cases entry applies. See
	// docs/opcore-body-variants.md.
	Variant *Variant
}

type GraphQL struct {
	Document  string  // the operation document, sent verbatim as `query`
	Operation string  // operation name, sent as `operationName`; "" when anonymous
	Variables []Field // derived from the document signature, decorated by `variable`
}

type InlineOptions struct {
	// AllowReservedNames lets an input take a name the umbra CLI reserves for its flags.
	// A consumer mounting no CLI sets it. Duplicate inputs stay refused.
	AllowReservedNames bool
}

type MCPCall struct {
	Tool string

	// Allow and Deny guard the outgoing arguments, PostCall the returned value.
	// All three match a regex against one named string field.
	Allow    []ProxyRule
	Deny     []ProxyRule
	PostCall []ProxyRule
}

type MCPEnv struct {
	Name  string
	Value guardfile.ValueChain
}

type MCPUpstream struct {
	Kind string // "stdio" | "http"

	Command string
	Argv    []string
	Env     []MCPEnv

	URL      string
	URLValue guardfile.ValueChain
	Auth     guardfile.Auth
}

type Operation struct {
	Desc Descriptor
	RT   *Runtime
}

type Property struct {
	Type         string // string|boolean|integer|number|array
	Items        string // element type when Type==array
	Item         *Property
	Properties   map[string]Property
	Required     []string
	Raw          bool
	Location     string // path|query|body|form (neutral hint)
	UpstreamName string // outgoing query parameter when it differs from the local property name
	Description  string
	Enum         []any
	Minimum      *float64
	Maximum      *float64
	MinItems     *int
	MaxItems     *int
	// Keyed marks an object whose key set is the caller's, every value shaped
	// like Entry. umbra#8032.
	Keyed   bool
	Entry   *Property
	Variant *PropertyVariant
}

type PropertyVariant struct {
	On    string
	Cases map[string]Property
}

type Provider = valuesource.Provider

type Proxy struct {
	Name     string       // local served tool name
	Upstream UpstreamTool // exact upstream MCP tool mapping
	Allow    []ProxyRule  // request-time allow rules
	Deny     []ProxyRule  // request-time deny rules
	PostCall []ProxyRule  // response-time checks after the upstream call
	Describe string       // optional human note
}

type ProxyRule struct {
	Field    string
	Patterns []string
}

type Request struct {
	Method      string
	URL         string
	Body        []byte
	ContentType string
}

type Response struct {
	Decoded any
	Raw     []byte
	Status  string
}

type Runtime struct {
	BaseURL   string
	Auth      guardfile.Auth
	Providers map[string]Provider
	Client    *http.Client
	Restrict  []guardfile.Restriction

	// AllowMeta names the path params the wrap's `allow-metacharacters` exempts.
	// Query is exempt by construction, never by this list; specverb-request.md.
	AllowMeta []string

	// Headers are wrap-declared request headers, applied before the default
	// User-Agent. See docs/specverb-request.md.
	Headers map[string]string

	// BaseURLValue (zero = static BaseURL) resolves the host through the first
	// available source in its chain once, caching it. See specverb-policy.md.
	BaseURLValue guardfile.ValueChain

	// Database backs `sql` grants. The pool opens once on first use, so a
	// consumer that serves no SQL grant never opens a connection.
	Database Database

	// MCP is the wrap-level upstream backing `mcp` dialect leaves. Its value
	// chains stay symbolic here and resolve per call, never at parse.
	MCP MCPUpstream
	// contains filtered or unexported fields
}

type RuntimeConfig struct {
	BaseURL      string
	Auth         guardfile.Auth
	Providers    map[string]Provider
	Client       *http.Client
	Restrict     []guardfile.Restriction
	AllowMeta    []string
	Headers      map[string]string
	BaseURLValue guardfile.ValueChain
	Database     Database
	MCP          MCPUpstream
}

type SQL struct {
	Statement   string  // sent verbatim; parameters bind, nothing interpolates
	Params      []Field // ordered, binding to $1..$N or ?..? in that order
	MaxRows     int     // result bound for a reading statement
	Reads       bool    // true when the statement returns rows rather than a count
	Placeholder byte    // '$' or '?', the style the statement uses
}

type Schema struct {
	Properties        map[string]Property // keyed by field name
	Required          []string            // names that must be supplied, in a stable order
	MutuallyExclusive [][]string          // groups where at most one property may be supplied
}

type UpstreamTool struct {
	Server string
	Tool   string
}

type Variant struct {
	On    string
	Cases map[string][]Field
}