devconfig

type Config struct {
	// Version is the schema version (1 today). Forward-compat: an
	// unknown future version still loads — fields we don't know are
	// preserved on save only if round-tripped, which we do not do;
	// keep additions backward-compatible.
	Version int `yaml:"version"`

	// PortBase overrides DefaultPortBase for this machine. Zero =
	// DefaultPortBase.
	PortBase int `yaml:"port_base,omitempty"`

	// Projects is the registry, keyed by project name (lock.project).
	Projects map[string]*Project `yaml:"projects,omitempty"`

	// Remotes are named remote docker hosts, keyed by a user-chosen name.
	// Populated by `stack remote add`; consumed in remote mode to run the
	// docker stack on a beefy SSH-reachable box. Empty = local-only, the default.
	Remotes map[string]*Remote `yaml:"remotes,omitempty"`

	// DefaultMode is the global default execution mode when a project does
	// not pin its own: "local" (default) or "remote". Empty == local.
	DefaultMode string `yaml:"default_mode,omitempty"`

	// DefaultRemote is the Remotes key used in remote mode when a project
	// does not pin one. Empty == no default (an explicit pin/flag is then
	// required to resolve a remote).
	DefaultRemote string `yaml:"default_remote,omitempty"`
}

type Mode string

type PortPin struct {
	Key string
	Was int
	Now int
	// ClashesWith names another registered project already holding this port.
	// The pin is still honoured — an explicit choice is the answer, and
	// refusing it would put this back where it started — but two stacks that
	// both publish it cannot run at once, and docker's own message at bind
	// time says only "port is already allocated", never which project owns it.
	ClashesWith string
}

type Preset struct {
	// Services is the list of compose service names to bring up. Empty
	// = the whole stack.
	Services []string `yaml:"services,omitempty"`

	// Env is extra environment layered onto the compose subprocess on
	// top of the managed port vars (e.g. W17_OTEL_ENDPOINT="" to skip
	// the tracing backend on a weak machine). A preset CAN override a
	// managed port var here, but that is rarely wanted.
	Env map[string]string `yaml:"env,omitempty"`
}

type Project struct {
	// Path is the absolute filesystem path to the project root (the
	// directory holding w17/lock.yaml).
	Path string `yaml:"path"`

	// Ports maps a port-slot key (the override env-var name, e.g.
	// SHOP_GATEWAY_HOST_PORT) to the unique host port w17ctl assigned
	// it. Rewritten into the compose subprocess env on `stack up`.
	Ports map[string]int `yaml:"ports,omitempty"`

	// ActivePreset is the preset applied by a bare `stack up` (empty =
	// full stack, no env overlay, all services).
	ActivePreset string `yaml:"active_preset,omitempty"`

	// Presets are named run profiles for this project.
	Presets map[string]*Preset `yaml:"presets,omitempty"`

	// Autosync is this dev's local override of the project's
	// dev-DB workflow mode. nil = no override (follow the lock's project
	// default); non-nil wins over the lock. true = Mode A (autosync —
	// the initiative follows the git branch, with auto snapshot/restore),
	// false = Mode B (manual — active initiative set via `initiative
	// activate`).
	Autosync *bool `yaml:"autosync,omitempty"`

	// ActiveInitiative is the dev's currently-active initiative in manual
	// (autosync-off) mode — the persistent pointer `initiative activate`
	// sets, which `stack build` + `db snapshot` then scope to. Empty =
	// the implicit "default" initiative. Ignored in autosync mode (the
	// git branch drives the initiative there).
	ActiveInitiative string `yaml:"active_initiative,omitempty"`

	// Mode pins this project's stack execution mode, winning over the
	// global DefaultMode. "" = follow DefaultMode; "local" | "remote".
	// Set by `stack local` / `stack remote use`.
	Mode string `yaml:"mode,omitempty"`

	// Remote pins which registered remote this project uses in remote
	// mode, winning over DefaultRemote. "" = follow DefaultRemote; else a
	// Remotes key.
	Remote string `yaml:"remote,omitempty"`

	// Bind is the host interface docker publishes this project's ports on,
	// injected as W17_BIND_HOST into the compose env (like the port map).
	// "" = loopback (127.0.0.1, secure default) | "loopback" | "public"
	// (0.0.0.0 — reachable off-box). Set by `stack bind`. It is a
	// dev-machine runtime concern (not a codegen input), so it lives here
	// next to the ports, NOT in the lock.
	Bind string `yaml:"bind,omitempty"`

	// PublicAck records that the developer has acknowledged (once, by
	// typing the confirmation phrase) that this project's containers are
	// exposed to the network — the guard for the dangerous public+remote
	// combination. Reset whenever Bind leaves "public".
	PublicAck bool `yaml:"public_ack,omitempty"`
}

type Remote struct {
	// SSH is the destination passed to ssh/rsync: user@host[:port]. An
	// ssh_config alias (a plain host name) is fine.
	SSH string `yaml:"ssh"`

	// Path is the base directory on the server; each project gets a
	// subdir <Path>/<project> that w17ctl rsyncs the tree into.
	Path string `yaml:"path"`
}

type Slot struct {
	// Key is the stable slot identifier — equal to EnvVar, so a slot's
	// assigned port survives across re-introspection.
	Key string

	// EnvVar is the environment variable that overrides the host port
	// (e.g. SHOP_GATEWAY_HOST_PORT). w17ctl sets this in the compose
	// subprocess env on `stack up`.
	EnvVar string

	// Default is the compose default (the `:-N` value), 0 if the
	// mapping used `${VAR}` with no default.
	Default int

	// Container is the in-container port the host port maps to (for
	// display only).
	Container int

	// Service is the compose service name the port belongs to.
	Service string

	// Source is the project-relative compose file the slot came from.
	Source string
}