@specverse/engines 6.11.2 → 6.16.0

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');
+  }
+`;
+}