@specverse/engines 6.6.3 → 6.11.2

package/libs/instance-factories/applications/templates/generic/backend-package-json-generator.ts

@@ -1,15 +1,56 @@
 /**
  * Backend Package.json Generator
  *
- * Generates package.json for backend workspace in monorepo
+ * Generates package.json for backend workspace in monorepo. Adapts deps +
+ * scripts to the manifest's resolved ORM/storage so a manifest pinning
+ * MongoDBNativeDriver doesn't get stuck with Prisma scripts and
+ * `@prisma/client` in dependencies.
  */
 
 import type { TemplateContext } from '@specverse/types';
 
-export default function generateBackendPackageJson(context: TemplateContext): string {
-  const { spec } = context;
+/** Read the manifest's resolved orm name (e.g. "PrismaORM", "MongoDBNativeDriver"). */
+function resolveOrmName(manifest: any): string {
+  if (!manifest) return 'PrismaORM';
+  const inner = manifest.manifests
+    ? Object.values(manifest.manifests)[0] as any
+    : manifest;
+  if (!inner) return 'PrismaORM';
+  // Prefer explicit capabilityMappings for orm.client; fall back to defaultMappings.orm.
+  const caps = Array.isArray(inner.capabilityMappings) ? inner.capabilityMappings : [];
+  const ormCap = caps.find((m: any) => m?.capability === 'orm.client') ||
+                 caps.find((m: any) => m?.capability === 'orm.schema');
+  if (ormCap) return ormCap.implementation || ormCap.instanceFactory || 'PrismaORM';
+  return inner.defaultMappings?.orm || 'PrismaORM';
+}
 
+export default function generateBackendPackageJson(context: TemplateContext): string {
+  const { spec, manifest } = context as any;
   const appName = (spec.metadata?.component || 'app').toLowerCase().replace(/\s+/g, '-');
+  const orm = resolveOrmName(manifest);
+  const isMongoNative = orm === 'MongoDBNativeDriver';
+
+  // Database scripts are ORM-specific. Prisma has db:setup/generate/push;
+  // MongoDB native has nothing to generate (collections are dynamic), so
+  // we drop those scripts entirely rather than emit no-op placeholders.
+  const dbScripts: Record<string, string> = isMongoNative
+    ? {}
+    : {
+        'db:setup': 'prisma generate && prisma db push',
+        'db:generate': 'prisma generate',
+        'db:push': 'prisma db push',
+        'db:migrate': 'prisma migrate dev',
+        'db:studio': 'prisma studio',
+        'db:seed': 'tsx prisma/seed.ts',
+      };
+
+  const ormDeps: Record<string, string> = isMongoNative
+    ? { 'mongodb': '^6.3.0' }
+    : { '@prisma/client': '^5.7.0' };
+
+  const ormDevDeps: Record<string, string> = isMongoNative
+    ? {}
+    : { 'prisma': '^5.7.0' };
 
   const pkg: Record<string, any> = {
     name: `${appName}-backend`,
@@ -32,13 +73,8 @@ export default function generateBackendPackageJson(context: TemplateContext): st
       // Production
       'start': 'node dist/main.js',
 
-      // Database
-      'db:setup': 'prisma generate && prisma db push',
-      'db:generate': 'prisma generate',
-      'db:push': 'prisma db push',
-      'db:migrate': 'prisma migrate dev',
-      'db:studio': 'prisma studio',
-      'db:seed': 'tsx prisma/seed.ts',
+      // Database (ORM-specific; empty for native driver)
+      ...dbScripts,
 
       // Testing
       'test': 'vitest run --passWithNoTests',
@@ -54,7 +90,7 @@ export default function generateBackendPackageJson(context: TemplateContext): st
     },
 
     dependencies: {
-      '@prisma/client': '^5.7.0',
+      ...ormDeps,
       'fastify': '^5.8.3',
       '@fastify/cors': '^10.0.0',
       '@fastify/helmet': '^12.0.0',
@@ -70,7 +106,7 @@ export default function generateBackendPackageJson(context: TemplateContext): st
       'typescript': '^5.3.0',
       '@types/node': '^20.10.0',
       'tsx': '^4.7.0',
-      'prisma': '^5.7.0',
+      ...ormDevDeps,
       'vitest': '^3.0.0',
       '@vitest/coverage-v8': '^3.0.0',
       'eslint': '^9.0.0',

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

@@ -36,16 +36,26 @@ export default function generateFastifyRoutes(context: TemplateContext): string
     }
   }
 
-  // Add custom action endpoints
+  // Add custom action endpoints. Each action can declare:
+  //   path:   explicit HTTP path (absolute or relative)
+  //   method: explicit HTTP method
+  // If `path` starts with `/api/` (or any absolute non-relative form), it
+  // ESCAPES the controller's prefix and gets mounted at root level via the
+  // `registerExternalRoutes` exported function (the main.ts generator
+  // collects these across controllers and registers them without a prefix).
   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`);
+      const explicitPath: string | undefined = action.path;
+      const explicitMethod: string | undefined = action.method;
+      const isExternal = !!(explicitPath && /^\/api\//.test(explicitPath));
       endpoints.push({
         operation: actionName,
-        method: 'POST',
-        path: hasIdParam ? `/:id/${actionName}` : `/${actionName}`,
+        method: explicitMethod || 'POST',
+        path: explicitPath || (hasIdParam ? `/:id/${actionName}` : `/${actionName}`),
+        external: isExternal,
         parameters: params,
         description: action.description || `Custom action: ${actionName}`,
       });
@@ -57,9 +67,41 @@ export default function generateFastifyRoutes(context: TemplateContext): string
     console.warn(`Warning: Controller ${controllerName} has no endpoints. Generating empty routes file.`);
   }
 
-  const routeHandlers = endpoints?.map((endpoint: any) => {
-    return generateRouteHandler(endpoint, modelName, handlerName, isModelController, implType, controllerName);
-  }).join('\n\n') || '';
+  // Split endpoints by routing scope:
+  //   - internal: mounted under the controller's `/api/<plural>` prefix
+  //     (the default plugin export). Both CURVED ops and relative-path
+  //     custom actions live here.
+  //   - external: actions that declared an absolute `path` like
+  //     `/api/v2/auth/register`. Mounted at root via the separately
+  //     exported `registerExternalRoutes` function so they escape the
+  //     controller prefix.
+  const internalEndpoints = endpoints?.filter((e: any) => !e.external) || [];
+  const externalEndpoints = endpoints?.filter((e: any) => e.external) || [];
+
+  const internalHandlers = internalEndpoints
+    .map((endpoint: any) => generateRouteHandler(endpoint, modelName, handlerName, isModelController, implType, controllerName))
+    .join('\n\n');
+  const externalHandlers = externalEndpoints
+    .map((endpoint: any) => generateRouteHandler(endpoint, modelName, handlerName, isModelController, implType, controllerName))
+    .join('\n\n');
+
+  const externalRoutesExport = externalEndpoints.length > 0 ? `
+/**
+ * Mount the external (root-prefix) routes for this controller.
+ *
+ * Called by the generated main.ts at root scope (no prefix) so action.path
+ * declarations like '/api/v2/auth/register' land at exactly that URL,
+ * bypassing the controller's '/api/<plural>' prefix.
+ */
+export async function registerExternalRoutes(
+  fastify: FastifyInstance,
+  options: any
+) {
+  const handler = ${isModelController ? 'options.controllers' : 'options.services'}.${handlerName};
+
+${externalHandlers.split('\n').map(line => '  ' + line).join('\n')}
+}
+` : '';
 
   // Generate the complete route file
   return `${imports}
@@ -77,9 +119,9 @@ export default async function ${routeName.replace('Controller', '')}Routes(
 ) {
   const handler = ${isModelController ? 'options.controllers' : 'options.services'}.${handlerName};
 
-${routeHandlers.split('\n').map(line => '  ' + line).join('\n')}
+${internalHandlers.split('\n').map(line => '  ' + line).join('\n')}
 }
-`;
+${externalRoutesExport}`;
 }
 
 /**
@@ -306,28 +348,38 @@ function generateHandlerBody(
 }`;
 
     default: {
-      // Custom action — validate body against declared parameters, then call handler
+      // Custom action — merge URL params + body into a single `args` object
+      // and pass it to the handler. The merged shape lets the action method
+      // read fields uniformly without caring whether they came from `:id`
+      // in the path or the JSON body. Validation still fires on declared
+      // parameters but is skipped for any param name that's also a URL
+      // path parameter (those come from request.params, not the body).
+      const path = endpoint?.path || '';
+      const urlParamNames = new Set<string>();
+      const urlParamRegex = /:([A-Za-z_][\w]*)/g;
+      let urlMatch: RegExpExecArray | null;
+      while ((urlMatch = urlParamRegex.exec(path)) !== null) {
+        urlParamNames.add(urlMatch[1]);
+      }
+
       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
+      // Generate per-parameter body validation, skipping URL-path-sourced params
       const validations: string[] = [];
       for (const [pName, pDef] of Object.entries(params) as [string, any][]) {
+        if (urlParamNames.has(pName)) continue;
         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' });`);
+          validations.push(`  if (args.${pName} === undefined || args.${pName} === null) errors.push({ field: '${pName}', message: '${pName} is required' });`);
         }
-        // Type checks
+        // Type checks (skip when undefined — `required` covers the missing case)
         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' });`);
+          validations.push(`  if (args.${pName} !== undefined && typeof args.${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' });`);
+          validations.push(`  if (args.${pName} !== undefined && typeof args.${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' });`);
+          validations.push(`  if (args.${pName} !== undefined && typeof args.${pName} !== 'boolean') errors.push({ field: '${pName}', message: '${pName} must be a boolean' });`);
         }
       }
 
@@ -336,14 +388,21 @@ function generateHandlerBody(
         : '';
 
       return `try {
+  const params = (request.params || {}) as Record<string, any>;
   const body = (request.body || {}) as Record<string, any>;
+  const args = { ...params, ...body };
 ${validationBlock}
-  const result = await handler.${operation}(${callArgs});
+  const result = await handler.${operation}(args);
   return reply.send(result || { success: true });
 } catch (error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  // 501 for TODO-stubbed action bodies (#43F); 400 for real failures.
+  if (msg.includes('is not implemented')) {
+    return reply.status(501).send({ error: 'Not Implemented', message: msg });
+  }
   return reply.status(400).send({
     error: 'Failed to execute ${operation}',
-    message: error instanceof Error ? error.message : String(error)
+    message: msg
   });
 }`;
     }

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

@@ -7,16 +7,39 @@
 import type { TemplateContext } from '@specverse/types';
 import { normalizeSpec, deriveBasePath } from '@specverse/types/spec-rules';
 
+/** Resolve the manifest's orm choice so the server template adapts its
+ * imports + lifecycle hooks. When MongoDBNativeDriver is selected we
+ * drop the prisma import + prisma.$disconnect call (no prisma in deps);
+ * the mongo client has its own disconnect helper exposed by the
+ * client-generator. */
+function resolveOrmName(manifest: any): string {
+  if (!manifest) return 'PrismaORM';
+  const inner = manifest.manifests
+    ? Object.values(manifest.manifests)[0] as any
+    : manifest;
+  if (!inner) return 'PrismaORM';
+  const caps = Array.isArray(inner.capabilityMappings) ? inner.capabilityMappings : [];
+  const ormCap = caps.find((m: any) => m?.capability === 'orm.client') ||
+                 caps.find((m: any) => m?.capability === 'orm.schema');
+  if (ormCap) return ormCap.implementation || ormCap.instanceFactory || 'PrismaORM';
+  return inner.defaultMappings?.orm || 'PrismaORM';
+}
+
 export default function generateFastifyServer(context: TemplateContext): string {
-  const { spec, models } = context;
+  const { spec, models, manifest } = context as any;
+  const orm = resolveOrmName(manifest);
+  const isMongoNative = orm === 'MongoDBNativeDriver';
 
   // Extract model names for route registration
   const allModels = models || (spec?.models ? Object.values(spec.models) : []);
   const modelNames = allModels.map((m: any) => m.name).filter(Boolean);
 
-  // Generate route imports and registrations
+  // Generate route imports and registrations. We import the routes module
+  // as a namespace so the optional `registerExternalRoutes` named export is
+  // available at runtime — its presence depends on whether the controller
+  // declared any actions with absolute `path:` (escape-the-prefix) routes.
   const routeImports = modelNames.map((name: string) =>
-    `import ${name}Routes from './routes/${name}Controller.js';`
+    `import ${name}Routes, * as ${name}RoutesNS from './routes/${name}Controller.js';`
   ).join('\n');
 
   const routeRegistrations = modelNames.map((name: string) => {
@@ -24,6 +47,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');
 
+  // External-route registrations: each controller's namespace may export
+  // `registerExternalRoutes` for action.path declarations like
+  // '/api/v2/auth/register' that need to escape the controller prefix.
+  // Mounted at root scope, no prefix, no plugin scoping.
+  const externalRouteRegistrations = modelNames.map((name: string) => {
+    return `  if (typeof (${name}RoutesNS as any).registerExternalRoutes === 'function') {
+    await (${name}RoutesNS as any).registerExternalRoutes(fastify, { 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;
@@ -59,7 +92,7 @@ export default function generateFastifyServer(context: TemplateContext): string
 // workspace before running the script.
 import { config as loadEnv } from 'dotenv';
 import { existsSync } from 'fs';
-import { resolve as resolvePath, dirname, join } from 'path';
+import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 {
   let dir = dirname(fileURLToPath(import.meta.url));
@@ -72,12 +105,17 @@ import { fileURLToPath } from 'url';
 
 import Fastify from 'fastify';
 import cors from '@fastify/cors';
-import { PrismaClient } from '@prisma/client';
+${isMongoNative
+  ? `import { disconnect as disconnectMongo } from './db/mongoClient.js';`
+  : `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();
+${isMongoNative
+  ? `// MongoDB native driver client lives in db/mongoClient.ts; nothing
+// to initialize at module scope (lazy-connect on first getCollection).`
+  : `// Initialize Prisma
+export const prisma = new PrismaClient();`}
 
 // Initialize Fastify
 const fastify = Fastify({
@@ -117,6 +155,9 @@ ${serviceSingletonImports ? `// Service singletons + their Fastify route files\n
 async function registerRoutes() {
 ${routeRegistrations}
 ${serviceRouteRegistrations ? '\n  // Service operation routes (RPC-style under /api/services/{ServiceName})\n' + serviceRouteRegistrations : ''}
+
+  // External-prefix actions (action.path declarations like '/api/v2/auth/register')
+${externalRouteRegistrations}
 }
 
 // Start server
@@ -145,7 +186,7 @@ ${hasEvents ? `    console.log(\`WebSocket: ws://localhost:\${port}/ws\`);
       try {
         fastify.log.info(\`Received \${signal}, closing server...\`);
         await fastify.close();
-        try { await (prisma as any).$disconnect?.(); } catch { /* ignore */ }
+        try { ${isMongoNative ? 'await disconnectMongo();' : 'await (prisma as any).$disconnect?.();'} } catch { /* ignore */ }
         process.exit(0);
       } catch (err) {
         fastify.log.error({ err }, 'Error during shutdown');

package/libs/instance-factories/services/templates/mongodb-native/__tests__/controller-generator.test.ts

@@ -94,7 +94,9 @@ describe('MongoDB native — controller-generator', () => {
       model: { ...baseModel, storage: { collection: 'custom_todos' } },
     } as any);
     expect(out).toContain(`COLLECTION_NAME = 'custom_todos'`);
-    expect(out).toContain(`getCollection('custom_todos')`);
+    // CURVED ops reference the constant, not the literal — keeps the
+    // generator output noUnusedLocals-clean under strict tsc.
+    expect(out).toContain(`getCollection(COLLECTION_NAME)`);
   });
 
   it('omits CURVED ops not declared on the controller', () => {

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

@@ -36,7 +36,7 @@ export default function generateMongoNativeController(context: TemplateContext):
   const collection = collectionName(model);
   const curedOps = controller.cured || {};
 
-  const customActions = generateCustomActions(controller, modelName);
+  const customActions = generateCustomActions(controller);
 
   const validate = generateValidateMethod(model, modelName);
   const create = curedOps.create ? generateCreateMethod(model, modelName, modelVar, collection) : '';
@@ -56,7 +56,7 @@ export default function generateMongoNativeController(context: TemplateContext):
 import { ObjectId, type Filter, type Document } from 'mongodb';
 import { getCollection } from '../db/mongoClient.js';
 ${hasEventPublishing ? `import { eventBus } from '../events/eventBus.js';` : ''}
-${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${modelName}Controller.ai.js';` : ''}
+${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${controllerName}.ai.js';` : ''}
 
 const COLLECTION_NAME = '${collection}';
 
@@ -147,7 +147,7 @@ function generateCreateMethod(model: any, modelName: string, modelVar: string, c
     const validation = this.validate(data, { operation: 'create' });
     if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
 
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     const result = await collection.insertOne({ ...data });
     const ${modelVar} = { _id: result.insertedId, ...data };
 
@@ -163,7 +163,7 @@ function generateRetrieveMethod(modelName: string, modelVar: string, collection:
    * Retrieve ${modelName} by id. Returns null when not found.
    */
   public async retrieve(id: string): Promise<any | null> {
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     return await collection.findOne(byId(id));
   }
 
@@ -171,7 +171,7 @@ function generateRetrieveMethod(modelName: string, modelVar: string, collection:
    * Retrieve a page of ${modelName}s.
    */
   public async retrieveAll(options: { skip?: number; take?: number } = {}): Promise<any[]> {
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     const cursor = collection.find({});
     if (options.skip) cursor.skip(options.skip);
     if (options.take) cursor.limit(options.take);
@@ -198,7 +198,7 @@ function generateUpdateMethod(modelName: string, modelVar: string, collection: s
       updateData[key] = value;
     }
 
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     await collection.updateOne(byId(id), { $set: updateData });
     const ${modelVar} = await collection.findOne(byId(id));
     if (!${modelVar}) throw new Error('${modelName} not found after update');
@@ -231,7 +231,7 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string, c
    * States: ${states.join(' → ') || '(none declared)'}
    */
   public async evolve(id: string, data: any): Promise<any> {
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     const current = await collection.findOne(byId(id));
     if (!current) throw new Error('${modelName} not found');
 
@@ -264,7 +264,7 @@ function generateDeleteMethod(modelName: string, modelVar: string, collection: s
    * Delete ${modelName}.
    */
   public async delete(id: string): Promise<void> {
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     const ${modelVar} = await collection.findOne(byId(id));
     await collection.deleteOne(byId(id));
     if (${modelVar}) {
@@ -279,16 +279,83 @@ interface CustomActionsResult {
   needsAiBehaviors: boolean;
 }
 
-function generateCustomActions(controller: any, modelName: string): CustomActionsResult {
+/**
+ * Custom actions emit a per-step body using `matchMongoStep`. The same
+ * matcher is passed to the AI-behaviors-generator (via realize/index.ts)
+ * so both sides accumulate the same `declaredVars` set and produce
+ * matching function names + inputs for unmatched steps.
+ *
+ * Per step:
+ *   - matched → emit conventional native-driver code inline
+ *   - unmatched → emit `const stepNResult = await aiBehaviors.<funcName>({...});`
+ *     (the aiBehaviors function comes from the controller's `*.ai.ts`
+ *     file, generated by AI-behaviors-generator using the SAME matcher).
+ */
+import { matchMongoStep, type MongoStepContext } from './step-conventions.js';
+
+function generateCustomActions(controller: any): CustomActionsResult {
   if (!controller.actions || Object.keys(controller.actions).length === 0) {
     return { code: '', needsAiBehaviors: false };
   }
+  const CRUD_NAMES = new Set(['create', 'retrieve', 'retrieveAll', 'update', 'evolve', 'delete', 'validate']);
+  const modelName = controller.model || (controller.name || '').replace(/Controller$/, '') || 'Model';
+  const collectionName = modelName.toLowerCase() + 's';
   const out: string[] = [];
+  let needsAiBehaviors = false;
   for (const [actionName, action] of Object.entries<any>(controller.actions)) {
-    const params = generateActionParams(action);
-    const stepsHeader = (action.steps && action.steps.length > 0)
-      ? action.steps.map((s: any) => `   *   - ${typeof s === 'string' ? s : (s.action || JSON.stringify(s))}`).join('\n')
+    if (CRUD_NAMES.has(actionName)) continue;
+    const steps: any[] = Array.isArray(action.steps) ? action.steps : [];
+    const stepsHeader = steps.length > 0
+      ? steps.map((s: any) => `   *   - ${typeof s === 'string' ? s : (s.action || JSON.stringify(s))}`).join('\n')
       : '   *   (no spec steps declared)';
+
+    const declaredVars = new Set<string>();
+    const stepBodies: string[] = [];
+    let usesArgs = false;
+    let actionRefersToAi = false;
+    steps.forEach((rawStep: any, i: number) => {
+      const stepText = typeof rawStep === 'string' ? rawStep : (rawStep?.step || rawStep?.action);
+      if (typeof stepText !== 'string') {
+        stepBodies.push(`    // Step ${i + 1}: (non-string step ignored)`);
+        return;
+      }
+      const ctx: MongoStepContext = {
+        modelName,
+        collectionName,
+        serviceName: controller.name || 'Controller',
+        operationName: actionName,
+        stepNum: i + 1,
+        parameterNames: Object.keys(action.parameters || {}),
+        declaredVars,
+      };
+      const result = matchMongoStep(stepText, ctx);
+      stepBodies.push(result.call);
+      if (/\bargs\./.test(result.call)) usesArgs = true;
+      if (!result.matched) actionRefersToAi = true;
+    });
+
+    if (actionRefersToAi) needsAiBehaviors = true;
+    const argsParam = usesArgs ? 'args: any = {}' : '_args: any = {}';
+    let combined = stepBodies.join('\n\n');
+    // Drop the `const stepNResult =` declaration when no later step
+    // references the result. Strict tsc's noUnusedLocals applies to
+    // locals regardless of underscore prefix, so the only safe fix is
+    // to omit the assignment entirely. The await still fires.
+    const stepResultRe = /const\s+(step\d+Result)\s*=/g;
+    let mres: RegExpExecArray | null;
+    const declared: string[] = [];
+    while ((mres = stepResultRe.exec(combined)) !== null) declared.push(mres[1]);
+    for (const name of declared) {
+      const refCount = (combined.match(new RegExp(`\\b${name}\\b`, 'g')) || []).length;
+      if (refCount <= 1) {
+        // Only the declaration itself — drop the binding, keep the await.
+        combined = combined.replace(new RegExp(`const\\s+${name}\\s*=\\s*`), '');
+      }
+    }
+    const body = steps.length > 0
+      ? combined + `\n    return { success: true };`
+      : `    throw new Error('${controller.name || 'Controller'}.${actionName} is not implemented');`;
+
     out.push(`
   /**
    * ${actionName}
@@ -297,20 +364,10 @@ function generateCustomActions(controller: any, modelName: string): CustomAction
    * Spec steps:
 ${stepsHeader}
    */
-  public async ${actionName}(${params}): Promise<any> {
-    return await aiBehaviors.${actionName}({ controller: this, ...args });
+  public async ${actionName}(${argsParam}): Promise<any> {
+${body}
   }
 `);
   }
-  return { code: out.join('\n'), needsAiBehaviors: true };
-}
-
-function generateActionParams(action: any): string {
-  if (Array.isArray(action.parameters) && action.parameters.length > 0) {
-    return 'args: any';
-  }
-  if (action.parameters && typeof action.parameters === 'object' && Object.keys(action.parameters).length > 0) {
-    return 'args: any';
-  }
-  return 'args: any = {}';
+  return { code: out.join('\n'), needsAiBehaviors };
 }