contract

type Command struct {
	// Name is the `command` field the document carries: the cobra path without
	// the root ("finding", "scan status").
	Name string
	// Kind is the document's `kind` (KindRead, KindMutation, KindScan); empty
	// when the document carries none.
	Kind string
	// Description is a one-line summary, rendered as the schema's description.
	Description string
	// Item is a zero value of one item's Go type. Nil leaves items untyped.
	Item any
	// ItemsKind is ItemsList (the default) or ItemsObject.
	ItemsKind string
	// Variants are alternative item shapes a flag selects (traffic --curl).
	// The items schema is then anyOf the default and every variant.
	Variants []Variant
	// Extras is a zero value of a struct whose JSON fields are the command's
	// own top-level keys. omitempty fields are optional, the rest required.
	// They override a common envelope extra of the same name.
	Extras any
}

type Document struct {
	Name        string
	Description string
	Value       any
}

type Envelope struct {
	SchemaVersion int    `json:"schema_version"`
	Command       string `json:"command"`
	// Kind is the document's shape: read, mutation or scan.
	Kind string `json:"kind,omitempty"`
	// OK is true on every result document; the error envelope carries false.
	OK bool `json:"ok"`
	// Changed, Action and DryRun are the mutation spine (kind "mutation").
	Changed *bool  `json:"changed,omitempty"`
	Action  string `json:"action,omitempty"`
	DryRun  bool   `json:"dry_run,omitempty"`
	// ProjectUUID is the project filter actually applied; DBPath the store the
	// command opened.
	ProjectUUID string `json:"project_uuid,omitempty"`
	DBPath      string `json:"db_path,omitempty"`
	// Total counts the whole result set; Offset/Limit describe this page.
	Total  int64 `json:"total"`
	Offset int   `json:"offset"`
	Limit  int   `json:"limit"`
	// Items is always an array, never null and never an object.
	Items []any `json:"items"`
	// Query / QueryArgv are the ready-to-run follow-up command.
	Query     string   `json:"query,omitempty"`
	QueryArgv []string `json:"query_argv,omitempty"`
	// GeneratedAt is RFC3339 UTC with exactly three fractional digits;
	// GeneratedAtMS the same instant in epoch milliseconds.
	GeneratedAt   string `json:"generated_at,omitempty"`
	GeneratedAtMS int64  `json:"generated_at_ms,omitempty"`
}

type EnvelopeCommon struct {
	// ProjectSource says where the project selection came from.
	ProjectSource string `json:"project_source" jsonschema:"enum=flag,enum=env,enum=active_file,enum=default"`
	// ProjectScoped states whether a project filter was applied at all.
	ProjectScoped *bool `json:"project_scoped,omitempty"`
	// Warnings are advisories about how the result was produced.
	Warnings []string `json:"warnings,omitempty"`
	// GlobSources reports a --glob-db merge: matched vs loaded files.
	GlobSources *GlobSources `json:"glob_sources,omitempty"`
	// OutputBudget reports a page cut by --max-output-bytes.
	OutputBudget *OutputBudget `json:"output_budget,omitempty"`
}

type ErrorBody struct {
	Code     apicontract.ErrorCode `json:"code"`
	Message  string                `json:"message"`
	ExitCode int                   `json:"exit_code"`
}

type ErrorEnvelope struct {
	SchemaVersion int    `json:"schema_version"`
	Command       string `json:"command"`
	// OK is always false on an error document.
	OK    bool      `json:"ok"`
	Error ErrorBody `json:"error"`
	// DBPath names the store the command had opened, when it got that far.
	DBPath string `json:"db_path,omitempty"`
	// SoftFail states that --soft-fail forced the process exit status to 0.
	SoftFail      bool   `json:"soft_fail,omitempty"`
	GeneratedAt   string `json:"generated_at"`
	GeneratedAtMS int64  `json:"generated_at_ms"`
}

type EventFields struct {
	Required    []string
	Optional    []string
	Description string
}

type GlobSkipped struct {
	File  string `json:"file"`
	Error string `json:"error"`
}

type GlobSources struct {
	Pattern     string        `json:"pattern"`
	Matched     int           `json:"matched"`
	Loaded      int           `json:"loaded"`
	Skipped     []GlobSkipped `json:"skipped"`
	ParseErrors int           `json:"parse_errors"`
}

type OutputBudget struct {
	MaxBytes   int `json:"max_bytes"`
	Returned   int `json:"returned"`
	Omitted    int `json:"omitted"`
	NextOffset int `json:"next_offset"`
}

type Schema = jsonschema.Schema

type Variant struct {
	Flag string
	Item any
}