@specverse/engines 4.1.13 → 4.1.15

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

@@ -0,0 +1,249 @@
+import { matchStep } from "./step-conventions.js";
+import { createHash } from "crypto";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+async function validateTypeScript(code) {
+  try {
+    const esbuild = await import("esbuild");
+    await esbuild.transform(code, {
+      loader: "ts",
+      format: "esm",
+      target: "es2022"
+    });
+    return null;
+  } catch (err) {
+    const msg = err?.errors?.[0]?.text || err?.message || "unknown syntax error";
+    return msg;
+  }
+}
+const PROMPT_VERSION = "9.1.0";
+function cacheKey(step, modelName, operationName, functionName, inputs) {
+  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() {
+  const cwd = process.env.SPECVERSE_USER_CWD || process.cwd();
+  return join(cwd, ".specverse", "ai-cache");
+}
+function cacheRead(key) {
+  const path = join(cacheDir(), `${key}.ts`);
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function cacheWrite(key, body) {
+  const dir = cacheDir();
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, `${key}.ts`), body, "utf8");
+  } catch (err) {
+    console.warn(`      [ai-cache] write failed: ${err?.message || err}`);
+  }
+}
+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 stepInput = steps[i];
+      const stepText = typeof stepInput === "string" ? stepInput : stepInput?.step;
+      const stepAs = typeof stepInput === "object" ? stepInput?.as : void 0;
+      const stepReturns = typeof stepInput === "object" ? stepInput?.returns : void 0;
+      if (typeof stepText !== "string") continue;
+      const ctx = {
+        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) {
+        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
+  });
+}
+async function generateAiBehaviorsFile(opts) {
+  const { ownerName, unmatchedFunctions, availableModels: availableModels2, spec } = opts;
+  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(ownerName);
+    }
+  } catch {
+    aiService = null;
+  }
+  const functions = [];
+  let cacheHits = 0;
+  let cacheMisses = 0;
+  for (const { functionName, step, operationName, parameterNames, inputs, returns, modelName } 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 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} }`;
+    }
+    const key = cacheKey(step, modelName, operationName, functionName, inputs);
+    let body = cacheRead(key);
+    let source = body ? "AI-CACHED" : "STUB";
+    if (body) {
+      const testCode = `export async function ${functionName}(input: any): Promise<any> {
+${body}
+}`;
+      const validationError = await validateTypeScript(testCode);
+      if (validationError) {
+        console.warn(`      [ai-validate] cached ${functionName} failed validation: ${validationError}`);
+        body = null;
+        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: availableModels2,
+          spec,
+          returnType
+          // Pass declared return type to Claude
+        });
+        if (body) {
+          const testCode = `export async function ${functionName}(input: any): Promise<any> {
+${body}
+}`;
+          const validationError = await validateTypeScript(testCode);
+          if (validationError) {
+            console.warn(`      [ai-validate] ${functionName} has syntax error: ${validationError}`);
+            body = `// AI-generated code failed validation: ${validationError}
+  // Step: ${step}
+  throw new Error('AI behavior has invalid syntax \u2014 see comment above');`;
+            source = "AI-INVALID";
+          } else {
+            source = "AI-GENERATED";
+            cacheWrite(key, body);
+          }
+        }
+      } 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(", ")}
+` : "";
+    const returnsDoc = returnType !== "any" ? ` * Returns: ${returnType}
+` : "";
+    functions.push(`/**
+ * ${functionName}
+ *
+ * Spec step: "${step}"
+ * Called by: ${ownerName}.${operationName}()
+${inputsDoc}${returnsDoc} * 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." : source === "AI-CACHED" ? "Restored from AI cache (.specverse/ai-cache/). Delete cache entry to regenerate." : source === "AI-INVALID" ? "AI returned code with syntax errors \u2014 function throws at runtime. Fix or regenerate." : "STUB \u2014 Claude CLI unavailable. Install Claude Code or implement manually."}
+ */
+export async function ${functionName}(${signature}): Promise<${returnType}> {
+${destructure ? destructure + "\n" : ""}${body}
+}`);
+  }
+  if (aiService?.endSession) aiService.endSession();
+  if (cacheHits > 0 || cacheMisses > 0) {
+    console.log(`      AI cache: ${cacheHits} hit(s), ${cacheMisses} miss(es) for ${ownerName}`);
+  }
+  return `/**
+ * ${ownerName} \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 ${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}" \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,
+  generateAiBehaviorsFile
+};

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

@@ -6,14 +6,17 @@ function generateBehaviorBody(behavior, opMeta, context) {
 function generateBehaviorWithHelpers(behavior, opMeta, context) {
   const parts = [];
   const helperMethods = [];
+  const preconditionDeclared = /* @__PURE__ */ new Set();
   const preconditions = generatePreconditionChecks(
     behavior.preconditions || [],
-    context
+    context,
+    preconditionDeclared
   );
   if (preconditions) parts.push(preconditions);
-  const { code, helpers } = generateStepLogic(
+  const { code, helpers, unmatchedSteps } = generateStepLogic(
     behavior.steps || [],
-    context
+    context,
+    preconditionDeclared
   );
   parts.push(code);
   helperMethods.push(...helpers);
@@ -23,79 +26,86 @@ function generateBehaviorWithHelpers(behavior, opMeta, context) {
   if (postconditions) parts.push(postconditions);
   const events = generateEventPublishing(
     behavior.sideEffects || [],
-    context.operationName
+    context.operationName,
+    context.parameterNames
   );
   if (events) parts.push(events);
   let body = parts.join("\n\n");
   if (behavior.transactional) {
     body = generateTransactionWrapper(body, context);
   }
-  return { body, helperMethods };
+  return { body, helperMethods, unmatchedSteps };
 }
-function generatePreconditionChecks(preconditions, context) {
+function generatePreconditionChecks(preconditions, context, declared) {
   if (preconditions.length === 0) return "";
-  const checks = preconditions.map((pc) => matchPreconditionPattern(pc, context));
+  if (!declared) declared = /* @__PURE__ */ new Set();
+  const checks = preconditions.map((pc) => matchPreconditionPattern(pc, context, declared));
   return `    // === PRECONDITIONS ===
 ${checks.join("\n")}`;
 }
-function matchPreconditionPattern(precondition, context) {
+function findIdParam(modelName, paramNames) {
+  const modelVar = modelName.charAt(0).toLowerCase() + modelName.slice(1);
+  const idParam = paramNames.find((p) => p === `${modelVar}Id`);
+  if (idParam) return idParam;
+  if (paramNames.includes("id")) return "id";
+  return `${modelVar}Id`;
+}
+function matchPreconditionPattern(precondition, context, declared) {
   const pc = precondition.toLowerCase();
-  const prismaModel = context.prismaModel || context.modelName;
+  const params = context.parameterNames || [];
   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)) {
+      return `    // Guard: ${precondition} (already fetched)`;
+    }
+    declared.add(entityVar);
+    return `    const ${entityVar} = await prisma.${entityVar}.findUniqueOrThrow({ where: { id: ${idParam} } });`;
   }
   if (pc.includes("is not empty") || pc.includes("is required")) {
     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');`;
     }
   }
   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} \u2014 ' + validation.errors.join(', '));
