@specverse/engines 6.11.2 → 6.17.0

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

@@ -0,0 +1,44 @@
+function toMethod(words) {
+  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";
+}
+function toVar(name) {
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+function matchAgainstConventions(step, ctx, conventions, aiArgsExpr) {
+  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)
+        };
+      }
+    }
+  }
+  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 \u2014 pure transform]
+    const ${resultVar} = await aiBehaviors.${functionName}(${inputObj});`,
+    functionName,
+    inputs,
+    resultVar
+  };
+}
+export {
+  matchAgainstConventions,
+  toMethod,
+  toVar
+};

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

@@ -1,6 +1,6 @@
 import { buildTransitionMap, isAutoField } from "@specverse/types/spec-rules";
 function generateMongoNativeController(context) {
-  const { controller, model } = context;
+  const { controller, model, models } = context;
   if (!controller) throw new Error("Controller is required in template context");
   if (!model) throw new Error("Model is required for controller generation");
   const controllerName = controller.name;
@@ -8,7 +8,13 @@ function generateMongoNativeController(context) {
   const modelVar = lowerFirst(modelName);
   const collection = collectionName(model);
   const curedOps = controller.cured || {};
-  const customActions = generateCustomActions(controller);
+  const modelRegistry = {};
+  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) : "";
   const retrieve = curedOps.retrieve ? generateRetrieveMethod(modelName, modelVar, collection) : "";
@@ -23,7 +29,7 @@ function generateMongoNativeController(context) {
  */
 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}';
@@ -223,7 +229,7 @@ function generateDeleteMethod(modelName, modelVar, collection) {
 `;
 }
 import { matchMongoStep } from "./step-conventions.js";
