@geekmidas/cli 10.0.0-alpha.72 → 10.0.0-alpha.73

package/dist/{state-CCuTJNRH.cjs → state-DMjFPOhf.cjs}

@@ -1,16 +1,19 @@
 const require_rolldown_runtime = require("./rolldown-runtime-C0BPl7ul.cjs");
 const require_run = require("./run-fVZ-rLnc.cjs");
-const require_discover = require("./discover-B4VjaFJk.cjs");
+const require_discover = require("./discover-D1It5r_h.cjs");
 const require_derive = require("./derive-DAbo49sm.cjs");
 const require_workspace = require("./workspace-vdrcRI-m.cjs");
 const require_config = require("./config.cjs");
-const require_resolve = require("./resolve-wEjEvbJ5.cjs");
-const require_fakes = require("./fakes-zW-jNAbQ.cjs");
+const require_EndpointGenerator = require("./EndpointGenerator-CP6sBvQV.cjs");
+const require_resolve = require("./resolve-E5RfY0bm.cjs");
+const require_SubscriberGenerator = require("./SubscriberGenerator-Bixm28fN.cjs");
 let node_path = require("node:path");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 let node_os = require("node:os");
 let node_util = require("node:util");
+let _geekmidas_constructs_crons = require("@geekmidas/constructs/crons");
+let _geekmidas_constructs_queue = require("@geekmidas/constructs/queue");
 let _geekmidas_manifest = require("@geekmidas/manifest");
 let node_net = require("node:net");
 let node_child_process = require("node:child_process");
