@pattern-stack/codegen 0.2.0

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

@@ -0,0 +1,259 @@
+---
+to: src/infrastructure/broadcast/websocket-broadcast.backend.ts
+force: true
+---
+import { Injectable, Logger } from '@nestjs/common'
+import {
+  WebSocketGateway,
+  WebSocketServer,
+  SubscribeMessage,
+  OnGatewayConnection,
+  OnGatewayDisconnect,
+  ConnectedSocket,
+  MessageBody,
+} from '@nestjs/websockets'
+import type { Server, Socket } from 'socket.io'
+import type {
+  BroadcastBackend,
+  BroadcastHandler,
+} from './broadcast-backend.interface'
+
+interface SubscribePayload {
+  channels: string[]
+}
+
+interface UnsubscribePayload {
+  channels: string[]
+}
+
+interface BroadcastMessage {
+  channel: string
+  event: string
+  payload: Record<string, unknown>
+}
+
+/**
+ * WebSocket-based broadcast backend using Socket.IO.
+ * Clients connect and subscribe to channels to receive real-time domain events.
+ *
+ * Protocol:
+ *   Client → Server: { "subscribe": ["session", "agent"] }
+ *   Client → Server: { "unsubscribe": ["session"] }
+ *   Server → Client: { "channel": "session", "event": "session.running", "payload": {...} }
+ */
+@Injectable()
+@WebSocketGateway({
+  path: '<%= websocketPath %>',
+  cors: {
+    origin: '<%= corsOrigin %>',
+    credentials: <%= corsCredentials %>,
+  },
+})
+export class WebSocketBroadcastBackend
+  implements BroadcastBackend, OnGatewayConnection, OnGatewayDisconnect
+{
+  private readonly logger = new Logger(WebSocketBroadcastBackend.name)
+
+  @WebSocketServer()
+  private server!: Server
+
+  /** channel -> set of subscribed sockets */
+  private channelSubscribers = new Map<string, Set<Socket>>()
+
+  /** socket -> set of channels subscribed to */
+  private socketChannels = new Map<Socket, Set<string>>()
+
+  /** server-side handlers for channels */
+  private handlers = new Map<string, Set<BroadcastHandler>>()
+
+  private closed = false
+
+  readonly supportsPush = true
+
+  handleConnection(client: Socket): void {
+    this.logger.log(`Client connected: ${client.id}`)
+    this.socketChannels.set(client, new Set())
+  }
+
+  handleDisconnect(client: Socket): void {
+    this.logger.log(`Client disconnected: ${client.id}`)
+
+    // Remove client from all channel subscriptions
+    const channels = this.socketChannels.get(client)
+    if (channels) {
+      for (const channel of channels) {
+        const subscribers = this.channelSubscribers.get(channel)
+        if (subscribers) {
+          subscribers.delete(client)
+          if (subscribers.size === 0) {
+            this.channelSubscribers.delete(channel)
+          }
+        }
+      }
+    }
+    this.socketChannels.delete(client)
+  }
+
+  @SubscribeMessage('subscribe')
+  handleSubscribe(
+    @ConnectedSocket() client: Socket,
+    @MessageBody() data: SubscribePayload,
+  ): { subscribed: string[] } {
+    const channels = data?.channels ?? []
+    const subscribedChannels: string[] = []
+
+    for (const channel of channels) {
+      if (typeof channel !== 'string' || channel.length === 0) {
+        continue
+      }
+
+      // Add to channel subscribers
+      let subscribers = this.channelSubscribers.get(channel)
+      if (!subscribers) {
+        subscribers = new Set()
+        this.channelSubscribers.set(channel, subscribers)
+      }
+      subscribers.add(client)
+
+      // Track which channels this socket is subscribed to
+      const socketChans = this.socketChannels.get(client)
+      if (socketChans) {
+        socketChans.add(channel)
+      }
+
+      subscribedChannels.push(channel)
+      this.logger.debug(`Client ${client.id} subscribed to channel: ${channel}`)
+    }
+
+    return { subscribed: subscribedChannels }
+  }
+
+  @SubscribeMessage('unsubscribe')
+  handleUnsubscribe(
+    @ConnectedSocket() client: Socket,
+    @MessageBody() data: UnsubscribePayload,
+  ): { unsubscribed: string[] } {
+    const channels = data?.channels ?? []
+    const unsubscribedChannels: string[] = []
+
+    for (const channel of channels) {
+      if (typeof channel !== 'string' || channel.length === 0) {
+        continue
+      }
+
+      // Remove from channel subscribers
+      const subscribers = this.channelSubscribers.get(channel)
+      if (subscribers) {
+        subscribers.delete(client)
+        if (subscribers.size === 0) {
+          this.channelSubscribers.delete(channel)
+        }
+      }
+
+      // Remove from socket's channel list
+      const socketChans = this.socketChannels.get(client)
+      if (socketChans) {
+        socketChans.delete(channel)
+      }
+
+      unsubscribedChannels.push(channel)
+      this.logger.debug(
+        `Client ${client.id} unsubscribed from channel: ${channel}`,
+      )
+    }
+
+    return { unsubscribed: unsubscribedChannels }
+  }
+
+  async broadcast(
+    channel: string,
+    eventType: string,
+    payload: Record<string, unknown>,
+  ): Promise<void> {
+    if (this.closed) {
+      throw new Error('Broadcast backend is closed')
+    }
+
+    const message: BroadcastMessage = {
+      channel,
+      event: eventType,
+      payload,
+    }
+
+    // Send to WebSocket clients
+    const subscribers = this.channelSubscribers.get(channel)
+    if (subscribers && subscribers.size > 0) {
+      for (const socket of subscribers) {
+        socket.emit('broadcast', message)
+      }
+      this.logger.debug(
+        `Broadcast to ${subscribers.size} clients on channel "${channel}": ${eventType}`,
+      )
+    }
+
+    // Call server-side handlers
+    const channelHandlers = this.handlers.get(channel)
+    if (channelHandlers && channelHandlers.size > 0) {
+      const promises = Array.from(channelHandlers).map((handler) =>
+        handler(eventType, payload).catch((error) => {
+          this.logger.error(
+            `Handler error on channel "${channel}": ${error.message}`,
+          )
+        }),
+      )
+      await Promise.all(promises)
+    }
+  }
+
+  async subscribe(channel: string, handler: BroadcastHandler): Promise<void> {
+    if (this.closed) {
+      throw new Error('Broadcast backend is closed')
+    }
+
+    let channelHandlers = this.handlers.get(channel)
+    if (!channelHandlers) {
+      channelHandlers = new Set()
+      this.handlers.set(channel, channelHandlers)
+    }
+    channelHandlers.add(handler)
+  }
+
+  async unsubscribe(channel: string): Promise<void> {
+    this.handlers.delete(channel)
+  }
+
+  async healthCheck(): Promise<boolean> {
+    return !this.closed && this.server !== undefined
+  }
+
+  async close(): Promise<void> {
+    this.closed = true
+
+    // Disconnect all clients
+    for (const socket of this.socketChannels.keys()) {
+      socket.disconnect(true)
+    }
+
+    this.channelSubscribers.clear()
+    this.socketChannels.clear()
+    this.handlers.clear()
+  }
+
+  /**
+   * Get statistics about current connections (for monitoring)
+   */
+  getStats(): {
+    totalConnections: number
+    channelCounts: Record<string, number>
+  } {
+    const channelCounts: Record<string, number> = {}
+    for (const [channel, subscribers] of this.channelSubscribers) {
+      channelCounts[channel] = subscribers.size
+    }
+
+    return {
+      totalConnections: this.socketChannels.size,
+      channelCounts,
+    }
+  }
+}

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

