@pattern-stack/codegen 0.7.5 → 0.7.6

package/runtime/subsystems/sync/execute-sync.use-case.ts

@@ -278,11 +278,35 @@ export class ExecuteSyncUseCase<T extends Record<string, unknown>> {
     );
 
     if (diff === 'noop') {
+      // Sinks that declare `reprojectsOnNoop` reproject side data the differ
+      // can't see (e.g. EAV field_values) — so fall through to the idempotent
+      // upsert instead of short-circuiting. The canonical state is unchanged,
+      // so the audit `operation` stays `'noop'`, but we capture the local id
+      // returned by the upsert. Sinks without the flag keep today's behavior.
+      if (!this.sink.reprojectsOnNoop) {
+        await this.recorder.recordItem({
+          syncRunId: runId,
+          entityType: input.subscription.domain,
+          externalId: change.externalId,
+          localId: null,
+          operation: 'noop',
+          status: 'success',
+          changedFields: {},
+          tenantId: input.tenantId,
+        });
+        return;
+      }
+
+      const { id: noopLocalId } = await this.sink.upsertByExternalId(
+        input.userId,
+        change.record,
+        input.provider,
+      );
       await this.recorder.recordItem({
         syncRunId: runId,
         entityType: input.subscription.domain,
         externalId: change.externalId,
-        localId: null,
+        localId: noopLocalId,
         operation: 'noop',
         status: 'success',
         changedFields: {},

package/runtime/subsystems/sync/sync-sink.protocol.ts

@@ -52,4 +52,11 @@ export interface ISyncSink<TCanonical> {
     userId: string,
     externalId: string,
   ): Promise<{ id: string } | null>;
+
+  /**
+   * When true, the orchestrator does NOT short-circuit on a `noop` diff — it
+   * still calls upsertByExternalId so the sink can reproject side data (e.g.
+   * EAV field_values) the differ doesn't see. Default false.
+   */
+  readonly reprojectsOnNoop?: boolean;
 }

package/src/patterns/library/synced.pattern.ts

@@ -23,7 +23,8 @@ export const SyncedPattern = definePattern({
 	serviceImport: '@shared/base-classes/synced-entity-service',
 	repositoryInheritedMethods: [
 		'findById, findByIds, list, count, exists, create, update, delete, upsertMany',
-		'findByExternalId, findAllByUserId, findVisibleByUserId, syncUpsert',
+		'findByExternalId, findManyByExternalIds, findAllByUserId, findVisibleByUserId',
+		'syncUpsertOne, findByExternalIdProjected, softDeleteByExternalId, syncUpsert',
 	],
 	serviceInheritedMethods: [
 		'findById, findByIds, list, count, exists, create, update, delete',

package/templates/_shared/generated-banner.mjs

@@ -0,0 +1,74 @@
+/**
+ * Shared `@generated` banner helper.
+ *
+ * Single source of truth for the DO-NOT-EDIT banner that every
+ * force-overwritten codegen output carries. The banner exists because
+ * force-emitted files are silently re-written on every `bun run codegen`
+ * (and wholesale on `codegen entity new --all`). Without a visible warning,
+ * a hand edit made directly into a generated file looks permanent — until
+ * the next re-emit wipes it. The banner is the warning.
+ *
+ * Why a helper (not copy-pasted text): the banner wording is a contract.
+ * Centralising it means a future change (e.g. a new extension seam, a
+ * reworded regenerate command) touches one file, and the emission tests
+ * assert against this exact function.
+ *
+ * Consumed by each generator's `prompt.js`, which calls
+ * `renderGeneratedBanner({ source, generator, seam })` once and forwards the
+ * result as the `generatedBanner` template local. Templates emit it as their
+ * first body line via:
+ *
+ *     <%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
+ *
+ * The `typeof` guard keeps direct-EJS rendering (unit tests that build their
+ * own locals) from throwing a ReferenceError when a test does not opt into
+ * the banner local.
+ */
+
+/**
+ * Marker substring that identifies a generated-banner line. Tests and
+ * tooling can grep for this to assert (or strip) the banner. Kept as a
+ * single token so it survives reflow / line-wrapping changes to the prose.
+ */
+export const GENERATED_BANNER_MARKER = '@generated by @pattern-stack/codegen';
+
+/**
+ * Render the DO-NOT-EDIT banner.
+ *
+ * @param {object} opts
+ * @param {string} [opts.source]    Source definition path (e.g. the entity
+ *                                   YAML), relative to the consumer repo root
+ *                                   when known. Interpolated into the banner so
+ *                                   a reader knows which file to edit instead.
+ * @param {string} [opts.generator] The codegen generator that emitted the file
+ *                                   (e.g. 'entity', 'junction'). Purely
+ *                                   informational; helps when `source` is
+ *                                   unavailable.
+ * @param {string} [opts.seam]      The supported extension seam — how to
+ *                                   customise behaviour without editing the
+ *                                   generated file (e.g. 'a pattern in
+ *                                   src/patterns/*.pattern.ts', 'a subclass /
+ *                                   base-class behavior config').
+ * @param {string} [opts.comment]   Comment leader for the host language.
+ *                                   Defaults to '//' (TS/JS). Pass '--' for SQL.
+ * @returns {string} A single comment line, no trailing newline.
+ */
+export function renderGeneratedBanner(opts = {}) {
+	const { source, generator, seam, comment = '//' } = opts;
+
+	const from = source
+		? ` from ${source}`
+		: generator
+			? ` (${generator} generator)`
+			: '';
+	const extend = seam
+		? ` To extend, use ${seam}.`
+		: '';
+
+	return (
+		`${comment} ${GENERATED_BANNER_MARKER}${from} — DO NOT EDIT. ` +
+		`Hand edits are overwritten on re-emit. Regenerate with \`bun run codegen\`.${extend}`
+	);
+}
+
+export default renderGeneratedBanner;

package/templates/broadcast/new/backend-interface.ejs.t

@@ -2,6 +2,7 @@
 to: src/infrastructure/broadcast/broadcast-backend.interface.ts
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 export type BroadcastHandler = (
   eventType: string,
   payload: Record<string, unknown>,

package/templates/broadcast/new/bridge-listener.ejs.t

@@ -2,6 +2,7 @@
 to: src/infrastructure/broadcast/broadcast-bridge.listener.ts
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable, Logger } from '@nestjs/common'
 import { OnEvent } from '@nestjs/event-emitter'
 import { WebSocketBroadcastBackend } from './websocket-broadcast.backend'

package/templates/broadcast/new/channel.ejs.t

@@ -2,6 +2,7 @@
 to: src/infrastructure/broadcast/channel.ts
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import type { BroadcastBackend, BroadcastHandler } from './broadcast-backend.interface'
 
 /**

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

@@ -2,6 +2,7 @@
 to: src/infrastructure/broadcast/index.ts
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 // Interfaces
 export type { BroadcastBackend, BroadcastHandler } from './broadcast-backend.interface'
 export { BROADCAST_BACKEND } from './broadcast-backend.interface'

package/templates/broadcast/new/memory-backend.ejs.t

@@ -2,6 +2,7 @@
 to: src/infrastructure/broadcast/memory-broadcast.backend.ts
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable } from '@nestjs/common'
 import type {
   BroadcastBackend,

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

@@ -2,6 +2,7 @@
 to: src/infrastructure/broadcast/broadcast.module.ts
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Module } from '@nestjs/common'
 import { WebSocketBroadcastBackend } from './websocket-broadcast.backend'
 import { MemoryBroadcastBackend } from './memory-broadcast.backend'

package/templates/broadcast/new/prompt.js

@@ -9,6 +9,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import yaml from 'yaml'
+import { renderGeneratedBanner } from '../../_shared/generated-banner.mjs'
 
 // ============================================================================
 // Default Configuration
@@ -243,7 +244,19 @@ export default {
       events: events.sort(),
     }))
 
+    // @generated DO-NOT-EDIT banner — stamped at the top of every
+    // force-overwritten broadcast output. `args.yaml` (when provided) is the
+    // consumer-relative source config; otherwise defaults are used.
+    const generatedBanner = renderGeneratedBanner({
+      source: args.yaml,
+      generator: 'broadcast',
+      seam: 'the broadcast config YAML',
+    })
+
     return {
+      // @generated DO-NOT-EDIT banner (see renderGeneratedBanner)
+      generatedBanner,
+
       // Basic config
       name: broadcast.name,
       websocketPath: broadcast.websocket?.path ?? '/ws/broadcast',

package/templates/broadcast/new/websocket-backend.ejs.t

@@ -2,6 +2,7 @@
 to: src/infrastructure/broadcast/websocket-broadcast.backend.ts
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable, Logger } from '@nestjs/common'
 import {
   WebSocketGateway,

package/templates/entity/new/backend/application/commands/create.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.commands ? outputPaths.createCommand : '' %>"
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.createCommand) { -%>
 /**
  * Create <%= className %> Command

package/templates/entity/new/backend/application/commands/delete.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.commands ? outputPaths.deleteCommand : '' %>"
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.deleteCommand) { -%>
 /**
  * Delete <%= className %> Command

package/templates/entity/new/backend/application/commands/grouped-index.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.commands ? outputPaths.commandsGroupedIndex : '' %>"
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.commandsGroupedIndex) { -%>
 /**
  * <%= className %> Commands Module

package/templates/entity/new/backend/application/commands/index.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.commands ? outputPaths.commandsIndex : '' %>"
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.commandsIndex) { -%>
 /**
  * <%= className %> Commands Barrel Export

package/templates/entity/new/backend/application/commands/update.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.commands ? outputPaths.updateCommand : '' %>"
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.updateCommand) { -%>
 /**
  * Update <%= className %> Command

package/templates/entity/new/backend/application/queries/declarative-queries.ejs.t

@@ -3,6 +3,7 @@ to: "<%= hasDeclarativeQueries ? `${basePaths.backendSrc}/${paths.queries}/decla
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (hasDeclarativeQueries) { -%>
 /**
  * Declarative Query Classes for <%= className %>

package/templates/entity/new/backend/application/queries/get-by-id.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.queries ? outputPaths.getByIdQuery : '' %>"
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.getByIdQuery) { -%>
 /**
  * Get <%= className %> By ID Query

package/templates/entity/new/backend/application/queries/grouped-index.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.queries ? outputPaths.queriesGroupedIndex : '' %>"
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.queriesGroupedIndex) { -%>
 /**
  * <%= className %> Queries Module

package/templates/entity/new/backend/application/queries/index.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.queries ? outputPaths.queriesIndex : '' %>"
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.queriesIndex) { -%>
 /**
  * <%= className %> Queries Barrel Export

package/templates/entity/new/backend/application/queries/list.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.queries ? outputPaths.listQuery : '' %>"
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.listQuery) { -%>
 /**
  * List <%= classNamePlural %> Query

package/templates/entity/new/backend/application/queries/relationships.queries.ejs.t

@@ -3,6 +3,7 @@ to: "<%= (isCleanArchitecture && hasRelationships && !isGrouped) ? `${basePaths.
 skip_if: <%= !(isCleanArchitecture && hasRelationships && !isGrouped) %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (isCleanArchitecture && hasRelationships && !isGrouped) { -%>
 /**
  * Relationship Composition Queries for <%= className %>

package/templates/entity/new/backend/application/schemas/dto.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.dtos ? outputPaths.dto : '' %>"
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> DTOs
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/backend/database/repository.ejs.t

@@ -3,6 +3,7 @@ to: <%= basePaths.backendSrc %>/<%= paths.repositories %>/<%= name %>.repository
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> Repository Implementation
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/backend/database/schema.ejs.t

@@ -3,6 +3,7 @@ to: "<%= generate.drizzleSchema ? outputPaths.drizzleSchema : '' %>"
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> Drizzle Schema
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/backend/domain/entity.ejs.t

@@ -3,6 +3,7 @@ to: <%= outputPaths.entity %>
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.entity) { -%>
 /**
  * <%= className %> Domain Entity

package/templates/entity/new/backend/domain/grouped-index.ejs.t

@@ -3,6 +3,7 @@ to: <%= outputPaths.domainGroupedIndex %>
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.domainGroupedIndex) { -%>
 /**
  * <%= className %> Domain Module

package/templates/entity/new/backend/domain/index.ejs.t

@@ -3,6 +3,7 @@ to: <%= basePaths.backendSrc %>/<%= paths.domain %>/index.ts
 skip_if: <%= !isCleanArchitecture || (!isNested || isGrouped) %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> Domain Barrel Export
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/backend/domain/repository-interface.ejs.t

@@ -3,6 +3,7 @@ to: <%= outputPaths.repositoryInterface %>
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (outputPaths.repositoryInterface) { -%>
 /**
  * <%= className %> Repository Interface

package/templates/entity/new/backend/modules/core/module.ejs.t

@@ -3,6 +3,7 @@ to: <%= outputPaths.module %>
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= classNamePlural %> Module
  * Generated by entity codegen - do not edit directly

package/templates/entity/new/backend/modules/core/sync-source.ejs.t

@@ -3,6 +3,7 @@ to: "<%= hasDetection ? (isCleanLitePs ? clpOutputPaths.syncSourceModule : `${ba
 skip_if: <%= !hasDetection %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Module } from '@nestjs/common';
 import { buildChangeSource } from '@shared/subsystems/sync';
 import type {

package/templates/entity/new/backend/modules/core/sync-source.providers.ejs.t

@@ -3,6 +3,7 @@ to: "<%= hasDetection ? (isCleanLitePs ? clpOutputPaths.syncSourceProviders : `$
 skip_if: <%= !hasDetection %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 /**
  * <%= className %> sync-source providers
  * Generated by entity codegen — do not edit directly.

package/templates/entity/new/backend/modules/trpc/module.ejs.t

@@ -3,6 +3,7 @@ to: "<%= exposeTrpc ? `${basePaths.backendSrc}/presentation/trpc/${plural}.route
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (exposeTrpc) { -%>
 /**
  * <%= classNamePlural %> tRPC Router

package/templates/entity/new/backend/presentation/controller.ejs.t

@@ -3,6 +3,7 @@ to: "<%= (exposeRest || exposeElectric) ? `${basePaths.backendSrc}/${paths.contr
 skip_if: <%= !isCleanArchitecture %>
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (exposeRest) { -%>
 /**
  * <%= classNamePlural %> Controller

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

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.controller : nul
 skip_if: "<%= typeof clpOutputPaths === 'undefined' %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Controller, Get<% if (generateWrites) { %>, Post, Patch, Delete, Body, Headers<% } %>, NotFoundException, Param, ParseUUIDPipe } from '@nestjs/common';
 import { ApiBearerAuth, <% if (generateWrites) { %>ApiBody, <% } %>ApiOperation, ApiParam, ApiResponse } from '@nestjs/swagger';
 import { <%= classNames.findByIdUseCase %> } from './use-cases/find-<%= entityName %>-by-id.use-case';

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

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.createDto : null
 skip_if: "<%= typeof clpOutputPaths === 'undefined' %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { z } from 'zod';
 
 export const <%= classNames.createSchema %> = z.object({

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

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

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

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

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

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

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

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

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

@@ -3,6 +3,7 @@ to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.module : null %>
 skip_if: "<%= typeof clpOutputPaths === 'undefined' %>"
 force: true
 ---
+<%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 <% if (hasEmits) { -%>
 /**
  * EVT-7: This entity emits typed domain events. Use-cases depend on