@specverse/engines 6.7.8 → 6.16.0

package/libs/instance-factories/services/postgres-native-services.yaml

@@ -0,0 +1,90 @@
+name: PostgresNativeDriver
+version: "1.0.0"
+category: service
+description: "Business logic services using the native node-postgres (pg) driver — raw SQL, no ORM layer"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [services, business-logic, postgres, pg, native-driver, controllers]
+
+compatibility:
+  specverse: ">=5.0.0"
+  node: ">=18.0.0"
+
+# Same shape as MongoDBNativeDriver — the pg pool IS the data layer; no ORM
+# layer to swap in independently. This single factory therefore provides
+# both the orm.* capabilities and the service-layer capabilities.
+capabilities:
+  provides:
+    - "orm.schema"     # Emits the pg pool client + DDL (the connection IS the schema layer)
+    - "orm.client"
+    - "orm.postgres.native"
+    - "service.controller"
+    - "service.business"
+    - "service.crud"
+  requires:
+    - "storage.database.relational"
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  orm: "postgres-native"
+  version: "^8.11.0"
+
+dependencies:
+  runtime:
+    - name: "pg"
+      version: "^8.11.0"
+
+  dev:
+    - name: "@types/pg"
+      version: "^8.11.0"
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  # `schema` slot emits the pg pool singleton + a co-located CREATE TABLE
+  # script (schema.sql) so users can bootstrap a database without pulling
+  # in an external migrator. The pool generator owns the runtime
+  # connection; the DDL generator owns the static SQL.
+  schema:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/postgres-native/client-generator.ts"
+    outputPattern: "{backendDir}/src/db/pgClient.ts"
+
+  ddl:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/postgres-native/ddl-generator.ts"
+    outputPattern: "{backendDir}/src/db/schema.sql"
+
+  controllers:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/postgres-native/controller-generator.ts"
+    outputPattern: "{backendDir}/src/controllers/{model}Controller.ts"
+
+  services:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/postgres-native/service-generator.ts"
+    outputPattern: "{backendDir}/src/services/{service}.ts"
+
+configuration:
+  outputStructure: "monorepo"
+  backendDir: "backend"
+  tableNaming: "lowercase-pluralized"  # User → users, OrderItem → orderitems
+  validation: true
+  eventPublishing: true
+  errorHandling: "throw"
+
+requirements:
+  dependencies:
+    npm:
+      dependencies:
+        "pg": "^8.11.0"
+  environment:
+    - name: "POSTGRES_URL"
+      description: "PostgreSQL connection string (e.g. postgres://user:pass@localhost:5432/myapp)"
+      required: true
+  configuration: {}