@@ -1005,11 +1008,11 @@ function providerOf(workspace) {
 * would be worse than a slower one.
 */
 function cacheBackendFor(on) {
-	return require_fakes.DEFAULT_CACHE[on];
+	return require_SubscriberGenerator.DEFAULT_CACHE[on];
 }
 /** Where a declared bucket lives on a target. */
 function storageBackendFor(on) {
-	return require_fakes.DEFAULT_STORAGE[on];
+	return require_SubscriberGenerator.DEFAULT_STORAGE[on];
 }
 /**
 * Which broker carries declared queues and topics on a target.
@@ -1018,7 +1021,7 @@ function storageBackendFor(on) {
 * `Queue` has no events at all, whatever the target.
 */
 function eventsBackendFor(on) {
-	return require_fakes.DEFAULT_EVENTS[on];
+	return require_SubscriberGenerator.DEFAULT_EVENTS[on];
 }
 //#endregion
 //#region src/docker/templates.ts
@@ -1538,11 +1541,37 @@ CMD ["node", "${appPath}/server.js"]
 * @internal Exported for testing
 */
 function generateBackendDockerfile(options) {
+	return gkmBundleDockerfile(options, {
+		title: "Backend Dockerfile",
+		bundle: "server.mjs",
+		as: "server.mjs",
+		expose: true
+	});
+}
+/** The port a worker answers its health check on, inside its container. */
+const WORKER_PORT = 3e3;
+/**
+* A Worker's image: the same build as its host app's backend — a pruned
+* slice, `gkm build --provider server --production` in the image, with the
+* encrypted credentials from the `gkm_credentials` secret — and a runner that
+* is the worker's bundle alone. It publishes nothing: its one route is the
+* health check the HEALTHCHECK asks.
+* @internal Exported for testing
+*/
+function generateWorkerDockerfile(options) {
+	return gkmBundleDockerfile(options, {
+		title: `Worker Dockerfile (${options.worker})`,
+		bundle: options.bundle,
+		as: "worker.mjs",
+		expose: false
+	});
+}
+function gkmBundleDockerfile(options, runner) {
 	const { port, healthCheckPath = "/health" } = options;
 	const { app } = layout(options);
 	const externals = externalsStages(options, app);
 	return `# syntax=docker/dockerfile:1
-# Backend Dockerfile: a turbo-pruned slice, bundled by gkm build in the image
+# ${runner.title}: a turbo-pruned slice, bundled by gkm build in the image
 
 ${prunerStage(options)}
 
@@ -1563,8 +1592,8 @@ RUN apk add --no-cache tini
 RUN addgroup --system --gid 1001 nodejs && \\
     adduser --system --uid 1001 hono
 
-# The bundled server
-COPY --from=builder --chown=hono:nodejs ${app}/.gkm/server/dist/server.mjs ./${externals.copy}
+# The bundled ${runner.as === "server.mjs" ? "server" : "worker"}
+COPY --from=builder --chown=hono:nodejs ${app}/.gkm/server/dist/${runner.bundle} ./${runner.as === runner.bundle ? "" : runner.as}${externals.copy}
 
 ENV NODE_ENV=production
 ENV PORT=${port}
@@ -1573,11 +1602,9 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \\
   CMD wget -qO- http://localhost:${port}${healthCheckPath} > /dev/null 2>&1 || exit 1
 
 USER hono
-
-EXPOSE ${port}
-
+${runner.expose ? `\nEXPOSE ${port}\n` : ""}
 ENTRYPOINT ["/sbin/tini", "--"]
-CMD ["node", "server.mjs"]
+CMD ["node", "${runner.as}"]
 `;
 }
 /**
@@ -2264,7 +2291,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, cache = require_fakes.DEFAULT_CACHE.aws, derived = false, edge = true) {
+function containerFor(kind, events = DEFAULT_EVENTS, cache = require_SubscriberGenerator.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") {
@@ -2285,7 +2312,7 @@ function planFor(manifest, stage, order, options = {}) {
 	const resources = [];
 	const fakes = {};
 	const events = options.events ?? "pgboss";
-	const cache = options.cache ?? require_fakes.DEFAULT_CACHE.aws;
+	const cache = options.cache ?? require_SubscriberGenerator.DEFAULT_CACHE.aws;
 	for (const id of order) {
 		const declaration = manifest[id];
 		if (!declaration) continue;
@@ -2986,6 +3013,36 @@ function appEnvKeys(manifest, appName, runnables = {}) {
 			for (const key of other.provides ?? []) keys.add(key);
 		}
 	}
+	addEdgeKeys(manifest, edges, keys);
+	if (declaration.kind === "site" || declaration.kind === "mobile-app") for (const key of Object.keys((0, _geekmidas_manifest.publicEnvFor)(declaration, manifest))) keys.add(key);
+	return keys;
+}
+/**
+* The keys a Worker's own process reads: what the worker and everything built
+* from it declared an edge to, the broker its crons schedule through, and the
+* address of every queue and topic — which of them its consumers and
+* subscribers are bound to is only known once a build has found them, so a
+* process that runs them is handed each carrier's.
+*
+* `undefined` when no worker has that id.
+*/
+function workerEnvKeys(manifest, workerId, runnables = {}) {
+	const declaration = manifest[workerId];
+	if (declaration?.kind !== "worker") return void 0;
+	const keys = /* @__PURE__ */ new Set([
+		...declaration.provides ?? [],
+		...declaration.requires ?? [],
+		"EVENT_PUBLISHER_CONNECTION_STRING"
+	]);
+	for (const other of Object.values(manifest)) {
+		if (other.kind !== "queue" && other.kind !== "topic") continue;
+		for (const key of other.provides ?? []) keys.add(key);
+	}
+	addEdgeKeys(manifest, [...(0, _geekmidas_manifest.dependenciesOf)(declaration).map((edge) => edge.target), ...runnables[workerId] ?? []], keys);
+	return keys;
+}
+/** What each construct an edge reaches hands the process that reaches it. */
+function addEdgeKeys(manifest, edges, keys) {
 	for (const id of edges) {
 		const target = manifest[id];
 		if (!target) continue;
@@ -3002,8 +3059,6 @@ function appEnvKeys(manifest, appName, runnables = {}) {
 			keys.add("AWS_REGION");
 		}
 	}
-	if (declaration.kind === "site" || declaration.kind === "mobile-app") for (const key of Object.keys((0, _geekmidas_manifest.publicEnvFor)(declaration, manifest))) keys.add(key);
-	return keys;
 }
 /** One compose service per app the workspace runs, behind the apps profile. */
 function appServices(workspace, manifest, containers, runnables = {}, fakes = {}) {
@@ -4467,7 +4522,7 @@ async function reconcileWorkspace(workspace, options) {
 		runnables
 	});
 	const manifest = options.manifest ?? discovered;
-	const fakes = fakesApply(options.stage, options.fake) ? await require_fakes.readFakes(workspace.root, manifest) : {};
+	const fakes = fakesApply(options.stage, options.fake) ? await require_SubscriberGenerator.readFakes(workspace.root, manifest) : {};
 	const result = await reconcile({
 		root: workspace.root,
 		project: workspace.name,
@@ -4534,6 +4589,707 @@ function localAddress(port) {
 	return `http://localhost:${port}`;
 }
 //#endregion
+//#region src/generators/CronGenerator.ts
+var CronGenerator = class extends require_discover.ConstructGenerator {
+	async build(context, constructs, outputDir, options) {
+		const target = options?.target ?? "aws";
+		const logger = console;
+		const cronInfos = [];
+		if (target === "server") {
+			await this.generateServerCronsFile(outputDir, constructs);
+			logger.log(`Generated server crons file with ${constructs.length} crons`);
+			return cronInfos;
+		}
+		if (constructs.length === 0) return cronInfos;
+		const cronsDir = (0, node_path.join)(outputDir, "crons");
+		await (0, node_fs_promises.mkdir)(cronsDir, { recursive: true });
+		for (const { key, construct, path } of constructs) {
+			const handlerFile = await this.generateCronHandler(cronsDir, path.relative, key, context, construct.owner);
+			cronInfos.push({
+				name: key,
+				handler: (0, node_path.relative)(options?.root ?? process.cwd(), handlerFile).replace(/\.ts$/, ".handler"),
+				schedule: construct.schedule || "rate(1 hour)",
+				timeout: construct.timeout,
+				memorySize: construct.memorySize,
+				environment: await construct.getEnvironment({ markOptional: context.markOptional }),
+				dependencies: construct.constructs
+			});
+			logger.log(`Generated cron handler: ${key}`);
+		}
+		return cronInfos;
+	}
+	isConstruct(value) {
+		return _geekmidas_constructs_crons.Cron.isCron(value);
+	}
+	/**
+	* The crons file a server entry imports.
+	*
+	* Shaped after `generateServerSubscribersFile`: one module, every cron, a
+	* `setupCrons` the generated entry calls beside `setupSubscribers`.
+	*
+	* It picks its scheduler from what the process can reach. With a Postgres it
+	* uses pg-boss, whose schedules live in the database — so a deployment
+	* running four replicas fires each job once, which is the thing a timer in
+	* every process gets wrong and does not report. With no database it falls
+	* back to timers and says plainly that it is doing so.
+	*/
+	async generateServerCronsFile(outputDir, crons) {
+		await (0, node_fs_promises.mkdir)(outputDir, { recursive: true });
+		const cronsPath = (0, node_path.join)(outputDir, "crons.ts");
+		if (crons.length === 0) {
+			await (0, node_fs_promises.writeFile)(cronsPath, `/**
+ * Generated cron setup — this app declares none.
+ */
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+
+export async function setupCrons(
+  _envParser: EnvironmentParser<any>,
+  _logger: Logger,
+): Promise<void> {}
+
+export function cronsStatus(): { failed: string[]; connections: unknown[] } {
+  return { failed: [], connections: [] };
+}
+
+export async function stopCrons(): Promise<void> {}
+`);
+			return cronsPath;
+		}
+		const importsByFile = /* @__PURE__ */ new Map();
+		for (const { path, key } of crons) {
+			const importPath = (0, node_path.relative)((0, node_path.dirname)(cronsPath), path.relative).replace(/\.ts$/, ".js");
+			if (!importsByFile.has(importPath)) importsByFile.set(importPath, []);
+			importsByFile.get(importPath)?.push(key);
+		}
+		const content = `/**
+ * Generated cron setup.
+ *
+ * Schedules every cron this app declares, in the process that serves it.
+ *
+ * The schedule lives in Postgres, through pg-boss, in the database the worker
+ * named with \`.database(db)\`. That is what makes running several replicas
+ * safe: each job fires once, where a timer in every process fires it once per
+ * replica and reports nothing.
+ *
+ * No connection string appears here. The construct that owns the database is
+ * the only thing that knows its key, and it is resolved through service
+ * discovery like any other dependency.
+ */
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+import { runCron, scheduleInProcess, toCronExpression } from '@geekmidas/constructs/crons';
+import { ServiceDiscovery } from '@geekmidas/services';
+${Array.from(importsByFile.entries()).map(([importPath, exports]) => `import { ${exports.join(", ")} } from '${importPath}';`).join("\n")}
+
+const crons = [
+${crons.map(({ key }) => `  { name: '${key}', cron: ${key} }`).join(",\n")}
+];
+
+type Stoppable = { stop: () => Promise<void> | void };
+const running: Stoppable[] = [];
+// What a worker's health check reads: the crons that cannot be scheduled, and
+// the broker connection the schedule is kept through.
+const failed: string[] = [];
+const connections: import('@geekmidas/events').EventConnection[] = [];
+
+export async function setupCrons(
+  envParser: EnvironmentParser<any>,
+  logger: Logger,
+): Promise<void> {
+  if (crons.length === 0) {
+    return;
+  }
+
+  const serviceDiscovery = ServiceDiscovery.getInstance(envParser);
+
+  // Resolved once per cron rather than per firing: registering services on
+  // every tick would reconnect a database every minute.
+  const prepared = [];
+  for (const { name, cron } of crons) {
+    try {
+      const schedule = toCronExpression(cron.schedule);
+      const services = cron.services.length > 0
+        ? await serviceDiscovery.register(cron.services)
+        : {};
+
+      prepared.push({ name, cron, schedule, services });
+    } catch (error) {
+      // An unrepresentable schedule is a build-time mistake, and failing the
+      // process for it would take the HTTP server down with it.
+      logger.error({ err: error, cron: name }, 'Cron has no runnable schedule, skipping');
+      failed.push(name);
+    }
+  }
+
+  const run = async (entry: (typeof prepared)[number]) => {
+    try {
+      // The cron's own function, the way its Lambda would run it — services,
+      // the worker's database as \`db\`, its events. It used to call a
+      // \`handler\` a Cron does not have, so every firing logged a failure.
+      await runCron(entry.cron, serviceDiscovery);
+    } catch (error) {
+      logger.error({ err: error, cron: entry.name }, 'Cron failed');
+    }
+  };
+
+  // The app's one pg-boss: the events broker's, as the broker's role, in the
+  // broker's schema. A server fires its own crons, and a process scheduling in
+  // memory fires each job once per replica — so the schedule lives in
+  // Postgres. It used to be a second pg-boss on the worker's database, as the
+  // runtime role, which can neither create a schema nor use the broker's.
+  const { url, devPid } = envParser
+    .create((get) => ({
+      url: get('EVENT_PUBLISHER_CONNECTION_STRING').string().optional(),
+      // Set by \`gkm dev\` on the server it starts, and by nothing deployed.
+      devPid: get('GKM_DEV_PID').string().optional(),
+    }))
+    .parse();
+
+  if (!url?.startsWith('pgboss://')) {
+    // \`gkm dev\` on a target whose crons are infrastructure once deployed —
+    // EventBridge rules on AWS — has no broker to keep a schedule in. It is one
+    // process, so a timer fires each job once, which is all pg-boss is for
+    // here. Only there: a deployed server firing by timer fires once per
+    // replica, so outside dev this stays the error below.
+    if (devPid) {
+      for (const entry of prepared) {
+        running.push(scheduleInProcess(entry.schedule, () => run(entry)));
+        logger.info({ cron: entry.name, schedule: entry.schedule }, 'Cron scheduled in this process');
+      }
+      return;
+    }
+
+    logger.error(
+      { crons: prepared.map(({ name }) => name) },
+      'These crons have nowhere to keep their schedule. On a server they are ' +
+        'scheduled through the pg-boss events broker ' +
+        '(EVENT_PUBLISHER_CONNECTION_STRING), and ' +
+        (url ? 'the broker configured is not pg-boss.' : 'none is configured.'),
+    );
+    failed.push(...prepared.map(({ name }) => name));
+    return;
+  }
+
+  // Through the registered pg-boss driver, which the entry registers for a
+  // server whose broker is pg-boss. Naming \`@geekmidas/events/pgboss\` here
+  // made every bundle with a cron resolve pg-boss, whatever its broker.
+  const { EventConnectionFactory } = await import('@geekmidas/events');
+  const connection = (await EventConnectionFactory.fromConnectionString(
+    url,
+  )) as import('@geekmidas/events').EventConnection & { instance?: any };
+  const boss = connection.instance!;
+
+  // What this app declares now. Anything else under the prefix belonged to a
+  // cron since renamed or deleted, and would keep firing at a handler that has
+  // gone.
+  //
+  // The prefix is \`cron.\` rather than \`cron:\`: pg-boss accepts
+  // alphanumerics, underscores, hyphens, periods and slashes in a queue name,
+  // and rejects a colon outright.
+  const declared = new Set(prepared.map(({ name }) => \`cron.\${name}\`));
+  for (const existing of await boss.getSchedules()) {
+    if (existing.name.startsWith('cron.') && !declared.has(existing.name)) {
+      await boss.unschedule(existing.name);
+      logger.info({ cron: existing.name }, 'Removed a schedule nothing declares');
+    }
+  }
+
+  for (const entry of prepared) {
+    const queue = \`cron.\${entry.name}\`;
+    await boss.createQueue(queue);
+    // UTC, so this agrees with the schedule a deploy target would have made.
+    await boss.schedule(queue, entry.schedule, undefined, { tz: 'UTC' });
+    await boss.work(queue, () => run(entry));
+
+    logger.info({ cron: entry.name, schedule: entry.schedule }, 'Cron scheduled');
+  }
+
+  running.push({ stop: () => connection.close() });
+  connections.push(connection);
+  logger.info({ count: prepared.length }, 'Crons scheduled');
+}
+
+/** The crons that cannot be scheduled, and the connection that schedules the rest. */
+export function cronsStatus(): {
+  failed: string[];
+  connections: import('@geekmidas/events').EventConnection[];
+} {
+  return { failed: [...failed], connections: [...connections] };
+}
+
+/**
+ * Stop scheduling, let a firing in flight finish, and close the broker
+ * connection — pg-boss's graceful stop does all three. The caller bounds it.
+ */
+export async function stopCrons(): Promise<void> {
+  const open = [...running];
+  running.length = 0;
+  connections.length = 0;
+  await Promise.all(open.map((r) => r.stop()));
+}
+`;
+		await (0, node_fs_promises.writeFile)(cronsPath, content);
+		return cronsPath;
+	}
+	async generateCronHandler(outputDir, sourceFile, exportName, context, owner) {
+		const handlerFileName = `${exportName}.ts`;
+		const handlerPath = (0, node_path.join)(outputDir, handlerFileName);
+		const importPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), sourceFile).replace(/\.ts$/, ".js");
+		const runtime = require_EndpointGenerator.runtimeFor(context, (0, node_path.dirname)(handlerPath), owner);
+		const content = `import { AWSScheduledFunction } from '@geekmidas/constructs/aws';
+import { ${exportName} } from '${importPath}';
+${runtime.imports}
+${context.storageDrivers?.imports ?? ""}
+${runtime.bindings}
+${context.storageDrivers?.setup ? `\n// The handler registers the drivers its target needs.\n${context.storageDrivers.setup}\n` : ""}
+const adapter = new AWSScheduledFunction(envParser, ${exportName});
+
+export const handler = adapter.handler;
+`;
+		await (0, node_fs_promises.writeFile)(handlerPath, content);
+		return handlerPath;
+	}
+};
+//#endregion
+//#region src/generators/QueueGenerator.ts
+/**
+* Generates the runtime for queue consumers (`worker.queue(…)`).
+*
+* - **server** (`gkm dev`): a single `queues.ts` exposing `setupQueues()` that
+*   polls each queue in-process, alongside the Hono server, through the queue's
+*   own connection string — pg-boss by default, SQS on the AWS emulator.
+* - **aws-lambda**: one handler file per queue wrapping `AWSLambdaQueue`, backed
+*   by an SQS event-source mapping.
+*/
+var QueueGenerator = class extends require_discover.ConstructGenerator {
+	isConstruct(value) {
+		return _geekmidas_constructs_queue.Queue.isQueue(value);
+	}
+	async build(context, constructs, outputDir, options) {
+		const target = options?.target ?? "aws";
+		const logger = console;
+		const queueInfos = [];
+		if (target === "server") {
+			await this.generateServerQueuesFile(outputDir, constructs);
+			logger.log(`Generated server queues file with ${constructs.length} queues (polling mode)`);
+			return queueInfos;
+		}
+		if (constructs.length === 0) return queueInfos;
+		const queuesDir = (0, node_path.join)(outputDir, "queues");
+		await (0, node_fs_promises.mkdir)(queuesDir, { recursive: true });
+		for (const { key, construct, path } of constructs) {
+			const handlerFile = await this.generateQueueHandler(queuesDir, path.relative, key, context, construct.owner);
+			queueInfos.push({
+				name: construct.name,
+				handler: (0, node_path.relative)(options?.root ?? process.cwd(), handlerFile).replace(/\.ts$/, ".handler"),
+				batchSize: construct.batchSize,
+				fifo: construct.fifo,
+				timeout: construct.timeout,
+				environment: await construct.getEnvironment({ markOptional: context.markOptional }),
+				dependencies: construct.constructs
+			});
+			logger.log(`Generated queue handler: ${key}`);
+		}
+		return queueInfos;
+	}
+	async generateQueueHandler(outputDir, sourceFile, exportName, context, owner) {
+		const handlerPath = (0, node_path.join)(outputDir, `${exportName}.ts`);
+		const importPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), sourceFile).replace(/\.ts$/, ".js");
+		const runtime = require_EndpointGenerator.runtimeFor(context, (0, node_path.dirname)(handlerPath), owner);
+		const content = `import { AWSLambdaQueue } from '@geekmidas/constructs/aws';
+import { ${exportName} } from '${importPath}';
+${runtime.imports}
+${context.storageDrivers?.imports ?? ""}
+${runtime.bindings}
+${context.storageDrivers?.setup ? `\n// The handler registers the drivers its target needs.\n${context.storageDrivers.setup}\n` : ""}
+const adapter = new AWSLambdaQueue(envParser, ${exportName});
+
+export const handler = adapter.handler;
+`;
+		await (0, node_fs_promises.writeFile)(handlerPath, content);
+		return handlerPath;
+	}
+	async generateServerQueuesFile(outputDir, queues) {
+		await (0, node_fs_promises.mkdir)(outputDir, { recursive: true });
+		const queuesPath = (0, node_path.join)(outputDir, "queues.ts");
+		if (queues.length === 0) {
+			await (0, node_fs_promises.writeFile)(queuesPath, `/**
+ * Generated queues setup — this app declares none.
+ */
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+
+export async function setupQueues(
+  _envParser: EnvironmentParser<any>,
+  _logger: Logger,
+): Promise<void> {}
+
+export function queuesStatus(): { failed: string[]; connections: unknown[] } {
+  return { failed: [], connections: [] };
+}
+
+export async function stopQueues(): Promise<void> {}
+`);
+			return queuesPath;
+		}
+		const importsByFile = /* @__PURE__ */ new Map();
+		for (const { path, key } of queues) {
+			const importPath = (0, node_path.relative)((0, node_path.dirname)(queuesPath), path.relative).replace(/\.ts$/, ".js");
+			if (!importsByFile.has(importPath)) importsByFile.set(importPath, []);
+			importsByFile.get(importPath)?.push(key);
+		}
+		const content = `/**
+ * Generated queue consumers setup.
+ *
+ * Each queue's one consumer polls its own queue, through the queue's own
+ * connection string — the one its producers publish on. SQS cannot push, so
+ * this is a poller on every transport: pg-boss locally by default, the SQS
+ * queue on the AWS emulator.
+ *
+ * Deployed on Lambda, a queue's consumer is an SQS event source instead.
+ */
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+import { EventConnectionFactory, Subscriber } from '@geekmidas/events';
+import type { EventConnection } from '@geekmidas/events';
+import { ServiceDiscovery } from '@geekmidas/services';
+${Array.from(importsByFile.entries()).map(([importPath, exports]) => `import { ${exports.join(", ")} } from '${importPath}';`).join("\n")}
+
+const queues = [
+${queues.map(({ key, construct }) => `  { queue: ${key}, connectionKey: '${(0, _geekmidas_manifest.provideKey)(construct.id, "publisherConnectionString")}' },`).join("\n")}
+];
+
+// What was opened, and what could not be: a worker's health check reads both,
+// and its shutdown closes what was opened.
+const connections = new Map<string, EventConnection>();
+const failed: string[] = [];
+
+export async function setupQueues(
+  envParser: EnvironmentParser<any>,
+  logger: Logger,
+): Promise<void> {
+  const serviceDiscovery = ServiceDiscovery.getInstance(envParser);
+
+  for (const { queue, connectionKey } of queues) {
+    const connectionString = process.env[connectionKey];
+    if (!connectionString) {
+      logger.error({ queue: queue.name, connectionKey }, 'No connection string for this queue');
+      failed.push(queue.name);
+      continue;
+    }
+
+    try {
+      let connection = connections.get(connectionString);
+      if (!connection) {
+        connection = await EventConnectionFactory.fromConnectionString(connectionString);
+        connections.set(connectionString, connection);
+      }
+      const eventSubscriber = await Subscriber.fromConnection(connection);
+      const services = queue.services.length > 0
+        ? await serviceDiscovery.register(queue.services)
+        : {};
+      // The queue's database — the worker's, or its own — handed over as \`db\`.
+      const db = queue.databaseService
+        ? (await serviceDiscovery.register([queue.databaseService]))[
+            queue.databaseService.serviceName
+          ]
+        : undefined;
+
+      // A queue's messages carry one type — its own name.
+      await eventSubscriber.subscribe([queue.name], async (message) => {
+        try {
+          const validation = await queue.messageSchema['~standard'].validate(message.payload);
+          if (validation.issues) {
+            logger.error({ issues: validation.issues, queue: queue.name }, 'Queue message failed validation');
+            return;
+          }
+
+          await queue.handler({
+            messages: [validation.value],
+            services: services,
+            logger: queue.logger,
+            db,
+          } as any);
+        } catch (error) {
+          logger.error({ err: error, queue: queue.name }, 'Failed to process queue message');
+          // Rethrown so the transport keeps the message for a retry.
+          throw error;
+        }
+      });
+      logger.info({ queue: queue.name }, 'Queue consumer started polling');
+    } catch (error) {
+      logger.error({ err: error, queue: queue.name }, 'Failed to set up queue consumer');
+      failed.push(queue.name);
+    }
+  }
+}
+
+/** The consumers that could not start, and the connections that did. */
+export function queuesStatus(): { failed: string[]; connections: EventConnection[] } {
+  return { failed: [...failed], connections: [...connections.values()] };
+}
+
+/**
+ * Stop polling, let the messages in flight finish, and close each broker
+ * connection — pg-boss's graceful stop does all three. The caller bounds it.
+ */
+export async function stopQueues(): Promise<void> {
+  const open = [...connections.values()];
+  connections.clear();
+  await Promise.all(open.map((connection) => connection.close()));
+}
+`;
+		await (0, node_fs_promises.writeFile)(queuesPath, content);
+		return queuesPath;
+	}
+};
+//#endregion
+//#region src/generators/WorkerGenerator.ts
+/**
+* A worker whose topic subscribers would have to be pushed to over HTTP.
+*
+* On SNS a subscriber is an HTTP endpoint SNS delivers to, and a worker's
+* process serves nothing but its health check. A server target's broker is
+* pg-boss, where each subscriber polls a queue of its own, so this is only
+* reached by building server images for a project that deploys to AWS — where
+* a subscriber is a Lambda instead.
+*/
+var WorkerSubscribersNeedPush = class extends Error {
+	worker;
+	subscribers;
+	constructor(worker, subscribers) {
+		super(`The worker '${worker}' runs topic subscribers (${subscribers.join(", ")}), and this build's broker is SNS, which pushes each event to its subscriber over HTTP. A worker image serves only its health check. Deploy to a server target, whose broker is pg-boss and whose subscribers poll, or to AWS, where each subscriber is a Lambda.`);
+		this.worker = worker;
+		this.subscribers = subscribers;
+		this.name = "WorkerSubscribersNeedPush";
+	}
+};
+/** Where a worker's generated entry lives, under an app's `.gkm/server`. */
+function workerEntryDir(serverDir, workerId) {
+	return (0, node_path.join)(serverDir, "workers", require_derive.appKey(workerId));
+}
+/** The file a worker's bundle is written to, beside the server's. */
+function workerBundleName(workerId) {
+	return `worker-${require_derive.appKey(workerId)}.mjs`;
+}
+/**
+* A Worker's production entry: the process that runs its crons, its queue
+* consumers and its topic subscribers, and answers nothing but a health check.
+*
+* It is the server's runtime without the server. The `crons.ts`, `queues.ts`
+* and `subscribers.ts` it starts are the files `gkm dev` starts — written by
+* the same generators, given only this worker's constructs — so a consumer
+* runs the same code in development and in the image. What it adds is the
+* process around them: drivers, a health check that says when a consumer or
+* the broker is down, and a shutdown that drains.
+*/
+var WorkerGenerator = class {
+	generators;
+	constructor(generators = {
+		cron: new CronGenerator(),
+		queue: new QueueGenerator(),
+		subscriber: new require_SubscriberGenerator.SubscriberGenerator()
+	}) {
+		this.generators = generators;
+	}
+	/** Write the worker's files; returns its entry, `worker.ts`. */
+	async build(input) {
+		const { context, workerId, outputDir } = input;
+		if (input.subscribers.length > 0 && context.eventsBackends?.includes("sns")) throw new WorkerSubscribersNeedPush(workerId, input.subscribers.map(({ key }) => key));
+		await (0, node_fs_promises.mkdir)(outputDir, { recursive: true });
+		const options = { target: "server" };
+		await Promise.all([
+			this.generators.cron.build(context, input.crons, outputDir, options),
+			this.generators.queue.build(context, input.queues, outputDir, options),
+			this.generators.subscriber.build(context, input.subscribers, outputDir, options)
+		]);
+		await (0, node_fs_promises.writeFile)((0, node_path.join)(outputDir, "app.ts"), workerApp(context, workerId, outputDir));
+		await (0, node_fs_promises.writeFile)((0, node_path.join)(outputDir, "telemetry.ts"), require_EndpointGenerator.generateTelemetryModule(context.telemetry ? {
+			...context.telemetry,
+			serviceName: workerId
+		} : void 0));
+		const entry = (0, node_path.join)(outputDir, "worker.ts");
+		await (0, node_fs_promises.writeFile)(entry, workerEntry(context.production?.healthCheck ?? "/health"));
+		return entry;
+	}
+};
+/**
+* `app.ts`: the worker's runtime — its logger and environment parser off the
+* Worker construct, the drivers its target needs, and a `startWorker` that
+* starts every cron, consumer and subscriber it owns.
+*/
+function workerApp(context, workerId, outputDir) {
+	const runtime = require_EndpointGenerator.runtimeFor(context, outputDir, workerId);
+	return `/**
+ * Generated worker runtime for ${workerId}.
+ * Generated by 'gkm build --production'.
+ */
+import { setupCrons, cronsStatus, stopCrons } from './crons.js';
+import { setupQueues, queuesStatus, stopQueues } from './queues.js';
+import { setupSubscribers, subscribersStatus, stopSubscribers } from './subscribers.js';
+${runtime.imports}
+${context.storageDrivers?.imports ?? ""}
+
+${runtime.bindings}
+
+${context.storageDrivers?.setup ? `// The entry point registers the drivers its target needs.
+${context.storageDrivers.setup}
+` : ""}
+// Who this worker is to Postgres: application_name on every connection.
+process.env.GKM_APP_NAME ??= ${JSON.stringify(workerId)};
+
+export { logger };
+
+/** What the health check answers, and why. */
+export interface WorkerHealth {
+  healthy: boolean;
+  /** The crons, queues and subscribers that could not start. */
+  failed: string[];
+  /** How many broker connections did not answer. */
+  down: number;
+}
+
+/** Whether one broker connection answers: open, and — on pg-boss — a query. */
+async function answers(connection: unknown): Promise<boolean> {
+  const c = connection as {
+    isConnected?: () => boolean;
+    instance?: { getDb?: () => { executeSql: (sql: string) => Promise<unknown> } };
+  };
+  if (c.isConnected && !c.isConnected()) return false;
+  const db = c.instance?.getDb?.();
+  if (!db) return true;
+  try {
+    await Promise.race([
+      db.executeSql('select 1'),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 2000).unref()),
+    ]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Start everything this worker runs. */
+export async function startWorker(): Promise<{
+  health: () => Promise<WorkerHealth>;
+  stop: () => Promise<void>;
+}> {
+  // An app object with no routes: on a server target nothing is pushed to a
+  // subscriber, so there is nothing to mount.
+  const noRoutes = { post: () => undefined };
+
+  await setupSubscribers(noRoutes, envParser, logger).catch((error) => {
+    logger.error({ err: error }, 'Failed to start subscribers');
+  });
+  await setupQueues(envParser, logger).catch((error) => {
+    logger.error({ err: error }, 'Failed to start queue consumers');
+  });
+  await setupCrons(envParser, logger).catch((error) => {
+    logger.error({ err: error }, 'Failed to schedule crons');
+  });
+
+  const statuses = () => [subscribersStatus(), queuesStatus(), cronsStatus()];
+
+  return {
+    async health() {
+      const all = statuses();
+      const failed = all.flatMap((s) => s.failed);
+      const alive = await Promise.all(
+        all.flatMap((s) => s.connections as unknown[]).map(answers),
+      );
+      const down = alive.filter((ok) => !ok).length;
+      return { healthy: failed.length === 0 && down === 0, failed, down };
+    },
+    // Each stops pulling, waits for what it has in flight, and closes its
+    // broker connection. Together, so one slow handler does not hold the
+    // others' connections open.
+    async stop() {
+      await Promise.all([stopSubscribers(), stopQueues(), stopCrons()]);
+    },
+  };
+}
+`;
+}
+/**
+* `worker.ts`: the process. Health first, so the container answers while the
+* consumers connect; then the worker; then a shutdown that drains.
+*/
+function workerEntry(healthCheck) {
+	return `#!/usr/bin/env node
+/**
+ * Production worker entry point.
+ * Generated by 'gkm build --production'.
+ *
+ * Runs this worker's crons, queue consumers and topic subscribers, and serves
+ * one route: ${healthCheck}, on PORT — 200 when every consumer started and
+ * every broker connection answers, 503 otherwise.
+ *
+ * On SIGTERM it stops pulling messages and scheduling crons, lets the handlers
+ * in flight finish, closes its broker connections and database pools, and
+ * exits 0 — or 1, at GKM_SHUTDOWN_TIMEOUT_MS (8s by default, under Docker's
+ * 10s stop timeout).
+ */
+import { createServer } from 'node:http';
+import { runShutdownHooks } from '@geekmidas/constructs';
+import { startTelemetry } from './telemetry.js';
+
+// Before the worker is imported, so the libraries it loads are instrumented.
+await startTelemetry({ ignorePaths: [${JSON.stringify(healthCheck)}] });
+
+const { startWorker, logger } = await import('./app.js');
+
+const port = Number(process.env.PORT) || 3000;
+
+let worker: Awaited<ReturnType<typeof startWorker>> | undefined;
+let stopping = false;
+
+const server = createServer((req, res) => {
+  const path = (req.url ?? '/').split('?')[0];
+  if (path !== ${JSON.stringify(healthCheck)} || (req.method !== 'GET' && req.method !== 'HEAD')) {
+    res.writeHead(404).end();
+    return;
+  }
+  const answer = (status: number, body: unknown) => {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(body));
+  };
+  if (stopping) return answer(503, { status: 'stopping' });
+  if (!worker) return answer(503, { status: 'starting' });
+  worker.health().then(
+    (health) => answer(health.healthy ? 200 : 503, { status: health.healthy ? 'ok' : 'unhealthy', ...health }),
+    (error) => answer(503, { status: 'unhealthy', error: String(error) }),
+  );
+});
+server.listen(port);
+
+const shutdown = async () => {
+  if (stopping) return;
+  stopping = true;
+  const deadline = Number(process.env.GKM_SHUTDOWN_TIMEOUT_MS) || 8000;
+  logger.info({ deadline }, 'Graceful shutdown initiated');
+  setTimeout(() => {
+    logger.warn({ deadline }, 'Shutdown deadline reached, exiting');
+    process.exit(1);
+  }, deadline).unref();
+
+  // Nothing new is pulled or scheduled; what is in flight finishes.
+  await worker?.stop().catch((error) => logger.error({ err: error }, 'Failed to stop the worker'));
+  // Then what the handlers used: database pools.
+  await runShutdownHooks((error) => logger.error({ err: error }, 'Shutdown hook failed'));
+  server.close();
+  logger.info('Worker stopped');
+  process.exit(0);
+};
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
+worker = await startWorker();
+logger.info({ port }, 'Worker started');
+`;
+}
+//#endregion
 //#region src/secrets/encryption.ts
 var encryption_exports = /* @__PURE__ */ require_rolldown_runtime.__exportAll({
 	encryptSecrets: () => encryptSecrets,
@@ -4586,6 +5342,74 @@ function keyFingerprint(masterKey) {
 	return (0, node_crypto.createHash)("sha256").update(masterKey).digest("hex").slice(0, 8);
 }
 //#endregion
+//#region src/build/workers.ts
+/** A worker with background work and no backend app to build it from. */
+var WorkerHasNoApp = class extends Error {
+	worker;
+	constructor(worker) {
+		super(`The worker '${worker}' has crons, queues or subscribers, and the workspace has no backend app that builds a server to carry its entry. Declare a RestApi whose app holds the worker's code.`);
+		this.worker = worker;
+		this.name = "WorkerHasNoApp";
+	}
+};
+/** A worker whose service name an app already has. */
+var WorkerNameTaken = class extends Error {
+	worker;
+	service;
+	constructor(worker, service) {
+		super(`The worker '${worker}' runs as the service '${service}', and an app is already called that. Rename the worker — new Worker('${worker}Worker') — so each container has a name of its own.`);
+		this.worker = worker;
+		this.service = service;
+		this.name = "WorkerNameTaken";
+	}
+};
+/**
+* The workers a workspace deploys — each one that has background work — and
+* the app each is built from.
+*
+* The host is the backend app whose directory holds the most of the worker's
+* files; one whose work sits outside every app (a shared `jobs/` directory)
+* is built by the first backend, by name, that generates a server. An app
+* with its own entry is never one — gkm's generators do not build it — and a
+* surface that serves itself, an auth server, only when it holds the work.
+*
+* @param background Each worker's files, from discovery's `background`.
+*/
+function workerUnits(workspace, manifest, background) {
+	const hosts = Object.entries(workspace.apps).filter(([, app]) => app.type === "backend" && !app.entry).map(([name, app]) => {
+		const surface = Object.entries(manifest).find(([id, d]) => d.kind === "rest-api" && require_derive.appKey(id) === name)?.[1];
+		return {
+			name,
+			root: (0, node_path.isAbsolute)(app.path) ? app.path : (0, node_path.join)(workspace.root, app.path),
+			generated: !(surface?.kind === "rest-api" && surface.endpoints.length > 0)
+		};
+	}).sort((a, b) => a.name.localeCompare(b.name));
+	const units = [];
+	for (const [id, declaration] of Object.entries(manifest)) {
+		if (declaration.kind !== "worker") continue;
+		const files = background[id] ?? [];
+		if (files.length === 0) continue;
+		const name = require_derive.appKey(id);
+		if (workspace.apps[name]) throw new WorkerNameTaken(id, name);
+		const ranked = hosts.map((host) => ({
+			host,
+			holds: files.filter((file) => isUnder(file, host.root)).length
+		})).sort((a, b) => b.holds - a.holds || Number(b.host.generated) - Number(a.host.generated));
+		const host = ranked[0]?.host;
+		if (!host || ranked[0].holds === 0 && !host.generated) throw new WorkerHasNoApp(id);
+		units.push({
+			id,
+			name,
+			app: host.name
+		});
+	}
+	return units.sort((a, b) => a.name.localeCompare(b.name));
+}
+function isUnder(file, dir) {
+	const rel = (0, node_path.relative)(dir, file);
+	return rel !== "" && !rel.startsWith("..") && !(0, node_path.isAbsolute)(rel) ? !rel.startsWith(`..${node_path.sep}`) : false;
+}
+//#endregion
 //#region src/deploy/devServices.ts
 /**
 * Mail and object storage on a deployed stage: real ones, or — only when
@@ -5043,7 +5867,7 @@ async function dockerCommand(options) {
 	const cwd = options.cwd ?? process.cwd();
 	const loaded = await require_config.loadWorkspaceConfig(cwd);
 	const names = loaded.type === "single" ? Object.fromEntries(Object.keys(loaded.workspace.apps).map((name) => [name, resolveDockerConfig(loaded.raw).imageName])) : {};
-	const result = await workspaceDockerCommand(loaded.workspace, loaded.manifest, names);
+	const result = await workspaceDockerCommand(loaded.workspace, loaded.manifest, names, loaded.background);
 	if (options.build) for (const app of result.apps) await buildDockerImage(app, result.buildRoot, options);
 	if (options.push) for (const app of result.apps) await pushDockerImage(app.imageName, options, result.buildRoot);
 	return result;
@@ -5095,7 +5919,7 @@ async function pushDockerImage(imageName, options, cwd) {
 * Generate Dockerfiles for all apps in a workspace.
 * @internal Exported for testing
 */
-async function workspaceDockerCommand(workspace, manifest, imageNames = {}) {
+async function workspaceDockerCommand(workspace, manifest, imageNames = {}, background = {}) {
 	const results = [];
 	const layout = imageLayout(workspace);
 	logger$1.log(`\n🐳 Generating Dockerfiles for workspace: ${workspace.name}`);
@@ -5125,6 +5949,24 @@ async function workspaceDockerCommand(workspace, manifest, imageNames = {}) {
 			imageName: imageNames[appName] ?? appName
 		});
 	}
+	for (const worker of manifest ? workerUnits(workspace, manifest, background) : []) {
+		logger$1.log(`\n   📄 Generating Dockerfile for ${worker.name} (worker ${worker.id}, built from ${worker.app})`);
+		const dockerfile = workerDockerfile(worker, workspace.apps[worker.app], {
+			layout,
+			workspaceRoot: workspace.root
+		});
+		const path = workerDockerfileOf(worker.name);
+		const dockerfilePath = (0, node_path.join)(workspace.root, path);
+		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(dockerfilePath), { recursive: true });
+		await (0, node_fs_promises.writeFile)(dockerfilePath, dockerfile);
+		logger$1.log(`      Generated: ${path}`);
+		results.push({
+			appName: worker.name,
+			type: "backend",
+			dockerfile: dockerfilePath,
+			imageName: imageNames[worker.name] ?? worker.name
+		});
+	}
 	const dockerignorePath = await ensureDockerignore(layout.buildRoot);
 	logger$1.log(`\n   Ensured: ${dockerignorePath}`);
 	const composePath = await writeConstructsCompose(workspace);
@@ -5164,6 +6006,24 @@ function appDockerfile(appName, app, options) {
 		healthCheckPath: "/health"
 	});
 }
