@specverse/engines 4.1.13 → 4.1.14

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

@@ -36,6 +36,22 @@ export default function generateFastifyRoutes(context: TemplateContext): string
     }
   }
 
+  // Add custom action endpoints
+  if (controller.actions) {
+    if (!endpoints) endpoints = [];
+    for (const [actionName, action] of Object.entries(controller.actions) as [string, any][]) {
+      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}`,
+      });
+    }
+  }
+
   // Generate route handlers for each endpoint
   if (!endpoints || endpoints.length === 0) {
     console.warn(`Warning: Controller ${controllerName} has no endpoints. Generating empty routes file.`);
@@ -137,7 +153,7 @@ function generateRouteHandler(
 
   const method = endpoint.method?.toLowerCase() || inferHttpMethod(operation);
   const path = inferPath(operation, endpoint); // Always call inferPath to handle path extraction
-  const handler = generateHandlerBody(operation, modelName, handlerName, isModelController, implType);
+  const handler = generateHandlerBody(operation, modelName, handlerName, isModelController, implType, endpoint);
 
   let route = `// ${operation} ${modelName}\n`;
   route += `fastify.${method}('${path}', {\n`;
@@ -181,7 +197,8 @@ function generateHandlerBody(
   modelName: string,
   handlerName: string,
   isModelController: boolean,
-  implType: any
+  implType: any,
+  endpoint?: any
 ): string {
   const rawLowerModel = modelName?.toLowerCase() || 'item';
   // Avoid JavaScript reserved words as variable names
@@ -276,17 +293,23 @@ function generateHandlerBody(
   });
 }`;
 
-    default:
-      // For custom actions, generate a handler that calls the action method
+    default: {
+      // Custom action — pass named parameters from body (and :id from URL if present)
+      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)
   });
 }`;
+    }
   }
 }
 
