@pattern-stack/codegen 0.2.0

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

@@ -0,0 +1,67 @@
+---
+to: src/infrastructure/broadcast/broadcast-bridge.listener.ts
+force: true
+---
+import { Injectable, Logger } from '@nestjs/common'
+import { OnEvent } from '@nestjs/event-emitter'
+import { WebSocketBroadcastBackend } from './websocket-broadcast.backend'
+import { Channels } from './channel'
+<% eventImports.forEach((imp) => { -%>
+
+// <%= imp.file.charAt(0).toUpperCase() + imp.file.slice(1).replace('.events', '') %> Events
+import {
+<% imp.events.forEach((event, idx) => { -%>
+  <%= event %>,
+<% }); -%>
+} from '../../domain/events/<%= imp.file %>'
+<% }); -%>
+
+/**
+ * Bridge between domain events (via EventEmitter2) and WebSocket broadcast.
+ * Listens to domain events and broadcasts them to subscribed WebSocket clients.
+ */
+@Injectable()
+export class BroadcastBridgeListener {
+  private readonly logger = new Logger(BroadcastBridgeListener.name)
+
+  constructor(private readonly broadcast: WebSocketBroadcastBackend) {}
+<% Object.entries(bridgeEventsByChannel).forEach(([channel, events]) => { -%>
+
+  // ============================================================
+  // <%= channel.charAt(0).toUpperCase() + channel.slice(1) %> Events
+  // ============================================================
+<% events.forEach((event) => { -%>
+
+  @OnEvent(<%= event.className %>.eventName)
+  async handle<%= event.className %>(event: <%= event.className %>): Promise<void> {
+    await this.broadcastSafe(Channels.<%= channel.toUpperCase() %>, <%= event.className %>.eventName, {
+<% event.fields.forEach((field) => { -%>
+<% if (event.transforms[field]) { -%>
+      <%= field %>: <%= event.transforms[field] %>,
+<% } else { -%>
+      <%= field %>: event.<%= field %>,
+<% } -%>
+<% }); -%>
+    })
+  }
+<% }); -%>
+<% }); -%>
+
+  // ============================================================
+  // Helper
+  // ============================================================
+
+  private async broadcastSafe(
+    channel: string,
+    eventType: string,
+    payload: Record<string, unknown>,
+  ): Promise<void> {
+    try {
+      await this.broadcast.broadcast(channel, eventType, payload)
+    } catch (error) {
+      this.logger.error(
+        `Failed to broadcast ${eventType} on channel ${channel}: ${error}`,
+      )
+    }
+  }
+}

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

@@ -0,0 +1,77 @@
+---
+to: src/infrastructure/broadcast/channel.ts
+force: true
+---
+import type { BroadcastBackend, BroadcastHandler } from './broadcast-backend.interface'
+
+/**
+ * Channel wrapper providing a scoped API for broadcasting and subscribing
+ * to events on a specific channel.
+ *
+ * @example
+ * ```typescript
+ * const sessionChannel = new Channel(backend, 'session')
+ * await sessionChannel.emit('session.running', { sessionId: '123', appUrl: 'http://...' })
+ * ```
+ */
+export class Channel {
+  constructor(
+    private readonly backend: BroadcastBackend,
+    public readonly name: string,
+  ) {}
+
+  /**
+   * Emit an event to all subscribers of this channel
+   */
+  async emit(eventType: string, payload: Record<string, unknown>): Promise<void> {
+    await this.backend.broadcast(this.name, eventType, payload)
+  }
+
+  /**
+   * Subscribe to events on this channel (server-side)
+   */
+  async subscribe(handler: BroadcastHandler): Promise<void> {
+    await this.backend.subscribe(this.name, handler)
+  }
+
+  /**
+   * Unsubscribe all handlers from this channel (server-side)
+   */
+  async unsubscribe(): Promise<void> {
+    await this.backend.unsubscribe(this.name)
+  }
+}
+
+/**
+ * Predefined channel names for domain events
+ */
+export const Channels = {
+<% channels.forEach((ch) => { -%>
+  <%= ch.constName %>: '<%= ch.name %>',
+<% }); -%>
+} as const
+
+export type ChannelName = (typeof Channels)[keyof typeof Channels]
+
+/**
+ * Factory for creating channel instances
+ */
+export class ChannelFactory {
+  constructor(private readonly backend: BroadcastBackend) {}
+
+  /**
+   * Create a channel instance for the given name
+   */
+  channel(name: string): Channel {
+    return new Channel(this.backend, name)
+  }
+<% channels.forEach((ch) => { -%>
+
+  /**
+   * Get the <%= ch.name %> events channel
+   */
+  <%= ch.name %>(): Channel {
+    return this.channel(Channels.<%= ch.constName %>)
+  }
+<% }); -%>
+}

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

