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

package/dist/{state-BJFherj1.mjs → state-DtS2HEfi.mjs}

@@ -1,16 +1,19 @@
 import { t as __exportAll } from "./rolldown-runtime-BhDjJH2R.mjs";
 import { a as runOutput, i as run$1, s as gkmHome } from "./run-BJLIerMM.mjs";
-import { d as output, r as discover } from "./discover-Buwf1z4P.mjs";
+import { d as output, r as discover, u as ConstructGenerator } from "./discover-BPelzeGW.mjs";
 import { t as appKey } from "./derive-B4vDpzgP.mjs";
 import { O as TEST_STAGE, h as getPublicEnvPrefix, n as allConstructGlobs } from "./workspace-C7NqCsQF.mjs";
 import { ConfigNotFound, NotInAnApp, loadWorkspaceAppInfo, loadWorkspaceConfig } from "./config.mjs";
-import { c as runtimeOf } from "./resolve-BsXEXAUz.mjs";
-import { i as DEFAULT_STORAGE, n as DEFAULT_CACHE, r as DEFAULT_EVENTS$1, t as readFakes } from "./fakes-C9RiT6XG.mjs";
+import { n as runtimeFor, r as generateTelemetryModule } from "./EndpointGenerator-DftalLYg.mjs";
+import { c as runtimeOf } from "./resolve-CV4eQkDa.mjs";
+import { a as DEFAULT_STORAGE, i as DEFAULT_EVENTS$1, n as readFakes, r as DEFAULT_CACHE, t as SubscriberGenerator } from "./SubscriberGenerator-DZk_pKDh.mjs";
 import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 import { constants, existsSync, readFileSync } from "node:fs";
 import { appendFile, chmod, copyFile, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { homedir, networkInterfaces, tmpdir } from "node:os";
 import { promisify } from "node:util";
+import { Cron } from "@geekmidas/constructs/crons";
+import { Queue } from "@geekmidas/constructs/queue";
 import { DEFAULT_POSTGRES_VERSION, cacheTable, cookieDomain, dependenciesOf, dependentsOf, externalApiUrl, kebabCase, mobileOrigins, provideKey, providedKeyFor, provisionOrder, publicEnvFor, schemeBase, scopedName } from "@geekmidas/manifest";
 import { createServer } from "node:net";
 import { execFile, spawn } from "node:child_process";
@@ -1536,11 +1539,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)}
 
@@ -1561,8 +1590,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}
@@ -1571,11 +1600,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}"]
 `;
 }
 /**
@@ -2984,6 +3011,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(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, [...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;
@@ -3000,8 +3057,6 @@ function appEnvKeys(manifest, appName, runnables = {}) {
 			keys.add("AWS_REGION");
 		}
 	}
-	if (declaration.kind === "site" || declaration.kind === "mobile-app") for (const key of Object.keys(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 = {}) {
@@ -4532,6 +4587,707 @@ function localAddress(port) {
 	return `http://localhost:${port}`;
 }
 //#endregion
