@geekmidas/cli 10.0.0-alpha.12 → 10.0.0-alpha.13

package/dist/{credentials-DQRvPz2S.cjs → credentials-Q6F0uqJq.cjs}

@@ -1,26 +1,39 @@
-const require_chunk = require('./chunk-CUT6urMc.cjs');
-const require_discover = require('./discover-DmW9Bscc.cjs');
-const require_config = require('./config-RYR9j6EF.cjs');
-const require_workspace = require('./workspace-DPV7FtAv.cjs');
-const require_generator = require('./generator-CNzBw7g5.cjs');
-const require_storage = require('./storage-CSNplaJn.cjs');
-const node_fs = require_chunk.__toESM(require("node:fs"));
-const node_path = require_chunk.__toESM(require("node:path"));
-const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
-const node_fs_promises = require_chunk.__toESM(require("node:fs/promises"));
-const node_child_process = require_chunk.__toESM(require("node:child_process"));
-const node_net = require_chunk.__toESM(require("node:net"));
-const dotenv = require_chunk.__toESM(require("dotenv"));
-const yaml = require_chunk.__toESM(require("yaml"));
-const node_crypto = require_chunk.__toESM(require("node:crypto"));
-const __geekmidas_db_pg_roles = require_chunk.__toESM(require("@geekmidas/db/pg/roles"));
-const __aws_sdk_client_s3 = require_chunk.__toESM(require("@aws-sdk/client-s3"));
-const pg = require_chunk.__toESM(require("pg"));
-const node_util = require_chunk.__toESM(require("node:util"));
-const __geekmidas_cache_postgres = require_chunk.__toESM(require("@geekmidas/cache/postgres"));
-
+const require_rolldown_runtime = require("./rolldown-runtime-C0BPl7ul.cjs");
+const require_discover = require("./discover-BERGFg8v.cjs");
+const require_config = require("./config-Q1rvKHvw.cjs");
+const require_workspace = require("./workspace-mFpI_ky_.cjs");
+const require_generator = require("./generator-Wdfp0jCS.cjs");
+const require_storage = require("./storage-C-30BD1e.cjs");
+let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let node_child_process = require("node:child_process");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+let node_net = require("node:net");
+let dotenv = require("dotenv");
+let yaml = require("yaml");
+let node_crypto = require("node:crypto");
+let _geekmidas_db_pg_roles = require("@geekmidas/db/pg/roles");
+let _aws_sdk_client_s3 = require("@aws-sdk/client-s3");
+let pg = require("pg");
+let node_util = require("node:util");
+let _geekmidas_cache_postgres = require("@geekmidas/cache/postgres");
 //#region src/workspace/backends.ts
 /**
+* Which backend each declared kind resolves to — decided by where the project
+* deploys, and by nothing else.
+*
+* These used to be read out of a `services:` block, where one key answered two
+* questions: *does this exist* and *what backs it*. The first is the manifest's
+* — a declared `Cache` is why there is a cache — and the second is the deploy
+* target's, because the right cache for a Lambda is not the right cache for a
+* box already running Postgres. With both answered elsewhere there was nothing
+* left for the block to say, so it is gone and these read the target.
+*
+* Mail has no answer here at all: every provider speaks SMTP, so the provider
+* is whichever one the stage's mail URL points at.
+*/
+/**
 * Which family of defaults a workspace's deploy target belongs to.
 *
 * One question, asked once: **does this target run containers the project
@@ -60,7 +73,6 @@ function storageBackendFor(on) {
 function eventsBackendFor(on) {
 	return require_discover.DEFAULT_EVENTS[on];
 }
-
 //#endregion
 //#region src/reconcile/containers.ts
 /**
@@ -92,7 +104,7 @@ function postgresImage(version) {
 * per project: a project needing `postgis/postgis` says so in config.
 */
 const DEFAULT_IMAGES = {
-	postgres: postgresImage(__geekmidas_manifest.DEFAULT_POSTGRES_VERSION),
+	postgres: postgresImage(_geekmidas_manifest.DEFAULT_POSTGRES_VERSION),
 	minio: "pgsty/minio:RELEASE.2026-08-04T00-00-00Z",
 	mailpit: "axllent/mailpit:latest",
 	redis: "redis:8-alpine",
@@ -186,17 +198,15 @@ function portKeys(containers) {
 * survives days of dev is noise rather than state.
 */
 function volumeOf(container) {
-	const volumes = {
+	return {
 		postgres: "postgres-data",
 		minio: "minio-data",
 		redis: "redis-data",
 		rabbitmq: "rabbitmq-data",
 		localstack: "localstack-data",
 		caddy: "caddy-data"
-	};
-	return volumes[container];
+	}[container];
 }
-
 //#endregion
 //#region src/reconcile/caddyfile.ts
 /**
@@ -273,7 +283,7 @@ function portOf(address) {
 		const { port, protocol } = new URL(address);
 		return port || (protocol === "https:" ? "443" : "80");
 	} catch {
-		return void 0;
+		return;
 	}
 }
 /**
@@ -356,10 +366,21 @@ const GENERATED = `# Generated by gkm from the construct manifest — do not edi
 # root and point Node at it, so nothing has to be installed to use these URLs
 # from code; a browser needs the root trusted once.
 `;
-
 //#endregion
 //#region src/reconcile/plan.ts
 /**
+* The reconcile plan — what a manifest wants to exist, for one stage.
+*
+* Pure. Turning the plan into running containers and provisioned resources is
+* the applier's job; deciding *what* should exist is this, so the decisions can
+* be asserted as data rather than by starting Docker.
+*
+* One plan serves every stage. `gkm dev` reconciles `development` and `gkm test`
+* reconciles `test`; they differ only in what the resources are called, never in
+* what infrastructure exists. Roles are cluster-scoped in Postgres while grants
+* are per-object, so one container and one role pair serve both.
+*/
+/**
 * Which container serves a kind.
 *
 * Derived kinds map to the same container as their parent — a schema tenant
@@ -460,7 +481,7 @@ const EVENT_CONTAINERS = {
 	rabbitmq: "rabbitmq"
 };
 /** The backend a project gets when it declares queues or topics and says nothing. */
-const DEFAULT_EVENTS$1 = "pgboss";
+const DEFAULT_EVENTS = "pgboss";
 /**
 * How a resource of each kind separates its stage suffix.
 *
@@ -493,7 +514,7 @@ function resourceName(id, kind, stage, localStage) {
 * broker the project selected, which is why the backend is an argument here
 * rather than a second pass that adds containers after the fact.
 */
-function containerFor(kind, events = DEFAULT_EVENTS$1, cache = require_discover.DEFAULT_CACHE.aws, derived = false, edge = true) {
+function containerFor(kind, events = DEFAULT_EVENTS, cache = require_discover.DEFAULT_CACHE.aws, derived = false, edge = true) {
 	if (EVENT_KINDS[kind]) return EVENT_CONTAINERS[events] ?? CONTAINERS.database;
 	if (kind === "file-server") return edge ? "caddy" : CONTAINERS.objects;
 	if (kind === "cache") {
@@ -512,7 +533,7 @@ function containerFor(kind, events = DEFAULT_EVENTS$1, cache = require_discover.
 function planFor(manifest, stage, order, options = {}) {
 	const containers = /* @__PURE__ */ new Set();
 	const resources = [];
-	const events = options.events ?? DEFAULT_EVENTS$1;
+	const events = options.events ?? "pgboss";
 	const cache = options.cache ?? require_discover.DEFAULT_CACHE.aws;
 	for (const id of order) {
 		const declaration = manifest[id];
@@ -528,10 +549,10 @@ function planFor(manifest, stage, order, options = {}) {
 			kind: declaration.kind,
 			...container ? { container } : {},
 			name: resourceName(id, declaration.kind, stage, options.localStage),
-			envKey: (0, __geekmidas_manifest.providedKeyFor)(id, declaration.kind, ROLES[declaration.kind] ?? "url"),
+			envKey: (0, _geekmidas_manifest.providedKeyFor)(id, declaration.kind, ROLES[declaration.kind] ?? "url"),
 			provisions: PROVISIONS[declaration.kind] === true,
-			...declaration.kind === "rest-api" ? { callers: (0, __geekmidas_manifest.dependentsOf)(manifest, id) } : {},
-			...declaration.kind === "site" ? { publicEnv: (0, __geekmidas_manifest.publicEnvFor)(declaration, manifest) } : {},
+			...declaration.kind === "rest-api" ? { callers: (0, _geekmidas_manifest.dependentsOf)(manifest, id) } : {},
+			...declaration.kind === "site" ? { publicEnv: (0, _geekmidas_manifest.publicEnvFor)(declaration, manifest) } : {},
 			...declaration.kind === "file-server" && declaration.open?.length ? { open: declaration.open } : {},
 			..."of" in declaration ? { of: declaration.of } : {},
 			..."schema" in declaration && declaration.schema ? { schema: declaration.schema } : {},
@@ -569,6 +590,7 @@ function planFor(manifest, stage, order, options = {}) {
 * broker.
 */
 var CacheNeedsDatabase = class extends Error {
+	ids;
 	constructor(ids) {
 		super(`A cache backed by the database needs a declared database, and none was declared, and on this deploy target that is where a cache lives. Declare one. Caches affected: ${ids.join(", ")}.`);
 		this.ids = ids;
@@ -587,6 +609,8 @@ var CacheNeedsDatabase = class extends Error {
 * application rather than a deployment choice.
 */
 var CacheIsAmbiguous = class extends Error {
+	ids;
+	databases;
 	constructor(ids, databases) {
 		super(`A cache backed by the database needs to know which one, and this app declares ${databases.length}: ${databases.join(", ")}. Declare the cache from its database — e.g. ${databases[0]}.cache('Sessions') — rather than as a bare new Cache(). Caches affected: ${ids.join(", ")}.`);
 		this.ids = ids;
@@ -595,16 +619,29 @@ var CacheIsAmbiguous = class extends Error {
 	}
 };
 var PgBossNeedsDatabase = class extends Error {
+	ids;
 	constructor(ids) {
 		super(`pg-boss keeps its queues in a declared database, and none was declared. Declare one: on this deploy target, events are carried by pg-boss. Queues and topics affected: ${ids.join(", ")}.`);
 		this.ids = ids;
 		this.name = "PgBossNeedsDatabase";
 	}
 };
-
 //#endregion
 //#region src/reconcile/env.ts
 /**
+* The URLs a reconciled stage injects.
+*
+* One `<NAME>_URL` per construct, and the protocol picks the driver. This is the
+* seam between the target that writes a URL and the client that parses it, so
+* every component of it is read off the resource — never inherited from ambient
+* environment. A bucket can live in a different region than the function reading
+* it, and `AWS_REGION` in a Lambda is the *function's* region, so a URL that
+* omits `?region=` breaks cross-region silently at runtime.
+*
+* Locally that self-containment is what lets the port be whatever was free: the
+* app reads `ORDERS_URL` and never sees a host or a port.
+*/
+/**
 * The credential local containers are brought up with.
 *
 * The design's `roles: false` case — both URLs fall back to the cluster's master
@@ -656,9 +693,9 @@ function envFor(plan, options) {
 		if (url) env[resource.envKey] = url;
 		if (isDatabase(resource.kind) && resource.roles !== false) {
 			const owner = ownerUrl(resource, plan, options.ports, options.project ?? "");
-			if (owner) env[(0, __geekmidas_manifest.provideKey)(resource.id, "ownerUrl")] = owner;
+			if (owner) env[(0, _geekmidas_manifest.provideKey)(resource.id, "ownerUrl")] = owner;
 		}
-		if (resource.kind === "email" && url) env[(0, __geekmidas_manifest.provideKey)(resource.id, "from")] = options.mailFrom ?? `noreply@${LOCAL_HOST}`;
+		if (resource.kind === "email" && url) env[(0, _geekmidas_manifest.provideKey)(resource.id, "from")] = options.mailFrom ?? `noreply@${LOCAL_HOST}`;
 	}
 	Object.assign(env, publicEnv(plan, env));
 	Object.assign(env, brokerEnv(plan, options.ports));
@@ -704,10 +741,10 @@ function publicEnv(plan, resolved) {
 function surfaceEnv(resource, url, resolved = {}) {
 	if (!url) return {};
 	const origins = [...new Set((resource.callers ?? []).map((caller) => resolved[caller]).filter((address) => Boolean(address)).map(originOf).filter((origin) => Boolean(origin)))].sort();
-	const domain = (0, __geekmidas_manifest.cookieDomain)([url, ...origins]);
+	const domain = (0, _geekmidas_manifest.cookieDomain)([url, ...origins]);
 	return {
-		[(0, __geekmidas_manifest.provideKey)(resource.id, "trustedOrigins")]: origins.join(","),
-		...domain ? { [(0, __geekmidas_manifest.provideKey)(resource.id, "cookieDomain")]: domain } : {}
+		[(0, _geekmidas_manifest.provideKey)(resource.id, "trustedOrigins")]: origins.join(","),
+		...domain ? { [(0, _geekmidas_manifest.provideKey)(resource.id, "cookieDomain")]: domain } : {}
 	};
 }
 /** An address reduced to the origin a browser compares against. */
@@ -715,7 +752,7 @@ function originOf(address) {
 	try {
 		return new URL(address).origin;
 	} catch {
-		return void 0;
+		return;
 	}
 }
 /**
@@ -746,7 +783,7 @@ function ownerUrl(resource, plan, ports, project) {
 	if (!resource.container) return void 0;
 	const port = ports[primaryPortKey(resource.container)];
 	if (port === void 0) return void 0;
-	const owner = (0, __geekmidas_db_pg_roles.ownerRole)(localRole(resource));
+	const owner = (0, _geekmidas_db_pg_roles.ownerRole)(localRole(resource));
 	return postgres(port, rootDatabase(resource, plan), {
 		user: owner,
 		password: localRolePassword(project, plan, owner)
@@ -796,7 +833,7 @@ function urlFor(resource, plan, ports, project, addresses = {}) {
 				const schema = schemaOf(resource, plan);
 				return schema ? `${postgres(port, database)}?search_path=${schema}` : postgres(port, database);
 			}
-			const role = resource.kind === "database-reader" ? (0, __geekmidas_db_pg_roles.readerRole)(parentRole(resource, plan)) : localRole(resource);
+			const role = resource.kind === "database-reader" ? (0, _geekmidas_db_pg_roles.readerRole)(parentRole(resource, plan)) : localRole(resource);
 			return postgres(port, database, {
 				user: role,
 				password: localRolePassword(project, plan, role)
@@ -813,7 +850,7 @@ function urlFor(resource, plan, ports, project, addresses = {}) {
 			if (resource.of) {
 				const parent = plan.resources.find((r) => r.id === resource.of);
 				const url = parent ? urlFor(parent, plan, ports, project, addresses) : void 0;
-				return url ? withTable(url, resource.table ?? (0, __geekmidas_manifest.cacheTable)(resource.id)) : void 0;
+				return url ? withTable(url, resource.table ?? (0, _geekmidas_manifest.cacheTable)(resource.id)) : void 0;
 			}
 			switch (plan.cache) {
 				case "elasticache": return `redis://${LOCAL_HOST}:${port}`;
@@ -821,7 +858,7 @@ function urlFor(resource, plan, ports, project, addresses = {}) {
 			}
 		case "queue":
 		case "topic": return broker(plan, port);
-		default: return void 0;
+		default: return;
 	}
 }
 /**
@@ -912,7 +949,6 @@ function schemaOf(resource, plan) {
 		if (current.kind === "database-schema") return current.schema;
 		current = current.of ? byId.get(current.of) : void 0;
 	}
-	return void 0;
 }
 /**
 * A backend whose local addresses cannot be derived yet.
@@ -922,6 +958,7 @@ function schemaOf(resource, plan) {
 * lands, saying so is better than handing out a string that fails on first use.
 */
 var UnprovisionedEventsBackend = class extends Error {
+	backend;
 	constructor(backend) {
 		super(`The local target cannot derive addresses for '${backend}' yet — its topics and queues are named by ARN, which nothing creates locally. Use 'pgboss' (the default) or 'rabbitmq' for local development.`);
 		this.backend = backend;
@@ -939,9 +976,27 @@ var UnprovisionedEventsBackend = class extends Error {
 function localSecret(project, plan, resource) {
 	return (0, node_crypto.createHash)("sha256").update(`${project}:${plan.stage}:${resource.id}`).digest("base64url").slice(0, 43);
 }
-
 //#endregion
 //#region src/reconcile/apps.ts
+/**
+* The apps, as services beside the containers their constructs derive.
+*
+* `gkm docker` used to write these by hand: every backend got
+* `DATABASE_URL=postgresql://…@postgres:5432/app` and `REDIS_URL=redis://redis`,
+* which was right only for a project whose single database happened to be
+* called `Database` — an `Orders` database publishes `ORDERS_URL`, a schema
+* tenant has a URL of its own, and buckets and mail were not wired at all.
+*
+* Now an app's environment is exactly what reconcile hands `gkm dev`: every key
+* the declared constructs provide, from the same derivation. The only
+* difference is where the addresses point — at the containers by service name
+* on the compose network, rather than at `localhost` on the ports published for
+* the host.
+*
+* Always from the *local* stage's plan, whichever stage is being reconciled:
+* `gkm test` rewrites the same file, and running the tests must not quietly
+* point these apps at the test databases.
+*/
 /** The profile app services carry, so `gkm dev` starts only the containers. */
 const APPS_PROFILE = "apps";
 /**
@@ -962,7 +1017,7 @@ function dockerfileOf(appName, path) {
 * rewritten to `<container>:<inside>`.
 */
 function inNetworkEnv(workspace, manifest) {
-	const plan = planFor(manifest, workspace.stages.local, (0, __geekmidas_manifest.provisionOrder)(manifest), {
+	const plan = planFor(manifest, workspace.stages.local, (0, _geekmidas_manifest.provisionOrder)(manifest), {
 		localStage: workspace.stages.local,
 		...backendsOf(workspace)
 	});
@@ -1023,9 +1078,18 @@ function appServices(workspace, manifest, containers) {
 	}
 	return services;
 }
-
 //#endregion
 //#region src/reconcile/clients.ts
+/**
+* The real Postgres and MinIO clients the applier runs against.
+*
+* Kept apart from `provision.ts` so the rules there — what gets created, in what
+* order, and never dropping anything — are asserted against fakes, while the
+* drivers live here where there is nothing to assert but wiring.
+*
+* Both are constructed from the same local addresses the env writer composes,
+* so the applier cannot end up talking to a different container than the app.
+*/
 /** The credential local containers are brought up with. */
 const LOCAL_USER$1 = "geekmidas";
 /**
@@ -1046,8 +1110,7 @@ function pgClient(port) {
 		});
 		await client.connect();
 		try {
-			const result = await client.query(sql, values);
-			return result.rows;
+			return (await client.query(sql, values)).rows;
 		} finally {
 			await client.end();
 		}
@@ -1055,7 +1118,7 @@ function pgClient(port) {
 }
 /** A bucket client pointed at the local MinIO. */
 function bucketClient(port) {
-	const s3 = new __aws_sdk_client_s3.S3Client({
+	const s3 = new _aws_sdk_client_s3.S3Client({
 		region: "us-east-1",
 		endpoint: `http://localhost:${port}`,
 		forcePathStyle: true,
@@ -1067,34 +1130,48 @@ function bucketClient(port) {
 	return {
 		async exists(bucket) {
 			try {
-				await s3.send(new __aws_sdk_client_s3.HeadBucketCommand({ Bucket: bucket }));
+				await s3.send(new _aws_sdk_client_s3.HeadBucketCommand({ Bucket: bucket }));
 				return true;
 			} catch {
 				return false;
 			}
 		},
 		async create(bucket) {
-			await s3.send(new __aws_sdk_client_s3.CreateBucketCommand({ Bucket: bucket }));
+			await s3.send(new _aws_sdk_client_s3.CreateBucketCommand({ Bucket: bucket }));
 		},
 		async policy(bucket) {
 			try {
-				const result = await s3.send(new __aws_sdk_client_s3.GetBucketPolicyCommand({ Bucket: bucket }));
-				return result.Policy;
+				return (await s3.send(new _aws_sdk_client_s3.GetBucketPolicyCommand({ Bucket: bucket }))).Policy;
 			} catch {
-				return void 0;
+				return;
 			}
 		},
 		async setPolicy(bucket, policy) {
-			await s3.send(new __aws_sdk_client_s3.PutBucketPolicyCommand({
+			await s3.send(new _aws_sdk_client_s3.PutBucketPolicyCommand({
 				Bucket: bucket,
 				Policy: policy
 			}));
 		}
 	};
 }
-
 //#endregion
 //#region src/reconcile/compose.ts
+/**
+* The compose document a plan implies.
+*
+* The third declaration of the same containers disappears here: today a
+* `services: ['postgres','minio']` block is kept in step with the code by hand,
+* which is the triplication this design exists to remove, in the one place you
+* touch every day. A `database` implies Postgres; the list is derived.
+*
+* Returns an object rather than a string for the same reason `plan` is pure —
+* what should exist is asserted as data, and turning it into YAML is one line at
+* the edge.
+*
+* What stays config is unchanged: images and versions are pinned explicitly, and
+* a container no construct implies is still declared by hand. Neutral facts come
+* from the declaration, provider detail from config.
+*/
 /** The credential every derived container is brought up with locally. */
 const LOCAL_USER = "geekmidas";
 /**
@@ -1355,9 +1432,18 @@ var UnassignedPort = class extends Error {
 		this.key = key;
 	}
 };
-
 //#endregion
 //#region src/reconcile/docker.ts
+/**
+* The real Docker, behind the small interface reconcile needs.
+*
+* Shells out to `docker compose` rather than talking to the daemon socket: it is
+* what a developer runs by hand when something is wrong, so the two cannot
+* disagree, and it keeps Docker out of this package's dependencies.
+*
+* Every call is scoped to the generated compose file. Nothing here can touch a
+* container this project did not generate.
+*/
 const run = (0, node_util.promisify)(node_child_process.execFile);
 /**
 * The generated file, then the project's own if it has one.
@@ -1388,7 +1474,7 @@ const dockerCli = {
 			const port = Number(stdout.trim().split(":").pop());
 			return Number.isFinite(port) && port > 0 ? port : void 0;
 		} catch {
-			return void 0;
+			return;
 		}
 	},
 	async up(composePath, services) {
@@ -1440,8 +1526,7 @@ const dockerCli = {
 			const running = /* @__PURE__ */ new Set();
 			for (const line of stdout.trim().split("\n").filter(Boolean)) {
 				const entry = JSON.parse(line);
-				const ok = entry.State === "running" && (entry.Health === void 0 || entry.Health === "" || entry.Health === "healthy");
-				if (ok && entry.Service) running.add(entry.Service);
+				if (entry.State === "running" && (entry.Health === void 0 || entry.Health === "" || entry.Health === "healthy") && entry.Service) running.add(entry.Service);
 			}
 			return services.every((service) => running.has(service));
 		} catch {
@@ -1449,10 +1534,27 @@ const dockerCli = {
 		}
 	}
 };
-
 //#endregion
 //#region src/reconcile/ports.ts
 /**
+* Port allocation — why two projects can run at once.
+*
+* Publishing `5432:5432` means the second project on your machine cannot start.
+* Nothing solves that except giving each project its own ports, and what makes
+* it *possible* is the single-`<NAME>_URL` rule: an app reads `ORDERS_URL` and
+* never sees a host or a port, so reconcile is free to bind whatever is
+* available and compose the URL from what it bound. An app reading `DB_HOST` and
+* `DB_PORT` separately could not be moved this way.
+*
+* Assignments are **persisted, not recomputed**. Recomputing means adding a
+* construct renumbers its neighbours, and every running container, saved
+* connection string, and `psql` history goes stale at once.
+*
+* Pure, with the liveness probe injected — a collision with another project's
+* stack is a fact about the machine, and keeping it a parameter is what lets the
+* rules be asserted without binding a socket.
+*/
+/**
 * The window ports are drawn from.
 *
 * Above the registered range so nothing here needs privileges, and below the
@@ -1550,17 +1652,33 @@ async function nextFree(from, taken, probe) {
 * rather than as a connection failure ten minutes later.
 */
 function isPortFree(port) {
-	return new Promise((resolve$1) => {
+	return new Promise((resolve) => {
 		const server = (0, node_net.createServer)();
-		server.once("error", () => resolve$1(false));
-		server.once("listening", () => server.close(() => resolve$1(true)));
+		server.once("error", () => resolve(false));
+		server.once("listening", () => server.close(() => resolve(true)));
 		server.listen(port, "0.0.0.0");
 	});
 }
-
 //#endregion
 //#region src/reconcile/provision.ts
 /**
+* Creating what the URLs name.
+*
+* Convergent and idempotent: every statement asks whether the thing exists
+* first, so reconciling repeatedly is free and a half-applied run recovers by
+* being run again. That property is what lets `gkm dev` do this on every start.
+*
+* The line the design draws is at data, not at side effects — this creates
+* databases, schemas, and buckets, and it never seeds, resets, or drops. A
+* developer who wants their data gone asks for it explicitly.
+*
+* Statement generation is separated from application for the reason the design
+* gives: the same DDL has to run in-process locally and from a provisioner in a
+* VPC, and one implementation is what stops "works locally, fails deployed".
+* When the role DDL lands in `@geekmidas/db` this delegates to it rather than
+* growing its own.
+*/
+/**
 * The Postgres work a plan implies.
 *
 * Databases before the schemas inside them, which `provisionOrder` already
@@ -1611,9 +1729,9 @@ function postgresStatements(plan, project = "") {
 function cacheTableDdl(cache, home, plan) {
 	const database = rootDatabase(home, plan);
 	const schema = home.roles === false ? void 0 : home.schema;
-	const name = cache.table ?? (0, __geekmidas_manifest.cacheTable)(cache.id);
+	const name = cache.table ?? (0, _geekmidas_manifest.cacheTable)(cache.id);
 	const table = schema ? `${schema}.${name}` : name;
-	const created = (0, __geekmidas_cache_postgres.cacheTableStatements)({ table }).map((statement) => ({
+	const created = (0, _geekmidas_cache_postgres.cacheTableStatements)({ table }).map((statement) => ({
 		id: cache.id,
 		describe: statement.describe,
 		database,
@@ -1622,7 +1740,7 @@ function cacheTableDdl(cache, home, plan) {
 	}));
 	if (!schema) return created;
 	const runtime = localRole(home);
-	const owner = (0, __geekmidas_db_pg_roles.ownerRole)(runtime);
+	const owner = (0, _geekmidas_db_pg_roles.ownerRole)(runtime);
 	const qualified = table.split(".").map((part) => quoteIdentifier(part)).join(".");
 	return [
 		...created,
@@ -1650,9 +1768,9 @@ function cacheTableDdl(cache, home, plan) {
 function rolesFor(resource, schema, plan, project) {
 	if (resource.roles === false) return [];
 	const runtime = localRole(resource);
-	const owner = (0, __geekmidas_db_pg_roles.ownerRole)(runtime);
-	const reader = plan.resources.some((r) => r.kind === "database-reader" && r.of === resource.id) ? (0, __geekmidas_db_pg_roles.readerRole)(runtime) : void 0;
-	return (0, __geekmidas_db_pg_roles.roleStatements)({
+	const owner = (0, _geekmidas_db_pg_roles.ownerRole)(runtime);
+	const reader = plan.resources.some((r) => r.kind === "database-reader" && r.of === resource.id) ? (0, _geekmidas_db_pg_roles.readerRole)(runtime) : void 0;
+	return (0, _geekmidas_db_pg_roles.roleStatements)({
 		runtime,
 		owner,
 		...reader ? { reader } : {},
@@ -1702,8 +1820,7 @@ async function applyPostgres(client, statements) {
 			});
 			continue;
 		}
-		const rows = await client.query(statement.database, statement.exists.sql, statement.exists.values);
-		if (rows.length > 0) {
+		if ((await client.query(statement.database, statement.exists.sql, statement.exists.values)).length > 0) {
 			applied.push({
 				id: statement.id,
 				describe: statement.describe,
@@ -1828,9 +1945,20 @@ async function applyBuckets(client, buckets) {
 	}
 	return applied;
 }
-
 //#endregion
 //#region src/reconcile/state.ts
+/**
+* What reconcile records, and the hash that lets it do nothing.
+*
+* Reconciling on every `gkm dev` is only acceptable if the converged case is
+* free, so the desired plan is hashed: matching hash plus healthy containers
+* means there is nothing to do. Without that, the automatic reconcile the design
+* asks for would tax every start.
+*
+* Almost nothing needs recording — roles are queried, migrations have their own
+* table, containers are remembered by Docker. Only ports and this hash have no
+* other owner.
+*/
 const STATE_DIR = ".gkm/reconcile";
 /**
 * The hash of everything a reconcile would act on.
@@ -1859,7 +1987,7 @@ async function loadState(root, stage) {
 		const state = JSON.parse(raw);
 		return state.stage === stage ? state : void 0;
 	} catch {
-		return void 0;
+		return;
 	}
 }
 /** Record what was applied, so the next run can skip it. */
@@ -1871,10 +1999,28 @@ async function saveState(root, state) {
 function statePath(root, stage) {
 	return (0, node_path.join)(root, STATE_DIR, `${stage}.json`);
 }
-
 //#endregion
 //#region src/reconcile/index.ts
 /**
+* Reconcile — the one convergent function `gkm dev`, `gkm test`, and `gkm setup`
+* all call.
+*
+* Three phases, and only this one has side effects: declaring is pure (`gkm
+* build` and the dev watcher), running reads `<NAME>_URL` and provisions
+* nothing. Reconcile computes the desired state, compares, and applies the
+* difference — which is what makes "when does it run" answerable with
+* *whenever, repeatedly*.
+*
+* It is safe to run automatically because its blast radius is entirely local:
+* this project's containers, this project's `.gkm/`. Nothing it does can reach a
+* cloud. The line is drawn at data, not at side effects — it allocates ports,
+* writes compose, starts containers, and creates roles; it never seeds, resets,
+* or drops.
+*
+* Docker is injected rather than imported so the rules above can be asserted
+* without a daemon. The default implementation is the real one.
+*/
+/**
 * Where the generated compose file is written, relative to the project root.
 *
 * At the root, beside the project's own `docker-compose.yml`, because the two
@@ -1919,7 +2065,7 @@ const CADDY_ROOT_IN_CONTAINER = "/data/caddy/pki/authorities/local/root.crt";
 */
 async function reconcile(options) {
 	const { root, project, manifest, stage, start = true, provision = true, docker = dockerCli, probe = isPortFree, sql = pgClient, buckets = bucketClient } = options;
-	const plan = planFor(manifest, stage, (0, __geekmidas_manifest.provisionOrder)(manifest), {
+	const plan = planFor(manifest, stage, (0, _geekmidas_manifest.provisionOrder)(manifest), {
 		localStage: options.localStage,
 		events: options.events,
 		cache: options.cache,
@@ -1958,9 +2104,7 @@ async function reconcile(options) {
 		hash,
 		changed: false
 	};
-	const recorded = await loadState(root, stage);
-	const converged = recorded?.hash === hash && (0, node_fs.existsSync)(composePath) && (!start || await docker.healthy(composePath, plan.containers));
-	if (converged) return result;
+	if ((await loadState(root, stage))?.hash === hash && (0, node_fs.existsSync)(composePath) && (!start || await docker.healthy(composePath, plan.containers))) return result;
 	await write(composePath, toYaml(compose));
 	if (plan.containers.includes("caddy")) {
 		await write((0, node_path.join)(root, CADDYFILE_PATH), caddyfileRoot());
@@ -2037,10 +2181,28 @@ async function write(path, content) {
 	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(path), { recursive: true });
 	await (0, node_fs_promises.writeFile)(path, content);
 }
-
 //#endregion
 //#region src/reconcile/workspace.ts
 /**
+* Workspace config → reconcile.
+*
+* Nothing here is read from a `services:` block — there is none. Which
+* containers exist comes from the manifest; which backend a cache or a broker
+* resolves to comes from the deploy target; and an image pin is the project's
+* own `docker-compose.yml`, merged over the generated file.
+*
+* Shared by `gkm setup`, `gkm dev`, and `gkm test` so all three converge on the
+* same state, differing only in the stage they pass.
+*/
+var workspace_exports = /* @__PURE__ */ require_rolldown_runtime.__exportAll({
+	backendsOf: () => backendsOf,
+	constructGlobs: () => constructGlobs,
+	derivedContainers: () => derivedContainers,
+	reconcileWorkspace: () => reconcileWorkspace,
+	surfaceAddresses: () => surfaceAddresses,
+	usesConstructs: () => usesConstructs
+});
+/**
 * Every constructs glob in the workspace, resolved against its app.
 *
 * Absolute because discovery globs from a single cwd while apps live in
@@ -2076,7 +2238,7 @@ async function derivedContainers(workspace, stage, manifest) {
 		patterns: constructGlobs(workspace),
 		cwd: workspace.root
 	});
-	return planFor(found, stage, (0, __geekmidas_manifest.provisionOrder)(found), {
+	return planFor(found, stage, (0, _geekmidas_manifest.provisionOrder)(found), {
 		localStage: workspace.stages.local,
 		...backendsOf(workspace)
 	}).containers;
@@ -2127,22 +2289,16 @@ function surfaceAddresses(workspace, manifest, at = (_app, port) => localAddress
 	const addresses = {};
 	for (const [id, declaration] of Object.entries(manifest)) {
 		if (declaration.kind !== "rest-api" && declaration.kind !== "site") continue;
-		const host = declaration.kind === "site" ? require_config.appKey(id) : appKeyOfHost(manifest, id);
-		const app = host ? workspace.apps[host] : void 0;
-		if (host && app?.port) addresses[id] = at(host, app.port);
+		const host = require_config.appKey(id);
+		const port = workspace.apps[host]?.port;
+		if (port) addresses[id] = at(host, port);
 	}
 	return addresses;
 }
-/** The app key serving a surface, following a mount to its host. */
-function appKeyOfHost(manifest, id) {
-	const host = require_config.hostOf(manifest, id);
-	return host ? require_config.appKey(host) : void 0;
-}
 /** Where a local process answers, given the port the workspace gave it. */
 function localAddress(port) {
 	return `http://localhost:${port}`;
 }
-
 //#endregion
 //#region src/credentials/index.ts
 const logger = console;
@@ -2175,15 +2331,15 @@ function loadEnvFiles(envConfig, cwd = process.cwd()) {
 * @internal Exported for testing
 */
 async function isPortAvailable(port) {
-	return new Promise((resolve$1) => {
+	return new Promise((resolve) => {
 		const server = (0, node_net.createServer)();
 		server.once("error", (err) => {
-			if (err.code === "EADDRINUSE") resolve$1(false);
-			else resolve$1(false);
+			if (err.code === "EADDRINUSE") resolve(false);
+			else resolve(false);
 		});
 		server.once("listening", () => {
 			server.close();
-			resolve$1(true);
+			resolve(true);
 		});
 		server.listen(port);
 	});
@@ -2252,11 +2408,10 @@ async function savePortState(workspaceRoot, ports) {
 */
 function getContainerHostPort(workspaceRoot, service, containerPort) {
 	try {
-		const result = (0, node_child_process.execSync)(`docker compose port ${service} ${containerPort}`, {
+		const match = (0, node_child_process.execSync)(`docker compose port ${service} ${containerPort}`, {
 			cwd: workspaceRoot,
 			stdio: "pipe"
-		}).toString().trim();
-		const match = result.match(/:(\d+)$/);
+		}).toString().trim().match(/:(\d+)$/);
 		return match ? Number(match[1]) : null;
 	} catch {
 		return null;
@@ -2269,8 +2424,7 @@ function getContainerHostPort(workspaceRoot, service, containerPort) {
 * @internal Exported for testing
 */
 async function resolveServicePorts(workspaceRoot) {
-	const composePath = (0, node_path.join)(workspaceRoot, "docker-compose.yml");
-	const mappings = parseComposePortMappings(composePath);
+	const mappings = parseComposePortMappings((0, node_path.join)(workspaceRoot, "docker-compose.yml"));
 	if (mappings.length === 0) return {
 		dockerEnv: {},
 		ports: {},
@@ -2504,13 +2658,12 @@ ${generateCredentialsInjection(secretsJsonPath)}`;
 * @internal Exported for testing
 */
 async function createEntryWrapper(wrapperPath, entryPath, secretsJsonPath) {
-	const credentialsInjection = secretsJsonPath ? `${generateCredentialsInjection(secretsJsonPath)}
-` : "";
 	const content = `#!/usr/bin/env node
 /**
  * Entry wrapper generated by 'gkm dev --entry'
  */
-${credentialsInjection}// Import and run the user's entry file (dynamic import ensures secrets load first)
+${secretsJsonPath ? `${generateCredentialsInjection(secretsJsonPath)}
+` : ""}// Import and run the user's entry file (dynamic import ensures secrets load first)
 await import('${entryPath}');
 `;
 	await (0, node_fs_promises.writeFile)(wrapperPath, content);
@@ -2550,8 +2703,8 @@ async function prepareEntryCredentials(options) {
 	credentials.PORT = String(resolvedPort);
 	const declaredKeys = [];
 	if (appInfo && usesConstructs(appInfo.workspace)) {
-		const { reconcileWorkspace: reconcileWorkspace$1 } = await Promise.resolve().then(() => require("./workspace-Cji6lE8E.cjs"));
-		const reconciled = await reconcileWorkspace$1(appInfo.workspace, {
+		const { reconcileWorkspace } = await Promise.resolve().then(() => workspace_exports);
+		const reconciled = await reconcileWorkspace(appInfo.workspace, {
 			stage: options.reconcileStage ?? appInfo.workspace.stages.local,
 			start: options.startDocker ?? false
 		});
@@ -2559,8 +2712,7 @@ async function prepareEntryCredentials(options) {
 		declaredKeys.push(...Object.keys(reconciled.env));
 		if (Object.keys(reconciled.env).length > 0) logger.log(`🔌 Resolved ${Object.keys(reconciled.env).length} declared URL(s)`);
 	} else {
-		const composePath = (0, node_path.join)(secretsRoot, "docker-compose.yml");
-		const mappings = parseComposePortMappings(composePath);
+		const mappings = parseComposePortMappings((0, node_path.join)(secretsRoot, "docker-compose.yml"));
 		if (mappings.length > 0) {
 			let resolvedPorts;
 			if (portMode === "full") resolvedPorts = await resolveServicePorts(secretsRoot);
@@ -2581,8 +2733,10 @@ async function prepareEntryCredentials(options) {
 					mappings
 				};
 			}
-			if (options.startDocker) if (appInfo) await startWorkspaceServices(appInfo.workspace, resolvedPorts.dockerEnv, credentials);
-			else await startComposeServices(secretsRoot, resolvedPorts.dockerEnv, credentials);
+			if (options.startDocker) {
+				if (appInfo) await startWorkspaceServices(appInfo.workspace, resolvedPorts.dockerEnv, credentials);
+				else await startComposeServices(secretsRoot, resolvedPorts.dockerEnv, credentials);
+			}
 			if (Object.keys(resolvedPorts.ports).length > 0) {
 				const rewritten = rewriteUrlsWithPorts(credentials, resolvedPorts);
 				Object.assign(credentials, rewritten);
@@ -2620,150 +2774,144 @@ async function prepareEntryCredentials(options) {
 		declaredKeys
 	};
 }
-
 //#endregion
-Object.defineProperty(exports, 'COMPOSE_PATH', {
-  enumerable: true,
-  get: function () {
-    return COMPOSE_PATH;
-  }
-});
-Object.defineProperty(exports, 'LOCAL_CA_PATH', {
-  enumerable: true,
-  get: function () {
-    return LOCAL_CA_PATH;
-  }
+Object.defineProperty(exports, "COMPOSE_PATH", {
+	enumerable: true,
+	get: function() {
+		return COMPOSE_PATH;
+	}
 });
-Object.defineProperty(exports, 'applyPostgres', {
-  enumerable: true,
-  get: function () {
-    return applyPostgres;
-  }
+Object.defineProperty(exports, "LOCAL_CA_PATH", {
+	enumerable: true,
+	get: function() {
+		return LOCAL_CA_PATH;
+	}
 });
-Object.defineProperty(exports, 'backendsOf', {
-  enumerable: true,
-  get: function () {
-    return backendsOf;
-  }
+Object.defineProperty(exports, "applyPostgres", {
+	enumerable: true,
+	get: function() {
+		return applyPostgres;
+	}
 });
-Object.defineProperty(exports, 'cacheBackendFor', {
-  enumerable: true,
-  get: function () {
-    return cacheBackendFor;
-  }
+Object.defineProperty(exports, "cacheBackendFor", {
+	enumerable: true,
+	get: function() {
+		return cacheBackendFor;
+	}
 });
-Object.defineProperty(exports, 'constructGlobs', {
-  enumerable: true,
-  get: function () {
-    return constructGlobs;
-  }
+Object.defineProperty(exports, "constructGlobs", {
+	enumerable: true,
+	get: function() {
+		return constructGlobs;
+	}
 });
-Object.defineProperty(exports, 'createCredentialsPreload', {
-  enumerable: true,
-  get: function () {
-    return createCredentialsPreload;
-  }
+Object.defineProperty(exports, "createCredentialsPreload", {
+	enumerable: true,
+	get: function() {
+		return createCredentialsPreload;
+	}
 });
-Object.defineProperty(exports, 'createEntryWrapper', {
-  enumerable: true,
-  get: function () {
-    return createEntryWrapper;
-  }
+Object.defineProperty(exports, "createEntryWrapper", {
+	enumerable: true,
+	get: function() {
+		return createEntryWrapper;
+	}
 });
-Object.defineProperty(exports, 'derivedContainers', {
-  enumerable: true,
-  get: function () {
-    return derivedContainers;
-  }
+Object.defineProperty(exports, "derivedContainers", {
+	enumerable: true,
+	get: function() {
+		return derivedContainers;
+	}
 });
-Object.defineProperty(exports, 'eventsBackendFor', {
-  enumerable: true,
-  get: function () {
-    return eventsBackendFor;
-  }
+Object.defineProperty(exports, "eventsBackendFor", {
+	enumerable: true,
+	get: function() {
+		return eventsBackendFor;
+	}
 });
-Object.defineProperty(exports, 'findAvailablePort', {
-  enumerable: true,
-  get: function () {
-    return findAvailablePort;
-  }
+Object.defineProperty(exports, "findAvailablePort", {
+	enumerable: true,
+	get: function() {
+		return findAvailablePort;
+	}
 });
-Object.defineProperty(exports, 'isPortAvailable', {
-  enumerable: true,
-  get: function () {
-    return isPortAvailable;
-  }
+Object.defineProperty(exports, "isPortAvailable", {
+	enumerable: true,
+	get: function() {
+		return isPortAvailable;
+	}
 });
-Object.defineProperty(exports, 'loadEnvFiles', {
-  enumerable: true,
-  get: function () {
-    return loadEnvFiles;
-  }
+Object.defineProperty(exports, "loadEnvFiles", {
+	enumerable: true,
+	get: function() {
+		return loadEnvFiles;
+	}
 });
-Object.defineProperty(exports, 'loadSecretsForApp', {
-  enumerable: true,
-  get: function () {
-    return loadSecretsForApp;
-  }
+Object.defineProperty(exports, "loadSecretsForApp", {
+	enumerable: true,
+	get: function() {
+		return loadSecretsForApp;
+	}
 });
-Object.defineProperty(exports, 'prepareEntryCredentials', {
-  enumerable: true,
-  get: function () {
-    return prepareEntryCredentials;
-  }
+Object.defineProperty(exports, "prepareEntryCredentials", {
+	enumerable: true,
+	get: function() {
+		return prepareEntryCredentials;
+	}
 });
-Object.defineProperty(exports, 'providerOf', {
-  enumerable: true,
-  get: function () {
-    return providerOf;
-  }
+Object.defineProperty(exports, "providerOf", {
+	enumerable: true,
+	get: function() {
+		return providerOf;
+	}
 });
-Object.defineProperty(exports, 'reconcileWorkspace', {
-  enumerable: true,
-  get: function () {
-    return reconcileWorkspace;
-  }
+Object.defineProperty(exports, "reconcileWorkspace", {
+	enumerable: true,
+	get: function() {
+		return reconcileWorkspace;
+	}
 });
-Object.defineProperty(exports, 'resolveServicePorts', {
-  enumerable: true,
-  get: function () {
-    return resolveServicePorts;
-  }
+Object.defineProperty(exports, "resolveServicePorts", {
+	enumerable: true,
+	get: function() {
+		return resolveServicePorts;
+	}
 });
-Object.defineProperty(exports, 'resourceName', {
-  enumerable: true,
-  get: function () {
-    return resourceName;
-  }
+Object.defineProperty(exports, "resourceName", {
+	enumerable: true,
+	get: function() {
+		return resourceName;
+	}
 });
-Object.defineProperty(exports, 'rewriteUrlsWithPorts', {
-  enumerable: true,
-  get: function () {
-    return rewriteUrlsWithPorts;
-  }
+Object.defineProperty(exports, "rewriteUrlsWithPorts", {
+	enumerable: true,
+	get: function() {
+		return rewriteUrlsWithPorts;
+	}
 });
-Object.defineProperty(exports, 'startWorkspaceServices', {
-  enumerable: true,
-  get: function () {
-    return startWorkspaceServices;
-  }
+Object.defineProperty(exports, "startWorkspaceServices", {
+	enumerable: true,
+	get: function() {
+		return startWorkspaceServices;
+	}
 });
-Object.defineProperty(exports, 'storageBackendFor', {
-  enumerable: true,
-  get: function () {
-    return storageBackendFor;
-  }
+Object.defineProperty(exports, "storageBackendFor", {
+	enumerable: true,
+	get: function() {
+		return storageBackendFor;
+	}
 });
-Object.defineProperty(exports, 'surfaceAddresses', {
-  enumerable: true,
-  get: function () {
-    return surfaceAddresses;
-  }
+Object.defineProperty(exports, "usesConstructs", {
+	enumerable: true,
+	get: function() {
+		return usesConstructs;
+	}
 });
-Object.defineProperty(exports, 'usesConstructs', {
-  enumerable: true,
-  get: function () {
-    return usesConstructs;
-  }
+Object.defineProperty(exports, "workspace_exports", {
+	enumerable: true,
+	get: function() {
+		return workspace_exports;
+	}
 });
-//# sourceMappingURL=credentials-DQRvPz2S.cjs.map
+
+//# sourceMappingURL=credentials-Q6F0uqJq.cjs.map