@specverse/engines 4.1.0

package/libs/instance-factories/communication/README.md

@@ -0,0 +1,47 @@
+# Communication Factory
+
+Event-driven messaging infrastructure with publisher/subscriber generation.
+
+## Definitions
+
+| File | Description |
+|------|-------------|
+| `event-emitter.yaml` | In-memory event bus using EventEmitter3 (development/testing) |
+| `rabbitmq-events.yaml` | RabbitMQ AMQP bus for production pub/sub messaging |
+
+## Generated Output
+
+### EventEmitter (`eventemitter/`)
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `bus-generator` | `src/events/eventBus.ts` | Singleton event bus with typed event names |
+| `publisher-generator` | `src/events/publishers/{event}Publisher.ts` | Per-event publisher (one per spec event) |
+| `subscriber-generator` | `src/events/subscribers/{event}Subscriber.ts` | Per-event subscriber with handler logic |
+
+### RabbitMQ (`rabbitmq/` — defined, templates pending)
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `publisher-generator` | `src/events/publishers/{event}Publisher.ts` | AMQP publisher with confirms |
+| `subscriber-generator` | `src/events/subscribers/{event}Subscriber.ts` | AMQP consumer with ack/nack |
+| `connection-generator` | `src/events/connection.ts` | RabbitMQ connection management |
+
+## Technology
+
+- **EventEmitter**: eventemitter3 ^5.0.0 (zero-dependency, in-process)
+- **RabbitMQ**: amqplib ^0.10.3 (topic exchange, durable queues, prefetch)
+
+## Capabilities
+
+| Provides | Requires |
+|----------|----------|
+| `messaging.pubsub` | (none) |
+| `messaging.events` | |
+| `messaging.inmemory` (EventEmitter) | |
+| `messaging.queue` (RabbitMQ) | |
+
+## Configuration
+
+EventEmitter: `maxListeners: 100`, `captureRejections: true`
+RabbitMQ: topic exchange, durable queues, prefetch 10, persistent messages, confirm-select

package/libs/instance-factories/communication/event-emitter.yaml

@@ -0,0 +1,56 @@
+name: EventEmitter
+version: "1.0.0"
+category: communication
+description: "In-memory event bus using Node.js EventEmitter for development and testing"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [events, in-memory, pubsub, eventemitter, development]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "messaging.pubsub"
+    - "messaging.events"
+    - "messaging.inmemory"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "eventemitter3"
+  version: "^5.0.0"
+
+dependencies:
+  runtime:
+    - name: "eventemitter3"
+      version: "^5.0.0"
+
+  dev:
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  bus:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/eventemitter/bus-generator.ts"
+    outputPattern: "src/events/eventBus.ts"
+
+  publisher:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/eventemitter/publisher-generator.ts"
+    outputPattern: "src/events/publishers/{event}Publisher.ts"
+
+  subscriber:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/eventemitter/subscriber-generator.ts"
+    outputPattern: "src/events/subscribers/{event}Subscriber.ts"
+
+configuration:
+  maxListeners: 100
+  captureRejections: true
+  errorHandling: "log"

package/libs/instance-factories/communication/rabbitmq-events.yaml

@@ -0,0 +1,87 @@
+name: RabbitMQEvents
+version: "1.0.0"
+category: communication
+description: "RabbitMQ event bus for pub/sub messaging and event-driven architecture"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [rabbitmq, events, messaging, pubsub, amqp]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "messaging.pubsub"
+    - "messaging.events"
+    - "messaging.queue"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "amqplib"
+  version: "^0.10.3"
+
+dependencies:
+  runtime:
+    - name: "amqplib"
+      version: "^0.10.3"
+    - name: "uuid"
+      version: "^9.0.0"
+
+  dev:
+    - name: "@types/amqplib"
+      version: "^0.10.4"
+    - name: "@types/uuid"
+      version: "^9.0.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  publisher:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/rabbitmq/publisher-generator.ts"
+    outputPattern: "src/events/publishers/{event}Publisher.ts"
+
+  subscriber:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/rabbitmq/subscriber-generator.ts"
+    outputPattern: "src/events/subscribers/{event}Subscriber.ts"
+
+  connection:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/rabbitmq/connection-generator.ts"
+    outputPattern: "src/events/connection.ts"
+
+configuration:
+  connection:
+    protocol: "amqp"
+    hostname: "localhost"
+    port: 5672
+    username: "guest"
+    password: "guest"
+    vhost: "/"
+    heartbeat: 60
+
+  exchange:
+    type: "topic"
+    durable: true
+    autoDelete: false
+
+  queue:
+    durable: true
+    exclusive: false
+    autoDelete: false
+
+  publishing:
+    persistent: true
+    mandatory: true
+    confirmSelect: true
+
+  consuming:
+    prefetch: 10
+    noAck: false
+    exclusive: false