@@ -0,0 +1,55 @@
+---
+to: "<%= generate.commands ? outputPaths.createCommand : '' %>"
+skip_if: <%= !isCleanArchitecture %>
+force: true
+---
+<% if (outputPaths.createCommand) { -%>
+/**
+ * Create <%= className %> Command
+ * Generated by entity codegen - do not edit directly
+ *
+ * EXTENSION POINTS (add business logic here):
+ * - Validation: Add domain validation rules before creating
+ * - Defaults: Compute default values not handled by DTO
+ * - Side effects: Emit events, send notifications, create related entities
+ * - Authorization: Check user permissions beyond route-level auth
+ * - Audit: Log creation for compliance/debugging
+ */
+
+import { Inject, Injectable } from '@nestjs/common';
+import { <%= repositoryToken %> } from '<%= imports.constants %>';
+import type { Create<%= className %>Input, I<%= className %>Repository } from '<%= imports.domain %>';
+import { <%= className %> } from '<%= imports.domain %>';
+import type { Create<%= className %>Dto } from '<%= imports.schemas %>';
+
+@Injectable()
+export class <%= createCommandClass %> {
+	constructor(
+		@Inject(<%= repositoryToken %>)
+		private readonly <%= camelName %>Repository: I<%= className %>Repository,
+	) {}
+
+	async execute(dto: Create<%= className %>Dto): Promise<<%= className %>> {
+		// TODO: Add pre-create validation and business rules here
+
+		// Map DTO to domain input
+		const input: Create<%= className %>Input = {
+<% fields.forEach((field) => { -%>
+<% if (field.required) { -%>
+			<%= field.camelName %>: dto.<%= field.camelName %>,
+<% } else if (field.nullable) { -%>
+			<%= field.camelName %>: dto.<%= field.camelName %> ?? null,
+<% } else { -%>
+			<%= field.camelName %>: dto.<%= field.camelName %>,
+<% } -%>
+<% }) -%>
+		};
+
+		const created = await this.<%= camelName %>Repository.create(input);
+
+		// TODO: Add post-create side effects here (events, notifications, etc.)
+
+		return created;
+	}
+}
+<% } -%>

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

