spec

type AI struct {
	// Deny are project paths (globs) the assistant never reads, e.g. configs/** holding credentials.
	Deny         []string `yaml:"deny"`
	Instructions string   `yaml:"instructions"`
	// Ideas are the questions tab offers in an empty chat, by screen (services, logs, ...) or "all";
	// they come before rig's own.
	Ideas map[string][]string `yaml:"ideas"`
}

type Agent struct {
	On           AgentTrigger `yaml:"on"`
	Instructions string       `yaml:"instructions"`
	Tools        []string     `yaml:"tools"`
	Approve      []string     `yaml:"approve"`
}

type AgentTrigger struct {
	Event    string `yaml:"event"`
	Schedule string `yaml:"schedule"`
}

type Alert struct {
	Name   string  `yaml:"name"`
	Source string  `yaml:"source"`
	Metric string  `yaml:"metric"`
	Query  string  `yaml:"query"`
	Warn   float64 `yaml:"warn"`
	Crit   float64 `yaml:"crit"`
	// Below fires when the number drops under the thresholds instead (consumers, ready replicas).
	Below bool   `yaml:"below"`
	Unit  string `yaml:"unit"`
}

type Build struct {
	Go         string            `yaml:"go"`
	Dockerfile string            `yaml:"dockerfile"`
	Context    string            `yaml:"context"`
	Command    []string          `yaml:"command"`
	Args       map[string]string `yaml:"args"`
}

type Component struct {
	Name string `yaml:"-"`
	Kind string `yaml:"kind"`
	Type string `yaml:"type"`
	Node yaml.Node
}

type DashVar struct {
	Values  []string `yaml:"values"`
	Source  string   `yaml:"source"`
	Query   string   `yaml:"query"`
	Label   string   `yaml:"label"`
	Default string   `yaml:"default"`
	Multi   bool     `yaml:"multi"`
	All     bool     `yaml:"all"`
}

type Dashboard struct {
	Help string `yaml:"help"`
	// Vars are the dashboard's $variables, picked in the UI; queries use them as $name.
	Vars   map[string]*DashVar `yaml:"vars"`
	Panels []Panel             `yaml:"panels"`
	// VarOrder is Vars as rig.yaml lists them.
	VarOrder []string `yaml:"-"`
}

type Environment struct {
	Name        string     `yaml:"-"`
	Description string     `yaml:"description"`
	Runtime     *Component `yaml:"runtime"`
	Protected   bool       `yaml:"protected"`
	// ReadOnly refuses every change (start, stop, deploy, exec, data and KV writes, load), even with
	// --yes; reads, logs, metrics, traces and read-only queries still work.
	ReadOnly   bool                  `yaml:"readonly"`
	Vars       map[string]string     `yaml:"vars"`
	Only       []string              `yaml:"only"`
	Components map[string]*Component `yaml:"components"`
	Services   map[string]yaml.Node  `yaml:"services"`
	// Tasks replace the project's tasks of the same name in this environment.
	Tasks map[string]Task `yaml:"tasks"`
	// Queries replace the project's queries of the same name in this environment.
	Queries map[string]*Query `yaml:"queries"`
	// Alerts add to the project's alerts in this environment.
	Alerts []Alert `yaml:"alerts"`
	// OTel replaces the fields it sets of the project's otel:.
	OTel *OTel `yaml:"otel"`
	// Infra names the environment that runs this one's shared services, so heavy infrastructure
	// (a database, a broker) runs once for local, docker and kind alike.
	Infra string `yaml:"infra"`
}

type Import map[string]string

type Importer func(path, dir string) (map[string]*Service, error)

type LoadRun struct {
	Help      string        `yaml:"help"`
	Generator string        `yaml:"generator"`
	Profile   string        `yaml:"profile"`
	Rate      float64       `yaml:"rate"`
	For       time.Duration `yaml:"for"`
	Assert    []string      `yaml:"assert"`
}

