@pattern-stack/codegen 0.7.5 → 0.7.6

package/templates/junction/new/prompt.js

@@ -17,6 +17,7 @@ import fs from "node:fs";
 import path from "node:path";
 import yaml from "yaml";
 import pluralizePkg from "pluralize";
+import { renderGeneratedBanner } from "../../_shared/generated-banner.mjs";
 
 // ============================================================================
 // Naming Helpers (inlined to avoid import issues with Hygen)
@@ -376,6 +377,63 @@ export default {
     const leftEntityCamel = camelCase(leftEntity);
     const rightEntityCamel = camelCase(rightEntity);
 
+    // ======================================================================
+    // Inbound-sync write surface (#374)
+    // ======================================================================
+    // The junction sync identity is the tuple (leftId, rightId[, role]); its
+    // externalId is a COMPOSITE string. Both parent FKs resolve strictly. FK
+    // write-keys use `${camelCase(entity)}ExternalId` (matches the reference).
+
+    const leftSyncWriteKey = `${leftEntityCamel}ExternalId`;
+    const rightSyncWriteKey = `${rightEntityCamel}ExternalId`;
+    const roleColumnCamel = hasRole ? 'role' : null;
+    // Role TS type — literal union from the enum choices, else absent.
+    const roleTsType = hasRole
+      ? roleChoices.map((c) => `'${c}'`).join(' | ')
+      : null;
+
+    // JunctionSyncConfig literal fields. refTable is emitted as a live table
+    // identifier (leftTable/rightTable) by the template.
+    const syncConfig = {
+      leftColumn: leftColumnCamel,
+      leftRefTable: leftTable,
+      rightColumn: rightColumnCamel,
+      rightRefTable: rightTable,
+      roleColumn: roleColumnCamel,
+    };
+
+    // TSyncWrite fields: both parent external ids + optional role + userId.
+    const syncWriteFields = [
+      { name: leftSyncWriteKey, tsType: 'string' },
+      { name: rightSyncWriteKey, tsType: 'string' },
+      ...(hasRole ? [{ name: 'role', tsType: roleTsType }] : []),
+      { name: 'userId', tsType: 'string' },
+    ];
+
+    // TSyncProjection fields: composite id + local FK columns + optional role +
+    // timestamps. No surrogate id column on a junction.
+    const syncProjectionFields = [
+      { name: 'id', tsType: 'string' },
+      { name: leftColumnCamel, tsType: 'string' },
+      { name: rightColumnCamel, tsType: 'string' },
+      ...(hasRole ? [{ name: 'role', tsType: roleTsType }] : []),
+      { name: 'createdAt', tsType: 'Date' },
+      { name: 'updatedAt', tsType: 'Date' },
+    ];
+
+    // Parent-table imports for the FK resolvers, deduped (#368). Junction
+    // endpoints are distinct by schema, so two imports unless they collide.
+    const syncParentImports = [];
+    const seenSyncImports = new Set();
+    for (const imp of [
+      { table: leftTable, importPath: leftEntityImportFromJunction },
+      { table: rightTable, importPath: rightEntityImportFromJunction },
+    ]) {
+      if (seenSyncImports.has(imp.table)) continue;
+      seenSyncImports.add(imp.table);
+      syncParentImports.push(imp);
+    }
+
     // ======================================================================
     // Class names
     // ======================================================================
@@ -391,7 +449,20 @@ export default {
     // Return all template locals
     // ======================================================================
 
+    // @generated DO-NOT-EDIT banner — stamped at the top of every
+    // force-overwritten junction output. `yamlPath` is the consumer-relative
+    // source definition.
+    const generatedBanner = renderGeneratedBanner({
+      // Relative to cwd so the banner is portable across machines.
+      source: path.relative(cwd, fullPath),
+      generator: 'junction',
+      seam: 'the junction YAML',
+    });
+
     return {
+      // @generated DO-NOT-EDIT banner (see renderGeneratedBanner)
+      generatedBanner,
+
       // Identity
       name: junctionName,
       entityNamePascal,
@@ -451,6 +522,18 @@ export default {
       leftTable,
       rightTable,
 
+      // ──────────────────────────────────────────────────────────────────
+      // Inbound-sync write surface (#374)
+      // ──────────────────────────────────────────────────────────────────
+      leftSyncWriteKey,
+      rightSyncWriteKey,
+      roleColumnCamel,
+      roleTsType,
+      junctionSyncConfig: syncConfig,
+      syncWriteFields,
+      syncProjectionFields,
+      syncParentImports,
+
       // ──────────────────────────────────────────────────────────────────
       // CGP-60 — fan-out locals
       // ──────────────────────────────────────────────────────────────────

package/templates/junction/new/repository.ejs.t

@@ -2,15 +2,47 @@
 to: "<%= outputPaths.repository %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable, Inject } from '@nestjs/common';
 import { eq } from 'drizzle-orm';
 import { DRIZZLE } from '@shared/constants/tokens';
 import type { DrizzleClient } from '@shared/types/drizzle';
-import { BaseRepository } from '@shared/base-classes/base-repository';
+import { JunctionSyncRepository } from '@shared/base-classes/junction-sync-repository';
+import type { JunctionSyncConfig } from '@shared/base-classes/junction-sync-repository';
+<%_ syncParentImports.forEach((imp) => { _%>
+import { <%= imp.table %> } from '<%= imp.importPath %>';
+<%_ }); _%>
 import { <%= tableVarName %>, type <%= classNames.entity %> } from './<%= name %>.entity';
 
+/**
+ * Canonical fields a synced <%= name %> junction write carries (#374). BOTH
+ * parent FKs are named by their vendor external ids and resolved STRICTLY in
+ * the tx (a missing parent throws → the orchestrator records a failed item and
+ * continues). `userId` is run context (no column on the junction).
+ */
+export interface <%= classNames.entity %>SyncWrite {
+<%_ syncWriteFields.forEach((f) => { _%>
+  readonly <%= f.name %>: <%- f.tsType %>;
+<%_ }); _%>
+}
+
+/**
+ * Canonical-projected view of a <%= name %> junction row, keyed for the sync
+ * differ (#374). `id` is the COMPOSITE externalId (the junction has no
+ * surrogate id); the FKs are the LOCAL resolved uuids.
+ */
+export interface <%= classNames.entity %>SyncProjection {
+<%_ syncProjectionFields.forEach((f) => { _%>
+  readonly <%= f.name %>: <%- f.tsType %>;
+<%_ }); _%>
+}
+
 @Injectable()
-export class <%= classNames.repository %> extends BaseRepository<<%= classNames.entity %>> {
+export class <%= classNames.repository %> extends JunctionSyncRepository<
+  <%= classNames.entity %>,
+  <%= classNames.entity %>SyncWrite,
+  <%= classNames.entity %>SyncProjection
+> {
   readonly table = <%= tableVarName %>;
 
   // Junctions track temporal validity via started_at / ended_at, NOT via
@@ -21,6 +53,14 @@ export class <%= classNames.repository %> extends BaseRepository<<%= classNames.
     userTracking: false,
   };
 
+  // Inbound-sync write surface (#374). Both endpoints resolve strictly against
+  // the live parent tables; role-bearing junctions conflict on (left,right,role).
+  protected readonly syncConfig: JunctionSyncConfig = {
+    left: { column: '<%= junctionSyncConfig.leftColumn %>', refTable: <%= junctionSyncConfig.leftRefTable %> },
+    right: { column: '<%= junctionSyncConfig.rightColumn %>', refTable: <%= junctionSyncConfig.rightRefTable %> },
+    roleColumn: <%- junctionSyncConfig.roleColumn ? `'${junctionSyncConfig.roleColumn}'` : 'null' %>,
+  };
+
   constructor(@Inject(DRIZZLE) db: DrizzleClient) {
     super(db);
   }
@@ -62,6 +102,7 @@ export class <%= classNames.repository %> extends BaseRepository<<%= classNames.
     return rows as <%= classNames.entity %>[];
   }
 
-  // Inherited from BaseRepository:
+  // Inherited from JunctionSyncRepository (+ BaseRepository):
   //   findById, findByIds, list, count, exists, create, update, delete, upsertMany
+  //   syncUpsertOne, findByExternalIdProjected, softDeleteByExternalId
 }

package/templates/junction/new/service.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.service %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable, Inject, Optional } from '@nestjs/common';
 import { WithAnalytics } from '@shared/base-classes/with-analytics';
 import { EVENT_BUS } from '@shared/constants/tokens';

package/templates/relationship/new/controller.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.controller %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Controller, Get, Param } from '@nestjs/common';
 import { <%= classNames.findByIdUseCase %> } from './use-cases/find-<%= name %>-by-id.use-case';
 import { <%= classNames.listUseCase %> } from './use-cases/list-<%= entityNamePlural %>.use-case';

package/templates/relationship/new/dto/create.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.createDto %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { z } from 'zod';
 <%_ if (hasTypes) { _%>
 import { <%= typeEnumName %> } from '../<%= name %>.entity';

package/templates/relationship/new/dto/output.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.outputDto %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { z } from 'zod';
 
 export const <%= classNames.outputSchema %> = z.object({

package/templates/relationship/new/dto/update.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.updateDto %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { z } from 'zod';
 import { <%= classNames.createSchema %> } from './create-<%= name %>.dto';
 

package/templates/relationship/new/entity.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.entity %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import {
 <%_ drizzleImports.filter(i => i !== 'relations').forEach(i => { _%>
   <%= i %>,

package/templates/relationship/new/index.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.index %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= classNames.entity %> module barrel export
  * Generated by relationship codegen - do not edit directly

package/templates/relationship/new/module.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.module %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Module } from '@nestjs/common';
 import { DatabaseModule } from '@shared/database/database.module';
 

package/templates/relationship/new/prompt.js

@@ -12,6 +12,7 @@ import fs from "node:fs";
 import path from "node:path";
 import yaml from "yaml";
 import pluralizePkg from "pluralize";
+import { renderGeneratedBanner } from "../../_shared/generated-banner.mjs";
 
 // ============================================================================
 // Naming Helpers (inlined to avoid import issues with Hygen)
@@ -591,7 +592,20 @@ export default {
     // Return all template locals
     // ======================================================================
 
+    // @generated DO-NOT-EDIT banner — stamped at the top of every
+    // force-overwritten relationship output. `yamlPath` is the
+    // consumer-relative source definition.
+    const generatedBanner = renderGeneratedBanner({
+      // Relative to cwd so the banner is portable across machines.
+      source: path.relative(process.cwd(), fullPath),
+      generator: 'relationship',
+      seam: 'the relationship YAML',
+    });
+
     return {
+      // @generated DO-NOT-EDIT banner (see renderGeneratedBanner)
+      generatedBanner,
+
       // Identity
       name,
       entityNamePascal,

package/templates/relationship/new/repository.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.repository %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable, Inject } from '@nestjs/common';
 <% if (hasDeclarativeQueries) { -%>
 import { eq<%= hasMultiFieldQuery ? ', and' : '' %><%= hasOrderedQuery ? ', desc, asc' : '' %> } from 'drizzle-orm';

package/templates/relationship/new/service.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.service %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable, Inject, Optional } from '@nestjs/common';
 import { WithAnalytics } from '@shared/base-classes/with-analytics';
 import { EVENT_BUS } from '@shared/constants/tokens';

package/templates/relationship/new/use-cases/declarative-queries.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= hasDeclarativeQueries ? outputPaths.declarativeQueries : null %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (hasDeclarativeQueries) { -%>
 /**
  * Declarative Query Use Cases for <%= classNames.entity %>

package/templates/relationship/new/use-cases/find-by-id.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.findByIdUseCase %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable } from '@nestjs/common';
 import { <%= classNames.service %> } from '../<%= name %>.service';
 import type { <%= classNames.entity %> } from '../<%= name %>.entity';

package/templates/relationship/new/use-cases/list.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= outputPaths.listUseCase %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable } from '@nestjs/common';
 import { <%= classNames.service %> } from '../<%= name %>.service';
 import type { <%= classNames.entity %> } from '../<%= name %>.entity';

package/templates/subsystem/auth/auth-oauth-state.schema.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= schemaPath %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 // Schema barrel append tracked in #284 — same gap as events/jobs/sync today.
 /**
  * Drizzle schema for the `auth_oauth_state` table — backs the

package/templates/subsystem/auth/prompt.js

@@ -29,6 +29,8 @@
  * Auth has NO `multi_tenant` knob (see auth-scaffold-locals.ts docstring).
  */
 
+import { renderGeneratedBanner } from "../../_shared/generated-banner.mjs";
+
 export default {
   prompt: async ({ args }) => {
     return {
@@ -41,6 +43,12 @@ export default {
       envConfigPath: args.envConfigPath ?? ".env.config",
       redirectUriBase: args.redirectUriBase ?? "http://localhost:3000",
       tokenEncryptionKey: args.tokenEncryptionKey ?? "",
+      // @generated DO-NOT-EDIT banner — the auth subsystem schema is
+      // force-overwritten on every `subsystem install`.
+      generatedBanner: renderGeneratedBanner({
+        generator: "subsystem auth",
+        seam: "the codegen.config.yaml auth block, then re-run `codegen subsystem install`",
+      }),
     };
   },
 };

package/templates/subsystem/events/domain-events.schema.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= schemaPath %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * Drizzle schema for the domain_events outbox table.
  *

package/templates/subsystem/events/prompt.js

@@ -16,6 +16,8 @@
  * imported. So no workerPath / workerMode / mainTsPath locals here.
  */
 
+import { renderGeneratedBanner } from "../../_shared/generated-banner.mjs";
+
 function coerceBool(raw) {
   if (raw === true) return true;
   if (raw === false) return false;
@@ -34,6 +36,12 @@ export default {
       generatedKeepPath:
         args.generatedKeepPath ??
         "shared/subsystems/events/generated/.gitkeep",
+      // @generated DO-NOT-EDIT banner — the events subsystem schema is
+      // force-overwritten on every `subsystem install`.
+      generatedBanner: renderGeneratedBanner({
+        generator: "subsystem events",
+        seam: "the codegen.config.yaml events block, then re-run `codegen subsystem install`",
+      }),
     };
   },
 };

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

@@ -2,6 +2,7 @@
 to: "<%= schemaPath %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * Drizzle schema for the job orchestration domain (ADR-022).
  *

package/templates/subsystem/jobs/prompt.js

@@ -14,6 +14,8 @@
  *     --appName <string>
  */
 
+import { renderGeneratedBanner } from "../../_shared/generated-banner.mjs";
+
 function coerceBool(raw) {
   if (raw === true) return true;
   if (raw === false) return false;
@@ -35,6 +37,12 @@ export default {
       workerPath: args.workerPath ?? "worker.ts",
       schemaPath:
         args.schemaPath ?? "shared/subsystems/jobs/job-orchestration.schema.ts",
+      // @generated DO-NOT-EDIT banner — the jobs subsystem schema is
+      // force-overwritten on every `subsystem install`.
+      generatedBanner: renderGeneratedBanner({
+        generator: "subsystem jobs",
+        seam: "the codegen.config.yaml jobs block, then re-run `codegen subsystem install`",
+      }),
     };
   },
 };

package/templates/subsystem/sync/prompt.js

@@ -23,6 +23,8 @@
  * Phase 2 timing for `examples/sync/`.
  */
 
+import { renderGeneratedBanner } from "../../_shared/generated-banner.mjs";
+
 function coerceBool(raw) {
   if (raw === true) return true;
   if (raw === false) return false;
@@ -38,6 +40,12 @@ export default {
       configPath: args.configPath ?? "codegen.config.yaml",
       schemaPath:
         args.schemaPath ?? "shared/subsystems/sync/sync-audit.schema.ts",
+      // @generated DO-NOT-EDIT banner — the sync subsystem schema is
+      // force-overwritten on every `subsystem install`.
+      generatedBanner: renderGeneratedBanner({
+        generator: "subsystem sync",
+        seam: "the codegen.config.yaml sync block, then re-run `codegen subsystem install`",
+      }),
     };
   },
 };

package/templates/subsystem/sync/sync-audit.schema.ejs.t

@@ -2,6 +2,7 @@
 to: "<%= schemaPath %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * Drizzle schema for the sync subsystem audit/observability tables (SYNC-1).
  *