@@ -0,0 +1,45 @@
+---
+to: "<%= generate.commands ? outputPaths.deleteCommand : '' %>"
+skip_if: <%= !isCleanArchitecture %>
+force: true
+---
+<% if (outputPaths.deleteCommand) { -%>
+/**
+ * Delete <%= className %> Command
+ * Generated by entity codegen - do not edit directly
+ *
+ * EXTENSION POINTS (add business logic here):
+ * - Authorization: Check if user can delete this specific record
+ * - Referential integrity: Check for dependent records, cascade or block
+ * - Soft delete: Mark as deleted instead of hard delete
+ * - Side effects: Emit events, clean up related data, notify subscribers
+ * - Audit: Log deletion for compliance/debugging
+ */
+
+import { Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { <%= repositoryToken %> } from '<%= imports.constants %>';
+import type { I<%= className %>Repository } from '<%= imports.domain %>';
+import { <%= className %> } from '<%= imports.domain %>';
+
+@Injectable()
+export class <%= deleteCommandClass %> {
+	constructor(
+		@Inject(<%= repositoryToken %>)
+		private readonly <%= camelName %>Repository: I<%= className %>Repository,
+	) {}
+
+	async execute(id: string): Promise<<%= className %>> {
+		// TODO: Add pre-delete validation here
+		// e.g., check for dependent records, verify user permissions
+
+		const deleted = await this.<%= camelName %>Repository.delete(id);
+		if (!deleted) {
+			throw new NotFoundException(`<%= className %> with id ${id} not found`);
+		}
+
+		// TODO: Add post-delete side effects here (events, cleanup, etc.)
+
+		return deleted;
+	}
+}
+<% } -%>

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

@@ -0,0 +1,149 @@
+---
+to: "<%= generate.commands ? outputPaths.commandsGroupedIndex : '' %>"
+skip_if: <%= !isCleanArchitecture %>
+force: true
+---
+<% if (outputPaths.commandsGroupedIndex) { -%>
+/**
+ * <%= className %> Commands Module
+ * Generated by entity codegen - do not edit directly
+ *
+ * This file contains all command classes for <%= className %>
+ * using grouped file layout (file_grouping: "grouped")
+ */
+
+import { Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { <%= repositoryToken %> } from '<%= imports.constants %>';
+import type { Create<%= className %>Input, I<%= className %>Repository, Update<%= className %>Input } from '<%= imports.domain %>';
+import { <%= className %> } from '<%= imports.domain %>';
+import type { Create<%= className %>Dto, Update<%= className %>Dto } from '<%= imports.schemas %>';
+
+// ============================================================================
+// Create Command
+// ============================================================================
+
+/**
+ * Create <%= className %> Command
+ *
+ * EXTENSION POINTS (add business logic here):
+ * - Validation: Add domain validation rules before creating
+ * - Defaults: Compute default values not handled by DTO
+ * - Side effects: Emit events, send notifications, create related entities
+ * - Authorization: Check user permissions beyond route-level auth
+ * - Audit: Log creation for compliance/debugging
+ */
+@Injectable()
+export class <%= createCommandClass %> {
+	constructor(
+		@Inject(<%= repositoryToken %>)
+		private readonly <%= camelName %>Repository: I<%= className %>Repository,
+	) {}
+
+	async execute(dto: Create<%= className %>Dto): Promise<<%= className %>> {
+		// TODO: Add pre-create validation and business rules here
+
+		// Map DTO to domain input
+		const input: Create<%= className %>Input = {
+<% fields.forEach((field) => { -%>
+<% if (field.required) { -%>
+			<%= field.camelName %>: dto.<%= field.camelName %>,
+<% } else if (field.nullable) { -%>
+			<%= field.camelName %>: dto.<%= field.camelName %> ?? null,
+<% } else { -%>
+			<%= field.camelName %>: dto.<%= field.camelName %>,
+<% } -%>
+<% }) -%>
+		};
+
+		const created = await this.<%= camelName %>Repository.create(input);
+
+		// TODO: Add post-create side effects here (events, notifications, etc.)
+
+		return created;
+	}
+}
+
+// ============================================================================
+// Update Command
+// ============================================================================
+
+/**
+ * Update <%= className %> Command
+ *
+ * EXTENSION POINTS (add business logic here):
+ * - Validation: Add domain validation rules (e.g., state transitions)
+ * - Authorization: Check if user can modify this specific record
+ * - Conflict detection: Optimistic locking, version checks
+ * - Side effects: Emit events, invalidate caches, notify subscribers
+ * - Audit: Log changes for compliance/debugging
+ */
+@Injectable()
+export class <%= updateCommandClass %> {
+	constructor(
+		@Inject(<%= repositoryToken %>)
+		private readonly <%= camelName %>Repository: I<%= className %>Repository,
+	) {}
+
+	async execute(id: string, dto: Update<%= className %>Dto): Promise<<%= className %>> {
+		const existing = await this.<%= camelName %>Repository.findById(id);
+		if (!existing) {
+			throw new NotFoundException(`<%= className %> with id ${id} not found`);
+		}
+
+		// TODO: Add pre-update validation and business rules here
+		// e.g., check state transitions, verify user permissions on this record
+
+		// Map DTO to domain input (only include defined fields)
+		const input: Update<%= className %>Input = {
+<% fields.forEach((field) => { -%>
+			...(dto.<%= field.camelName %> !== undefined && { <%= field.camelName %>: dto.<%= field.camelName %> }),
+<% }) -%>
+		};
+
+		const updated = await this.<%= camelName %>Repository.update(id, input);
+		if (!updated) {
+			throw new NotFoundException(`<%= className %> with id ${id} not found`);
+		}
+
+		// TODO: Add post-update side effects here (events, cache invalidation, etc.)
+
+		return updated;
+	}
+}
+
+// ============================================================================
+// Delete Command
+// ============================================================================
+
+/**
+ * Delete <%= className %> Command
+ *
+ * EXTENSION POINTS (add business logic here):
+ * - Authorization: Check if user can delete this specific record
+ * - Referential integrity: Check for dependent records, cascade or block
+ * - Soft delete: Mark as deleted instead of hard delete
+ * - Side effects: Emit events, clean up related data, notify subscribers
+ * - Audit: Log deletion for compliance/debugging
+ */
+@Injectable()
+export class <%= deleteCommandClass %> {
+	constructor(
+		@Inject(<%= repositoryToken %>)
+		private readonly <%= camelName %>Repository: I<%= className %>Repository,
+	) {}
+
+	async execute(id: string): Promise<<%= className %>> {
+		// TODO: Add pre-delete validation here
+		// e.g., check for dependent records, verify user permissions
+
+		const deleted = await this.<%= camelName %>Repository.delete(id);
+		if (!deleted) {
+			throw new NotFoundException(`<%= className %> with id ${id} not found`);
+		}
+
+		// TODO: Add post-delete side effects here (events, cleanup, etc.)
+
+		return deleted;
+	}
+}
+<% } -%>

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

@@ -0,0 +1,15 @@
+---
+to: "<%= generate.commands ? outputPaths.commandsIndex : '' %>"
+skip_if: <%= !isCleanArchitecture %>
+force: true
+---
+<% if (outputPaths.commandsIndex) { -%>
+/**
+ * <%= className %> Commands Barrel Export
+ * Generated by entity codegen - do not edit directly
+ */
+
+export * from './<%= fileNames.createCommand.replace('.ts', '') %>';
+export * from './<%= fileNames.updateCommand.replace('.ts', '') %>';
+export * from './<%= fileNames.deleteCommand.replace('.ts', '') %>';
+<% } -%>

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

@@ -0,0 +1,58 @@
+---
+to: "<%= generate.commands ? outputPaths.updateCommand : '' %>"
+skip_if: <%= !isCleanArchitecture %>
+force: true
+---
+<% if (outputPaths.updateCommand) { -%>
+/**
+ * Update <%= className %> Command
+ * Generated by entity codegen - do not edit directly
+ *
+ * EXTENSION POINTS (add business logic here):
+ * - Validation: Add domain validation rules (e.g., state transitions)
+ * - Authorization: Check if user can modify this specific record
+ * - Conflict detection: Optimistic locking, version checks
+ * - Side effects: Emit events, invalidate caches, notify subscribers
+ * - Audit: Log changes for compliance/debugging
+ */
+
+import { Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { <%= repositoryToken %> } from '<%= imports.constants %>';
+import type { I<%= className %>Repository, Update<%= className %>Input } from '<%= imports.domain %>';
+import { <%= className %> } from '<%= imports.domain %>';
+import type { Update<%= className %>Dto } from '<%= imports.schemas %>';
+
+@Injectable()
+export class <%= updateCommandClass %> {
+	constructor(
+		@Inject(<%= repositoryToken %>)
+		private readonly <%= camelName %>Repository: I<%= className %>Repository,
+	) {}
+
+	async execute(id: string, dto: Update<%= className %>Dto): Promise<<%= className %>> {
+		const existing = await this.<%= camelName %>Repository.findById(id);
+		if (!existing) {
+			throw new NotFoundException(`<%= className %> with id ${id} not found`);
+		}
+
+		// TODO: Add pre-update validation and business rules here
+		// e.g., check state transitions, verify user permissions on this record
+
+		// Map DTO to domain input (only include defined fields)
+		const input: Update<%= className %>Input = {
+<% fields.forEach((field) => { -%>
+			...(dto.<%= field.camelName %> !== undefined && { <%= field.camelName %>: dto.<%= field.camelName %> }),
+<% }) -%>
+		};
+
+		const updated = await this.<%= camelName %>Repository.update(id, input);
+		if (!updated) {
+			throw new NotFoundException(`<%= className %> with id ${id} not found`);
+		}
+
+		// TODO: Add post-update side effects here (events, cache invalidation, etc.)
+
+		return updated;
+	}
+}
+<% } -%>

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

@@ -0,0 +1,36 @@
+---
+to: "<%= hasDeclarativeQueries ? `${basePaths.backendSrc}/${paths.queries}/declarative-queries.ts` : '' %>"
+skip_if: <%= !isCleanArchitecture %>
+force: true
+---
+<% if (hasDeclarativeQueries) { -%>
+/**
+ * Declarative Query Classes for <%= className %>
+ * Generated from queries: block in entity YAML - do not edit directly
+ */
+
+import { Inject, Injectable } from '@nestjs/common';
+import { <%= repositoryToken %> } from '<%= imports.constants %>';
+import type { I<%= className %>Repository } from '<%= imports.domain %>';
+import type { <%= className %> } from '<%= imports.domain %>';
+
+<% processedQueries.forEach((q) => { -%>
+@Injectable()
+export class <%= q.useCaseClassName %> {
+	constructor(
+		@Inject(<%= repositoryToken %>)
+		private readonly repository: I<%= className %>Repository,
+	) {}
+
+	async execute(<%- q.params.map(p => `${p.camelName}: ${p.tsType}`).join(', ') %>): Promise<<%- q.returnType %>> {
+		return this.repository.<%= q.methodName %>(<%= q.params.map(p => p.camelName).join(', ') %>);
+	}
+}
+
+<% }) -%>
+export const declarativeQueryClasses = [
+<% processedQueries.forEach((q) => { -%>
+	<%= q.useCaseClassName %>,
+<% }) -%>
+];
+<% } -%>

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

@@ -0,0 +1,42 @@
+---
+to: "<%= generate.queries ? outputPaths.getByIdQuery : '' %>"
+skip_if: <%= !isCleanArchitecture %>
+force: true
+---
+<% if (outputPaths.getByIdQuery) { -%>
+/**
+ * Get <%= className %> By ID Query
+ * Generated by entity codegen - do not edit directly
+ *
+ * EXTENSION POINTS (add query logic here):
+ * - Authorization: Check if user can access this specific record
+ * - Enrichment: Add computed fields or related data
+ * - Caching: Add cache layer for frequently accessed records
+ */
+
+import { Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { <%= repositoryToken %> } from '<%= imports.constants %>';
+import type { I<%= className %>Repository<%= hasRelationships ? `, ${className}With` : '' %> } from '<%= imports.domain %>';
+import { <%= className %> } from '<%= imports.domain %>';
+
+@Injectable()
+export class <%= getByIdQueryClass %> {
+	constructor(
+		@Inject(<%= repositoryToken %>)
+		private readonly <%= camelName %>Repository: I<%= className %>Repository,
+	) {}
+
+	async execute(id: string<%= hasRelationships ? `, include?: ${className}With` : '' %>): Promise<<%= className %>> {
+		// TODO: Add authorization check if needed (row-level security)
+
+		const entity = await this.<%= camelName %>Repository.findById(id<%= hasRelationships ? ', include' : '' %>);
+		if (!entity) {
+			throw new NotFoundException(`<%= className %> with id ${id} not found`);
+		}
+
+		// TODO: Add enrichment or computed fields if needed
+
+		return entity;
+	}
+}
+<% } -%>