type LogsUI struct {
	Wrap bool `yaml:"wrap"`
	// Raw shows lines as written instead of "LEVEL message key=value"; s switches.
	Raw bool `yaml:"raw"`
	// Time, Level and Message are the JSON keys of those parts, first match wins.
	Time    []string `yaml:"time"`
	Level   []string `yaml:"level"`
	Message []string `yaml:"message"`
	// Fields, when set, are the only other keys shown, in this order; Hide are keys left out (stack,
	// caller, ...) until h shows them.
	Fields []string `yaml:"fields"`
	Hide   []string `yaml:"hide"`
}

type Migration struct {
	From  int
	Apply func(root *yaml.Node) error
}

type OTel struct {
	// Endpoint takes every signal (an OpenTelemetry Collector: svc://otel-collector:4318); Traces,
	// Metrics and Logs send one signal elsewhere, with its full path (svc://jaeger:4318/v1/traces).
	// A signal with no address is off.
	Endpoint string `yaml:"endpoint"`
	Traces   string `yaml:"traces"`
	Metrics  string `yaml:"metrics"`
	Logs     string `yaml:"logs"`
	// Protocol is http/protobuf (default), http/json or grpc.
	Protocol string `yaml:"protocol"`
	// Sample is the fraction of traces kept (parent based); left out, the SDK's default (all).
	Sample *float64 `yaml:"sample"`
	// Attributes are added to every service's resource, after service.namespace (the project) and
	// deployment.environment (the environment).
	Attributes map[string]string `yaml:"attributes"`
}

type Panel struct {
	// Row starts a new titled row of panels; a panel with only row: is the row's header.
	Row   string `yaml:"row"`
	Title string `yaml:"title"`
	Query string `yaml:"query"`
	// Queries are several queries drawn together (p50, p95 and p99), each with its own legend.
	Queries []PanelQuery `yaml:"queries"`
	Unit    string       `yaml:"unit"`
	Source  string       `yaml:"source"`
	Legend  string       `yaml:"legend"`
	Help    string       `yaml:"help"`
	// Kind: line (default), stat, gauge, bar (one bar per series, its last value), table.
	Kind string `yaml:"kind"`
	// Width is out of 24 columns, like Grafana (default 12, stat and gauge 6); Height in lines.
	Width  int `yaml:"width"`
	Height int `yaml:"height"`
	// Min and Max bound a gauge (default 0..100 for %, else 0..the largest value).
	Min *float64 `yaml:"min"`
	Max *float64 `yaml:"max"`
	// Warn and Crit colour stat, gauge and bar values amber and red past them.
	Warn *float64 `yaml:"warn"`
	Crit *float64 `yaml:"crit"`
	// Stack draws line series stacked.
	Stack bool `yaml:"stack"`
}

type PanelQuery struct {
	Query  string `yaml:"query"`
	Legend string `yaml:"legend"`
}

type Plugin struct {
	// Path loads the plugin from a directory instead of the installed store.
	Path string `yaml:"path,omitempty"`
	// Version is the version or range to use, as rig plugin add writes it.
	Version string `yaml:"version,omitempty"`
	// Off disables the plugin.
	Off bool `yaml:"off,omitempty"`
	// Config is every other key, checked against the plugin's config schema.
	Config map[string]any `yaml:",inline"`
}

type Probe struct {
	Port string `yaml:"port"`
	Path string `yaml:"path"`
}

