@pattern-stack/codegen 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/runtime/base-classes/lifecycle-events.ts

@@ -23,8 +23,17 @@
  */
 
 import { randomUUID } from 'crypto';
+import { Logger } from '@nestjs/common';
 import type { IEventBus, DomainEvent } from '../subsystems/events/event-bus.protocol';
 
+/**
+ * Module-level logger for fire-and-forget emission failures. Routed through the
+ * Nest `Logger` (not bare `console`) so consumers configuring `app.useLogger`
+ * or the factory `logger:` option can format and filter it like any other
+ * framework log line.
+ */
+const logger = new Logger('LifecycleEvents');
+
 // ============================================================================
 // Event categories (subset of pattern-stack's EventCategory)
 // ============================================================================
@@ -99,7 +108,17 @@ export function buildLifecycleEvent(
 		aggregateType: entityName,
 		payload: snapshot ? { snapshot } : {},
 		occurredAt: new Date(),
-		metadata: { category: 'lifecycle' as EventCategory },
+		// AUDIT tier: lifecycle/change events are untyped audit-trail records —
+		// never bridge-routed, no pool/direction. The `domain_events`
+		// `domain_events_tier_routing_check` CHECK requires `tier='audit' ⇔
+		// (pool IS NULL AND direction IS NULL)`; the DEFAULT `tier='domain'`
+		// (applied by toInsertValues when absent) requires non-null routing
+		// fields, so an un-tiered lifecycle row violates the constraint and the
+		// INSERT is rejected — silently, pre-fix, by emitSafely's catch. Stamp
+		// `tier:'audit'` so these rows land (and surface under the
+		// observability viewer's audit-tier toggle). The bridge guard keeps
+		// audit-tier events out of job routing.
+		metadata: { category: 'lifecycle' as EventCategory, tier: 'audit' },
 	};
 }
 
@@ -119,7 +138,9 @@ export function buildChangeEvents(
 			newValue: c.newValue,
 		},
 		occurredAt: new Date(),
-		metadata: { category: 'change' as EventCategory },
+		// AUDIT tier — see buildLifecycleEvent. Change events are audit-trail
+		// records; tier:'audit' satisfies the tier-routing CHECK constraint.
+		metadata: { category: 'change' as EventCategory, tier: 'audit' },
 	}));
 }
 
@@ -144,9 +165,21 @@ export async function emitSafely(
 		} else {
 			await eventBus.publishMany(events);
 		}
-	} catch {
-		// Log but never fail the CRUD operation.
-		// In production, this would use a structured logger.
-		console.warn(`[lifecycle-events] failed to emit ${events.length} event(s)`);
+	} catch (err) {
+		// Never fail the CRUD operation — but surface the cause. The bare
+		// `catch` that used to live here swallowed the error entirely, so a
+		// failing bus printed `failed to emit N event(s)` with zero
+		// diagnosability. Route through the Nest Logger (not bare console) at
+		// warn level, including the distinct event types and the error message;
+		// the stack follows at debug so it's available without noising the
+		// default-threshold output.
+		const message = err instanceof Error ? err.message : String(err);
+		const types = [...new Set(events.map((e) => e.type))].join(', ');
+		logger.warn(
+			`failed to emit ${events.length} event(s) [${types}]: ${message}`,
+		);
+		if (err instanceof Error && err.stack) {
+			logger.debug(err.stack);
+		}
 	}
 }

package/templates/subsystem/jobs/job-orchestration.schema.ejs.t

@@ -1,6 +1,7 @@
 ---
 to: "<%= schemaPath %>"
 force: true
+skip_if: "<%= skipSchema %>"
 ---
 <%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**

package/templates/subsystem/jobs/main-hook.ejs.t

@@ -7,5 +7,5 @@ skip_if: "<%= mainHookInjected %>"
   // JOBS — Embedded worker mode (optional)
   // To run the job worker in-process (single-process deploy), add to AppModule imports:
   //   JobWorkerModule.forRoot({ mode: 'embedded' })
-  // For standalone worker (separate process), use worker.ts at the project root.
+  // For standalone worker (separate process), run src/worker.ts (bun src/worker.ts).
   // See codegen.config.yaml jobs.worker_mode to toggle the documented default.

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);
+  });
+}