package/libs/instance-factories/communication/templates/eventemitter/bus-generator.ts

@@ -0,0 +1,93 @@
+/**
+ * EventEmitter Bus Generator
+ *
+ * Generates in-memory event bus using EventEmitter3
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+/**
+ * Generate EventEmitter bus singleton
+ */
+export default function generateEventBus(context: TemplateContext): string {
+  const { spec } = context;
+
+  const events = spec.events ? Object.keys(spec.events) : [];
+
+  return `/**
+ * Event Bus
+ * In-memory event bus using EventEmitter3
+ * Generated from SpecVerse specification
+ */
+
+import EventEmitter from 'eventemitter3';
+
+// Event type definitions
+${events.map(event => `export type ${event}Payload = any; // TODO: Define payload type`).join('\n')}
+
+// Event names enum
+export enum EventName {
+${events.map(event => `  ${event} = '${event}',`).join('\n')}
+}
+
+/**
+ * Event Bus Singleton
+ */
+class EventBus extends EventEmitter {
+  private static instance: EventBus;
+
+  private constructor() {
+    super();
+    this.setMaxListeners(100); // Configure max listeners
+  }
+
+  /**
+   * Get singleton instance
+   */
+  public static getInstance(): EventBus {
+    if (!EventBus.instance) {
+      EventBus.instance = new EventBus();
+    }
+    return EventBus.instance;
+  }
+
+  /**
+   * Publish an event
+   */
+  public publish<T = any>(event: EventName | string, payload: T): void {
+    console.log(\`[EventBus] Publishing event: \${event}\`, payload);
+    this.emit(event, payload);
+  }
+
+  /**
+   * Subscribe to an event
+   */
+  public subscribe<T = any>(
+    event: EventName | string,
+    handler: (payload: T) => void | Promise<void>
+  ): () => void {
+    console.log(\`[EventBus] Subscribing to event: \${event}\`);
+    this.on(event, handler);
+
+    // Return unsubscribe function
+    return () => {
+      this.off(event, handler);
+    };
+  }
+
+  /**
+   * Subscribe to an event (one-time)
+   */
+  public subscribeOnce<T = any>(
+    event: EventName | string,
+    handler: (payload: T) => void | Promise<void>
+  ): void {
+    this.once(event, handler);
+  }
+}
+
+// Export singleton instance
+export const eventBus = EventBus.getInstance();
+export default eventBus;
+`;
+}

package/libs/instance-factories/communication/templates/eventemitter/publisher-generator.ts

@@ -0,0 +1,117 @@
+/**
+ * EventEmitter Publisher Generator
+ *
+ * Generates event publishers for EventEmitter
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+/**
+ * Generate event publisher
+ */
+export default function generateEventPublisher(context: TemplateContext): string {
+  const { event, spec } = context;
+
+  if (!event) {
+    throw new Error('Event is required in template context');
+  }
+
+  const eventName = event.name;
+  const publisherName = `${eventName}Publisher`;
+
+  return `/**
+ * ${publisherName}
+ * Publisher for ${eventName} events
+ * ${event.description || ''}
+ */
+
+import { eventBus, EventName } from '../eventBus.js';
+
+export interface ${eventName}Payload {
+${generatePayloadInterface(event)}
+}
+
+/**
+ * ${publisherName} class
+ */
+export class ${publisherName} {
+  /**
+   * Publish ${eventName} event
+   */
+  public async publish(payload: ${eventName}Payload): Promise<void> {
+    try {
+      // Validate payload
+      this.validate(payload);
+
+      // Add timestamp if not present
+      const enrichedPayload = {
+        ...payload,
+        timestamp: payload.timestamp || new Date().toISOString(),
+      };
+
+      // Publish event
+      eventBus.publish(EventName.${eventName}, enrichedPayload);
+
+      console.log(\`[${publisherName}] Published event\`, enrichedPayload);
+    } catch (error) {
+      console.error(\`[${publisherName}] Failed to publish event\`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Validate event payload
+   */
+  private validate(payload: ${eventName}Payload): void {
+    // TODO: Add validation logic
+${generateValidation(event)}
+  }
+}
+
+// Export singleton instance
+export const ${eventName.toLowerCase()}Publisher = new ${publisherName}();
+export default ${eventName.toLowerCase()}Publisher;
+`;
+}
+
+/**
+ * Generate payload interface from event attributes
+ */
+function generatePayloadInterface(event: any): string {
+  const attributes = event.attributes || {};
+  const fields: string[] = [];
+
+  for (const [name, config] of Object.entries(attributes)) {
+    const attr: any = config;
+    const type = attr.type || 'String';
+    let tsType = 'string';
+
+    // Map SpecVerse types to TypeScript types
+    if (type === 'Integer' || type === 'Number') tsType = 'number';
+    if (type === 'Boolean') tsType = 'boolean';
+    if (type === 'DateTime') tsType = 'string'; // ISO string
+    if (type === 'UUID') tsType = 'string';
+
+    const optional = attr.required ? '' : '?';
+    fields.push(`  ${name}${optional}: ${tsType};`);
+  }
+
+  return fields.join('\n') || '  // No attributes defined';
+}
+
+/**
+ * Generate validation logic
+ */
+function generateValidation(event: any): string {
+  const attributes = event.attributes || {};
+  const validations: string[] = [];
+
+  for (const [name, config] of Object.entries(attributes)) {
+    const attr: any = config;
+    if (attr.required) {
+      validations.push(`    if (!payload.${name}) throw new Error('${name} is required');`);
+    }
+  }
+
+  return validations.join('\n') || '    // No validation rules';
+}

package/libs/instance-factories/communication/templates/eventemitter/subscriber-generator.ts

@@ -0,0 +1,101 @@
+/**
+ * EventEmitter Subscriber Generator
+ *
+ * Generates event subscribers for EventEmitter
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+/**
+ * Generate event subscriber
+ */
+export default function generateEventSubscriber(context: TemplateContext): string {
+  const { event, service, spec } = context;
+
+  if (!event) {
+    throw new Error('Event is required in template context');
+  }
+
+  const eventName = event.name;
+  const subscriberName = `${eventName}Subscriber`;
+
+  return `/**
+ * ${subscriberName}
+ * Subscriber for ${eventName} events
+ * ${event.description || ''}
+ */
+
+import { eventBus, EventName, type ${eventName}Payload } from '../eventBus.js';
+
+/**
+ * ${subscriberName} class
+ */
+export class ${subscriberName} {
+  private unsubscribe?: () => void;
+
+  /**
+   * Start listening for ${eventName} events
+   */
+  public start(): void {
+    console.log(\`[${subscriberName}] Starting subscriber\`);
+
+    this.unsubscribe = eventBus.subscribe<${eventName}Payload>(
+      EventName.${eventName},
+      this.handleEvent.bind(this)
+    );
+  }
+
+  /**
+   * Stop listening for ${eventName} events
+   */
+  public stop(): void {
+    if (this.unsubscribe) {
+      console.log(\`[${subscriberName}] Stopping subscriber\`);
+      this.unsubscribe();
+      this.unsubscribe = undefined;
+    }
+  }
+
+  /**
+   * Handle ${eventName} event
+   */
+  private async handleEvent(payload: ${eventName}Payload): Promise<void> {
+    try {
+      console.log(\`[${subscriberName}] Received event\`, payload);
+
+      // Process event
+      await this.processEvent(payload);
+
+      console.log(\`[${subscriberName}] Event processed successfully\`);
+    } catch (error) {
+      console.error(\`[${subscriberName}] Failed to process event\`, error);
+      // TODO: Add error handling (dead letter queue, retry logic, etc.)
+    }
+  }
+
+  /**
+   * Process ${eventName} event
+   */
+  private async processEvent(payload: ${eventName}Payload): Promise<void> {
+    // TODO: Implement event processing logic
+    ${generateProcessingLogic(event)}
+  }
+}
+
+// Export singleton instance
+export const ${eventName.toLowerCase()}Subscriber = new ${subscriberName}();
+export default ${eventName.toLowerCase()}Subscriber;
+`;
+}
+
+/**
+ * Generate processing logic placeholder
+ */
+function generateProcessingLogic(event: any): string {
+  return `
+    // Example: Update database, send notifications, trigger workflows, etc.
+    console.log('Processing ${event.name} event:', payload);
+
+    // Add your business logic here
+  `;
+}

package/libs/instance-factories/controllers/README.md

@@ -0,0 +1,42 @@
+# Controllers Factory
+
+Fastify REST API route handlers and server bootstrap generation.
+
+## Definition
+
+| File | Description |
+|------|-------------|
+| `fastify.yaml` | Fastify v4 REST API server with CORS, Helmet, and rate limiting |
+
+## Generated Output
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `routes-generator` | `backend/src/routes/{controller}.ts` | Per-model route handler with CRUD endpoints |
+| `meta-routes-generator` | `backend/src/routes/MetaRoutes.ts` | Meta API for spec/view metadata (serves frontend) |
+| `server-generator` | `backend/src/server.ts` | Server bootstrap — registers all model routes |
+
+The routes generator reads each controller from the spec and creates Fastify route
+handlers. The server generator auto-imports and registers all model route files.
+Meta routes expose spec and view metadata for the view-renderer architecture.
+
+## Technology
+
+- **Framework**: Fastify ^4.24.0
+- **Middleware**: @fastify/cors, @fastify/helmet, @fastify/rate-limit
+- **Language**: TypeScript with tsx for development
+
+## Capabilities
+
+| Provides | Requires |
+|----------|----------|
+| `api.rest` | `storage.database` |
+| `api.rest.crud` | `validation.runtime` |
+| `api.websocket` | |
+
+## Configuration
+
+- Server: port 3000, host 0.0.0.0, trust proxy, structured logging
+- CORS: origin true, credentials true
+- Rate limit: 100 requests per minute
+- Scripts: `dev` (tsx watch), `start` (node dist)

package/libs/instance-factories/controllers/fastify.yaml

@@ -0,0 +1,127 @@
+name: FastifyAPI
+version: "1.0.0"
+category: controller
+description: "Fastify REST API server with WebSocket support"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [fastify, rest-api, websocket, controller]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "api.rest"
+    - "api.rest.crud"
+    - "api.websocket"
+  requires:
+    - "storage.database"  # Needs a database for data persistence
+    - "validation.runtime"  # Needs validation schemas
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "fastify"
+  version: "^4.24.0"
+
+dependencies:
+  runtime:
+    - name: "fastify"
+      version: "^4.24.0"
+    - name: "@fastify/cors"
+      version: "^8.4.0"
+    - name: "@fastify/helmet"
+      version: "^11.1.0"
+    - name: "@fastify/rate-limit"
+      version: "^9.0.0"
+
+  dev:
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+    - name: "tsx"
+      version: "^4.0.0"
+
+codeTemplates:
+  routes:
+    engine: typescript
+    generator: "libs/instance-factories/controllers/templates/fastify/routes-generator.ts"
+    outputPattern: "{backendDir}/src/routes/{controller}.ts"
+
+  meta:
+    engine: typescript
+    generator: "libs/instance-factories/controllers/templates/fastify/meta-routes-generator.ts"
+    outputPattern: "{backendDir}/src/routes/MetaRoutes.ts"
+
+  server:
+    engine: typescript
+    generator: "libs/instance-factories/controllers/templates/fastify/server-generator.ts"
+    outputPattern: "{backendDir}/src/server.ts"
+
+configuration:
+  outputStructure: "monorepo"
+  backendDir: "backend"
+
+  server:
+    port: 3000
+    host: "0.0.0.0"
+    trustProxy: true
+    requestIdLogLabel: "reqId"
+    logger:
+      level: "info"
+      prettyPrint: true
+
+  middleware:
+    cors:
+      origin: true
+      credentials: true
+    helmet:
+      enabled: true
+    rateLimit:
+      max: 100
+      timeWindow: "1 minute"
+
+# Requirements for generic scaffolding (runtime-agnostic structure)
+requirements:
+  # Package dependencies (Node.js/npm-specific)
+  dependencies:
+    npm:
+      dependencies:
+        "fastify": "^4.24.0"
+        "@fastify/cors": "^8.4.0"
+        "yaml": "^2.3.0"
+      devDependencies:
+        "tsx": "^4.0.0"
+      scripts:
+        "dev": "tsx watch src/main.ts"
+        "start": "node dist/main.js"
+
+  # Environment variables (universal structure)
+  environment:
+    - name: "PORT"
+      description: "Server port"
+      example: "3000"
+      required: false
+      category: "Server"
+    - name: "HOST"
+      description: "Server host"
+      example: "0.0.0.0"
+      required: false
+      category: "Server"
+    - name: "LOG_LEVEL"
+      description: "Logging level (trace, debug, info, warn, error, fatal)"
+      example: "info"
+      required: false
+      category: "Server"
+
+  # Build/runtime configuration (TypeScript-specific)
+  configuration:
+    tsconfig:
+      compilerOptions:
+        target: "ES2022"
+        module: "ESNext"
+        moduleResolution: "node"