type Project struct {
	Version int      `yaml:"version"`
	Name    string   `yaml:"project"`
	Default string   `yaml:"default"`
	Imports []Import `yaml:"imports"`
	// Include are globs of more YAML files merged under this one, later files winning.
	Include []string `yaml:"include"`
	// Templates are partial entries a service, component, task or query takes with `extends`;
	// ${name} in one is the entry's name.
	Templates map[string]yaml.Node `yaml:"templates"`
	// Defaults are per section (services, tasks, ...) keys every entry starts from.
	Defaults map[string]yaml.Node `yaml:"defaults"`
	// Plugins configures plugins by name: where one comes from, whether it is off, and its own keys.
	Plugins      map[string]*Plugin      `yaml:"plugins"`
	Vars         map[string]string       `yaml:"vars"`
	Services     map[string]*Service     `yaml:"services"`
	Environments map[string]*Environment `yaml:"environments"`
	Components   map[string]*Component   `yaml:"components"`
	Dashboards   map[string]*Dashboard   `yaml:"dashboards"`
	// Views are screens built from widgets bound to sources: a tab, a service section, a panel.
	Views map[string]*view.View `yaml:"views"`
	// Tests are named test suites: `rig test <name>` and the Tests screen.
	Tests     map[string]*TestSuite `yaml:"tests"`
	Manifests []string              `yaml:"manifests"`
	// Tasks are named lists of shell steps: `rig task <name>`.
	Tasks map[string]Task `yaml:"tasks"`
	// Queries are saved queries: run on demand, or on a schedule while the UI is open.
	Queries map[string]*Query `yaml:"queries"`
	// Secrets are names ${NAME} may use whose values live outside the repo: the environment, then
	// `rig secret set`, then the default written here.
	Secrets map[string]Secret `yaml:"secrets"`
	// Alerts are watched while the UI is open and shown in its header; `rig alerts` checks them once.
	Alerts []Alert `yaml:"alerts"`
	// Reports name the metrics a run is measured by: `rig report <name>`, a test suite's report:,
	// the Load screen's W.
	Reports map[string]*Report `yaml:"reports"`
	// Load names load runs: a generator driven by a profile, judged by assertions (`rig load run <name>`).
	Load map[string]*LoadRun `yaml:"load"`
	// Sections split the Services screen by business area; services in none fall under "other".
	Sections map[string]*Section `yaml:"sections"`
	// OTel points every app and load service at OpenTelemetry backends.
	OTel *OTel `yaml:"otel"`
	// UI picks the screens of `rig` and their order.
	UI *UI `yaml:"ui"`
	// Keys is the key preset: rig (the default). Usually set in .rig/local.yaml or
	// ~/.config/rig/config.yaml, since it is a personal choice.
	Keys string `yaml:"keys"`
	// AI tells the assistant (`rig ai`, @ in the UI) about the project: paths it must not read, notes.
	AI *AI `yaml:"ai"`
	// Agents are AI agents that run on an event or a schedule with a limited set of tools.
	Agents map[string]*Agent `yaml:"agents"`
	// Policy binds users, groups and the AI to roles of allowed, confirmed and approved actions.
	Policy *policy.Config `yaml:"policy"`
	// Help is shown by `rig -h` under the project name: this project's own quick-start for its main
	// CLI workflows (e.g. build/deploy/ship with a target database and image tag). Plain text, a few
	// example command lines; left out, `rig -h` shows only its own generic help.
	Help string `yaml:"help"`

	// DashboardOrder, TestOrder and SectionOrder are the names as rig.yaml lists them.
	DashboardOrder []string `yaml:"-"`
	TestOrder      []string `yaml:"-"`
	SectionOrder   []string `yaml:"-"`
	ViewOrder      []string `yaml:"-"`

	// Unset are the ${NAME}s the file uses (outside other environments) that nothing sets and that
	// have no :-default: they stay as written.
	Unset []string `yaml:"-"`
	// NoImporter are the imports: kinds skipped because no installed plugin reads them.
	NoImporter []string `yaml:"-"`
	// FromEnv are the ${NAME}s the file took from the process environment, with their values.
	FromEnv map[string]string `yaml:"-"`

	// Config is the composed file, with where each value came from.
	Config *config.Doc `yaml:"-"`

	// Dir is where the project file lives; relative paths in it resolve from here.
	Dir  string `yaml:"-"`
	File string `yaml:"-"`
	// contains filtered or unexported fields
}

type Query struct {
	Name   string            `yaml:"-"`
	Source string            `yaml:"source"`
	Query  string            `yaml:"query"`
	Help   string            `yaml:"help"`
	Group  string            `yaml:"group"`
	Params map[string]string `yaml:"params"`
	// Every runs the query on a schedule while the UI is open, when Active (or activated there).
	Every  time.Duration `yaml:"every"`
	Active bool          `yaml:"active"`
}

type Redundancy struct {
	Path string
	Line int
	From config.Origin
}

