@geekmidas/cli 10.0.0-alpha.1 → 10.0.0-alpha.100

package/dist/compose-BftbEv0b.mjs

@@ -0,0 +1,3154 @@
+import { t as __exportAll } from "./rolldown-runtime-BhDjJH2R.mjs";
+import { t as GkmError } from "./errors-D8Gwp5kU.mjs";
+import { a as runOutput, i as run } from "./run-BJLIerMM.mjs";
+import { B as LOGS_PORT, I as otlpTelemetryEnv, L as resolveStageTelemetry, at as certificateFor, ft as SERVER_IPV4_KEY, ht as isReservedStageKey, it as ComposeTlsFileMissing, ot as proxyFor, z as telemetryEnv } from "./workspace-D1QbNd55.mjs";
+import { a as serverAddressHint, h as stackBackups, i as requiredServerAddress, l as systemLookup, m as backupsService, o as stackHosts, p as backupsRoleStatements, r as isLocalHost, s as stageDns, t as HostNotPointingAtServer, u as BACKUPS_SERVICE, x as stageBackups } from "./dns-CQZQL3gj.mjs";
+import { t as defineTarget } from "./define-6poNqm5O.mjs";
+import { $ as devServicesUsed, $t as applyBuckets, An as scopeTelemetryEnv, Cn as envFor, En as planFor, Fn as hostFor, Gn as logsAccess, Gt as imageLayout, Hn as primaryPortKey, I as appDockerfile, In as DEFAULT_IMAGES, Jn as withLogsPassword, K as validateImageRef, Kn as logsService, Kt as TURBO_VERSION, M as stageProviderNotes, Mn as telemetryOf, Nn as usesTelemetry, Pn as EMULATOR_ACCESS_KEY_ID, Qt as workerUnits, R as ensureDockerignore, Sn as withRedisPassword, St as composeFor, Wn as LOGS_SERVICE, Wt as composeBuildPaths, Xn as isMainFrontendApp, Yn as NoDomainForStage, Yt as findBuildRoot, Zn as resolveHost, _ as createComposeState, _n as REDIS_SERVICE, _t as LEGACY_LOCAL_LOGIN, at as appEnvKeys, bn as runsRedis, bt as pgClient, ct as workerEnvKeys, dt as constructGlobs, en as applyPolicies, et as externalServices, gn as withGeneratedSecrets, in as postgresStatements, it as suppliedOnly, kn as isTelemetryKey, ln as postgresSuperuser, n as reportDatabaseRuns, nn as bucketPolicies, o as recordDnsChanges, on as LOCAL_RABBITMQ_USER, qn as stackLogs, qt as WORKER_PORT, r as reportPlannedSeeds, rt as stageServiceDeclarations, s as currentActor, sn as loadLocalCredentials, st as networkEnv, t as DeploySeedsFailed, tn as applyPostgres, u as DeployJournal, vn as STACK_CACHE, vt as ensurePostgresLogin, wn as localRolePassword, x as recordRelease, xn as stackRedis, yn as redisService, yt as bucketClient, z as workerDockerfile, zn as portKeys, zt as initStageSecrets } from "./seeds-E4nUeXTl.mjs";
+import { t as appKey } from "./derive-B4vDpzgP.mjs";
+import { i as DEFAULT_EVENTS } from "./SubscriberGenerator-1-IsjIwF.mjs";
+import { a as imageRef } from "./identity-CBXr4wNi.mjs";
+import { r as discover } from "./discover-kziEht4W.mjs";
+import { i as installedFrom } from "./drivers-C08LL4E8.mjs";
+import { f as plannedSeeds, o as SeedFailed, p as seedDatabases, u as migrateDatabases } from "./databases-BeGP5eDh.mjs";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { hostname, userInfo } from "node:os";
+import { spawn } from "node:child_process";
+import { createConnection, createServer } from "node:net";
+import { createHash } from "node:crypto";
+import { CLIENT_IP_HEADER, provideKey, provisionOrder, publicEnvFor } from "@geekmidas/manifest";
+import { stringify } from "yaml";
+import { request } from "node:https";
+//#region src/compose/docker.ts
+/**
+* The Docker operations `gkm compose` needs, behind an interface.
+*
+* Small on purpose, like reconcile's: the rules about *when* each runs — the
+* registry is asked before anything is pulled, nothing is started for a tag
+* that is missing — are asserted against a fake, and this file is only the
+* wiring to the real CLI.
+*
+* Every call is an argument array. Image refs, tags and paths come from the
+* workspace, and none of them reaches a shell.
+*/
+/** `output` as `spawn` reads it. */
+const STDIO = {
+	inherit: "inherit",
+	stderr: [
+		"ignore",
+		2,
+		2
+	],
+	ignore: "ignore"
+};
+/**
+* The environment a docker command for `engine` runs with: this process's,
+* with `DOCKER_HOST` pointing at the stack's engine when it is a server's.
+*/
+function engineEnv(engine, extra = {}) {
+	if (!engine.host && Object.keys(extra).length === 0) return void 0;
+	return {
+		...process.env,
+		...extra,
+		...engine.host ? { DOCKER_HOST: engine.host } : {}
+	};
+}
+/** How a stack's docker commands run: where it is, where output goes. */
+function runOptions(stack, extra) {
+	const env = engineEnv(stack, extra);
+	return {
+		cwd: stack.cwd,
+		stdio: STDIO[stack.output ?? "inherit"],
+		...env ? { env } : {},
+		...stack.signal ? { signal: stack.signal } : {}
+	};
+}
+/** The network compose puts a project's services on. */
+function projectNetwork(project) {
+	return `${project}_default`;
+}
+/**
+* The host ports a `docker ps` Ports column publishes: `0.0.0.0:443->443/tcp,
+* [::]:443->443/tcp, 0.0.0.0:9000-9001->9000-9001/tcp`.
+*/
+function publishedPorts(column) {
+	const ports = /* @__PURE__ */ new Set();
+	for (const match of column.matchAll(/(?:[\d.]+|\[[^\]]*\]):(\d+)(?:-(\d+))?->/g)) {
+		const first = Number(match[1]);
+		const last = match[2] ? Number(match[2]) : first;
+		for (let port = first; port <= last; port++) ports.add(port);
+	}
+	return [...ports];
+}
+/** Each line `docker ps` printed, as the containers holding `port`. */
+function portHolders(output, port) {
+	return output.split("\n").filter(Boolean).map((line) => line.split("	")).filter(([, , , column = ""]) => publishedPorts(column).includes(port)).map(([container = "", project, service]) => ({
+		container,
+		...project ? { project } : {},
+		...service ? { service } : {}
+	}));
+}
+/** How long a stack has to pass its health checks. */
+const WAIT_TIMEOUT_S = 180;
+/** `docker compose port` printed nothing a port can be read from. */
+var ServicePortUnknown = class extends GkmError {
+	service;
+	inside;
+	output;
+	constructor(service, inside, output) {
+		super(`'${service}' publishes no host port for ${inside} (docker said: ${output.trim() || "nothing"}). Is it running? \`docker compose ps\` shows the stack.`);
+		this.service = service;
+		this.inside = inside;
+		this.output = output;
+		this.name = "ServicePortUnknown";
+	}
+};
+/**
+* Whether `ref` names a registry on this machine's loopback — which the
+* daemon pulls from and pushes to over plain HTTP by default, and `docker
+* manifest inspect` reaches only when told `--insecure` (without it, a local
+* registry's image is reported as no such manifest).
+*/
+function isLoopbackRegistry(ref) {
+	const first = ref.split("/")[0];
+	if (!ref.includes("/") || !/[.:]|^localhost$/.test(first)) return false;
+	const host = first.replace(/:\d+$/, "");
+	return host === "localhost" || /^127(?:\.\d{1,3}){3}$/.test(host);
+}
+/** `docker push` finished without saying what digest the registry stored. */
+var PushDigestUnknown = class extends GkmError {
+	ref;
+	output;
+	constructor(ref, output) {
+		super(`Pushed ${ref}, but docker did not say which digest the registry stored (it said: ${output.trim().split("\n").slice(-3).join(" / ") || "nothing"}). Check the push with \`docker buildx imagetools inspect ${ref}\`.`);
+		this.ref = ref;
+		this.output = output;
+		this.name = "PushDigestUnknown";
+	}
+};
+/** The digest `docker push` reports last: `<tag>: digest: sha256:… size: …`. */
+function pushedDigest(output) {
+	return [...output.matchAll(/digest: (sha256:[0-9a-f]{64})/g)].at(-1)?.[1];
+}
+function compose(stack, args) {
+	return [
+		"compose",
+		"-p",
+		stack.project,
+		"-f",
+		stack.file,
+		...(stack.overrides ?? []).flatMap((file) => ["-f", file]),
+		...args
+	];
+}
+/** Run a program and keep everything it said, whatever it exits with. */
+function capture(command, args, options = {}) {
+	const { timeoutMs = 6e4 } = options;
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, [...args], {
+			stdio: [
+				options.input === void 0 ? "ignore" : "pipe",
+				"pipe",
+				"pipe"
+			],
+			shell: false,
+			...options.env ? { env: options.env } : {}
+		});
+		if (options.input !== void 0) child.stdin?.end(options.input);
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+		timer.unref?.();
+		child.on("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			resolve({
+				code,
+				stdout,
+				stderr
+			});
+		});
+	});
+}
+/**
+* Whether a failed `docker manifest inspect` means the tag is not there, as
+* opposed to the registry not answering.
+*
+* Read off the message because that is all the CLI gives. Anything not
+* recognisably "no such tag" is treated as the registry being unreachable:
+* a registry that refused credentials must not be reported as a tag that was
+* never pushed, or the fix offered would be the wrong one.
+*/
+function isMissingManifest(output) {
+	return /no such manifest|manifest unknown|manifest for .* not found|not found: manifest/i.test(output);
+}
+const dockerCompose = {
+	async lookup(ref) {
+		const { code, stdout, stderr } = await capture("docker", [
+			"manifest",
+			"inspect",
+			...isLoopbackRegistry(ref) ? ["--insecure"] : [],
+			ref
+		]);
+		if (code === 0) return {
+			ref,
+			status: "found"
+		};
+		const output = `${stderr}\n${stdout}`.trim();
+		return isMissingManifest(output) ? {
+			ref,
+			status: "missing"
+		} : {
+			ref,
+			status: "unreachable",
+			detail: output
+		};
+	},
+	async build(stack, services) {
+		await run("docker", compose(stack, ["build", ...services]), runOptions(stack, {
+			...process.env,
+			DOCKER_BUILDKIT: "1"
+		}));
+	},
+	async pull(stack, services) {
+		await run("docker", compose(stack, ["pull", ...services]), runOptions(stack));
+	},
+	async up(stack, services) {
+		await run("docker", compose(stack, [
+			"up",
+			"-d",
+			"--wait",
+			`--wait-timeout=${WAIT_TIMEOUT_S}`,
+			...services ? [] : ["--remove-orphans"],
+			...services ?? []
+		]), runOptions(stack));
+	},
+	async down(stack) {
+		await run("docker", compose(stack, ["down"]), runOptions(stack));
+	},
+	async port(stack, service, inside) {
+		const env = engineEnv(stack);
+		const output = await runOutput("docker", compose(stack, [
+			"port",
+			service,
+			String(inside)
+		]), {
+			cwd: stack.cwd,
+			...env ? { env } : {},
+			...stack.signal ? { signal: stack.signal } : {}
+		});
+		const port = Number(output.trim().split(":").pop());
+		if (!Number.isInteger(port) || port <= 0) throw new ServicePortUnknown(service, inside, output);
+		return port;
+	},
+	async health(stack, service) {
+		const env = engineEnv(stack);
+		const { code, stdout } = await capture("docker", compose(stack, [
+			"ps",
+			"--format",
+			"{{.Health}}",
+			service
+		]), env ? { env } : {});
+		if (code !== 0) return void 0;
+		return stdout.trim().split("\n")[0] || void 0;
+	},
+	async copyOut(stack, service, from, to) {
+		await mkdir(dirname(to), { recursive: true });
+		await run("docker", compose(stack, [
+			"cp",
+			`${service}:${from}`,
+			to
+		]), runOptions(stack));
+	},
+	async push(stack, ref) {
+		const output = await runOutput("docker", ["push", ref], {
+			cwd: stack.cwd,
+			...stack.signal ? { signal: stack.signal } : {}
+		});
+		const digest = pushedDigest(output);
+		if (!digest) throw new PushDigestUnknown(ref, output);
+		return digest;
+	},
+	async digest(engine, ref) {
+		const env = engineEnv(engine);
+		const { code, stdout } = await capture("docker", [
+			"image",
+			"inspect",
+			"--format={{json .RepoDigests}} {{.Id}}",
+			ref
+		], env ? { env } : {});
+		if (code !== 0) return void 0;
+		const [json = "[]", id] = stdout.trim().split(" ");
+		const repository = ref.split("@")[0].replace(/:[\w][\w.-]*$/, "");
+		try {
+			const digests = JSON.parse(json);
+			const match = Array.isArray(digests) ? digests.find((entry) => typeof entry === "string" && entry.startsWith(`${repository}@`)) : void 0;
+			if (match) return match.slice(repository.length + 1);
+		} catch {}
+		return id || void 0;
+	},
+	async ensureNetwork(engine, name) {
+		const env = engineEnv(engine);
+		const options = env ? { env } : {};
+		const { code } = await capture("docker", [
+			"network",
+			"inspect",
+			name
+		], options);
+		if (code === 0) return;
+		const created = await capture("docker", [
+			"network",
+			"create",
+			name
+		], options);
+		if (created.code !== 0 && !/already exists/.test(created.stderr)) throw new NetworkCreateFailed(name, created.stderr);
+	},
+	async publishers(engine, port) {
+		const env = engineEnv(engine);
+		const { stdout } = await capture("docker", [
+			"ps",
+			"--format",
+			"{{.Names}}	{{.Label \"com.docker.compose.project\"}}	{{.Label \"com.docker.compose.service\"}}	{{.Ports}}"
+		], env ? { env } : {});
+		return portHolders(stdout, port);
+	},
+	async exec(stack, service, command, input) {
+		const env = engineEnv(stack);
+		const options = env ? { env } : {};
+		const { stdout: ids } = await capture("docker", [
+			"ps",
+			"-q",
+			"--filter",
+			`label=com.docker.compose.project=${stack.project}`,
+			"--filter",
+			`label=com.docker.compose.service=${service}`
+		], options);
+		const container = ids.trim().split("\n")[0];
+		if (!container) return {
+			code: null,
+			stdout: "",
+			stderr: `${service} is not running`
+		};
+		return capture("docker", [
+			"exec",
+			...input === void 0 ? [] : ["-i"],
+			container,
+			...command
+		], {
+			...options,
+			...input === void 0 ? {} : { input }
+		});
+	},
+	async container(engine, project, service) {
+		const env = engineEnv(engine);
+		const { stdout } = await capture("docker", [
+			"ps",
+			"--filter",
+			`label=com.docker.compose.project=${project}`,
+			"--filter",
+			`label=com.docker.compose.service=${service}`,
+			"--format",
+			"{{.ID}}	{{.Image}}"
+		], env ? { env } : {});
+		const [id, image] = stdout.trim().split("\n")[0]?.split("	") ?? [];
+		return id && image ? {
+			id,
+			image
+		} : void 0;
+	},
+	runOnce(engine, options) {
+		return dockerExit([
+			"run",
+			"--rm",
+			...options.stdin ? ["-i"] : [],
+			"--network",
+			options.network,
+			...Object.keys(options.env ?? {}).flatMap((name) => ["-e", name]),
+			"--entrypoint",
+			"",
+			options.image,
+			...options.command
+		], {
+			env: engineEnv(engine, { ...options.env }) ?? process.env,
+			...options.stdin ? { stdin: options.stdin } : {},
+			...options.output ? { output: options.output } : {}
+		});
+	}
+};
+/** Spawn `docker`, its output where `output` says; resolve with the exit code. */
+function dockerExit(args, options = {}) {
+	const output = STDIO[options.output ?? "inherit"];
+	const out = Array.isArray(output) ? output : [
+		output,
+		output,
+		output
+	];
+	return new Promise((resolve, reject) => {
+		const child = spawn("docker", [...args], {
+			stdio: [
+				options.stdin ? "pipe" : "ignore",
+				out[1],
+				out[2]
+			],
+			env: options.env ?? process.env,
+			shell: false
+		});
+		if (options.stdin && child.stdin) {
+			options.stdin.on("error", (error) => child.stdin?.destroy(error));
+			child.stdin.on("error", () => {});
+			options.stdin.pipe(child.stdin);
+		}
+		child.on("error", reject);
+		child.on("close", (code) => resolve(code ?? 1));
+	});
+}
+/** `docker network create` failed. */
+var NetworkCreateFailed = class extends GkmError {
+	network;
+	output;
+	constructor(network, output) {
+		super(`Could not create the Docker network '${network}' (docker said: ${output.trim() || "nothing"}). Create it by hand with \`docker network create ${network}\` and run again.`);
+		this.network = network;
+		this.output = output;
+		this.name = "NetworkCreateFailed";
+	}
+};
+//#endregion
+//#region src/compose/server.ts
+/**
+* Where a deployed compose stage runs: its server, reached over SSH.
+*
+* gkm never runs on the server. It runs where the deploy is started — a CI
+* runner, a developer's machine — and drives the server's Docker engine over
+* SSH (`DOCKER_HOST=ssh://user@host`), so the server holds Docker, an SSH
+* login and nothing else: no gkm, no checkout, no cloud credentials.
+*
+* ```ts
+* deploy: { compose: { server: { production: { user: 'deploy' } } } }
+* ```
+*
+* The host is the stage's `GKM_SERVER_IPV4` secret — the address its DNS
+* records already point at — unless `host` names another. The local stage is
+* never given one: it runs on this machine's Docker.
+*
+* What the deploy needs from inside the server — Postgres and MinIO, published
+* on the server's loopback alone — it reaches through an SSH tunnel on the same
+* login, so neither is ever published publicly.
+*/
+/** A deployed compose stage with nowhere to run. */
+var ComposeServerMissing = class extends GkmError {
+	stage;
+	missing;
+	constructor(stage, missing) {
+		super(missing === "config" ? `'${stage}' is a deployed stage, and gkm deploys it to its server's Docker over SSH — it never starts a deployed stage on this machine's Docker. Name the login in gkm.config.ts: deploy: { compose: { server: { ${stage}: { user: 'deploy' } } } } — the host is the stage's ${SERVER_IPV4_KEY} secret (gkm secrets:set ${SERVER_IPV4_KEY} '<ip>' --stage ${stage}), or set host there too.` : `deploy.compose.server.${stage} names no host, and '${stage}' has no ${SERVER_IPV4_KEY} secret to default to. Set it: gkm secrets:set ${SERVER_IPV4_KEY} '<ip>' --stage ${stage} — or set deploy.compose.server.${stage}.host.`);
+		this.stage = stage;
+		this.missing = missing;
+		this.name = "ComposeServerMissing";
+	}
+};
+/** SSH to the stage's server failed before anything was changed there. */
+var ComposeServerUnreachable = class extends GkmError {
+	target;
+	stderr;
+	constructor(target, stderr) {
+		super(`Could not reach Docker on ${target} over SSH (ssh said: ${stderr.trim() || "nothing"}). Check that \`ssh ${target} docker version\` works from here: the host key in ~/.ssh/known_hosts, the key in your agent or ~/.ssh/config, and the user in the server's docker group.`);
+		this.target = target;
+		this.stderr = stderr;
+		this.name = "ComposeServerUnreachable";
+	}
+};
+/** An SSH tunnel to a port on the server's loopback did not open. */
+var ComposeTunnelFailed = class extends GkmError {
+	target;
+	remotePort;
+	stderr;
+	constructor(target, remotePort, stderr) {
+		super(`Could not open an SSH tunnel to 127.0.0.1:${remotePort} on ${target} (ssh said: ${stderr.trim() || "nothing"}). The server's sshd must allow TCP forwarding (AllowTcpForwarding yes, the default) for the deploy user.`);
+		this.target = target;
+		this.remotePort = remotePort;
+		this.stderr = stderr;
+		this.name = "ComposeTunnelFailed";
+	}
+};
+/**
+* The stage's server: its login from `deploy.compose.server.<stage>`, its
+* host from there or the stage's `GKM_SERVER_IPV4`. Undefined for the local
+* stage, which runs on this machine.
+*
+* @throws {ComposeServerMissing} for a deployed stage with no login or host
+*/
+function composeServer(options) {
+	const { stage } = options;
+	if (options.local) return void 0;
+	const config = options.config?.[stage];
+	if (!config) throw new ComposeServerMissing(stage, "config");
+	const host = config.host ?? options.custom?.["GKM_SERVER_IPV4"]?.trim();
+	if (!host) throw new ComposeServerMissing(stage, "host");
+	return {
+		user: config.user,
+		host,
+		port: config.port ?? 22
+	};
+}
+/** `user@host`, as a person types it after `ssh`. */
+function sshTarget(server) {
+	return `${server.user}@${server.host}`;
+}
+/** The server's Docker engine, as `DOCKER_HOST` names it. */
+function dockerHost(server) {
+	const host = server.host.includes(":") ? `[${server.host}]` : server.host;
+	return `ssh://${server.user}@${host}${server.port === 22 ? "" : `:${server.port}`}`;
+}
+/** The arguments every `ssh` gkm runs starts with: no prompt, ever. */
+function sshArgs(server) {
+	return [
+		"-o",
+		"BatchMode=yes",
+		"-o",
+		"ConnectTimeout=20",
+		"-p",
+		String(server.port),
+		sshTarget(server)
+	];
+}
+async function freeLocalPort() {
+	const server = createServer();
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", resolve);
+	});
+	const address = server.address();
+	await new Promise((resolve) => server.close(resolve));
+	if (!address || typeof address === "string") return 0;
+	return address.port;
+}
+function connects(port) {
+	return new Promise((resolve) => {
+		const socket = createConnection({
+			host: "127.0.0.1",
+			port
+		});
+		socket.once("connect", () => {
+			socket.destroy();
+			resolve(true);
+		});
+		socket.once("error", () => resolve(false));
+	});
+}
+/** The real one: the system's `ssh`, with the user's keys and known hosts. */
+const sshAccess = {
+	check(server) {
+		return new Promise((resolve, reject) => {
+			const child = spawn("ssh", [
+				...sshArgs(server),
+				"docker",
+				"version",
+				"--format",
+				"{{.Server.Version}}"
+			], { stdio: [
+				"ignore",
+				"ignore",
+				"pipe"
+			] });
+			let stderr = "";
+			child.stderr.on("data", (chunk) => {
+				stderr += chunk.toString();
+			});
+			child.on("error", (error) => reject(new ComposeServerUnreachable(sshTarget(server), error.message)));
+			child.on("close", (code) => code === 0 ? resolve() : reject(new ComposeServerUnreachable(sshTarget(server), stderr)));
+		});
+	},
+	async tunnel(server, remotePort) {
+		const port = await freeLocalPort();
+		const child = spawn("ssh", [
+			"-N",
+			"-o",
+			"ExitOnForwardFailure=yes",
+			"-o",
+			"ControlPath=none",
+			"-L",
+			`127.0.0.1:${port}:127.0.0.1:${remotePort}`,
+			...sshArgs(server)
+		], { stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		] });
+		let stderr = "";
+		let exited = false;
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.on("exit", () => {
+			exited = true;
+		});
+		child.on("error", (error) => {
+			exited = true;
+			stderr += error.message;
+		});
+		const close = async () => {
+			if (exited) return;
+			const gone = new Promise((resolve) => child.once("exit", resolve));
+			child.kill("SIGTERM");
+			await gone;
+		};
+		for (let attempt = 0; attempt < 150; attempt++) {
+			if (exited) break;
+			if (await connects(port)) return {
+				port,
+				close
+			};
+			await new Promise((resolve) => setTimeout(resolve, 200));
+		}
+		await close();
+		throw new ComposeTunnelFailed(sshTarget(server), remotePort, stderr);
+	}
+};
+//#endregion
+//#region src/compose/caddyfile.ts
+/**
+* The stack's own edge, rendered for Caddy: one site block per route.
+*
+* Deployed, each host is the stage's real domain and Caddy gets it a
+* certificate from Let's Encrypt on first request — the same automatic HTTPS
+* it does anywhere, with nothing to configure but the name — or serves the
+* stage's own certificate (`deploy.compose.tls`). Locally the hosts are
+* `*.localhost` and the certificates come from Caddy's own CA, as the `gkm
+* dev` edge does, so a local stack is `https://` like a deployed one.
+*
+* Pure: the routes are data (`routes.ts`), and rendering them is one string.
+*/
+/** Where Caddy reads a stage's own certificate, inside its container. */
+const CADDY_TLS_DIR = "/etc/caddy/tls";
+/** An upstream on the stack's own network: its service name. */
+function address({ service, port }) {
+	return `${service}:${port}`;
+}
+/** The Caddyfile for a stack's edge. */
+function edgeCaddyfile(routes, options) {
+	const { tls } = options;
+	const global = tls.kind === "internal" ? `{
+	# No ACME and no public DNS: the CA is Caddy's own and the names resolve
+	# to this machine.
+	local_certs
+	auto_https disable_redirects
+}` : options.email ? `{
+	email ${options.email}
+}` : "";
+	const certificate = tls.kind === "internal" ? `
+	tls internal
+` : tls.kind === "files" ? `
+	tls ${tls.certFile} ${tls.keyFile}
+` : "";
+	const blocks = routes.map(({ host, upstreams, prefix, allow, streaming }) => `https://${host} {${certificate}
+	# gkm's own header, which only a service of this stack may send: the auth
+	# server rate-limits by the client address it carries.
+	request_header -${CLIENT_IP_HEADER}
+${allow ? `
+	# Only these addresses — the peer Caddy sees, never a header a client
+	# could set. Everything else is refused before it reaches the upstream.
+	@denied not remote_ip ${allow.join(" ")}
+	respond @denied 403
+` : ""}${prefix ? `
+	# A bucket, served at a host of its own: the bucket is a prefix on MinIO,
+	# which routes and signs on the Host header — so it is sent the upstream's.
+	reverse_proxy ${upstreams.map(address).join(" ")} {
+		rewrite ${prefix}{uri}
+		header_up Host {upstream_hostport}
+	}` : `
+	# Host and X-Forwarded-* are passed through as Caddy does by default, so
+	# an app builds redirects, cookies and links on the address a caller used.
+	reverse_proxy ${upstreams.map(address).join(" ")}${streaming ? ` {
+		# Never buffer: a streamed response — server-sent events, a Next.js
+		# RSC payload — reaches the client as each chunk is written.
+		flush_interval -1
+	}` : ""}`}
+}`);
+	return `${HEADER}${global ? `${global}\n\n` : ""}${blocks.join("\n\n")}\n`;
+}
+const HEADER = `# Generated by gkm compose from the construct manifest — do not edit.
+#
+# One host per API and site, each in front of its own container, one per
+# file server in front of the stack's MinIO, and — when its logs are served
+# publicly — one for OpenObserve, to the addresses it allows.
+`;
+//#endregion
+//#region src/compose/images.ts
+/**
+* Which image each app runs — and, for a tag, whether every one exists.
+*
+* A tag is a release's identity: `--tag=v1.4.0` means the images CI pushed as
+* v1.4.0, and nothing else. So a stack is never half rolled out: every app's
+* image is asked of the registry before anything is pulled or the running
+* stack is touched, and one missing image stops the whole run naming every
+* one that is missing. Nor is a missing image quietly built instead — a build
+* of whatever is checked out here is not the release the tag names.
+*/
+/**
+* The tag a site's image carries for a release.
+*
+* A site's public URLs are inlined when it is built, so one bundle serves one
+* stage: `v1.4.0-production` and `v1.4.0-staging` are two images of the same
+* commit. A backend reads its URLs at runtime, so one image serves every stage
+* and its tag is the release's alone.
+*/
+function siteTag(tag, stage) {
+	return `${tag}-${stage}`;
+}
+/** Images a tag names that the registry does not have. */
+var ImageTagNotFound = class extends GkmError {
+	tag;
+	refs;
+	constructor(tag, refs) {
+		super(`The registry has no image for ${refs.length === 1 ? "this app" : `${refs.length} apps`} at '${tag}':\n` + refs.map((ref) => `  - ${ref}`).join("\n") + `\nNothing was pulled or started. Push '${tag}' for every app from CI, pick a tag that exists, or run without --tag to build from this checkout.`);
+		this.tag = tag;
+		this.refs = refs;
+		this.name = "ImageTagNotFound";
+	}
+};
+/** The registry did not answer, or did not let this machine in. */
+var RegistryUnreachable = class extends GkmError {
+	ref;
+	detail;
+	constructor(ref, detail) {
+		super(`Could not ask the registry about ${ref}: ${detail || "no answer"}\nNothing was pulled or started. Check the registry is reachable and that this machine is logged in to it (\`docker login <registry>\`).`);
+		this.ref = ref;
+		this.detail = detail;
+		this.name = "RegistryUnreachable";
+	}
+};
+/**
+* Assert every image exists, before anything else happens.
+*
+* Asked all at once and reported all at once: a release missing two images is
+* one problem with two names, and finding the second only after fixing the
+* first is a slower way to learn the same thing.
+*
+* @throws {RegistryUnreachable} when the registry cannot say
+* @throws {ImageTagNotFound} listing every missing image
+*/
+async function assertImagesExist(docker, tag, images) {
+	const lookups = await Promise.all(images.map((image) => docker.lookup(image.ref)));
+	const unreachable = lookups.find((lookup) => lookup.status === "unreachable");
+	if (unreachable?.status === "unreachable") throw new RegistryUnreachable(unreachable.ref, unreachable.detail);
+	const missing = lookups.filter((lookup) => lookup.status === "missing").map((lookup) => lookup.ref);
+	if (missing.length > 0) throw new ImageTagNotFound(tag, missing);
+}
+/**
+* A push or a pull with no `deploy.registry` to push to or pull from.
+*
+* Without one an image is named `<namespace>/<project>-<app>:<tag>`, which
+* Docker resolves to Docker Hub — so a release would be pushed to, or pulled
+* from, somebody else's account. It is never a fallback.
+*/
+var RegistryRequired = class extends GkmError {
+	operation;
+	ref;
+	constructor(operation, ref) {
+		super(`${operation === "push" ? "Pushing" : "Pulling"} images needs a registry, and gkm.config.ts sets no deploy.registry: '${ref}' would be ${operation === "push" ? "pushed to" : "pulled from"} Docker Hub. Set deploy.registry (e.g. registry: 'ghcr.io/acme') in gkm.config.ts.` + (operation === "pull" ? " To run images built here instead, pass --build." : ""));
+		this.operation = operation;
+		this.ref = ref;
+		this.name = "RegistryRequired";
+	}
+};
+/** An image pinned to its digest: `<ref>@sha256:…`. */
+function pinnedRef(ref, digest) {
+	return `${ref.split("@")[0]}@${digest}`;
+}
+/** A digests file with no entry for an app the stack runs. */
+var ImageDigestMissing = class extends GkmError {
+	file;
+	apps;
+	constructor(file, apps) {
+		super(`${file} pins no digest for ${apps.join(", ")}. Use the file the same release's \`gkm compose --build --push --digests-file\` wrote, or run without --digests-file to pull by tag.`);
+		this.file = file;
+		this.apps = apps;
+		this.name = "ImageDigestMissing";
+	}
+};
+/** A digests file entry that is not this app's image. */
+var ImageDigestMismatch = class extends GkmError {
+	app;
+	expected;
+	found;
+	constructor(app, expected, found) {
+		super(`The digests file pins '${app}' to ${found}, but this release runs ${expected}. It was written for another registry, project, stage or tag; use the file this stage's push of this tag wrote.`);
+		this.app = app;
+		this.expected = expected;
+		this.found = found;
+		this.name = "ImageDigestMismatch";
+	}
+};
+/** A digests file that is not a JSON object of app to pinned ref. */
+var ImageDigestsInvalid = class extends GkmError {
+	file;
+	detail;
+	constructor(file, detail) {
+		super(`${file} is not a digests file (${detail}). It should be the JSON object \`gkm compose --build --push --digests-file\` writes: { "api": "<registry>/<image>:<tag>@sha256:…" }.`);
+		this.file = file;
+		this.detail = detail;
+		this.name = "ImageDigestsInvalid";
+	}
+};
+/** Parse a digests file's content, checking its shape. */
+function parseDigests(file, content) {
+	let parsed;
+	try {
+		parsed = JSON.parse(content);
+	} catch (error) {
+		throw new ImageDigestsInvalid(file, error instanceof Error ? error.message : String(error));
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new ImageDigestsInvalid(file, "not a JSON object");
+	for (const [app, value] of Object.entries(parsed)) if (typeof value !== "string" || !/@sha256:[0-9a-f]{64}$/.test(value)) throw new ImageDigestsInvalid(file, `'${app}' is not an <image>:<tag>@sha256:… ref`);
+	return parsed;
+}
+/**
+* Each image pinned to the digest the file names for it.
+*
+* @throws {ImageDigestMissing} naming every app the file has no entry for
+* @throws {ImageDigestMismatch} when an entry is another image or tag
+*/
+function pinImages(file, digests, images) {
+	const missing = images.filter((image) => !digests[image.app]).map((image) => image.app);
+	if (missing.length > 0) throw new ImageDigestMissing(file, missing);
+	return images.map((image) => {
+		const pinned = digests[image.app];
+		if (pinned.split("@")[0] !== image.ref) throw new ImageDigestMismatch(image.app, image.ref, pinned);
+		return {
+			...image,
+			ref: pinned
+		};
+	});
+}
+//#endregion
+//#region src/compose/traefik.ts
+/**
+* The server's shared edge, rendered for Traefik: what the edge itself runs
+* with, and what one stack registers with it.
+*
+* One Traefik per server owns 80 and 443, the ACME state and the redirect to
+* HTTPS. It is configured through its file provider alone: each stack writes
+* one file — its routers, services and middlewares, every name prefixed with
+* its compose project — into a directory the edge watches, and removes it
+* when it stops. There is no Docker socket: the edge never learns what runs
+* on the server except from those files.
+*
+* The edge and the stacks meet on one external Docker network. Only a
+* stack's public services join it, each under an alias prefixed with its
+* project (`<project>-api`), because the network is shared: a bare service
+* name there would be answered by every stack's `api`.
+*
+* Pure: the documents are data, and the edge's side effects are `edge.ts`'s.
+*/
+/**
+* The image, pinned: the edge is every stack's way in, so a new version is a
+* change to this line, not whatever `latest` is on the day a server starts.
+*/
+const TRAEFIK_IMAGE = "traefik:v3.7.13";
+/** The edge's compose project, one per server. */
+const EDGE_PROJECT = "gkm-edge";
+/** The external network the edge and every stack's public services share. */
+const EDGE_NETWORK = "gkm-edge";
+/** The edge's compose service. */
+const EDGE_SERVICE = "traefik";
+/** Inside the edge's container: what it watches, and where certificates are. */
+const EDGE_DYNAMIC_DIR = "/etc/gkm-edge/dynamic";
+const EDGE_CERTS_DIR = "/etc/gkm-edge/certs";
+/** The certificate resolver every deployed route without its own certificate uses. */
+const ACME_RESOLVER = "letsencrypt";
+/** The internal entrypoint the edge's health check asks; never published. */
+const PING_PORT = 8082;
+/** A stack's service, as the edge — and the stack itself — reach it. */
+function edgeAlias(project, service) {
+	return `${project}-${service}`;
+}
+/** A stack's certificate, as the edge's container reads it. */
+function edgeCertificatePaths(project) {
+	return {
+		certFile: `${EDGE_CERTS_DIR}/${project}.crt`,
+		keyFile: `${EDGE_CERTS_DIR}/${project}.key`
+	};
+}
+/**
+* The edge's static configuration: the entrypoints, the redirect, ACME, and
+* the directory it watches. No API and no dashboard — nothing about the edge
+* is reachable but the routes stacks register.
+*/
+function traefikStatic(ports) {
+	return {
+		global: {
+			checkNewVersion: false,
+			sendAnonymousUsage: false
+		},
+		entryPoints: {
+			web: {
+				address: ":80",
+				http: { redirections: { entryPoint: {
+					to: ports.https === 443 ? "websecure" : `:${ports.https}`,
+					scheme: "https",
+					permanent: true
+				} } }
+			},
+			websecure: { address: ":443" },
+			ping: { address: `:${PING_PORT}` }
+		},
+		ping: { entryPoint: "ping" },
+		providers: { file: {
+			directory: EDGE_DYNAMIC_DIR,
+			watch: true
+		} },
+		certificatesResolvers: { [ACME_RESOLVER]: { acme: {
+			storage: "/acme/acme.json",
+			httpChallenge: { entryPoint: "web" }
+		} } },
+		log: { level: "INFO" }
+	};
+}
+/** The edge's compose document. */
+function edgeCompose(options) {
+	const { ports } = options;
+	return {
+		name: EDGE_PROJECT,
+		services: { [EDGE_SERVICE]: {
+			image: TRAEFIK_IMAGE,
+			restart: "unless-stopped",
+			ports: [`${ports.https}:443`, `${ports.http}:80`],
+			configs: [{
+				source: "traefik",
+				target: "/etc/traefik/traefik.yml"
+			}],
+			volumes: [
+				`dynamic:${EDGE_DYNAMIC_DIR}`,
+				`certs:${EDGE_CERTS_DIR}`,
+				"acme:/acme"
+			],
+			labels: { "dev.geekmidas.edge.config": createHash("sha256").update(options.staticConfig).digest("hex").slice(0, 16) },
+			networks: ["edge"],
+			healthcheck: {
+				test: [
+					"CMD",
+					"traefik",
+					"healthcheck",
+					"--ping"
+				],
+				interval: "10s",
+				timeout: "5s",
+				retries: 5
+			},
+			logging: options.logging
+		} },
+		configs: { traefik: { content: options.staticConfig } },
+		volumes: {
+			acme: {},
+			dynamic: {},
+			certs: {}
+		},
+		networks: { edge: {
+			name: EDGE_NETWORK,
+			external: true
+		} }
+	};
+}
+/** A stack's dynamic configuration, as an object. */
+function traefikDynamic(routes, options) {
+	const { project, tls } = options;
+	const name = (route, suffix) => `${project}-${route.name}${suffix ? `-${suffix}` : ""}`;
+	const url = ({ service, port }) => `http://${edgeAlias(project, service)}:${port}`;
+	const routers = {};
+	const services = {};
+	const middlewares = {};
+	const strip = `${project}-strip-gkm-headers`;
+	if (routes.length > 0) middlewares[strip] = { headers: { customRequestHeaders: { [CLIENT_IP_HEADER]: "" } } };
+	for (const route of routes) {
+		const chain = [strip];
+		if (route.allow) {
+			middlewares[name(route, "allow")] = { ipAllowList: { sourceRange: [...route.allow] } };
+			chain.push(name(route, "allow"));
+		}
+		if (route.prefix) {
+			middlewares[name(route, "prefix")] = { addPrefix: { prefix: route.prefix } };
+			chain.push(name(route, "prefix"));
+		}
+		routers[name(route)] = {
+			rule: `Host(\`${route.host}\`)`,
+			entryPoints: ["websecure"],
+			service: name(route),
+			middlewares: chain,
+			tls: tls.kind === "acme" ? { certResolver: ACME_RESOLVER } : {}
+		};
+		services[name(route)] = { loadBalancer: {
+			servers: route.upstreams.map((upstream) => ({ url: url(upstream) })),
+			...route.prefix ? { passHostHeader: false } : {},
+			...route.streaming ? { responseForwarding: { flushInterval: "-1ms" } } : {},
+			...route.health ? { healthCheck: {
+				path: route.health,
+				interval: "5s",
+				timeout: "3s"
+			} } : {}
+		} };
+	}
+	return {
+		http: {
+			routers,
+			services,
+			...Object.keys(middlewares).length > 0 ? { middlewares } : {}
+		},
+		...tls.kind === "files" ? { tls: { certificates: [{
+			certFile: tls.certFile,
+			keyFile: tls.keyFile
+		}] } } : {}
+	};
+}
+/** A stack's dynamic configuration file, as written to the edge's directory. */
+function traefikDynamicFile(routes, options) {
+	return `# Generated by gkm compose for ${options.project} — do not edit.
+# The shared edge (${EDGE_PROJECT}) reads every file in this directory; this
+# one is removed by gkm compose --down.
+${yaml(traefikDynamic(routes, options))}`;
+}
+/** The edge's static configuration file. */
+function traefikStaticFile(ports) {
+	return `# Generated by gkm compose — the server's shared edge. Do not edit.
+${yaml(traefikStatic(ports))}`;
+}
+/** The edge's compose file. */
+function edgeComposeFile(options) {
+	return `# Generated by gkm compose — the server's shared edge. Do not edit.
+#
+# Started by the first stack that runs with proxy: 'traefik', and left
+# running by gkm compose --down. Stop it, once nothing uses it, with:
+#
+#   docker compose -p ${EDGE_PROJECT} down
+${yaml(edgeCompose(options))}`;
+}
+function yaml(value) {
+	return stringify(value, {
+		lineWidth: 0,
+		aliasDuplicateObjects: false
+	});
+}
+//#endregion
+//#region src/compose/stack.ts
+/**
+* The stack a workspace runs as for one stage — pure.
+*
+* Everything `gkm compose` writes is decided here, as data: the compose file,
+* the Caddyfile, one env file per backend, and the image each app runs. The
+* command around it reads the workspace, asks the registry, writes the files
+* and starts Docker; none of those decide anything, so all of it can be
+* asserted without a daemon.
+*
+* The values come from the same derivations every other target uses. The
+* plan is reconcile's `planFor`, the keys an app reads are `appEnvKeys`, and
+* every URL is `envFor`'s — asked twice, once with each app at its public
+* address and once on the compose network, because a browser and a sibling
+* service reach the same API by different names.
+*/
+/** Where a stack's files are written, relative to the workspace root. */
+function stackDir(stage) {
+	return `.gkm/compose/${stage}`;
+}
+/**
+* The compose project a stage's stack runs as.
+*
+* The deploy identity's scope, so two workspaces with one name in different
+* namespaces never share containers or volumes — and the stage, so a
+* machine can run two stages side by side.
+*/
+function composeProject(identity) {
+	return `${identity.scope}-${identity.stage}`;
+}
+/** The ports the edge is published on, and the variables that move them. */
+const EDGE_PORT_ENV = {
+	https: "GKM_COMPOSE_HTTPS_PORT",
+	http: "GKM_COMPOSE_HTTP_PORT"
+};
+/**
+* The variable that moves the local stage's OpenObserve off its loopback
+* port, 5080 — which the local stage takes from nowhere else, since it
+* ignores `deploy.telemetry`. Another stack, or another tool, may hold 5080.
+*/
+const LOGS_PORT_ENV = "GKM_COMPOSE_LOGS_PORT";
+/**
+* Containers this target does not run.
+*
+* The AWS emulator never applies: a stack is a server target, whose events
+* are pg-boss. Reconcile's Caddy fronts `gkm dev`'s host processes; the stack
+* brings its own edge.
+*
+* MinIO and Mailpit run on the local stage always, and on a deployed stage
+* only where `--allow-dev-services` allowed them and its secrets configure no
+* real bucket or mail server — see `devServices.ts`.
+*/
+const NOT_RUN = {
+	localstack: true,
+	caddy: true
+};
+/** The kinds a deployed stage takes from its secrets, or a dev service. */
+const SERVICE_KINDS = {
+	email: "email",
+	objects: "objects",
+	"file-server": "file-server"
+};
+/** The region MinIO is addressed with. It has no regions; the SDK wants one. */
+const MINIO_REGION = "us-east-1";
+/** The S3 client's credentials, read beside a bucket's URL when it has them. */
+const STORAGE_KEYS = [
+	"AWS_ACCESS_KEY_ID",
+	"AWS_SECRET_ACCESS_KEY",
+	"AWS_REGION"
+];
+/**
+* Every service's Docker logs, rotated. The json-file driver keeps a
+* container's output in one file that grows until the disk is full — on a
+* small server, in weeks. Three files of 10 MB each per container is enough
+* to see what happened and never fills anything. A project's own override
+* file that sets `logging` wins over it.
+*/
+const LOG_ROTATION = {
+	driver: "json-file",
+	options: {
+		"max-size": "10m",
+		"max-file": "3"
+	}
+};
+/**
+* The stack with Caddy's files inline: its Caddyfile and, where the stage has
+* one, its own certificate — `configs` with their `content`, which compose
+* copies into the container through the engine's API. Nothing is mounted from
+* a path, so the stack runs the same on a server's engine, over SSH, as on
+* this machine's. Their hash is a label: a changed file is a changed service,
+* which `up` recreates (compose does not, for a config's content alone).
+*/
+function withCaddyConfigs(compose, files) {
+	const caddy = compose.services.caddy;
+	if (!caddy) return compose;
+	const configs = {
+		caddyfile: { content: files.caddyfile },
+		...files.tls ? {
+			"tls-cert": { content: files.tls.cert },
+			"tls-key": { content: files.tls.key }
+		} : {}
+	};
+	const hash = createHash("sha256");
+	for (const [name, { content }] of Object.entries(configs)) hash.update(`${name}\0${content}\0`);
+	return {
+		...compose,
+		services: {
+			...compose.services,
+			caddy: {
+				...caddy,
+				configs: [{
+					source: "caddyfile",
+					target: "/etc/caddy/Caddyfile"
+				}, ...files.tls ? [{
+					source: "tls-cert",
+					target: `${CADDY_TLS_DIR}/cert.pem`
+				}, {
+					source: "tls-key",
+					target: `${CADDY_TLS_DIR}/key.pem`,
+					mode: 256
+				}] : []],
+				labels: {
+					...caddy.labels,
+					"dev.geekmidas.caddy.config": hash.digest("hex").slice(0, 16)
+				}
+			}
+		},
+		configs: {
+			...compose.configs,
+			...configs
+		}
+	};
+}
+/** The local stage's stack, without the logins `gkm dev` generates. */
+var LocalCredentialsMissing = class extends GkmError {
+	stage;
+	constructor(stage) {
+		super(`The local stage '${stage}' runs with this machine's generated logins, and none were passed. Load them with loadLocalCredentials(workspace) and pass them as localCredentials.`);
+		this.stage = stage;
+		this.name = "LocalCredentialsMissing";
+	}
+};
+/**
+* A deployed stage's container logins, derived from its seed like its role
+* passwords — so every deploy of the stage computes the same ones, and no one
+* reading the repo can.
+*/
+function derivedCredentials(project, plan, seed) {
+	const derive = (purpose) => localRolePassword(project, plan, purpose, seed);
+	return {
+		postgres: {
+			user: postgresSuperuser(project),
+			password: derive("master")
+		},
+		minio: {
+			user: `${project}-minio`,
+			password: derive("minio")
+		},
+		rabbitmq: {
+			user: LOCAL_RABBITMQ_USER,
+			password: derive("rabbitmq")
+		},
+		redis: { password: derive("redis") },
+		cacheToken: derive("cache-token"),
+		emulator: {
+			accessKeyId: EMULATOR_ACCESS_KEY_ID,
+			secretAccessKey: derive("emulator")
+		},
+		logs: {
+			email: `admin@${project}`,
+			password: derive("logs")
+		}
+	};
+}
+/** A value only the stage's secrets can hold, and they do not. */
+var StageSecretMissing = class extends GkmError {
+	app;
+	key;
+	stage;
+	constructor(app, key, stage) {
+		super(`'${app}' reads ${key}, and the stage '${stage}' has none. Nothing in the stack can derive it; set it in the stage's secrets: gkm secrets:set ${key} '…' --stage ${stage}`);
+		this.app = app;
+		this.key = key;
+		this.stage = stage;
+		this.name = "StageSecretMissing";
+	}
+};
+/** A deployed stage's secrets with no seed to derive its passwords from. */
+var StageSeedMissing = class extends GkmError {
+	stage;
+	constructor(stage) {
+		super(`The stage '${stage}' has no seed in its secrets, and a deployed stage's database passwords are derived from it. Run gkm compose --stage ${stage} without --dry-run once, or gkm deploy, to generate it.`);
+		this.stage = stage;
+		this.name = "StageSeedMissing";
+	}
+};
+/** A workspace with no API and no site to run. */
+var NothingToCompose = class extends GkmError {
+	root;
+	constructor(root) {
+		super(`${root} declares no RestApi, no site and no Worker with work to do, so a stack would run nothing. Mobile apps ship through their own toolchain.`);
+		this.root = root;
+		this.name = "NothingToCompose";
+	}
+};
+/** A value that cannot be written to an env file a line at a time. */
+var EnvValueMultiline = class extends GkmError {
+	app;
+	key;
+	constructor(app, key) {
+		super(`${key} for '${app}' spans more than one line, and an env file holds one value per line. Store it on one line — base64, or JSON — and decode it where it is read.`);
+		this.app = app;
+		this.key = key;
+		this.name = "EnvValueMultiline";
+	}
+};
+/** The services a stack's apps wait on and the edge waits on in turn. */
+const HEALTHY = { condition: "service_healthy" };
+/**
+* An app's health check: its own server, asked on 127.0.0.1 — not
+* `localhost`, which resolves to `::1` first in an Alpine container while a
+* server may listen on IPv4 alone.
+*/
+function probe(port, path) {
+	return {
+		test: [
+			"CMD",
+			"wget",
+			"-q",
+			"-O",
+			"/dev/null",
+			`http://127.0.0.1:${port}${path}`
+		],
+		interval: "5s",
+		timeout: "3s",
+		retries: 20,
+		start_period: "10s"
+	};
+}
+/**
+* What a stage's stack provisions: reconcile's plan, with a server target's
+* backends whatever `deploy.default` says — the stack is one machine running
+* containers, so events are pg-boss beside the declared database, and every
+* cache, one declared from that database included, is in the stack's own
+* Redis.
+*/
+function stackPlan(workspace, manifest, stage) {
+	return planFor(manifest, stage, provisionOrder(manifest), {
+		localStage: workspace.stages.local,
+		events: DEFAULT_EVENTS.server,
+		cache: STACK_CACHE,
+		edge: false
+	});
+}
+/** The stack for one stage. */
+function composeStack(input) {
+	const { workspace, manifest, stage, identity } = input;
+	const local = stage === workspace.stages.local;
+	const project = composeProject(identity);
+	const custom = input.secrets?.custom ?? {};
+	const https = input.ports?.https ?? 443;
+	const http = input.ports?.http ?? 80;
+	const proxy = proxyFor(workspace.deploy?.compose, stage, local);
+	const certificate = local ? void 0 : certificateFor(workspace.deploy?.compose, stage, workspace.root);
+	const plan = stackPlan(workspace, manifest, stage);
+	const byId = new Map(plan.resources.map((r) => [r.id, r]));
+	if (local && !input.localCredentials) throw new LocalCredentialsMissing(stage);
+	const seed = local ? input.localCredentials.seed : input.secrets?.seed;
+	if (!seed) throw new StageSeedMissing(stage);
+	const containers = local ? input.localCredentials : derivedCredentials(workspace.name, plan, seed);
+	const credential = {
+		containers: {
+			...containers,
+			minio: {
+				user: custom.AWS_ACCESS_KEY_ID ?? containers.minio.user,
+				password: custom.AWS_SECRET_ACCESS_KEY ?? containers.minio.password
+			}
+		},
+		seed
+	};
+	const apps = stackApps(workspace, manifest, plan, {
+		local,
+		stage,
+		https,
+		identity,
+		images: input.images
+	});
+	const workers = stackWorkers(workerUnits(workspace, manifest, input.background ?? {}), {
+		stage,
+		identity,
+		images: input.images
+	});
+	if (apps.length === 0 && workers.length === 0) throw new NothingToCompose(workspace.root);
+	const owners = /* @__PURE__ */ new Map();
+	for (const resource of plan.resources) {
+		owners.set(resource.envKey, resource);
+		if (resource.kind === "email") {
+			owners.set(provideKey(resource.id, "from"), resource);
+			owners.set(provideKey(resource.id, "inboxUrl"), resource);
+		}
+		if (resource.kind === "external-api") owners.set(provideKey(resource.id, "credentials"), resource);
+	}
+	const domain = workspace.domains?.[stage];
+	const telemetry = resolveStageTelemetry({
+		...workspace.deploy?.telemetry ? { telemetry: workspace.deploy.telemetry } : {},
+		stage,
+		local,
+		target: "compose",
+		runtime: "server",
+		selfHosted: true,
+		used: usesTelemetry(manifest)
+	});
+	const logsBase = telemetry?.provider === "self-hosted" ? stackLogs({
+		config: local && input.ports?.logs ? {
+			...telemetry.selfHosted,
+			port: input.ports.logs
+		} : telemetry.selfHosted,
+		stage,
+		local,
+		project: workspace.name,
+		...domain ? { domain } : {},
+		custom,
+		https,
+		...local ? { localLogin: input.localCredentials.logs } : {}
+	}) : void 0;
+	const services = local ? {
+		missing: [],
+		minio: plan.resources.filter((r) => r.kind === "objects").map((r) => r.id),
+		mailpit: plan.resources.filter((r) => r.kind === "email").map((r) => r.id)
+	} : externalServices({
+		stage,
+		declarations: stageServiceDeclarations({
+			manifest,
+			...input.runnables ? { runnables: input.runnables } : {}
+		}),
+		supplied: custom,
+		allow: input.allowDevServices === true,
+		...domain ? { domain } : {},
+		providers: stageProviderNotes(workspace, stage)
+	});
+	const redis = stackRedis({
+		plan,
+		stage,
+		local,
+		custom,
+		...local ? { localPassword: input.localCredentials.redis.password } : {}
+	});
+	const infra = [...plan.containers.filter((c) => !NOT_RUN[c]).filter((c) => c !== LOGS_SERVICE).filter((c) => c !== "minio" || services.minio.length > 0).filter((c) => c !== "mailpit" || services.mailpit.length > 0).filter((c) => c !== "redis" || redis !== void 0), ...logsBase ? [LOGS_SERVICE] : []].sort();
+	const storage = infra.includes("minio") ? (() => {
+		const buckets = services.minio.map((id) => byId.get(id)?.name).filter((name) => Boolean(name)).sort();
+		return {
+			...credential.containers.minio,
+			buckets,
+			policies: bucketPolicies(plan).filter((p) => buckets.includes(p.bucket))
+		};
+	})() : void 0;
+	const fileServers = /* @__PURE__ */ new Map();
+	if (storage) for (const resource of plan.resources) {
+		if (resource.kind !== "file-server" || !resource.of) continue;
+		if (!services.minio.includes(resource.of)) continue;
+		if (custom[resource.envKey] !== void 0) continue;
+		const bucket = byId.get(resource.of);
+		if (!bucket) continue;
+		let host;
+		if (local) host = hostFor(resource, workspace.name);
+		else {
+			if (!domain) throw new NoDomainForStage(stage);
+			host = `${resource.subdomain ?? appKey(resource.id)}.${domain}`;
+		}
+		fileServers.set(resource.id, {
+			url: `https://${host}${local && https !== 443 ? `:${https}` : ""}`,
+			route: {
+				name: `files-${appKey(resource.id)}`,
+				host,
+				upstreams: [{
+					service: "minio",
+					port: 9e3
+				}],
+				streaming: false,
+				prefix: `/${bucket.name}`
+			}
+		});
+	}
+	const edgeServices = new Set(proxy === "traefik" ? [
+		...apps.map((app) => app.name),
+		...fileServers.size > 0 ? ["minio"] : [],
+		...logsBase?.host && logsBase.public ? [LOGS_SERVICE] : []
+	] : []);
+	const hostOf = (service) => edgeServices.has(service) ? edgeAlias(project, service) : service;
+	const logs = logsBase && {
+		...logsBase,
+		appEnv: {
+			...logsBase.appEnv,
+			OTEL_EXPORTER_OTLP_ENDPOINT: logsBase.appEnv.OTEL_EXPORTER_OTLP_ENDPOINT.replace(`//openobserve:`, `//${hostOf("openobserve")}:`)
+		}
+	};
+	const derivation = {
+		project: workspace.name,
+		credentials: credential.containers,
+		seed: credential.seed,
+		...!local && domain ? { mailFrom: `noreply@${domain}` } : {}
+	};
+	const outside = networkEnv(plan, {
+		...derivation,
+		addresses: Object.fromEntries(apps.map((app) => [app.id, app.url]))
+	}, hostOf);
+	const inside = networkEnv(plan, {
+		...derivation,
+		addresses: Object.fromEntries(apps.map((app) => [app.id, `http://${hostOf(app.name)}:${app.port}`]))
+	}, hostOf);
+	const surfaceUrls = new Map(plan.resources.filter((r) => r.kind === "rest-api" || r.kind === "site").map((r) => [r.envKey, r.id]));
+	const appById = new Map(apps.map((app) => [app.id, app]));
+	/**
+	* What a key resolves to for one app, from the stage's secrets where only
+	* they can hold it, and the derivations otherwise.
+	*/
+	const valueFor = (app, key, owner) => {
+		if (isReservedStageKey(key)) return void 0;
+		if (owner && SERVICE_KINDS[owner.kind]) {
+			if (custom[key] !== void 0) return custom[key];
+			if (owner.kind === "file-server") return fileServers.get(owner.id)?.url;
+			return outside[key];
+		}
+		if (owner && suppliedOnly(owner.kind, owner.id, key, local)) {
+			const value = custom[key];
+			if (value === void 0) throw new StageSecretMissing(app.name, key, stage);
+			return value;
+		}
+		if (custom[key] !== void 0) return custom[key];
+		if (owner?.kind === "cache") return redis?.urls[key];
+		const surface = surfaceUrls.get(key);
+		if (app.kind === "rest-api" && surface && surface !== app.id) return inside[key];
+		return outside[key];
+	};
+	const telemetryValues = logs ? telemetryEnv({
+		endpoint: logs.appEnv.OTEL_EXPORTER_OTLP_ENDPOINT,
+		headers: logs.appEnv.OTEL_EXPORTER_OTLP_HEADERS
+	}, telemetry?.sampleRate ?? 1) : telemetry?.provider === "otlp" ? otlpTelemetryEnv(telemetry) : void 0;
+	/** Each key one backend process reads, resolved for this stage. */
+	const valuesFor = (app, keys) => {
+		const values = {};
+		for (const key of [...keys].sort()) {
+			if (isTelemetryKey(key)) continue;
+			const owner = owners.get(key) ?? storageOwner(key, plan);
+			if (!local && owner?.kind === "email" && key.endsWith("_INBOX_URL")) continue;
+			if (STORAGE_KEYS.includes(key)) {
+				const value = custom[key] ?? storageValue(key, storage);
+				if (value !== void 0) values[key] = value;
+				continue;
+			}
+			const value = valueFor(app, key, owner);
+			if (value !== void 0) values[key] = value;
+		}
+		return values;
+	};
+	for (const app of apps) {
+		if (app.kind === "site") {
+			const site = manifest[app.id];
+			if (site?.kind !== "site") continue;
+			const args = {};
+			for (const [key, source] of Object.entries(publicEnvFor(site, manifest))) {
+				const value = valueFor(app, source, owners.get(source));
+				if (value !== void 0) args[key] = value;
+			}
+			if (app.build && Object.keys(args).length > 0) app.build.args = args;
+			continue;
+		}
+		if (input.buildOnly) continue;
+		const keys = appEnvKeys(manifest, app.name, input.runnables) ?? /* @__PURE__ */ new Set();
+		const values = valuesFor(app, keys);
+		const trusted = provideKey(app.id, "trustedOrigins");
+		if (keys.has(trusted)) {
+			const internal = (byId.get(app.id)?.callers ?? []).map((caller) => appById.get(caller)).filter((caller) => caller?.kind === "rest-api").map((caller) => `http://${hostOf(caller.name)}:${caller.port}`);
+			const origins = [...(values[trusted] ?? "").split(",").filter(Boolean), ...internal];
+			values[trusted] = [...new Set(origins)].join(",");
+		}
+		app.env = {
+			...scopeTelemetryEnv(values, {
+				uses: telemetryOf(manifest, app.id) !== void 0,
+				serviceName: app.name,
+				...telemetryValues ? { telemetry: telemetryValues } : {}
+			}),
+			NODE_ENV: "production",
+			PORT: String(app.port),
+			STAGE: stage
+		};
+		for (const [key, value] of Object.entries(app.env)) if (/[\r\n]/.test(value)) throw new EnvValueMultiline(app.name, key);
+	}
+	for (const worker of input.buildOnly ? [] : workers) {
+		const keys = workerEnvKeys(manifest, worker.id, input.runnables) ?? /* @__PURE__ */ new Set();
+		worker.env = {
+			...scopeTelemetryEnv(valuesFor({
+				name: worker.name,
+				id: worker.id,
+				kind: "rest-api"
+			}, keys), {
+				uses: telemetryOf(manifest, worker.id) !== void 0,
+				serviceName: worker.name,
+				...telemetryValues ? { telemetry: telemetryValues } : {}
+			}),
+			NODE_ENV: "production",
+			PORT: String(worker.port),
+			STAGE: stage
+		};
+		for (const [key, value] of Object.entries(worker.env)) if (/[\r\n]/.test(value)) throw new EnvValueMultiline(worker.name, key);
+	}
+	const deployedTls = certificate ? {
+		kind: "files",
+		...proxy === "caddy" ? {
+			certFile: `${CADDY_TLS_DIR}/cert.pem`,
+			keyFile: `${CADDY_TLS_DIR}/key.pem`
+		} : edgeCertificatePaths(project)
+	} : { kind: "acme" };
+	const tls = local ? { kind: "internal" } : deployedTls;
+	const backupsChoice = input.buildOnly ? void 0 : stageBackups(workspace, manifest, stage);
+	const backups = backupsChoice?.mode === "on" && infra.includes("postgres") ? stackBackups({
+		workspace,
+		stage,
+		project,
+		plan,
+		backups: backupsChoice.backups,
+		custom,
+		seed,
+		superuser: credential.containers.postgres,
+		...telemetryValues ? { telemetry: telemetryValues } : {}
+	}) : void 0;
+	const layout = input.layout ?? defaultLayout(workspace.root);
+	const compose = stackFile({
+		project,
+		plan,
+		infra,
+		apps,
+		workers,
+		credentials: credential.containers,
+		...storage ? { storage } : {},
+		...logs ? { logs } : {},
+		...redis ? { redis } : {},
+		...backups ? { backups } : {},
+		https,
+		http,
+		composeDir: join(workspace.root, stackDir(stage)),
+		buildRoot: layout.buildRoot,
+		workspaceRoot: workspace.root,
+		envFiles: !input.buildOnly,
+		proxy,
+		edge: new Map([...edgeServices].map((service) => [service, hostOf(service)]))
+	});
+	const routes = [
+		...apps.map((app) => ({
+			name: app.name,
+			host: app.host,
+			upstreams: [{
+				service: app.name,
+				port: app.port
+			}],
+			streaming: true,
+			health: app.kind === "site" ? "/" : "/health"
+		})),
+		...[...fileServers.values()].map(({ route }) => route),
+		...logs?.host && logs.public ? [{
+			name: LOGS_SERVICE,
+			host: logs.host,
+			upstreams: [{
+				service: LOGS_SERVICE,
+				port: LOGS_PORT
+			}],
+			streaming: true,
+			allow: logs.public.allow
+		}] : []
+	];
+	const dockerfiles = {};
+	for (const app of apps) {
+		if (!app.build) continue;
+		dockerfiles[app.build.dockerfile] = appDockerfile(app.name, workspace.apps[app.name], {
+			layout,
+			workspaceRoot: workspace.root,
+			apps: workspace.apps,
+			manifest,
+			cache: STACK_CACHE,
+			workspace,
+			stage
+		});
+	}
+	for (const worker of workers) {
+		if (!worker.build) continue;
+		dockerfiles[worker.build.dockerfile] = workerDockerfile({
+			id: worker.id,
+			name: worker.name,
+			app: worker.host
+		}, workspace.apps[worker.host], {
+			layout,
+			workspaceRoot: workspace.root,
+			cache: STACK_CACHE
+		});
+	}
+	return {
+		project,
+		stage,
+		local,
+		apps,
+		workers,
+		infra,
+		compose,
+		proxy,
+		routes,
+		...proxy === "caddy" ? { caddyfile: edgeCaddyfile(routes, { tls }) } : { traefik: traefikDynamicFile(routes, {
+			project,
+			tls: deployedTls
+		}) },
+		...certificate ? { tls: certificate } : {},
+		dockerfiles,
+		plan,
+		credential,
+		...storage ? { storage } : {},
+		devServices: local ? [] : devServicesUsed(services),
+		...logs ? { logs } : {},
+		...telemetry ? { telemetry } : {},
+		...redis ? { redis } : {},
+		...backups ? { backups } : {}
+	};
+}
+/** The stack's MinIO's value for one of the S3 client's keys. */
+function storageValue(key, storage) {
+	if (!storage) return void 0;
+	if (key === "AWS_ACCESS_KEY_ID") return storage.user;
+	if (key === "AWS_SECRET_ACCESS_KEY") return storage.password;
+	if (key === "AWS_REGION") return MINIO_REGION;
+}
+/** Which bucket an S3 credential key belongs to — the first one declared. */
+function storageOwner(key, plan) {
+	if (!STORAGE_KEYS.includes(key)) return void 0;
+	return plan.resources.find((r) => r.kind === "objects");
+}
+/** The apps a stack runs: every API and every site, at its stage address. */
+function stackApps(workspace, manifest, plan, options) {
+	const apps = [];
+	const resources = new Map(plan.resources.map((r) => [r.id, r]));
+	for (const [id, declaration] of Object.entries(manifest)) {
+		if (declaration.kind !== "rest-api" && declaration.kind !== "site") continue;
+		const name = appKey(id);
+		const app = workspace.apps[name];
+		const resource = resources.get(id);
+		if (!app || !resource || !app.port) continue;
+		const host = hostOf(name, app, workspace, resource, options);
+		const tag = declaration.kind === "site" ? siteTag(options.images.tag, options.stage) : options.images.tag;
+		const ref = validateImageRef(imageRef(options.identity, name, options.images.registry, tag));
+		apps.push({
+			app: name,
+			name,
+			id,
+			kind: declaration.kind,
+			path: app.path,
+			port: app.port,
+			host,
+			url: `https://${host}${options.local && options.https !== 443 ? `:${options.https}` : ""}`,
+			ref,
+			tag,
+			...options.images.mode === "build" ? { build: { dockerfile: `${stackDir(options.stage)}/Dockerfile.${name}` } } : {}
+		});
+	}
+	return apps.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Each worker's image, and where it is built from. */
+function stackWorkers(units, options) {
+	return units.map((unit) => ({
+		app: unit.name,
+		name: unit.name,
+		id: unit.id,
+		host: unit.app,
+		port: WORKER_PORT,
+		ref: validateImageRef(imageRef(options.identity, unit.name, options.images.registry, options.images.tag)),
+		tag: options.images.tag,
+		...options.images.mode === "build" ? { build: { dockerfile: `${stackDir(options.stage)}/Dockerfile.${unit.name}` } } : {}
+	}));
+}
+/**
+* The host an app answers on for a stage: the `gkm dev` edge's
+* `*.localhost` names for the local stage, and the stage's domain — by the
+* same rule a deploy follows — for any other.
+*/
+function hostOf(name, app, workspace, resource, options) {
+	if (options.local) return hostFor(resource, workspace.name);
+	return resolveHost(name, app, options.stage, workspace.domains, isMainFrontendApp(name, app, workspace.apps));
+}
+/** The compose document: the infrastructure, the apps, and the edge. */
+function stackFile(options) {
+	const { project, plan, apps } = options;
+	const infra = options.infra.filter((name) => name !== LOGS_SERVICE);
+	const derived = composeFor({
+		...plan,
+		containers: [...infra]
+	}, {
+		project,
+		ports: Object.fromEntries(portKeys(infra, plan.fakes).map((key) => [key, 0])),
+		credentials: options.credentials
+	});
+	const services = {};
+	const volumes = {
+		...derived.volumes,
+		...options.proxy === "caddy" ? {
+			"caddy-data": {},
+			"caddy-config": {}
+		} : {},
+		...options.logs ? { "openobserve-data": {} } : {}
+	};
+	for (const name of infra) {
+		const { ports: _ports, depends_on, profiles: _profiles, ...service } = derived.services[name];
+		services[name] = {
+			...service,
+			...depends_on?.length ? { depends_on: Object.fromEntries(depends_on.map((dep) => [dep, HEALTHY])) } : {}
+		};
+	}
+	const postgres = services.postgres;
+	if (postgres) postgres.ports = ["127.0.0.1::5432"];
+	const minio = services.minio;
+	if (minio && options.storage) {
+		minio.environment = {
+			...minio.environment,
+			MINIO_ROOT_USER: options.storage.user,
+			MINIO_ROOT_PASSWORD: options.storage.password
+		};
+		minio.ports = ["127.0.0.1::9000"];
+	}
+	if (services["redis"] && options.redis) services[REDIS_SERVICE] = redisService(options.redis);
+	if (options.logs) services[LOGS_SERVICE] = logsService(options.logs);
+	if (options.backups) services[BACKUPS_SERVICE] = backupsService(options.backups, options.envFiles);
+	for (const app of apps) services[app.name] = {
+		image: app.ref,
+		...app.build ? { build: {
+			...composeBuildPaths({
+				composeDir: options.composeDir,
+				buildRoot: options.buildRoot,
+				workspaceRoot: options.workspaceRoot,
+				dockerfile: app.build.dockerfile
+			}),
+			...app.build.args ? { args: app.build.args } : {}
+		} } : {},
+		restart: "unless-stopped",
+		...app.kind === "rest-api" ? {
+			env_file: [{
+				path: `./${app.name}.env`,
+				format: "raw"
+			}],
+			...infra.length ? { depends_on: Object.fromEntries(infra.map((name) => [name, HEALTHY])) } : {}
+		} : {},
+		healthcheck: probe(app.port, app.kind === "site" ? "/" : "/health")
+	};
+	for (const worker of options.workers) services[worker.name] = {
+		image: worker.ref,
+		...worker.build ? { build: composeBuildPaths({
+			composeDir: options.composeDir,
+			buildRoot: options.buildRoot,
+			workspaceRoot: options.workspaceRoot,
+			dockerfile: worker.build.dockerfile
+		}) } : {},
+		restart: "unless-stopped",
+		env_file: [{
+			path: `./${worker.name}.env`,
+			format: "raw"
+		}],
+		...infra.length ? { depends_on: Object.fromEntries(infra.map((name) => [name, HEALTHY])) } : {},
+		healthcheck: probe(worker.port, "/health")
+	};
+	if (options.proxy === "caddy") services.caddy = {
+		image: DEFAULT_IMAGES.caddy,
+		restart: "unless-stopped",
+		ports: [`${options.https}:443`, `${options.http}:80`],
+		volumes: ["caddy-data:/data", "caddy-config:/config"],
+		depends_on: Object.fromEntries(apps.map((app) => [app.name, HEALTHY])),
+		healthcheck: {
+			test: [
+				"CMD",
+				"caddy",
+				"version"
+			],
+			interval: "10s",
+			timeout: "5s",
+			retries: 5
+		}
+	};
+	for (const [service, alias] of options.edge) {
+		const definition = services[service];
+		if (!definition) continue;
+		definition.networks = {
+			default: { aliases: [alias] },
+			edge: { aliases: [alias] }
+		};
+	}
+	for (const service of Object.values(services)) {
+		if (!options.envFiles) delete service.env_file;
+		service.logging = {
+			driver: LOG_ROTATION.driver,
+			options: { ...LOG_ROTATION.options }
+		};
+	}
+	return {
+		name: project,
+		services,
+		volumes,
+		...options.edge.size > 0 ? { networks: { edge: {
+			name: EDGE_NETWORK,
+			external: true
+		} } } : {}
+	};
+}
+/**
+* A build without a layout: the workspace is the build root, with pnpm.
+* What a caller that never looked at the filesystem gets.
+*/
+function defaultLayout(root) {
+	return {
+		buildRoot: root,
+		gkmRoot: ".",
+		tools: {
+			packageManager: "pnpm",
+			turboVersion: TURBO_VERSION,
+			monorepo: true
+		},
+		gkmPaths: ["gkm.config.*"]
+	};
+}
+/** Render an app's env file: one `KEY=value` per line, read raw by compose. */
+function envFile(env) {
+	return `${Object.entries(env).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => `${key}=${value}`).join("\n")}\n`;
+}
+//#endregion
+//#region src/compose/edge.ts
+/**
+* The server's shared Traefik edge, in Docker: started when a stack needs it,
+* and each stack's routes written to — and removed from — the directory it
+* watches.
+*
+* Everything goes through the server's Docker engine, never its filesystem:
+* the edge's static configuration is handed to it inline, and the directories
+* it watches are volumes each stack writes into with `docker exec`. So the
+* deploy runs anywhere that reaches the engine — a CI runner over SSH — and
+* nothing it writes depends on a path on that machine.
+*
+*   gkm-edge (compose project)
+*     traefik.yml                   its static configuration (inline config)
+*     dynamic/<project>.yml         one per stack: routers, services, middlewares
+*     certs/<project>.crt|.key      a stack's own certificate, where it has one
+*/
+/** The edge's compose project, as docker is asked about it. */
+function edgeRef(file, options = {}) {
+	return {
+		project: EDGE_PROJECT,
+		file,
+		cwd: dirname(file),
+		...options
+	};
+}
+/** Writing to or removing from the edge's volumes failed. */
+var EdgeWriteFailed = class extends GkmError {
+	path;
+	output;
+	constructor(path, output) {
+		super(`Could not write ${path} in the shared edge (${EDGE_PROJECT}): ${output.trim() || "it is not running"}. Check it with \`docker compose -p ${EDGE_PROJECT} ps\` on the server, and run gkm compose again.`);
+		this.path = path;
+		this.output = output;
+		this.name = "EdgeWriteFailed";
+	}
+};
+/**
+* Something other than the proxy a stack is set to holds the edge's ports.
+*
+* With `proxy: 'traefik'`, the stack's own Caddy — still running from before
+* the switch — or any other container; with `proxy: 'caddy'`, the shared
+* edge, or another stack's Caddy. Refused before anything is started, so the
+* stack is never left half on one proxy and half on the other.
+*/
+var ComposeProxyClash = class extends GkmError {
+	project;
+	proxy;
+	port;
+	holder;
+	constructor(project, proxy, port, holder) {
+		const by = holder.project ? `${holder.container} (compose project ${holder.project})` : holder.container;
+		const fix = proxy === "traefik" ? holder.project === project && holder.service === "caddy" ? `That is this stack's own Caddy, from before it was switched to proxy: 'traefik'. Move it once: stop it (docker compose -p ${project} stop caddy), then run gkm compose again — the shared edge takes 80/443 and the stack registers with it.` : `The shared edge needs ports 80 and 443. Stop ${holder.container}${holder.project ? ` (docker compose -p ${holder.project} down, or its own gkm compose --down)` : ""}, or move the edge with GKM_COMPOSE_HTTPS_PORT/GKM_COMPOSE_HTTP_PORT.` : holder.project === "gkm-edge" ? `That is the server's shared Traefik edge, which other stacks register with. Set deploy.compose.proxy to 'traefik' for this stage so the stack registers with it too, or stop the edge once nothing uses it (docker compose -p ${EDGE_PROJECT} down).` : `Stop ${holder.container}, or publish this stack's Caddy elsewhere with GKM_COMPOSE_HTTPS_PORT/GKM_COMPOSE_HTTP_PORT.`;
+		super(`${project} is set to proxy: '${proxy}', and port ${port} is held by ${by}. ${fix}`);
+		this.project = project;
+		this.proxy = proxy;
+		this.port = port;
+		this.holder = holder;
+		this.name = "ComposeProxyClash";
+	}
+};
+/**
+* Refuse a stack whose edge ports are held by anything but its own proxy:
+* the shared edge for `'traefik'`, the stack's own Caddy for `'caddy'`.
+*/
+async function assertEdgePorts(docker, options) {
+	const { project, proxy, ports } = options;
+	for (const port of [ports.https, ports.http]) for (const holder of await docker.publishers(options.engine, port)) if (!(proxy === "traefik" ? holder.project === "gkm-edge" : holder.project === project && holder.service === "caddy")) throw new ComposeProxyClash(project, proxy, port, holder);
+}
+/**
+* Write a file into the edge's running container whole or not at all: a
+* temporary name, then a rename. Not `.yml`: the edge reads only `.yml`,
+* `.yaml` and `.toml` files, so it never sees one half written.
+*/
+async function put(docker, edge, path, content, mode = "644") {
+	const result = await docker.exec(edge, EDGE_SERVICE, [
+		"sh",
+		"-c",
+		"set -e; t=\"$1.tmp\"; cat > \"$t\"; chmod \"$2\" \"$t\"; mv \"$t\" \"$1\"",
+		"sh",
+		path,
+		mode
+	], content);
+	if (result.code !== 0) throw new EdgeWriteFailed(path, `${result.stderr}${result.stdout}`);
+}
+/** Remove files from the edge's container; whether the first was there. */
+async function remove(docker, edge, paths) {
+	return (await docker.exec(edge, EDGE_SERVICE, [
+		"sh",
+		"-c",
+		"e=1; [ -f \"$1\" ] && e=0; rm -f \"$@\"; exit $e",
+		"sh",
+		...paths
+	])).code === 0;
+}
+/**
+* The edge, up: its network and its container — started when it is not
+* running, and recreated when its configuration changed. Idempotent: on a
+* server where it already runs as configured, `up` changes nothing. Its
+* compose file is written to `file`, on this machine: compose reads it here.
+*/
+async function ensureEdge(docker, options) {
+	const { file, ports } = options;
+	const content = edgeComposeFile({
+		ports,
+		staticConfig: traefikStaticFile(ports),
+		logging: options.logging
+	});
+	await mkdir(dirname(file), { recursive: true });
+	if (await readFile(file, "utf-8").catch(() => void 0) !== content) await writeFile(file, content);
+	const ref = edgeRef(file, {
+		...options.host ? { host: options.host } : {},
+		...options.output ? { output: options.output } : {},
+		...options.signal ? { signal: options.signal } : {}
+	});
+	await docker.ensureNetwork(ref, EDGE_NETWORK);
+	await docker.up(ref, [EDGE_SERVICE]);
+	return [file];
+}
+/** A stack's routes, inside the edge's container. */
+function routesPath(project) {
+	return `${EDGE_DYNAMIC_DIR}/${project}.yml`;
+}
+function certificatePaths(project) {
+	return [`${EDGE_CERTS_DIR}/${project}.crt`, `${EDGE_CERTS_DIR}/${project}.key`];
+}
+/**
+* Register a stack with the edge: its certificate first, where it has one,
+* so the routes that need it never load without it — then its routes, in one
+* rename the edge picks up whole. The certificate is read here and written
+* through the engine. The paths written, inside the edge.
+*/
+async function writeEdgeRoutes(docker, edge, project, routes, certificate) {
+	const written = [];
+	const [crt, key] = certificatePaths(project);
+	if (certificate) {
+		await put(docker, edge, crt, await readFile(certificate.certFile, "utf-8"));
+		await put(docker, edge, key, await readFile(certificate.keyFile, "utf-8"), "600");
+		written.push(crt, key);
+	} else await remove(docker, edge, [crt, key]);
+	await put(docker, edge, routesPath(project), routes);
+	written.push(routesPath(project));
+	return written;
+}
+/** What a stack's file holds for the moment between emptying and removal. */
+const UNREGISTERED = "# Unregistered by gkm compose --down.\n";
+/**
+* Unregister a stack: its routes, then its certificate. Whether there was
+* anything to remove — false, too, when the edge is not running.
+*/
+async function removeEdgeRoutes(docker, edge, project) {
+	const file = routesPath(project);
+	if ((await docker.exec(edge, "traefik", [
+		"test",
+		"-f",
+		file
+	])).code !== 0) return false;
+	await put(docker, edge, file, UNREGISTERED);
+	await remove(docker, edge, [file, ...certificatePaths(project)]);
+	return true;
+}
+//#endregion
+//#region src/compose/secrets.ts
+function deployedStackSecrets(workspace, stage, stored, manifest) {
+	const withSeed = withGeneratedSecrets(stored ?? initStageSecrets(stage), manifest);
+	const withLogs = resolveStageTelemetry({
+		...workspace.deploy?.telemetry ? { telemetry: workspace.deploy.telemetry } : {},
+		stage,
+		local: false,
+		target: "compose",
+		runtime: "server",
+		selfHosted: true,
+		used: usesTelemetry(manifest)
+	})?.provider === "self-hosted" ? withLogsPassword(withSeed.secrets) : {
+		secrets: withSeed.secrets,
+		generated: []
+	};
+	const withRedis = runsRedis(manifest, withLogs.secrets.custom ?? {}) ? withRedisPassword(withLogs.secrets) : {
+		secrets: withLogs.secrets,
+		generated: []
+	};
+	return {
+		secrets: withRedis.secrets,
+		generated: [
+			...withSeed.generated,
+			...withLogs.generated,
+			...withRedis.generated
+		]
+	};
+}
+//#endregion
+//#region src/target/compose/health.ts
+/**
+* Asking each app of a stack whether it answers — through Caddy, over HTTPS,
+* the way a browser reaches it.
+*
+* `docker compose up --wait` already knows each container passed its own
+* health check, asked on 127.0.0.1 inside it. What that cannot say is whether
+* the stack is reachable: whether the edge routes the host to the app, and
+* whether the certificate it presents is one a client accepts. So the check
+* goes through the edge, by hostname, and verifies the certificate.
+*/
+/** A request that got no answer in time. */
+var HealthRequestTimedOut = class extends GkmError {
+	url;
+	timeoutMs;
+	constructor(url, timeoutMs) {
+		super(`${url} did not answer within ${timeoutMs}ms. Check the stack is up with \`docker compose ps\`.`);
+		this.url = url;
+		this.timeoutMs = timeoutMs;
+		this.name = "HealthRequestTimedOut";
+	}
+};
+/** The real probe: one HTTPS GET, the certificate verified. */
+const httpsProbe = ({ url, ca, connectTo, connectPort, timeoutMs, signal }) => {
+	const target = new URL(url);
+	return new Promise((resolve, reject) => {
+		const req = request({
+			host: connectTo ?? target.hostname,
+			port: connectPort ?? (target.port || 443),
+			servername: target.hostname,
+			path: `${target.pathname}${target.search}`,
+			method: "GET",
+			headers: { host: target.host },
+			...ca ? { ca } : {},
+			...signal ? { signal } : {},
+			timeout: timeoutMs
+		}, (res) => {
+			res.resume();
+			res.on("end", () => resolve(res.statusCode ?? 0));
+			res.on("error", reject);
+		});
+		req.on("timeout", () => req.destroy(new HealthRequestTimedOut(url, timeoutMs)));
+		req.on("error", reject);
+		req.end();
+	});
+};
+/** Whether a status means the app answered as it should. */
+function isHealthy(status) {
+	return status >= 200 && status < 400;
+}
+/** Apps that did not answer through the edge. */
+var ComposeAppsUnhealthy = class extends GkmError {
+	project;
+	apps;
+	proxy;
+	constructor(project, apps, proxy = "caddy") {
+		const names = apps.map((a) => a.app).join(" ");
+		super(`${project} started, but ${apps.length === 1 ? "this app does" : "these apps do"} not answer through ${proxy === "caddy" ? "Caddy" : "the shared Traefik edge"}:\n` + apps.map(({ url, last }) => `  - ${url}: ${last}`).join("\n") + (proxy === "caddy" ? `\nSee why with \`docker compose -p ${project} logs caddy ${names}\`.` : `\nSee why with \`docker compose -p gkm-edge logs traefik\` and \`docker compose -p ${project} logs ${names}\`.`));
+		this.project = project;
+		this.apps = apps;
+		this.proxy = proxy;
+		this.name = "ComposeAppsUnhealthy";
+	}
+};
+//#endregion
+//#region src/target/compose/phases.ts
+/**
+* The compose target's phases: a stage as one Docker Compose stack behind
+* Caddy — the local stage on this machine's Docker, a deployed stage on its
+* server's, driven over SSH (`compose/server.ts`) from wherever the deploy
+* runs.
+*
+* The order is the point of this file, and the rules it keeps are these:
+*
+* - A tag is checked before anything happens (`validate`). Every app's image
+*   is asked of the registry first; one missing image stops the run naming
+*   them all, and nothing is written, pulled or started.
+* - The databases exist before the apps do (`provision`). Postgres comes up
+*   alone, its databases, roles and grants are created, its migrations
+*   applied and its seeds run from this machine — through an SSH tunnel to a
+*   server's loopback — and only then do the apps
+*   start — so an app
+*   never boots against a schema that is not there yet.
+* - What a stage runs is recorded (`release`). Each app's image, the tag it
+*   was released under and the digest it resolved to are written to the
+*   stage's state, so "what is this stage running" has an exact answer.
+* - What was started answers (`verify`): each app is asked through Caddy,
+*   over HTTPS, with the certificate verified.
+*
+* Every image is built inside Docker from a pruned slice of the build root —
+* the same Dockerfiles `gkm docker` writes — so nothing is built on this
+* machine before `docker compose build`.
+*
+* Docker, the registry, Postgres and the health probe are
+* injected, so the rules are asserted without a daemon; the defaults are the
+* real ones.
+*/
+/** `--push` without `--build`: there is nothing built here to push. */
+var ComposePushNeedsBuild = class extends GkmError {
+	constructor() {
+		super("--push pushes the images this checkout builds, so it needs --build (and never --pull): gkm compose --stage <stage> --build --push --tag <tag>.");
+		this.name = "ComposePushNeedsBuild";
+	}
+};
+/** Digests to run by, on a run that pulls nothing. */
+var ComposePinNeedsPull = class extends GkmError {
+	constructor() {
+		super("--digests-file pins the images a release pulls, so it needs --tag (or --pull) — or, with --build --push, it is where the pushed digests are written.");
+		this.name = "ComposePinNeedsPull";
+	}
+};
+/** A port variable that does not hold a port. */
+var EdgePortInvalid = class extends GkmError {
+	variable;
+	value;
+	constructor(variable, value) {
+		super(`${variable}=${value} is not a port. Set it to a number between 1 and 65535, or unset it for the default.`);
+		this.variable = variable;
+		this.value = value;
+		this.name = "EdgePortInvalid";
+	}
+};
+/** A build with no commit to tag its images with. */
+var NoGitRevision = class extends GkmError {
+	root;
+	constructor(root) {
+		super(`Images built here are tagged with the commit they were built from, and ${root} is not in a git repository with a commit. Commit, or pass --tag to name the images yourself.`);
+		this.root = root;
+		this.name = "NoGitRevision";
+	}
+};
+/**
+* The project's own file merged over a stage's stack: `docker-compose.<stage>.yml`
+* at the workspace root. What the generated file cannot know — a port bound
+* to a tailnet address, another log driver — goes there, and is never
+* overwritten.
+*/
+function stackOverrideFile(root, stage) {
+	return join(root, `docker-compose.${stage}.yml`);
+}
+/** The commit HEAD is at, short — and `-dirty` when the tree has changes. */
+async function gitRevision(root) {
+	let sha;
+	try {
+		sha = (await runOutput("git", [
+			"rev-parse",
+			"--short",
+			"HEAD"
+		], { cwd: root })).trim();
+	} catch {
+		throw new NoGitRevision(root);
+	}
+	if (!sha) throw new NoGitRevision(root);
+	return (await runOutput("git", ["status", "--porcelain"], { cwd: root }).catch(() => "")).trim() ? `${sha}-dirty` : sha;
+}
+/** The edge's ports, from the environment — 443 and 80 when unset. */
+function edgePorts(env = process.env) {
+	const read = (variable, fallback) => {
+		const value = env[variable];
+		if (value === void 0 || value === "") return fallback;
+		const port = Number(value);
+		if (!Number.isInteger(port) || port < 1 || port > 65535) throw new EdgePortInvalid(variable, value);
+		return port;
+	};
+	const logs = env["GKM_COMPOSE_LOGS_PORT"] ? read(LOGS_PORT_ENV, 0) : void 0;
+	return {
+		https: read(EDGE_PORT_ENV.https, 443),
+		http: read(EDGE_PORT_ENV.http, 80),
+		...logs ? { logs } : {}
+	};
+}
+/**
+* The real ones. Each app is asked for three minutes before it counts as
+* down: a deployed stage's first ACME certificate can take that long.
+*/
+const defaultDeps = {
+	docker: dockerCompose,
+	revision: gitRevision,
+	sql: pgClient,
+	buckets: bucketClient,
+	logins: ensurePostgresLogin,
+	migrate: migrateDatabases,
+	seed: seedDatabases,
+	probe: httpsProbe,
+	healthAttempts: 90,
+	healthIntervalMs: 2e3,
+	env: process.env,
+	lookup: systemLookup,
+	server: sshAccess
+};
+/**
+* The stack the stage would run, and — for a tag — the registry's word that
+* every image it names exists. Nothing is written: a missing image stops the
+* run here, before a file, a secret or a container is touched.
+*/
+async function validateCompose(ctx, deps, options = {}) {
+	const { workspace, stage, identity, tag } = ctx;
+	const root = workspace.root;
+	const mode = options.mode ?? (ctx.tagGiven ? "pull" : "build");
+	const push = options.push === true;
+	if (push && mode !== "build") throw new ComposePushNeedsBuild();
+	if (options.pin && mode !== "pull") throw new ComposePinNeedsPull();
+	const registry = workspace.deploy?.registry;
+	if (!registry && (push || mode === "pull")) throw new RegistryRequired(push ? "push" : "pull", imageRef(identity, ctx.apps[0] ?? workspace.name, void 0, tag));
+	const runnables = {};
+	const background = {};
+	const manifest = await discover({
+		patterns: constructGlobs(workspace),
+		cwd: root,
+		runnables,
+		background
+	});
+	const { secrets, generated } = await stageSecrets(ctx, manifest);
+	const layout = mode === "build" ? imageLayout(workspace) : void 0;
+	const composed = composeStack({
+		workspace,
+		manifest,
+		runnables,
+		background,
+		stage,
+		identity,
+		images: {
+			mode,
+			tag,
+			...registry ? { registry } : {}
+		},
+		secrets,
+		...stage === workspace.stages.local ? { localCredentials: (await loadLocalCredentials(workspace)).credentials } : {},
+		allowDevServices: ctx.allowDevServices,
+		ports: edgePorts(deps.env),
+		...layout ? { layout } : {},
+		...push ? { buildOnly: true } : {}
+	});
+	if (mode === "build") assertRedisClient(workspace, composed);
+	const stack = options.pin ? withPinnedImages(composed, options.pin.file, options.pin.digests) : composed;
+	if (mode === "pull" && !ctx.dryRun) await assertImagesExist(deps.docker, tag, [...stack.apps, ...stack.workers]);
+	if (stack.redis && !stack.local) ctx.secrets.mask(stack.redis.password);
+	if (stack.logs && (!stack.local || stack.logs.passwordFromSecrets)) {
+		ctx.secrets.mask(stack.logs.password);
+		ctx.secrets.mask(stack.logs.appEnv.OTEL_EXPORTER_OTLP_HEADERS);
+	}
+	if (!push && !stack.local) requiredServerAddress(stage, workspace.domains?.[stage], secrets?.custom);
+	const server = push ? void 0 : composeServer({
+		stage,
+		local: stack.local,
+		config: workspace.deploy?.compose?.server,
+		custom: secrets?.custom
+	});
+	const dir = join(root, stackDir(stage));
+	const override = stackOverrideFile(root, stage);
+	const overrides = existsSync(override) ? [override] : [];
+	if (overrides.length > 0) ctx.logger.info(`🧩 Merging docker-compose.${stage}.yml over the generated stack`);
+	const recorded = push ? void 0 : await ctx.state.read(stage);
+	const previous = Object.fromEntries(Object.entries(recorded?.state.releases ?? {}).map(([name, releases]) => {
+		const { ref, tag, digest } = releases.current;
+		return [name, {
+			ref,
+			...tag ? { tag } : {},
+			...digest ? { digest } : {}
+		}];
+	}));
+	return {
+		mode,
+		push,
+		stack,
+		...server ? { server } : {},
+		dir,
+		ref: {
+			project: composeProject(identity),
+			file: join(dir, "docker-compose.yml"),
+			...overrides.length > 0 ? { overrides } : {},
+			cwd: root,
+			...server ? { host: dockerHost(server) } : {},
+			output: ctx.childOutput,
+			signal: ctx.signal
+		},
+		secrets,
+		generated,
+		previous,
+		files: [],
+		images: {},
+		changes: []
+	};
+}
+/**
+* What only a compose deploy checks before it changes anything, once the
+* stage's own keys are: the stage's own certificate is there, and every
+* public host points at the stage's server — its records written where a
+* provider holds them, then confirmed — before Caddy or Traefik ask Let's
+* Encrypt for a certificate it could not issue. A build-only run never asks.
+*/
+async function readyCompose(ctx, run, deps) {
+	const { stack } = run;
+	if (stack.tls) {
+		for (const file of [stack.tls.certFile, stack.tls.keyFile]) if (!existsSync(file)) throw new ComposeTlsFileMissing(ctx.stage, file);
+	}
+	if (stack.local) return;
+	if (run.server && !ctx.dryRun && !run.push) await deps.server.check(run.server);
+	await stageHostsDns(ctx, deps, stackHosts(stack).filter((host) => !isLocalHost(host)), run.secrets?.custom);
+}
+/** A stack whose caches are in Redis, built for an app that has no client. */
+var RedisClientMissing = class extends GkmError {
+	apps;
+	constructor(apps) {
+		super(`The stack keeps every cache in Redis, and ${apps.join(", ")} ${apps.length === 1 ? "does" : "do"} not depend on ioredis, the client the generated server reaches it with. Add it to the workspace: pnpm add ioredis`);
+		this.apps = apps;
+		this.name = "RedisClientMissing";
+	}
+};
+/**
+* Every backend and worker image built for a stack with a cache can resolve
+* `ioredis` — listed by its app or a directory above it, the way Node and
+* the image's install find it.
+*/
+function assertRedisClient(workspace, stack) {
+	if (!stack.plan.resources.some((r) => r.kind === "cache")) return;
+	const missing = [.../* @__PURE__ */ new Set([...stack.apps.filter((app) => app.kind === "rest-api").map((a) => a.name), ...stack.workers.map((worker) => worker.host)])].filter((name) => {
+		const app = workspace.apps[name];
+		return app && !installedFrom(join(workspace.root, app.path), "ioredis");
+	}).sort();
+	if (missing.length > 0) throw new RedisClientMissing(missing);
+}
+/**
+* The deploy's DNS step, for a deployed stage: its server's address — required
+* where it serves a real domain — then its own hosts written through each
+* domain's provider in `dns` where they differ, read back from it, and
+* recorded in the stage's state; hosts no provider writes resolved with the
+* system resolver. A dry run prints the plan and writes nothing, and warns
+* rather than stops.
+*
+* @throws {ServerAddressMissing} when the stage has a domain and no address
+* @throws {ServerAddressInvalid} for a value that is not an address
+* @throws {HostNotPointingAtServer} when a host is not the server
+*/
+async function stageHostsDns(ctx, deps, hosts, custom) {
+	const { workspace, stage } = ctx;
+	const server = requiredServerAddress(stage, workspace.domains?.[stage], custom);
+	if (hosts.length === 0) return;
+	if (ctx.skipDns) {
+		ctx.logger.info("🌐 DNS skipped (--skip-dns): no record is written or checked");
+		return;
+	}
+	if (!server) {
+		ctx.logger.info(`🌐 DNS skipped: no ${SERVER_IPV4_KEY} in '${stage}''s secrets — ${serverAddressHint(stage)}`);
+		return;
+	}
+	const log = (line) => ctx.logger.info(line);
+	if (workspace.dns) log(`🌐 DNS for '${stage}' → ${server.ipv4}${server.ipv6 ? ` / ${server.ipv6}` : ""}${ctx.dryRun ? " (dry run — nothing is written)" : ""}`);
+	try {
+		const result = await stageDns({
+			stage,
+			hosts,
+			server,
+			dns: workspace.dns,
+			credentials: ctx.credentials,
+			log,
+			lookup: deps.lookup ?? systemLookup,
+			...ctx.dryRun ? { dryRun: true } : {},
+			...deps.dnsProviderFor ? { providerFor: deps.dnsProviderFor } : {}
+		});
+		if (!ctx.dryRun) {
+			const journal = await DeployJournal.open(ctx.state, stage, () => createComposeState(stage));
+			const providers = new Map(result.plan.domains.map((d) => [d.domain, d.provider]));
+			await recordDnsChanges(journal, result.changes, (domain) => providers.get(domain));
+		}
+		const parts = [result.confirmed.length > 0 ? `${result.confirmed.length} host${result.confirmed.length === 1 ? "" : "s"} confirmed by the DNS provider` : "", result.resolved.length > 0 ? `${result.resolved.length} host${result.resolved.length === 1 ? "" : "s"} resolve${result.resolved.length === 1 ? "s" : ""} to ${server.ipv4}` : ""].filter(Boolean);
+		if (parts.length > 0) log(`🌐 ${parts.join(", ")}`);
+	} catch (error) {
+		if (ctx.dryRun && error instanceof HostNotPointingAtServer) {
+			ctx.logger.warn(`⚠ ${error.message}`);
+			return;
+		}
+		throw error;
+	}
+}
+/**
+* The stage's secrets — and, for a deployed stage, everything it generates
+* once: its seed, and each declared secret and keyring. Kept only once the
+* run goes ahead (`provision`), so a dry run, or a tag that is not there,
+* leaves the stage's secrets as it found them.
+*/
+async function stageSecrets(ctx, manifest) {
+	const stored = await ctx.secrets.read();
+	if (ctx.stage === ctx.workspace.stages.local) return {
+		secrets: stored,
+		generated: []
+	};
+	const { secrets, generated } = deployedStackSecrets(ctx.workspace, ctx.stage, stored, manifest);
+	if (secrets.seed) ctx.secrets.mask(secrets.seed);
+	for (const [key, value] of Object.entries(secrets.custom ?? {})) if (!isReservedStageKey(key)) ctx.secrets.mask(value);
+	return {
+		secrets,
+		generated
+	};
+}
+/**
+* The stack with each app's and worker's image pinned to the digest the file
+* names: the refs it is checked, pulled and recorded by, and the image each
+* compose service runs.
+*/
+function withPinnedImages(stack, file, digests) {
+	const apps = pinImages(file, digests, stack.apps);
+	const workers = pinImages(file, digests, stack.workers);
+	const services = { ...stack.compose.services };
+	for (const image of [...apps, ...workers]) services[image.name] = {
+		...services[image.name],
+		image: image.ref
+	};
+	return {
+		...stack,
+		apps,
+		workers,
+		compose: {
+			...stack.compose,
+			services
+		}
+	};
+}
+/**
+* A dry run: the stack's files, written so they can be read, and what a real
+* run would do — no image is built or pulled, no container touched, nothing
+* recorded and no secret kept.
+*/
+async function planCompose(ctx, run) {
+	if (run.generated.length > 0) ctx.logger.info(`🔑 "${ctx.stage}" has no ${run.generated.join(", ")} yet; this dry run used values it did not keep.`);
+	run.files = await writeStack(ctx.cwd, run.dir, run.stack);
+	printPlan(ctx, run);
+	if (!run.push && run.stack.infra.includes("postgres")) reportPlannedSeeds((await plannedSeeds({
+		root: ctx.workspace.root,
+		manifest: ctx.manifest
+	})).map(({ target, seeds }) => ({
+		folder: target.seeds,
+		seeds
+	})), (line) => ctx.logger.info(line));
+	const planned = (change) => {
+		run.changes.push(change);
+		ctx.emit({
+			type: "resource.planned",
+			...change
+		});
+	};
+	for (const service of run.push ? [] : run.stack.infra) planned({
+		key: `service:${service}`,
+		resourceType: "service",
+		action: "ensure"
+	});
+	for (const app of run.stack.apps) {
+		planned({
+			key: `image:${app.name}`,
+			resourceType: "image",
+			action: run.mode === "build" ? "build" : "reuse",
+			id: app.ref
+		});
+		if (run.push) continue;
+		planned({
+			key: `service:${app.name}`,
+			resourceType: "service",
+			action: run.previous[app.name] ? "reuse" : "create"
+		});
+	}
+	for (const worker of run.stack.workers) {
+		planned({
+			key: `image:${worker.name}`,
+			resourceType: "image",
+			action: run.mode === "build" ? "build" : "reuse",
+			id: worker.ref
+		});
+		if (run.push) continue;
+		planned({
+			key: `service:${worker.name}`,
+			resourceType: "service",
+			action: run.previous[worker.name] ? "reuse" : "create"
+		});
+	}
+	if (!run.push) planned({
+		key: run.stack.proxy === "caddy" ? "service:caddy" : `service:${EDGE_PROJECT}/${EDGE_SERVICE}`,
+		resourceType: "service",
+		action: "ensure"
+	});
+}
+/**
+* What the apps run on: the stage's generated secrets kept, the stack's files
+* written, its infrastructure started, and its databases, roles, grants and
+* migrations applied.
+*/
+async function provisionCompose(ctx, run, deps) {
+	const { stack, ref } = run;
+	if (run.push) return;
+	if (run.generated.length > 0 && run.secrets) {
+		await ctx.secrets.write(run.secrets);
+		ctx.logger.info(`🔑 Generated for "${ctx.stage}" (${ctx.secrets.store}): ${run.generated.join(", ")}`);
+	}
+	const ports = edgePorts(deps.env);
+	await assertEdgePorts(deps.docker, {
+		project: stack.project,
+		proxy: stack.proxy,
+		ports,
+		engine: ref
+	});
+	run.files = await writeStack(ctx.cwd, run.dir, stack);
+	printPlan(ctx, run);
+	if (stack.proxy === "traefik") {
+		ctx.logger.info(`\n🌐 Starting the shared edge (${EDGE_PROJECT})…`);
+		run.files.push(...await ensureEdge(deps.docker, {
+			file: edgeFile(run),
+			ports,
+			...ref.host ? { host: ref.host } : {},
+			logging: {
+				driver: LOG_ROTATION.driver,
+				options: { ...LOG_ROTATION.options }
+			},
+			...ref.output ? { output: ref.output } : {},
+			...ref.signal ? { signal: ref.signal } : {}
+		}));
+		applied(ctx, run, {
+			key: `service:${EDGE_PROJECT}/${EDGE_SERVICE}`,
+			resourceType: "service",
+			action: "ensure",
+			id: `${EDGE_PROJECT}/${EDGE_SERVICE}`,
+			via: "found"
+		});
+	}
+	if (stack.infra.length > 0) {
+		ctx.logger.info(`\n🗄️  Starting ${stack.infra.join(", ")}…`);
+		await deps.docker.up(ref, stack.infra);
+		for (const service of stack.infra) applied(ctx, run, {
+			key: `service:${service}`,
+			resourceType: "service",
+			action: "ensure",
+			id: `${stack.project}/${service}`,
+			via: Object.keys(run.previous).length > 0 ? "recorded" : "created"
+		});
+	}
+	if (stack.infra.includes("postgres")) await prepareDatabases(ctx, run, deps);
+	if (stack.storage && stack.infra.includes("minio")) await prepareBuckets(ctx, run, deps);
+}
+/**
+* Create each bucket the stack's MinIO serves, and the open paths of each
+* one a file server fronts — from this machine, on MinIO's loopback port,
+* the way `gkm dev` creates them.
+*/
+async function prepareBuckets(ctx, run, deps) {
+	const storage = run.stack.storage;
+	if (storage.buckets.length === 0) return;
+	const tunnel = await reach(run, deps, "minio", 9e3);
+	let done;
+	try {
+		const client = deps.buckets(tunnel.port, storage);
+		done = [...await applyBuckets(client, storage.buckets), ...await applyPolicies(client, storage.policies)];
+	} finally {
+		await tunnel.close();
+	}
+	const created = done.filter((entry) => entry.created).length;
+	ctx.logger.info(`🪣  Buckets: ${storage.buckets.join(", ")}${created ? ` (${created} change(s))` : ""}`);
+}
+/**
+* Create what the plan names in the stack's Postgres, migrate it, then run
+* its seeds — every one, every time, as each construct's owner.
+*/
+async function prepareDatabases(ctx, run, deps) {
+	const tunnel = await reach(run, deps, "postgres", 5432);
+	try {
+		await migrateAndSeed(ctx, run, deps, tunnel.port);
+	} finally {
+		await tunnel.close();
+	}
+}
+/**
+* A port a stack's service publishes on its engine's loopback, reachable
+* from this machine: the published port itself on the local stage, and on a
+* server an SSH tunnel to it over the deploy's own login — so Postgres and
+* MinIO are never published beyond the server's loopback.
+*
+* Migrations and seeds run here, in this process, with the project's own
+* Kysely — the way `gkm migrate` runs them — through that port. No image
+* needs to carry them, and nothing is run on the server but the stack.
+*/
+async function reach(run, deps, service, inside) {
+	const published = await deps.docker.port(run.ref, service, inside);
+	if (!run.server) return {
+		port: published,
+		close: async () => {}
+	};
+	return deps.server.tunnel(run.server, published);
+}
+async function migrateAndSeed(ctx, run, deps, port) {
+	const { stack } = run;
+	const workspace = ctx.workspace;
+	const superuser = stack.credential.containers.postgres;
+	const login = await deps.logins({
+		port,
+		login: superuser,
+		legacy: [{
+			user: LEGACY_LOCAL_LOGIN.user,
+			password: superuser.password
+		}, ...stack.local ? [LEGACY_LOCAL_LOGIN] : []]
+	});
+	if (login.notice) ctx.logger.info(login.notice);
+	const statements = [...postgresStatements(stack.plan, workspace.name, stack.credential.seed), ...stack.backups ? backupsRoleStatements(stack.backups) : []];
+	if (statements.length > 0) {
+		ctx.logger.info("🗄️  Creating databases, roles and grants…");
+		await applyPostgres(deps.sql(port, login.login), statements);
+	}
+	const sources = {};
+	const manifest = await discover({
+		patterns: constructGlobs(workspace),
+		cwd: workspace.root,
+		sources
+	});
+	const env = envFor(stack.plan, {
+		ports: { [primaryPortKey("postgres")]: port },
+		project: workspace.name,
+		credentials: {
+			...stack.credential.containers,
+			postgres: login.login
+		},
+		seed: stack.credential.seed
+	});
+	const options = {
+		root: workspace.root,
+		manifest,
+		sources,
+		env
+	};
+	const runs = await deps.migrate(options);
+	const seeds = await deps.seed({
+		...options,
+		stage: ctx.stage
+	}).catch((error) => {
+		if (error instanceof SeedFailed) throw new DeploySeedsFailed(ctx.stage, error.construct, error.seed, error);
+		throw error;
+	});
+	reportDatabaseRuns(runs.map(({ target, applied }) => ({
+		construct: target.id,
+		folder: target.migrations,
+		applied
+	})), seeds.map(({ target, seeded }) => ({
+		construct: target.id,
+		folder: target.seeds,
+		seeded
+	})), (line) => ctx.logger.info(line), (event) => ctx.emit(event));
+}
+/**
+* Each app's image: built from this checkout — inside Docker, every one of
+* them, from a pruned slice of the build root — or pulled at the tag. Nothing
+* live changes.
+*/
+async function buildCompose(ctx, run, deps) {
+	const { stack, ref } = run;
+	const images = [...stack.apps, ...stack.workers];
+	const apps = images.map((image) => image.app);
+	if (run.push) {
+		run.files = await writeStack(ctx.cwd, run.dir, stack);
+		printPlan(ctx, run);
+	}
+	if (run.mode === "build") {
+		ctx.logger.info("\n🐳 Building images…");
+		await deps.docker.build(ref, apps);
+	} else {
+		ctx.logger.info(`\n🐳 Pulling ${ctx.tag}…`);
+		await deps.docker.pull(ref, apps);
+	}
+	if (run.push) ctx.logger.info("\n📤 Pushing images…");
+	for (const image of images) {
+		const digest = run.push ? await deps.docker.push(ref, image.ref) : await deps.docker.digest(ref, image.ref);
+		if (run.push) ctx.logger.info(`   ${image.app.padEnd(12)} ${image.ref}@${digest}`);
+		run.images[image.app] = {
+			ref: image.ref,
+			tag: image.tag,
+			...digest ? { digest } : {}
+		};
+		ctx.emit({
+			type: "artifact.built",
+			app: image.app,
+			imageRef: image.ref,
+			...digest ? { digest } : {}
+		});
+		run.changes.push({
+			key: `image:${image.app}`,
+			resourceType: "image",
+			action: run.mode === "build" ? "build" : "reuse",
+			id: digest ?? image.ref
+		});
+	}
+}
+/**
+* The whole stack up — anything it no longer defines removed — and each
+* app's image recorded in the stage's state.
+*/
+async function releaseCompose(ctx, run, deps) {
+	const { stack, ref } = run;
+	if (run.push) return;
+	ctx.logger.info("\n🚀 Starting the stack…");
+	await deps.docker.up(ref);
+	const edge = edgeRef(edgeFile(run), {
+		...ref.host ? { host: ref.host } : {},
+		...ref.output ? { output: ref.output } : {}
+	});
+	if (stack.proxy === "traefik" && stack.traefik) {
+		const written = await writeEdgeRoutes(deps.docker, edge, stack.project, stack.traefik, stack.tls);
+		ctx.logger.info(`🌐 Registered ${stack.routes.length} route(s) with ${EDGE_PROJECT}: ${written.at(-1)}`);
+	} else if (!stack.local) await removeEdgeRoutes(deps.docker, edge, stack.project);
+	if (stack.local) await deps.docker.copyOut(ref, "caddy", "/data/caddy/pki/authorities/local/root.crt", caFile(run)).catch(() => {});
+	await recordImages(ctx, run);
+	for (const app of stack.apps) {
+		const image = run.images[app.name];
+		applied(ctx, run, {
+			key: `service:${app.name}`,
+			resourceType: "service",
+			action: "ensure",
+			id: `${stack.project}/${app.name}`,
+			via: run.previous[app.name] ? "recorded" : "created"
+		});
+		ctx.emit({
+			type: "app.deployed",
+			app: app.name,
+			applicationId: `${stack.project}/${app.name}`,
+			imageRef: image?.ref ?? app.ref,
+			url: app.url
+		});
+	}
+	for (const worker of stack.workers) applied(ctx, run, {
+		key: `service:${worker.name}`,
+		resourceType: "service",
+		action: "ensure",
+		id: `${stack.project}/${worker.name}`,
+		via: run.previous[worker.name] ? "recorded" : "created"
+	});
+	ctx.logger.info(`\n✅ ${stack.project} is running:`);
+	for (const app of stack.apps) ctx.logger.info(`   ${app.name.padEnd(12)} ${app.url}`);
+	for (const worker of stack.workers) ctx.logger.info(`   ${worker.name.padEnd(12)} worker ${worker.id}`);
+	if (stack.local) ctx.logger.info(`\n🔐 Certificates are from Caddy's local CA: NODE_EXTRA_CA_CERTS=${join(stackDir(ctx.stage), "caddy-root.crt")}`);
+}
+/**
+* Each app's image in the stage's state — the same `images` a Dokploy deploy
+* records: the ref it runs, the tag it was released under, and the digest
+* the tag resolved to.
+*/
+async function recordImages(ctx, run) {
+	const journal = await DeployJournal.open(ctx.state, ctx.stage, () => createComposeState(ctx.stage));
+	const by = currentActor();
+	for (const app of [...run.stack.apps, ...run.stack.workers]) {
+		const image = run.images[app.app] ?? {
+			ref: app.ref,
+			tag: app.tag
+		};
+		recordRelease(journal.state, app.app, image, by);
+	}
+	journal.state.identity = ctx.identity.key;
+	await journal.save();
+}
+/**
+* Each app asked through Caddy, over HTTPS, the certificate verified: an API
+* at `/health`, a site at `/`. On the local stage the edge is this machine and
+* its certificates are Caddy's internal CA's, so the CA `release` copied out
+* is the one trusted and the request goes to 127.0.0.1.
+*/
+async function verifyCompose(ctx, run, deps) {
+	const { stack } = run;
+	if (run.push) return;
+	const ca = stack.local ? await readFile(caFile(run), "utf-8").catch(() => void 0) : void 0;
+	ctx.logger.info(`\n🩺 Checking each app through ${stack.proxy === "caddy" ? "Caddy" : "the shared edge"}…`);
+	const edge = stack.local ? { connectTo: "127.0.0.1" } : run.server ? {
+		connectTo: run.server.host,
+		connectPort: edgePorts(deps.env).https
+	} : void 0;
+	const results = await Promise.all(stack.apps.map((app) => checkApp(ctx, app, deps, {
+		ca,
+		edge
+	})));
+	results.push(...await Promise.all(stack.workers.map((worker) => checkContainer(ctx, run, deps, worker.name))));
+	if (stack.logs) results.push(await checkContainer(ctx, run, deps, LOGS_SERVICE));
+	const down = results.filter((result) => !result.healthy).map(({ app, url, last }) => ({
+		app,
+		url,
+		last
+	}));
+	if (down.length > 0) throw new ComposeAppsUnhealthy(stack.project, down, stack.proxy);
+	if (stack.logs) reportLogs(ctx, stack.logs, stack.local, run.server);
+}
+/**
+* A container's own health check, as Docker reports it: a worker's, which
+* has no route through the edge, and OpenObserve's — by default it has no
+* host there, and served publicly it answers only the addresses it allows,
+* which need not include this one.
+*/
+async function checkContainer(ctx, run, deps, service) {
+	const url = `docker:${service}`;
+	let last = "not asked";
+	for (let attempt = 1; attempt <= deps.healthAttempts; attempt++) {
+		ctx.signal.throwIfAborted();
+		const health = await deps.docker.health(run.ref, service).catch((error) => error instanceof Error ? error.message : String(error));
+		last = health ?? "not running";
+		const healthy = health === "healthy";
+		ctx.emit({
+			type: "health.checked",
+			app: service,
+			url,
+			healthy,
+			attempt
+		});
+		if (healthy) {
+			ctx.logger.info(`   ✓ ${service.padEnd(12)} ${url} (${last})`);
+			return {
+				app: service,
+				url,
+				last,
+				healthy
+			};
+		}
+		if (attempt < deps.healthAttempts) await new Promise((resolve) => setTimeout(resolve, deps.healthIntervalMs));
+	}
+	ctx.logger.warn(`   ✗ ${service.padEnd(12)} ${url} (${last})`);
+	return {
+		app: service,
+		url,
+		last,
+		healthy: false
+	};
+}
+/** How to open the logs, printed — and as an event, for a headless caller. */
+function reportLogs(ctx, logs, local, server) {
+	const lines = logsAccess(logs, {
+		stage: ctx.stage,
+		local,
+		user: server?.user ?? currentUser(),
+		hostname: server?.host ?? hostname(),
+		...server ? { known: true } : {}
+	});
+	ctx.logger.info(`\n${lines.join("\n")}`);
+	ctx.emit({
+		type: "logs.ready",
+		service: LOGS_SERVICE,
+		access: logs.public ? "public" : "tunnel",
+		url: logs.url,
+		...logs.public ? { allow: [...logs.public.allow] } : { port: logs.port },
+		email: logs.email
+	});
+}
+/** This machine's user — a guess at who would SSH in. */
+function currentUser() {
+	try {
+		return userInfo().username;
+	} catch {
+		return process.env.USER ?? "user";
+	}
+}
+async function checkApp(ctx, app, deps, options) {
+	const url = `${app.url}${app.kind === "site" ? "/" : "/health"}`;
+	let last = "not asked";
+	for (let attempt = 1; attempt <= deps.healthAttempts; attempt++) {
+		ctx.signal.throwIfAborted();
+		let status;
+		try {
+			status = await deps.probe({
+				url,
+				...options.ca ? { ca: options.ca } : {},
+				...options.edge,
+				timeoutMs: 1e4,
+				signal: ctx.signal
+			});
+			last = `HTTP ${status}`;
+		} catch (error) {
+			last = error instanceof Error ? error.message : String(error);
+		}
+		const healthy = status !== void 0 && isHealthy(status);
+		ctx.emit({
+			type: "health.checked",
+			app: app.name,
+			url,
+			healthy,
+			...status !== void 0 ? { status } : {},
+			attempt
+		});
+		if (healthy) {
+			ctx.logger.info(`   ✓ ${app.name.padEnd(12)} ${url} (${last})`);
+			return {
+				app: app.name,
+				url,
+				last,
+				healthy
+			};
+		}
+		if (attempt < deps.healthAttempts) await new Promise((resolve) => setTimeout(resolve, deps.healthIntervalMs));
+	}
+	ctx.logger.warn(`   ✗ ${app.name.padEnd(12)} ${url} (${last})`);
+	return {
+		app: app.name,
+		url,
+		last,
+		healthy: false
+	};
+}
+function composeResult(ctx, run) {
+	const apps = [...run.stack.apps.map((app) => {
+		const image = run.images[app.name];
+		return {
+			appName: app.name,
+			type: app.kind === "site" ? "web" : "backend",
+			success: !ctx.dryRun,
+			applicationId: `${run.stack.project}/${app.name}`,
+			imageRef: image?.ref ?? app.ref,
+			...image?.digest ? { digest: image.digest } : {},
+			url: app.url
+		};
+	}), ...run.stack.workers.map((worker) => {
+		const image = run.images[worker.name];
+		return {
+			appName: worker.name,
+			type: "backend",
+			success: !ctx.dryRun,
+			applicationId: `${run.stack.project}/${worker.name}`,
+			imageRef: image?.ref ?? worker.ref,
+			...image?.digest ? { digest: image.digest } : {}
+		};
+	})];
+	return {
+		apps,
+		projectId: run.stack.project,
+		successCount: ctx.dryRun ? 0 : apps.length,
+		failedCount: 0,
+		stage: ctx.stage,
+		identity: ctx.identity.key,
+		tag: ctx.tag,
+		dryRun: ctx.dryRun,
+		environmentId: "",
+		skipped: [...ctx.skipped],
+		urls: Object.fromEntries(run.stack.apps.map((app) => [app.name, app.url])),
+		changes: run.changes
+	};
+}
+function caFile(run) {
+	return join(run.dir, "caddy-root.crt");
+}
+/** The shared edge's compose file, as this machine hands it to compose. */
+function edgeFile(run) {
+	return join(run.dir, `${EDGE_PROJECT}.yml`);
+}
+function applied(ctx, run, change) {
+	const { via, ...rest } = change;
+	run.changes.push(rest);
+	ctx.emit({
+		type: "resource.applied",
+		...rest,
+		via
+	});
+}
+/** Write the stack's files: owner-only, since the env files hold secrets. */
+async function writeStack(root, dir, stack) {
+	await mkdir(dir, {
+		recursive: true,
+		mode: 448
+	});
+	await chmod(dir, 448);
+	const files = [];
+	const write = async (path, content, mode = 420) => {
+		await mkdir(dirname(path), { recursive: true });
+		await writeFile(path, content, { mode });
+		await chmod(path, mode);
+		files.push(path);
+	};
+	const tls = stack.proxy === "caddy" && stack.tls ? {
+		cert: await readFile(stack.tls.certFile, "utf-8"),
+		key: await readFile(stack.tls.keyFile, "utf-8")
+	} : void 0;
+	const compose = stack.caddyfile !== void 0 ? withCaddyConfigs(stack.compose, {
+		caddyfile: stack.caddyfile,
+		...tls ? { tls } : {}
+	}) : stack.compose;
+	await write(join(dir, "docker-compose.yml"), composeYaml(stack, compose), tls ? 384 : 420);
+	if (stack.caddyfile !== void 0) {
+		await write(join(dir, "Caddyfile"), stack.caddyfile);
+		await rm(join(dir, "traefik.yml"), { force: true });
+	} else await rm(join(dir, "Caddyfile"), { force: true });
+	if (stack.traefik !== void 0) await write(join(dir, "traefik.yml"), stack.traefik);
+	await rm(join(dir, "tls"), {
+		recursive: true,
+		force: true
+	});
+	for (const app of [...stack.apps, ...stack.workers]) if (app.env) await write(join(dir, `${app.name}.env`), envFile(app.env), 384);
+	if (stack.logs && stack.compose.services["openobserve"]?.env_file) await write(join(dir, `${LOGS_SERVICE}.env`), envFile(stack.logs.env), 384);
+	if (stack.redis && stack.compose.services["redis"]?.env_file) await write(join(dir, `${REDIS_SERVICE}.env`), envFile(stack.redis.env), 384);
+	if (stack.backups) {
+		for (const [name, content] of Object.entries(stack.backups.files)) await write(join(dir, BACKUPS_SERVICE, name), content);
+		if (stack.compose.services["backups"]?.env_file) await write(join(dir, `${BACKUPS_SERVICE}.env`), envFile(stack.backups.env), 384);
+	} else {
+		await rm(join(dir, BACKUPS_SERVICE), {
+			recursive: true,
+			force: true
+		});
+		await rm(join(dir, `${BACKUPS_SERVICE}.env`), { force: true });
+	}
+	for (const entry of await readdir(dir)) if (entry.endsWith(".credentials")) await rm(join(dir, entry));
+	for (const [path, content] of Object.entries(stack.dockerfiles)) await write(join(root, path), content);
+	await ensureDockerignore(findBuildRoot(root));
+	return files;
+}
+function composeYaml(stack, compose) {
+	const stage = ` --stage ${stack.stage}`;
+	return `# Generated by gkm compose from the construct manifest — do not edit.
+# The ${stack.stage} stage's APIs and sites behind ${stack.proxy === "caddy" ? "one Caddy" : `the shared Traefik edge (${EDGE_PROJECT})`}, and its workers.
+# Each backend and worker reads exactly the keys in its own env file beside
+# this one.
+#
+#   gkm compose${stage}          start or update it
+#   gkm compose${stage} --down   stop it
+${stringify(compose, {
+		lineWidth: 0,
+		aliasDuplicateObjects: false
+	})}`;
+}
+function printPlan(ctx, run) {
+	const { stack, mode, files } = run;
+	ctx.logger.info(`\n🧱 ${stack.project} — stage ${stack.stage}`);
+	if (run.server) ctx.logger.info(`   → ${sshTarget(run.server)} (docker over ssh)`);
+	for (const app of stack.apps) ctx.logger.info(`   ${app.name.padEnd(12)} ${app.url.padEnd(40)} ${mode} ${app.ref}`);
+	for (const worker of stack.workers) ctx.logger.info(`   ${worker.name.padEnd(12)} ${`worker ${worker.id} (no route)`.padEnd(40)} ${mode} ${worker.ref}`);
+	if (stack.infra.length > 0) ctx.logger.info(`   infrastructure: ${stack.infra.join(", ")}`);
+	if (stack.backups) ctx.logger.info(`   ${BACKUPS_SERVICE.padEnd(12)} ${stack.backups.databases.map((d) => d.file).join(", ")} — ${stack.backups.backups.describe}, to ${stack.backups.prefix}/`);
+	ctx.logger.info(`\n📝 Wrote ${files.length} file(s) under ${stackDir(stack.stage)}/`);
+}
+//#endregion
+//#region src/target/compose/index.ts
+/**
+* The built-in `compose` target: a stage as one Docker Compose stack behind
+* Caddy — the local stage on the machine that runs the deploy, a deployed
+* stage on its server's Docker engine, over SSH (`deploy.compose.server`).
+*
+* ```bash
+* gkm deploy --target compose --stage production --tag v1.4.0  # what CI pushed
+* gkm deploy --target compose --stage production               # built from here
+* gkm deploy --target compose --stage development              # the local stage
+* ```
+*
+* - `validate`: the stack (`composeStack`, pure) and, for a tag, every image
+*   looked up in the registry — `ImageTagNotFound` before anything changes
+* - `ready`: a deploy's own checks, after the stage's keys are — the stage's
+*   certificate, its server's address, and every public host's DNS
+* - `plan`: the stack's files and what a run would create or reuse
+* - `provision`: generated secrets kept, files written, infrastructure up,
+*   databases, roles, grants and migrations
+* - `build`: each backend bundled on the host and every image built — or, for
+*   a tag, pulled
+* - `release`: `up --wait --remove-orphans`, and each app's image, tag and
+*   digest in the stage's state
+* - `verify`: each app asked through Caddy over HTTPS
+*
+* With `push` (`gkm compose --build --push`), run with `buildOnly`, it builds
+* every image and pushes it to `deploy.registry`, and does nothing else: no
+* readiness check runs, so a stage whose keys the deploy has yet to write
+* still builds.
+*
+* `gkm compose` is this target with a few more switches (`--build`, `--pull`,
+* `--down`), run through the same `deploy()`.
+*/
+var compose_exports = /* @__PURE__ */ __exportAll({ composeTarget: () => composeTarget });
+/** The compose target, with its Docker, bundler and probe as given. */
+function composeTarget(options = {}) {
+	const { mode, push, pin, report, ...given } = options;
+	const deps = {
+		...defaultDeps,
+		...given
+	};
+	return defineTarget({
+		name: "compose",
+		runtime: "server",
+		capabilities: {
+			rollback: false,
+			migrations: "target",
+			images: true,
+			localStage: true,
+			selfHostedTelemetry: true
+		},
+		credentials: [],
+		tag: ({ cwd }) => deps.revision(cwd),
+		validate: (ctx) => validateCompose(ctx, deps, {
+			...mode ? { mode } : {},
+			...push ? { push } : {},
+			...pin ? { pin } : {}
+		}),
+		ready: (ctx, run) => readyCompose(ctx, run, deps),
+		plan: (ctx, run) => planCompose(ctx, run),
+		provision: (ctx, run) => provisionCompose(ctx, run, deps),
+		build: (ctx, run) => buildCompose(ctx, run, deps),
+		release: (ctx, run) => releaseCompose(ctx, run, deps),
+		verify: (ctx, run) => verifyCompose(ctx, run, deps),
+		result: (ctx, run) => {
+			report?.(run);
+			return composeResult(ctx, run);
+		}
+	});
+}
+//#endregion
+export { sshTarget as _, stackOverrideFile as a, composeProject as c, stackPlan as d, EDGE_PROJECT as f, dockerHost as g, composeServer as h, ComposePushNeedsBuild as i, derivedCredentials as l, pinnedRef as m, compose_exports as n, edgeRef as o, parseDigests as p, ComposePinNeedsPull as r, removeEdgeRoutes as s, composeTarget as t, stackDir as u, dockerCompose as v, projectNetwork as y };
+
+//# sourceMappingURL=compose-BftbEv0b.mjs.map