hostinfra

type Spec struct {
	// Name is the workload name (e.g. "postgres"). It names the instance in
	// logs and, by default, its data directory.
	Name string
	// Engine selects the implementation: EnginePostgres, EngineZitadel,
	// EngineNATS or EngineTemporal.
	Engine string
	// Port is the loopback port the server binds — the same number the app's
	// DSN dials, which is why the environment declares it once and hands it
	// to both.
	Port int
	// Database is created on first boot; User/Password are the credentials
	// the DSN carries.
	Database string
	User     string
	Password string
	// DataDir is where the cluster lives. Relative paths resolve against the
	// project root; empty means DefaultDataDirRel/<Name>.
	DataDir string
	// Version pins the engine major version. Empty means forge's default.
	Version string

	// IDPDatabase is the database Zitadel creates its schema in, on the
	// postgres server IDPDatabasePort names. Its OWN database — the
	// container path spent a second postgres container on the same
	// isolation.
	IDPDatabase string
	// IDPDatabasePort is where that postgres server listens. It is the
	// APP's host-native postgres, so this is the same number the app's DSN
	// carries, handed over from the one place the environment declares it.
	IDPDatabasePort int
	// IDPMasterKey is Zitadel's encryption key for the credentials it
	// stores. Exactly 32 characters, per Zitadel.
	IDPMasterKey string
	// IDPStepsFile is the declarative bootstrap passed as `--steps`
	// (idp-steps.yaml). Relative to the project root; this file IS the
	// instance's setup.
	IDPStepsFile string
	// IDPPATPath is where Zitadel writes the service-account personal
	// access token on first boot. It must match what the identity step of `forge env up`
	// reads — the two are one declaration.
	IDPPATPath string

	// NATSMonitorPort is the HTTP monitoring port (`--http_port`). Zero
	// means no monitoring endpoint.
	NATSMonitorPort int

	// TemporalNamespaces are created at launch; readiness waits for every
	// one of them. Empty means just Temporal's own "default".
	TemporalNamespaces []string
	// TemporalUIPort is the Web UI's port. Zero means headless.
	TemporalUIPort int
}

type Status struct {
	// Running reports whether a server this project owns is serving.
	//
	// Ownership is load-bearing and is why this cannot be a port probe.
	// On a shared dev box the declared port may be held by ANOTHER
	// project's postgres or a system one, and reporting that as "our
	// instance is up" is the same adoption mistake Start refuses to
	// make — it would show green for a database this project has never
	// written to.
	Running bool

	// Foreign reports the specific case of "something is listening on
	// the declared port, and it is not ours". Distinct from !Running
	// with nothing there: one means "start it", the other means "a
	// human must free the port", and collapsing them loses the only
	// actionable half.
	Foreign bool

	// Port is where the instance is ACTUALLY serving, which is not
	// necessarily the declared port: an instance started before the
	// declaration moved is still running on the old one. Zero when not
	// running, and -1 when it is alive but has not published a port yet
	// (mid-boot).
	Port int

	// Version is the engine build the instance is running, empty when
	// unknown. For postgres it is read from the cluster's own PG_VERSION
	// file — the server's record of what initdb created, rather than the
	// declaration's record of what was asked for. Those disagree exactly
	// when someone changed the declared version without recreating the
	// data directory, and that disagreement is the thing worth seeing.
	Version string

	// Ready reports whether the instance ANSWERS, as opposed to merely
	// having a live process. The two come apart during boot and stay
	// apart when a server wedges, and that gap is the whole difference
	// between "a process exists" and "the thing the app is about to dial
	// will respond" — the distinction Start's doc-comment already draws
	// for the write path.
	//
	// Meaningless when Running is false.
	Ready bool

	// DataDir is the resolved data directory, so a report can name the
	// thing on disk it is talking about.
	DataDir string
}