@pattern-stack/codegen 0.2.0 → 0.3.0

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

@@ -7,10 +7,13 @@ import { Injectable, Inject } from '@nestjs/common';
 <% if (hasDeclarativeQueries) { -%>
 import { eq<%= hasMultiFieldQuery ? ', and' : '' %><%= hasOrderedQuery ? ', desc, asc' : '' %> } from 'drizzle-orm';
 <% } -%>
+<% if (eavValueTable) { -%>
+import { sql } from 'drizzle-orm';
+<% } -%>
 import { DRIZZLE } from '@shared/constants/tokens';
-import type { DrizzleClient } from '@shared/types/drizzle';
+import type { DrizzleClient<% if (eavValueTable) { %>, DrizzleTx<% } %> } from '@shared/types/drizzle';
 import { <%= repositoryBaseClass %> } from '<%= repositoryBaseImport %>';
-<% if (hasTimestamps || hasSoftDelete) { -%>
+<% if (hasTimestamps || hasSoftDelete || hasUserTracking) { -%>
 import type { BehaviorConfig } from '@shared/base-classes/base-repository';
 <% } -%>
 import { <%= entityNamePlural %>, type <%= classNames.entity %> } from './<%= entityName %>.entity';
@@ -18,15 +21,23 @@ import { <%= entityNamePlural %>, type <%= classNames.entity %> } from './<%= en
 @Injectable()
 export class <%= classNames.repository %> extends <%= repositoryBaseClass %><<%= classNames.entity %>> {
   readonly table = <%= entityNamePlural %>;
-<% if (hasTimestamps || hasSoftDelete) { -%>
+<% if (hasTimestamps || hasSoftDelete || hasUserTracking) { -%>
 
   // Behaviors declared in YAML -> generated as config object
   protected override readonly behaviors: BehaviorConfig = {
     timestamps: <%= !!hasTimestamps %>,
     softDelete: <%= !!hasSoftDelete %>,
-    userTracking: false,
+    userTracking: <%= !!hasUserTracking %>,
   };
 <% } -%>
+<% if (hasPatternConfig) { -%>
+
+  // Per-entity `<%= patternName %>` pattern config (from YAML `config:` block).
+  // The pattern's base class declares `protected readonly patternConfig: TConfig`
+  // typed via its `configSchema`; this concrete record is read by the base at
+  // runtime (identical shape to `behaviors: BehaviorConfig`).
+  protected override readonly patternConfig = <%- renderPatternConfigLiteral(patternConfig, '  ', '  ') %> as const;
+<% } -%>
 
   constructor(@Inject(DRIZZLE) db: DrizzleClient) {
     super(db);
@@ -55,6 +66,48 @@ export class <%= classNames.repository %> extends <%= repositoryBaseClass %><<%=
 
   // TODO: Add entity-specific query methods here.
 <% } -%>
+<% if (eavValueTable) { -%>
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // EAV compound writes (task #23) — generated from eav_value_table: true
+  // ═══════════════════════════════════════════════════════════════════════
+  /**
+   * Upsert "current" value rows keyed by the composite unique
+   * (entity_type, entity_id, field_definition_id). Used by the service's
+   * upsertFieldsTransactional to dual-write a bag of dynamic fields
+   * atomically with the owning entity. Inherited upsertMany only
+   * supports single-column conflict targets — this override uses
+   * Drizzle's `onConflictDoUpdate` with an explicit column list.
+   */
+  async upsertCurrentValues(
+    inputs: Array<Partial<<%= classNames.entity %>>>,
+    tx?: DrizzleTx,
+  ): Promise<<%= classNames.entity %>[]> {
+    if (inputs.length === 0) return [];
+    const data = inputs.map((input) =>
+      this.withTimestamps(input as Record<string, unknown>, 'create'),
+    );
+    const runner = this.runner(tx);
+    const rows = await runner
+      .insert(this.table)
+      .values(data as any) // eslint-disable-line @typescript-eslint/no-explicit-any
+      .onConflictDoUpdate({
+        target: [
+          this.table['entityType'],
+          this.table['entityId'],
+          this.table['fieldDefinitionId'],
+        ],
+        set: {
+          value: sql`excluded.value`,
+          userId: sql`excluded.user_id`,
+          updatedAt: sql`excluded.updated_at`,
+        } as any, // eslint-disable-line @typescript-eslint/no-explicit-any
+      })
+      .returning();
+    return rows as <%= classNames.entity %>[];
+  }
+<% } -%>
+
   // Inherited from <%= repositoryBaseClass %>:
 <%_ repositoryInheritedMethods.forEach(line => { _%>
   //   <%= line %>

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

@@ -0,0 +1,50 @@
+---
+to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.searchController : null %>"
+skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.searchController %>"
+force: true
+---
+<% if (hasSearchQuery) { -%>
+import { BadRequestException, Controller, Get, Query } from '@nestjs/common';
+import { z } from 'zod';
+import { PaginationSchema } from '@shared/http/pagination';
+import { <%= searchQuery.useCaseClassName %> } from './use-cases/search-<%= entityNamePlural %>.use-case';
+
+const <%= searchQuery.filtersSchemaName %> = z.object({
+<% searchQuery.filters.forEach((f) => { -%>
+<% if (f.isUuid) { -%>
+  <%= f.camelName %>: z.string().uuid().optional(),
+<% } else if (f.hasChoices) { -%>
+  <%= f.camelName %>: z.enum([<%- f.choices.map((c) => `'${c}'`).join(', ') %>]).optional(),
+<% } else if (f.isBoolean) { -%>
+  <%= f.camelName %>: z.coerce.boolean().optional(),
+<% } else if (f.isNumber) { -%>
+  <%= f.camelName %>: z.coerce.number().optional(),
+<% } else { -%>
+  <%= f.camelName %>: z.string().optional(),
+<% } -%>
+<% }) -%>
+<% if (searchQuery.searchField) { -%>
+  search: z.string().optional(),
+<% } -%>
+}).merge(PaginationSchema);
+
+function parseOrThrow<S extends z.ZodTypeAny>(schema: S, input: unknown): z.infer<S> {
+  const result = schema.safeParse(input);
+  if (!result.success) throw new BadRequestException(result.error.flatten());
+  return result.data;
+}
+
+/**
+ * Filtered search controller (task #16) — generated from queries:
+ * block in <%= entityName %>.yaml.
+ */
+@Controller('<%= entityNamePlural %>')
+export class <%= classNames.searchController %> {
+  constructor(private readonly searchUseCase: <%= searchQuery.useCaseClassName %>) {}
+
+  @Get('search')
+  async search(@Query() query: Record<string, unknown>) {
+    return this.searchUseCase.execute(parseOrThrow(<%= searchQuery.filtersSchemaName %>, query));
+  }
+}
+<% } -%>

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

@@ -9,18 +9,41 @@ import { EVENT_BUS } from '@shared/constants/tokens';
 import { <%= serviceBaseClass %> } from '<%= serviceBaseImport %>';
 import { <%= classNames.repository %> } from './<%= entityName %>.repository';
 import type { <%= classNames.entity %> } from './<%= entityName %>.entity';
+<% if (eavEnabled) { -%>
+import { FieldValueService } from '../field_values/field_value.service';
+<% } -%>
+<% if (eavValueTable) { -%>
+import { toEavRows, mergeEavRows } from '@shared/eav-helpers';
+import type { DrizzleTx } from '@shared/types/drizzle';
+import { <%= eavDefinitionPascal %>Repository } from '../<%= eavDefinitionEntityPlural %>/<%= eavDefinitionEntity %>.repository';
+<% } -%>
 
 @Injectable()
 export class <%= classNames.service %> extends WithAnalytics(
   <%= serviceBaseClass %><<%= classNames.repository %>, <%= classNames.entity %>>,
 ) {
   protected override readonly entityName = '<%= entityName %>';
+<% if (hasPatternConfig) { -%>
+
+  // Per-entity `<%= patternName %>` pattern config (from YAML `config:` block).
+  // Mirrors the repository-side emission; the pattern's base service reads
+  // `this.patternConfig` directly.
+  protected override readonly patternConfig = <%- renderPatternConfigLiteral(patternConfig, '  ', '  ') %> as const;
+<% } -%>
 
   /** Injected by NestJS when EventsModule is registered. */
   @Optional() @Inject(EVENT_BUS)
   protected override eventBus: any = undefined;
 
-  constructor(protected readonly repository: <%= classNames.repository %>) {
+  constructor(
+    protected override readonly repository: <%= classNames.repository %>,
+<% if (eavEnabled) { -%>
+    private readonly fieldValues: FieldValueService,
+<% } -%>
+<% if (eavValueTable) { -%>
+    private readonly definitionRepo: <%= eavDefinitionPascal %>Repository,
+<% } -%>
+  ) {
     super(repository);
   }
 
@@ -31,4 +54,78 @@ export class <%= classNames.service %> extends WithAnalytics(
 <%_ serviceInheritedMethods.forEach(line => { _%>
   //   <%= line %>
 <%_ }) _%>
+<% if (eavEnabled) { %>
+  /**
+   * EAV paired read (ADR-13): fetch the entity and merge dynamic `field_values`
+   * into a single `fields` bag. FieldValueService owns the FieldDefinition
+   * lookup internally. Use this for frontend detail views, LLM context,
+   * exports.
+   */
+  async findByIdWithFields(
+    id: string,
+  ): Promise<(<%= classNames.entity %> & { fields: Record<string, unknown> }) | null> {
+    const entity = await this.repository.findById(id);
+    if (!entity) return null;
+    const fields = await this.fieldValues.findMergedByEntity('<%= entityName %>', id);
+    return { ...entity, fields };
+  }
+
+  /**
+   * EAV paired read (ADR-13): list variant. Fetches all entities then merges
+   * each one's EAV fields via FieldValueService. Acceptable for modest result
+   * sets; page externally for large collections.
+   */
+  async listWithFields(): Promise<Array<<%= classNames.entity %> & { fields: Record<string, unknown> }>> {
+    const entities = await this.repository.list();
+    if (entities.length === 0) return [];
+    return Promise.all(
+      entities.map(async (entity) => {
+        const fields = await this.fieldValues.findMergedByEntity('<%= entityName %>', entity.id);
+        return { ...entity, fields };
+      }),
+    );
+  }
+<% } %>
+<% if (eavValueTable) { %>
+  /**
+   * EAV compound write (task #23) — upserts a bag of dynamic fields onto
+   * an owning entity in a single transaction. Resolves field keys to
+   * definition ids internally (by reading <%= eavDefinitionPascal %>Repository),
+   * so use-cases inject only this service. Unknown keys are skipped; the
+   * caller is expected to have created the definitions first (auto-create
+   * is a later step).
+   */
+  async upsertFieldsTransactional(
+    entityType: string,
+    entityId: string,
+    userId: string,
+    fields: Record<string, unknown>,
+    tx?: DrizzleTx,
+  ): Promise<void> {
+    if (!fields || Object.keys(fields).length === 0) return;
+    const allDefs = await this.definitionRepo.list();
+    const defs = allDefs.filter((d) => (d as any).entityType === entityType);
+    const defIdByKey = new Map(defs.map((d) => [d.key, d.id]));
+    const rows = toEavRows(entityId, entityType, userId, fields, defIdByKey);
+    if (rows.length === 0) return;
+    await this.repository.upsertCurrentValues(rows as Array<Partial<<%= classNames.entity %>>>, tx);
+  }
+
+  /**
+   * EAV paired read (task #23) — returns the current merged `{ key: value }`
+   * bag for one owning entity. Resolves definition ids to keys internally.
+   */
+  async findMergedByEntity(
+    entityType: string,
+    entityId: string,
+  ): Promise<Record<string, unknown>> {
+    const [rows, allDefs] = await Promise.all([
+      this.repository.findByEntityIdAndType(entityId, entityType),
+      this.definitionRepo.list(),
+    ]);
+    const defs = allDefs.filter((d) => (d as any).entityType === entityType);
+    const defsById = new Map(defs.map((d) => [d.id, { key: d.key }]));
+    return mergeEavRows(rows as any, defsById);
+  }
+<% } %>
 }

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

@@ -0,0 +1,150 @@
+---
+to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.createUseCase : null %>"
+skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.createUseCase %>"
+force: true
+---
+<% if (eavEnabled) { -%>
+import { Injectable, Inject } from '@nestjs/common';
+import { DRIZZLE } from '<%= drizzleTokenImport %>';
+import type { DrizzleClient } from '<%= drizzleTypeImport %>';
+<% if (hasEmits && createEventType) { -%>
+import { TYPED_EVENT_BUS, TypedEventBus } from '<%= eventsTokenImport %>';
+<% } -%>
+import { FieldValueService } from '../../field_values/field_value.service';
+import { <%= classNames.service %> } from '../<%= entityName %>.service';
+import type { <%= classNames.createDto %> } from '../dto/create-<%= entityName %>.dto';
+import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';
+
+/**
+ * EAV compound-write use case (ADR-13).
+ *
+ * Splits `{ fields, ...core }` from the DTO and persists both halves in a
+ * single transaction: core columns go to the <%= entityName %> table via
+ * <%= classNames.service %>, dynamic `fields` go to `field_values` via
+ * FieldValueService.upsertFieldsTransactional (which owns the
+ * FieldDefinition lookup internally). Atomicity comes from the shared tx;
+ * each service still only writes its own domain.
+<% if (hasEmits && createEventType) { -%>
+ *
+ * EXTENSION POINT (EVT-7): verify payload mapping against
+ * events/<%= createEventType.type %>.yaml before shipping.
+<% } -%>
+ */
+@Injectable()
+export class <%= classNames.createUseCase %> {
+  constructor(
+    private readonly <%= entityNamePlural %>: <%= classNames.service %>,
+    private readonly fields: FieldValueService,
+    @Inject(DRIZZLE) private readonly db: DrizzleClient,
+<% if (hasEmits && createEventType) { -%>
+    @Inject(TYPED_EVENT_BUS) private readonly typedEvents: TypedEventBus,
+<% } -%>
+  ) {}
+
+  async execute(
+    dto: <%= classNames.createDto %> & { fields?: Record<string, unknown> },
+    <%= hasEmits && createEventType ? 'opts' : '_opts' %>?: { actor?: { tenantId?: string | null; userId?: string } },
+  ): Promise<<%= classNames.entity %>> {
+    return this.db.transaction(async (tx) => {
+      const { fields, ...core } = dto;
+      const entity = await this.<%= entityNamePlural %>.create(core as <%= classNames.createDto %>, tx);
+      if (fields && Object.keys(fields).length > 0) {
+        await this.fields.upsertFieldsTransactional(
+          '<%= entityName %>',
+          entity.id,
+          core.userId,
+          fields,
+          tx,
+        );
+      }
+<% if (hasEmits && createEventType) { -%>
+      // TODO: verify payload mapping against events/<%= createEventType.type %>.yaml
+      await this.typedEvents.publish(
+        '<%= createEventType.type %>',
+        entity.id,
+        {
+<% createEventType.payloadMap.forEach((p) => { -%>
+          <%= p.camelKey %>: <%- p.expression %>,<% if (p.todo) { %> // TODO: <%= p.todo %><% } %>
+
+<% }) -%>
+        },
+        {
+          tx,
+          metadata: opts?.actor
+            ? { tenantId: opts.actor.tenantId, userId: opts.actor.userId }
+            : undefined,
+        },
+      );
+<% } -%>
+      return entity;
+    });
+  }
+}
+<% } else { -%>
+<% if (hasEmits && createEventType) { -%>
+import { Injectable, Inject } from '@nestjs/common';
+import { DRIZZLE } from '<%= drizzleTokenImport %>';
+import type { DrizzleClient } from '<%= drizzleTypeImport %>';
+import { TYPED_EVENT_BUS, TypedEventBus } from '<%= eventsTokenImport %>';
+import { <%= classNames.service %> } from '../<%= entityName %>.service';
+import type { <%= classNames.createDto %> } from '../dto/create-<%= entityName %>.dto';
+import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';
+
+/**
+ * EXTENSION POINT (EVT-7): verify payload mapping against
+ * events/<%= createEventType.type %>.yaml before shipping.
+ */
+@Injectable()
+export class <%= classNames.createUseCase %> {
+  constructor(
+    private readonly service: <%= classNames.service %>,
+    @Inject(DRIZZLE) private readonly db: DrizzleClient,
+    @Inject(TYPED_EVENT_BUS) private readonly typedEvents: TypedEventBus,
+  ) {}
+
+  async execute(
+    dto: <%= classNames.createDto %>,
+    opts?: { actor?: { tenantId?: string | null; userId?: string } },
+  ): Promise<<%= classNames.entity %>> {
+    return this.db.transaction(async (tx) => {
+      const entity = await this.service.create(dto, tx);
+      // TODO: verify payload mapping against events/<%= createEventType.type %>.yaml
+      await this.typedEvents.publish(
+        '<%= createEventType.type %>',
+        entity.id,
+        {
+<% createEventType.payloadMap.forEach((p) => { -%>
+          <%= p.camelKey %>: <%- p.expression %>,<% if (p.todo) { %> // TODO: <%= p.todo %><% } %>
+
+<% }) -%>
+        },
+        {
+          tx,
+          metadata: opts?.actor
+            ? { tenantId: opts.actor.tenantId, userId: opts.actor.userId }
+            : undefined,
+        },
+      );
+      return entity;
+    });
+  }
+}
+<% } else { -%>
+import { Injectable } from '@nestjs/common';
+import { <%= classNames.service %> } from '../<%= entityName %>.service';
+import type { <%= classNames.createDto %> } from '../dto/create-<%= entityName %>.dto';
+import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';
+
+@Injectable()
+export class <%= classNames.createUseCase %> {
+  constructor(private readonly service: <%= classNames.service %>) {}
+
+  async execute(
+    dto: <%= classNames.createDto %>,
+    _opts?: { actor?: { tenantId?: string | null; userId?: string } },
+  ): Promise<<%= classNames.entity %>> {
+    return this.service.create(dto);
+  }
+}
+<% } -%>
+<% } -%>

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

@@ -0,0 +1,70 @@
+---
+to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.deleteUseCase : null %>"
+skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.deleteUseCase %>"
+force: true
+---
+<% if (hasEmits && deleteEventType) { -%>
+import { Injectable, Inject, NotFoundException } from '@nestjs/common';
+import { DRIZZLE } from '<%= drizzleTokenImport %>';
+import type { DrizzleClient } from '<%= drizzleTypeImport %>';
+import { TYPED_EVENT_BUS, TypedEventBus } from '<%= eventsTokenImport %>';
+import { <%= classNames.service %> } from '../<%= entityName %>.service';
+
+/**
+ * EXTENSION POINT (EVT-7): verify payload mapping against
+ * events/<%= deleteEventType.type %>.yaml before shipping.
+ */
+@Injectable()
+export class <%= classNames.deleteUseCase %> {
+  constructor(
+    private readonly service: <%= classNames.service %>,
+    @Inject(DRIZZLE) private readonly db: DrizzleClient,
+    @Inject(TYPED_EVENT_BUS) private readonly typedEvents: TypedEventBus,
+  ) {}
+
+  async execute(
+    id: string,
+    opts?: { actor?: { tenantId?: string | null; userId?: string } },
+  ): Promise<void> {
+    return this.db.transaction(async (tx) => {
+      const entity = await this.service.findById(id);
+      if (!entity) {
+        throw new NotFoundException(`<%= classNames.entity %> with id ${id} not found`);
+      }
+      await this.service.delete(id, tx);
+      // TODO: verify payload mapping against events/<%= deleteEventType.type %>.yaml
+      await this.typedEvents.publish(
+        '<%= deleteEventType.type %>',
+        entity.id,
+        {
+<% deleteEventType.payloadMap.forEach((p) => { -%>
+          <%= p.camelKey %>: <%- p.expression %>,<% if (p.todo) { %> // TODO: <%= p.todo %><% } %>
+
+<% }) -%>
+        },
+        {
+          tx,
+          metadata: opts?.actor
+            ? { tenantId: opts.actor.tenantId, userId: opts.actor.userId }
+            : undefined,
+        },
+      );
+    });
+  }
+}
+<% } else { -%>
+import { Injectable } from '@nestjs/common';
+import { <%= classNames.service %> } from '../<%= entityName %>.service';
+
+@Injectable()
+export class <%= classNames.deleteUseCase %> {
+  constructor(private readonly service: <%= classNames.service %>) {}
+
+  async execute(
+    id: string,
+    _opts?: { actor?: { tenantId?: string | null; userId?: string } },
+  ): Promise<void> {
+    return this.service.delete(id);
+  }
+}
+<% } -%>

package/templates/entity/new/clean-lite-ps/use-cases/find-by-id-with-fields.ejs.t

@@ -0,0 +1,19 @@
+---
+to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.findByIdWithFieldsUseCase : null %>"
+skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.findByIdWithFieldsUseCase %>"
+force: true
+---
+import { Injectable } from '@nestjs/common';
+import { <%= classNames.service %> } from '../<%= entityName %>.service';
+import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';
+
+@Injectable()
+export class <%= classNames.findByIdWithFieldsUseCase %> {
+  constructor(private readonly service: <%= classNames.service %>) {}
+
+  async execute(
+    id: string,
+  ): Promise<(<%= classNames.entity %> & { fields: Record<string, unknown> }) | null> {
+    return this.service.findByIdWithFields(id);
+  }
+}

package/templates/entity/new/clean-lite-ps/use-cases/find-by-id.ejs.t

@@ -2,7 +2,7 @@
 to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.findByIdUseCase : null %>"
 force: true
 ---
-import { Injectable } from '@nestjs/common';
+import { Injectable, NotFoundException } from '@nestjs/common';
 import { <%= classNames.service %> } from '../<%= entityName %>.service';
 import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';
 
@@ -10,7 +10,11 @@ import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';
 export class <%= classNames.findByIdUseCase %> {
   constructor(private readonly service: <%= classNames.service %>) {}
 
-  async execute(id: string): Promise<<%= classNames.entity %> | null> {
-    return this.service.findById(id);
+  async execute(id: string): Promise<<%= classNames.entity %>> {
+    const entity = await this.service.findById(id);
+    if (entity === null || entity === undefined) {
+      throw new NotFoundException(`<%= classNames.entity %> not found: ${id}`);
+    }
+    return entity;
   }
 }

package/templates/entity/new/clean-lite-ps/use-cases/list-with-fields.ejs.t

@@ -0,0 +1,17 @@
+---
+to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.listWithFieldsUseCase : null %>"
+skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.listWithFieldsUseCase %>"
+force: true
+---
+import { Injectable } from '@nestjs/common';
+import { <%= classNames.service %> } from '../<%= entityName %>.service';
+import type { <%= classNames.entity %> } from '../<%= entityName %>.entity';
+
+@Injectable()
+export class <%= classNames.listWithFieldsUseCase %> {
+  constructor(private readonly service: <%= classNames.service %>) {}
+
+  async execute(): Promise<Array<<%= classNames.entity %> & { fields: Record<string, unknown> }>> {
+    return this.service.listWithFields();
+  }
+}

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

@@ -0,0 +1,63 @@
+---
+to: "<%= typeof clpOutputPaths !== 'undefined' ? clpOutputPaths.searchUseCase : null %>"
+skip_if: "<%= typeof clpOutputPaths === 'undefined' || !clpOutputPaths.searchUseCase %>"
+force: true
+---
+<% if (hasSearchQuery) { -%>
+import { Injectable } from '@nestjs/common';
+import { and, asc, eq<% if (searchQuery.searchField) { %>, ilike<% } %>, type SQL } from 'drizzle-orm';
+import type { Page } from '@shared/http/pagination';
+import { <%= classNames.service %> } from '../<%= entityName %>.service';
+import { <%= entityNamePlural %>, type <%= classNames.entity %> } from '../<%= entityName %>.entity';
+
+export interface <%= searchQuery.inputTypeName %> {
+<% searchQuery.filters.forEach((f) => { -%>
+  <%= f.camelName %>?: <%- f.hasChoices ? f.choices.map((c) => `'${c}'`).join(' | ') : f.tsType %>;
+<% }) -%>
+<% if (searchQuery.searchField) { -%>
+  search?: string;
+<% } -%>
+<% if (searchQuery.paginate) { -%>
+  limit: number;
+  offset: number;
+<% } -%>
+}
+
+/**
+ * Filtered search use case (task #16).
+ *
+ * Composes the entity service's `list` + `count` with filter-AND and
+ * an optional ilike search on `<%= searchQuery.searchField ?? 'N/A' %>`.
+ * Pagination is enforced at the Zod layer in the controller.
+ */
+@Injectable()
+export class <%= searchQuery.useCaseClassName %> {
+  constructor(private readonly service: <%= classNames.service %>) {}
+
+  async execute(input: <%= searchQuery.inputTypeName %>): Promise<Page<<%= classNames.entity %>>> {
+    const conditions: SQL[] = [];
+<% searchQuery.filters.forEach((f) => { -%>
+<% if (f.isBoolean) { -%>
+    if (input.<%= f.camelName %> !== undefined) conditions.push(eq(<%= entityNamePlural %>.<%= f.camelName %>, input.<%= f.camelName %>));
+<% } else { -%>
+    if (input.<%= f.camelName %>) conditions.push(eq(<%= entityNamePlural %>.<%= f.camelName %>, input.<%= f.camelName %>));
+<% } -%>
+<% }) -%>
+<% if (searchQuery.searchField) { -%>
+    if (input.search) conditions.push(ilike(<%= entityNamePlural %>.<%= searchQuery.searchFieldCamel %>, `%${input.search}%`));
+<% } -%>
+
+    const where =
+      conditions.length === 0 ? undefined :
+      conditions.length === 1 ? conditions[0] :
+      and(...conditions);
+
+    const [items, total] = await Promise.all([
+      this.service.list({ where, limit: input.limit, offset: input.offset, orderBy: asc(<%= entityNamePlural %>.createdAt) }),
+      this.service.count(where),
+    ]);
+
+    return { items, total, limit: input.limit, offset: input.offset };
+  }
+}
+<% } -%>