@specverse/engines 4.1.13 → 4.1.14

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

@@ -7,6 +7,7 @@
 
 import type { TemplateContext } from '@specverse/types';
 import { buildTransitionMap, isAutoField } from '@specverse/types/spec-rules';
+import { generateBehaviorWithHelpers, type BehaviorContext, type BehaviorMetadata } from './behavior-generator.js';
 
 /**
  * Generate Prisma controller for a model
@@ -36,6 +37,9 @@ export default function generatePrismaController(context: TemplateContext): stri
   const idType = idAttr?.type || 'UUID';
   const needsIntParse = idType === 'Integer' || idType === 'Int' || idType === 'Number';
 
+  // Generate custom actions and collect AI behavior stubs
+  const customActions = generateCustomActions(controller, modelName, modelVar);
+
   return `/**
  * ${controllerName}
  * Model-specific business logic for ${modelName}
@@ -43,7 +47,8 @@ export default function generatePrismaController(context: TemplateContext): stri
  */
 
 import { PrismaClient } from '@prisma/client';
-${hasEventPublishing(curedOps, controller) ? `import { eventBus, EventName } from '../events/eventBus.js';` : ''}
+${hasEventPublishing(curedOps, controller) ? `import { eventBus } from '../events/eventBus.js';` : ''}
+${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${modelName}Controller.ai.js';` : ''}
 
 const prisma = new PrismaClient();
 
@@ -62,13 +67,14 @@ export class ${controllerName} {
   ${curedOps.update ? generateUpdateMethod(model, modelName, modelVar, controller, allModels) : ''}
   ${curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, controller) : ''}
   ${curedOps.delete ? generateDeleteMethod(model, modelName, modelVar, controller) : ''}
-  ${generateCustomActions(controller, modelName, modelVar)}
+  ${customActions.code}
 }
 
 // Export singleton instance
 export const ${modelVar}Controller = new ${controllerName}();
 export default ${modelVar}Controller;
 `;
+
 }
 
 /**
@@ -368,26 +374,59 @@ function generateDeleteMethod(model: any, modelName: string, modelVar: string, c
 /**
  * Generate custom actions defined in controller
  */
-function generateCustomActions(controller: any, modelName: string, modelVar: string): string {
+interface CustomActionsResult {
+  code: string;
+  unmatchedSteps: Array<{ step: string; functionName: string; operationName: string }>;
+  needsAiBehaviors: boolean;
+}
+
+function generateCustomActions(controller: any, modelName: string, modelVar: string): CustomActionsResult {
   if (!controller.actions || Object.keys(controller.actions).length === 0) {
-    return '';
+    return { code: '', unmatchedSteps: [], needsAiBehaviors: false };
   }
 
   const actions: string[] = [];
+  const allUnmatchedSteps: Array<{ step: string; functionName: string; operationName: string }> = [];
 
   Object.entries(controller.actions).forEach(([actionName, action]: [string, any]) => {
+    const behavior: BehaviorMetadata = {
+      preconditions: action.requires || action.preconditions || [],
+      steps: action.steps || [],
+      postconditions: action.ensures || action.postconditions || [],
+      sideEffects: action.publishes || action.events || [],
+      transactional: action.transactional,
+    };
+
+    const ctx: BehaviorContext = {
+      modelName,
+      serviceName: `${modelName}Controller`,
+      operationName: actionName,
+      prismaModel: modelVar,
+      parameterNames: Object.keys(action.parameters || {}),
+    };
+
+    const result = generateBehaviorWithHelpers(behavior, {}, ctx);
+    allUnmatchedSteps.push(...result.unmatchedSteps);
+
     actions.push(`
   /**
    * ${actionName}
    * ${action.description || ''}
    */
   public async ${actionName}(${generateActionParams(action)}): Promise<any> {
-    // TODO: Implement ${actionName} logic
-    throw new Error('${actionName} not implemented');
+${result.body}
   }`);
+
+    if (result.helperMethods.length > 0) {
+      actions.push(...result.helperMethods);
+    }
   });
 
-  return actions.join('\n');
+  return {
+    code: actions.join('\n'),
+    unmatchedSteps: allUnmatchedSteps,
+    needsAiBehaviors: allUnmatchedSteps.length > 0,
+  };
 }
 
 /**
@@ -509,5 +548,12 @@ ${includes}
  * Check if controller publishes events
  */
 function hasEventPublishing(curedOps: any, controller: any): boolean {
-  return controller.publishes && Array.isArray(controller.publishes) && controller.publishes.length > 0;
+  if (controller.publishes && Array.isArray(controller.publishes) && controller.publishes.length > 0) return true;
+  // Check if any custom action publishes events
+  if (controller.actions) {
+    for (const action of Object.values(controller.actions) as any[]) {
+      if (action.publishes?.length > 0 || action.events?.length > 0 || action.sideEffects?.length > 0) return true;
+    }
+  }
+  return false;
 }

package/libs/instance-factories/services/templates/prisma/step-conventions.ts

@@ -18,6 +18,10 @@ export interface StepContext {
   serviceName: string;
   operationName: string;
   stepNum: number;
+  /** Parameter names from the action (e.g., ['pollId', 'optionId']) */
+  parameterNames?: string[];
+  /** Variables already declared (to avoid redeclaration) */
+  declaredVars?: Set<string>;
 }
 
 function toVar(name: string): string {
@@ -28,15 +32,81 @@ function toMethod(words: string): string {
   return words.trim().replace(/\s+(.)/g, (_, c) => c.toUpperCase()).replace(/^\w/, c => c.toLowerCase());
 }
 
+/**
+ * Resolve a value expression in a step to a TypeScript expression.
+ *
+ * Handles:
+ * - "current time", "now", "timestamp" → new Date().toISOString()
+ * - References to declared variables (e.g., "discount.amount") → discount.amount
+ * - References to operation parameters → parameter name
+ * - References to stepNResult → stepNResult
+ * - Numbers → numeric literal
+ * - Boolean literals → true/false
+ * - Everything else → quoted string literal
+ */
+function resolveValue(rawValue: string, ctx: StepContext): string {
+  const value = rawValue.trim().replace(/^['"]|['"]$/g, '');
+
+  // Time expressions
+  if (/^(current\s*time|now|timestamp)$/i.test(value)) {
+    return 'new Date().toISOString()';
+  }
+
+  // Boolean literals
+  if (value === 'true' || value === 'false') return value;
+
+  // Numeric literal
+  if (/^-?\d+(\.\d+)?$/.test(value)) return value;
+
+  const declared = ctx.declaredVars || new Set();
+  const params = ctx.parameterNames || [];
+
+  // Reference: "varName" or "varName.field" — check if root matches a declared var or parameter
+  const rootMatch = value.match(/^([a-zA-Z_][a-zA-Z0-9_]*)(\.[a-zA-Z0-9_.]+)?$/);
+  if (rootMatch) {
+    const root = rootMatch[1];
+    if (declared.has(root) || params.includes(root)) {
+      return value;  // use as-is (e.g., "discount.amount")
+    }
+  }
+
+  // Natural language reference: "calculated amount", "the discount" etc.
+  // Try to match to a declared var by tokenising
+  const tokens = value.toLowerCase().split(/\s+/);
+  for (const declaredName of [...declared, ...params]) {
+    const normalized = declaredName.toLowerCase();
+    if (tokens.includes(normalized)) return declaredName;
+  }
+
+  // "calculated X" / "computed X" / "the X" — look for a stepNResult with
+  // matching field. Since we don't know the AI function's return shape at
+  // compile time, emit a typed access with a TODO comment the developer can fix.
+  const calcMatch = value.match(/^(?:the\s+|calculated\s+|computed\s+|resulting\s+)(\w+)/i);
+  if (calcMatch) {
+    const field = calcMatch[1];
+    // Find most recent stepNResult
+    const stepResults = [...declared].filter(v => /^step\d+Result$/.test(v)).sort().reverse();
+    if (stepResults.length > 0) {
+      return `(${stepResults[0]} as any).${field} /* TODO: verify field name */`;
+    }
+  }
+
+  // Looks like natural language (multiple words with spaces) — emit TODO
+  if (/\s/.test(value)) {
+    return `/* TODO: resolve "${value}" — no matching declared variable */ null`;
+  }
+
+  // Fallback: quoted string literal
+  return `'${value.replace(/'/g, "\\'")}'`;
+}
+
 export const STEP_CONVENTIONS: StepConvention[] = [
   // --- Validation ---
   {
     name: 'validate',
     pattern: /^validate\s+(.+)/i,
     generateCall: (m, ctx) => `    // Step ${ctx.stepNum}: Validate ${m[1]}
-    const validationResult = this.validate(params, { operation: '${ctx.operationName}' });
-    if (!validationResult.valid) {
-      throw new Error(\`Validation failed: \${validationResult.errors.join(', ')}\`);
+    // TODO: Add validation logic for ${m[1]}
     }`,
   },
 
@@ -48,21 +118,9 @@ export const STEP_CONVENTIONS: StepConvention[] = [
       const condition = m[1];
       const methodName = toMethod('check ' + condition);
       return `    // Step ${ctx.stepNum}: Check ${condition}
-    const checkResult = await this.${methodName}(params);
-    if (!checkResult) {
-      throw new Error('Check failed: ${condition}');
-    }`;
-    },
-    generateMethod: (m, ctx) => {
-      const condition = m[1];
-      const methodName = toMethod('check ' + condition);
-      return `
-  private async ${methodName}(params: any): Promise<boolean> {
     // TODO: Implement check — ${condition}
-    const ${toVar(ctx.prismaModel)} = await this.prisma.${toVar(ctx.prismaModel)}.findUnique({ where: { id: params.id } });
-    if (!${toVar(ctx.prismaModel)}) return false;
-    return true;
-  }`;
+    // const checkResult = ...
+    // if (!checkResult) throw new Error('Check failed: ${condition}');`;
     },
   },
 