type Report struct {
	Help string `yaml:"help"`
	// Source is the metrics component (default the first).
	Source  string         `yaml:"source"`
	Metrics []ReportMetric `yaml:"metrics"`
	Traces  []ReportTrace  `yaml:"traces"`
	Queries []ReportQuery  `yaml:"queries"`
	// Verbosity is brief, normal (default) or full: how many series, rows and slow traces it keeps.
	Verbosity string `yaml:"verbosity"`
	// Every adds a timeline: each metric's value per interval of the window.
	Every time.Duration `yaml:"every"`
	// Format is md (default), html, json, xml, csv or junit; a file name's extension wins.
	Format string `yaml:"format"`
	// Template is markdown (Go text/template) shown instead of the default layout: {{table "source"}}
	// renders a plugin source, {{.Rows}}, {{.Tests}}, {{.Load}} and {{.Compare}} the measured parts.
	Template string `yaml:"template"`
	// Tests adds a suite's last run, Load a load: entry's last result.
	Tests string `yaml:"tests"`
	Load  string `yaml:"load"`
	// Compare is last (or a saved report's time, 20261011-1504): each metric's change against it.
	Compare string `yaml:"compare"`
	// AI adds a summary the assistant writes from the report.
	AI bool `yaml:"ai"`
	// Publish runs these actions with the report: ${report} is its markdown, ${file} its saved file.
	Publish []ReportPublish `yaml:"publish"`
	// Schedule measures and publishes it on a cron schedule (5 fields) while `rig report watch` runs,
	// over the time since its last run.
	Schedule string `yaml:"schedule"`
}

type ReportMetric struct {
	Title  string   `yaml:"title"`
	Query  string   `yaml:"query"`
	Unit   string   `yaml:"unit"`
	Legend string   `yaml:"legend"`
	Stats  []string `yaml:"stats"`
}

type ReportPublish struct {
	Action string         `yaml:"action"`
	Args   map[string]any `yaml:"args"`
}

type ReportQuery struct {
	Title  string `yaml:"title"`
	Source string `yaml:"source"`
	Query  string `yaml:"query"`
}

type ReportTrace struct {
	Title     string        `yaml:"title"`
	Source    string        `yaml:"source"`
	Service   string        `yaml:"service"`
	Operation string        `yaml:"operation"`
	Min       time.Duration `yaml:"min"`
}

type Run struct {
	Command []string `yaml:"command"`
	Args    []string `yaml:"args"`
	Dir     string   `yaml:"dir"`
}

type Secret struct {
	Help    string `yaml:"help"`
	Default string `yaml:"default"`
}

type Section struct {
	Name     string   `yaml:"-"`
	Help     string   `yaml:"help"`
	Services []string `yaml:"services"`
}

type Service struct {
	Name string `yaml:"-"`
	// Extends names the templates this service starts from, in order.
	Extends   yaml.Node         `yaml:"extends"`
	Role      string            `yaml:"role"`
	Groups    []string          `yaml:"groups"`
	DependsOn []string          `yaml:"depends_on"`
	Ports     map[string]int    `yaml:"ports"`
	Env       map[string]string `yaml:"env"`
	// EnvFile are KEY=VALUE files (from the project directory) read under env:, later files winning.
	EnvFile []string `yaml:"env_file"`
	Image   string   `yaml:"image"`
	// Replicas left out keeps what the environment has (the manifest's count, or a running workload's);
	// 0 keeps a service deployed but stopped.
	Replicas *int   `yaml:"replicas"`
	Build    *Build `yaml:"build"`
	Run      *Run   `yaml:"run"`
	Health   *Probe `yaml:"health"`
	Metrics  *Probe `yaml:"metrics"`
	Pprof    *Probe `yaml:"pprof"`
	// Shared marks infrastructure that one environment runs for others (see Environment.Infra).
	Shared bool `yaml:"shared"`
	// Delay is how long up waits after the service's dependencies are ready before starting it.
	Delay time.Duration `yaml:"delay"`
	// Manual services start only when named (or through their group or section), never with "all"
	// or their role (rig infra up).
	Manual bool `yaml:"manual"`
	// Watch is what rig watch (ctrl+w in the UI) rebuilds and restarts the service on.
	Watch *Watch `yaml:"watch"`

	// Sections owned by adapters (local:, docker:, k8s:, ...), decoded by the adapter that reads them.
	Sections map[string]yaml.Node `yaml:",inline"`
}