+/** Where `gkm docker` writes a worker's Dockerfile. */
+function workerDockerfileOf(worker) {
+	return `.gkm/docker/Dockerfile.${worker}`;
+}
+/**
+* A Worker's Dockerfile: its host app's build, and the worker's bundle as the
+* runner — see `generateWorkerDockerfile`.
+*/
+function workerDockerfile(worker, host, options) {
+	return generateWorkerDockerfile({
+		...appImageOptions(options.layout, worker.app, host, options.workspaceRoot),
+		imageName: worker.name,
+		port: WORKER_PORT,
+		worker: worker.id,
+		bundle: workerBundleName(worker.id),
+		healthCheckPath: "/health"
+	});
+}
 /**
 * A site's Dockerfile, with an `ARG` for every key its bundler inlines.
 *
@@ -5401,7 +6261,7 @@ async function deployDocker(options) {
 	const cwd = options.cwd ?? process.cwd();
 	const docker = {
 		cwd,
-		dockerfile: (0, node_path.join)(cwd, dockerfileOf(config.appName ?? imageName, options.appPath ?? ".")),
+		dockerfile: (0, node_path.join)(cwd, options.dockerfile ?? dockerfileOf(config.appName ?? imageName, options.appPath ?? ".")),
 		...options.signal ? { signal: options.signal } : {},
 		...options.stdio ? { stdio: options.stdio } : {}
 	};
@@ -5733,6 +6593,12 @@ function setPostgresBackupId(state, backupId) {
 	if (state.backups) state.backups.postgresBackupId = backupId;
 }
 //#endregion
+Object.defineProperty(exports, "CronGenerator", {
+	enumerable: true,
+	get: function() {
+		return CronGenerator;
+	}
+});
 Object.defineProperty(exports, "DEFAULT_IMAGES", {
 	enumerable: true,
 	get: function() {
@@ -5787,6 +6653,12 @@ Object.defineProperty(exports, "NoDomainForStage", {
 		return NoDomainForStage;
 	}
 });
+Object.defineProperty(exports, "QueueGenerator", {
+	enumerable: true,
+	get: function() {
+		return QueueGenerator;
+	}
+});
 Object.defineProperty(exports, "STORAGE_KEY_PAIR", {
 	enumerable: true,
 	get: function() {
@@ -5805,6 +6677,18 @@ Object.defineProperty(exports, "UnknownDevService", {
 		return UnknownDevService;
 	}
 });
+Object.defineProperty(exports, "WORKER_PORT", {
+	enumerable: true,
+	get: function() {
+		return WORKER_PORT;
+	}
+});
+Object.defineProperty(exports, "WorkerGenerator", {
+	enumerable: true,
+	get: function() {
+		return WorkerGenerator;
+	}
+});
 Object.defineProperty(exports, "appDockerfile", {
 	enumerable: true,
 	get: function() {
@@ -6381,6 +7265,42 @@ Object.defineProperty(exports, "withGeneratedSecrets", {
 		return withGeneratedSecrets;
 	}
 });
+Object.defineProperty(exports, "workerBundleName", {
+	enumerable: true,
+	get: function() {
+		return workerBundleName;
+	}
+});
+Object.defineProperty(exports, "workerDockerfile", {
+	enumerable: true,
+	get: function() {
+		return workerDockerfile;
+	}
+});
+Object.defineProperty(exports, "workerDockerfileOf", {
+	enumerable: true,
+	get: function() {
+		return workerDockerfileOf;
+	}
+});
+Object.defineProperty(exports, "workerEntryDir", {
+	enumerable: true,
+	get: function() {
+		return workerEntryDir;
+	}
+});
+Object.defineProperty(exports, "workerEnvKeys", {
+	enumerable: true,
+	get: function() {
+		return workerEnvKeys;
+	}
+});
+Object.defineProperty(exports, "workerUnits", {
+	enumerable: true,
+	get: function() {
+		return workerUnits;
+	}
+});
 Object.defineProperty(exports, "workspace_exports", {
 	enumerable: true,
 	get: function() {
@@ -6388,4 +7308,4 @@ Object.defineProperty(exports, "workspace_exports", {
 	}
 });
 
-//# sourceMappingURL=state-CCuTJNRH.cjs.map
+//# sourceMappingURL=state-DMjFPOhf.cjs.map