@specverse/engine-realize 3.5.3

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/engine-realize';
+
+/**
+ * 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/engine-realize';
+
+/**
+ * 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/engine-realize';
+
+/**
+ * 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/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"

package/libs/instance-factories/controllers/templates/fastify/meta-routes-generator.ts

@@ -0,0 +1,103 @@
+/**
+ * Fastify Meta Routes Generator
+ *
+ * Generates meta API endpoints for serving spec and view metadata
+ * These endpoints are needed by view-renderers architecture
+ */
+
+import type { TemplateContext } from '@specverse/engine-realize';
+
+/**
+ * Generate Fastify meta routes for spec and views metadata
+ */
+export default function generateMetaRoutes(context: TemplateContext): string {
+  const { spec } = context;
+
+  return `/**
+ * Meta API Routes
+ *
+ * Provides spec and view metadata endpoints for the frontend
+ */
+
+import { FastifyInstance, FastifyPluginOptions } from 'fastify';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { parse } from 'yaml';
+
+export default async function MetaRoutes(
+  fastify: FastifyInstance,
+  options: FastifyPluginOptions
+) {
+  // Get specification
+  fastify.get('/spec', async (request, reply) => {
+    try {
+      const specPath = join(process.cwd(), '../../../specs/main.specly');
+      const specContent = await readFile(specPath, 'utf-8');
+      const spec = parse(specContent);
+      return spec;
+    } catch (error: any) {
+      reply.status(500).send({ error: \`Failed to load spec: \${error.message}\` });
+    }
+  });
+
+  // Get all views
+  fastify.get('/views', async (request, reply) => {
+    try {
+      const specPath = join(process.cwd(), '../../../specs/main.specly');
+      const specContent = await readFile(specPath, 'utf-8');
+      const spec = parse(specContent);
+
+      // Extract views from the spec
+      const views = [];
+      if (spec.components && typeof spec.components === 'object') {
+        // components is an object with component names as keys
+        for (const [componentName, component] of Object.entries(spec.components)) {
+          if (component && typeof component === 'object' && 'views' in component) {
+            const componentViews = component.views as Record<string, any>;
+            for (const [viewName, viewDef] of Object.entries(componentViews)) {
+              views.push({
+                name: viewName,
+                ...viewDef as any
+              });
+            }
+          }
+        }
+      }
+
+      return { views };
+    } catch (error: any) {
+      reply.status(500).send({ error: \`Failed to load views: \${error.message}\` });
+    }
+  });
+
+  // Get individual view by name
+  fastify.get('/views/:viewName', async (request, reply) => {
+    try {
+      const { viewName } = request.params as { viewName: string };
+      const specPath = join(process.cwd(), '../../../specs/main.specly');
+      const specContent = await readFile(specPath, 'utf-8');
+      const spec = parse(specContent);
+
+      // Find the view
+      if (spec.components && typeof spec.components === 'object') {
+        for (const [componentName, component] of Object.entries(spec.components)) {
+          if (component && typeof component === 'object' && 'views' in component) {
+            const componentViews = component.views as Record<string, any>;
+            if (componentViews[viewName]) {
+              return {
+                name: viewName,
+                ...componentViews[viewName]
+              };
+            }
+          }
+        }
+      }
+
+      reply.status(404).send({ error: \`View \${viewName} not found\` });
+    } catch (error: any) {
+      reply.status(500).send({ error: \`Failed to load view: \${error.message}\` });
+    }
+  });
+}
+`;
+}