@metaobjectsdev/migrate-ts 0.8.1 → 0.9.0-rc.1

package/README.md

@@ -5,7 +5,7 @@ Schema migration tool for MetaObjects-driven projects.
 Compares loaded MetaObjects metadata against a live Postgres or SQLite (libsql/Turso) database
 and emits paired `up.sql` + `down.sql` migration files.
 
-**Status:** v0.3. TS reference implementation; emits migration SQL but does not yet apply against the DB.
+**Status:** v0.3. TS reference implementation. Emits migration SQL, applies pending migrations against the DB (`--apply`), and tracks migration history via a ledger table.
 
 ## Install
 
@@ -97,8 +97,6 @@ Targets Cloudflare D1 via the wrangler CLI. Connection is read from `wrangler.to
 
 ## Not yet shipped
 
-- `meta migrate --apply` (apply migrations against the DB).
-- Migration history table.
 - Triggers, generated columns, partial indexes, exclusion constraints, check constraints.
 - MySQL.
 - Data migrations (column-type changes that need data transformation: error with hint).

package/dist/apply/apply.d.ts

@@ -0,0 +1,61 @@
+import { type Kysely } from "kysely";
+import { type LedgerDialect, type LedgerOptions } from "./ledger.js";
+import { splitSqlStatements } from "../sql/split-statements.js";
+export { splitSqlStatements };
+export interface ApplyPendingOptions {
+    /** When true, compute + return the plan but apply nothing. */
+    dryRun: boolean;
+    /**
+     * Target dialect. Decides ledger schema-qualification (pg) and whether the
+     * Postgres advisory lock is taken. Defaults to `sqlite` (no schema, no lock)
+     * to preserve the original single-DB behavior for callers that omit it.
+     */
+    dialect?: LedgerDialect;
+    /** Multi-tenant ledger location + advisory-lock name. Defaults preserve current behavior. */
+    ledger?: LedgerOptions;
+}
+export interface ApplyPendingResult {
+    /** Migration names that were pending (not yet in the ledger), in order. */
+    pending: string[];
+    /** Migration names that were applied this run, in order. Empty on dryRun. */
+    applied: string[];
+}
+/**
+ * Apply pending committed migration files in order, tracked by the
+ * migration-history ledger, transactionally.
+ *
+ * Idempotency comes from the LEDGER (skip names already recorded), NOT from
+ * re-diffing — so hand-authored files + data steps replay exactly once.
+ *
+ * For each pending migration (sorted by directory name), the file's SQL and a
+ * `recordApplied` row are run in the SAME Kysely transaction; any failure rolls
+ * back that file's tx, leaving it unrecorded (so a re-run retries it), and
+ * stops the run. Previously-applied files are checksum-compared against the
+ * ledger — a changed file errors (tamper guard).
+ */
+export declare function applyPending(db: Kysely<Record<string, unknown>>, dir: string, opts: ApplyPendingOptions): Promise<ApplyPendingResult>;
+export interface RollbackToOptions {
+    /** Target dialect. Decides ledger schema-qualification + advisory lock. Defaults to `sqlite`. */
+    dialect?: LedgerDialect;
+    /** Multi-tenant ledger location + advisory-lock name. Defaults preserve current behavior. */
+    ledger?: LedgerOptions;
+}
+export interface RollbackToResult {
+    /** Migration names rolled back, in execution (reverse-chronological) order. */
+    rolledBack: string[];
+}
+/**
+ * Roll back applied migrations newer than `target` (or all, when `target` is
+ * `null`), in REVERSE lexical order — running each migration's `down.sql` then
+ * deleting its ledger row, in ONE transaction per migration. `target` is itself
+ * retained (only ledger names strictly-greater than it are rolled back; lexical
+ * = chronological given the zero-padded timestamp prefix).
+ *
+ * An empty / whitespace-only `down.sql` THROWS before that migration is
+ * unrecorded — data-migration downs are hand-authored and must never be
+ * silently skipped. `down.sql` is split with the same {@link splitSqlStatements}
+ * the up-path uses. Wrapped in the same Postgres session advisory lock as
+ * {@link applyPending} (no-op on SQLite).
+ */
+export declare function rollbackTo(db: Kysely<Record<string, unknown>>, dir: string, target: string | null, opts?: RollbackToOptions): Promise<RollbackToResult>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/apply/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/apply/apply.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,MAAM,EAAyB,MAAM,QAAQ,CAAC;AAC5D,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,aAAa,EAGnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAKhE,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAO9B,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAgD7B;AAED,MAAM,WAAW,iBAAiB;IAChC,iGAAiG;IACjG,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAyC3B"}

package/dist/apply/apply.js

@@ -0,0 +1,241 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { sql } from "kysely";
+import { appliedRecords, DEFAULT_LEDGER_SCHEMA, deleteApplied, ensureLedger, MIGRATIONS_TABLE, recordApplied, } from "./ledger.js";
+import { splitSqlStatements } from "../sql/split-statements.js";
+// Re-exported here for back-compat: `splitSqlStatements` historically lived in
+// this module. Its canonical home is now ../sql/split-statements.js (shared with
+// the D1 safety pass), but consumers importing from apply.js keep working.
+export { splitSqlStatements };
+/** The per-migration up-SQL filename, shared with writeMigration's layout. */
+const UP_SQL = "up.sql";
+/** The per-migration down-SQL filename, shared with writeMigration's layout. */
+const DOWN_SQL = "down.sql";
+/**
+ * Apply pending committed migration files in order, tracked by the
+ * migration-history ledger, transactionally.
+ *
+ * Idempotency comes from the LEDGER (skip names already recorded), NOT from
+ * re-diffing — so hand-authored files + data steps replay exactly once.
+ *
+ * For each pending migration (sorted by directory name), the file's SQL and a
+ * `recordApplied` row are run in the SAME Kysely transaction; any failure rolls
+ * back that file's tx, leaving it unrecorded (so a re-run retries it), and
+ * stops the run. Previously-applied files are checksum-compared against the
+ * ledger — a changed file errors (tamper guard).
+ */
+export async function applyPending(db, dir, opts) {
+    const dialect = opts.dialect ?? "sqlite";
+    const ledger = opts.ledger;
+    // Serialize concurrent applies against the same ledger with a Postgres
+    // session advisory lock (no-op on SQLite). Held for the whole apply duration.
+    return withAdvisoryLock(db, dialect, ledger, async () => {
+        await ensureLedger(db, dialect, ledger);
+        const recorded = await appliedRecords(db, dialect, ledger);
+        const discovered = await discoverMigrations(dir);
+        // Tamper guard: any already-applied migration whose current up.sql checksum
+        // differs from the recorded one is a hard error.
+        for (const m of discovered) {
+            const recordedChecksum = recorded.get(m.name);
+            if (recordedChecksum === undefined)
+                continue;
+            const current = checksumOf(await readFile(m.upPath, "utf8"));
+            if (current !== recordedChecksum) {
+                throw new Error(`migration '${m.name}' was already applied but its up.sql checksum changed ` +
+                    `(recorded ${recordedChecksum.slice(0, 12)}…, current ${current.slice(0, 12)}…). ` +
+                    `Applied migrations are immutable; revert the edit or author a new migration.`);
+            }
+        }
+        const pending = discovered.filter((m) => !recorded.has(m.name));
+        const pendingNames = pending.map((m) => m.name);
+        if (opts.dryRun) {
+            return { pending: pendingNames, applied: [] };
+        }
+        const applied = [];
+        for (const m of pending) {
+            const text = await readFile(m.upPath, "utf8");
+            const checksum = checksumOf(text);
+            // Run the file's SQL + the ledger insert in ONE transaction. A failure
+            // rolls the whole file back (unrecorded) and propagates — stopping the run.
+            await runSqlFileWithLedgerMutation(db, text, (trx) => recordApplied(trx, m.name, checksum, dialect, ledger));
+            applied.push(m.name);
+        }
+        return { pending: pendingNames, applied };
+    });
+}
+/**
+ * Roll back applied migrations newer than `target` (or all, when `target` is
+ * `null`), in REVERSE lexical order — running each migration's `down.sql` then
+ * deleting its ledger row, in ONE transaction per migration. `target` is itself
+ * retained (only ledger names strictly-greater than it are rolled back; lexical
+ * = chronological given the zero-padded timestamp prefix).
+ *
+ * An empty / whitespace-only `down.sql` THROWS before that migration is
+ * unrecorded — data-migration downs are hand-authored and must never be
+ * silently skipped. `down.sql` is split with the same {@link splitSqlStatements}
+ * the up-path uses. Wrapped in the same Postgres session advisory lock as
+ * {@link applyPending} (no-op on SQLite).
+ */
+export async function rollbackTo(db, dir, target, opts = {}) {
+    const dialect = opts.dialect ?? "sqlite";
+    const ledger = opts.ledger;
+    return withAdvisoryLock(db, dialect, ledger, async () => {
+        await ensureLedger(db, dialect, ledger);
+        const recorded = await appliedRecords(db, dialect, ledger);
+        const discovered = await discoverMigrations(dir);
+        const byName = new Map(discovered.map((m) => [m.name, m]));
+        // Applied names strictly-greater than target (or all when target is null),
+        // newest-first.
+        const toRollback = [...recorded.keys()]
+            .filter((name) => target === null || compareLexical(name, target) > 0)
+            .sort((a, b) => compareLexical(b, a));
+        const rolledBack = [];
+        for (const name of toRollback) {
+            const m = byName.get(name);
+            if (m === undefined) {
+                throw new Error(`rollback '${name}': migration directory is missing (cannot read its down.sql)`);
+            }
+            const downText = await readDownSql(m.downPath, name);
+            if (downText.trim().length === 0) {
+                throw new Error(`rollback '${name}': down.sql is empty — data-migration downs must be ` +
+                    `hand-authored, never silently skipped.`);
+            }
+            // Run the down SQL + the ledger delete in ONE transaction.
+            await runSqlFileWithLedgerMutation(db, downText, (trx) => deleteApplied(trx, name, dialect, ledger));
+            rolledBack.push(name);
+        }
+        return { rolledBack };
+    });
+}
+/**
+ * Read a migration's `down.sql`. Distinguishes a MISSING file (never authored —
+ * ENOENT) from a present-but-empty one: a missing down throws a "not found"
+ * error (a never-written down has a different cause than a deliberately-blank
+ * one), while genuinely-empty content falls through to the caller's empty-down
+ * check. Both remain hard errors; this only reports the right cause.
+ */
+async function readDownSql(path, name) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (isErrnoException(err) && err.code === "ENOENT") {
+            throw new Error(`rollback '${name}': down.sql not found for migration '${name}' ` +
+                `(expected at ${path}) — data-migration downs must be hand-authored.`);
+        }
+        throw err;
+    }
+}
+/** Narrow an unknown caught value to a Node errno exception (has a string `code`). */
+function isErrnoException(err) {
+    return (err instanceof Error &&
+        typeof err.code === "string");
+}
+/**
+ * Run `body` while holding a Postgres SESSION-level advisory lock for mutual
+ * exclusion across concurrent applies/rollbacks against the same ledger.
+ *
+ * pg session advisory locks are per-connection, so the lock is taken on a single
+ * dedicated connection (`db.connection()`) held for the entire `body` duration;
+ * `body` still runs its own migrations via `db.transaction()` on the pool — the
+ * lock only needs to be held by some session for mutual exclusion. SESSION (not
+ * transaction) level so a `CREATE INDEX CONCURRENTLY` in a migration cannot
+ * deadlock against it. On SQLite (single-writer; no advisory locks) it is a
+ * pass-through.
+ */
+async function withAdvisoryLock(db, dialect, ledger, body) {
+    if (dialect !== "postgres") {
+        return body();
+    }
+    const key = advisoryKey(lockNameFor(ledger));
+    return db.connection().execute(async (lockConn) => {
+        // Bind the key as a parameter cast to bigint (a signed 64-bit int as a
+        // decimal string, possibly negative) — matching the runner's
+        // `pg_advisory_lock($1::bigint)`.
+        await sql `SELECT pg_advisory_lock(${key}::bigint)`.execute(lockConn);
+        try {
+            return await body();
+        }
+        finally {
+            // Releasing the lock must NOT mask an in-flight body error: a throw out of
+            // `finally` would replace any pending body rejection. Log-and-swallow the
+            // unlock failure so the body's error (if any) propagates intact. The lock
+            // is session-scoped, so it is released anyway when the connection closes.
+            try {
+                await sql `SELECT pg_advisory_unlock(${key}::bigint)`.execute(lockConn);
+            }
+            catch (unlockErr) {
+                console.warn(`migrate-ts: failed to release advisory lock (it will be freed when the ` +
+                    `session ends): ${String(unlockErr)}`);
+            }
+        }
+    });
+}
+/** Default advisory-lock name: explicit `lockName`, else `<schema>.<table>`. */
+function lockNameFor(ledger) {
+    if (ledger?.lockName !== undefined)
+        return ledger.lockName;
+    const schema = ledger?.schema ?? DEFAULT_LEDGER_SCHEMA;
+    const table = ledger?.table ?? MIGRATIONS_TABLE;
+    return `${schema}.${table}`;
+}
+/** Stable 64-bit signed advisory-lock key (decimal string) from a lock name. */
+function advisoryKey(name) {
+    const hash = createHash("sha256").update(name).digest();
+    return hash.readBigInt64BE(0).toString();
+}
+/**
+ * Run a migration SQL file's statements followed by a ledger mutation, all in
+ * ONE Kysely transaction on the pool. The file is split with
+ * {@link splitSqlStatements} and each statement executed in order, then
+ * `mutateLedger` records/unrecords the migration — so the data change and its
+ * ledger row commit or roll back together. Any failure rolls the whole
+ * transaction back (leaving the ledger untouched) and propagates to the caller.
+ *
+ * Shared by both the apply (up.sql + recordApplied) and rollback
+ * (down.sql + deleteApplied) paths.
+ */
+async function runSqlFileWithLedgerMutation(db, sqlText, mutateLedger) {
+    await db.transaction().execute(async (trx) => {
+        for (const stmt of splitSqlStatements(sqlText)) {
+            await sql.raw(stmt).execute(trx);
+        }
+        await mutateLedger(trx);
+    });
+}
+async function discoverMigrations(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const migrations = [];
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        migrations.push({
+            name: e.name,
+            upPath: join(dir, e.name, UP_SQL),
+            downPath: join(dir, e.name, DOWN_SQL),
+        });
+    }
+    // Directory names are timestamp-prefixed (`<YYYYMMDDHHMMSS>-<slug>`), so a
+    // plain lexical (code-unit) sort is the apply order.
+    migrations.sort((a, b) => compareLexical(a.name, b.name));
+    return migrations;
+}
+function checksumOf(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/** Stable lexical (code-unit) comparison; the same ordering as `a < b`/`a > b`. */
+function compareLexical(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+//# sourceMappingURL=apply.js.map

package/dist/apply/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/apply/apply.ts"],"names":[],"mappings":"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"}

package/dist/apply/ledger.d.ts

@@ -0,0 +1,78 @@
+import { type Kysely } from "kysely";
+/**
+ * Default migration-history ledger table name. A single source of truth tracked
+ * across postgres + sqlite so `meta migrate --apply` can skip already-applied
+ * files (idempotency from the LEDGER, not from re-diffing).
+ */
+export declare const MIGRATIONS_TABLE = "_metaobjects_migrations";
+/** Default Postgres schema holding the ledger (and, by default, the lock scope). */
+export declare const DEFAULT_LEDGER_SCHEMA = "public";
+/** The dialect signal threaded through the ledger fns (schema-qualification only applies to pg). */
+export type LedgerDialect = "postgres" | "sqlite";
+/**
+ * Multi-tenant ledger configuration. Generalizes the fixed
+ * `public._metaobjects_migrations` ledger so multiple apps/tenants can track
+ * independently in one physical database.
+ *
+ * Defaults preserve the original single-tenant behavior exactly: `schema`
+ * defaults to `public`, `table` to `_metaobjects_migrations`. Postgres uses
+ * `schema`; SQLite has no schemas and ignores it. `lockName` is consumed by the
+ * advisory-lock path (apply/rollback) — see {@link applyPending}.
+ */
+export interface LedgerOptions {
+    /** Postgres schema holding the ledger table. Default `public`. Ignored on SQLite. */
+    schema?: string;
+    /** Ledger table name. Default `_metaobjects_migrations`. */
+    table?: string;
+    /** Advisory-lock name. Default derived from `<schema>.<table>`. Postgres-only. */
+    lockName?: string;
+}
+/** A single ledger row. */
+export interface LedgerRow {
+    /** Migration name = the `<timestamp>-<slug>` directory name (sort key + id). */
+    name: string;
+    /** sha-256 of the up.sql contents at apply time (tamper guard). */
+    checksum: string;
+}
+/**
+ * Create the migration-history table if it does not already exist. Idempotent:
+ * re-running is a no-op and preserves existing rows. Dialect-portable DDL
+ * (TEXT columns work on both sqlite and postgres; `applied_at` is stored as
+ * text so we don't depend on a dialect-specific timestamp type).
+ *
+ * On Postgres a multi-tenant `schema` is created first (`CREATE SCHEMA IF NOT
+ * EXISTS`) so the ledger can live outside `public`.
+ */
+export declare function ensureLedger(db: Kysely<Record<string, unknown>>, dialect?: LedgerDialect, opts?: LedgerOptions): Promise<void>;
+/**
+ * Record a migration as applied. Inserts a row with the current UTC timestamp.
+ * Intended to run inside the SAME transaction that applied the migration SQL.
+ */
+export declare function recordApplied(db: Kysely<Record<string, unknown>>, name: string, checksum: string, dialect?: LedgerDialect, opts?: LedgerOptions): Promise<void>;
+/** Delete a migration's ledger row (rollback unrecord). */
+export declare function deleteApplied(db: Kysely<Record<string, unknown>>, name: string, dialect?: LedgerDialect, opts?: LedgerOptions): Promise<void>;
+/** Return the set of applied migration names. */
+export declare function appliedNames(db: Kysely<Record<string, unknown>>, dialect?: LedgerDialect, opts?: LedgerOptions): Promise<Set<string>>;
+/**
+ * Return a name→checksum map for all applied migrations (tamper-guard input).
+ *
+ * The {@link BASELINE_NAME} marker row is excluded at the SQL level: it is a
+ * marker, NOT a migration, so no migration-listing consumer (e.g. rollback-all,
+ * which derives its work list from these names) should ever see it. The baseline
+ * is read independently via {@link baselineRecord}.
+ */
+export declare function appliedRecords(db: Kysely<Record<string, unknown>>, dialect?: LedgerDialect, opts?: LedgerOptions): Promise<Map<string, string>>;
+/** Reserved ledger name for the baseline marker (sorts before any timestamped migration). */
+export declare const BASELINE_NAME = "0000-baseline";
+/**
+ * Record (or overwrite) the baseline marker — the snapshot checksum captured when
+ * `migrate baseline` seeded the reference snapshot. Lets a later check detect a
+ * snapshot that was hand-edited out of sync with the migration chain.
+ */
+export declare function recordBaseline(db: Kysely<Record<string, unknown>>, dialect: LedgerDialect, checksum: string, opts?: LedgerOptions): Promise<void>;
+/** Read the baseline marker, or null if none recorded. */
+export declare function baselineRecord(db: Kysely<Record<string, unknown>>, dialect?: LedgerDialect, opts?: LedgerOptions): Promise<{
+    name: string;
+    checksum: string;
+} | null>;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/apply/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/apply/ledger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAO,MAAM,QAAQ,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAE1D,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,WAAW,CAAC;AA2B9C,oGAAoG;AACpG,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElD;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2BAA2B;AAC3B,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;CAClB;AA4CD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnC,OAAO,GAAE,aAAwB,EACjC,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,aAAwB,EACjC,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,2DAA2D;AAC3D,wBAAsB,aAAa,CACjC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,aAAwB,EACjC,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,iDAAiD;AACjD,wBAAsB,YAAY,CAChC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnC,OAAO,GAAE,aAAwB,EACjC,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAEtB;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnC,OAAO,GAAE,aAAwB,EACjC,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAY9B;AAED,6FAA6F;AAC7F,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,0DAA0D;AAC1D,wBAAsB,cAAc,CAClC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACnC,OAAO,GAAE,aAAwB,EACjC,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAOpD"}

package/dist/apply/ledger.js

@@ -0,0 +1,146 @@
+import { sql } from "kysely";
+/**
+ * Default migration-history ledger table name. A single source of truth tracked
+ * across postgres + sqlite so `meta migrate --apply` can skip already-applied
+ * files (idempotency from the LEDGER, not from re-diffing).
+ */
+export const MIGRATIONS_TABLE = "_metaobjects_migrations";
+/** Default Postgres schema holding the ledger (and, by default, the lock scope). */
+export const DEFAULT_LEDGER_SCHEMA = "public";
+/**
+ * Safe SQL identifier pattern for caller-supplied `schema` / `table` names. These
+ * are interpolated as SQL identifiers (one `sql.ref` per part), so they MUST be a
+ * single, unquoted-style identifier — no dots, spaces, or quotes — otherwise
+ * Kysely's `sql.ref` would split a value like `"v1.2_migrations"` on every `.`
+ * into a wrong multi-part name. Validated at resolve time; a violation throws.
+ */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Throw a clear, actionable error if a caller-supplied SQL-identifier option
+ * (`schema` / `table`) is not a single safe identifier. Names the offending
+ * option + value so the caller can fix the misconfiguration directly.
+ */
+function assertSafeIdentifier(option, value) {
+    if (!SAFE_IDENTIFIER.test(value)) {
+        throw new Error(`LedgerOptions.${option} must be a single SQL identifier matching ` +
+            `${SAFE_IDENTIFIER.source} (letters, digits, underscore; not starting with a digit). ` +
+            `Got ${JSON.stringify(value)} — a dotted/quoted/spaced value would be mis-parsed as a ` +
+            `multi-part identifier. Use a plain name (e.g. a per-tenant prefix) instead.`);
+    }
+}
+/**
+ * Resolve a {@link LedgerOptions} (+ dialect) to a concrete ledger location.
+ * On Postgres the table is schema-qualified (`"<schema>"."<table>"`); on SQLite
+ * (no schema concept) the schema is ignored and the bare `"<table>"` is used.
+ *
+ * Caller-supplied `schema` / `table` are validated against {@link SAFE_IDENTIFIER}
+ * (a violation throws here, naming the option + value), then assembled from two
+ * separate `sql.ref` parts so identifier quoting stays dialect-portable AND no
+ * `.` can be mis-parsed as a multi-part separator.
+ */
+function resolveLedger(dialect, opts) {
+    const schema = opts?.schema ?? DEFAULT_LEDGER_SCHEMA;
+    const table = opts?.table ?? MIGRATIONS_TABLE;
+    assertSafeIdentifier("table", table);
+    if (dialect === "postgres") {
+        assertSafeIdentifier("schema", schema);
+    }
+    const ref = dialect === "postgres"
+        ? sql `${sql.ref(schema)}.${sql.ref(table)}`
+        : sql `${sql.ref(table)}`;
+    return { dialect, schema, table, ref };
+}
+/**
+ * Create the migration-history table if it does not already exist. Idempotent:
+ * re-running is a no-op and preserves existing rows. Dialect-portable DDL
+ * (TEXT columns work on both sqlite and postgres; `applied_at` is stored as
+ * text so we don't depend on a dialect-specific timestamp type).
+ *
+ * On Postgres a multi-tenant `schema` is created first (`CREATE SCHEMA IF NOT
+ * EXISTS`) so the ledger can live outside `public`.
+ */
+export async function ensureLedger(db, dialect = "sqlite", opts) {
+    const ledger = resolveLedger(dialect, opts);
+    if (ledger.dialect === "postgres") {
+        await sql `CREATE SCHEMA IF NOT EXISTS ${sql.ref(ledger.schema)}`.execute(db);
+    }
+    await sql `
+    CREATE TABLE IF NOT EXISTS ${ledger.ref} (
+      name TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL,
+      checksum TEXT NOT NULL
+    )
+  `.execute(db);
+}
+/**
+ * Record a migration as applied. Inserts a row with the current UTC timestamp.
+ * Intended to run inside the SAME transaction that applied the migration SQL.
+ */
+export async function recordApplied(db, name, checksum, dialect = "sqlite", opts) {
+    const ledger = resolveLedger(dialect, opts);
+    const appliedAt = new Date().toISOString();
+    await sql `
+    INSERT INTO ${ledger.ref} (name, applied_at, checksum)
+    VALUES (${name}, ${appliedAt}, ${checksum})
+  `.execute(db);
+}
+/** Delete a migration's ledger row (rollback unrecord). */
+export async function deleteApplied(db, name, dialect = "sqlite", opts) {
+    const ledger = resolveLedger(dialect, opts);
+    await sql `
+    DELETE FROM ${ledger.ref} WHERE name = ${name}
+  `.execute(db);
+}
+/** Return the set of applied migration names. */
+export async function appliedNames(db, dialect = "sqlite", opts) {
+    return new Set((await appliedRecords(db, dialect, opts)).keys());
+}
+/**
+ * Return a name→checksum map for all applied migrations (tamper-guard input).
+ *
+ * The {@link BASELINE_NAME} marker row is excluded at the SQL level: it is a
+ * marker, NOT a migration, so no migration-listing consumer (e.g. rollback-all,
+ * which derives its work list from these names) should ever see it. The baseline
+ * is read independently via {@link baselineRecord}.
+ */
+export async function appliedRecords(db, dialect = "sqlite", opts) {
+    const ledger = resolveLedger(dialect, opts);
+    // Raw select keeps this dialect-portable and sidesteps typing the dynamic
+    // table name against the untyped Kysely<Record<string, unknown>> schema.
+    const result = await sql `
+    SELECT name, checksum FROM ${ledger.ref} WHERE name != ${BASELINE_NAME}
+  `.execute(db);
+    const map = new Map();
+    for (const row of result.rows) {
+        map.set(row.name, row.checksum);
+    }
+    return map;
+}
+/** Reserved ledger name for the baseline marker (sorts before any timestamped migration). */
+export const BASELINE_NAME = "0000-baseline";
+/**
+ * Record (or overwrite) the baseline marker — the snapshot checksum captured when
+ * `migrate baseline` seeded the reference snapshot. Lets a later check detect a
+ * snapshot that was hand-edited out of sync with the migration chain.
+ */
+export async function recordBaseline(db, dialect, checksum, opts) {
+    const ledger = resolveLedger(dialect, opts);
+    await ensureLedger(db, dialect, opts);
+    const appliedAt = new Date().toISOString();
+    // Upsert: delete any prior baseline, then insert (portable across sqlite/pg).
+    await sql `DELETE FROM ${ledger.ref} WHERE name = ${BASELINE_NAME}`.execute(db);
+    await sql `
+    INSERT INTO ${ledger.ref} (name, applied_at, checksum)
+    VALUES (${BASELINE_NAME}, ${appliedAt}, ${checksum})
+  `.execute(db);
+}
+/** Read the baseline marker, or null if none recorded. */
+export async function baselineRecord(db, dialect = "sqlite", opts) {
+    const ledger = resolveLedger(dialect, opts);
+    const result = await sql `
+    SELECT name, checksum FROM ${ledger.ref} WHERE name = ${BASELINE_NAME}
+  `.execute(db);
+    const row = result.rows[0];
+    return row ? { name: row.name, checksum: row.checksum } : null;
+}
+//# sourceMappingURL=ledger.js.map

package/dist/apply/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/apply/ledger.ts"],"names":[],"mappings":"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"}

package/dist/check-expr-compare.d.ts

@@ -0,0 +1,13 @@
+/** Canonical form: drop casts/brackets/parens, fold `= ANY (ARRAY[…])` back to `IN`, lower-case, collapse whitespace. */
+export declare function normalizeCheckExpr(expr: string): string;
+/** True when two CHECK expressions are equivalent after normalization. */
+export declare function checkExprEquals(a: string | undefined, b: string | undefined): boolean;
+/**
+ * `CHECK (<expr>)` → `<expr>` (balanced outer wrapper); returns input unchanged
+ * if there is no CHECK wrapper. Tolerates a trailing constraint modifier suffix
+ * (`pg_get_constraintdef` can return `CHECK (<expr>) NOT VALID`) so the wrapper
+ * still strips cleanly to the inner expression instead of falling through to the
+ * unchanged-input fallback (which would cause spurious drop+add churn).
+ */
+export declare function stripCheckWrapper(def: string): string;
+//# sourceMappingURL=check-expr-compare.d.ts.map

package/dist/check-expr-compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-expr-compare.d.ts","sourceRoot":"","sources":["../src/check-expr-compare.ts"],"names":[],"mappings":"AAcA,yHAAyH;AACzH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAevD;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGrF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGrD"}

package/dist/check-expr-compare.js

@@ -0,0 +1,48 @@
+// src/check-expr-compare.ts
+//
+// CHECK-expression comparison. Postgres rewrites a stored CHECK body so the raw
+// text we generate and the introspected text differ textually but mean the same
+// thing. This reduces both to ONE canonical form for comparison. Reliable here
+// because every check expression we emit is machine-derived with a simple, known
+// shape (comparison / IN / length / regex) — there is no arbitrary author SQL to
+// mis-normalize. The rewrites PG applies (verified against a live server):
+//   - parenthesizes terms:  `col >= 0 AND col <= 100`  →  `(col >= 0) AND (col <= 100)`
+//   - rewrites IN-lists:     `status IN ('A','B')`      →  `status = ANY (ARRAY['A'::text, 'B'::text])`
+//   - appends type casts:    string literals gain `::text`
+// All three are canonicalized below so an enum/range CHECK introspected from PG
+// compares equal to the one we generate (idempotency on the --from-db / verify paths).
+/** Canonical form: drop casts/brackets/parens, fold `= ANY (ARRAY[…])` back to `IN`, lower-case, collapse whitespace. */
+export function normalizeCheckExpr(expr) {
+    const stripped = expr
+        .toLowerCase()
+        // Drop `::text` / `::"MyType"` type casts PG adds to literals. The lookbehind
+        // restricts the strip to a cast that immediately follows a CLOSING single
+        // quote (`'open'::text`), so a `::` appearing INSIDE a regex pattern literal
+        // (`slug ~ 'a::foo'`) is preserved — otherwise two distinct regex CHECKs would
+        // normalize equal and a pattern change would be silently missed.
+        .replace(/(?<=')::\s*"?\w+"?/g, "")
+        .replace(/[()[\]]/g, " ") // drop parens AND square brackets (ARRAY[…])
+        .replace(/\s+/g, " ")
+        .trim();
+    // PG stores `col IN (…)` as `col = ANY (ARRAY[…])`; after the bracket strip above
+    // that reads `col = any array …`. Fold it back to the `col in …` form we emit.
+    return stripped.replace(/=\s*any\s+array/g, "in").replace(/\s+/g, " ").trim();
+}
+/** True when two CHECK expressions are equivalent after normalization. */
+export function checkExprEquals(a, b) {
+    if (a === undefined || b === undefined)
+        return false;
+    return normalizeCheckExpr(a) === normalizeCheckExpr(b);
+}
+/**
+ * `CHECK (<expr>)` → `<expr>` (balanced outer wrapper); returns input unchanged
+ * if there is no CHECK wrapper. Tolerates a trailing constraint modifier suffix
+ * (`pg_get_constraintdef` can return `CHECK (<expr>) NOT VALID`) so the wrapper
+ * still strips cleanly to the inner expression instead of falling through to the
+ * unchanged-input fallback (which would cause spurious drop+add churn).
+ */
+export function stripCheckWrapper(def) {
+    const m = /^\s*CHECK\s*\((.*)\)(?:\s+NOT\s+VALID)?\s*$/is.exec(def);
+    return m ? m[1].trim() : def.trim();
+}
+//# sourceMappingURL=check-expr-compare.js.map