@@ -0,0 +1,21 @@
+---
+to: src/infrastructure/broadcast/index.ts
+force: true
+---
+// Interfaces
+export type { BroadcastBackend, BroadcastHandler } from './broadcast-backend.interface'
+export { BROADCAST_BACKEND } from './broadcast-backend.interface'
+
+// Backends
+export { MemoryBroadcastBackend } from './memory-broadcast.backend'
+export { WebSocketBroadcastBackend } from './websocket-broadcast.backend'
+
+// Channel API
+export { Channel, ChannelFactory, Channels } from './channel'
+export type { ChannelName } from './channel'
+
+// Bridge
+export { BroadcastBridgeListener } from './broadcast-bridge.listener'
+
+// Module
+export { BroadcastModule } from './broadcast.module'

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

@@ -0,0 +1,87 @@
+---
+to: src/infrastructure/broadcast/memory-broadcast.backend.ts
+force: true
+---
+import { Injectable } from '@nestjs/common'
+import type {
+  BroadcastBackend,
+  BroadcastHandler,
+} from './broadcast-backend.interface'
+
+/**
+ * In-memory broadcast backend for testing and single-process scenarios.
+ * Events are delivered synchronously to registered handlers.
+ */
+@Injectable()
+export class MemoryBroadcastBackend implements BroadcastBackend {
+  private handlers = new Map<string, Set<BroadcastHandler>>()
+  private closed = false
+
+  readonly supportsPush = false
+
+  async broadcast(
+    channel: string,
+    eventType: string,
+    payload: Record<string, unknown>,
+  ): Promise<void> {
+    if (this.closed) {
+      throw new Error('Broadcast backend is closed')
+    }
+
+    const channelHandlers = this.handlers.get(channel)
+    if (!channelHandlers || channelHandlers.size === 0) {
+      return
+    }
+
+    const promises = Array.from(channelHandlers).map((handler) =>
+      handler(eventType, payload).catch((error) => {
+        console.error(
+          `[MemoryBroadcast] Handler error on channel "${channel}":`,
+          error,
+        )
+      }),
+    )
+
+    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
+  }
+
+  async close(): Promise<void> {
+    this.closed = true
+    this.handlers.clear()
+  }
+
+  /**
+   * Get the number of handlers for a channel (for testing)
+   */
+  getHandlerCount(channel: string): number {
+    return this.handlers.get(channel)?.size ?? 0
+  }
+
+  /**
+   * Get all subscribed channels (for testing)
+   */
+  getChannels(): string[] {
+    return Array.from(this.handlers.keys())
+  }
+}

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

@@ -0,0 +1,57 @@
+---
+to: src/infrastructure/broadcast/broadcast.module.ts
+force: true
+---
+import { Module } from '@nestjs/common'
+import { WebSocketBroadcastBackend } from './websocket-broadcast.backend'
+import { MemoryBroadcastBackend } from './memory-broadcast.backend'
+import { BroadcastBridgeListener } from './broadcast-bridge.listener'
+import { BROADCAST_BACKEND } from './broadcast-backend.interface'
+
+/**
+ * Broadcast module providing WebSocket-based real-time event broadcasting.
+ *
+ * This module:
+ * - Exposes a WebSocket gateway at <%= websocketPath %> for client connections
+ * - Bridges domain events (from EventEmitter2) to WebSocket clients
+ * - Supports channels: <%= channelNames.join(', ') %>
+ *
+ * Usage:
+ * ```typescript
+ * @Module({
+ *   imports: [BroadcastModule],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * Client protocol:
+ * ```
+ * // Subscribe to channels
+ * socket.emit('subscribe', { channels: ['session', 'agent'] })
+ *
+ * // Receive broadcasts
+ * socket.on('broadcast', (msg) => {
+ *   console.log(msg.channel, msg.event, msg.payload)
+ * })
+ *
+ * // Unsubscribe
+ * socket.emit('unsubscribe', { channels: ['session'] })
+ * ```
+ */
+@Module({
+  providers: [
+    WebSocketBroadcastBackend,
+    MemoryBroadcastBackend,
+    BroadcastBridgeListener,
+    {
+      provide: BROADCAST_BACKEND,
+      useExisting: WebSocketBroadcastBackend,
+    },
+  ],
+  exports: [
+    WebSocketBroadcastBackend,
+    MemoryBroadcastBackend,
+    BROADCAST_BACKEND,
+  ],
+})
+export class BroadcastModule {}