-    }`;
+    return `    // TODO: Implement validation: ${precondition}`;
   }
   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]}');`;
   }
   const stateMatch = precondition.match(/^(\w+)\s+is\s+(\w+)$/i);
   if (stateMatch) {
     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 (!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);`;
   }
-  return `    // Guard: ${precondition}
-    // TODO: Implement precondition check`;
+  return `    // TODO: Implement precondition: ${precondition}`;
 }
-function generateStepLogic(steps, context) {
+function generateStepLogic(steps, context, preconditionDeclared) {
   const helpers = [];
+  const unmatchedSteps = [];
+  const declaredVars = preconditionDeclared || /* @__PURE__ */ new Set();
   if (steps && steps.length > 0) {
-    const stepCode = steps.map((step, i) => {
-      if (typeof step !== "string") {
+    const stepCode = steps.map((stepInput, i) => {
+      const stepText = typeof stepInput === "string" ? stepInput : stepInput.step;
+      const resultName = typeof stepInput === "object" ? stepInput.as : void 0;
+      const returns = typeof stepInput === "object" ? stepInput.returns : void 0;
+      if (typeof stepText !== "string") {
         return `    // Step ${i + 1}: Complex operation \u2014 see expanded definition`;
       }
       const ctx = {
@@ -103,24 +113,40 @@ function generateStepLogic(steps, context) {
         prismaModel: context.prismaModel || context.modelName,
         serviceName: context.serviceName,
         operationName: context.operationName,
-        stepNum: i + 1
+        stepNum: i + 1,
+        parameterNames: context.parameterNames,
+        declaredVars,
+        resultName
+        // Pass through the named result
       };
-      const result = matchStep(step, ctx);
+      const result = matchStep(stepText, ctx);
       if (result.helperMethod) {
         helpers.push(result.helperMethod);
       }
+      if (!result.matched && result.functionName) {
+        unmatchedSteps.push({
+          step: stepText,
+          functionName: result.functionName,
+          operationName: context.operationName,
+          inputs: result.inputs || [],
+          returns,
+          resultName: resultName || `step${i + 1}Result`
+        });
+      }
       return result.call;
     });
     return {
       code: `    // === EXECUTE ===
 ${stepCode.join("\n\n")}`,
-      helpers
+      helpers,
+      unmatchedSteps
     };
   }
   return {
     code: `    // === EXECUTE ===
 ${inferLogicFromOperationName(context)}`,
-    helpers
+    helpers,
+    unmatchedSteps
   };
 }
 function inferLogicFromOperationName(context) {
@@ -154,10 +180,11 @@ function generatePostconditionVerification(postconditions) {
 ${checks.join("\n")}
     }`;
 }
-function generateEventPublishing(sideEffects, operationName) {
+function generateEventPublishing(sideEffects, operationName, parameterNames) {
   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() });`
+    (event) => `    await eventBus.publish('${event}', { ${paramFields}timestamp: new Date().toISOString() } as any);`
   );
   return `    // === EVENTS ===
 ${publishes.join("\n")}`;