manifest

type Argv []string

type Build struct {
	Context    string `yaml:"context,omitempty"`
	Dockerfile string `yaml:"dockerfile,omitempty"`
	Target     string `yaml:"target,omitempty"`
	// Args are build arguments, and they routinely decide what the image
	// contains rather than merely how it is labelled: a Dockerfile that takes
	// ARG NODE_ENV and runs `npm ci` installs the development dependencies or
	// skips them on the strength of that one value. Dropping them produced an
	// image that built successfully and then exited 127 because the command
	// the compose file runs was never installed.
	Args map[string]string `yaml:"args,omitempty"`
}

type Diagnostic struct {
	Severity Severity
	Rule     string // "R1".."R7", or "" for structural findings
	Path     string // e.g. services/api/env/DATABASE_URL
	Msg      string
	Argv     Argv // populated for Approval findings, shown verbatim to the human
}

type Emulator struct {
	// Image is digest-free on purpose: these are devbay's choices rather than
	// the repository's, and pinning them here would mean a devbay release to
	// take a patch to a mail catcher.
	Image string
	// Port is the one that gets the bay hostname.
	Port int
	// Ports are the rest, each of which gets its own subdomain -- a mail
	// catcher's interface and its SMTP port are separately addressable, which
	// is the whole reason a service may declare more than one.
	Ports map[string]int
	// Health is how devbay knows it is ready.
	Health *Health
	// Cmd overrides the image's entrypoint where the emulator needs it.
	Cmd Argv
	Env map[string]string
	// Why is shown when a developer asks what they are getting.
	Why string
}

type External struct {
	Emulate string `yaml:"emulate"`
	Real    string `yaml:"real,omitempty"` // "never" or "gated"; there is no "always"
	Mint    *Mint  `yaml:"mint,omitempty"`
}

type Fork string

type Health struct {
	HTTP string `yaml:"http,omitempty"` // path probed on the primary port
	TCP  int    `yaml:"tcp,omitempty"`  // port that must accept a connection
	Cmd  Argv   `yaml:"cmd,omitempty"`  // exec in container; healthy on exit 0

	// Log is an RE2 regex matched against stdout and stderr. Preferred for
	// processes with no port, and often better than an HTTP probe for dev
	// servers, which print an explicit ready line: Vite emits "ready in 412
	// ms", Sidekiq "Starting processing, hit Ctrl-C to stop", Celery
	// "celery@host ready.". Matching that is real readiness.
	Log string `yaml:"log,omitempty"`

	// Process is liveness only: healthy while the main process runs. The
	// weakest probe available, and Validate warns on it. It exists because the
	// alternative — inventing a fake HTTP endpoint for a Sidekiq or Celery
	// worker — is a lie that silently defeats the verification loop.
	Process bool `yaml:"process,omitempty"`

	Timeout     string `yaml:"timeout,omitempty"`
	Interval    string `yaml:"interval,omitempty"`
	StartPeriod string `yaml:"start_period,omitempty"`
}

type Kind string

type Manifest struct {
	Version     int                  `yaml:"version"`
	Project     string               `yaml:"project"`
	Services    map[string]*Service  `yaml:"services"`
	Tasks       map[string]*Task     `yaml:"tasks"`
	Externals   map[string]*External `yaml:"externals,omitempty"`
	Supervision *Supervision         `yaml:"supervision,omitempty"`

	// Path is the file this manifest was loaded from. Not part of the format.
	Path string `yaml:"-"`
}

type Mint struct {
	Provider string         `yaml:"provider,omitempty"` // aws-sts, github-app, gcp-sa
	TTL      string         `yaml:"ttl,omitempty"`
	Scope    map[string]any `yaml:"scope,omitempty"`
}

type Mount struct {
	// Source is relative to the repository root and confined to it.
	Source string `yaml:"source"`
	// Target is an absolute path inside the container.
	Target string `yaml:"target"`
}

type Report struct {
	Format ReportFormat `yaml:"format"`
	Path   string       `yaml:"path,omitempty"`
}

type ReportFormat string

type Restart string

type Result struct {
	Diagnostics []Diagnostic
}

type Scope string

type Seed struct {
	After   []string `yaml:"after"`
	Sources []string `yaml:"sources"`
}

