@specverse/engines 4.1.13 → 4.1.15

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,48 @@ function generateHandlerBody(
   });
 }`;
 
-    default:
-      // For custom actions, generate a handler that calls the action method
+    default: {
+      // Custom action — validate body against declared parameters, then call handler
+      const params = endpoint?.parameters || {};
+      const paramNames = Object.keys(params);
+      const callArgs = paramNames.length > 0
+        ? paramNames.map(p => `body.${p}`).join(', ')
+        : 'body';
+
+      // Generate per-parameter validation checks
+      const validations: string[] = [];
+      for (const [pName, pDef] of Object.entries(params) as [string, any][]) {
+        const required = typeof pDef === 'string' ? pDef.includes('required') : pDef?.required;
+        const typeStr = typeof pDef === 'string' ? pDef.split(' ')[0] : pDef?.type || 'String';
+        if (required) {
+          validations.push(`  if (body.${pName} === undefined || body.${pName} === null) errors.push({ field: '${pName}', message: '${pName} is required' });`);
+        }
+        // Type checks
+        if (typeStr === 'UUID' || typeStr === 'String' || typeStr === 'Email') {
+          validations.push(`  if (body.${pName} !== undefined && typeof body.${pName} !== 'string') errors.push({ field: '${pName}', message: '${pName} must be a string' });`);
+        } else if (typeStr === 'Integer' || typeStr === 'Number' || typeStr === 'Float') {
+          validations.push(`  if (body.${pName} !== undefined && typeof body.${pName} !== 'number') errors.push({ field: '${pName}', message: '${pName} must be a number' });`);
+        } else if (typeStr === 'Boolean') {
+          validations.push(`  if (body.${pName} !== undefined && typeof body.${pName} !== 'boolean') errors.push({ field: '${pName}', message: '${pName} must be a boolean' });`);
+        }
+      }
+
+      const validationBlock = validations.length > 0
+        ? `  const errors: Array<{ field: string; message: string }> = [];\n${validations.join('\n')}\n  if (errors.length > 0) return reply.status(400).send({ error: 'Validation failed', details: errors });`
+        : '';
+
       return `try {
-  const result = await handler.${operation}(request.body as any);
-  return reply.send(result);
+  const body = (request.body || {}) as Record<string, any>;
+${validationBlock}
+  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 +370,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/scaffolding/templates/generic/tsconfig-generator.ts

@@ -9,12 +9,33 @@ import type { TemplateContext } from '@specverse/types';
 export default function generateTsConfig(context: TemplateContext): string {
   const { manifest, spec } = context;
 
+  // Detect layout: monorepo (default) vs standalone. In standalone layouts
+  // the scaffolding factory sets `outputStructure: standalone` + `backendDir: "."`
+  // so code lives in ./src directly. In monorepo layouts code lives under
+  // backend/src/ and frontend/src/, each with its own tsconfig, and the root
+  // tsconfig is just a solution-style stub so `tsc --noEmit` at the project
+  // root doesn't hit TS18003 ("no inputs").
+  const implementationTypes = (context as any).implementationTypes || [];
+  const isMonorepo = !implementationTypes.some((it: any) => {
+    const cfg = it?.configuration || it?.instanceFactory?.configuration || {};
+    return cfg.outputStructure === 'standalone';
+  });
+
+  if (isMonorepo) {
+    // In monorepo mode each workspace (backend/, frontend/) owns its own
+    // tsconfig. A root tsconfig is actively harmful: tsc --noEmit at the
+    // project root either trips TS18003 ("no inputs") on `include: ["src/**/*"]`
+    // or TS18002 ("empty files list") on `{"files": []}`. Return an empty
+    // string so the realize pipeline treats it as "skip this template".
+    return '';
+  }
+
   // Extract TypeScript options from implementation types
-  const mergedOptions = extractTsConfigOptions(context.implementationTypes || []);
+  const mergedOptions = extractTsConfigOptions(implementationTypes);
 
   // Detect if we're using React - check both implementation types AND if we have views in the spec
   const hasViews = spec && (spec.views || (Array.isArray(spec.views) && spec.views.length > 0));
-  const usesReact = hasViews && (context.implementationTypes || []).some((implType: any) =>
+  const usesReact = hasViews && implementationTypes.some((implType: any) =>
     implType.capabilities?.provides?.includes('ui.components') &&
     implType.technology?.framework === 'react'
   );

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

@@ -0,0 +1,376 @@
+/**
+ * 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';
+import { createHash } from 'crypto';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Validate generated TypeScript using esbuild's transform.
+ * Returns null if valid, or an error message describing the problem.
+ *
+ * This catches syntax errors (unbalanced braces, unclosed strings, etc.)
+ * but not type errors — those need full tsc which requires the project
+ * context. That's a separate validation step run by the realize pipeline.
+ */
+async function validateTypeScript(code: string): Promise<string | null> {
+  try {
+    const esbuild = await import('esbuild');
+    await esbuild.transform(code, {
+      loader: 'ts',
+      format: 'esm',
+      target: 'es2022',
+    });
+    return null;
+  } catch (err: any) {
+    const msg = err?.errors?.[0]?.text || err?.message || 'unknown syntax error';
+    return msg;
+  }
+}
+
+/**
+ * AI output cache — avoids re-calling Claude for unchanged steps.
+ *
+ * Cache key: sha256(step + modelName + operationName + inputs + promptVersion)
+ * Cache location: $SPECVERSE_USER_CWD/.specverse/ai-cache/<hash>.ts
+ *
+ * Invalidation: automatic — any change to the step text or inputs
+ * produces a new hash. The prompt version is part of the hash so
+ * prompt upgrades also invalidate.
+ */
+const PROMPT_VERSION = '9.1.0';
+
+function cacheKey(step: string, modelName: string, operationName: string, functionName: string, inputs: string[]): string {
+  const payload = JSON.stringify({ step, modelName, operationName, functionName, inputs: [...inputs].sort(), v: PROMPT_VERSION });
+  return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+
+function cacheDir(): string {
+  const cwd = process.env.SPECVERSE_USER_CWD || process.cwd();
+  return join(cwd, '.specverse', 'ai-cache');
+}
+
+function cacheRead(key: string): string | null {
+  const path = join(cacheDir(), `${key}.ts`);
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function cacheWrite(key: string, body: string): void {
+  const dir = cacheDir();
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, `${key}.ts`), body, 'utf8');
+  } catch (err: any) {
+    console.warn(`      [ai-cache] write failed: ${err?.message || err}`);
+  }
+}
+
+/**
+ * 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[];
+    returns?: Record<string, string> | 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 stepInput = steps[i];
+      // Support both string steps and object steps { step, as, returns }
+      const stepText = typeof stepInput === 'string' ? stepInput : stepInput?.step;
+      const stepAs = typeof stepInput === 'object' ? stepInput?.as : undefined;
+      const stepReturns = typeof stepInput === 'object' ? stepInput?.returns : undefined;
+
+      if (typeof stepText !== 'string') continue;
+
+      const ctx: StepContext = {
+        modelName,
+        prismaModel: modelVar,
+        serviceName: `${modelName}Controller`,
+        operationName: actionName,
+        stepNum: i + 1,
+        parameterNames,
+        declaredVars,
+        resultName: stepAs,
+      };
+
+      const result = matchStep(stepText, ctx);
+      if (!result.matched && result.functionName) {
+        // Avoid duplicate function definitions
+        const existing = unmatchedFunctions.find(f => f.functionName === result.functionName);
+        if (!existing) {
+          unmatchedFunctions.push({
+            functionName: result.functionName,
+            step: stepText,
+            operationName: actionName,
+            parameterNames,
+            inputs: result.inputs || [],
+            returns: stepReturns,
+          });
+        }
+      }
+    }
+  }
+
+  if (unmatchedFunctions.length === 0) return '';
+
+  return generateAiBehaviorsFile({
+    ownerName: `${modelName}Controller`,
+    unmatchedFunctions: unmatchedFunctions.map(f => ({
+      ...f,
+      modelName,
+    })),
+    availableModels,
+    spec: context.spec,
+  });
+}
+
+/**
+ * Generate an AI behaviors file from a pre-collected list of unmatched
+ * functions. Used by both the controller generator (via generateAiBehaviors
+ * above) and the service generator (via collectUnmatched → this function).
+ */
+export async function generateAiBehaviorsFile(opts: {
+  ownerName: string;
+  unmatchedFunctions: Array<{
+    functionName: string;
+    step: string;
+    operationName: string;
+    parameterNames: string[];
+    inputs: string[];
+    returns?: Record<string, string> | string;
+    modelName: string;
+  }>;
+  availableModels: string[];
+  spec?: any;
+}): Promise<string> {
+  const { ownerName, unmatchedFunctions, availableModels, spec } = opts;
+  if (unmatchedFunctions.length === 0) return '';
+
+  // Start a Claude session for this owner — 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(ownerName);
+    }
+  } catch {
+    aiService = null;
+  }
+
+  // Generate function bodies sequentially — same Claude session for all
+  const functions: string[] = [];
+  let cacheHits = 0;
+  let cacheMisses = 0;
+  for (const { functionName, step, operationName, parameterNames, inputs, returns, modelName } 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;`
+      : '';
+
+    // Build return type from spec declaration (if provided)
+    // returns can be:
+    //   - a string: "number" → Promise<number>
+    //   - an object: { amount: "number", rate: "number" } → Promise<{ amount: number; rate: number }>
+    //   - undefined → Promise<any>
+    let returnType = 'any';
+    if (typeof returns === 'string') {
+      returnType = returns;
+    } else if (returns && typeof returns === 'object') {
+      const fields = Object.entries(returns).map(([k, v]) => `${k}: ${v}`).join('; ');
+      returnType = `{ ${fields} }`;
+    }
+
+    // Check cache first — skip Claude if we've generated this exact step before
+    const key = cacheKey(step, modelName, operationName, functionName, inputs);
+    let body: string | null = cacheRead(key);
+    let source: 'AI-CACHED' | 'AI-GENERATED' | 'AI-INVALID' | 'STUB' = body ? 'AI-CACHED' : 'STUB';
+    if (body) {
+      // Validate cache entry — a previously valid entry may have been
+      // corrupted on disk or the validator rules may have changed
+      const testCode = `export async function ${functionName}(input: any): Promise<any> {\n${body}\n}`;
+      const validationError = await validateTypeScript(testCode);
+      if (validationError) {
+        console.warn(`      [ai-validate] cached ${functionName} failed validation: ${validationError}`);
+        body = null;  // Force regeneration
+        source = 'STUB';
+      } else {
+        cacheHits++;
+      }
+    }
+
+    if (!body && aiService) {
+      cacheMisses++;
+      try {
+        body = await aiService.generateBehavior({
+          step,
+          modelName,
+          operationName,
+          functionName,
+          parameterNames: inputs,  // the actual inputs to the pure function
+          availableModels,
+          spec,
+          returnType,  // Pass declared return type to Claude
+        });
+
+        if (body) {
+          // Validate the generated body as a standalone function
+          const testCode = `export async function ${functionName}(input: any): Promise<any> {\n${body}\n}`;
+          const validationError = await validateTypeScript(testCode);
+          if (validationError) {
+            console.warn(`      [ai-validate] ${functionName} has syntax error: ${validationError}`);
+            // Don't cache invalid output; treat as failed generation
+            body = `// AI-generated code failed validation: ${validationError}\n  // Step: ${step}\n  throw new Error('AI behavior has invalid syntax — see comment above');`;
+            source = 'AI-INVALID';
+          } else {
+            source = 'AI-GENERATED';
+            cacheWrite(key, body);
+          }
+        }
+      } 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`
+      : '';
+    const returnsDoc = returnType !== 'any'
+      ? ` * Returns: ${returnType}\n`
+      : '';
+
+    functions.push(`/**
+ * ${functionName}
+ *
+ * Spec step: "${step}"
+ * Called by: ${ownerName}.${operationName}()
+${inputsDoc}${returnsDoc} * 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.'
+   : source === 'AI-CACHED'
+   ? 'Restored from AI cache (.specverse/ai-cache/). Delete cache entry to regenerate.'
+   : source === 'AI-INVALID'
+   ? 'AI returned code with syntax errors — function throws at runtime. Fix or regenerate.'
+   : 'STUB — Claude CLI unavailable. Install Claude Code or implement manually.'}
+ */
+export async function ${functionName}(${signature}): Promise<${returnType}> {
+${destructure ? destructure + '\n' : ''}${body}
+}`);
+  }
+
+  // End the session
+  if (aiService?.endSession) aiService.endSession();
+
+  // Report cache stats to stdout — picked up by realize pipeline
+  if (cacheHits > 0 || cacheMisses > 0) {
+    console.log(`      AI cache: ${cacheHits} hit(s), ${cacheMisses} miss(es) for ${ownerName}`);
+  }
+
+  return `/**
+ * ${ownerName} — 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 ${ownerName} when executing operations.
+ *
+ * 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')}
+`;
+}