@specverse/engines 6.7.8 → 6.16.0

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

@@ -0,0 +1,372 @@
+/**
+ * PostgreSQL Native (pg) — Controller Generator
+ *
+ * Generates per-model controllers exposing CURVED operations via the pg
+ * pool helpers (`insertOne` / `findOneByField` / `updateOneById` / etc.).
+ * Same shape and same behaviour as the mongodb-native counterpart — the
+ * only differences are runtime-driver calls.
+ *
+ * Scope (MVP):
+ *   - Validate / Create / Retrieve / Update / Delete fully wired
+ *   - Evolve emits a lifecycle-aware update when the model declares states;
+ *     transitions are validated against the declared flow before update
+ *   - Custom actions emit per-step bodies via `matchPgStep`. The same
+ *     matcher is passed to the AI-behaviors-generator (via realize/index.ts)
+ *     so both sides agree on `declaredVars`, function names, and inputs.
+ *
+ * Out of scope:
+ *   - withTx() multi-statement transactions for create/update flows
+ *     (deferred — current MVP commits each helper call individually)
+ *   - JOIN-driven retrieve variants (deferred)
+ *
+ * Table naming: lowercase + 's' (User → users) unless the model declares
+ * `storage.table`. ID is a string at the API surface; the pgClient helpers
+ * pass the value through as-is so UUIDs / slugs / int-as-string all work.
+ */
+import type { TemplateContext } from '@specverse/types';
+import { buildTransitionMap, isAutoField } from '@specverse/types/spec-rules';
+
+export default function generatePgNativeController(context: TemplateContext): string {
+  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');
+
+  const controllerName = controller.name;
+  const modelName = model.name;
+  const modelVar = lowerFirst(modelName);
+  const table = tableName(model);
+  const curedOps = controller.cured || {};
+
+  // 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.
+  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(modelName, modelVar) : '';
+  const retrieve = curedOps.retrieve ? generateRetrieveMethod(modelName, modelVar) : '';
+  const update = curedOps.update ? generateUpdateMethod(modelName, modelVar) : '';
+  const evolve = curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar) : '';
+  const del = curedOps.delete ? generateDeleteMethod(modelName, modelVar) : '';
+
+  const hasEventPublishing =
+    curedOps.create || curedOps.update || curedOps.evolve || curedOps.delete;
+
+  // Helpers always imported: insertOne / findOneByField / findAll /
+  // updateOneById / deleteOneById are referenced by the CRUD ops; `query`
+  // is referenced by retrieveAll's offset path. The composite + bulk
+  // helpers are conditional — only the convention-driven step bodies
+  // emit them, so we scan the customActions.code to decide.
+  const helperImports = [
+    'insertOne',
+    'findOneByField',
+    'findAll',
+    'updateOneById',
+    'deleteOneById',
+    'query',
+    customActions.code.includes('findOneByFields(') ? 'findOneByFields' : '',
+    customActions.code.includes('insertMany(') ? 'insertMany' : '',
+  ].filter(Boolean).join(', ');
+
+  return `/**
+ * ${controllerName}
+ * Model-specific business logic for ${modelName} (PostgreSQL native driver)
+ * ${controller.description || ''}
+ */
+import { ${helperImports} } from '../db/pgClient.js';
+${hasEventPublishing || customActions.needsAiBehaviors ? `import { eventBus } from '../events/eventBus.js';` : ''}
+${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${controllerName}.ai.js';` : ''}
+
+const TABLE_NAME = '${table}';
+
+export class ${controllerName} {
+${validate}
+${create}
+${retrieve}
+${update}
+${evolve}
+${del}
+${customActions.code}
+}
+
+export const ${modelVar}Controller = new ${controllerName}();
+export default ${modelVar}Controller;
+`;
+}
+
+function lowerFirst(s: string): string {
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}
+
+function tableName(model: any): string {
+  if (model?.storage?.table) return String(model.storage.table);
+  // Lowercase-pluralized: User → users, OrderItem → orderitems
+  return model.name.toLowerCase() + 's';
+}
+
+function generateValidateMethod(model: any, modelName: string): string {
+  return `
+  /**
+   * Validate ${modelName} data — runs before create / update / evolve.
+   */
+  public validate(
+    _data: any,
+    _context: { operation: 'create' | 'update' | 'evolve' }
+  ): { valid: boolean; errors: string[] } {
+    const errors: string[] = [];
+${generateValidationLogic(model)}
+    return { valid: errors.length === 0, errors };
+  }
+`;
+}
+
+function generateValidationLogic(model: any): string {
+  if (!model.attributes) return '    // No validation rules defined';
+  const attrList = Array.isArray(model.attributes)
+    ? model.attributes.map((a: any) => [a.name, a])
+    : Object.entries(model.attributes);
+  const out: string[] = [];
+  attrList.forEach(([name, attr]: [string, any]) => {
+    if (attr.required && !isAutoField(name, attr)) {
+      out.push(`    if (_context.operation === 'create' && !_data.${name}) errors.push('${name} is required');`);
+    }
+    if (attr.type === 'String' || attr.type === 'string') {
+      if (attr.min) out.push(`    if (_data.${name} && _data.${name}.length < ${attr.min}) errors.push('${name} must be at least ${attr.min} characters');`);
+      if (attr.max) out.push(`    if (_data.${name} && _data.${name}.length > ${attr.max}) errors.push('${name} must be at most ${attr.max} characters');`);
+    }
+    if (attr.values && Array.isArray(attr.values)) {
+      const values = attr.values.map((v: string) => `'${v}'`).join(', ');
+      out.push(`    if (_data.${name} && ![${values}].includes(_data.${name})) errors.push('${name} must be one of: ${attr.values.join(', ')}');`);
+    }
+    if (attr.format === 'email') {
+      out.push(`    if (_data.${name} && !/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(_data.${name})) errors.push('${name} must be a valid email address');`);
+    }
+  });
+  return out.join('\n') || '    // No validation rules defined';
+}
+
+function generateCreateMethod(modelName: string, modelVar: string): string {
+  return `
+  /**
+   * Create a new ${modelName}.
+   */
+  public async create(data: any): Promise<any> {
+    const validation = this.validate(data, { operation: 'create' });
+    if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
+
+    const ${modelVar} = await insertOne(TABLE_NAME, { ...data });
+
+    await eventBus.publish('${modelName}Created', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    return ${modelVar};
+  }
+`;
+}
+
+function generateRetrieveMethod(modelName: string, _modelVar: string): string {
+  return `
+  /**
+   * Retrieve ${modelName} by id. Returns null when not found.
+   */
+  public async retrieve(id: string): Promise<any | null> {
+    return await findOneByField(TABLE_NAME, 'id', id);
+  }
+
+  /**
+   * Retrieve a page of ${modelName}s.
+   */
+  public async retrieveAll(options: { skip?: number; take?: number } = {}): Promise<any[]> {
+    if (!options.skip && !options.take) {
+      return await findAll(TABLE_NAME);
+    }
+    const limit = options.take ?? 100;
+    const offset = options.skip ?? 0;
+    const result = await query(\`SELECT * FROM "\${TABLE_NAME}" LIMIT $1 OFFSET $2\`, [limit, offset]);
+    return result.rows;
+  }
+`;
+}
+
+function generateUpdateMethod(modelName: string, modelVar: string): string {
+  return `
+  /**
+   * Update ${modelName}.
+   */
+  public async update(id: string, data: any): Promise<any> {
+    const validation = this.validate(data, { operation: 'update' });
+    if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
+
+    // Strip nested objects + id — only scalar fields are written.
+    const updateData: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (key === 'id') continue;
+      if (Array.isArray(value)) continue;
+      if (value !== null && typeof value === 'object' && !(value instanceof Date)) continue;
+      updateData[key] = value;
+    }
+
+    await updateOneById(TABLE_NAME, id, updateData);
+    const ${modelVar} = await findOneByField(TABLE_NAME, 'id', id);
+    if (!${modelVar}) throw new Error('${modelName} not found after update');
+
+    await eventBus.publish('${modelName}Updated', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    return ${modelVar};
+  }
+`;
+}
+
+function generateEvolveMethod(model: any, modelName: string, modelVar: string): string {
+  const lifecycles = Array.isArray(model.lifecycles)
+    ? model.lifecycles
+    : (model.lifecycles ? Object.entries(model.lifecycles).map(([name, lc]: [string, any]) => ({ name, ...lc })) : []);
+  const lifecycle = lifecycles[0];
+  const lifecycleName = lifecycle?.name || 'status';
+  const validTransitions = lifecycle ? buildTransitionMap(lifecycle) : {};
+  const states = lifecycle?.states && lifecycle.states.length > 0
+    ? lifecycle.states.map((s: any) => typeof s === 'string' ? s : s.name)
+    : Array.from(new Set([
+        ...Object.keys(validTransitions),
+        ...Object.values(validTransitions).flat(),
+      ]));
+
+  return `
+  /**
+   * Evolve ${modelName} through lifecycle "${lifecycleName}"
+   * States: ${states.join(' → ') || '(none declared)'}
+   */
+  public async evolve(id: string, data: any): Promise<any> {
+    const current = await findOneByField(TABLE_NAME, 'id', id);
+    if (!current) throw new Error('${modelName} not found');
+
+    const targetLifecycle = data?.lifecycleName || '${lifecycleName}';
+    const targetState = data?.toState ?? data?.state ?? data?.[targetLifecycle];
+    if (!targetState) throw new Error('evolve requires toState (or ${lifecycleName}) in the request body');
+
+    ${states.length > 0 ? `
+    const currentState = (current as any)[targetLifecycle];
+    const validTransitions: Record<string, string[]> = ${JSON.stringify(validTransitions)};
+    const allowed = validTransitions[currentState] || [];
+    if (!allowed.includes(targetState)) {
+      throw new Error(\`Invalid transition: \${currentState} → \${targetState}. Allowed: \${allowed.join(', ') || 'none'}\`);
+    }
+    ` : ''}
+
+    await updateOneById(TABLE_NAME, id, { [targetLifecycle]: targetState });
+    const ${modelVar} = await findOneByField(TABLE_NAME, 'id', id);
+    if (!${modelVar}) throw new Error('${modelName} not found after evolve');
+
+    await eventBus.publish('${modelName}Evolved', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    return ${modelVar};
+  }
+`;
+}
+
+function generateDeleteMethod(modelName: string, modelVar: string): string {
+  return `
+  /**
+   * Delete ${modelName}.
+   */
+  public async delete(id: string): Promise<void> {
+    const ${modelVar} = await findOneByField(TABLE_NAME, 'id', id);
+    await deleteOneById(TABLE_NAME, id);
+    if (${modelVar}) {
+      await eventBus.publish('${modelName}Deleted', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    }
+  }
+`;
+}
+
+interface CustomActionsResult {
+  code: string;
+  needsAiBehaviors: boolean;
+}
+
+import { matchPgStep, type PgStepContext } from './step-conventions.js';
+
+function generateCustomActions(controller: any, modelRegistry: Record<string, 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 tableNameLocal = modelName.toLowerCase() + 's';
+  const out: string[] = [];
+  let needsAiBehaviors = false;
+  for (const [actionName, action] of Object.entries<any>(controller.actions)) {
+    if (CRUD_NAMES.has(actionName)) {
+      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: PgStepContext = {
+        modelName,
+        tableName: tableNameLocal,
+        serviceName: controller.name || 'Controller',
+        operationName: actionName,
+        stepNum: i + 1,
+        parameterNames: Object.keys(action.parameters || {}),
+        declaredVars,
+        models: modelRegistry,
+      };
+      const result = matchPgStep(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 unused step{N}Result locals (strict tsc's noUnusedLocals applies
+    // even to underscored names — same logic as the mongo controller).
+    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) {
+        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}
+   * ${action.description || ''}
+   *
+   * Spec steps:
+${stepsHeader}
+   */
+  public async ${actionName}(${argsParam}): Promise<any> {
+${body}
+  }
+`);
+  }
+  return { code: out.join('\n'), needsAiBehaviors };
+}

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

@@ -0,0 +1,236 @@
+/**
+ * Postgres native (pg) — schema.sql DDL generator.
+ *
+ * Emits a single `schema.sql` script with one CREATE TABLE statement per
+ * spec model, plus indexes derived from `unique` and FK declarations.
+ * Designed to be run via `npm run db:setup` (which pipes the file through
+ * `psql "$POSTGRES_URL"`). Idempotent: every CREATE is `IF NOT EXISTS`.
+ *
+ * Type mapping (best-effort, kept simple):
+ *   String, UUID, Text, Email     → TEXT
+ *   Integer, Int                  → INTEGER
+ *   BigInt                        → BIGINT
+ *   Float, Number                 → DOUBLE PRECISION
+ *   Boolean                       → BOOLEAN
+ *   DateTime, Date                → TIMESTAMPTZ
+ *   Json                          → JSONB
+ *
+ * Primary key:
+ *   - `id UUID required`            → id UUID PRIMARY KEY DEFAULT gen_random_uuid()
+ *   - any other "id" required       → id TEXT PRIMARY KEY
+ *
+ * Out of scope (deferred): partial indexes, RLS policies, check constraints
+ * derived from `min/max` ranges, composite keys.
+ */
+import type { TemplateContext } from '@specverse/types';
+
+export default function generatePgSchemaSql(context: TemplateContext): string {
+  const { spec, models } = context as any;
+
+  // Pull a flat list of {modelName, model} from the most-likely shapes:
+  //   1. Realize passes `models` (array of model specs from the resolved
+  //      component); use it directly.
+  //   2. Otherwise walk spec.components[].models.
+  const allModels: Array<[string, any]> = [];
+  if (Array.isArray(models) && models.length > 0) {
+    for (const m of models) if (m?.name) allModels.push([m.name, m]);
+  } else if (spec?.components) {
+    const components = Array.isArray(spec.components)
+      ? spec.components
+      : Object.values(spec.components);
+    for (const comp of components as any[]) {
+      const ms = comp?.models;
+      if (!ms) continue;
+      const entries: [string, any][] = Array.isArray(ms)
+        ? ms.map((m: any) => [m.name, m])
+        : Object.entries(ms);
+      for (const [name, m] of entries) {
+        if (name) allModels.push([name, m]);
+      }
+    }
+  }
+
+  const banner = `-- ============================================================
+-- ${spec?.metadata?.component || 'Application'} — schema.sql
+-- Generated by @specverse/engines (postgres-native).
+-- Run via: psql "$POSTGRES_URL" -f src/db/schema.sql
+-- Re-runnable: every statement is IF NOT EXISTS / idempotent.
+-- ============================================================
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";  -- for gen_random_uuid()
+`;
+
+  if (allModels.length === 0) {
+    return banner + '\n-- No models declared. (Add one to your spec to populate this file.)\n';
+  }
+
+  const tableBlocks = allModels.map(([name, model]) => generateTable(name, model));
+  return banner + '\n' + tableBlocks.join('\n\n') + '\n';
+}
+
+function generateTable(modelName: string, model: any): string {
+  const table = model?.storage?.table || (modelName.toLowerCase() + 's');
+  const attrs = model.attributes;
+  if (!attrs) {
+    return `-- ${modelName}\nCREATE TABLE IF NOT EXISTS "${table}" (\n  id TEXT PRIMARY KEY\n);`;
+  }
+  const list: [string, any][] = Array.isArray(attrs)
+    ? attrs.map((a: any) => [a.name, a])
+    : Object.entries(attrs);
+
+  const columns: string[] = [];
+  const indexes: string[] = [];
+  let hasIdColumn = false;
+
+  for (const [colName, attr] of list) {
+    if (!colName) continue;
+    const { sql, isPk, isUnique } = columnDef(colName, attr, modelName);
+    if (isPk) hasIdColumn = true;
+    columns.push('  ' + sql);
+    if (isUnique && !isPk) {
+      indexes.push(
+        `CREATE UNIQUE INDEX IF NOT EXISTS "${table}_${colName}_uq" ON "${table}" ("${colName}");`,
+      );
+    } else if (colName.endsWith('Id') && colName !== 'id') {
+      // FK columns — index for join performance.
+      indexes.push(
+        `CREATE INDEX IF NOT EXISTS "${table}_${colName}_idx" ON "${table}" ("${colName}");`,
+      );
+    }
+  }
+
+  // No id declared in spec — synthesise one so the table is keyed.
+  if (!hasIdColumn) {
+    columns.unshift('  "id" TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text');
+  }
+
+  // createdAt / updatedAt — provide defaults if not declared.
+  const declaredNames = new Set(list.map(([n]) => n));
+  if (!declaredNames.has('createdAt')) {
+    columns.push('  "createdAt" TIMESTAMPTZ NOT NULL DEFAULT NOW()');
+  }
+  if (!declaredNames.has('updatedAt')) {
+    columns.push('  "updatedAt" TIMESTAMPTZ NOT NULL DEFAULT NOW()');
+  }
+
+  // Lifecycle columns — for every declared lifecycle, add a TEXT column
+  // (named after the lifecycle, defaulting to its first state) so
+  // controller.evolve has somewhere to write the transitioned state.
+  // Mongo is schemaless so this happens implicitly there; in postgres we
+  // need an explicit column.
+  const lifecycles = Array.isArray(model.lifecycles)
+    ? model.lifecycles
+    : (model.lifecycles ? Object.entries(model.lifecycles).map(([name, lc]: [string, any]) => ({ name, ...lc })) : []);
+  for (const lc of lifecycles) {
+    const lcName = lc?.name;
+    if (!lcName || declaredNames.has(lcName)) continue;
+    const initial = deriveInitialState(lc);
+    const defaultClause = initial ? ` DEFAULT '${initial.replace(/'/g, "''")}'` : '';
+    columns.push(`  "${lcName}" TEXT NOT NULL${defaultClause}`);
+  }
+
+  const indexBlock = indexes.length > 0 ? '\n\n' + indexes.join('\n') : '';
+  return `-- ${modelName}\nCREATE TABLE IF NOT EXISTS "${table}" (\n${columns.join(',\n')}\n);${indexBlock}`;
+}
+
+interface ColumnDefResult {
+  sql: string;
+  isPk: boolean;
+  isUnique: boolean;
+}
+
+function columnDef(name: string, attr: any, _modelName: string): ColumnDefResult {
+  const required = !!attr.required;
+  const unique = !!attr.unique;
+  const type = (attr.type || 'String').toLowerCase();
+  const isIdColumn = name === 'id';
+
+  if (isIdColumn) {
+    if (type === 'uuid') {
+      return { sql: `"id" UUID PRIMARY KEY DEFAULT gen_random_uuid()`, isPk: true, isUnique: true };
+    }
+    return { sql: `"id" TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text`, isPk: true, isUnique: true };
+  }
+
+  let sqlType: string;
+  switch (type) {
+    case 'integer':
+    case 'int':
+      sqlType = 'INTEGER';
+      break;
+    case 'bigint':
+      sqlType = 'BIGINT';
+      break;
+    case 'float':
+    case 'number':
+    case 'double':
+      sqlType = 'DOUBLE PRECISION';
+      break;
+    case 'boolean':
+    case 'bool':
+      sqlType = 'BOOLEAN';
+      break;
+    case 'datetime':
+    case 'date':
+    case 'timestamp':
+      sqlType = 'TIMESTAMPTZ';
+      break;
+    case 'uuid':
+      sqlType = 'UUID';
+      break;
+    case 'json':
+    case 'jsonb':
+      sqlType = 'JSONB';
+      break;
+    default:
+      sqlType = 'TEXT';
+  }
+
+  const nullness = required ? ' NOT NULL' : '';
+  const uniqueClause = unique ? ' UNIQUE' : '';
+  const defaultClause = formatColumnDefault(attr.default, type);
+  return {
+    sql: `"${name}" ${sqlType}${nullness}${uniqueClause}${defaultClause}`,
+    isPk: false,
+    isUnique: unique,
+  };
+}
+
+/** Derive the initial state from a lifecycle declaration. Handles:
+ *  - explicit `initial: stateName`
+ *  - explicit states[] array — first entry
+ *  - `flow: "a -> b -> c"` shorthand — first arrow-source
+ */
+function deriveInitialState(lc: any): string | null {
+  if (!lc) return null;
+  if (typeof lc.initial === 'string') return lc.initial;
+  if (Array.isArray(lc.states) && lc.states.length > 0) {
+    const first = lc.states[0];
+    return typeof first === 'string' ? first : (first?.name ?? null);
+  }
+  if (typeof lc.flow === 'string') {
+    const head = lc.flow.split(/\s*->\s*/)[0]?.trim();
+    return head || null;
+  }
+  if (lc.transitions && typeof lc.transitions === 'object') {
+    // Pick the source side of the first transition.
+    const first = Object.values(lc.transitions)[0];
+    if (typeof first === 'string') return first.split(/\s*->\s*/)[0]?.trim() || null;
+  }
+  return null;
+}
+
+function formatColumnDefault(value: any, type: string): string {
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'boolean') return ` DEFAULT ${value}`;
+  if (typeof value === 'number') return ` DEFAULT ${value}`;
+  if (typeof value === 'string') {
+    if (/^-?\d+(\.\d+)?$/.test(value)) return ` DEFAULT ${value}`;
+    if (value === 'true' || value === 'false') return ` DEFAULT ${value}`;
+    if (value === 'now' && (type === 'datetime' || type === 'date' || type === 'timestamp')) {
+      return ` DEFAULT NOW()`;
+    }
+    // Quoted SQL string literal — escape single quotes.
+    return ` DEFAULT '${value.replace(/'/g, "''")}'`;
+  }
+  return '';
+}

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

@@ -0,0 +1,84 @@
+/**
+ * PostgreSQL Native (pg) — Service Generator
+ *
+ * Generates abstract business-logic services that use the pgClient
+ * helpers directly. The service body is intentionally skeletal: each
+ * declared operation gets a typed method, but the body is a TODO stub
+ * containing the spec steps as comments. The behavior-step → SQL
+ * conventions for service bodies are a follow-up; controllers already
+ * inline conventions today.
+ */
+import type { TemplateContext } from '@specverse/types';
+
+export default function generatePgNativeService(context: TemplateContext): string {
+  const { service } = context;
+  if (!service) throw new Error('Service is required in template context');
+
+  const serviceName = service.name;
+  const operationsCode = generateOperations(service);
+  const usesDb = /\bquery\b|\bgetPool\b/.test(operationsCode);
+  const hasEvents = (service.publishes && service.publishes.length > 0) ||
+                    (service.subscribes && service.subscribes.length > 0);
+
+  return `/**
+ * ${serviceName}
+ * Abstract business logic service (PostgreSQL native driver)
+ * ${service.description || ''}
+ */
+${usesDb ? `import { query, getPool } from '../db/pgClient.js';` : ''}
+${hasEvents ? `import { eventBus } from '../events/eventBus.js';` : ''}
+
+export class ${serviceName} {
+${operationsCode}
+}
+
+const ${lowerFirst(serviceName)} = new ${serviceName}();
+export const ${lowerFirst(serviceName)}Instance = ${lowerFirst(serviceName)};
+export default ${lowerFirst(serviceName)};
+`;
+}
+
+function lowerFirst(s: string): string {
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}
+
+function generateOperations(service: any): string {
+  const ops = service.operations;
+  if (!ops || (Array.isArray(ops) && ops.length === 0) || (!Array.isArray(ops) && Object.keys(ops).length === 0)) {
+    return `
+  /**
+   * Default service entrypoint — replace with real operations once declared
+   * on the service's spec.
+   */
+  public async execute(_params: any = {}): Promise<any> {
+    throw new Error('${service.name}.execute is not implemented');
+  }
+`;
+  }
+  const entries: [string, any][] = Array.isArray(ops)
+    ? ops.map((op: any) => [op.name, op])
+    : Object.entries(ops);
+  return entries.map(([name, op]) => generateOperation(name, op, service.name)).join('\n');
+}
+
+function generateOperation(operationName: string, operation: any, serviceName: string): string {
+  const stepsHeader = (operation.steps && operation.steps.length > 0)
+    ? operation.steps.map((s: any) => `   *   - ${typeof s === 'string' ? s : (s.action || JSON.stringify(s))}`).join('\n')
+    : '   *   (no spec steps declared)';
+  return `
+  /**
+   * ${operationName}
+   * ${operation.description || ''}
+   *
+   * Spec steps:
+${stepsHeader}
+   */
+  public async ${operationName}(_args: any = {}): Promise<any> {
+    // TODO: translate spec steps into pg-native SQL calls. Controllers
+    // already inline conventions today; service-side parity is a
+    // follow-up. For now this stub keeps realize completing and the
+    // service surface callable.
+    throw new Error('${serviceName}.${operationName} is not implemented');
+  }
+`;
+}