package/templates/broadcast/new/prompt.js

@@ -0,0 +1,268 @@
+/**
+ * Hygen prompt.js - Loads broadcast config and prepares template locals
+ *
+ * Usage: bunx hygen broadcast new [--yaml broadcast.yaml]
+ *
+ * If no YAML is provided, generates with sensible defaults.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import yaml from 'yaml'
+
+// ============================================================================
+// Default Configuration
+// ============================================================================
+
+const defaultConfig = {
+  broadcast: {
+    name: 'default',
+    channels: ['session', 'agent', 'git'],
+    websocket: {
+      path: '/ws/broadcast',
+      cors: {
+        origin: '*',
+        credentials: true,
+      },
+    },
+    bridge_events: {
+      session: [
+        'SessionProvisioning',
+        'SessionRunning',
+        'SessionPaused',
+        'SessionTerminating',
+        'SessionTerminated',
+        'SessionProvisionFailed',
+      ],
+      agent: [
+        'AgentSpawned',
+        'AgentStatusChanged',
+        'AgentCompleted',
+        'AgentFailed',
+        'AgentRunStarted',
+        'AgentRunCompleted',
+        'AgentRunFailed',
+      ],
+      git: [
+        'GitOperationStarted',
+        'GitOperationCompleted',
+        'GitOperationFailed',
+        'GitCommitCreated',
+        'GitPushCompleted',
+      ],
+    },
+  },
+}
+
+// ============================================================================
+// Event Metadata (field mappings for each domain event)
+// ============================================================================
+
+const eventMetadata = {
+  // Session Events
+  SessionProvisioning: {
+    eventName: 'session.provisioning',
+    channel: 'session',
+    file: 'session.events',
+    fields: ['sessionId', 'projectId', 'worktreeRef'],
+  },
+  SessionRunning: {
+    eventName: 'session.running',
+    channel: 'session',
+    file: 'session.events',
+    fields: ['sessionId', 'appUrl', 'vncUrl'],
+  },
+  SessionPaused: {
+    eventName: 'session.paused',
+    channel: 'session',
+    file: 'session.events',
+    fields: ['sessionId'],
+  },
+  SessionTerminating: {
+    eventName: 'session.terminating',
+    channel: 'session',
+    file: 'session.events',
+    fields: ['sessionId', 'reason'],
+  },
+  SessionTerminated: {
+    eventName: 'session.terminated',
+    channel: 'session',
+    file: 'session.events',
+    fields: ['sessionId', 'reason'],
+  },
+  SessionProvisionFailed: {
+    eventName: 'session.provision_failed',
+    channel: 'session',
+    file: 'session.events',
+    fields: ['sessionId', 'error', 'step'],
+  },
+
+  // Agent Events
+  AgentSpawned: {
+    eventName: 'agent.spawned',
+    channel: 'agent',
+    file: 'agent.events',
+    fields: ['agentId', 'sessionId', 'name', 'parentAgentId'],
+  },
+  AgentStatusChanged: {
+    eventName: 'agent.status_changed',
+    channel: 'agent',
+    file: 'agent.events',
+    fields: ['agentId', 'previousStatus', 'newStatus'],
+  },
+  AgentCompleted: {
+    eventName: 'agent.completed',
+    channel: 'agent',
+    file: 'agent.events',
+    fields: ['agentId', 'sessionId'],
+  },
+  AgentFailed: {
+    eventName: 'agent.failed',
+    channel: 'agent',
+    file: 'agent.events',
+    fields: ['agentId', 'sessionId', 'error'],
+    transforms: { error: 'String(event.error)' },
+  },
+  AgentRunStarted: {
+    eventName: 'agent.run.started',
+    channel: 'agent',
+    file: 'agent.events',
+    fields: ['agentRunId', 'agentId', 'sessionId', 'trigger', 'workingRef'],
+  },
+  AgentRunCompleted: {
+    eventName: 'agent.run.completed',
+    channel: 'agent',
+    file: 'agent.events',
+    fields: ['agentRunId', 'agentId', 'sessionId', 'tokenUsage'],
+  },
+  AgentRunFailed: {
+    eventName: 'agent.run.failed',
+    channel: 'agent',
+    file: 'agent.events',
+    fields: ['agentRunId', 'agentId', 'error'],
+    transforms: { error: 'String(event.error)' },
+  },
+
+  // Git Events
+  GitOperationStarted: {
+    eventName: 'git.operation.started',
+    channel: 'git',
+    file: 'git.events',
+    fields: ['operationId', 'sessionId', 'operationType', 'repositoryId'],
+  },
+  GitOperationCompleted: {
+    eventName: 'git.operation.completed',
+    channel: 'git',
+    file: 'git.events',
+    fields: ['operationId', 'sessionId', 'operationType', 'commitSha'],
+  },
+  GitOperationFailed: {
+    eventName: 'git.operation.failed',
+    channel: 'git',
+    file: 'git.events',
+    fields: ['operationId', 'sessionId', 'operationType', 'error'],
+  },
+  GitCommitCreated: {
+    eventName: 'git.commit.created',
+    channel: 'git',
+    file: 'git.events',
+    fields: ['operationId', 'sessionId', 'agentRunId', 'commitSha', 'message', 'filesChanged'],
+  },
+  GitPushCompleted: {
+    eventName: 'git.push.completed',
+    channel: 'git',
+    file: 'git.events',
+    fields: ['operationId', 'sessionId', 'ref', 'remote'],
+  },
+}
+
+// ============================================================================
+// Prompt Export
+// ============================================================================
+
+export default {
+  prompt: async ({ args }) => {
+    let config = defaultConfig
+
+    // Load custom config if provided
+    if (args.yaml) {
+      const fullPath = path.resolve(process.cwd(), args.yaml)
+      if (!fs.existsSync(fullPath)) {
+        throw new Error(`Config file not found: ${fullPath}`)
+      }
+      const content = fs.readFileSync(fullPath, 'utf-8')
+      const parsed = yaml.parse(content)
+      config = { broadcast: { ...defaultConfig.broadcast, ...parsed.broadcast } }
+    }
+
+    const broadcast = config.broadcast
+
+    // Process channels
+    const channels = broadcast.channels.map((ch) => ({
+      name: ch,
+      constName: ch.toUpperCase(),
+    }))
+
+    // Process bridge events - group by channel and enrich with metadata
+    const bridgeEventsByChannel = {}
+    const allBridgeEvents = []
+    const eventImportsByFile = {}
+
+    for (const [channel, events] of Object.entries(broadcast.bridge_events)) {
+      bridgeEventsByChannel[channel] = []
+
+      for (const eventName of events) {
+        const meta = eventMetadata[eventName]
+        if (!meta) {
+          console.warn(`Warning: Unknown event ${eventName}, skipping`)
+          continue
+        }
+
+        const eventInfo = {
+          className: eventName,
+          eventName: meta.eventName,
+          channel: meta.channel,
+          fields: meta.fields,
+          transforms: meta.transforms || {},
+        }
+
+        bridgeEventsByChannel[channel].push(eventInfo)
+        allBridgeEvents.push(eventInfo)
+
+        // Track imports by file
+        if (!eventImportsByFile[meta.file]) {
+          eventImportsByFile[meta.file] = []
+        }
+        eventImportsByFile[meta.file].push(eventName)
+      }
+    }
+
+    // Convert import map to array for template
+    const eventImports = Object.entries(eventImportsByFile).map(([file, events]) => ({
+      file,
+      events: events.sort(),
+    }))
+
+    return {
+      // Basic config
+      name: broadcast.name,
+      websocketPath: broadcast.websocket?.path ?? '/ws/broadcast',
+      corsOrigin: broadcast.websocket?.cors?.origin ?? '*',
+      corsCredentials: broadcast.websocket?.cors?.credentials ?? true,
+
+      // Channels
+      channels,
+      channelNames: broadcast.channels,
+
+      // Bridge events
+      bridgeEventsByChannel,
+      allBridgeEvents,
+      eventImports,
+
+      // Convenience flags
+      hasSessionEvents: !!bridgeEventsByChannel.session?.length,
+      hasAgentEvents: !!bridgeEventsByChannel.agent?.length,
+      hasGitEvents: !!bridgeEventsByChannel.git?.length,
+    }
+  },
+}