+//#region src/generators/CronGenerator.ts
+var CronGenerator = class extends 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 = join(outputDir, "crons");
+		await 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: 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 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 mkdir(outputDir, { recursive: true });
+		const cronsPath = join(outputDir, "crons.ts");
+		if (crons.length === 0) {
+			await 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 = relative(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 writeFile(cronsPath, content);
+		return cronsPath;
+	}
+	async generateCronHandler(outputDir, sourceFile, exportName, context, owner) {
+		const handlerFileName = `${exportName}.ts`;
+		const handlerPath = join(outputDir, handlerFileName);
+		const importPath = relative(dirname(handlerPath), sourceFile).replace(/\.ts$/, ".js");
+		const runtime = runtimeFor(context, 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 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 ConstructGenerator {
+	isConstruct(value) {
+		return 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 = join(outputDir, "queues");
+		await 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: 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 = join(outputDir, `${exportName}.ts`);
+		const importPath = relative(dirname(handlerPath), sourceFile).replace(/\.ts$/, ".js");
+		const runtime = runtimeFor(context, 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 writeFile(handlerPath, content);
+		return handlerPath;
+	}
+	async generateServerQueuesFile(outputDir, queues) {
+		await mkdir(outputDir, { recursive: true });
+		const queuesPath = join(outputDir, "queues.ts");
+		if (queues.length === 0) {
+			await 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 = relative(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: '${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 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 join(serverDir, "workers", appKey(workerId));
+}
+/** The file a worker's bundle is written to, beside the server's. */
+function workerBundleName(workerId) {
+	return `worker-${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 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 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 writeFile(join(outputDir, "app.ts"), workerApp(context, workerId, outputDir));
+		await writeFile(join(outputDir, "telemetry.ts"), generateTelemetryModule(context.telemetry ? {
+			...context.telemetry,
+			serviceName: workerId
+		} : void 0));
+		const entry = join(outputDir, "worker.ts");
+		await 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 = 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__ */ __exportAll({
 	encryptSecrets: () => encryptSecrets,
@@ -4584,6 +5340,74 @@ function keyFingerprint(masterKey) {
 	return 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" && appKey(id) === name)?.[1];
+		return {
+			name,
+			root: isAbsolute(app.path) ? app.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 = 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 = relative(dir, file);
+	return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel) ? !rel.startsWith(`..${sep}`) : false;
+}
+//#endregion
 //#region src/deploy/devServices.ts
 /**
 * Mail and object storage on a deployed stage: real ones, or — only when
@@ -5041,7 +5865,7 @@ async function dockerCommand(options) {
 	const cwd = options.cwd ?? process.cwd();
 	const loaded = await 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;
@@ -5093,7 +5917,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}`);
@@ -5123,6 +5947,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 = join(workspace.root, path);
+		await mkdir(dirname(dockerfilePath), { recursive: true });
+		await 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);
@@ -5162,6 +6004,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.
 *
@@ -5399,7 +6259,7 @@ async function deployDocker(options) {
 	const cwd = options.cwd ?? process.cwd();
 	const docker = {
 		cwd,
-		dockerfile: join(cwd, dockerfileOf(config.appName ?? imageName, options.appPath ?? ".")),
+		dockerfile: join(cwd, options.dockerfile ?? dockerfileOf(config.appName ?? imageName, options.appPath ?? ".")),
 		...options.signal ? { signal: options.signal } : {},
 		...options.stdio ? { stdio: options.stdio } : {}
 	};
@@ -5725,6 +6585,6 @@ function setPostgresBackupId(state, backupId) {
 	if (state.backups) state.backups.postgresBackupId = backupId;
 }
 //#endregion
-export { applyPostgres as $, storage_exports as $t, STORAGE_KEY_PAIR as A, findAvailablePort as At, encryptSecrets as B, keystoreProject as Bt, isMainFrontendApp as C, DEFAULT_IMAGES as Ct, DEV_SERVICES as D, primaryPortKey as Dt, otelEnv as E, portKeys as Et, manifestServiceDeclarations as F, isRemoteStore as Ft, constructGlobs as G, imageName as Gt, keyFingerprint as H, readKey as Ht, parseDevServices as I, secretsStoreFor as It, workspace_exports as J, markerOf as Jt, derivedContainers as K, imageRef as Kt, reportDevServices as L, store_exports as Lt, assertExternalServices as M, loadEnvFiles as Mt, devServicesUsed as N, loadSecretsForApp as Nt, DevServicesNeedServerTarget as O, createCredentialsPreload as Ot, externalServices as P, prepareEntryCredentials as Pt, applyPolicies as Q, maskPassword as Qt, requiredStageKeys as R, FileSecretsStore as Rt, NoDomainForStage as S, storageBackendFor as St, isOtlpDestination as T, fakeKey as Tt, FAKE_ENV as U, applicationName as Ut, encryption_exports as V, projectKey as Vt, backendsOf as W, deployIdentity as Wt, forgetState as X, projectName as Xt, LOCAL_CA_PATH as Y, ownershipMarker as Yt, applyBuckets as Z, initStageSecrets as Zt, deployDocker as _, detectPackageManager as _t, recordRelease as a, bucketClient as at, ensureDockerignore as b, eventsBackendFor as bt, setBackupState as c, networkEnv as ct, setGeneratedSecret as d, planFor as dt, toEmbeddableSecrets as en, bucketPolicies as et, setPostgresBackupId as f, resourceName as ft, credentialsFileContent as g, TURBO_VERSION as gt, credentialsBuildArg as h, imageLayout as ht, isDnsVerified as i, composeFor as it, UnknownDevService as j, isPortAvailable as jt, ExternalServicesNotConfigured as k, createEntryWrapper as kt, setDnsRecord as l, envFor as lt, withGeneratedSecrets as m, composeBuildPaths as mt, getBackupState as n, postgresStatements as nt, recordRollback as o, pgClient as ot, DeployJournal as p, hostFor as pt, reconcileWorkspace as q, isOwnedBy as qt, getGeneratedSecret as r, quoteIdentifier as rt, setApplicationId as s, appEnvKeys as st, createEmptyState as t, withCustomSecret as tn, postgresDatabaseNames as tt, setDnsVerification as u, localRolePassword as ut, appDockerfile as v, findBuildRoot as vt, resolveHost as w, describeServices as wt, validateImageRef as x, providerOf as xt, dockerCommand as y, cacheBackendFor as yt, suppliedOnly as z, getKeyPath as zt };
+export { constructGlobs as $, applicationName as $t, DevServicesNeedServerTarget as A, eventsBackendFor as At, requiredStageKeys as B, findAvailablePort as Bt, validateImageRef as C, composeBuildPaths as Ct, isOtlpDestination as D, detectPackageManager as Dt, resolveHost as E, WORKER_PORT as Et, devServicesUsed as F, fakeKey as Ft, keyFingerprint as G, isRemoteStore as Gt, workerUnits as H, loadEnvFiles as Ht, externalServices as I, portKeys as It, workerEntryDir as J, FileSecretsStore as Jt, WorkerGenerator as K, secretsStoreFor as Kt, manifestServiceDeclarations as L, primaryPortKey as Lt, STORAGE_KEY_PAIR as M, storageBackendFor as Mt, UnknownDevService as N, DEFAULT_IMAGES as Nt, otelEnv as O, findBuildRoot as Ot, assertExternalServices as P, describeServices as Pt, backendsOf as Q, readKey as Qt, parseDevServices as R, createCredentialsPreload as Rt, workerDockerfileOf as S, hostFor as St, isMainFrontendApp as T, TURBO_VERSION as Tt, encryptSecrets as U, loadSecretsForApp as Ut, suppliedOnly as V, isPortAvailable as Vt, encryption_exports as W, prepareEntryCredentials as Wt, CronGenerator as X, keystoreProject as Xt, QueueGenerator as Y, getKeyPath as Yt, FAKE_ENV as Z, projectKey as Zt, deployDocker as _, workerEnvKeys as _t, recordRelease as a, ownershipMarker as an, applyBuckets as at, ensureDockerignore as b, planFor as bt, setBackupState as c, maskPassword as cn, bucketPolicies as ct, setGeneratedSecret as d, withCustomSecret as dn, quoteIdentifier as dt, deployIdentity as en, derivedContainers as et, setPostgresBackupId as f, composeFor as ft, credentialsFileContent as g, networkEnv as gt, credentialsBuildArg as h, appEnvKeys as ht, isDnsVerified as i, markerOf as in, forgetState as it, ExternalServicesNotConfigured as j, providerOf as jt, DEV_SERVICES as k, cacheBackendFor as kt, setDnsRecord as l, storage_exports as ln, postgresDatabaseNames as lt, withGeneratedSecrets as m, pgClient as mt, getBackupState as n, imageRef as nn, workspace_exports as nt, recordRollback as o, projectName as on, applyPolicies as ot, DeployJournal as p, bucketClient as pt, workerBundleName as q, store_exports as qt, getGeneratedSecret as r, isOwnedBy as rn, LOCAL_CA_PATH as rt, setApplicationId as s, initStageSecrets as sn, applyPostgres as st, createEmptyState as t, imageName as tn, reconcileWorkspace as tt, setDnsVerification as u, toEmbeddableSecrets as un, postgresStatements as ut, appDockerfile as v, envFor as vt, NoDomainForStage as w, imageLayout as wt, workerDockerfile as x, resourceName as xt, dockerCommand as y, localRolePassword as yt, reportDevServices as z, createEntryWrapper as zt };
 
-//# sourceMappingURL=state-BJFherj1.mjs.map
+//# sourceMappingURL=state-DtS2HEfi.mjs.map