package/dist/chunk-KYR3B3OW.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../runtime/base-classes/lifecycle-events.ts"],"sourcesContent":["/**\n * Lifecycle event emission for BaseService.\n *\n * Ported from pattern-stack/atoms/patterns/services/base.py — the Python\n * BaseService emits LIFECYCLE and CHANGE events on every CRUD operation.\n * This module provides the same capability for the TypeScript codegen stack.\n *\n * Design:\n *   - Fire-and-forget: event emission never fails the CRUD operation.\n *   - IEventBus is optional: if no EVENT_BUS is injected, emission is silently\n *     skipped. This means base classes work in projects that haven't installed\n *     the events subsystem.\n *   - LIFECYCLE events carry an entity snapshot in payload.\n *   - CHANGE events carry per-field old/new diffs.\n *   - Controlled per-entity via `emitLifecycleEvents` flag (default: true).\n *\n * @deprecated EVT-7 — Lifecycle events are untyped and emit outside of the\n *   CRUD transaction. New work should declare an `emits:` block on the entity\n *   and publish typed domain events from use-cases via TYPED_EVENT_BUS inside\n *   the same Drizzle transaction. See `docs/specs/EVT-7.md`. This helper is\n *   retained for BaseService backward compatibility until all entities have\n *   migrated to typed emits.\n */\n\nimport { randomUUID } from 'crypto';\nimport type { IEventBus, DomainEvent } from '../subsystems/events/event-bus.protocol';\n\n// ============================================================================\n// Event categories (subset of pattern-stack's EventCategory)\n// ============================================================================\n\nexport type EventCategory = 'lifecycle' | 'change';\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\n/** System fields excluded from entity snapshots and change diffs. */\nconst SYSTEM_FIELDS = new Set([\n\t'id',\n\t'createdAt',\n\t'updatedAt',\n\t'deletedAt',\n]);\n\n/**\n * Snapshot an entity's field values, excluding system fields.\n * Mirrors pattern-stack's `_get_entity_snapshot()`.\n */\nexport function entitySnapshot(entity: Record<string, unknown>): Record<string, unknown> {\n\tconst snap: Record<string, unknown> = {};\n\tfor (const [key, value] of Object.entries(entity)) {\n\t\tif (!SYSTEM_FIELDS.has(key)) {\n\t\t\tsnap[key] = value;\n\t\t}\n\t}\n\treturn snap;\n}\n\n/**\n * Diff two entity snapshots, returning per-field old/new pairs.\n * Only includes fields that actually changed.\n */\nexport function diffSnapshots(\n\tbefore: Record<string, unknown>,\n\tafter: Record<string, unknown>,\n): Array<{ field: string; oldValue: unknown; newValue: unknown }> {\n\tconst changes: Array<{ field: string; oldValue: unknown; newValue: unknown }> = [];\n\tconst allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);\n\n\tfor (const key of allKeys) {\n\t\tif (SYSTEM_FIELDS.has(key)) continue;\n\t\tconst oldVal = before[key];\n\t\tconst newVal = after[key];\n\t\t// Simple equality — good enough for primitives and nulls.\n\t\t// For deep objects, JSON.stringify comparison.\n\t\tif (oldVal !== newVal && JSON.stringify(oldVal) !== JSON.stringify(newVal)) {\n\t\t\tchanges.push({ field: key, oldValue: oldVal, newValue: newVal });\n\t\t}\n\t}\n\n\treturn changes;\n}\n\n// ============================================================================\n// Event builders\n// ============================================================================\n\nexport function buildLifecycleEvent(\n\tentityName: string,\n\taction: 'created' | 'updated' | 'deleted',\n\tentityId: string,\n\tsnapshot?: Record<string, unknown>,\n): DomainEvent {\n\treturn {\n\t\tid: randomUUID(),\n\t\ttype: `${entityName}.${action}`,\n\t\taggregateId: entityId,\n\t\taggregateType: entityName,\n\t\tpayload: snapshot ? { snapshot } : {},\n\t\toccurredAt: new Date(),\n\t\tmetadata: { category: 'lifecycle' as EventCategory },\n\t};\n}\n\nexport function buildChangeEvents(\n\tentityName: string,\n\tentityId: string,\n\tchanges: Array<{ field: string; oldValue: unknown; newValue: unknown }>,\n): DomainEvent[] {\n\treturn changes.map((c) => ({\n\t\tid: randomUUID(),\n\t\ttype: `${entityName}.field_changed`,\n\t\taggregateId: entityId,\n\t\taggregateType: entityName,\n\t\tpayload: {\n\t\t\tfieldName: c.field,\n\t\t\toldValue: c.oldValue,\n\t\t\tnewValue: c.newValue,\n\t\t},\n\t\toccurredAt: new Date(),\n\t\tmetadata: { category: 'change' as EventCategory },\n\t}));\n}\n\n// ============================================================================\n// Emission helper (fire-and-forget)\n// ============================================================================\n\n/**\n * Emit events to the bus, swallowing errors.\n * Mirrors pattern-stack's `_emit_lifecycle_event()` try/except.\n */\nexport async function emitSafely(\n\teventBus: IEventBus | undefined,\n\tevents: DomainEvent[],\n): Promise<void> {\n\tif (!eventBus || events.length === 0) return;\n\ttry {\n\t\tif (events.length === 1) {\n\t\t\tconst only = events[0];\n\t\t\tif (!only) return;\n\t\t\tawait eventBus.publish(only);\n\t\t} else {\n\t\t\tawait eventBus.publishMany(events);\n\t\t}\n\t} catch {\n\t\t// Log but never fail the CRUD operation.\n\t\t// In production, this would use a structured logger.\n\t\tconsole.warn(`[lifecycle-events] failed to emit ${events.length} event(s)`);\n\t}\n}\n"],"mappings":";AAwBA,SAAS,kBAAkB;AAc3B,IAAM,gBAAgB,oBAAI,IAAI;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACD,CAAC;AAMM,SAAS,eAAe,QAA0D;AACxF,QAAM,OAAgC,CAAC;AACvC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AAClD,QAAI,CAAC,cAAc,IAAI,GAAG,GAAG;AAC5B,WAAK,GAAG,IAAI;AAAA,IACb;AAAA,EACD;AACA,SAAO;AACR;AAMO,SAAS,cACf,QACA,OACiE;AACjE,QAAM,UAA0E,CAAC;AACjF,QAAM,UAAU,oBAAI,IAAI,CAAC,GAAG,OAAO,KAAK,MAAM,GAAG,GAAG,OAAO,KAAK,KAAK,CAAC,CAAC;AAEvE,aAAW,OAAO,SAAS;AAC1B,QAAI,cAAc,IAAI,GAAG,EAAG;AAC5B,UAAM,SAAS,OAAO,GAAG;AACzB,UAAM,SAAS,MAAM,GAAG;AAGxB,QAAI,WAAW,UAAU,KAAK,UAAU,MAAM,MAAM,KAAK,UAAU,MAAM,GAAG;AAC3E,cAAQ,KAAK,EAAE,OAAO,KAAK,UAAU,QAAQ,UAAU,OAAO,CAAC;AAAA,IAChE;AAAA,EACD;AAEA,SAAO;AACR;AAMO,SAAS,oBACf,YACA,QACA,UACA,UACc;AACd,SAAO;AAAA,IACN,IAAI,WAAW;AAAA,IACf,MAAM,GAAG,UAAU,IAAI,MAAM;AAAA,IAC7B,aAAa;AAAA,IACb,eAAe;AAAA,IACf,SAAS,WAAW,EAAE,SAAS,IAAI,CAAC;AAAA,IACpC,YAAY,oBAAI,KAAK;AAAA,IACrB,UAAU,EAAE,UAAU,YAA6B;AAAA,EACpD;AACD;AAEO,SAAS,kBACf,YACA,UACA,SACgB;AAChB,SAAO,QAAQ,IAAI,CAAC,OAAO;AAAA,IAC1B,IAAI,WAAW;AAAA,IACf,MAAM,GAAG,UAAU;AAAA,IACnB,aAAa;AAAA,IACb,eAAe;AAAA,IACf,SAAS;AAAA,MACR,WAAW,EAAE;AAAA,MACb,UAAU,EAAE;AAAA,MACZ,UAAU,EAAE;AAAA,IACb;AAAA,IACA,YAAY,oBAAI,KAAK;AAAA,IACrB,UAAU,EAAE,UAAU,SAA0B;AAAA,EACjD,EAAE;AACH;AAUA,eAAsB,WACrB,UACA,QACgB;AAChB,MAAI,CAAC,YAAY,OAAO,WAAW,EAAG;AACtC,MAAI;AACH,QAAI,OAAO,WAAW,GAAG;AACxB,YAAM,OAAO,OAAO,CAAC;AACrB,UAAI,CAAC,KAAM;AACX,YAAM,SAAS,QAAQ,IAAI;AAAA,IAC5B,OAAO;AACN,YAAM,SAAS,YAAY,MAAM;AAAA,IAClC;AAAA,EACD,QAAQ;AAGP,YAAQ,KAAK,qCAAqC,OAAO,MAAM,WAAW;AAAA,EAC3E;AACD;","names":[]}