@@ -322,11 +345,9 @@ function inferHttpMethod(operation: string): string {
  * handles custom service operation paths locally.
  */
 function inferPath(operation: string, endpoint: any): string {
-  // For custom actions, extract relative path from endpoint.path
-  if (endpoint?.path && endpoint.serviceOperation?.type === 'custom') {
-    const pathParts = endpoint.path.split('/').filter((p: string) => p);
-    const lastPart = pathParts[pathParts.length - 1];
-    return `/${lastPart}`;
+  // If endpoint has an explicit path, use it directly
+  if (endpoint?.path) {
+    return endpoint.path;
   }
 
   return sharedInferPath(operation);

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

@@ -24,6 +24,16 @@ export default function generateFastifyServer(context: TemplateContext): string
     return `  await fastify.register(${name}Routes, { prefix: '${path}', controllers: { ${name}Controller: new (await import('./controllers/${name}Controller.js')).${name}Controller() } });`;
   }).join('\n');
 
+  // Check for events in spec
+  const specEvents = spec.events ? Object.keys(spec.events) : [];
+  const hasEvents = specEvents.length > 0 || modelNames.length > 0;
+
+  // Service imports
+  const servicesList = spec.services ? Object.keys(spec.services) : [];
+  const serviceImports = servicesList.map((name: string) =>
+    `import './${name.charAt(0).toLowerCase() + name.slice(1)}.js'; // Initialize ${name} event subscriptions`
+  );
+
   return `/**
  * Fastify Server
  * Generated from SpecVerse specification
@@ -32,6 +42,8 @@ export default function generateFastifyServer(context: TemplateContext): string
 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();
@@ -56,13 +68,18 @@ fastify.get('/api/spec', async () => embeddedSpec);
 fastify.get('/api/runtime/info', async () => ({
   controllers: ${JSON.stringify(modelNames.map((n: string) => `${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)\n${serviceImports.join('\n')}` : ''}
+
 async function registerRoutes() {
 ${routeRegistrations}
 }
@@ -71,10 +88,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: string) => `/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/libs/instance-factories/services/templates/prisma/ai-behaviors-generator.ts

@@ -0,0 +1,211 @@
+/**
+ * AI Behaviors Generator
+ *
+ * Generates files for behavior steps that couldn't be matched
+ * by convention patterns. Tries to use the configured AI engine to
+ * generate real implementations; falls back to stubs if AI is unavailable.
+ *
+ * - Clearly separated from convention-generated code (.ai.ts suffix)
+ * - Each function header documents the spec step + generation method
+ * - Human reviewable and editable
+ * - Regeneratable via `specverse ai regenerate` (TODO)
+ * - Falls back to stub if AI unavailable or fails
+ *
+ * Level separation:
+ *   L1/L2: Convention code → inline in controller (trusted, deterministic)
+ *   L3:    Quint guards → guards.ts (formally verified)
+ *   L4:    AI-generated → behaviors/*.ai.ts (needs human review)
+ */
+
+import type { TemplateContext } from '@specverse/types';
+import { matchStep, type StepContext } from './step-conventions.js';
+
+/**
+ * Generate AI behaviors file for a controller's unmatched steps.
+ * Returns empty string if all steps matched conventions (no AI file needed).
+ *
+ * This is async — it calls the AI engine to generate function bodies.
+ */
+export default async function generateAiBehaviors(context: TemplateContext): Promise<string> {
+  const { controller, model } = context;
+  if (!controller?.actions) return '';
+
+  const modelName = model?.name || controller.model || 'Model';
+  const modelVar = modelName.charAt(0).toLowerCase() + modelName.slice(1);
+
+  // Find unmatched steps across all actions.
+  // We simulate step execution through matchStep() so declaredVars accumulates
+  // exactly as it does in the controller generator — that way the inputs array
+  // for each unmatched step matches what will actually be passed at runtime.
+  const unmatchedFunctions: Array<{
+    functionName: string;
+    step: string;
+    operationName: string;
+    parameterNames: string[];
+    inputs: string[];
+  }> = [];
+
+  for (const [actionName, action] of Object.entries(controller.actions) as [string, any][]) {
+    const steps = action.steps || [];
+    const parameterNames = Object.keys(action.parameters || {});
+    const preconditions = action.requires || action.preconditions || [];
+
+    // Simulate precondition variable declarations
+    const declaredVars = new Set<string>();
+    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: StepContext = {
+        modelName,
+        prismaModel: modelVar,
+        serviceName: `${modelName}Controller`,
+        operationName: actionName,
+        stepNum: i + 1,
+        parameterNames,
+        declaredVars,
+      };
+
+      const result = matchStep(step, ctx);
+      if (!result.matched && result.functionName) {
+        // Avoid duplicate function definitions, but capture the widest set of inputs
+        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 '';
+
+  // Start a Claude session for this controller — all unmatched functions share
+  // the conversation context, so Claude builds understanding of the spec
+  // across calls (mirrors app-demo's session-based AI service)
+  let aiService: any = 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) : []) as string[];
+
+  // Generate function bodies sequentially — same Claude session for all
+  const functions: string[] = [];
+  for (const { functionName, step, operationName, parameterNames, inputs } of unmatchedFunctions) {
+    // Pure function signature: all inputs as a typed destructured object
+    const signature = inputs.length > 0
+      ? `input: { ${inputs.map(n => `${n}: any`).join('; ')} }`
+      : 'input: Record<string, never>';
+
+    // Inside the body, destructure for readability
+    const destructure = inputs.length > 0
+      ? `  const { ${inputs.join(', ')} } = input;`
+      : '';
+
+    let body: string | null = 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 {
+        // Fall through to stub
+      }
+    }
+
+    if (!body) {
+      body = `  throw new Error('Not implemented: ${functionName} — see behaviors/${modelName}Controller.ai.ts');`;
+    } else {
+      // Indent body to match function scope
+      body = body.split('\n').map(line => line ? '  ' + line : line).join('\n');
+    }
+
+    const inputsDoc = inputs.length > 0
+      ? ` * Inputs: ${inputs.join(', ')}\n`
+      : '';
+
+    functions.push(`/**
+ * ${functionName}
+ *
+ * Spec step: "${step}"
+ * Called by: ${modelName}Controller.${operationName}()
+${inputsDoc} * Source: ${source}
+ * Generated: ${new Date().toISOString().split('T')[0]}
+ *
+ * PURE FUNCTION — 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 — Claude CLI unavailable. Install Claude Code or implement manually.'}
+ */
+export async function ${functionName}(${signature}): Promise<any> {
+${destructure ? destructure + '\n' : ''}${body}
+}`);
+  }
+
+  // End the session
+  if (aiService?.endSession) aiService.endSession();
+
+  return `/**
+ * ${modelName}Controller — AI-Generated Behaviors
+ *
+ * ⚠️  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}" → prisma.model.findUniqueOrThrow(...)
+ *   "Create {Model}" → prisma.model.create(...)
+ *   "Update {Model} {field} to {value}" → prisma.model.update(...)
+ *   "Delete {Model}" → prisma.model.delete(...)
+ *   "Transition {Model} to {state}" → prisma.model.update({ status: ... })
+ *   "Count {Model}s per {Group}" → prisma.model.groupBy(...)
+ *   See step-conventions.ts for the full list.
+ *
+ * Generated: ${new Date().toISOString().split('T')[0]}
+ */
+
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+${functions.join('\n\n')}
+`;
+}

