@pattern-stack/codegen 0.23.0 → 0.25.0

package/templates/subsystem/jobs/prompt.js

@@ -9,9 +9,10 @@
  * Invoked via:
  *   bunx hygen subsystem jobs \
  *     --workerPath <abs> --workerExists <'true'|''> \
+ *     --jobWorkerModuleImport <specifier> --workerForRootOpts <ts-literal> \
  *     --mainTsPath <abs> --configPath <abs> --schemaPath <abs> \
  *     --multiTenant <'true'|'false'> --workerMode <embedded|standalone> \
- *     --appName <string>
+ *     --skipSchema <'true'|''> --appName <string>
  */
 
 import { renderGeneratedBanner } from "../../_shared/generated-banner.mjs";
@@ -23,6 +24,28 @@ function coerceBool(raw) {
   return false;
 }
 
+// #513: the CLI base64-encodes --workerForRootOpts because Hygen's yargs parser
+// mangles a raw `{ mode: 'standalone', … }` TS literal (the braces/colons are
+// read as nested object syntax). Decode it back to the source string here. A
+// direct hygen invocation that passes a non-encoded value (or omits it) falls
+// back to the plain default below.
+function decodeWorkerForRootOpts(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    return "{ mode: 'standalone', allPools: true }";
+  }
+  try {
+    const decoded = Buffer.from(raw, "base64").toString("utf-8");
+    // Re-encoding round-trips iff `raw` was valid base64 of the decoded bytes;
+    // guards against a hand-passed plain literal being treated as base64.
+    if (Buffer.from(decoded, "utf-8").toString("base64") === raw) {
+      return decoded;
+    }
+  } catch {
+    /* fall through to raw */
+  }
+  return raw;
+}
+
 export default {
   prompt: async ({ args }) => {
     return {
@@ -34,9 +57,24 @@ export default {
       // Hygen's skip_if treats any non-empty string as truthy, so we send an
       // empty string when the file doesn't exist (CLI already does this).
       workerExists: args.workerExists ?? "",
-      workerPath: args.workerPath ?? "worker.ts",
+      // #513: the worker lands at `src/worker.ts` (inside the default tsconfig
+      // include, next to `app.module.ts`); the CLI always passes an absolute
+      // --workerPath, this fallback only guards a direct hygen invocation.
+      workerPath: args.workerPath ?? "src/worker.ts",
+      // #513: mode-aware JobWorkerModule import + the pre-serialised
+      // forRoot(<opts>) literal (the only mode-dependent import the worker
+      // carries — AppModule is imported relatively).
+      jobWorkerModuleImport:
+        args.jobWorkerModuleImport ??
+        "@pattern-stack/codegen/runtime/subsystems/jobs/index",
+      workerForRootOpts: decodeWorkerForRootOpts(args.workerForRootOpts),
       schemaPath:
         args.schemaPath ?? "shared/subsystems/jobs/job-orchestration.schema.ts",
+      // #517: package mode skips the schema template (the schema ships in the
+      // package, re-exported via the schema barrel). Hygen's skip_if treats any
+      // non-empty string as truthy, so the CLI sends '' in vendored mode and
+      // 'true' in package mode. Default '' so a direct hygen invocation renders.
+      skipSchema: args.skipSchema ?? "",
       // @generated DO-NOT-EDIT banner — the jobs subsystem schema is
       // force-overwritten on every `subsystem install`.
       generatedBanner: renderGeneratedBanner({

package/templates/subsystem/jobs/worker.ejs.t

@@ -5,31 +5,42 @@ unless_exists: true
 /**
  * Standalone job worker entrypoint — emitted by `codegen subsystem install jobs`.
  *
- * Boots a Nest application context (NO HTTP listener) wiring the full
- * subsystem barrel (`SUBSYSTEM_MODULES` — events + jobs + bridge + integration, in
- * dependency order) plus `JobWorkerModule.forRoot({ mode: 'standalone',
- * allPools: true })`. Run with:
+ * Boots a Nest application context (NO HTTP listener) that composes the
+ * consumer's root `AppModule` plus `JobWorkerModule.forRoot({ mode:
+ * 'standalone', allPools: true, … })`. Run with:
  *
- *   bun worker.ts
+ *   bun src/worker.ts
  *
- * Why the barrel + `allPools`:
- *   - The events subsystem's outbox drain and the bridge's fanout wrappers
- *     run as `job_run` rows in the RESERVED `events_*` pools. A worker that
- *     only polls the non-reserved pools (`interactive`, `batch`, …) leaves
- *     those lanes stranded — `BridgeDeliveryHandler` never fires and durable
- *     event→job fanout silently stops.
+ * Why import `AppModule` whole:
+ *   - Job handlers are Nest providers registered by the consumer's handler
+ *     modules (and the subsystem barrel). Composing around `AppModule` gives
+ *     this worker the SAME DI graph as the HTTP process — every `@JobHandler`
+ *     resolves its dependencies here exactly as it would in the API. A bare
+ *     `SUBSYSTEM_MODULES`-only worker boots with an empty handler surface.
+ *   - `AppModule` already wires `DatabaseModule` + `SUBSYSTEM_MODULES` (events +
+ *     jobs + bridge + integration, dependency-ordered), so the worker needs no
+ *     mode-aware barrel import — only `JobWorkerModule` itself.
+ *
+ * Why `allPools: true`:
+ *   - The events subsystem's outbox drain and the bridge's fanout wrappers run
+ *     as `job_run` rows in the RESERVED `events_*` pools. A worker that only
+ *     polls the non-reserved pools (`interactive`, `batch`, …) strands those
+ *     lanes — `BridgeDeliveryHandler` never fires and durable event→job fanout
+ *     silently stops.
  *   - `allPools: true` activates every pool in the resolved config, reserved
  *     lanes included, so this single standalone process drains both user work
  *     and the framework's reserved lanes.
- *   - Importing `SUBSYSTEM_MODULES` (rather than `JobsDomainModule` alone)
- *     registers `EVENT_BUS` / `JOB_ORCHESTRATOR` / `BRIDGE_*` so the
- *     framework `@framework/bridge_delivery` handler resolves its DI deps.
- *     `BridgeModule`'s reserved-pool guard short-circuits to pass because
- *     `allPools` is set.
  *
- * Embedded mode (single-process) is configured by importing
- * `JobWorkerModule.forRoot({ mode: 'embedded' })` inside AppModule instead —
- * see the commented guidance injected into `src/main.ts`.
+ * STANDALONE ONLY: this entrypoint is for `jobs.worker_mode: standalone`. In
+ * embedded mode the worker already runs inside `AppModule` (via the
+ * `JobWorkerModule.forRoot({ mode: 'embedded' })` the barrel composes), so
+ * booting this file too would double-spawn the worker against the same pools.
+ *
+ * DO NOT boot `AppModule` twice in one process: a consumer `AppModule`
+ * registers an OpenAPI document against the per-process `OpenApiRegistry`
+ * singleton, which throws `DuplicateSchemaError` on the second registration.
+ * Multi-rung boot validation (e.g. "does the worker boot AND does the API
+ * boot?") must spawn CHILD PROCESSES, not import both modules into one.
  *
  * SIGTERM triggers graceful shutdown bounded by SHUTDOWN_TIMEOUT_MS; after the
  * timeout the process exits hard so orchestrators (systemd, Kubernetes) can
@@ -39,26 +50,23 @@ import 'reflect-metadata';
 import { Logger, Module } from '@nestjs/common';
 import { NestFactory } from '@nestjs/core';
 
-import { DatabaseModule } from '@shared/database/database.module';
-import { JobWorkerModule } from '@shared/subsystems/jobs/job-worker.module';
-import { SUBSYSTEM_MODULES } from '@generated/subsystems';
+import { AppModule } from './app.module';
+import { JobWorkerModule } from '<%= jobWorkerModuleImport %>';
 
 const SHUTDOWN_TIMEOUT_MS = 30_000;
 
 @Module({
   imports: [
-    DatabaseModule,
-    // Events + Jobs + Bridge + Integration (dependency-ordered) from the generated
-    // barrel. This is the same composition AppModule imports — keeping the
-    // worker's DI graph identical to the HTTP app's so handlers resolve the
-    // same way in both processes.
-    ...SUBSYSTEM_MODULES,
+    // Consumer root — DatabaseModule + SUBSYSTEM_MODULES + handler modules.
+    // Importing it whole keeps the worker's DI graph identical to the HTTP app's
+    // so every `@JobHandler` resolves the same way in both processes.
+    AppModule,
     // `allPools: true` drains the reserved `events_*` lanes (events outbox +
     // bridge wrappers) alongside the user pools.
-    JobWorkerModule.forRoot({ mode: 'standalone', allPools: true }),
+    JobWorkerModule.forRoot(<%- workerForRootOpts %>),
   ],
 })
-class WorkerAppModule {}
+export class WorkerAppModule {}
 
 async function bootstrap(): Promise<void> {
   const logger = new Logger('JobWorker');
@@ -98,8 +106,12 @@ async function bootstrap(): Promise<void> {
   logger.log('job worker started (standalone mode, all pools)');
 }
 
-bootstrap().catch((err) => {
-  // eslint-disable-next-line no-console
-  console.error('failed to bootstrap job worker', err);
-  process.exit(1);
-});
+// Gated so the module can be imported by boot-checks / e2e without spawning a
+// worker; `bun src/worker.ts` runs it as the entrypoint.
+if (import.meta.main) {
+  bootstrap().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error('failed to bootstrap job worker', err);
+    process.exit(1);
+  });
+}