@specverse/engines 6.7.8 → 6.16.0

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

@@ -0,0 +1,193 @@
+/**
+ * Regression tests for the PostgreSQL native (pg) controller generator.
+ *
+ * Mirrors the mongodb-native suite — the conventions are intentionally
+ * the same shape so spec authors can swap factories without rewriting
+ * .specly text. These tests pin shape, not full compilation:
+ *
+ *   - CURVED ops emit pg helper calls (insertOne / findOneByField /
+ *     updateOneById / deleteOneById / findAll / query)
+ *   - Lifecycle transitions decode flow shorthand and emit a transition map
+ *   - Behaviour-derived actions colliding with CRUD names emit a warning
+ *     and are dropped (shared with mongo)
+ *   - Custom action steps run through `matchPgStep` (CRUD-shape steps
+ *     map to inline helper calls, the rest delegate to aiBehaviors)
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import generatePgNativeController from '../controller-generator.js';
+
+const baseModel = {
+  name: 'Todo',
+  attributes: {
+    id: { name: 'id', type: 'UUID', required: true, auto: 'uuid4' },
+    title: { name: 'title', type: 'String', required: true },
+    completed: { name: 'completed', type: 'Boolean', default: false },
+  },
+};
+
+const baseController = {
+  name: 'TodoController',
+  description: 'Controller for Todo',
+  cured: { create: true, retrieve: true, update: true, evolve: true, delete: true },
+};
+
+describe('Postgres native — controller-generator', () => {
+  it('emits all CURVED ops via pgClient helpers', () => {
+    const out = generatePgNativeController({
+      controller: baseController,
+      model: baseModel,
+    } as any);
+    expect(out).toContain(`TABLE_NAME = 'todos'`);
+    expect(out).toContain('insertOne');
+    expect(out).toContain('findOneByField');
+    expect(out).toContain('updateOneById');
+    expect(out).toContain('deleteOneById');
+    expect(out).toContain('findAll');
+    expect(out).not.toContain('PrismaClient');
+    expect(out).not.toContain('prisma.');
+    expect(out).not.toContain('getCollection');
+  });
+
+  it('does NOT import ObjectId — pg uses string ids end-to-end', () => {
+    const out = generatePgNativeController({
+      controller: baseController,
+      model: baseModel,
+    } as any);
+    expect(out).not.toContain('ObjectId');
+    expect(out).not.toContain('mongodb');
+  });
+
+  it('emits lifecycle transition map for `flow:` shorthand', () => {
+    const out = generatePgNativeController({
+      controller: baseController,
+      model: {
+        ...baseModel,
+        lifecycles: { status: { name: 'status', flow: 'pending -> done' } },
+      },
+    } as any);
+    expect(out).toContain('public async evolve(');
+    expect(out).toContain('"pending":["done"]');
+    expect(out).toContain('Invalid transition');
+  });
+
+  it('emits a working multi-state transition map for explicit states', () => {
+    const out = generatePgNativeController({
+      controller: baseController,
+      model: {
+        ...baseModel,
+        lifecycles: {
+          status: {
+            name: 'status',
+            states: ['draft', 'open', 'closed'],
+            transitions: { open: 'draft -> open', close: 'open -> closed' },
+          },
+        },
+      },
+    } as any);
+    expect(out).toContain('"draft":["open"]');
+    expect(out).toContain('"open":["closed"]');
+  });
+
+  it('uses model.storage.table override when present', () => {
+    const out = generatePgNativeController({
+      controller: baseController,
+      model: { ...baseModel, storage: { table: 'custom_todos' } },
+    } as any);
+    expect(out).toContain(`TABLE_NAME = 'custom_todos'`);
+    expect(out).toContain('TABLE_NAME');
+  });
+
+  it('omits CURVED ops not declared on the controller', () => {
+    const out = generatePgNativeController({
+      controller: { ...baseController, cured: { retrieve: true } },
+      model: baseModel,
+    } as any);
+    expect(out).toContain('public async retrieve(');
+    expect(out).not.toContain('public async create(');
+    expect(out).not.toContain('public async update(');
+    expect(out).not.toContain('public async delete(');
+    expect(out).not.toContain('public async evolve(');
+  });
+
+  describe('behaviour-derived actions', () => {
+    let warnSpy: ReturnType<typeof vi.spyOn>;
+    beforeEach(() => {
+      warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    });
+    afterEach(() => {
+      warnSpy.mockRestore();
+    });
+
+    it('warns + drops behaviour-derived actions colliding with CRUD names', () => {
+      const out = generatePgNativeController({
+        controller: {
+          ...baseController,
+          actions: {
+            delete: {
+              description: 'Soft-delete a todo',
+              parameters: { id: 'String' },
+              steps: ['Set deletedAt to now'],
+            },
+          },
+        },
+        model: baseModel,
+      } as any);
+      // The custom delete should NOT be emitted (collides with CRUD delete).
+      // Generator emits exactly one `public async delete(` (the CRUD op).
+      const deleteMatches = out.match(/public async delete\(/g) || [];
+      expect(deleteMatches.length).toBe(1);
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      const warnMsg = String(warnSpy.mock.calls[0]?.[0] ?? '');
+      expect(warnMsg).toContain('TodoController.delete');
+      expect(warnMsg).toContain('collides');
+    });
+
+    it('runs steps through matchPgStep — CRUD-shape steps inline pg helpers', () => {
+      const out = generatePgNativeController({
+        controller: {
+          ...baseController,
+          actions: {
+            archive: {
+              description: 'Archive a todo by id',
+              parameters: { id: 'String' },
+              steps: [
+                'Find Todo by id or fail with 404',
+                'Update Todo completed to true',
+                'Emit TodoArchived event',
+              ],
+            },
+          },
+        },
+        model: baseModel,
+      } as any);
+      expect(out).toContain('public async archive(');
+      // Step 1: find-by-field convention
+      expect(out).toContain(`findOneByField('todos', 'id', args.id)`);
+      // Step 2: update-field convention
+      expect(out).toContain(`updateOneById('todos', todo.id, { completed: true })`);
+      // Step 3: send-event convention
+      expect(out).toContain(`eventBus.publish('TodoArchived'`);
+    });
+
+    it('falls back to AI-behaviors for unmatched steps', () => {
+      const out = generatePgNativeController({
+        controller: {
+          ...baseController,
+          actions: {
+            score: {
+              description: 'Compute a todo priority score',
+              parameters: { id: 'String' },
+              steps: [
+                'Compute priority score from urgency and effort',
+                'Return score',
+              ],
+            },
+          },
+        },
+        model: baseModel,
+      } as any);
+      expect(out).toContain(`aiBehaviors.computePriorityScoreFromUrgencyAndEffort`);
+      expect(out).toContain(`from '../behaviors/TodoController.ai.js'`);
+    });
+  });
+});

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

@@ -0,0 +1,178 @@
+/**
+ * Postgres native (pg) — pool singleton.
+ *
+ * Emits a small connection module shared by all controllers and services.
+ * Table-naming convention: lowercase + 's' suffix (User → users), matching
+ * the lowercase-pluralized scheme declared in the factory yaml. Models with
+ * custom table names override via `model.storage?.table` (the
+ * controller-generator looks there first).
+ *
+ * Connection priority: POSTGRES_URL > DATABASE_URL > localhost default.
+ * Both URL forms are widely accepted by hosting providers (Supabase, Neon,
+ * Railway, Render). The pool is lazily initialised on first use and reused;
+ * `disconnect` is exposed for graceful-shutdown wiring.
+ */
+import type { TemplateContext } from '@specverse/types';
+
+export default function generatePgClient(_context: TemplateContext): string {
+  return `/**
+ * Postgres native (pg) — 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 — 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;
+  }
+}
+`;
+}