@pattern-stack/codegen 0.6.7 → 0.7.0

package/templates/entity/new/clean-lite-ps/prompt-extension.js

@@ -5,6 +5,8 @@
  * all variables required by the clean-lite-ps template set.
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
 import pluralizePkg from 'pluralize';
 // The patterns barrel has the side effect of pre-registering the five
 // library-shipped patterns (Base / Synced / Activity / Knowledge /
@@ -201,7 +203,7 @@ const EXTERNAL_ID_TRACKING_FIELDS = new Set([
 /**
  * Build a Drizzle column chain for a field
  */
-function buildDrizzleChain(fieldName, field, drizzleType) {
+function buildDrizzleChain(fieldName, field, drizzleType, enumName) {
   const nullable = field.nullable ?? false;
   const required = field.required ?? false;
   const hasDefault = field.default !== undefined && field.default !== null;
@@ -211,7 +213,11 @@ function buildDrizzleChain(fieldName, field, drizzleType) {
   // schemas using z.coerce.date() align with the entity type.
   // `timestamp` already defaults to Date — no mode override needed.
   let chain;
-  if (drizzleType === 'date') {
+  if (drizzleType === 'enum' && enumName) {
+    // Reference the pgEnum declaration emitted at the top of the entity file.
+    // The column name argument keeps the snake_case YAML field name.
+    chain = `${enumName}('${fieldName}')`;
+  } else if (drizzleType === 'date') {
     chain = `${drizzleType}('${fieldName}', { mode: 'date' })`;
   } else {
     chain = `${drizzleType}('${fieldName}')`;
@@ -247,7 +253,15 @@ function processFields(fields) {
     const choices = field.choices;
     const hasChoices = Array.isArray(choices) && choices.length > 0;
 
-    const drizzleType = DRIZZLE_TYPE_MAP[type] || 'text';
+    // Enum-typed fields (or any field with a `choices` list) emit a
+    // Postgres-native pgEnum declaration + column reference, so the
+    // generated `InferSelectModel` type narrows to the literal union
+    // instead of falling back to `string`. Matches the backend pipeline
+    // (templates/entity/new/backend/database/schema.ejs.t:66-104).
+    const drizzleType = hasChoices
+      ? 'enum'
+      : (DRIZZLE_TYPE_MAP[type] || 'text');
+    const enumName = hasChoices ? camelCase(fieldName) + 'Enum' : null;
     const tsType = hasChoices
       ? choices.map((c) => `'${c}'`).join(' | ')
       : (TS_TYPE_MAP[type] || 'unknown');
@@ -255,7 +269,7 @@ function processFields(fields) {
       ? `z.enum([${choices.map((c) => `'${c}'`).join(', ')}])`
       : (ZOD_TYPE_MAP[type] || 'z.unknown()');
 
-    const drizzleChain = buildDrizzleChain(fieldName, field, drizzleType);
+    const drizzleChain = buildDrizzleChain(fieldName, field, drizzleType, enumName);
 
     processed.push({
       name: fieldName,
@@ -271,6 +285,7 @@ function processFields(fields) {
       drizzleChain,
       choices,
       hasChoices,
+      enumName,
     });
   }
 
@@ -293,6 +308,57 @@ function mapOnDelete(onDelete) {
   return map[onDelete] ?? 'restrict';
 }
 
+/**
+ * Process has_many relationships into HasManyRelation[].
+ *
+ * Mirrors processBelongsTo. The `foreign_key` declared on a has_many
+ * relationship is the inverse FK living on the *target* entity's table —
+ * e.g. `account.relationships.contacts: { foreign_key: account_id }` means
+ * contacts.account_id. The method name on AccountRepository would be
+ * `findByAccountId`.
+ */
+function processHasMany(relationships, parentEntityNamePlural, fs, path, srcRoot) {
+  if (!relationships) return [];
+
+  const result = [];
+
+  for (const [relName, rel] of Object.entries(relationships)) {
+    if (rel.type !== 'has_many') continue;
+
+    const target = rel.target;
+    const inverseForeignKey = rel.foreign_key;
+    const targetPlural = pluralize(target);
+    const isSelfRef = targetPlural === parentEntityNamePlural;
+
+    // Check whether the target entity has already been generated.
+    // Only include targets that exist so the import block doesn't
+    // reference files that aren't on disk yet (two-pass generation).
+    let targetExists = false;
+    if (fs && path && srcRoot) {
+      const nestedPath = path.resolve(srcRoot, 'modules', targetPlural, `${target}.entity.ts`);
+      const flatPath = path.resolve(srcRoot, 'modules', `${target}.entity.ts`);
+      targetExists = fs.existsSync(nestedPath) || fs.existsSync(flatPath) || isSelfRef;
+    } else {
+      targetExists = isSelfRef;
+    }
+
+    result.push({
+      name: relName,
+      target,
+      targetClass: pascalCase(target),
+      targetPlural,
+      inverseForeignKey,
+      inverseForeignKeyCamel: camelCase(inverseForeignKey),
+      inverseForeignKeyPascal: pascalCase(inverseForeignKey),
+      isSelfRef,
+      targetExists,
+      importPath: `../${targetPlural}/${target}.repository`,
+    });
+  }
+
+  return result;
+}
+
 /**
  * Process belongs_to relationships into BelongsToRelation[]
  */
@@ -351,10 +417,16 @@ function processBelongsTo(relationships, parentEntityNamePlural) {
 /**
  * Collect drizzle imports needed for entity fields
  */
-function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking) {
+function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking, hasMany = []) {
   const imports = new Set(['pgTable', 'uuid']);
 
   for (const field of processedFields) {
+    if (field.drizzleType === 'enum') {
+      // Enum columns reference a `pgEnum` declaration emitted at the top
+      // of the entity file; the helper itself comes from drizzle-orm/pg-core.
+      imports.add('pgEnum');
+      continue;
+    }
     const importName = DRIZZLE_IMPORT_MAP[field.drizzleType];
     if (importName) imports.add(importName);
   }
@@ -375,7 +447,7 @@ function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSof
     imports.add('jsonb');
   }
 
-  if (belongsTo.length > 0) {
+  if (belongsTo.length > 0 || hasMany.length > 0) {
     imports.add('relations');
   }
 
@@ -750,6 +822,9 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   // Process belongs_to relationships
   const belongsTo = processBelongsTo(relationships, entityNamePlural);
 
+  // Process has_many relationships (CGP-358b)
+  const hasMany = processHasMany(relationships, entityNamePlural, fs, path, srcRoot);
+
   // Issue #41 — warn when a soft-delete entity declares non-restrict on_delete on any
   // belongs_to relation. The FK constraint applies to hard-delete only;
   // developers expecting soft-delete cascade must use activeParentFilter() instead.
@@ -783,10 +858,22 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   const fkFieldNames = new Set(belongsTo.map((r) => r.field));
   const nonFkFields = processedFields.filter((f) => !fkFieldNames.has(f.name));
 
+  // Enum field declarations — surface a separate collection so the entity
+  // template can emit `export const xEnum = pgEnum('x', [...])` ahead of
+  // the `pgTable(...)` block. Both FK-filtered and unfiltered processing
+  // include the same enum fields; they're never FKs.
+  const clpEnumFields = processedFields
+    .filter((f) => f.hasChoices && f.enumName)
+    .map((f) => ({
+      enumName: f.enumName,
+      dbName: f.name,
+      choices: f.choices,
+    }));
+
   // Drizzle imports needed
-  const drizzleEntityImports = collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking);
-  // Whether relations() import is needed
-  const hasRelationsBlock = belongsTo.length > 0;
+  const drizzleEntityImports = collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking, hasMany);
+  // Whether relations() import is needed (CGP-358b: also trigger on has_many)
+  const hasRelationsBlock = belongsTo.length > 0 || hasMany.length > 0;
 
   // Output paths
   const outputPaths = {
@@ -980,6 +1067,13 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     // Drizzle
     clpDrizzleImports: drizzleEntityImports,
     clpHasRelationsBlock: hasRelationsBlock,
+    // A self-referential belongs_to FK requires the `references()` callback
+    // to carry a `: AnyPgColumn` return-type annotation; otherwise TypeScript's
+    // strict mode flags the table const with TS7022/TS7024 (circular initializer).
+    // Surfaced by the cgp-62 relationship-scenario smoke when generating a CRM
+    // account with a `parent_account_id` self-FK.
+    clpHasSelfFk: belongsTo.some((rel) => rel.isSelfFk),
+    clpEnumFields,
 
     // Declarative queries
     processedQueries,
@@ -988,5 +1082,10 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     hasMultiFieldQuery,
     hasOrderedQuery,
     hasViaQuery,
+
+    // CGP-358b: has_many relationships for service-layer composition
+    clpHasMany: hasMany,
+    clpHasManyRelations: hasMany.length > 0,
+    clpExistingHasMany: hasMany.filter((r) => r.targetExists),
   };
 }

package/templates/entity/new/clean-lite-ps/repository.ejs.t

@@ -4,7 +4,17 @@ skip_if: "<%= typeof clpOutputPaths === 'undefined' %>"
 force: true
 ---
 import { Injectable, Inject } from '@nestjs/common';
-<% if (hasDeclarativeQueries) { -%>
+<%_
+// CGP-358: FK methods with opts take priority over same-named declarative query impl.
+// Always emit FK methods; skip declarative body when FK covers same name.
+const _fkMethods = (typeof clpBelongsTo !== 'undefined') ? clpBelongsTo : [];
+const _fkMethodNamesCLP = new Set(_fkMethods.map(rel => {
+  const _p = rel.camelField.charAt(0).toUpperCase() + rel.camelField.slice(1);
+  return `findBy${_p}`;
+}));
+const _needsEq = hasDeclarativeQueries || _fkMethods.length > 0;
+_%>
+<% if (_needsEq) { -%>
 import { eq<%= hasMultiFieldQuery ? ', and' : '' %><%= hasOrderedQuery ? ', desc, asc' : '' %> } from 'drizzle-orm';
 <% } -%>
 <% if (eavValueTable) { -%>
@@ -48,6 +58,12 @@ export class <%= classNames.repository %> extends <%= repositoryBaseClass %><<%=
   // Declarative queries (from queries: block in entity YAML)
   // ═══════════════════════════════════════════════════════════════════════
 <%_ processedQueries.forEach((q) => { _%>
+<%_
+// CGP-358: Skip declarative impl when a FK method covers this method name.
+// FK methods accept opts, making them a superset of a plain non-unique single-param query.
+const _skipClpDq = _fkMethodNamesCLP.has(q.methodName) && !q.isUnique && !q.hasVia && !q.hasSelect;
+_%>
+<%_ if (!_skipClpDq) { _%>
 
   async <%= q.methodName %>(<%- q.params.map(p => `${p.camelName}: ${p.tsType}`).join(', ') %>): Promise<<%- q.returnType %>> {
 <% if (q.isUnique) { -%>
@@ -61,11 +77,27 @@ export class <%= classNames.repository %> extends <%= repositoryBaseClass %><<%=
     return rows as <%= classNames.entity %>[];
 <% } -%>
   }
+<%_ } _%>
 <%_ }) _%>
 <% } else { -%>
 
   // TODO: Add entity-specific query methods here.
 <% } -%>
+<%_ if (_fkMethods.length > 0) { _%>
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // FK traversal methods (from belongs_to relationships — CGP-358b)
+  // Called by service-layer composition methods on the inverse (has_many) side.
+  // ═══════════════════════════════════════════════════════════════════════
+<%_ _fkMethods.forEach(rel => { _%>
+
+  async findBy<%= rel.camelField.charAt(0).toUpperCase() + rel.camelField.slice(1) %>(id: string, opts?: { cursor?: string; limit?: number }): Promise<<%= classNames.entity %>[]> {
+    let q = this.baseQuery().where(eq(this.table['<%= rel.camelField %>'], id));
+    if (opts?.limit) q = (q as any).limit(opts.limit);
+    return (await q) as <%= classNames.entity %>[];
+  }
+<%_ }) _%>
+<%_ } _%>
 <% if (eavValueTable) { -%>
 
   // ═══════════════════════════════════════════════════════════════════════

package/templates/entity/new/clean-lite-ps/service.ejs.t

@@ -17,6 +17,22 @@ import { toEavRows, mergeEavRows } from '@shared/eav-helpers';
 import type { DrizzleTx } from '@shared/types/drizzle';
 import { <%= eavDefinitionPascal %>Repository } from '../<%= eavDefinitionEntityPlural %>/<%= eavDefinitionEntity %>.repository';
 <% } -%>
+<%_ /* CGP-358b — service-layer composition: import target repos for belongs_to relationships */ _%>
+<%_ if (typeof clpBelongsTo !== 'undefined') { _%>
+<%_ const uniqueBelongsToTargets = [...new Map(clpBelongsTo.filter(r => !r.isSelfFk).map(r => [r.relatedEntity, r])).values()]; _%>
+<%_ uniqueBelongsToTargets.forEach(rel => { _%>
+import { <%= rel.relatedEntityPascal %>Repository } from '../<%= rel.relatedPlural %>/<%= rel.relatedEntity %>.repository';
+import type { <%= rel.relatedEntityPascal %> } from '../<%= rel.relatedPlural %>/<%= rel.relatedEntity %>.entity';
+<%_ }) _%>
+<%_ } _%>
+<%_ /* CGP-358b — import target repos for has_many relationships */ _%>
+<%_ if (typeof clpExistingHasMany !== 'undefined') { _%>
+<%_ const uniqueHasManyTargets = [...new Map(clpExistingHasMany.filter(r => !r.isSelfRef).map(r => [r.target, r])).values()]; _%>
+<%_ uniqueHasManyTargets.forEach(rel => { _%>
+import { <%= rel.targetClass %>Repository } from '../<%= rel.targetPlural %>/<%= rel.target %>.repository';
+import type { <%= rel.targetClass %> } from '../<%= rel.targetPlural %>/<%= rel.target %>.entity';
+<%_ }) _%>
+<%_ } _%>
 
 @Injectable()
 export class <%= classNames.service %> extends WithAnalytics(
@@ -43,6 +59,20 @@ export class <%= classNames.service %> extends WithAnalytics(
 <% if (eavValueTable) { -%>
     private readonly definitionRepo: <%= eavDefinitionPascal %>Repository,
 <% } -%>
+<%_ /* CGP-358b — inject target repos for belongs_to (non-self-ref) */ _%>
+<%_ if (typeof clpBelongsTo !== 'undefined') { _%>
+<%_ const uniqueBelongsToTargets2 = [...new Map(clpBelongsTo.filter(r => !r.isSelfFk).map(r => [r.relatedEntity, r])).values()]; _%>
+<%_ uniqueBelongsToTargets2.forEach(rel => { _%>
+    private readonly <%= rel.relatedEntity.replace(/_([a-z])/g, (_, c) => c.toUpperCase()) %>Repo: <%= rel.relatedEntityPascal %>Repository,
+<%_ }) _%>
+<%_ } _%>
+<%_ /* CGP-358b — inject target repos for has_many (non-self-ref) */ _%>
+<%_ if (typeof clpExistingHasMany !== 'undefined') { _%>
+<%_ const uniqueHasManyTargets2 = [...new Map(clpExistingHasMany.filter(r => !r.isSelfRef).map(r => [r.target, r])).values()]; _%>
+<%_ uniqueHasManyTargets2.forEach(rel => { _%>
+    private readonly <%= rel.target.replace(/_([a-z])/g, (_, c) => c.toUpperCase()) %>Repo: <%= rel.targetClass %>Repository,
+<%_ }) _%>
+<%_ } _%>
   ) {
     super(repository);
   }
@@ -67,6 +97,55 @@ export class <%= classNames.service %> extends WithAnalytics(
   }
 <%_ }) _%>
 <% } %>
+<%_ /* CGP-358b — service-layer composition methods for relationships */ _%>
+<%_ const hasBelongsToComposition = typeof clpBelongsTo !== 'undefined' && clpBelongsTo.length > 0; _%>
+<%_ const hasHasManyComposition = typeof clpExistingHasMany !== 'undefined' && clpExistingHasMany.length > 0; _%>
+<%_ if (hasBelongsToComposition || hasHasManyComposition) { _%>
+  // ═══════════════════════════════════════════════════════════════════════
+  // Relationship composition methods (CGP-358b / CGP-62)
+  // Two queries, no SQL JOIN. Core-contract path; relations() const stays
+  // as opt-in extension for hand-written Drizzle queries.
+  // ═══════════════════════════════════════════════════════════════════════
+<%_ } _%>
+<%_ if (hasBelongsToComposition) { _%>
+<%_ clpBelongsTo.forEach(rel => { _%>
+<%_ const relCamel = rel.relatedEntity.replace(/_([a-z])/g, (_, c) => c.toUpperCase()); _%>
+<%_ const entityCamel = entityName.replace(/_([a-z])/g, (_, c) => c.toUpperCase()); _%>
+
+  /**
+   * Fetch the <%= rel.relatedEntityPascal %> parent for this <%= entityNamePascal %>.
+   * Two repo calls: find self by id → find target by FK.
+   */
+  async <%= rel.relationKey %>(<%- entityCamel %>Id: string): Promise<<%= rel.relatedEntityPascal %> | null> {
+    const entity = await this.repository.findById(<%- entityCamel %>Id);
+    if (!entity) return null;
+<%_ if (rel.isSelfFk) { _%>
+    return entity.<%= rel.camelField %> ? this.repository.findById(entity.<%= rel.camelField %>) : null;
+<%_ } else { _%>
+    return entity.<%= rel.camelField %> ? this.<%= relCamel %>Repo.findById(entity.<%= rel.camelField %>) : null;
+<%_ } _%>
+  }
+<%_ }) _%>
+<%_ } _%>
+<%_ if (hasHasManyComposition) { _%>
+<%_ clpExistingHasMany.forEach(rel => { _%>
+<%_ const relCamel = rel.target.replace(/_([a-z])/g, (_, c) => c.toUpperCase()); _%>
+<%_ const entityCamel = entityName.replace(/_([a-z])/g, (_, c) => c.toUpperCase()); _%>
+<%_ const fkPascal = rel.inverseForeignKeyPascal; _%>
+
+  /**
+   * Fetch <%= rel.name %> for this <%= entityNamePascal %> by FK traversal.
+   * Single repo call with optional cursor/limit pagination.
+   */
+  async <%= rel.name %>(<%- entityCamel %>Id: string, opts?: { cursor?: string; limit?: number }): Promise<<%= rel.targetClass %>[]> {
+<%_ if (rel.isSelfRef) { _%>
+    return this.repository.findBy<%= fkPascal %>(<%- entityCamel %>Id, opts);
+<%_ } else { _%>
+    return this.<%= relCamel %>Repo.findBy<%= fkPascal %>(<%- entityCamel %>Id, opts);
+<%_ } _%>
+  }
+<%_ }) _%>
+<%_ } _%>
 <% if (eavEnabled) { %>
   /**
    * EAV paired read (ADR-13): fetch the entity and merge dynamic `field_values`

package/templates/entity/new/prompt.js

@@ -568,6 +568,7 @@ export default {
       moduleToGetByIdQuery: importHelpers.moduleToQuery(name, fileNames.getByIdQuery.replace('.ts', '')),
       moduleToListQuery: importHelpers.moduleToQuery(name, fileNames.listQuery.replace('.ts', '')),
       moduleToDeclarativeQueries: importHelpers.moduleToQuery(name, 'declarative-queries'),
+      moduleToRelationshipQueries: importHelpers.moduleToQuery(name, 'relationships.queries'),
       moduleToCreateCommand: importHelpers.moduleToCommand(name, fileNames.createCommand.replace('.ts', '')),
       moduleToUpdateCommand: importHelpers.moduleToCommand(name, fileNames.updateCommand.replace('.ts', '')),
       moduleToDeleteCommand: importHelpers.moduleToCommand(name, fileNames.deleteCommand.replace('.ts', '')),

package/templates/junction/new/_inject-parent-module-clp-left.ejs.t

@@ -0,0 +1,8 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.left ? parentModulePathLeft : '' %>"
+inject: true
+after: "    DatabaseModule,"
+skip_if: "<%= classNames.module %>"
+---
+    // CGP-60 — junction module (forwardRef breaks the parent↔junction module cycle)
+    forwardRef(() => <%= classNames.module %>),

package/templates/junction/new/_inject-parent-module-clp-right.ejs.t

@@ -0,0 +1,8 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.right ? parentModulePathRight : '' %>"
+inject: true
+after: "    DatabaseModule,"
+skip_if: "<%= classNames.module %>"
+---
+    // CGP-60 — junction module (forwardRef breaks the parent↔junction module cycle)
+    forwardRef(() => <%= classNames.module %>),

package/templates/junction/new/_inject-parent-module-import-clp-left.ejs.t

@@ -0,0 +1,9 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.left ? parentModulePathLeft : '' %>"
+inject: true
+after: "from '@nestjs/common';"
+skip_if: "<%= classNames.module %> }"
+---
+// CGP-60 — junction module wiring
+import { forwardRef } from '@nestjs/common';
+import { <%= classNames.module %> } from '<%= junctionModuleImportFromLeft %>';

package/templates/junction/new/_inject-parent-module-import-clp-right.ejs.t

@@ -0,0 +1,9 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.right ? parentModulePathRight : '' %>"
+inject: true
+after: "from '@nestjs/common';"
+skip_if: "<%= classNames.module %> }"
+---
+// CGP-60 — junction module wiring
+import { forwardRef } from '@nestjs/common';
+import { <%= classNames.module %> } from '<%= junctionModuleImportFromRight %>';

package/templates/junction/new/_inject-parent-service-clp-left.ejs.t

@@ -0,0 +1,51 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.left ? parentServicePathLeft : '' %>"
+inject: true
+before: "// Inherited from"
+skip_if: "<%= injectionMarkerLeft %>"
+---
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // CGP-60 — fan-out to <%= rightEntityPascal %> (junction: <%= name %>)
+  // Delegates to <%= classNames.service %>. Per-junction marker keeps
+  // idempotency; multiple junctions on the same parent each emit their own
+  // block. `forwardRef` resolves the circular module import (parent module
+  // imports junction module; junction module imports parent modules for
+  // repo DI).
+  // ═══════════════════════════════════════════════════════════════════════
+  <%= injectionMarkerLeft %>
+
+  @Inject(forwardRef(() => <%= classNames.service %>))
+  private readonly <%= entityNameCamel %>Service!: <%= classNames.service %>;
+
+  async attach<%= rightEntityPascal %>(
+    <%= leftEntityCamel %>Id: string,
+    <%= rightEntityCamel %>Id: string,
+    link?: <%= entityNamePascal %>LinkInput,
+  ): Promise<<%= entityNamePascal %>> {
+    return this.<%= entityNameCamel %>Service.attach(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id, link);
+  }
+
+  async detach<%= rightEntityPascal %>(
+    <%= leftEntityCamel %>Id: string,
+    <%= rightEntityCamel %>Id: string,
+  ): Promise<void> {
+    return this.<%= entityNameCamel %>Service.detach(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id);
+  }
+
+  async <%= rightEntityPlural %>List(
+    <%= leftEntityCamel %>Id: string,
+    opts?: { cursor?: string; limit?: number },
+  ): Promise<Array<{ entity: <%= rightEntityPascal %>; link: <%= entityNamePascal %> }>> {
+    return this.<%= entityNameCamel %>Service.listAssoc('left', <%= leftEntityCamel %>Id, opts) as Promise<
+      Array<{ entity: <%= rightEntityPascal %>; link: <%= entityNamePascal %> }>
+    >;
+  }
+
+  async <%= rightEntityPlural %>SetPrimary(
+    <%= leftEntityCamel %>Id: string,
+    <%= rightEntityCamel %>Id: string,
+  ): Promise<void> {
+    return this.<%= entityNameCamel %>Service.setPrimary(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id);
+  }
+

package/templates/junction/new/_inject-parent-service-clp-right.ejs.t

@@ -0,0 +1,48 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.right ? parentServicePathRight : '' %>"
+inject: true
+before: "// Inherited from"
+skip_if: "<%= injectionMarkerRight %>"
+---
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // CGP-60 — fan-out to <%= leftEntityPascal %> (junction: <%= name %>)
+  // Delegates to <%= classNames.service %>. See left-side block for the
+  // forwardRef + per-junction marker rationale.
+  // ═══════════════════════════════════════════════════════════════════════
+  <%= injectionMarkerRight %>
+
+  @Inject(forwardRef(() => <%= classNames.service %>))
+  private readonly <%= entityNameCamel %>Service!: <%= classNames.service %>;
+
+  async addTo<%= leftEntityPascal %>(
+    <%= rightEntityCamel %>Id: string,
+    <%= leftEntityCamel %>Id: string,
+    link?: <%= entityNamePascal %>LinkInput,
+  ): Promise<<%= entityNamePascal %>> {
+    return this.<%= entityNameCamel %>Service.attach(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id, link);
+  }
+
+  async removeFrom<%= leftEntityPascal %>(
+    <%= rightEntityCamel %>Id: string,
+    <%= leftEntityCamel %>Id: string,
+  ): Promise<void> {
+    return this.<%= entityNameCamel %>Service.detach(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id);
+  }
+
+  async <%= leftEntityPlural %>List(
+    <%= rightEntityCamel %>Id: string,
+    opts?: { cursor?: string; limit?: number },
+  ): Promise<Array<{ entity: <%= leftEntityPascal %>; link: <%= entityNamePascal %> }>> {
+    return this.<%= entityNameCamel %>Service.listAssoc('right', <%= rightEntityCamel %>Id, opts) as Promise<
+      Array<{ entity: <%= leftEntityPascal %>; link: <%= entityNamePascal %> }>
+    >;
+  }
+
+  async <%= leftEntityPlural %>SetPrimary(
+    <%= rightEntityCamel %>Id: string,
+    <%= leftEntityCamel %>Id: string,
+  ): Promise<void> {
+    return this.<%= entityNameCamel %>Service.setPrimary(<%= leftEntityCamel %>Id, <%= rightEntityCamel %>Id);
+  }
+

package/templates/junction/new/_inject-parent-service-import-clp-left.ejs.t

@@ -0,0 +1,11 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.left ? parentServicePathLeft : '' %>"
+inject: true
+after: "from '@nestjs/common';"
+skip_if: "<%= classNames.service %> }"
+---
+// CGP-60 — junction service + types (forwardRef resolves circular module dep)
+import { forwardRef } from '@nestjs/common';
+import { <%= classNames.service %>, <%= entityNamePascal %>LinkInput } from '<%= junctionServiceImportFromLeft %>';
+import type { <%= entityNamePascal %> } from '../<%= entityNamePlural %>/<%= name %>.entity';
+import type { <%= rightEntityPascal %> } from '<%= rightEntityImportFromJunction %>';

package/templates/junction/new/_inject-parent-service-import-clp-right.ejs.t

@@ -0,0 +1,11 @@
+---
+to: "<%= architecture === 'clean-lite-ps' && exposeOnParent.right ? parentServicePathRight : '' %>"
+inject: true
+after: "from '@nestjs/common';"
+skip_if: "<%= classNames.service %> }"
+---
+// CGP-60 — junction service + types (forwardRef resolves circular module dep)
+import { forwardRef } from '@nestjs/common';
+import { <%= classNames.service %>, <%= entityNamePascal %>LinkInput } from '<%= junctionServiceImportFromRight %>';
+import type { <%= entityNamePascal %> } from '../<%= entityNamePlural %>/<%= name %>.entity';
+import type { <%= leftEntityPascal %> } from '<%= leftEntityImportFromJunction %>';

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

@@ -0,0 +1,111 @@
+---
+to: "<%= outputPaths.entity %>"
+force: true
+---
+import {
+<%_ drizzleImports.filter(i => i !== 'relations').forEach(i => { _%>
+  <%= i %>,
+<%_ }) _%>
+} from 'drizzle-orm/pg-core';
+import { relations, type InferSelectModel } from 'drizzle-orm';
+import { <%= leftTable %> } from '../<%= leftTable %>/<%= leftEntity %>.entity';
+<%_ if (leftEntity !== rightEntity) { _%>
+import { <%= rightTable %> } from '../<%= rightTable %>/<%= rightEntity %>.entity';
+<%_ } _%>
+
+// ============================================================================
+// Enums
+// ============================================================================
+<%_ if (hasRole) { _%>
+
+export const <%= roleEnumName %> = pgEnum('<%= name %>_role', [
+<%_ roleEnumValues.forEach(v => { _%>
+  '<%= v %>',
+<%_ }) _%>
+]);
+<%_ } _%>
+<%_ processedCustomFields.filter(f => f.hasChoices).forEach(field => { _%>
+
+export const <%= field.enumName %> = pgEnum('<%= name %>_<%= field.name %>', [
+<%_ field.choices.forEach(c => { _%>
+  '<%= c %>',
+<%_ }) _%>
+]);
+<%_ }) _%>
+
+// ============================================================================
+// Table
+// ============================================================================
+
+export const <%= tableVarName %> = pgTable(
+  '<%= tableName %>',
+  {
+    // FK columns — composite primary key (no surrogate id: Q4 resolution)
+    <%= leftColumnCamel %>: uuid('<%= leftColumn %>').notNull().references(() => <%= leftTable %>.id, { onDelete: '<%= onDeleteLeft %>' }),
+    <%= rightColumnCamel %>: uuid('<%= rightColumn %>').notNull().references(() => <%= rightTable %>.id, { onDelete: '<%= onDeleteRight %>' }),
+<%_ if (hasRole) { _%>
+
+    // Role enum (per-pairing; declared in junction YAML's fields.role.choices)
+    role: <%= roleEnumName %>('role'),
+<%_ } _%>
+
+    // BaseJunctionFields — is_primary is always emitted
+    isPrimary: boolean('is_primary').notNull().default(false),
+<%_ if (temporal) { _%>
+
+    // Temporal window (temporal: true, default)
+    startedAt: timestamp('started_at'),
+    endedAt: timestamp('ended_at'),
+<%_ } _%>
+<%_ if (sourced) { _%>
+
+    // Provenance (sourced: true, default)
+    sourcedFrom: text('sourced_from'),
+    confidence: numeric('confidence', { precision: 5, scale: 4 }),
+    matchedAt: timestamp('matched_at'),
+<%_ } _%>
+<%_ if (hasCustomFields) { _%>
+
+    // Custom fields
+<%_ processedCustomFields.forEach(field => { _%>
+<%_ if (field.hasChoices) { _%>
+    <%= field.camelName %>: <%= field.enumName %>('<%= field.name %>'),
+<%_ } else if (field.drizzleType === 'uuid') { _%>
+    <%= field.camelName %>: uuid('<%= field.name %>'),
+<%_ } else { _%>
+    <%= field.camelName %>: <%= field.drizzleType %>('<%= field.name %>'),
+<%_ } _%>
+<%_ }) _%>
+<%_ } _%>
+
+    // Timestamps
+    createdAt: timestamp('created_at').notNull().defaultNow(),
+    updatedAt: timestamp('updated_at').notNull().defaultNow(),
+  },
+  (table) => [
+    // Composite primary key on the two FK columns (Q4 resolution: no surrogate id)
+    primaryKey({ columns: [table.<%= leftColumnCamel %>, table.<%= rightColumnCamel %>] }),
+  ],
+);
+
+export type <%= classNames.entity %> = InferSelectModel<typeof <%= tableVarName %>>;
+export type <%= classNames.entity %>Insert = typeof <%= tableVarName %>.$inferInsert;
+
+// ============================================================================
+// Relations — extension-path metadata for db.query.X.findMany({ with: ... })
+// Generated code does NOT consume these; they exist for hand-written admin
+// queries and for #60's fan-out methods once they land.
+// ============================================================================
+
+export const <%= tableVarName %>Relations = relations(<%= tableVarName %>, ({ one }) => ({
+  <%= leftEntity %>: one(<%= leftTable %>, {
+    fields: [<%= tableVarName %>.<%= leftColumnCamel %>],
+    references: [<%= leftTable %>.id],
+  }),
+<%_ if (leftEntity !== rightEntity) { _%>
+  <%= rightEntity %>: one(<%= rightTable %>, {
+    fields: [<%= tableVarName %>.<%= rightColumnCamel %>],
+    references: [<%= rightTable %>.id],
+  }),
+<%_ } _%>
+}));