@specverse/engines 4.1.13 → 4.1.14

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

@@ -1,20 +1,26 @@
 function generateEventBus(context) {
   const { spec } = context;
-  const events = spec.events ? Object.keys(spec.events) : [];
+  const hasEvents = spec.events && Object.keys(spec.events).length > 0;
+  const models = spec.models ? Object.keys(spec.models) : [];
   return `/**
  * Event Bus
- * In-memory event bus using EventEmitter3
+ * Typed in-memory event bus using EventEmitter3
  * Generated from SpecVerse specification
  */
 
 import EventEmitter from 'eventemitter3';
+${hasEvents || models.length > 0 ? `import type { EventPayloads, EventName } from './event-types.js';` : ""}
 
-// Event type definitions
-${events.map((event) => `export type ${event}Payload = any; // TODO: Define payload type`).join("\n")}
+// Re-export types for consumers
+${hasEvents || models.length > 0 ? `export type { EventPayloads, EventName } from './event-types.js';` : ""}
 
-// Event names enum
-export enum EventName {
-${events.map((event) => `  ${event} = '${event}',`).join("\n")}
+/**
+ * Event history entry
+ */
+interface EventHistoryEntry {
+  event: string;
+  payload: any;
+  timestamp: Date;
 }
 
 /**
@@ -22,15 +28,14 @@ ${events.map((event) => `  ${event} = '${event}',`).join("\n")}
  */
 class EventBus extends EventEmitter {
   private static instance: EventBus;
+  private history: EventHistoryEntry[] = [];
+  private maxHistory = 1000;
 
   private constructor() {
     super();
-    this.setMaxListeners(100); // Configure max listeners
+    this.setMaxListeners(100);
   }
 
-  /**
-   * Get singleton instance
-   */
   public static getInstance(): EventBus {
     if (!EventBus.instance) {
       EventBus.instance = new EventBus();
@@ -39,37 +44,33 @@ class EventBus extends EventEmitter {
   }
 
   /**
-   * Publish an event
+   * Publish a typed event
    */
-  public publish<T = any>(event: EventName | string, payload: T): void {
-    console.log(\`[EventBus] Publishing event: \${event}\`, payload);
+  public publish<K extends string>(event: K, payload: K extends keyof EventPayloads ? EventPayloads[K] : any): void {
+    this.history.push({ event, payload, timestamp: new Date() });
+    if (this.history.length > this.maxHistory) this.history.shift();
     this.emit(event, payload);
   }
 
   /**
-   * Subscribe to an event
+   * Subscribe to a typed event
    */
-  public subscribe<T = any>(
-    event: EventName | string,
-    handler: (payload: T) => void | Promise<void>
+  public subscribe<K extends string>(
+    event: K,
+    handler: (payload: K extends keyof EventPayloads ? EventPayloads[K] : any) => void | Promise<void>
   ): () => void {
-    console.log(\`[EventBus] Subscribing to event: \${event}\`);
     this.on(event, handler);
-
-    // Return unsubscribe function
-    return () => {
-      this.off(event, handler);
-    };
+    return () => { this.off(event, handler); };
   }
 
   /**
-   * Subscribe to an event (one-time)
+   * Get event history
    */
-  public subscribeOnce<T = any>(
-    event: EventName | string,
-    handler: (payload: T) => void | Promise<void>
-  ): void {
-    this.once(event, handler);
+  public getHistory(eventName?: string, limit = 50): EventHistoryEntry[] {
+    const filtered = eventName
+      ? this.history.filter(e => e.event === eventName)
+      : this.history;
+    return filtered.slice(-limit);
   }
 }
 

package/dist/libs/instance-factories/communication/templates/eventemitter/types-generator.js

@@ -0,0 +1,79 @@
+function tsType(specType) {
+  const map = {
+    String: "string",
+    Text: "string",
+    Email: "string",
+    URL: "string",
+    Integer: "number",
+    Float: "number",
+    Number: "number",
+    Decimal: "number",
+    Money: "number",
+    Boolean: "boolean",
+    Date: "string",
+    DateTime: "string",
+    Timestamp: "string",
+    UUID: "string",
+    Object: "Record<string, any>",
+    Array: "any[]"
+  };
+  return map[specType] || "any";
+}
+function generateEventTypes(context) {
+  const { spec } = context;
+  const events = spec.events && typeof spec.events === "object" ? Object.entries(spec.events) : [];
+  if (events.length === 0) {
+    return `/**
+ * Event Types \u2014 no events defined in specification
+ */
+export type EventPayloads = Record<string, any>;
+`;
+  }
+  const interfaces = [];
+  const payloadMapEntries = [];
+  for (const [eventName, eventDef] of events) {
+    const def = eventDef;
+    const attrs = def.attributes || def.payload || {};
+    const attrEntries = Array.isArray(attrs) ? attrs.map((a) => [a.name, a]) : Object.entries(attrs);
+    const fields = attrEntries.map(([name, attrDef]) => {
+      const type = typeof attrDef === "string" ? tsType(attrDef.split(" ")[0]) : tsType(attrDef?.type || "String");
+      const required = typeof attrDef === "string" ? attrDef.includes("required") : attrDef?.required;
+      return `  ${name}${required ? "" : "?"}: ${type};`;
+    });
+    interfaces.push(`export interface ${eventName}Payload {
+${fields.join("\n")}
+}`);
+    payloadMapEntries.push(`  ${eventName}: ${eventName}Payload;`);
+  }
+  const models = spec.models ? Object.keys(spec.models) : [];
+  for (const model of models) {
+    for (const suffix of ["Created", "Updated", "Deleted", "Evolved"]) {
+      const name = `${model}${suffix}`;
+      if (!payloadMapEntries.some((e) => e.includes(name))) {
+        payloadMapEntries.push(`  ${name}: { id: string; timestamp: string; [key: string]: any };`);
+      }
+    }
+  }
+  return `/**
+ * Event Payload Types
+ * Generated from SpecVerse specification
+ */
+
+${interfaces.join("\n\n")}
+
+/**
+ * Map of all event names to their payload types
+ */
+export type EventPayloads = {
+${payloadMapEntries.join("\n")}
+};
+
+/**
+ * All known event names
+ */
+export type EventName = keyof EventPayloads;
+`;
+}
+export {
+  generateEventTypes as default
+};

package/dist/libs/instance-factories/communication/templates/eventemitter/websocket-bridge-generator.js

@@ -0,0 +1,96 @@
+function generateWebSocketBridge(context) {
+  const { spec } = context;
+  const models = spec.models ? Object.keys(spec.models) : [];
+  const specEvents = spec.events ? Object.keys(spec.events) : [];
+  const curedEvents = models.flatMap(
+    (m) => ["Created", "Updated", "Deleted", "Evolved"].map((s) => `${m}${s}`)
+  );
+  const allEvents = [.../* @__PURE__ */ new Set([...specEvents, ...curedEvents])];
+  return `/**
+ * WebSocket Bridge
+ * Bridges the event bus to frontend clients for real-time updates.
+ * Generated from SpecVerse specification
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { WebSocket } from '@fastify/websocket';
+import { eventBus } from './eventBus.js';
+
+interface ClientSubscription {
+  ws: WebSocket;
+  events: Set<string>;
+}
+
+const clients = new Map<WebSocket, ClientSubscription>();
+
+// All events this bridge knows about
+const ALL_EVENTS = ${JSON.stringify(allEvents, null, 2)};
+
+/**
+ * Register WebSocket bridge with Fastify
+ */
+export async function registerWebSocketBridge(fastify: FastifyInstance): Promise<void> {
+  // Register @fastify/websocket plugin
+  const websocketPlugin = await import('@fastify/websocket');
+  await fastify.register(websocketPlugin.default || websocketPlugin);
+
+  // WebSocket route
+  fastify.get('/ws', { websocket: true }, (socket: WebSocket) => {
+    const subscription: ClientSubscription = { ws: socket, events: new Set() };
+    clients.set(socket, subscription);
+
+    socket.on('message', (raw: Buffer) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+
+        if (msg.type === 'subscribe' && msg.event) {
+          subscription.events.add(msg.event);
+          socket.send(JSON.stringify({ type: 'subscribed', event: msg.event }));
+        }
+
+        if (msg.type === 'unsubscribe' && msg.event) {
+          subscription.events.delete(msg.event);
+          socket.send(JSON.stringify({ type: 'unsubscribed', event: msg.event }));
+        }
+
+        if (msg.type === 'subscribe-all') {
+          ALL_EVENTS.forEach(e => subscription.events.add(e));
+          socket.send(JSON.stringify({ type: 'subscribed-all', events: ALL_EVENTS }));
+        }
+      } catch { /* ignore malformed messages */ }
+    });
+
+    socket.on('close', () => {
+      clients.delete(socket);
+    });
+
+    // Send initial connection confirmation
+    socket.send(JSON.stringify({
+      type: 'connected',
+      availableEvents: ALL_EVENTS,
+    }));
+  });
+
+  // Subscribe to all events and broadcast to interested clients
+  for (const eventName of ALL_EVENTS) {
+    eventBus.subscribe(eventName, (payload: any) => {
+      const message = JSON.stringify({
+        type: 'event',
+        event: eventName,
+        payload,
+        timestamp: new Date().toISOString(),
+      });
+
+      for (const [ws, sub] of clients) {
+        if (sub.events.has(eventName) && ws.readyState === 1) {
+          try { ws.send(message); } catch { /* client disconnected */ }
+        }
+      }
+    });
+  }
+}
+`;
+}
+export {
+  generateWebSocketBridge as default
+};

package/dist/libs/instance-factories/controllers/templates/fastify/routes-generator.js

@@ -16,6 +16,20 @@ function generateFastifyRoutes(context) {
       endpoints = curedToEndpoints(controller.cured, modelName);
     }
   }
+  if (controller.actions) {
+    if (!endpoints) endpoints = [];
+    for (const [actionName, action] of Object.entries(controller.actions)) {
+      const params = action.parameters || {};
+      const hasIdParam = Object.keys(params).some((p) => p === "id" || p === `${modelName?.charAt(0).toLowerCase()}${modelName?.slice(1)}Id`);
+      endpoints.push({
+        operation: actionName,
+        method: "POST",
+        path: hasIdParam ? `/:id/${actionName}` : `/${actionName}`,
+        parameters: params,
+        description: action.description || `Custom action: ${actionName}`
+      });
+    }
+  }
   if (!endpoints || endpoints.length === 0) {
     console.warn(`Warning: Controller ${controllerName} has no endpoints. Generating empty routes file.`);
   }
@@ -76,7 +90,7 @@ function generateRouteHandler(endpoint, modelName, handlerName, isModelControlle
   }
   const method = endpoint.method?.toLowerCase() || inferHttpMethod(operation);
   const path = inferPath(operation, endpoint);
-  const handler = generateHandlerBody(operation, modelName, handlerName, isModelController, implType);
+  const handler = generateHandlerBody(operation, modelName, handlerName, isModelController, implType, endpoint);
   let route = `// ${operation} ${modelName}
 `;
   route += `fastify.${method}('${path}', {
@@ -111,7 +125,7 @@ function generateRouteHandler(endpoint, modelName, handlerName, isModelControlle
   route += `});`;
   return route;
 }
-function generateHandlerBody(operation, modelName, handlerName, isModelController, implType) {
+function generateHandlerBody(operation, modelName, handlerName, isModelController, implType, endpoint) {
   const rawLowerModel = modelName?.toLowerCase() || "item";
   const RESERVED_WORDS = /* @__PURE__ */ new Set(["import", "export", "default", "class", "function", "return", "delete", "new", "this", "switch", "case", "break", "continue", "for", "while", "do", "if", "else", "try", "catch", "finally", "throw", "typeof", "instanceof", "in", "of", "let", "const", "var", "void", "with", "yield", "async", "await", "enum", "implements", "interface", "package", "private", "protected", "public", "static", "super", "extends"]);
   const lowerModel = RESERVED_WORDS.has(rawLowerModel) ? `${rawLowerModel}Item` : rawLowerModel;
@@ -199,16 +213,20 @@ function generateHandlerBody(operation, modelName, handlerName, isModelControlle
     message: error instanceof Error ? error.message : String(error)
   });
 }`;
-    default:
+    default: {
+      const paramNames = endpoint?.parameters ? Object.keys(endpoint.parameters) : [];
+      const callArgs = paramNames.length > 0 ? paramNames.map((p) => `body.${p}`).join(", ") : "body";
       return `try {
-  const result = await handler.${operation}(request.body as any);
-  return reply.send(result);
+  const body = (request.body || {}) as Record<string, any>;
+  const result = await handler.${operation}(${callArgs});
+  return reply.send(result || { success: true });
 } catch (error) {
   return reply.status(400).send({
     error: 'Failed to execute ${operation}',
     message: error instanceof Error ? error.message : String(error)
   });
 }`;
+    }
   }
 }
 function inferOperationFromMethodAndPath(method, path) {
@@ -227,10 +245,8 @@ function inferHttpMethod(operation) {
   return sharedInferHttpMethod(operation);
 }
 function inferPath(operation, endpoint) {
-  if (endpoint?.path && endpoint.serviceOperation?.type === "custom") {
-    const pathParts = endpoint.path.split("/").filter((p) => p);
-    const lastPart = pathParts[pathParts.length - 1];
-    return `/${lastPart}`;
+  if (endpoint?.path) {
+    return endpoint.path;
   }
   return sharedInferPath(operation);
 }

package/dist/libs/instance-factories/controllers/templates/fastify/server-generator.js

@@ -10,6 +10,12 @@ function generateFastifyServer(context) {
     const path = deriveBasePath(name);
     return `  await fastify.register(${name}Routes, { prefix: '${path}', controllers: { ${name}Controller: new (await import('./controllers/${name}Controller.js')).${name}Controller() } });`;
   }).join("\n");
+  const specEvents = spec.events ? Object.keys(spec.events) : [];
+  const hasEvents = specEvents.length > 0 || modelNames.length > 0;
+  const servicesList = spec.services ? Object.keys(spec.services) : [];
+  const serviceImports = servicesList.map(
+    (name) => `import './${name.charAt(0).toLowerCase() + name.slice(1)}.js'; // Initialize ${name} event subscriptions`
+  );
   return `/**
  * Fastify Server
  * Generated from SpecVerse specification
@@ -18,6 +24,8 @@ function generateFastifyServer(context) {
 import Fastify from 'fastify';
 import cors from '@fastify/cors';
 import { PrismaClient } from '@prisma/client';
+${hasEvents ? `import { eventBus } from './events/eventBus.js';
+import { registerWebSocketBridge } from './events/websocket-bridge.js';` : ""}
 
 // Initialize Prisma
 export const prisma = new PrismaClient();
@@ -42,13 +50,19 @@ fastify.get('/api/spec', async () => embeddedSpec);
 fastify.get('/api/runtime/info', async () => ({
   controllers: ${JSON.stringify(modelNames.map((n) => `${n}Controller`))},
   models: ${JSON.stringify(modelNames)},
-  events: [],
-  services: []
+  events: ${JSON.stringify(specEvents)},
+  services: ${JSON.stringify(servicesList)}
 }));
 
+${hasEvents ? `// Event history endpoint
+fastify.get('/api/events', async () => eventBus.getHistory());` : ""}
+
 // Register routes
 ${routeImports}
 
+${serviceImports.length > 0 ? `// Initialize services (registers event subscriptions)
+${serviceImports.join("\n")}` : ""}
+
 async function registerRoutes() {
 ${routeRegistrations}
 }
@@ -57,10 +71,14 @@ ${routeRegistrations}
 const start = async () => {
   try {
     await registerRoutes();
+${hasEvents ? `    // Register WebSocket bridge for real-time frontend events
+    await registerWebSocketBridge(fastify);` : ""}
     const port = parseInt(process.env.PORT || '3000');
     await fastify.listen({ port, host: '0.0.0.0' });
     console.log(\`Server running at http://localhost:\${port}\`);
     console.log(\`API endpoints: ${modelNames.map((n) => `/api/${n.toLowerCase()}s`).join(", ")}\`);
+${hasEvents ? `    console.log(\`WebSocket: ws://localhost:\${port}/ws\`);
+    console.log(\`Events: ${specEvents.join(", ")}\`);` : ""}
   } catch (err) {
     fastify.log.error(err);
     process.exit(1);

package/dist/libs/instance-factories/services/templates/prisma/ai-behaviors-generator.js

@@ -0,0 +1,141 @@
+import { matchStep } from "./step-conventions.js";
+async function generateAiBehaviors(context) {
+  const { controller, model } = context;
+  if (!controller?.actions) return "";
+  const modelName = model?.name || controller.model || "Model";
+  const modelVar = modelName.charAt(0).toLowerCase() + modelName.slice(1);
+  const unmatchedFunctions = [];
+  for (const [actionName, action] of Object.entries(controller.actions)) {
+    const steps = action.steps || [];
+    const parameterNames = Object.keys(action.parameters || {});
+    const preconditions = action.requires || action.preconditions || [];
+    const declaredVars = /* @__PURE__ */ new Set();
+    for (const pc of preconditions) {
+      const match = pc.match(/^(\w+)\s+(?:exists|is\s+\w+)$/i);
+      if (match) {
+        const entity = match[1];
+        declaredVars.add(entity.charAt(0).toLowerCase() + entity.slice(1));
+      }
+    }
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      if (typeof step !== "string") continue;
+      const ctx = {
+        modelName,
+        prismaModel: modelVar,
+        serviceName: `${modelName}Controller`,
+        operationName: actionName,
+        stepNum: i + 1,
+        parameterNames,
+        declaredVars
+      };
+      const result = matchStep(step, ctx);
+      if (!result.matched && result.functionName) {
+        const existing = unmatchedFunctions.find((f) => f.functionName === result.functionName);
+        if (!existing) {
+          unmatchedFunctions.push({
+            functionName: result.functionName,
+            step,
+            operationName: actionName,
+            parameterNames,
+            inputs: result.inputs || []
+          });
+        }
+      }
+    }
+  }
+  if (unmatchedFunctions.length === 0) return "";
+  let aiService = null;
+  try {
+    const { BehaviorAIService } = await import("@specverse/engines/ai");
+    aiService = new BehaviorAIService();
+    if (!aiService.isAvailable) {
+      aiService = null;
+    } else {
+      aiService.startSession(`${modelName}Controller`);
+    }
+  } catch {
+    aiService = null;
+  }
+  const availableModels = context.spec?.models ? Object.keys(context.spec.models) : [];
+  const functions = [];
+  for (const { functionName, step, operationName, parameterNames, inputs } of unmatchedFunctions) {
+    const signature = inputs.length > 0 ? `input: { ${inputs.map((n) => `${n}: any`).join("; ")} }` : "input: Record<string, never>";
+    const destructure = inputs.length > 0 ? `  const { ${inputs.join(", ")} } = input;` : "";
+    let body = null;
+    let source = "STUB";
+    if (aiService) {
+      try {
+        body = await aiService.generateBehavior({
+          step,
+          modelName,
+          operationName,
+          functionName,
+          parameterNames: inputs,
+          // the actual inputs to the pure function
+          availableModels,
+          spec: context.spec
+        });
+        if (body) source = "AI-GENERATED";
+      } catch {
+      }
+    }
+    if (!body) {
+      body = `  throw new Error('Not implemented: ${functionName} \u2014 see behaviors/${modelName}Controller.ai.ts');`;
+    } else {
+      body = body.split("\n").map((line) => line ? "  " + line : line).join("\n");
+    }
+    const inputsDoc = inputs.length > 0 ? ` * Inputs: ${inputs.join(", ")}
+` : "";
+    functions.push(`/**
+ * ${functionName}
+ *
+ * Spec step: "${step}"
+ * Called by: ${modelName}Controller.${operationName}()
+${inputsDoc} * Source: ${source}
+ * Generated: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}
+ *
+ * PURE FUNCTION \u2014 no database access, no event publishing, no external services.
+ * All data comes in via \`input\`; all effects happen in the calling controller.
+ * ${source === "AI-GENERATED" ? "AI-generated implementation. Review and test before deploying." : "STUB \u2014 Claude CLI unavailable. Install Claude Code or implement manually."}
+ */
+export async function ${functionName}(${signature}): Promise<any> {
+${destructure ? destructure + "\n" : ""}${body}
+}`);
+  }
+  if (aiService?.endSession) aiService.endSession();
+  return `/**
+ * ${modelName}Controller \u2014 AI-Generated Behaviors
+ *
+ * \u26A0\uFE0F  THIS FILE CONTAINS STUBS FOR STEPS THAT NEED IMPLEMENTATION
+ *
+ * These functions could not be generated from convention patterns.
+ * They are called by ${modelName}Controller when executing custom actions.
+ *
+ * Options for each function:
+ * - Implement manually (recommended for business-critical logic)
+ * - Use AI generation: specverse ai generate <function>
+ * - Refactor the spec step to use a convention pattern
+ *
+ * Convention patterns that ARE auto-generated (no AI needed):
+ *   "Find {Model} by {field}" \u2192 prisma.model.findUniqueOrThrow(...)
+ *   "Create {Model}" \u2192 prisma.model.create(...)
+ *   "Update {Model} {field} to {value}" \u2192 prisma.model.update(...)
+ *   "Delete {Model}" \u2192 prisma.model.delete(...)
+ *   "Transition {Model} to {state}" \u2192 prisma.model.update({ status: ... })
+ *   "Count {Model}s per {Group}" \u2192 prisma.model.groupBy(...)
+ *   See step-conventions.ts for the full list.
+ *
+ * Generated: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}
+ */
+
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+${functions.join("\n\n")}
+`;
+}
+export {
+  generateAiBehaviors as default
+};