package/libs/instance-factories/services/templates/prisma/behavior-generator.ts

@@ -24,6 +24,8 @@ export interface BehaviorContext {
   serviceName: string;
   operationName: string;
   prismaModel?: string;
+  /** Parameter names from the action definition (e.g., ['pollId', 'optionId', 'voterName']) */
+  parameterNames?: string[];
 }
 
 export interface BehaviorMetadata {
@@ -43,6 +45,14 @@ export interface OperationMetadata {
 export interface BehaviorResult {
   body: string;
   helperMethods: string[];
+  /** Steps that couldn't be matched by conventions — need AI generation */
+  unmatchedSteps: Array<{
+    step: string;
+    functionName: string;
+    operationName: string;
+    /** Names of variables passed as the typed input object */
+    inputs: string[];
+  }>;
 }
 
 /**
@@ -71,15 +81,18 @@ export function generateBehaviorWithHelpers(
   const parts: string[] = [];
   const helperMethods: string[] = [];
 
+  // Track variables declared by preconditions so steps can reuse them
+  const preconditionDeclared = new Set<string>();
+
   // Precondition guards
   const preconditions = generatePreconditionChecks(
-    behavior.preconditions || [], context
+    behavior.preconditions || [], context, preconditionDeclared
   );
   if (preconditions) parts.push(preconditions);
 
   // Main logic (from steps or inferred from operation semantics)
-  const { code, helpers } = generateStepLogic(
-    behavior.steps || [], context
+  const { code, helpers, unmatchedSteps } = generateStepLogic(
+    behavior.steps || [], context, preconditionDeclared
   );
   parts.push(code);
   helperMethods.push(...helpers);
@@ -92,7 +105,7 @@ export function generateBehaviorWithHelpers(
 
   // Event publishing
   const events = generateEventPublishing(
-    behavior.sideEffects || [], context.operationName
+    behavior.sideEffects || [], context.operationName, context.parameterNames
   );
   if (events) parts.push(events);
 
@@ -103,39 +116,56 @@ export function generateBehaviorWithHelpers(
     body = generateTransactionWrapper(body, context);
   }
 
-  return { body, helperMethods };
+  return { body, helperMethods, unmatchedSteps };
 }
 
 /**
  * Generate precondition checks from natural-language strings.
+ * Tracks declared variables to avoid duplicates and reuses fetched entities.
  */
 export function generatePreconditionChecks(
   preconditions: string[],
-  context: BehaviorContext
+  context: BehaviorContext,
+  declared?: Set<string>
 ): string {
   if (preconditions.length === 0) return '';
 
-  const checks = preconditions.map(pc => matchPreconditionPattern(pc, context));
+  if (!declared) declared = new Set<string>();
+  const checks = preconditions.map(pc => matchPreconditionPattern(pc, context, declared));
   return `    // === PRECONDITIONS ===\n${checks.join('\n')}`;
 }
 
+/** Find the parameter name that refers to a model (e.g., 'pollId' for 'Poll') */
+function findIdParam(modelName: string, paramNames: string[]): string {
+  const modelVar = modelName.charAt(0).toLowerCase() + modelName.slice(1);
+  // Check for modelId (e.g., pollId)
+  const idParam = paramNames.find(p => p === `${modelVar}Id`);
+  if (idParam) return idParam;
+  // Check for just 'id'
+  if (paramNames.includes('id')) return 'id';
+  return `${modelVar}Id`;
+}
+
 function matchPreconditionPattern(
   precondition: string,
-  context: BehaviorContext
+  context: BehaviorContext,
+  declared: Set<string>
 ): string {
   const pc = precondition.toLowerCase();
-  const prismaModel = context.prismaModel || context.modelName;
+  const params = context.parameterNames || [];
 
   // Pattern: "{Model} exists"
   const existsMatch = precondition.match(/^(\w+)\s+exists/i);
   if (existsMatch) {
     const entity = existsMatch[1];
     const entityVar = entity.charAt(0).toLowerCase() + entity.slice(1);
-    return `    // Guard: ${precondition}
-    const ${entityVar} = await prisma.${entityVar}.findUnique({ where: { id: params.id } });
-    if (!${entityVar}) {
-      throw new Error('Precondition failed: ${precondition}');
-    }`;
+    const idParam = findIdParam(entity, params);
+    if (declared.has(entityVar)) {
+      // Already fetched — just check it
+      return `    // Guard: ${precondition} (already fetched)`;
+    }
+    declared.add(entityVar);
+    return `    const ${entityVar} = await prisma.${entityVar}.findUniqueOrThrow({ where: { id: ${idParam} } });`;
   }
 
   // Pattern: "{field} is not empty" / "{field} is required"
@@ -143,31 +173,22 @@ function matchPreconditionPattern(
     const fieldMatch = precondition.match(/^(\w+)\s+is/i);
     if (fieldMatch) {
       const field = fieldMatch[1];
-      return `    // Guard: ${precondition}
-    if (!params.${field}) {
-      throw new Error('Precondition failed: ${precondition}');
-    }`;
+      const paramRef = params.includes(field) ? field : `params.${field}`;
+      return `    if (!${paramRef}) throw new Error('${field} is required');`;
     }
   }
 
   // Pattern: "{field} is valid"
   if (pc.includes('is valid')) {
-    return `    // Guard: ${precondition}
-    const validation = this.validate(params, { operation: '${context.operationName}' });
-    if (!validation.valid) {
-      throw new Error('Precondition failed: ${precondition} — ' + validation.errors.join(', '));
-    }`;
+    return `    // TODO: Implement validation: ${precondition}`;
   }
 
   // Pattern: "{X} matches {Y}" / "{X} equals {Y}"
   const matchesMatch = precondition.match(/^(\w+)\s+(?:matches|equals)\s+(.+)/i);
   if (matchesMatch) {
-    const left = matchesMatch[1];
-    const right = matchesMatch[2];
-    return `    // Guard: ${precondition}
-    if (params.${left.charAt(0).toLowerCase() + left.slice(1)} !== params.${right.charAt(0).toLowerCase() + right.slice(1)}) {
-      throw new Error('Precondition failed: ${precondition}');
-    }`;
+    const left = matchesMatch[1].charAt(0).toLowerCase() + matchesMatch[1].slice(1);
+    const right = matchesMatch[2].charAt(0).toLowerCase() + matchesMatch[2].slice(1);
+    return `    if (${left} !== ${right}) throw new Error('${matchesMatch[1]} must match ${matchesMatch[2]}');`;
   }
 
   // Pattern: "{Model} is {state}"
@@ -176,16 +197,19 @@ function matchPreconditionPattern(
     const model = stateMatch[1];
     const state = stateMatch[2];
     const modelVar = model.charAt(0).toLowerCase() + model.slice(1);
-    return `    // Guard: ${precondition}
-    const ${modelVar}State = await prisma.${modelVar}.findUniqueOrThrow({ where: { id: params.id } });
-    if (${modelVar}State.status !== '${state}') {
-      throw new Error('Precondition failed: ${precondition} (current: ' + ${modelVar}State.status + ')');
-    }`;
+    const idParam = findIdParam(model, params);
+
+    // If already declared, reuse; otherwise fetch
+    if (!declared.has(modelVar)) {
+      declared.add(modelVar);
+      return `    const ${modelVar} = await prisma.${modelVar}.findUniqueOrThrow({ where: { id: ${idParam} } });
+    if (${modelVar}.status !== '${state}') throw new Error('${model} must be ${state}, got ' + ${modelVar}.status);`;
+    }
+    return `    if (${modelVar}.status !== '${state}') throw new Error('${model} must be ${state}, got ' + ${modelVar}.status);`;
   }
 
   // Unrecognized
-  return `    // Guard: ${precondition}
-    // TODO: Implement precondition check`;
+  return `    // TODO: Implement precondition: ${precondition}`;
 }
 
 /**
@@ -193,9 +217,14 @@ function matchPreconditionPattern(
  */
 function generateStepLogic(
   steps: string[],
-  context: BehaviorContext
-): { code: string; helpers: string[] } {
+  context: BehaviorContext,
+  preconditionDeclared?: Set<string>
+): { code: string; helpers: string[]; unmatchedSteps: Array<{ step: string; functionName: string; operationName: string; inputs: string[] }> } {
   const helpers: string[] = [];
+  const unmatchedSteps: Array<{ step: string; functionName: string; operationName: string; inputs: string[] }> = [];
+
+  // Shared declared variables across steps — carried through from preconditions
+  const declaredVars = preconditionDeclared || new Set<string>();
 
   if (steps && steps.length > 0) {
     const stepCode = steps.map((step, i) => {
@@ -209,18 +238,29 @@ function generateStepLogic(
         serviceName: context.serviceName,
         operationName: context.operationName,
         stepNum: i + 1,
+        parameterNames: context.parameterNames,
+        declaredVars,
       };
 
       const result = matchStep(step, ctx);
       if (result.helperMethod) {
         helpers.push(result.helperMethod);
       }
+      if (!result.matched && result.functionName) {
+        unmatchedSteps.push({
+          step,
+          functionName: result.functionName,
+          operationName: context.operationName,
+          inputs: result.inputs || [],
+        });
+      }
       return result.call;
     });
 
     return {
       code: `    // === EXECUTE ===\n${stepCode.join('\n\n')}`,
       helpers,
+      unmatchedSteps,
     };
   }
 
@@ -228,6 +268,7 @@ function generateStepLogic(
   return {
     code: `    // === EXECUTE ===\n${inferLogicFromOperationName(context)}`,
     helpers,
+    unmatchedSteps,
   };
 }
 
@@ -280,12 +321,17 @@ ${checks.join('\n')}
  */
 export function generateEventPublishing(
   sideEffects: string[],
-  operationName: string
+  operationName: string,
+  parameterNames?: string[]
 ): string {
   if (!sideEffects || sideEffects.length === 0) return '';
 
+  const paramFields = parameterNames?.length
+    ? parameterNames.join(', ') + ', '
+    : '';
+
   const publishes = sideEffects.map(event =>
-    `    this.emit('${event}', { operation: '${operationName}', timestamp: new Date().toISOString() });`
+    `    await eventBus.publish('${event}', { ${paramFields}timestamp: new Date().toISOString() });`
   );
 
   return `    // === EVENTS ===\n${publishes.join('\n')}`;