type Service struct {
	Kind  Kind   `yaml:"kind,omitempty"`
	Image string `yaml:"image,omitempty"`
	Build *Build `yaml:"build,omitempty"`

	Scope Scope `yaml:"scope,omitempty"`
	Fork  Fork  `yaml:"fork,omitempty"`
	Seed  *Seed `yaml:"seed,omitempty"`

	Workdir string `yaml:"workdir,omitempty"`

	Install Argv `yaml:"install,omitempty"`
	// InstallScripts permits package lifecycle scripts during Install.
	//
	// False by default: devbay appends --ignore-scripts or the ecosystem
	// equivalent. Running install scripts on a freshly cloned untrusted
	// repository is the delivery mechanism used by the self-replicating
	// Shai-Hulud npm worm, which steals cloud credentials. Setting this true
	// is approval-gated.
	InstallScripts bool `yaml:"install_scripts,omitempty"`

	Start Argv `yaml:"start,omitempty"` // long-running services
	Run   Argv `yaml:"run,omitempty"`   // oneshots

	// Labels are container labels, passed through to the daemon.
	//
	// Load-bearing far more often than they look: a reverse proxy that
	// discovers its backends by label routes to nothing without them, and the
	// stack comes up healthy and answers 404. devbay's own labels are how
	// teardown finds what to remove, so those win on a collision.
	Labels map[string]string `yaml:"labels,omitempty"`

	// DockerSocket binds the host's Docker daemon socket into the service.
	//
	// Off by default and approval-gated, because a container that can reach
	// the daemon can start any other container on the machine, with any image
	// and any mount -- the bay is then isolated from nothing, and neither is
	// the rest of the developer's machine. It exists because refusing outright
	// made devbay unable to run things Docker runs: a reverse proxy that reads
	// container labels, a container manager, and above all a test suite that
	// starts its own containers. An orchestration layer that cannot orchestrate
	// those is not finished; one that hands the daemon over silently is not
	// safe. So it is written down, and a human agrees to it once.
	DockerSocket bool `yaml:"docker_socket,omitempty"`

	// Restart is what to do when the process exits.
	//
	// Present because real compose files depend on it. A stack whose web
	// service talks to a cache it does not declare a dependency on races the
	// cache at startup, and the compose file handles that with
	// `restart: on-failure` rather than with depends_on -- which means
	// transcribing the file without this field produces a stack that dies
	// where the original recovers. devbay cannot infer the missing dependency
	// from the file, so it honours the mechanism the file actually uses.
	Restart Restart `yaml:"restart,omitempty"`

	// Port is the primary port: the one that gets a hostname and, unless
	// overridden, the one an http probe targets. Exactly one exists per
	// service so hostname routing is unambiguous.
	Port int `yaml:"port,omitempty"`
	// Ports are additional named ports. Real services routinely expose more
	// than one — a mail catcher listens on SMTP and serves a web UI, an object
	// store serves an API and a console.
	Ports map[string]int `yaml:"ports,omitempty"`

	Primary bool     `yaml:"primary,omitempty"`
	Needs   []string `yaml:"needs,omitempty"`

	Health *Health `yaml:"health,omitempty"`

	// Watch globs are evaluated by the daemon on the host using native
	// FSEvents or inotify, never by a watcher inside the container: virtiofs
	// does not implement inotify, so host edits do not reliably produce
	// events in a container, and polling costs real CPU per watcher per bay.
	Watch       []string    `yaml:"watch,omitempty"`
	WatchAction WatchAction `yaml:"watch_action,omitempty"`

	// Mounts bind a directory from the repository over a path in the
	// container.
	//
	// Needed by the common `target: dev` pattern, where an image builds the
	// source in and the source is then bound back over the top so edits are
	// live. Declared rather than inferred: devbay tried inferring it from the
	// build context and got it right for interpreted images and wrong for
	// compiled ones, where the same directory holds build output and mounting
	// source over it hides the binary.
	Mounts []Mount `yaml:"mounts,omitempty"`

	// Volumes are paths backed by a named volume rather than the bind mount —
	// node_modules, .venv, vendor/bundle, target, .next. Not an optimisation
	// to defer: a bind-mounted dependency tree runs at roughly 2.5x native on
	// macOS and a named volume recovers most of that.
	Volumes []string `yaml:"volumes,omitempty"`

	// Egress is the outbound allowlist. Absent or empty means no outbound
	// network at all.
	//
	// R4. This field is never authorable by the introspection agent: the
	// validator strips it from model-produced manifests. If a model could
	// write the allowlist, a prompt injection would append its own
	// destination and the sandbox would defeat itself.
	Egress []string `yaml:"egress,omitempty"`

	Env map[string]string `yaml:"env,omitempty"`

	// Provided marks a service devbay generated from its own emulator
	// catalogue rather than one the repository declared. Not part of the
	// format: it exists so R2's approval prompt stays about repository
	// content. Asking a developer to approve an argv devbay chose for them
	// trains them to approve prompts, which is the opposite of what the rule
	// is for.
	Provided bool `yaml:"-"`
}

type Severity int

type Supervision struct {
	Banner      *bool `yaml:"banner,omitempty"`
	FaviconTint *bool `yaml:"favicon_tint,omitempty"`
}

type Task struct {
	Run Argv `yaml:"run"`

	// Needs is the service subgraph this task requires. An empty slice is
	// valid and common: a unit suite that boots zero containers is the
	// fastest path to a verified result.
	//
	// R6. Omitting the key entirely is an error rather than a default,
	// because forcing the author to think about it is the point.
	//
	// The distinction is carried by nil versus empty: YAML decodes `needs: []`
	// to an empty non-nil slice and an omitted key to nil, so no side channel
	// is needed -- which also means a Task built in Go rather than parsed from
	// a file can satisfy the rule, by writing []string{}.
	Needs []string `yaml:"needs"`

	In      string            `yaml:"in,omitempty"`
	Report  *Report           `yaml:"report,omitempty"`
	Env     map[string]string `yaml:"env,omitempty"`
	Timeout string            `yaml:"timeout,omitempty"`
	// contains filtered or unexported fields
}

type WatchAction string