-function generateCustomActions(controller) {
+function generateCustomActions(controller, modelRegistry = {}) {
   if (!controller.actions || Object.keys(controller.actions).length === 0) {
     return { code: "", needsAiBehaviors: false };
   }
@@ -233,7 +239,12 @@ function generateCustomActions(controller) {
   const out = [];
   let needsAiBehaviors = false;
   for (const [actionName, action] of Object.entries(controller.actions)) {
-    if (CRUD_NAMES.has(actionName)) continue;
+    if (CRUD_NAMES.has(actionName)) {
+      console.warn(
+        `\u26A0\uFE0F  ${controller.name || "Controller"}.${actionName} \u2014 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 = Array.isArray(action.steps) ? action.steps : [];
     const stepsHeader = steps.length > 0 ? steps.map((s) => `   *   - ${typeof s === "string" ? s : s.action || JSON.stringify(s)}`).join("\n") : "   *   (no spec steps declared)";
     const declaredVars = /* @__PURE__ */ new Set();
@@ -253,7 +264,8 @@ function generateCustomActions(controller) {
         operationName: actionName,
         stepNum: i + 1,
         parameterNames: Object.keys(action.parameters || {}),
-        declaredVars
+        declaredVars,
+        models: modelRegistry
       };
       const result = matchMongoStep(stepText, ctx);
       stepBodies.push(result.call);

package/dist/libs/instance-factories/services/templates/mongodb-native/step-conventions.js

@@ -1,15 +1,68 @@
-function toVar(name) {
-  return name.charAt(0).toLowerCase() + name.slice(1);
+import {
+  toVar,
+  matchAgainstConventions
+} from "../_shared/step-matching.js";
+function deriveModelDefaults(modelName, ctx) {
+  if (!ctx.models) return [];
+  const model = ctx.models[modelName] || ctx.models[modelName.charAt(0).toUpperCase() + modelName.slice(1)];
+  if (!model) return [];
+  const attrs = model.attributes;
+  if (!attrs) return [];
+  const list = Array.isArray(attrs) ? attrs.map((a) => [a.name, a]) : Object.entries(attrs);
+  const declaredVars = ctx.declaredVars || /* @__PURE__ */ new Set();
+  const out = [];
+  const conventionManaged = /* @__PURE__ */ new Set(["createdAt", "updatedAt", "id"]);
+  for (const [name, attr] of list) {
+    if (!name) continue;
+    if (conventionManaged.has(name)) continue;
+    const required = !!attr.required;
+    const hasDefault = attr.default !== void 0;
+    if (!required && !hasDefault) continue;
+    if (hasDefault) {
+      out.push(`${name}: ${formatDefault(attr.default, attr.type)}`);
+      continue;
+    }
+    const type = (attr.type || "String").toLowerCase();
+    if (type === "integer" || type === "int" || type === "number" || type === "float") {
+      const min = attr.min ?? 0;
+      out.push(`${name}: ${min}`);
+    } else if (type === "boolean") {
+      out.push(`${name}: false`);
+    } else if (type === "datetime" || type === "date") {
+      if (attr.auto === "now") {
+        out.push(`${name}: new Date().toISOString()`);
+      } else {
+        out.push(`${name}: new Date().toISOString()`);
+      }
+    } else {
+      const selfVar = modelName.charAt(0).toLowerCase() + modelName.slice(1);
+      const fkMatch = name.match(/^(.+)Id$/);
+      if (fkMatch && fkMatch[1] !== selfVar && declaredVars.has(fkMatch[1])) {
+        out.push(`${name}: (${fkMatch[1]} as any)?._id ?? (${fkMatch[1]} as any)?.id`);
+      } else {
+        out.push(`${name}: ''`);
+      }
+    }
+  }
+  return out;
+}
+function formatDefault(value, type) {
+  if (value === null || value === void 0) return "null";
+  if (typeof value === "boolean") return String(value);
+  if (typeof value === "number") return String(value);
+  if (typeof value === "string") {
+    if (/^-?\d+(\.\d+)?$/.test(value)) return value;
+    if (value === "true" || value === "false") return value;
+    if (value === "now" && (type === "DateTime" || type === "Date")) {
+      return "new Date().toISOString()";
+    }
+    return JSON.stringify(value);
+  }
+  return JSON.stringify(value);
 }
 function toCollection(modelName) {
   return modelName.toLowerCase() + "s";
 }
-function toMethod(words) {
-  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";
-}
 function resolveValue(rawValue, ctx) {
   const value = rawValue.trim().replace(/^['"]|['"]$/g, "");
   if (/^(current\s*time|now|timestamp)$/i.test(value)) return "new Date().toISOString()";
@@ -26,6 +79,14 @@ function resolveValue(rawValue, ctx) {
   if (/\s/.test(value)) return `/* TODO: resolve "${value}" */ null`;
   return `'${value.replace(/'/g, "\\'")}'`;
 }
+function mostRecentStepResult(ctx) {
+  const declared = Array.from(ctx.declaredVars || []);
+  const stepResults = declared.filter((v) => /^step\d+Result$/.test(v)).sort((a, b) => parseInt(b.slice(4), 10) - parseInt(a.slice(4), 10));
+  return stepResults[0] ?? null;
+}
+function pascal(model) {
+  return model.charAt(0).toUpperCase() + model.slice(1);
+}
 const MONGO_STEP_CONVENTIONS = [
   // --- Find / Lookup by single field ---
   // Matches: "Look up X by Y", "Find X by Y", "Find X by Y or fail with 404"
@@ -47,7 +108,8 @@ const MONGO_STEP_CONVENTIONS = [
       const failOnMissing = /or\s+fail/i.test(m[0]);
       return `    // Step ${ctx.stepNum}: Find ${model} by ${field}
     const ${modelVar}_collection = await getCollection('${collection}');
-    const ${modelVar} = await ${modelVar}_collection.findOne({ ${field}: ${idVal} });${failOnMissing ? `
+    let ${modelVar} = await ${modelVar}_collection.findOne({ ${field}: ${idVal} });
+    if (${modelVar} && !(${modelVar} as any).id && (${modelVar} as any)._id) (${modelVar} as any).id = String((${modelVar} as any)._id);${failOnMissing ? `
     if (!${modelVar}) throw new Error('${model} not found');` : ""}`;
     }
   },
@@ -67,9 +129,22 @@ const MONGO_STEP_CONVENTIONS = [
         return `    // Step ${ctx.stepNum}: Find ${model} by ${f1} and ${f2} (already loaded)`;
       }
       declared.add(modelVar);
+      const resolveFieldSource = (f) => {
+        const stripIdMatch = f.match(/^(.+)Id$/);
+        if (stripIdMatch) {
+          const candidate = stripIdMatch[1];
+          if (candidate !== modelVar && declared.has(candidate)) {
+            return `(${candidate} as any)?._id ?? (${candidate} as any)?.id`;
+          }
+        }
+        return `args.${f}`;
+      };
+      const f1Src = resolveFieldSource(f1);
+      const f2Src = resolveFieldSource(f2);
       return `    // Step ${ctx.stepNum}: Find ${model} by ${f1} and ${f2}
     const ${modelVar}_collection = await getCollection('${collection}');
-    const ${modelVar} = await ${modelVar}_collection.findOne({ ${f1}: args.${f1}, ${f2}: args.${f2} });`;
+    let ${modelVar} = await ${modelVar}_collection.findOne({ ${f1}: ${f1Src}, ${f2}: ${f2Src} });
+    if (${modelVar} && !(${modelVar} as any).id && (${modelVar} as any)._id) (${modelVar} as any).id = String((${modelVar} as any)._id);`;
     }
   },
   // --- Create model record ---
@@ -227,6 +302,148 @@ const MONGO_STEP_CONVENTIONS = [
     }`;
     }
   },
+  // ──────────────────────────────────────────────────────────────────
+  // SIDE-EFFECT CONVENTIONS — patterns that the generator handles
+  // mechanically. The LLM never sees these; persistence happens
+  // deterministically from the spec text.
+  // ──────────────────────────────────────────────────────────────────
+  // --- Persist / Save / Store {Model} record ---
+  // Matches: "Persist refresh token for revocation tracking",
+  //          "Save user record", "Store session"
+  // Source of the record: most-recent step{N}Result if any (typical case
+  // — the prior AI step computed what to persist), else `args`.
+  {
+    name: "persist",
+    pattern: /^(?:persist|save|store)\s+(\w+(?:\s+\w+)?)(?:\s+(?:for|to|record).*)?$/i,
+    generateCall: (m, ctx) => {
+      const target = toVar(m[1].replace(/\s+(.)/g, (_, c) => c.toUpperCase()));
+      const collection = toCollection(target);
+      const recordSrc = mostRecentStepResult(ctx) ?? "args";
+      return `    // Step ${ctx.stepNum}: Persist ${m[1]}
+    {
+      const _coll = await getCollection('${collection}');
+      await _coll.insertOne(${recordSrc} && typeof ${recordSrc} === 'object' && !Array.isArray(${recordSrc}) ? ${recordSrc} as any : { value: ${recordSrc} });
+    }`;
+    }
+  },
+  // --- Conditional create: "If X does not exist, create new X with ..." ---
+  // Reuses the model variable already declared by a prior find; mutates
+  // it to point at the newly-created record so subsequent steps see it.
+  {
+    name: "conditional-create",
+    pattern: /^if\s+(\w+)\s+does\s+not\s+exist,?\s+create\s+new\s+(\w+)(?:\s+with\s+.+)?$/i,
+    generateCall: (m, ctx) => {
+      const modelVar = toVar(m[1]);
+      const Model = pascal(m[2]);
+      const collection = toCollection(Model);
+      if (!ctx.declaredVars?.has(modelVar)) return "";
+      const defaults = deriveModelDefaults(Model, ctx);
+      const defaultsBlock = defaults.length > 0 ? defaults.join(", ") + "," : "";
+      return `    // Step ${ctx.stepNum}: If ${modelVar} does not exist, create new ${Model}
+    if (!${modelVar}) {
+      const _newRecord = { ${defaultsBlock} ...args, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() };
+      const _ins = await (await getCollection('${collection}')).insertOne(_newRecord);
+      ${modelVar} = { _id: _ins.insertedId, id: String(_ins.insertedId), ..._newRecord } as any;
+    } else if (${modelVar} && !(${modelVar} as any).id && (${modelVar} as any)._id) {
+      (${modelVar} as any).id = String((${modelVar} as any)._id);
+    }`;
+    }
+  },
+  // --- Conditional update: "If X exists, update Y" ---
+  // Updates a single field on the previously-loaded record. Field defaults
+  // to lastLoginAt-style timestamp when the step says "update Y" without
+  // a "to <value>" clause.
+  {
+    name: "conditional-update",
+    pattern: /^if\s+(\w+)\s+exists,?\s+update\s+(\w+)(?:\s+(.+))?$/i,
+    generateCall: (m, ctx) => {
+      const modelVar = toVar(m[1]);
+      const field = m[2];
+      const collection = toCollection(m[1]);
+      if (!ctx.declaredVars?.has(modelVar)) return "";
+      return `    // Step ${ctx.stepNum}: If ${modelVar} exists, update ${field}
+    if (${modelVar}) {
+      await (await getCollection('${collection}')).updateOne(
+        { _id: ${modelVar}._id },
+        { $set: { ${field}: new Date().toISOString() } }
+      );
+    }`;
+    }
+  },
+  // --- Auto-create / Bulk fan-out create ---
+  // Matches: "Auto-create player profiles for all available games"
+  //          "Create X records for all Y"
+  // Pure-mechanical: enumerate the source collection, build a record per
+  // item linking it to the most-recently-loaded model var (typically
+  // `user`), insertMany. No AI hop — domain-specific field defaults are
+  // limited to the link fields (userId, gameId) plus createdAt/updatedAt.
+  // Anything richer should be done in a follow-up step (e.g. "Set displayName...").
+  {
+    name: "auto-create-loop",
+    pattern: /^(?:auto-create|bulk\s+create)\s+(\w+)\s+(?:profile|record|entry|entries)?s?\s+for\s+(?:all\s+)?(?:available\s+)?(\w+)$/i,
+    generateCall: (m, ctx) => {
+      const Model = pascal(m[1]);
+      const targetCollection = toCollection(Model);
+      const sourceCollection = m[2].toLowerCase();
+      const declared = Array.from(ctx.declaredVars || []);
+      const ownerVar = declared.find((v) => !/^step\d+Result$/.test(v) && v !== "args");
+      const sourceSingular = sourceCollection.replace(/s$/, "");
+      const linkField = sourceSingular + "Id";
+      const ownerLinkField = ownerVar ? ownerVar + "Id" : "ownerId";
+      const modelDefaults = deriveModelDefaults(Model, ctx);
+      const defaultsBlock = modelDefaults.length > 0 ? modelDefaults.filter((d) => !d.startsWith(`${ownerLinkField}:`) && !d.startsWith(`${linkField}:`)).join(", ") : "";
+      return `    // Step ${ctx.stepNum}: Auto-create ${m[1]} ${m[2]} for all ${m[2]}
+    {
+      const _allItems = await (await getCollection('${sourceCollection}')).find({}).toArray();
+      const _ownerId = ${ownerVar ? `(${ownerVar} as any)?.id ?? (${ownerVar} as any)?._id` : "null"};
+      const _records = _allItems.map((_item: any) => ({
+        ${defaultsBlock ? defaultsBlock + "," : ""}
+        ${ownerLinkField}: _ownerId,
+        ${linkField}: (_item as any).${sourceSingular}Id ?? (_item as any).id ?? String((_item as any)._id),
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      }));
+      if (_records.length > 0) {
+        await (await getCollection('${targetCollection}')).insertMany(_records as any);
+      }
+    }`;
+    }
+  },
+  // --- "Otherwise create new X record" — pairs with prior conditional ---
+  // Emitted as an `else` branch attached to the conditional that came
+  // before. We don't enforce ordering at the convention level; if the
+  // author writes "Otherwise" without a prior "If ... does not exist,
+  // create" the emitted else lands without an if and tsc catches it.
+  {
+    name: "otherwise-create",
+    pattern: /^otherwise\s+create\s+(?:new\s+)?(\w+)\s+record$/i,
+    generateCall: (m, ctx) => {
+      const Model = pascal(m[1]);
+      const modelVar = toVar(Model);
+      const collection = toCollection(Model);
+      const wasDeclared = ctx.declaredVars?.has(modelVar);
+      const declared = Array.from(ctx.declaredVars || []);
+      const defaults = deriveModelDefaults(Model, ctx);
+      const supplied = /* @__PURE__ */ new Set();
+      for (const entry of defaults) {
+        const colonIdx = entry.indexOf(":");
+        if (colonIdx > 0) supplied.add(entry.slice(0, colonIdx).trim());
+      }
+      const fkAssignments = declared.filter((v) => v !== modelVar && !/^step\d+Result$/.test(v) && v !== "args").filter((v) => !supplied.has(v + "Id")).map((v) => {
+        supplied.add(v + "Id");
+        return `${v}Id: (${v} as any)?._id ?? (${v} as any)?.id`;
+      }).join(", ");
+      const defaultsBlock = defaults.length > 0 ? defaults.join(", ") + "," : "";
+      ctx.declaredVars?.add(modelVar);
+      return `    // Step ${ctx.stepNum}: Otherwise create new ${Model} record
+    else {
+      const _newRecord = { ${defaultsBlock} ${fkAssignments ? fkAssignments + "," : ""} ...args, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() };
+      const _ins = await (await getCollection('${collection}')).insertOne(_newRecord);
+      ${wasDeclared ? `${modelVar} = { _id: _ins.insertedId, id: String(_ins.insertedId), ..._newRecord } as any;` : `const ${modelVar} = { _id: _ins.insertedId, id: String(_ins.insertedId), ..._newRecord };
+      void ${modelVar};`}
+    }`;
+    }
+  },
   // --- Send/Emit/Publish event ---
   // Emits an eventBus.publish call. The payload references the controller's
   // primary model variable IF it was declared by a prior matched step;
@@ -288,32 +505,11 @@ const MONGO_STEP_CONVENTIONS = [
   }
 ];
 function matchMongoStep(step, ctx) {
-  for (const convention of MONGO_STEP_CONVENTIONS) {
-    const m = step.match(convention.pattern);
-    if (m) {
-      const call = convention.generateCall(m, ctx);
-      if (call) {
-        return { matched: true, call };
-      }
-    }
-  }
-  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 = inputs.length > 0 ? `{ ${inputs.map((n) => paramNames.includes(n) ? `${n}: args.${n}` : n).join(", ")} }` : "{}";
-  return {
-    matched: false,
-    call: `    // Step ${ctx.stepNum}: ${step} [AI-generated \u2014 pure function]
-    const ${resultVar} = await aiBehaviors.${functionName}(${inputObj});`,
-    functionName,
-    inputs,
-    resultVar
-  };
+  const aiArgsExpr = (inputs, paramNames) => inputs.length > 0 ? `{ ${inputs.map((n) => paramNames.includes(n) ? `${n}: args.${n}` : n).join(", ")} }` : "{}";
+  return matchAgainstConventions(step, ctx, MONGO_STEP_CONVENTIONS, aiArgsExpr);
 }
 export {
   MONGO_STEP_CONVENTIONS,
+  deriveModelDefaults,
   matchMongoStep
 };

package/dist/libs/instance-factories/services/templates/postgres-native/client-generator.js

@@ -0,0 +1,165 @@
+function generatePgClient(_context) {
+  return `/**
+ * Postgres native (pg) \u2014 singleton pool + helpers.
+ *
+ * Picks up POSTGRES_URL or DATABASE_URL from the environment. The pool is
+ * lazily initialised on first use and reused across requests; \`disconnect\`
+ * is exposed for graceful-shutdown wiring. \`withTx\` runs a callback in a
+ * single connection inside BEGIN/COMMIT (rolled back on throw).
+ */
+import { Pool, type PoolClient, type QueryResult, type QueryResultRow } from 'pg';
+
+const connectionString =
+  process.env.POSTGRES_URL ||
+  process.env.DATABASE_URL ||
+  'postgres://postgres:postgres@localhost:5432/specverse';
+
+let pool: Pool | null = null;
+
+export function getPool(): Pool {
+  if (pool) return pool;
+  pool = new Pool({ connectionString });
+  return pool;
+}
+
+/** Run a parameterised query against the pool.
+ *  T defaults to QueryResultRow so callers can pass a row interface. */
+export async function query<T extends QueryResultRow = QueryResultRow>(
+  text: string,
+  params: ReadonlyArray<unknown> = [],
+): Promise<QueryResult<T>> {
+  return getPool().query<T>(text, params as unknown[]);
+}
+
+/** Run a callback inside a transaction. The callback receives a dedicated
+ *  client; commit on resolve, rollback on throw. */
+export async function withTx<T>(
+  fn: (client: PoolClient) => Promise<T>,
+): Promise<T> {
+  const client = await getPool().connect();
+  try {
+    await client.query('BEGIN');
+    const result = await fn(client);
+    await client.query('COMMIT');
+    return result;
+  } catch (err) {
+    await client.query('ROLLBACK');
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+/** Build a comma-separated list of \`"col"\` from an object's keys, plus
+ *  matching positional placeholders \`$1, $2, ...\`. Quoted to preserve
+ *  case-sensitive identifiers (camelCase columns work without folding). */
+function buildPositionals(keys: string[], offset = 0): string {
+  return keys.map((_k, i) => '$' + (i + 1 + offset)).join(', ');
+}
+function quoteCols(keys: string[]): string {
+  return keys.map((k) => '"' + k.replace(/"/g, '""') + '"').join(', ');
+}
+
+/** INSERT a record into \`table\` and return the inserted row (with any
+ *  database-supplied defaults like generated id / createdAt populated). */
+export async function insertOne<T extends QueryResultRow = QueryResultRow>(
+  table: string,
+  record: Record<string, unknown>,
+): Promise<T> {
+  const keys = Object.keys(record);
+  const values = keys.map((k) => record[k]);
+  const sql = keys.length === 0
+    ? \`INSERT INTO "\${table}" DEFAULT VALUES RETURNING *\`
+    : \`INSERT INTO "\${table}" (\${quoteCols(keys)}) VALUES (\${buildPositionals(keys)}) RETURNING *\`;
+  const result = await query<T>(sql, values);
+  return result.rows[0] as T;
+}
+
+/** Bulk-insert many records into \`table\` in one round trip. Returns the
+ *  inserted rows. All records must share the same shape. */
+export async function insertMany<T extends QueryResultRow = QueryResultRow>(
+  table: string,
+  records: ReadonlyArray<Record<string, unknown>>,
+): Promise<T[]> {
+  if (records.length === 0) return [];
+  const firstKeys = Object.keys(records[0]!);
+  const valuesClauses: string[] = [];
+  const flatValues: unknown[] = [];
+  for (let i = 0; i < records.length; i++) {
+    const row = records[i] as Record<string, unknown>;
+    const placeholders = firstKeys.map((_k, j) => '$' + (i * firstKeys.length + j + 1)).join(', ');
+    valuesClauses.push('(' + placeholders + ')');
+    for (const k of firstKeys) flatValues.push(row[k]);
+  }
+  const sql = \`INSERT INTO "\${table}" (\${quoteCols(firstKeys)}) VALUES \${valuesClauses.join(', ')} RETURNING *\`;
+  const result = await query<T>(sql, flatValues);
+  return result.rows;
+}
+
+/** SELECT a single row by a field equality. Returns null if not found. */
+export async function findOneByField<T extends QueryResultRow = QueryResultRow>(
+  table: string,
+  field: string,
+  value: unknown,
+): Promise<T | null> {
+  const sql = \`SELECT * FROM "\${table}" WHERE "\${field.replace(/"/g, '""')}" = $1 LIMIT 1\`;
+  const result = await query<T>(sql, [value]);
+  return result.rows[0] ?? null;
+}
+
+/** SELECT a single row matching all (field, value) pairs (AND-ed). */
+export async function findOneByFields<T extends QueryResultRow = QueryResultRow>(
+  table: string,
+  fields: Record<string, unknown>,
+): Promise<T | null> {
+  const keys = Object.keys(fields);
+  if (keys.length === 0) {
+    const result = await query<T>(\`SELECT * FROM "\${table}" LIMIT 1\`);
+    return result.rows[0] ?? null;
+  }
+  const where = keys.map((k, i) => '"' + k.replace(/"/g, '""') + '" = $' + (i + 1)).join(' AND ');
+  const sql = \`SELECT * FROM "\${table}" WHERE \${where} LIMIT 1\`;
+  const result = await query<T>(sql, keys.map((k) => fields[k]));
+  return result.rows[0] ?? null;
+}
+
+/** SELECT all rows from a table \u2014 equivalent to a Mongo
+ *  \`collection.find({}).toArray()\` for the bulk-fan-out auto-create
+ *  convention. */
+export async function findAll<T extends QueryResultRow = QueryResultRow>(
+  table: string,
+): Promise<T[]> {
+  const result = await query<T>(\`SELECT * FROM "\${table}"\`);
+  return result.rows;
+}
+
+/** UPDATE columns of the row identified by id. Quotes column names so
+ *  camelCase identifiers survive postgres' default lower-case folding. */
+export async function updateOneById(
+  table: string,
+  id: unknown,
+  patch: Record<string, unknown>,
+): Promise<void> {
+  const keys = Object.keys(patch);
+  if (keys.length === 0) return;
+  const setClause = keys.map((k, i) => '"' + k.replace(/"/g, '""') + '" = $' + (i + 1)).join(', ');
+  const sql = \`UPDATE "\${table}" SET \${setClause} WHERE "id" = $\${keys.length + 1}\`;
+  await query(sql, [...keys.map((k) => patch[k]), id]);
+}
+
+/** DELETE the row identified by id. */
+export async function deleteOneById(table: string, id: unknown): Promise<void> {
+  await query(\`DELETE FROM "\${table}" WHERE "id" = $1\`, [id]);
+}
+
+export async function disconnect(): Promise<void> {
+  if (pool) {
+    await pool.end();
+    pool = null;
+  }
+}
+`;
+}
+export {
+  generatePgClient as default
+};