@pattern-stack/codegen 0.2.0 → 0.3.0

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

@@ -5,80 +5,103 @@
  * all variables required by the clean-lite-ps template set.
  */
 
+import pluralizePkg from 'pluralize';
+// The patterns barrel has the side effect of pre-registering the five
+// library-shipped patterns (Base / Synced / Activity / Knowledge /
+// Metadata). App-defined patterns are loaded separately in the parent
+// prompt.js via loadAppPatterns() against `codegen.config.yaml patterns:`
+// globs before this helper runs — we only read the registry here.
+import { getPattern } from '../../../../src/patterns/registry.js';
+import '../../../../src/patterns/library/index.js';
+
 // ============================================================================
-// Family → Base Class Mapping
+// Pattern registry resolution
 // ============================================================================
 
-const FAMILY_MAP = {
-  'synced': {
-    repositoryBaseClass: 'SyncedEntityRepository',
-    serviceBaseClass: 'SyncedEntityService',
-    repositoryBaseImport: '@shared/base-classes/synced-entity-repository',
-    serviceBaseImport: '@shared/base-classes/synced-entity-service',
-    repositoryInheritedMethods: [
-      'findById, findByIds, list, count, exists, create, update, delete, upsertMany',
-      'findByExternalId, findAllByUserId, findVisibleByUserId, syncUpsert',
-    ],
-    serviceInheritedMethods: [
-      'findById, findByIds, list, count, exists, create, update, delete',
-      'findByExternalId, findAllByUserId, findVisibleByUserId',
-    ],
-  },
-  activity: {
-    repositoryBaseClass: 'ActivityEntityRepository',
-    serviceBaseClass: 'ActivityEntityService',
-    repositoryBaseImport: '@shared/base-classes/activity-entity-repository',
-    serviceBaseImport: '@shared/base-classes/activity-entity-service',
-    repositoryInheritedMethods: [
-      'findById, findByIds, list, count, exists, create, update, delete, upsertMany',
-      'findByDateRange, findByUserId, findByOpportunityId, findRecentByOpportunityId',
-    ],
-    serviceInheritedMethods: [
-      'findById, findByIds, list, count, exists, create, update, delete',
-      'findByDateRange, findByUserId, findByOpportunityId, findRecentByOpportunityId',
-    ],
-  },
-  knowledge: {
-    repositoryBaseClass: 'KnowledgeEntityRepository',
-    serviceBaseClass: 'KnowledgeEntityService',
-    repositoryBaseImport: '@shared/base-classes/knowledge-entity-repository',
-    serviceBaseImport: '@shared/base-classes/knowledge-entity-service',
-    repositoryInheritedMethods: [
-      'findById, findByIds, list, count, exists, create, update, delete, upsertMany',
-      'semanticSearch, findPendingByOpportunityId, updateStatus, updateStatusBatch',
-    ],
-    serviceInheritedMethods: [
-      'findById, findByIds, list, count, exists, create, update, delete',
-      'semanticSearch, findPendingByOpportunityId, updateStatus, updateStatusBatch',
-    ],
-  },
-  metadata: {
-    repositoryBaseClass: 'MetadataEntityRepository',
-    serviceBaseClass: 'MetadataEntityService',
-    repositoryBaseImport: '@shared/base-classes/metadata-entity-repository',
-    serviceBaseImport: '@shared/base-classes/metadata-entity-service',
-    repositoryInheritedMethods: [
-      'findById, findByIds, list, count, exists, create, update, delete, upsertMany',
-      'findByEntityIdAndType, listByEntityId, listHistoryByEntityId',
-    ],
-    serviceInheritedMethods: [
-      'findById, findByIds, list, count, exists, create, update, delete',
-      'findByEntityIdAndType, listByEntityId, listHistoryByEntityId',
-    ],
-  },
-  base: {
-    repositoryBaseClass: 'BaseRepository',
-    serviceBaseClass: 'BaseService',
-    repositoryBaseImport: '@shared/base-classes/base-repository',
-    serviceBaseImport: '@shared/base-classes/base-service',
-    repositoryInheritedMethods: [
-      'findById, findByIds, list, count, exists, create, update, delete, upsertMany',
-    ],
-    serviceInheritedMethods: [
-      'findById, findByIds, list, count, exists, create, update, delete',
-    ],
-  },
-};
+
+/**
+ * Serialize a plain object as an idiomatic TypeScript object literal.
+ * Unlike JSON.stringify, this emits bare identifier keys when legal
+ * (matching the ADR-031 §4 example) and single-quoted strings. Only
+ * the shapes that actually appear in validated pattern configs are
+ * supported — strings, numbers, booleans, nulls, nested objects, and
+ * arrays of the same. Anything else falls through to JSON.stringify
+ * to stay safe.
+ */
+function renderPatternConfigLiteral(value, indent = '  ', initialIndent = '') {
+  // `currentIndent` is the indent applied to the closing brace of the
+  // outermost value; nested lines add one more level of `indent`.
+  // Templates that emit this helper inside an already-indented block
+  // (e.g. a class body indented by 2 spaces) should pass the block's
+  // indent as `initialIndent` so the closing brace and child lines line
+  // up correctly with the surrounding code.
+  return _renderLiteral(value, indent, initialIndent);
+}
+
+function _renderLiteral(value, baseIndent, currentIndent) {
+  if (value === null) return 'null';
+  if (typeof value === 'string') {
+    // Single-quoted TS string with \\ + ' escapes. Matches ADR-031 example style.
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    const next = currentIndent + baseIndent;
+    const items = value.map((v) => `${next}${_renderLiteral(v, baseIndent, next)}`);
+    return `[\n${items.join(',\n')},\n${currentIndent}]`;
+  }
+  if (typeof value === 'object') {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return '{}';
+    const next = currentIndent + baseIndent;
+    const lines = entries.map(([k, v]) => {
+      const key = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) ? k : `'${k}'`;
+      return `${next}${key}: ${_renderLiteral(v, baseIndent, next)}`;
+    });
+    return `{\n${lines.join(',\n')},\n${currentIndent}}`;
+  }
+  // Anything else — fall back to a safe JSON serialization.
+  return JSON.stringify(value);
+}
+
+/**
+ * Resolve the base-class locals (repository + service class name + import
+ * path + inherited-method comment lines) for an entity by looking up its
+ * declared pattern in the shared registry.
+ *
+ * Resolution order:
+ *   1. `entity.pattern` — single-pattern case. Returns that pattern's record.
+ *   2. `entity.patterns[0]` — multi-pattern case: the first name drives the
+ *      base-class choice. Subsequent patterns contribute columns + implied
+ *      behaviors (PATTERN-4 composition check) but do not change the
+ *      template's repository/service base class.
+ *   3. `'Base'` fallback — library pattern that anchors the identity case.
+ *
+ * Exported for unit-testing; consumers import `buildCleanLitePsLocals`.
+ */
+export function resolvePatternBaseClasses(entity) {
+  const name =
+    (typeof entity.pattern === 'string' && entity.pattern) ||
+    (Array.isArray(entity.patterns) && entity.patterns[0]) ||
+    'Base';
+  const def = getPattern(name) || getPattern('Base');
+  if (!def) {
+    throw new Error(
+      `Pattern '${name}' is not registered, and the library 'Base' pattern ` +
+      `is also missing. Did the patterns barrel fail to load?`,
+    );
+  }
+  return {
+    patternName: def.name,
+    repositoryBaseClass: def.repositoryClass,
+    serviceBaseClass: def.serviceClass,
+    repositoryBaseImport: def.repositoryImport,
+    serviceBaseImport: def.serviceImport,
+    repositoryInheritedMethods: def.repositoryInheritedMethods ?? [],
+    serviceInheritedMethods: def.serviceInheritedMethods ?? [],
+  };
+}
 
 // ============================================================================
 // Helper utilities