@@ -73,22 +131,40 @@ export const STEP_CONVENTIONS: StepConvention[] = [
     generateCall: (m, ctx) => {
       const model = m[1];
       const field = m[2];
+      const modelVar = toVar(model);
+      const params = ctx.parameterNames || [];
+      const declared = ctx.declaredVars || new Set();
+
+      // Find the ID parameter: modelId (e.g., pollId) or field directly
+      const idParam = field === 'id'
+        ? (params.find(p => p === `${modelVar}Id`) || params.find(p => p === 'id') || `${modelVar}Id`)
+        : (params.find(p => p === field) || `params.${field}`);
+
+      // Skip if already declared by precondition
+      if (declared.has(modelVar)) {
+        return `    // Step ${ctx.stepNum}: Find ${model} by ${field} (already loaded)`;
+      }
+      declared.add(modelVar);
+
       return `    // Step ${ctx.stepNum}: Find ${model} by ${field}
-    const ${toVar(model)} = await this.prisma.${toVar(model)}.findUnique({ where: { ${field}: params.${field} } });
-    if (!${toVar(model)}) {
-      throw new Error('${model} not found by ${field}');
-    }`;
+    const ${modelVar} = await prisma.${modelVar}.findUniqueOrThrow({ where: { ${field}: ${idParam} } });`;
     },
   },
 
   // --- Create ---
   {
     name: 'create',
-    pattern: /^create\s+(\w+)(?:\s+record)?/i,
+    pattern: /^create\s+(\w+)(?:\s+(?:with\s+)?(.+))?/i,
     generateCall: (m, ctx) => {
       const model = m[1];
+      const modelVar = toVar(model);
+      // Build data from parameter names if available
+      const paramNames = ctx.parameterNames || [];
+      const dataFields = paramNames.length > 0
+        ? `{ ${paramNames.join(', ')} }`
+        : 'data';
       return `    // Step ${ctx.stepNum}: Create ${model}
-    const ${toVar(model)} = await this.prisma.${toVar(model)}.create({ data: params });`;
+    const ${modelVar} = await prisma.${modelVar}.create({ data: ${dataFields} });`;
     },
   },
 
