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 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 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 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"`
	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"`
	// 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"`
	// 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"`
	// AI tells the assistant (`rig ai`, @ in the UI) about the project: paths it must not read, notes.
	AI *AI `yaml:"ai"`
	// 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:"-"`

	// 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:"-"`
	// FromEnv are the ${NAME}s the file took from the process environment, with their values.
	FromEnv map[string]string `yaml:"-"`

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

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 Report struct {
	Help string `yaml:"help"`
	// Source is the metrics component (default the first).
	Source  string         `yaml:"source"`
	Metrics []ReportMetric `yaml:"metrics"`
}

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

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:"-"`
	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"`
	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"`
}

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"`
	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 simple (fewer columns, keys and panels, for newcomers) or detailed (the default); V
	// switches it in the UI.
	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"`
}