@@ -87,12 +110,7 @@ const FAMILY_MAP = {
 const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
 const camelCase = (s) => s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 const pascalCase = (s) => capitalize(camelCase(s));
-const pluralize = (s) => {
-  if (s.endsWith('y')) return s.slice(0, -1) + 'ies';
-  if (s.endsWith('s') || s.endsWith('x') || s.endsWith('ch') || s.endsWith('sh'))
-    return s + 'es';
-  return s + 's';
-};
+const pluralize = (s) => pluralizePkg.plural(s);
 
 // ============================================================================
 // Drizzle type mapping
@@ -128,9 +146,11 @@ const DRIZZLE_IMPORT_MAP = {
 const ZOD_TYPE_MAP = {
   string: 'z.string()',
   integer: 'z.number().int()',
-  // PG numeric is returned by Drizzle as a string; z.coerce.number() parses
-  // strings at the boundary while still accepting numeric JSON input.
-  decimal: 'z.coerce.number()',
+  // PG numeric is returned by Drizzle as a string (precision preservation);
+  // z.coerce.string() accepts either JSON string or number and coerces to string
+  // so the DTO type aligns with the entity type. Do arithmetic at the consumer
+  // via Number(value) or a BigNumber library.
+  decimal: 'z.coerce.string()',
   boolean: 'z.boolean()',
   uuid: 'z.string().uuid()',
   date: 'z.coerce.date()',
@@ -145,7 +165,7 @@ const ZOD_TYPE_MAP = {
 const TS_TYPE_MAP = {
   string: 'string',
   integer: 'number',
-  decimal: 'number',
+  decimal: 'string',
   boolean: 'boolean',
   uuid: 'string',
   date: 'Date',
@@ -165,6 +185,15 @@ const BEHAVIOR_MANAGED_FIELDS = new Set([
   'is_active',
 ]);
 
+// Fields injected by external_id_tracking behavior — only behavior-managed when
+// that behavior is enabled (otherwise 'provider' etc. could be a legitimate
+// user-declared field, e.g. on field_definition).
+const EXTERNAL_ID_TRACKING_FIELDS = new Set([
+  'external_id',
+  'provider',
+  'provider_metadata',
+]);
+
 // ============================================================================
 // Field processors
 // ============================================================================
@@ -177,7 +206,16 @@ function buildDrizzleChain(fieldName, field, drizzleType) {
   const required = field.required ?? false;
   const hasDefault = field.default !== undefined && field.default !== null;
 
-  let chain = `${drizzleType}('${fieldName}')`;
+  // Drizzle's `date('x')` returns the PgDateString builder by default
+  // (data type: string). Force the Date-typed variant so DTO Zod
+  // schemas using z.coerce.date() align with the entity type.
+  // `timestamp` already defaults to Date — no mode override needed.
+  let chain;
+  if (drizzleType === 'date') {
+    chain = `${drizzleType}('${fieldName}', { mode: 'date' })`;
+  } else {
+    chain = `${drizzleType}('${fieldName}')`;
+  }
 
   // Add .notNull() for non-nullable required fields
   if (required && !nullable) {
@@ -239,10 +277,26 @@ function processFields(fields) {
   return processed;
 }
 
+/**
+ * Map YAML on_delete value to the Drizzle onDelete option string.
+ *
+ * ADR-021 uses snake_case values in YAML (set_null, no_action) while
+ * Drizzle expects the SQL keyword form with a space ('set null', 'no action').
+ */
+function mapOnDelete(onDelete) {
+  const map = {
+    restrict: 'restrict',
+    cascade: 'cascade',
+    set_null: 'set null',
+    no_action: 'no action',
+  };
+  return map[onDelete] ?? 'restrict';
+}
+
 /**
  * Process belongs_to relationships into BelongsToRelation[]
  */
-function processBelongsTo(relationships) {
+function processBelongsTo(relationships, parentEntityNamePlural) {
   if (!relationships) return [];
 
   const result = [];
@@ -254,6 +308,26 @@ function processBelongsTo(relationships) {
     const field = rel.foreign_key;
     const nullable = rel.nullable ?? true;
     const relatedPlural = pluralize(target);
+    const isSelfFk = relatedPlural === parentEntityNamePlural;
+
+    // on_delete defaults to 'restrict' per ADR-021
+    const onDeleteYaml = rel.on_delete ?? 'restrict';
+    const onDelete = mapOnDelete(onDeleteYaml);
+
+    // Relation key: for self-FKs derive from the FK column name
+    // (parent_account_id → parentAccount) to avoid colliding with the
+    // table's own snake_case name. For non-self-FKs preserve the prior
+    // behavior of using the target entity name verbatim so existing
+    // consumer code (e.g. drizzle queryBuilder.with.field_definition)
+    // keeps working.
+    let relationKey;
+    if (isSelfFk) {
+      // parent_account_id → parent_account → parentAccount
+      const base = field.endsWith('_id') ? field.slice(0, -3) : field;
+      relationKey = camelCase(base);
+    } else {
+      relationKey = target;
+    }
 
     result.push({
       field,
@@ -264,6 +338,10 @@ function processBelongsTo(relationships) {
       relatedPlural,
       nullable,
       importPath: `../${relatedPlural}/${target}.entity`,
+      relationKey,
+      isSelfFk,
+      onDelete,
+      onDeleteYaml,
     });
   }
 
@@ -273,7 +351,7 @@ function processBelongsTo(relationships) {
 /**
  * Collect drizzle imports needed for entity fields
  */
-function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete) {
+function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking) {
   const imports = new Set(['pgTable', 'uuid']);
 
   for (const field of processedFields) {
@@ -291,6 +369,12 @@ function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSof
     imports.add('timestamp');
   }
 
+  // external_id_tracking behavior injects varchar + jsonb columns
+  if (hasExternalIdTracking) {
+    imports.add('varchar');
+    imports.add('jsonb');
+  }
+
   if (belongsTo.length > 0) {
     imports.add('relations');
   }
@@ -456,6 +540,81 @@ function processQueries(queriesBlock, processedFields, entityNamePascal) {
   });
 }
 
+// ============================================================================
+// Search query processing
+// ============================================================================
+
+/**
+ * Process the `queries: - name: search` declarations into template locals.
+ *
+ * A search query compiles down to:
+ *   - A `SearchXsUseCase` class composing the entity service's list+count
+ *     with filter-AND and optional ilike search.
+ *   - A thin `@Get('search')` controller route that runs the request
+ *     querystring through a Zod schema before delegating.
+ *   - A `searchUseCase` / output-path entry so the module/controller
+ *     templates can emit imports + provider entries.
+ *
+ * Multiple search declarations per entity aren't supported yet — first
+ * one wins and a warning surfaces in the emitted comment. Consumers can
+ * split into separate entities if they need multiple search surfaces.
+ */
+function processSearchQueries(queriesBlock, processedFields, belongsTo, entityName, entityNamePascal, entityNamePlural, entityNamePluralPascal) {
+  if (!queriesBlock || !Array.isArray(queriesBlock)) return null;
+  const search = queriesBlock.find((q) => q && q.name === 'search');
+  if (!search) return null;
+
+  const filters = Array.isArray(search.filters) ? search.filters : [];
+  if (filters.length === 0) return null;
+
+  // Build a field->type lookup that covers both regular fields and FK
+  // columns from belongs_to relationships — filters commonly target
+  // account_id / user_id etc.
+  const fieldTypeMap = {};
+  for (const pf of processedFields) {
+    const entry = {
+      tsType: pf.tsType,
+      hasChoices: pf.hasChoices,
+      choices: pf.choices,
+      isUuid: pf.type === 'uuid',
+    };
+    fieldTypeMap[pf.name] = entry;
+    fieldTypeMap[pf.camelName] = entry;
+  }
+  for (const rel of belongsTo) {
+    fieldTypeMap[rel.field] = { tsType: 'string', isUuid: true };
+    fieldTypeMap[rel.camelField] = { tsType: 'string', isUuid: true };
+  }
+
+  const resolvedFilters = filters.map((name) => {
+    const info = fieldTypeMap[name] || fieldTypeMap[camelCase(name)] || { tsType: 'string' };
+    return {
+      name,
+      camelName: camelCase(name),
+      tsType: info.tsType,
+      hasChoices: !!info.hasChoices,
+      choices: info.choices,
+      isUuid: !!info.isUuid,
+      // Booleans + numbers need z.coerce.* in the querystring schema.
+      isBoolean: info.tsType === 'boolean',
+      isNumber: info.tsType === 'number',
+    };
+  });
+
+  const searchField = typeof search.search === 'string' ? search.search : null;
+  const paginate = search.paginate !== false; // default true
+
+  return {
+    filters: resolvedFilters,
+    searchField,
+    searchFieldCamel: searchField ? camelCase(searchField) : null,
+    paginate,
+    useCaseClassName: `Search${entityNamePluralPascal}UseCase`,
+    filtersSchemaName: `${entityNamePascal}FiltersSchema`,
+    inputTypeName: `Search${entityNamePluralPascal}Input`,
+  };
+}
+
 // ============================================================================
 // Main export
 // ============================================================================
@@ -474,17 +633,84 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   const behaviors = definition.behaviors || [];
   const queriesBlock = definition.queries || null;
 
-  // Source root — configurable via baseLocals.srcRoot or entity.src_root, defaults to 'src'
-  const srcRoot = baseLocals.srcRoot || entity.src_root || 'src';
+  // Source root — resolved in priority order:
+  //   1. baseLocals.srcRoot (e.g. set explicitly by tests or callers)
+  //   2. entity.src_root (per-entity override in YAML)
+  //   3. baseLocals.backendSrc (clean-lite-ps reads paths.backend_src from
+  //      codegen.config.yaml; prompt.js threads BASE_PATHS.backendSrc here)
+  //   4. 'src' (sane default for greenfield projects)
+  const srcRoot =
+    baseLocals.srcRoot ||
+    entity.src_root ||
+    baseLocals.backendSrc ||
+    'src';
 
   const entityName = entity.name;
   const entityNamePascal = pascalCase(entityName);
   const entityNamePlural = entity.plural || pluralize(entityName);
   const entityNamePluralPascal = pascalCase(entityNamePlural);
 
-  // Family resolution
-  const family = entity.family || 'base';
-  const familyConfig = FAMILY_MAP[family] || FAMILY_MAP['base'];
+  // Generation toggles — `generate.writes` defaults to true so consumers who
+  // regenerate pick up create/update/delete use cases without YAML changes.
+  // Set `generate.writes: false` in YAML to suppress write-side emission
+  // (use cases, controller routes, module providers).
+  const generateBlock = definition.generate || {};
+  const generateWrites = generateBlock.writes !== false;
+
+  // EAV (ADR-13) — when true, emit paired reads + transactional compound
+  // writes. Consumer must provide `@shared/eav-helpers` and `FieldValueService`.
+  const eavEnabled = definition.eav === true;
+
+  // EAV value-table shape (task #23) — when true, this entity IS the value
+  // table. Templates emit compound methods (upsertFieldsTransactional,
+  // findMergedByEntity) on the service, upsertCurrentValues on the repo,
+  // and auto-wire the paired field-definitions module for DI.
+  const eavValueTable = definition.eav_value_table === true;
+  const eavDefinitionEntity = eavValueTable
+    ? (definition.eav_definition_table || null)
+    : null;
+  const eavDefinitionEntityPlural = eavDefinitionEntity
+    ? pluralize(eavDefinitionEntity)
+    : null;
+  const eavDefinitionPascal = eavDefinitionEntity
+    ? pascalCase(eavDefinitionEntity)
+    : null;
+  const eavDefinitionPluralPascal = eavDefinitionEntityPlural
+    ? pascalCase(eavDefinitionEntityPlural)
+    : null;
+
+  // Pattern resolution — registry-driven (ADR-031, PATTERN-5).
+  //
+  // The prior PATTERN-3 bridge that lowercased the pattern name to index
+  // FAMILY_MAP is gone; the registry returns the canonical record. The
+  // shape returned by `resolvePatternBaseClasses` matches the legacy
+  // FAMILY_MAP entries verbatim for the five library patterns so the
+  // emitted output is byte-identical.
+  const patternBase = resolvePatternBaseClasses(entity);
+  const { patternName } = patternBase;
+  // FAMILY_MAP is gone (PATTERN-5); `patternConfigClasses` is the structural
+  // equivalent — repository + service class names + import paths + inherited
+  // method comment lists, sourced directly from the pattern registry.
+  const patternConfigClasses = {
+    repositoryBaseClass: patternBase.repositoryBaseClass,
+    serviceBaseClass: patternBase.serviceBaseClass,
+    repositoryBaseImport: patternBase.repositoryBaseImport,
+    serviceBaseImport: patternBase.serviceBaseImport,
+    repositoryInheritedMethods: patternBase.repositoryInheritedMethods,
+    serviceInheritedMethods: patternBase.serviceInheritedMethods,
+  };
+  // Per-entity pattern config: resolve the matching block from
+  // `config: { <PatternName>: {...} }`. When the pattern has no
+  // configSchema OR the entity doesn't provide one, this stays null and
+  // templates emit no `patternConfig` property.
+  const patternConfigBlock =
+    (definition.config && definition.config[patternName]) ||
+    (definition.entity && definition.entity.config && definition.entity.config[patternName]) ||
+    null;
+  const hasPatternConfig =
+    patternConfigBlock != null &&
+    typeof patternConfigBlock === 'object' &&
+    Object.keys(patternConfigBlock).length > 0;
 
   // Process entity fields
   const processedFields = processFields(fields);
@@ -493,9 +719,28 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   const behaviorNames = behaviors.map((b) => (typeof b === 'string' ? b : b.name));
   const hasTimestamps = behaviorNames.includes('timestamps');
   const hasSoftDelete = behaviorNames.includes('soft_delete');
+  const hasUserTracking = behaviorNames.includes('user_tracking');
+  const hasExternalIdTracking = behaviorNames.includes('external_id_tracking');
 
   // Process declarative queries
-  const processedQueries = processQueries(queriesBlock, processedFields, entityNamePascal);
+  // Filter out search-named entries — they're handled by
+  // processSearchQueries below. processQueries only understands the
+  // by-column shape.
+  const byColumnQueries = Array.isArray(queriesBlock)
+    ? queriesBlock.filter((q) => q && 'by' in q)
+    : queriesBlock;
+  const processedQueries = processQueries(byColumnQueries, processedFields, entityNamePascal);
+  // Process search query declaration (at most one per entity for now).
+  const searchQuery = processSearchQueries(
+    queriesBlock,
+    processedFields,
+    [], // belongsTo populated below — late-bind via reassignment
+    entityName,
+    entityNamePascal,
+    entityNamePlural,
+    entityNamePluralPascal,
+  );
+
   const hasDeclarativeQueries = processedQueries.length > 0;
   const declarativeQueryClasses = processedQueries.map((q) => q.useCaseClassName);
   const hasMultiFieldQuery = processedQueries.some((q) => q.hasMultipleParams);
@@ -503,14 +748,43 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   const hasViaQuery = processedQueries.some((q) => q.hasVia);
 
   // Process belongs_to relationships
-  const belongsTo = processBelongsTo(relationships);
+  const belongsTo = processBelongsTo(relationships, entityNamePlural);
+
+  // 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.
+  if (hasSoftDelete && belongsTo.some((rel) => rel.onDeleteYaml !== 'restrict')) {
+    const affectedRels = belongsTo
+      .filter((rel) => rel.onDeleteYaml !== 'restrict')
+      .map((rel) => `${rel.field} (on_delete: ${rel.onDeleteYaml})`)
+      .join(', ');
+    console.warn(
+      `[codegen] WARNING: ${entityName} has soft_delete behavior but declares non-restrict on_delete on: ${affectedRels}. ` +
+      `on_delete is a no-op for soft-delete — only hard-DELETE triggers Postgres cascade rules. ` +
+      `See ADR-021: docs/adrs/ADR-021-on-delete-semantics.md`,
+    );
+  }
+
+  // Re-process search query now that belongsTo is known — filters can
+  // reference FK columns (account_id, user_id) which aren't in
+  // processedFields because they're emitted by the belongsTo loop.
+  const searchQueryResolved = processSearchQueries(
+    queriesBlock,
+    processedFields,
+    belongsTo,
+    entityName,
+    entityNamePascal,
+    entityNamePlural,
+    entityNamePluralPascal,
+  );
+
 
   // Filter FK fields that are already emitted by the clpBelongsTo loop
   const fkFieldNames = new Set(belongsTo.map((r) => r.field));
   const nonFkFields = processedFields.filter((f) => !fkFieldNames.has(f.name));
 
   // Drizzle imports needed
-  const drizzleEntityImports = collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete);
+  const drizzleEntityImports = collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSoftDelete, hasExternalIdTracking);
   // Whether relations() import is needed
   const hasRelationsBlock = belongsTo.length > 0;
 
@@ -521,11 +795,33 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     service: `${srcRoot}/modules/${entityNamePlural}/${entityName}.service.ts`,
     controller: `${srcRoot}/modules/${entityNamePlural}/${entityName}.controller.ts`,
     module: `${srcRoot}/modules/${entityNamePlural}/${entityNamePlural}.module.ts`,
+    index: `${srcRoot}/modules/${entityNamePlural}/index.ts`,
     findByIdUseCase: `${srcRoot}/modules/${entityNamePlural}/use-cases/find-${entityName}-by-id.use-case.ts`,
     listUseCase: `${srcRoot}/modules/${entityNamePlural}/use-cases/list-${entityNamePlural}.use-case.ts`,
+    findByIdWithFieldsUseCase: eavEnabled
+      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/find-${entityName}-by-id-with-fields.use-case.ts`
+      : null,
+    listWithFieldsUseCase: eavEnabled
+      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/list-${entityNamePlural}-with-fields.use-case.ts`
+      : null,
+    createUseCase: generateWrites
+      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/create-${entityName}.use-case.ts`
+      : null,
+    updateUseCase: generateWrites
+      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/update-${entityName}.use-case.ts`
+      : null,
+    deleteUseCase: generateWrites
+      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/delete-${entityName}.use-case.ts`
+      : null,
     createDto: `${srcRoot}/modules/${entityNamePlural}/dto/create-${entityName}.dto.ts`,
     updateDto: `${srcRoot}/modules/${entityNamePlural}/dto/update-${entityName}.dto.ts`,
     outputDto: `${srcRoot}/modules/${entityNamePlural}/dto/${entityName}-output.dto.ts`,
+    searchUseCase: searchQueryResolved
+      ? `${srcRoot}/modules/${entityNamePlural}/use-cases/search-${entityNamePlural}.use-case.ts`
+      : null,
+    searchController: searchQueryResolved
+      ? `${srcRoot}/modules/${entityNamePlural}/${entityName}-search.controller.ts`
+      : null,
     declarativeQueries: hasDeclarativeQueries
       ? `${srcRoot}/modules/${entityNamePlural}/use-cases/declarative-queries.ts`
       : null,
@@ -540,7 +836,14 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     controller: `${entityNamePascal}Controller`,
     module: `${entityNamePluralPascal}Module`,
     findByIdUseCase: `Find${entityNamePascal}ByIdUseCase`,
+    searchUseCase: `Search${entityNamePluralPascal}UseCase`,
+    searchController: `${entityNamePascal}SearchController`,
     listUseCase: `List${entityNamePluralPascal}UseCase`,
+    findByIdWithFieldsUseCase: `Find${entityNamePascal}ByIdWithFieldsUseCase`,
+    listWithFieldsUseCase: `List${entityNamePluralPascal}WithFieldsUseCase`,
+    createUseCase: `Create${entityNamePascal}UseCase`,
+    updateUseCase: `Update${entityNamePascal}UseCase`,
+    deleteUseCase: `Delete${entityNamePascal}UseCase`,
     createDto: `Create${entityNamePascal}Dto`,
     updateDto: `Update${entityNamePascal}Dto`,
     outputDto: `${entityNamePascal}OutputDto`,
@@ -551,7 +854,8 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
 
   // Fields for create DTO: exclude id, behavior-managed fields, and FK fields
   const createDtoFields = nonFkFields.filter(
-    (f) => !BEHAVIOR_MANAGED_FIELDS.has(f.name),
+    (f) => !BEHAVIOR_MANAGED_FIELDS.has(f.name)
+        && !(hasExternalIdTracking && EXTERNAL_ID_TRACKING_FIELDS.has(f.name)),
   );
 
   // FK fields from belongs_to for create/output DTOs
@@ -568,12 +872,36 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     zodChainCreate: zodChainForCreate(f),
   }));
 
-  // Build zodChain for each output DTO field (all non-FK fields)
-  const outputDtoFields = nonFkFields.map((f) => ({
+  // Build zodChain for each output DTO field (all non-FK fields).
+  // When external_id_tracking is enabled, its fields are injected into the
+  // entity table but do not appear in the output DTO (they're metadata).
+  const outputDtoSource = hasExternalIdTracking
+    ? nonFkFields.filter((f) => !EXTERNAL_ID_TRACKING_FIELDS.has(f.name))
+    : nonFkFields;
+  const outputDtoFields = outputDtoSource.map((f) => ({
     ...f,
     zodChainOutput: zodChainForOutput(f),
   }));
 
+  // EVT-7: emits locals flow through from baseLocals (prompt.js computed them
+  // against the full events registry). When this helper is called in isolation
+  // (e.g. from unit tests) baseLocals.hasEmits may be undefined — provide
+  // null-safe defaults so the CLP templates emits guards evaluate to false
+  // cleanly.
+  const hasEmits = Boolean(baseLocals?.hasEmits);
+  const emitsEvents = baseLocals?.emitsEvents ?? [];
+  const createEventType = baseLocals?.createEventType ?? null;
+  const updateEventType = baseLocals?.updateEventType ?? null;
+  const deleteEventType = baseLocals?.deleteEventType ?? null;
+  const eventsTokenImport =
+    baseLocals?.eventsTokenImport ?? '@shared/subsystems/events';
+  const typedEventBusImport =
+    baseLocals?.typedEventBusImport ?? '@shared/subsystems/events';
+  const drizzleTokenImport =
+    baseLocals?.drizzleTokenImport ?? '@shared/constants/tokens';
+  const drizzleTypeImport =
+    baseLocals?.drizzleTypeImport ?? '@shared/types/drizzle';
+
   return {
     // Clean-Lite-PS identity
     entityName,
@@ -581,13 +909,46 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     entityNamePlural,
     entityNamePluralPascal,
 
-    // Family
-    family,
-    ...familyConfig,
+    // EVT-7 emits locals (null-safe defaults if baseLocals didn't provide them)
+    hasEmits,
+    emitsEvents,
+    createEventType,
+    updateEventType,
+    deleteEventType,
+    eventsTokenImport,
+    typedEventBusImport,
+    drizzleTokenImport,
+    drizzleTypeImport,
+
+    // Pattern — registry-driven (ADR-031)
+    patternName,
+    hasPatternConfig,
+    patternConfig: patternConfigBlock,
+    renderPatternConfigLiteral,
+    ...patternConfigClasses,
 
     // Behavior flags (also exposed at top level for template use)
     hasTimestamps,
     hasSoftDelete,
+    hasUserTracking,
+    hasExternalIdTracking,
+
+    // Generation toggles
+    generateWrites,
+
+    // EAV (ADR-13)
+    eavEnabled,
+
+    // EAV value-table (task #23) — this entity IS the value table.
+    eavValueTable,
+    eavDefinitionEntity,
+    eavDefinitionEntityPlural,
+    eavDefinitionPascal,
+    eavDefinitionPluralPascal,
+    // Search query (#16)
+    searchQuery: searchQueryResolved,
+    hasSearchQuery: !!searchQueryResolved,
+
 
     // Output paths
     clpOutputPaths: outputPaths,