@@ -99,12 +175,12 @@ export const STEP_CONVENTIONS: StepConvention[] = [
     generateCall: (m, ctx) => {
       const model = m[1];
       const field = m[2];
-      const value = m[3].trim().replace(/"/g, "'");
-      const isString = /^[a-z]/.test(value) && !value.includes('.');
-      const val = isString ? `'${value}'` : value;
-      return `    // Step ${ctx.stepNum}: Update ${model} ${field} to ${value}
-    await this.prisma.${toVar(model)}.update({
-      where: { id: params.id },
+      const rawValue = m[3];
+      const modelVar = toVar(model);
+      const val = resolveValue(rawValue, ctx);
+      return `    // Step ${ctx.stepNum}: Update ${model} ${field} to ${rawValue.trim()}
+    await prisma.${modelVar}.update({
+      where: { id: ${modelVar}.id },
       data: { ${field}: ${val} },
     });`;
     },
@@ -116,9 +192,10 @@ export const STEP_CONVENTIONS: StepConvention[] = [
     pattern: /^update\s+(\w+)(?:\s+(.+))?/i,
     generateCall: (m, ctx) => {
       const model = m[1];
+      const modelVar = toVar(model);
       return `    // Step ${ctx.stepNum}: Update ${model}
-    await this.prisma.${toVar(model)}.update({
-      where: { id: params.id },
+    await prisma.${modelVar}.update({
+      where: { id: ${modelVar}.id },
       data: params,
     });`;
     },
@@ -130,8 +207,9 @@ export const STEP_CONVENTIONS: StepConvention[] = [
     pattern: /^delete\s+(\w+)/i,
     generateCall: (m, ctx) => {
       const model = m[1];
+      const modelVar = toVar(model);
       return `    // Step ${ctx.stepNum}: Delete ${model}
-    await this.prisma.${toVar(model)}.delete({ where: { id: params.id } });`;
+    await prisma.${modelVar}.delete({ where: { id: ${modelVar}.id } });`;
     },
   },
 
@@ -142,11 +220,11 @@ export const STEP_CONVENTIONS: StepConvention[] = [
     generateCall: (m, ctx) => {
       const model = m[1];
       const state = m[2];
+      const modelVar = toVar(model);
       return `    // Step ${ctx.stepNum}: Transition ${model} to ${state}
-    const current = await this.prisma.${toVar(model)}.findUniqueOrThrow({ where: { id: params.id } });
-    // Lifecycle validation would check valid transition here
-    await this.prisma.${toVar(model)}.update({
-      where: { id: params.id },
+    if (${modelVar}.status === '${state}') throw new Error('${model} is already ${state}');
+    await prisma.${modelVar}.update({
+      where: { id: ${modelVar}.id },
       data: { status: '${state}' },
     });`;
     },
@@ -158,12 +236,12 @@ export const STEP_CONVENTIONS: StepConvention[] = [
     pattern: /^set\s+(\w+)\s+to\s+(.+)/i,
     generateCall: (m, ctx) => {
       const field = m[1];
-      const value = m[2].trim();
-      const isCurrentTime = /current time|now|timestamp/i.test(value);
-      const val = isCurrentTime ? 'new Date()' : `'${value}'`;
-      return `    // Step ${ctx.stepNum}: Set ${field} to ${value}
-    await this.prisma.${toVar(ctx.prismaModel)}.update({
-      where: { id: params.id },
+      const rawValue = m[2];
+      const modelVar = toVar(ctx.prismaModel);
+      const val = resolveValue(rawValue, ctx);
+      return `    // Step ${ctx.stepNum}: Set ${field} to ${rawValue.trim()}
+    await prisma.${modelVar}.update({
+      where: { id: ${modelVar}.id },
       data: { ${field}: ${val} },
     });`;
     },
@@ -176,10 +254,11 @@ export const STEP_CONVENTIONS: StepConvention[] = [
     generateCall: (m, ctx) => {
       const field = m[1];
       const amount = m[2];
-      const amountVal = /^\d+$/.test(amount) ? amount : `params.${amount}`;
+      const modelVar = toVar(ctx.prismaModel);
+      const amountVal = /^\d+$/.test(amount) ? amount : amount;
       return `    // Step ${ctx.stepNum}: Increment ${field} by ${amount}
-    await this.prisma.${toVar(ctx.prismaModel)}.update({
-      where: { id: params.id },
+    await prisma.${modelVar}.update({
+      where: { id: ${modelVar}.id },
       data: { ${field}: { increment: ${amountVal} } },
     });`;
     },
@@ -192,39 +271,19 @@ export const STEP_CONVENTIONS: StepConvention[] = [
     generateCall: (m, ctx) => {
       const field = m[1];
       const amount = m[2];
-      const amountVal = /^\d+$/.test(amount) ? amount : `params.${amount}`;
+      const modelVar = toVar(ctx.prismaModel);
+      const amountVal = /^\d+$/.test(amount) ? amount : amount;
       return `    // Step ${ctx.stepNum}: Decrement ${field} by ${amount}
-    const current${field} = await this.prisma.${toVar(ctx.prismaModel)}.findUniqueOrThrow({ where: { id: params.id } });
-    if ((current${field}.${field} || 0) < ${amountVal}) {
-      throw new Error('Cannot decrement ${field} below zero');
-    }
-    await this.prisma.${toVar(ctx.prismaModel)}.update({
-      where: { id: params.id },
+    await prisma.${modelVar}.update({
+      where: { id: ${modelVar}.id },
       data: { ${field}: { decrement: ${amountVal} } },
     });`;
     },
   },
 
-  // --- Calculate ---
-  {
-    name: 'calculate',
-    pattern: /^calculate\s+(.+)/i,
-    generateCall: (m, ctx) => {
-      const metric = m[1];
-      const methodName = toMethod('calculate ' + metric);
-      return `    // Step ${ctx.stepNum}: Calculate ${metric}
-    const ${toVar(metric.replace(/\s+/g, ''))} = await this.${methodName}(params);`;
-    },
-    generateMethod: (m, ctx) => {
-      const metric = m[1];
-      const methodName = toMethod('calculate ' + metric);
-      return `
-  private async ${methodName}(params: any): Promise<number> {
-    // TODO: Implement calculation — ${metric}
-    return 0;
-  }`;
-    },
-  },
+  // NOTE: "calculate X" is intentionally NOT a convention — it falls through to AI
+  // behaviors because calculations are domain-specific pure functions that benefit
+  // from AI generation with the full input context.
 
   // --- Send event ---
   {
@@ -233,7 +292,7 @@ export const STEP_CONVENTIONS: StepConvention[] = [
     generateCall: (m, ctx) => {
       const event = m[1];
       return `    // Step ${ctx.stepNum}: Emit ${event} event
-    this.emit('${event}', { ${toVar(ctx.prismaModel)}Id: params.id, operation: '${ctx.operationName}', timestamp: new Date().toISOString() });`;
+    await eventBus.publish('${event}', { ${toVar(ctx.prismaModel)}Id: ${toVar(ctx.prismaModel)}.id, operation: '${ctx.operationName}', timestamp: new Date().toISOString() });`;
     },
   },
 
@@ -244,7 +303,7 @@ export const STEP_CONVENTIONS: StepConvention[] = [
     generateCall: (m, ctx) => {
       const type = m[1];
       return `    // Step ${ctx.stepNum}: Send ${type} notification
-    this.emit('${type}Notification', { ${toVar(ctx.prismaModel)}Id: params.id, operation: '${ctx.operationName}' });`;
+    await eventBus.publish('${type}Notification', { ${toVar(ctx.prismaModel)}Id: ${toVar(ctx.prismaModel)}.id, operation: '${ctx.operationName}' });`;
     },
   },
 
@@ -256,7 +315,7 @@ export const STEP_CONVENTIONS: StepConvention[] = [
       const service = m[1];
       const method = m[2];
       return `    // Step ${ctx.stepNum}: Call ${service}.${method}
-    await this.${toVar(service)}.${method}(params);`;
+    await ${toVar(service)}.${method}({ ${(ctx.parameterNames || []).join(', ')} });`;
     },
   },
 
@@ -280,30 +339,52 @@ export const STEP_CONVENTIONS: StepConvention[] = [
 /**
  * Match a step string against all conventions. Returns the generated call
  * code and optionally a helper method to add to the class.
+ *
+ * For unmatched steps, the call is wired to a pure AI function that takes
+ * all currently-declared variables as a typed input object and returns
+ * a result that subsequent steps can use.
  */
 export function matchStep(
   step: string,
   ctx: StepContext
-): { call: string; helperMethod?: string } {
+): {
+  call: string;
+  helperMethod?: string;
+  matched: boolean;
+  functionName?: string;
+  inputs?: string[];
+  resultVar?: string;
+} {
   for (const convention of STEP_CONVENTIONS) {
     const match = step.match(convention.pattern);
     if (match) {
       return {
         call: convention.generateCall(match, ctx),
         helperMethod: convention.generateMethod?.(match, ctx),
+        matched: true,
       };
     }
   }
 
-  // No match — generate stub method
-  const methodName = toMethod(step);
+  // No match — pure AI function call
+  // Inputs = all variables declared by previous steps + operation parameters
+  const functionName = toMethod(step);
+  const declared = Array.from(ctx.declaredVars || []);
+  const paramNames = ctx.parameterNames || [];
+  const inputs = [...paramNames, ...declared];
+
+  const resultVar = `step${ctx.stepNum}Result`;
+  const inputObj = inputs.length > 0 ? `{ ${inputs.join(', ')} }` : '{}';
+
+  // Register the result variable so subsequent steps can reference it
+  if (ctx.declaredVars) ctx.declaredVars.add(resultVar);
+
   return {
-    call: `    // Step ${ctx.stepNum}: ${step}
-    await this.${methodName}(params);`,
-    helperMethod: `
-  private async ${methodName}(params: any): Promise<void> {
-    // TODO: Implement — ${step}
-    throw new Error('Not implemented: ${methodName}');
-  }`,
+    call: `    // Step ${ctx.stepNum}: ${step} [AI-generated — pure function]
+    const ${resultVar} = await aiBehaviors.${functionName}(${inputObj});`,
+    matched: false,
+    functionName,
+    inputs,
+    resultVar,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "4.1.13",
+  "version": "4.1.14",
   "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry",
   "type": "module",
   "main": "dist/index.js",