type Task struct {
	Help string `yaml:"help"`
	// Group is the tab the TUI's task picker lists it under; without one, the name's first word
	// (nexus-prune: nexus) when other tasks share it.
	Group string    `yaml:"group"`
	Args  []TaskArg `yaml:"args"`
	// Confirm asks before the first step, on any environment; --yes answers it.
	Confirm bool `yaml:"confirm"`
	// ReadOnly marks a task that changes nothing, so it runs in a read-only environment too.
	ReadOnly bool     `yaml:"readonly"`
	Steps    []string `yaml:"steps"`
	// StepHelp says what each step does: the # comment above it in rig.yaml, or its own first # lines.
	StepHelp []string `yaml:"-"`
}

type TaskArg struct {
	Name    string   `yaml:"name"`
	Help    string   `yaml:"help"`
	Default string   `yaml:"default"`
	Choices []string `yaml:"choices"`
	From    string   `yaml:"from"`
	Multi   bool     `yaml:"multi"`
}

type TestSuite struct {
	Name  string `yaml:"-"`
	Help  string `yaml:"help"`
	Group string `yaml:"group"`
	// Command runs the suite through sh instead of go test: pytest, jest, mvn test, cargo test, ...
	// Writing JUnit XML to $RIG_JUNIT gives the screen one row per test; without it the suite passes
	// or fails as a whole by its exit status.
	Command string `yaml:"command"`
	// Runner is a plugin's tests/1 runner (pytest, jest, vitest, hurl, k6, junit) instead of go test;
	// With is its options.
	Runner   string         `yaml:"runner"`
	With     map[string]any `yaml:"with"`
	Packages []string       `yaml:"packages"`
	// Exclude drops packages from Packages (go list patterns: ./pkg/tests/...), so a suite can be
	// "everything but the integration tests".
	Exclude []string `yaml:"exclude"`
	// Dir is where go test runs (default the project directory).
	Dir  string `yaml:"dir"`
	Run  string `yaml:"run"`
	Skip string `yaml:"skip"`
	Tags string `yaml:"tags"`
	// Env reaches the test binaries; svc:// addresses resolve in the active environment.
	Env      map[string]string `yaml:"env"`
	Timeout  time.Duration     `yaml:"timeout"`
	Race     bool              `yaml:"race"`
	Cover    bool              `yaml:"cover"`
	Short    bool              `yaml:"short"`
	Count    int               `yaml:"count"`
	Parallel int               `yaml:"parallel"`
	// Bench runs benchmarks matching it (go test -bench); Benchtime and Benchmem tune them.
	Bench     string `yaml:"bench"`
	Benchtime string `yaml:"benchtime"`
	Benchmem  bool   `yaml:"benchmem"`
	// Flags are more go test flags; Args go to the test binary after -args.
	Flags []string `yaml:"flags"`
	Args  []string `yaml:"args"`
	// Needs are services (or groups) the suite expects up; the UI warns when they are not.
	Needs []string `yaml:"needs"`
	// Report is a reports: entry measured over each run and saved with it.
	Report string `yaml:"report"`
}

type UI struct {
	// Tabs are the screens shown, in order (number keys follow it); left out, every screen the
	// project configures something for shows, in the order of Screens.
	Tabs []string `yaml:"tabs"`
	// Mode is detailed (the default), simple (fewer columns, keys and screens), software (the dev
	// screens and views for developers) or product (metrics and views for product); V picks it.
	Mode string  `yaml:"mode"`
	Logs *LogsUI `yaml:"logs"`
}

type Watch struct {
	// Paths are directories or files (from the project directory); left out, the packages a build.go
	// main imports from the project, else build.context, else run.dir.
	Paths []string `yaml:"paths"`
	// Ignore are globs matched against a changed file's path and name (*_test.go, docs/**).
	Ignore []string `yaml:"ignore"`
}