@abloatai/ablo 0.5.1 → 0.7.0

package/dist/schema/ddl.js

@@ -0,0 +1,317 @@
+/**
+ * Schema → Postgres DDL — the one pure SQL emitter shared by every consumer.
+ *
+ * `defineSchema(...)` (serialized to {@link SchemaJSON}) is the single source of
+ * truth; this module lowers it to ordered DDL strings. Both the hosted server
+ * (which applies it to Ablo-managed Postgres on `schema push`) and the
+ * `ablo migrate` CLI (which applies it to a customer's own Postgres) call these
+ * generators, so the SQL — column types, RLS, enum checks — is identical no
+ * matter who runs it. There is no second type map.
+ *
+ * Everything here is pure (returns strings; no DB, no I/O); the execution side
+ * (transaction + advisory lock) lives with each consumer because it's coupled
+ * to that consumer's Postgres client and error type.
+ *
+ *  - `generateProvisionPlan` — additive + idempotent (CREATE/ADD … IF NOT
+ *    EXISTS + RLS). Never loses data. The "create my tables" primitive.
+ *  - `generateMigrationPlan` — the destructive-aware counterpart driven by the
+ *    {@link diffSchema} step list (drops, renames, type casts, backfills).
+ */
+import { resolveTenancy, tenancyColumn } from './tenancy.js';
+// ── Identifier safety ────────────────────────────────────────────────────────
+/** Postgres unquoted-identifier-safe slug: lowercase `[a-z0-9_]`, ≤50 chars. */
+function slug(raw) {
+    const s = raw.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    return s.slice(0, 50) || 'x';
+}
+/** Per-app schema name for an app (organization) id. */
+export function appSchemaName(organizationId) {
+    return `app_${slug(organizationId)}`;
+}
+export function camelToSnake(identifier) {
+    return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+/** Quote an identifier (defense-in-depth; inputs are already slug/snake). */
+export function q(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
+// ── Field type mapping ───────────────────────────────────────────────────────
+export function sqlType(fieldType) {
+    switch (fieldType) {
+        case 'string':
+        case 'enum':
+            return 'TEXT';
+        case 'number':
+            // DOUBLE PRECISION, not INTEGER — a Zod `number` may be fractional and
+            // truncating to INTEGER is silent data loss.
+            return 'DOUBLE PRECISION';
+        case 'boolean':
+            return 'BOOLEAN';
+        case 'date':
+            return 'TIMESTAMPTZ';
+        case 'json':
+        default:
+            return 'JSONB';
+    }
+}
+const BASE_COLUMNS = new Set(['id', 'organization_id', 'created_by', 'created_at', 'updated_at']);
+// ── Provisioning (additive, idempotent) ─────────────────────────────────────
+/**
+ * Build the additive, idempotent provisioning plan for an app. Pure — no DB
+ * access.
+ *
+ * `targetSchema` is where the tables live: the app's schema `app_<id>` on the
+ * shared tier, or `public` on a dedicated tenant's own database (where the DB
+ * itself is the isolation boundary). For `public` the `CREATE SCHEMA` is
+ * skipped (it always exists).
+ */
+export function generateProvisionPlan(schema, targetSchema) {
+    const appSchema = targetSchema;
+    const qs = q(appSchema);
+    const statements = appSchema === 'public' ? [] : [`CREATE SCHEMA IF NOT EXISTS ${qs};`];
+    for (const [key, model] of Object.entries(schema.models)) {
+        // Default the physical table to the model key when `tableName` is omitted —
+        // same fallback the migration path uses (`tableOfModel: m.tableName ?? key`).
+        // Without this, a schema that doesn't set `tableName` (e.g. the `ablo init`
+        // starter) provisions zero tables.
+        const table = model.tableName ?? key;
+        const qt = `${qs}.${q(table)}`;
+        // Base columns are schema-driven, not blanket. `organization_id` (and its
+        // index + tenant-isolation RLS below) is emitted only for org-scoped models.
+        // A model that declares `orgScoped: false` (users, organizations, and other
+        // tables scoped via a FK / app layer) genuinely has no `organization_id`
+        // column — forcing one would add a NOT NULL column that fails on existing
+        // rows and contradicts the model's own declaration.
+        // Tenancy column: present only for column-scoped models, with the
+        // configured name (default `organization_id`). `parent`/`none` tenancy emit
+        // no tenancy column — they're scoped via a parent FK or not at all.
+        const orgCol = tenancyColumn(resolveTenancy(model));
+        const baseColumns = [
+            `  ${q('id')} TEXT PRIMARY KEY,`,
+            ...(orgCol ? [`  ${q(orgCol)} TEXT NOT NULL,`] : []),
+            `  ${q('created_by')} TEXT,`,
+            `  ${q('created_at')} TIMESTAMPTZ NOT NULL DEFAULT NOW(),`,
+            `  ${q('updated_at')} TIMESTAMPTZ NOT NULL DEFAULT NOW()`,
+        ];
+        statements.push(`CREATE TABLE IF NOT EXISTS ${qt} (\n${baseColumns.join('\n')}\n);`);
+        for (const [fieldName, meta] of Object.entries(model.fields)) {
+            const col = meta.column ?? camelToSnake(fieldName);
+            if (BASE_COLUMNS.has(col) || col === orgCol)
+                continue;
+            statements.push(`ALTER TABLE ${qt} ADD COLUMN IF NOT EXISTS ${q(col)} ${sqlType(meta.type)};`);
+            if (meta.type === 'enum' && meta.enumValues && meta.enumValues.length > 0) {
+                const cname = `${table}_${col}_enum`;
+                const allowed = meta.enumValues.map((v) => `'${v.replace(/'/g, "''")}'`).join(', ');
+                statements.push(`DO $$ BEGIN\n` +
+                    `  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = '${cname}') THEN\n` +
+                    `    ALTER TABLE ${qt} ADD CONSTRAINT ${q(cname)} CHECK (${q(col)} IN (${allowed}));\n` +
+                    `  END IF;\n` +
+                    `END $$;`);
+            }
+        }
+        // Org index + tenant-isolation RLS only where there's an `organization_id`
+        // to isolate on. Non-org-scoped tables rely on FK/app-layer scoping.
+        if (orgCol) {
+            statements.push(`CREATE INDEX IF NOT EXISTS ${q(`${table}_${orgCol}_idx`)} ON ${qt} (${q(orgCol)});`);
+            statements.push(`ALTER TABLE ${qt} ENABLE ROW LEVEL SECURITY;`);
+            statements.push(`ALTER TABLE ${qt} FORCE ROW LEVEL SECURITY;`);
+            const policy = `${table}_tenant_isolation`;
+            const predicate = `${q(orgCol)} = current_setting('app.current_org_id', true)`;
+            statements.push(`DROP POLICY IF EXISTS ${q(policy)} ON ${qt};`);
+            statements.push(`CREATE POLICY ${q(policy)} ON ${qt}\n  USING (${predicate})\n  WITH CHECK (${predicate});`);
+        }
+    }
+    return { appSchema, statements };
+}
+// ── Migration (destructive-aware, diff-driven) ──────────────────────────────
+function enumCheckStatements(table, col, qt, values) {
+    const cname = `${table}_${col}_enum`;
+    const stmts = [`ALTER TABLE ${qt} DROP CONSTRAINT IF EXISTS ${q(cname)};`];
+    if (values.length > 0) {
+        const allowed = values.map((v) => `'${v.replace(/'/g, "''")}'`).join(', ');
+        stmts.push(`ALTER TABLE ${qt} ADD CONSTRAINT ${q(cname)} CHECK (${q(col)} IN (${allowed}));`);
+    }
+    return stmts;
+}
+function indexName(table, col) {
+    return `${table}_${col}_idx`;
+}
+function columnNameOf(fieldName, meta) {
+    return meta?.column ?? camelToSnake(fieldName);
+}
+/**
+ * Encode a constant backfill value as a typed SQL literal. Inputs are operator-
+ * supplied (via the authed push), but we still encode by the field's declared
+ * type and escape strings rather than interpolate raw — defense-in-depth.
+ */
+function sqlLiteral(value, fieldType) {
+    switch (fieldType) {
+        case 'number':
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw new Error(`backfill for a number field must be a finite number, got ${JSON.stringify(value)}`);
+            }
+            return String(value);
+        case 'boolean':
+            return value ? 'TRUE' : 'FALSE';
+        case 'date':
+            return `'${String(value).replace(/'/g, "''")}'::timestamptz`;
+        case 'json':
+            return `'${JSON.stringify(value).replace(/'/g, "''")}'::jsonb`;
+        case 'string':
+        case 'enum':
+        default:
+            return `'${String(value).replace(/'/g, "''")}'`;
+    }
+}
+/**
+ * Lower an ordered migration step list to DDL. `next` is the schema being pushed
+ * (the target column shapes are read from it), `prev` the active one (used to
+ * resolve the *old* table name on a model rename).
+ */
+export function generateMigrationPlan(steps, opts) {
+    const { prev, next, targetSchema, backfills = [] } = opts;
+    const qs = q(targetSchema);
+    const statements = [];
+    const qtFor = (table) => `${qs}.${q(table)}`;
+    const tableOfModel = (schema, key) => {
+        const m = schema?.models[key];
+        if (!m)
+            return null;
+        return m.tableName ?? key;
+    };
+    const backfillFor = (model, field) => backfills.find((b) => b.model === model && b.field === field);
+    for (const step of steps) {
+        switch (step.kind) {
+            case 'create_model': {
+                // Reuse the provisioner for the full table (base cols + fields + enum
+                // checks + RLS), minus its `CREATE SCHEMA` (the schema already exists
+                // mid-migration).
+                const def = next.models[step.model];
+                if (!def)
+                    break;
+                const sub = { v: next.v, models: { [step.model]: def }, identityRoles: next.identityRoles };
+                for (const s of generateProvisionPlan(sub, targetSchema).statements) {
+                    if (!s.startsWith('CREATE SCHEMA'))
+                        statements.push(s);
+                }
+                break;
+            }
+            case 'drop_model':
+                statements.push(`DROP TABLE IF EXISTS ${qtFor(step.tableName)};`);
+                break;
+            case 'rename_model': {
+                const fromTable = tableOfModel(prev, step.from);
+                const toTable = tableOfModel(next, step.to);
+                // A logical model rename only needs SQL when the physical table name
+                // actually changes; if tableName is unchanged the rename is metadata.
+                if (fromTable && toTable && fromTable !== toTable) {
+                    statements.push(`ALTER TABLE ${qtFor(fromTable)} RENAME TO ${q(toTable)};`);
+                }
+                break;
+            }
+            case 'add_field': {
+                const table = tableOfModel(next, step.model);
+                if (!table)
+                    break;
+                const qt = qtFor(table);
+                const col = columnNameOf(step.field, step.meta);
+                // Added nullable first (the column is born NULL on every existing row).
+                statements.push(`ALTER TABLE ${qt} ADD COLUMN IF NOT EXISTS ${q(col)} ${sqlType(step.meta.type)};`);
+                if (step.meta.type === 'enum' && step.meta.enumValues?.length) {
+                    statements.push(...enumCheckStatements(table, col, qt, step.meta.enumValues));
+                }
+                // Backfill + enforce NOT NULL only with a supplied seed value. Without
+                // one, a required field stays nullable (gated `unexecutable` upstream).
+                const addBf = backfillFor(step.model, step.field);
+                if (addBf !== undefined) {
+                    statements.push(`UPDATE ${qt} SET ${q(col)} = ${sqlLiteral(addBf.value, step.meta.type)} WHERE ${q(col)} IS NULL;`);
+                    if (!step.meta.isOptional) {
+                        statements.push(`ALTER TABLE ${qt} ALTER COLUMN ${q(col)} SET NOT NULL;`);
+                    }
+                }
+                if (step.meta.isIndexed) {
+                    statements.push(`CREATE INDEX IF NOT EXISTS ${q(indexName(table, col))} ON ${qt} (${q(col)});`);
+                }
+                break;
+            }
+            case 'drop_field': {
+                const table = tableOfModel(next, step.model);
+                if (!table)
+                    break;
+                const prevMeta = prev?.models[step.model]?.fields[step.field];
+                statements.push(`ALTER TABLE ${qtFor(table)} DROP COLUMN IF EXISTS ${q(columnNameOf(step.field, prevMeta))};`);
+                break;
+            }
+            case 'rename_field': {
+                const table = tableOfModel(next, step.model);
+                if (!table)
+                    break;
+                const prevMeta = prev?.models[step.model]?.fields[step.from];
+                const nextMeta = next.models[step.model]?.fields[step.to];
+                const fromCol = columnNameOf(step.from, prevMeta);
+                const toCol = columnNameOf(step.to, nextMeta);
+                if (fromCol === toCol)
+                    break;
+                statements.push(`ALTER TABLE ${qtFor(table)} RENAME COLUMN ${q(fromCol)} TO ${q(toCol)};`);
+                break;
+            }
+            case 'alter_field': {
+                const table = tableOfModel(next, step.model);
+                if (!table)
+                    break;
+                const qt = qtFor(table);
+                const nextMeta = next.models[step.model]?.fields[step.field];
+                let col = columnNameOf(step.field, nextMeta);
+                const ch = step.changes;
+                // 0. Physical column rename. Subsequent alterations must address
+                // the new name.
+                if (ch.column) {
+                    statements.push(`ALTER TABLE ${qt} RENAME COLUMN ${q(ch.column.from)} TO ${q(ch.column.to)};`);
+                    col = ch.column.to;
+                }
+                // 1. Type — in-place cast or lossy drop-and-recreate.
+                if (ch.type) {
+                    const target = sqlType(ch.type.to);
+                    if (ch.type.cast === 'notCastable') {
+                        statements.push(`ALTER TABLE ${qt} DROP COLUMN IF EXISTS ${q(col)};`);
+                        statements.push(`ALTER TABLE ${qt} ADD COLUMN IF NOT EXISTS ${q(col)} ${target};`);
+                    }
+                    else {
+                        statements.push(`ALTER TABLE ${qt} ALTER COLUMN ${q(col)} TYPE ${target} USING ${q(col)}::${target};`);
+                    }
+                }
+                // 2. Enum CHECK — drop when leaving enum; (re)build when arriving at or
+                //    re-valuing an enum. Reads the full target value set from `next`.
+                if (ch.type?.from === 'enum' && nextMeta?.type !== 'enum') {
+                    statements.push(`ALTER TABLE ${qt} DROP CONSTRAINT IF EXISTS ${q(`${table}_${col}_enum`)};`);
+                }
+                else if (nextMeta?.type === 'enum' && (ch.enumValues || ch.type)) {
+                    statements.push(...enumCheckStatements(table, col, qt, nextMeta.enumValues ?? []));
+                }
+                // 3. Nullability. DROP NOT NULL is always safe. SET NOT NULL is gated
+                //    upstream (unexecutable on a table with NULLs); a supplied backfill
+                //    seeds the existing NULLs first so the constraint can take.
+                if (ch.nullability) {
+                    if (ch.nullability.toOptional) {
+                        statements.push(`ALTER TABLE ${qt} ALTER COLUMN ${q(col)} DROP NOT NULL;`);
+                    }
+                    else {
+                        const bf = backfillFor(step.model, step.field);
+                        if (bf !== undefined && nextMeta) {
+                            statements.push(`UPDATE ${qt} SET ${q(col)} = ${sqlLiteral(bf.value, nextMeta.type)} WHERE ${q(col)} IS NULL;`);
+                        }
+                        statements.push(`ALTER TABLE ${qt} ALTER COLUMN ${q(col)} SET NOT NULL;`);
+                    }
+                }
+                // 4. Index.
+                if (ch.indexed) {
+                    statements.push(ch.indexed.to
+                        ? `CREATE INDEX IF NOT EXISTS ${q(indexName(table, col))} ON ${qt} (${q(col)});`
+                        : `DROP INDEX IF EXISTS ${qs}.${q(indexName(table, col))};`);
+                }
+                break;
+            }
+        }
+    }
+    return { appSchema: targetSchema, statements };
+}

package/dist/schema/diff.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Schema diff + migration planning — the pure core of the managed-migration loop.
+ *
+ * Given two serialized schemas (the active one and the one being pushed), produce
+ * an ordered list of {@link MigrationStep}s describing how to evolve the database,
+ * and a {@link MigrationClassification} splitting the risky parts into *warnings*
+ * (execute but may lose/risk data) and *unexecutable* steps (fail on a non-empty
+ * table without a backfill/default). SQL emission and execution live elsewhere
+ * (server-side, where the type map + RLS live); this module is intentionally pure
+ * and DB-free so it is exhaustively unit-testable and reusable by the CLI.
+ *
+ * Design borrowed from mature tools:
+ *  - **Drizzle Kit**: keep the differ pure and inject RENAME decisions as data
+ *    (the {@link RenameHints} resolver seam) rather than guessing — the same
+ *    engine is then headless-testable and drivable by an interactive prompt.
+ *  - **Prisma migration engine**: a two-tier destructive classification
+ *    (warning vs unexecutable) and a type-change sub-tier
+ *    (safe / risky / not-castable) that decides in-place `ALTER TYPE` vs a
+ *    lossy drop-and-recreate.
+ *  - **Atlas**: a single `alter_field` step carrying *which* facets changed
+ *    (type / nullability / enum / index) instead of N discrete alter steps.
+ *
+ * Step ordering is the expand→contract sequence (add before drop, widen before
+ * narrow): create models → rename → add columns (always nullable) → alter →
+ * drop columns → drop models. NOT NULL is never set on add — it is an
+ * `alter_field` nullability change that a backfill must precede.
+ */
+import type { FieldMeta } from './field.js';
+import type { SchemaJSON } from './serialize.js';
+export type FieldType = FieldMeta['type'];
+/** Whether a Postgres `ALTER COLUMN … TYPE` can preserve the existing data. */
+export type CastSafety = 'safe' | 'risky' | 'notCastable';
+export interface FieldTypeChange {
+    readonly from: FieldType;
+    readonly to: FieldType;
+    /** `safe` → plain ALTER TYPE; `risky` → ALTER w/ USING (may fail per-row);
+     *  `notCastable` → drop-and-recreate (data loss). */
+    readonly cast: CastSafety;
+}
+/** `isOptional` transition. `true → false` is the dangerous direction. */
+export interface NullabilityChange {
+    readonly fromOptional: boolean;
+    readonly toOptional: boolean;
+}
+export interface EnumValuesChange {
+    readonly added: readonly string[];
+    readonly removed: readonly string[];
+}
+export interface IndexChange {
+    readonly from: boolean;
+    readonly to: boolean;
+}
+/** Physical column-name transition for a stable logical field. */
+export interface FieldColumnChange {
+    readonly from: string;
+    readonly to: string;
+}
+/** The facets of a single column that changed (Atlas-style bitmask, as data). */
+export interface FieldChanges {
+    readonly column?: FieldColumnChange;
+    readonly type?: FieldTypeChange;
+    readonly nullability?: NullabilityChange;
+    readonly enumValues?: EnumValuesChange;
+    readonly indexed?: IndexChange;
+}
+export type MigrationStep = {
+    readonly kind: 'create_model';
+    readonly model: string;
+    readonly tableName: string;
+} | {
+    readonly kind: 'drop_model';
+    readonly model: string;
+    readonly tableName: string;
+} | {
+    readonly kind: 'rename_model';
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: 'add_field';
+    readonly model: string;
+    readonly field: string;
+    readonly meta: FieldMeta;
+} | {
+    readonly kind: 'drop_field';
+    readonly model: string;
+    readonly field: string;
+} | {
+    readonly kind: 'rename_field';
+    readonly model: string;
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: 'alter_field';
+    readonly model: string;
+    readonly field: string;
+    readonly changes: FieldChanges;
+};
+/**
+ * Rename decisions, injected as data (Drizzle's resolver seam). Without a hint,
+ * a removed+added pair reads as drop+add (lossy) — the same safe default Prisma
+ * takes. `field.model` refers to the model key in the NEXT schema (post any
+ * model rename).
+ */
+export interface RenameHints {
+    readonly models?: readonly {
+        readonly from: string;
+        readonly to: string;
+    }[];
+    readonly fields?: readonly {
+        readonly model: string;
+        readonly from: string;
+        readonly to: string;
+    }[];
+}
+export declare function classifyCast(from: FieldType, to: FieldType): CastSafety;
+/**
+ * Diff two serialized schemas into an ordered, expand→contract migration plan.
+ * `prev` is the active schema (`null` for a first push → all creates). Rename
+ * decisions are supplied via {@link RenameHints}; anything not hinted reads as
+ * drop+add.
+ */
+export declare function diffSchema(prev: SchemaJSON | null, next: SchemaJSON, hints?: RenameHints): MigrationStep[];
+export type WarningCode = 'drop_model' | 'drop_field' | 'risky_cast' | 'lossy_recreate' | 'enum_value_removed';
+export type BlockerCode = 'required_field_added' | 'made_required';
+export interface MigrationSignal {
+    readonly code: WarningCode | BlockerCode;
+    readonly model: string;
+    readonly field?: string;
+    readonly detail: string;
+}
+export interface MigrationClassification {
+    /** Execute but may lose or risk data on a non-empty table. */
+    readonly warnings: readonly MigrationSignal[];
+    /** Will fail on a non-empty table unless a default/backfill is supplied. */
+    readonly unexecutable: readonly MigrationSignal[];
+}
+/**
+ * Classify a plan's steps into Prisma-style warnings vs unexecutable. The IR
+ * carries no per-field default, so a non-optional `add_field` is conservatively
+ * unexecutable (a backfill or default resolves it) — we cannot prove a default
+ * exists. Classification is rule-based (schema-derived); the runtime layer can
+ * downgrade a signal to a no-op when the target table is empty.
+ */
+export declare function classifyMigration(steps: readonly MigrationStep[]): MigrationClassification;
+/** Convenience: a plan is safe to auto-apply iff it has no unexecutable steps. */
+export declare function isAutoApplicable(classification: MigrationClassification): boolean;
+/**
+ * A constant value to seed into existing rows so an otherwise-`unexecutable`
+ * step becomes safe: a required field added to a non-empty table, or a field
+ * made required while NULLs exist. Deliberately a CONSTANT (not an SQL
+ * expression) — arbitrary backfill logic is out of scope; this serves the
+ * common "new column defaults to X" case only. `value` is typed to the field.
+ */
+export interface BackfillValue {
+    readonly model: string;
+    readonly field: string;
+    readonly value: string | number | boolean;
+}
+/**
+ * Does a provided backfill resolve this blocker? Only the two row-dependent
+ * blockers (`required_field_added`, `made_required`) are backfill-resolvable; a
+ * data-loss *warning* is not — that always needs `force`.
+ */
+export declare function isBlockerResolved(signal: MigrationSignal, backfills: readonly BackfillValue[]): boolean;
+/** The unexecutable signals NOT covered by a supplied backfill. Empty → the push
+ *  can proceed (modulo the separate `warnings`/`force` gate). */
+export declare function unresolvedBlockers(classification: MigrationClassification, backfills: readonly BackfillValue[]): readonly MigrationSignal[];