package/libs/instance-factories/services/templates/_shared/step-matching.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared step-matching machinery — common helpers + the canonical
+ * `matchAgainstConventions` walker that any ORM-specific step-conventions
+ * library can compose with.
+ *
+ * Each ORM library (prisma, mongodb-native) exports its own
+ * `STEP_CONVENTIONS` array of `{name, pattern, generateCall}` items
+ * describing what code to emit for matched patterns. The matcher itself
+ * is identical across libraries: walk the conventions in order, first
+ * match wins; if nothing matches, compute the AI-fallback shape
+ * (functionName + inputs + resultVar) deterministically.
+ *
+ * Extracted from prisma/step-conventions.ts and mongodb-native/step-conventions.ts
+ * so future ORM libraries can drop in just the conventions array
+ * without re-implementing matching logic. (#43K-D)
+ */
+
+/** Camel-case a step's text into a TS identifier. Identical algorithm
+ * across all ORM libraries — function names emitted in `aiBehaviors.<X>(...)`
+ * calls must agree with the function declarations the AI-behaviors-generator
+ * emits. Both sides go through this. */
+export function toMethod(words: string): string {
+  const cleaned = words.trim().replace(/[^A-Za-z0-9\s]+/g, ' ');
+  const camel = cleaned.replace(/\s+(.)/g, (_, c) => c.toUpperCase()).replace(/^\w/, (c) => c.toLowerCase());
+  const safe = camel.replace(/[^A-Za-z0-9_$]/g, '');
+  return safe || 'unnamedStep';
+}
+
+export function toVar(name: string): string {
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+
+export interface SharedStepContext {
+  modelName: string;
+  serviceName: string;
+  operationName: string;
+  stepNum: number;
+  parameterNames?: string[];
+  declaredVars?: Set<string>;
+  resultName?: string;
+}
+
+export interface SharedConvention<C extends SharedStepContext = SharedStepContext> {
+  name: string;
+  pattern: RegExp;
+  /** Emit inline code for this step. Return empty string to signal
+   * "regex matched but I can't safely emit" (caller falls through to AI). */
+  generateCall: (match: RegExpMatchArray, ctx: C) => string;
+  /** Optional helper-method body that some libraries (e.g. prisma's
+   * `check {condition}` convention) emit alongside the call site. */
+  generateMethod?: (match: RegExpMatchArray, ctx: C) => string;
+}
+
+export interface MatchResult {
+  matched: boolean;
+  call: string;
+  helperMethod?: string;
+  functionName?: string;
+  inputs?: string[];
+  resultVar?: string;
+}
+
+/** Walk conventions in order. First match wins (with empty-string fallthrough).
+ * Unmatched: compute the AI-delegate call site shape so the controller and
+ * the AI-behaviors-generator agree on function name + inputs + resultVar. */
+export function matchAgainstConventions<C extends SharedStepContext>(
+  step: string,
+  ctx: C,
+  conventions: ReadonlyArray<SharedConvention<C>>,
+  aiArgsExpr: (inputs: string[], paramNames: string[]) => string,
+): MatchResult {
+  for (const convention of conventions) {
+    const m = step.match(convention.pattern);
+    if (m) {
+      const call = convention.generateCall(m, ctx);
+      if (call) {
+        return {
+          matched: true,
+          call,
+          helperMethod: convention.generateMethod?.(m, ctx),
+        };
+      }
+    }
+  }
+
+  // AI fallback shape — same across all ORMs.
+  const functionName = toMethod(step);
+  const declared = Array.from(ctx.declaredVars || []);
+  const paramNames = ctx.parameterNames || [];
+  const inputs = [...paramNames, ...declared];
+  const resultVar = ctx.resultName || `step${ctx.stepNum}Result`;
+  if (ctx.declaredVars) ctx.declaredVars.add(resultVar);
+  const inputObj = aiArgsExpr(inputs, paramNames);
+
+  return {
+    matched: false,
+    call: `    // Step ${ctx.stepNum}: ${step} [AI-generated — pure transform]
+    const ${resultVar} = await aiBehaviors.${functionName}(${inputObj});`,
+    functionName,
+    inputs,
+    resultVar,
+  };
+}

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

@@ -26,7 +26,7 @@ import type { TemplateContext } from '@specverse/types';
 import { buildTransitionMap, isAutoField } from '@specverse/types/spec-rules';
 
 export default function generateMongoNativeController(context: TemplateContext): string {
-  const { controller, model } = context;
+  const { controller, model, models } = context as any;
   if (!controller) throw new Error('Controller is required in template context');
   if (!model) throw new Error('Model is required for controller generation');
 
@@ -36,7 +36,17 @@ export default function generateMongoNativeController(context: TemplateContext):
   const collection = collectionName(model);
   const curedOps = controller.cured || {};
 
-  const customActions = generateCustomActions(controller);
+  // Build a name → ModelSpec registry once so step-conventions can read
+  // attribute defaults (level: 1, totalResources: '', etc.) and FK targets
+  // when emitting create/insertMany code (#43K-A).
+  const modelRegistry: Record<string, any> = {};
+  if (Array.isArray(models)) {
+    for (const m of models) if (m?.name) modelRegistry[m.name] = m;
+  } else if (models && typeof models === 'object') {
+    Object.assign(modelRegistry, models);
+  }
+
+  const customActions = generateCustomActions(controller, modelRegistry);
 
   const validate = generateValidateMethod(model, modelName);
   const create = curedOps.create ? generateCreateMethod(model, modelName, modelVar, collection) : '';
@@ -55,7 +65,8 @@ 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';` : ''}
+${hasEventPublishing || customActions.needsAiBehaviors ? `import { eventBus } from '../events/eventBus.js';` : ''}
+${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${controllerName}.ai.js';` : ''}
 
 const COLLECTION_NAME = '${collection}';
 
@@ -275,29 +286,96 @@ function generateDeleteMethod(modelName: string, modelVar: string, collection: s
 
 interface CustomActionsResult {
   code: string;
+  needsAiBehaviors: boolean;
 }
 
 /**
- * Custom actions emit TODO stubs that throw "not implemented".
+ * 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.
  *
- * Why not delegate to `aiBehaviors.<actionName>`? Because the AI-behaviors
- * generator only emits functions for STEPS that didn't match a convention
- * pattern — not for actions themselves. So `aiBehaviors.rotate` would not
- * exist even when an action named `rotate` is declared on the controller.
- *
- * Real implementation of action bodies is deferred to the MongoDB-native
- * step-conventions library (#43F follow-up — mirror Prisma's
- * step-conventions.ts but emit native-driver collection calls).
+ * 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).
  */
-function generateCustomActions(controller: any): CustomActionsResult {
+import { matchMongoStep, type MongoStepContext } from './step-conventions.js';
+
+function generateCustomActions(controller: any, modelRegistry: Record<string, any> = {}): CustomActionsResult {
   if (!controller.actions || Object.keys(controller.actions).length === 0) {
-    return { code: '' };
+    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 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)) {
+      // Surface the collision so spec authors aren't silently losing
+      // a declared action. Going forward this could escalate to an
+      // error or auto-rename; for now a warning keeps existing specs
+      // building while making the dropped behaviour visible.
+      console.warn(
+        `⚠️  ${controller.name || 'Controller'}.${actionName} — behaviour-derived action collides with the auto-generated CURVED \`${actionName}\` op. Dropped to avoid TS2393 duplicate-implementation. Rename the behaviour (e.g. \`${actionName}Soft\` / \`hardDelete\`) if you need the custom logic.`
+      );
+      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,
+        models: modelRegistry,
+      };
+      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}
@@ -306,14 +384,10 @@ function generateCustomActions(controller: any): CustomActionsResult {
    * Spec steps:
 ${stepsHeader}
    */
-  public async ${actionName}(_args: any = {}): Promise<any> {
-    // TODO (#43F): translate spec steps into native MongoDB driver calls
-    // via a mongodb-native step-conventions library (mirror of the prisma
-    // one). For now this is a stub so realize completes and the action
-    // surface is callable for parity tests.
-    throw new Error('${controller.name}.${actionName} is not implemented');
+  public async ${actionName}(${argsParam}): Promise<any> {
+${body}
   }
 `);
   }
-  return { code: out.join('\n') };
+  return { code: out.join('\n'), needsAiBehaviors };
 }