@supabase/pg-delta 1.0.0-alpha.3 → 1.0.0-alpha.30

package/dist/core/sort/sort-changes.js

@@ -12,6 +12,7 @@
  */
 import debug from "debug";
 import { generateCustomConstraints } from "./custom-constraints.js";
+import { tryBreakCycleByChangeInjection } from "./cycle-breakers.js";
 import { printDebugGraph } from "./debug-visualization.js";
 const debugGraph = debug("pg-delta:graph");
 import { filterEdgesForCycleBreaking, getEdgesInCycle, } from "./dependency-filter.js";
@@ -19,7 +20,15 @@ import { buildGraphData, convertCatalogDependenciesToConstraints, convertConstra
 import { dedupeEdges } from "./graph-utils.js";
 import { logicalSort } from "./logical-sort.js";
 import { findCycle, formatCycleError, performStableTopologicalSort, } from "./topological-sort.js";
+import { UnorderableCycleError } from "./unorderable-cycle-error.js";
 import { getExecutionPhase } from "./utils.js";
+// `sortPhaseChanges` caps the change-injection breaker at one round per
+// node in the initial phase: there can never be more disjoint unbreakable
+// cycles than there are change nodes (each cycle has ≥ 2 distinct nodes).
+// The cap exists only to surface a buggy breaker as `CycleError` instead
+// of an infinite loop — the actual loop-protection guarantee comes from
+// `breakerRoundSignatures`, which throws the moment the same cycle
+// reappears after a break.
 /**
  * Sort changes using dependency information from catalogs and custom constraints.
  *
@@ -63,20 +72,38 @@ function sortChangesByPhasedGraph(catalogContext, changeList) {
     return [...sortedDropPhase, ...sortedCreateAlterPhase];
 }
 /**
- * Sort changes within a phase using Constraints derived from all dependency sources.
+ * Normalize a cycle by rotating it to start with the smallest node index, so
+ * cycles that loop through the same nodes in the same direction compare equal
+ * regardless of where DFS happened to enter them.
+ */
+function normalizeCycle(cycleNodeIndexes) {
+    if (cycleNodeIndexes.length === 0)
+        return "";
+    const minIndex = Math.min(...cycleNodeIndexes);
+    const minIndexPos = cycleNodeIndexes.indexOf(minIndex);
+    const rotated = [
+        ...cycleNodeIndexes.slice(minIndexPos),
+        ...cycleNodeIndexes.slice(0, minIndexPos),
+    ];
+    return rotated.join(",");
+}
+/**
+ * One attempt at sorting `phaseChanges`. Builds the graph from scratch,
+ * runs the iterative edge-removal cycle handler, and either returns a
+ * topologically sorted list or reports an unbreakable cycle so the caller
+ * can decide whether to dispatch a change-injection breaker.
  *
  * Algorithm:
- * 1. Build graph data (change sets and reverse indexes)
- * 2. Convert all sources to Constraints (catalog, explicit, custom constraints)
- * 3. Convert Constraints to edges
- * 4. Iteratively detect and break cycles (deduplicate edges, detect cycles, filter problematic edges)
- * 5. Perform stable topological sort on the acyclic graph
+ * 1. Build graph data (change sets and reverse indexes).
+ * 2. Convert all sources to Constraints (catalog, explicit, custom).
+ * 3. Convert Constraints to edges.
+ * 4. Iteratively detect and break cycles by removing weak edges.
+ * 5. Perform stable topological sort on the acyclic graph.
  *
- * In DROP phase, edges are inverted so drops run in reverse dependency order.
+ * In DROP phase, edges are inverted so drops run in reverse dependency
+ * order.
  */
-function sortPhaseChanges(phaseChanges, dependencyRows, options = {}) {
-    if (phaseChanges.length <= 1)
-        return phaseChanges;
+function attemptSortRound(phaseChanges, dependencyRows, options) {
     // Step 1: Build graph data structures
     const graphData = buildGraphData(phaseChanges, options);
     // Step 2: Convert all sources to Constraints
@@ -90,50 +117,31 @@ function sortPhaseChanges(phaseChanges, dependencyRows, options = {}) {
     ];
     // Step 3: Convert constraints to edges and deduplicate immediately
     let edges = dedupeEdges(convertConstraintsToEdges(allConstraints, options));
-    // Step 4: Iteratively detect and break cycles
-    // Track cycles we've seen to detect when filtering fails to break a cycle.
-    // The only way we loop indefinitely is if we encounter a cycle we've already seen,
-    // which means filtering didn't break it. Otherwise, we continue until all cycles are broken.
+    // Step 4: Iteratively detect and break cycles by edge filtering.
+    // We loop until no cycles remain OR we see the same cycle twice — the
+    // latter signals that edge filtering exhausted itself. At that point
+    // the caller may dispatch a change-injection breaker; if no breaker
+    // matches, the original throw path runs.
     const seenCycles = new Set();
-    /**
-     * Normalize a cycle by rotating it to start with the smallest node index.
-     * This allows us to compare cycles regardless of where they start.
-     */
-    function normalizeCycle(cycleNodeIndexes) {
-        if (cycleNodeIndexes.length === 0)
-            return "";
-        const minIndex = Math.min(...cycleNodeIndexes);
-        const minIndexPos = cycleNodeIndexes.indexOf(minIndex);
-        const rotated = [
-            ...cycleNodeIndexes.slice(minIndexPos),
-            ...cycleNodeIndexes.slice(0, minIndexPos),
-        ];
-        return rotated.join(",");
-    }
     while (true) {
-        // Edge deduplication moved outside loop
         const edgePairs = edgesToPairs(edges);
-        // Detect cycles
         const cycleNodeIndexes = findCycle(phaseChanges.length, edgePairs);
-        if (!cycleNodeIndexes) {
-            // No cycles found, we're done
+        if (!cycleNodeIndexes)
             break;
-        }
-        // Normalize cycle to check if we've seen it before
         const cycleSignature = normalizeCycle(cycleNodeIndexes);
         if (seenCycles.has(cycleSignature)) {
-            // We've seen this cycle before - filtering didn't break it
-            // Get edges involved in the cycle for detailed error message
-            const cycleEdges = getEdgesInCycle(cycleNodeIndexes, edges);
-            throw new Error(formatCycleError(cycleNodeIndexes, phaseChanges, cycleEdges));
+            // Edge filtering can't break this cycle. Report it back to the
+            // caller so it can try change-injection before throwing.
+            return {
+                kind: "unbreakable",
+                cycleNodeIndexes,
+                cycleEdges: getEdgesInCycle(cycleNodeIndexes, edges),
+            };
         }
-        // Track this cycle
         seenCycles.add(cycleSignature);
-        // Filter only edges involved in the cycle to break it
         edges = filterEdgesForCycleBreaking(edges, cycleNodeIndexes, phaseChanges, graphData);
     }
     const finalEdgePairs = edgesToPairs(edges);
-    // Debug visualization
     if (debugGraph.enabled) {
         printDebugGraph(phaseChanges, graphData, finalEdgePairs, dependencyRows, allConstraints);
     }
@@ -141,7 +149,54 @@ function sortPhaseChanges(phaseChanges, dependencyRows, options = {}) {
     const topologicalOrder = performStableTopologicalSort(phaseChanges.length, finalEdgePairs);
     if (!topologicalOrder || topologicalOrder.length !== phaseChanges.length) {
         // This should never happen if findCycle returned null, but guard anyway
-        throw new Error("CycleError: dependency graph contains a cycle");
+        throw new UnorderableCycleError("CycleError: dependency graph contains a cycle");
+    }
+    return {
+        kind: "sorted",
+        sorted: topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]),
+    };
+}
+/**
+ * Sort changes within a phase. Tries `attemptSortRound`; on an unbreakable
+ * cycle, dispatches to `tryBreakCycleByChangeInjection`, retries with the
+ * rewritten changes, and bails after `MAX_CYCLE_BREAKER_ROUNDS` to surface
+ * a buggy breaker as `CycleError` instead of an infinite loop.
+ *
+ * Best case (no cycles, the vast majority of plans): one round, no
+ * change-injection breaker code runs at all.
+ */
+function sortPhaseChanges(initialPhaseChanges, dependencyRows, options = {}) {
+    if (initialPhaseChanges.length <= 1)
+        return initialPhaseChanges;
+    let phaseChanges = initialPhaseChanges;
+    const breakerRoundSignatures = new Set();
+    // `attemptSortRound` returns at most one unbreakable cycle per call,
+    // so a phase with K independent unbreakable cycles needs K+1 rounds.
+    // Every cycle contains ≥ 2 distinct change nodes, so the maximum
+    // possible value of K is `floor(initialPhaseChanges.length / 2)` —
+    // using `initialPhaseChanges.length` itself is therefore a real upper
+    // bound with one round of slack (and matches the early-return guard
+    // above, which already excluded length-0 and length-1 phases).
+    const maxRounds = initialPhaseChanges.length;
+    for (let round = 0; round <= maxRounds; round++) {
+        const result = attemptSortRound(phaseChanges, dependencyRows, options);
+        if (result.kind === "sorted")
+            return result.sorted;
+        // Edge filtering hit an unbreakable cycle. Try the change-injection
+        // breakers (FK pattern, publication↔column pattern). If none matches,
+        // throw with the same diagnostic the original code emitted.
+        const broken = tryBreakCycleByChangeInjection(result.cycleNodeIndexes, phaseChanges);
+        if (broken === null) {
+            throw new UnorderableCycleError(formatCycleError(result.cycleNodeIndexes, phaseChanges, result.cycleEdges), result.cycleNodeIndexes.map((index) => phaseChanges[index]));
+        }
+        // Loop guard: if the same cycle node-set re-appears after a break,
+        // the breaker isn't making progress. Throw with full context.
+        const signature = normalizeCycle(result.cycleNodeIndexes);
+        if (breakerRoundSignatures.has(signature)) {
+            throw new UnorderableCycleError(formatCycleError(result.cycleNodeIndexes, phaseChanges, result.cycleEdges), result.cycleNodeIndexes.map((index) => phaseChanges[index]));
+        }
+        breakerRoundSignatures.add(signature);
+        phaseChanges = broken;
     }
-    return topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]);
+    throw new UnorderableCycleError(`CycleError: change-injection breaker exceeded ${maxRounds} rounds (one per node in the phase) — likely a buggy breaker rule`);
 }

package/dist/core/sort/topological-sort.js

@@ -5,7 +5,7 @@
  */
 export function performStableTopologicalSort(nodeCount, edges) {
     const adjacencyList = Array.from({ length: nodeCount }, () => new Set());
-    const inDegreeCounts = new Array(nodeCount).fill(0);
+    const inDegreeCounts = Array.from({ length: nodeCount }, () => 0);
     for (const [sourceIndex, targetIndex] of edges) {
         if (!adjacencyList[sourceIndex].has(targetIndex)) {
             adjacencyList[sourceIndex].add(targetIndex);
@@ -51,7 +51,7 @@ export function findCycle(nodeCount, edges) {
         adjacencyList[sourceIndex].push(targetIndex);
     }
     // 0 = unvisited, 1 = visiting, 2 = completed
-    const visitState = new Array(nodeCount).fill(0);
+    const visitState = Array.from({ length: nodeCount }, () => 0);
     const pathStack = [];
     let cycleNodeIndexes = null;
     const depthFirstSearch = (nodeIndex) => {

package/dist/core/sort/unorderable-cycle-error.d.ts

@@ -0,0 +1,18 @@
+import type { Change } from "../change.types.ts";
+/**
+ * Thrown by `sortChanges` when the dependency graph contains a cycle that
+ * neither weak-edge filtering nor the change-injection cycle breakers could
+ * resolve.
+ *
+ * `message` is the human-readable `formatCycleError` output (it starts with
+ * "CycleError:" for backward compatibility with log greps).
+ */
+export declare class UnorderableCycleError extends Error {
+    readonly name = "UnorderableCycleError";
+    /**
+     * Changes participating in the cycle, in cycle order. Empty when the
+     * failure came from an internal guard rather than a concrete cycle.
+     */
+    readonly cycle: readonly Change[];
+    constructor(message: string, cycle?: readonly Change[]);
+}

package/dist/core/sort/unorderable-cycle-error.js

@@ -0,0 +1,20 @@
+/**
+ * Thrown by `sortChanges` when the dependency graph contains a cycle that
+ * neither weak-edge filtering nor the change-injection cycle breakers could
+ * resolve.
+ *
+ * `message` is the human-readable `formatCycleError` output (it starts with
+ * "CycleError:" for backward compatibility with log greps).
+ */
+export class UnorderableCycleError extends Error {
+    name = "UnorderableCycleError";
+    /**
+     * Changes participating in the cycle, in cycle order. Empty when the
+     * failure came from an internal guard rather than a concrete cycle.
+     */
+    cycle;
+    constructor(message, cycle = []) {
+        super(message);
+        this.cycle = cycle;
+    }
+}

package/dist/core/sort/utils.d.ts

@@ -19,5 +19,15 @@ export declare function isMetadataStableId(stableId: string): boolean;
  * - ALTER operations with scope="privilege" → create_alter_object phase (metadata changes)
  * - ALTER operations that drop actual objects → drop phase (destructive ALTER)
  * - ALTER operations that don't drop objects → create_alter_object phase (non-destructive ALTER)
+ *
+ * Dependency-breaking ALTERs that remove a `pg_depend` edge to another
+ * object that may be dropped in the same plan (for example
+ * `ALTER COLUMN ... DROP DEFAULT` releasing a sequence reference, or
+ * `ALTER COLUMN ... TYPE <built-in>` releasing a user-defined type
+ * reference) are routed to the drop phase. The drop phase sorts in reverse
+ * dependency order using the main catalog, so the catalog edges already
+ * in `pg_depend` order the ALTER before any dependent `DROP TYPE` /
+ * `DROP SEQUENCE` / `DROP FUNCTION` and PostgreSQL no longer rejects the
+ * drop with error 2BP01.
  */
 export declare function getExecutionPhase(change: Change): Phase;

package/dist/core/sort/utils.js

@@ -1,3 +1,4 @@
+import { AlterTableAlterColumnDropDefault, AlterTableAlterColumnDropIdentity, AlterTableAlterColumnType, } from "../objects/table/changes/table.alter.js";
 /**
  * Check if a stable ID represents metadata (ACL, default privileges, comments, etc.)
  * rather than an actual database object.
@@ -20,6 +21,16 @@ export function isMetadataStableId(stableId) {
  * - ALTER operations with scope="privilege" → create_alter_object phase (metadata changes)
  * - ALTER operations that drop actual objects → drop phase (destructive ALTER)
  * - ALTER operations that don't drop objects → create_alter_object phase (non-destructive ALTER)
+ *
+ * Dependency-breaking ALTERs that remove a `pg_depend` edge to another
+ * object that may be dropped in the same plan (for example
+ * `ALTER COLUMN ... DROP DEFAULT` releasing a sequence reference, or
+ * `ALTER COLUMN ... TYPE <built-in>` releasing a user-defined type
+ * reference) are routed to the drop phase. The drop phase sorts in reverse
+ * dependency order using the main catalog, so the catalog edges already
+ * in `pg_depend` order the ALTER before any dependent `DROP TYPE` /
+ * `DROP SEQUENCE` / `DROP FUNCTION` and PostgreSQL no longer rejects the
+ * drop with error 2BP01.
  */
 export function getExecutionPhase(change) {
     // DROP operations always go to drop phase
@@ -43,6 +54,23 @@ export function getExecutionPhase(change) {
             // Destructive ALTER (DROP COLUMN, DROP CONSTRAINT, etc.) → drop phase
             return "drop";
         }
+        // Dependency-breaking column ALTERs that release a pg_depend edge.
+        // Routing these to the drop phase lets the existing catalog dependency
+        // edges (column → sequence, column → identity sequence) order them
+        // before the matching DROP statement.
+        if (change instanceof AlterTableAlterColumnDropDefault ||
+            change instanceof AlterTableAlterColumnDropIdentity) {
+            return "drop";
+        }
+        // ALTER COLUMN ... TYPE only safely runs in the drop phase when the
+        // target type is built-in. For user-defined target types we cannot tell
+        // here whether the type is created in the same plan, and the create
+        // happens in create_alter phase, so we keep the alter in that phase to
+        // preserve the create-then-alter ordering.
+        if (change instanceof AlterTableAlterColumnType &&
+            !change.column.is_custom_type) {
+            return "drop";
+        }
         // Non-destructive ALTER (ADD COLUMN, GRANT, etc.) → create_alter phase
         return "create_alter_object";
     }

package/dist/core/test-utils/assert-valid-sql.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Assert that the given SQL string is syntactically valid PostgreSQL.
+ *
+ * Uses the PostgreSQL parser from `@supabase/pg-topo` to ensure that
+ * serialized DDL statements are syntactically correct. This catches
+ * issues like malformed function signatures, missing keywords, etc.
+ *
+ * @param sql - The SQL string to validate (typically from `change.serialize()`).
+ */
+export declare function assertValidSql(sql: string): Promise<void>;

package/dist/core/test-utils/assert-valid-sql.js

@@ -0,0 +1,19 @@
+import { validateSqlSyntax } from "@supabase/pg-topo";
+/**
+ * Assert that the given SQL string is syntactically valid PostgreSQL.
+ *
+ * Uses the PostgreSQL parser from `@supabase/pg-topo` to ensure that
+ * serialized DDL statements are syntactically correct. This catches
+ * issues like malformed function signatures, missing keywords, etc.
+ *
+ * @param sql - The SQL string to validate (typically from `change.serialize()`).
+ */
+export async function assertValidSql(sql) {
+    try {
+        await validateSqlSyntax(sql);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown parser error";
+        throw new Error(`Invalid SQL syntax: ${message}\nSQL: ${sql}`);
+    }
+}

package/dist/index.d.ts

@@ -3,7 +3,20 @@
  *
  * This module exports the public API for the pg-delta library.
  */
+export { Catalog, createEmptyCatalog, extractCatalog, } from "./core/catalog.model.ts";
+export type { CatalogSnapshot } from "./core/catalog.snapshot.ts";
+export { deserializeCatalog, serializeCatalog, stringifyCatalogSnapshot, } from "./core/catalog.snapshot.ts";
+export { exportDeclarativeSchema } from "./core/export/index.ts";
+export type { DeclarativeSchemaOutput, FileCategory, FileEntry, FileMetadata, } from "./core/export/types.ts";
 export type { IntegrationDSL } from "./core/integrations/integration-dsl.ts";
+export type { Change } from "./core/change.types.ts";
 export { applyPlan } from "./core/plan/apply.ts";
+export type { CatalogInput } from "./core/plan/create.ts";
 export { createPlan } from "./core/plan/create.ts";
-export type { CreatePlanOptions, Plan } from "./core/plan/types.ts";
+export type { RenderedPlanFile, RenderPlanSqlOptions, } from "./core/plan/render.ts";
+export { flattenPlanStatements, renderPlanFiles, renderPlanSql, } from "./core/plan/render.ts";
+export type { SqlFormatOptions } from "./core/plan/sql-format.ts";
+export { formatSqlStatements } from "./core/plan/sql-format.ts";
+export type { CreatePlanOptions, ExecutionBoundaryReason, MigrationUnit, Plan, TransactionMode, } from "./core/plan/types.ts";
+export { UnorderableCycleError } from "./core/sort/unorderable-cycle-error.ts";
+export { createManagedPool } from "./core/postgres-config.ts";

package/dist/index.js

@@ -3,6 +3,15 @@
  *
  * This module exports the public API for the pg-delta library.
  */
+// Catalog model and extraction
+export { Catalog, createEmptyCatalog, extractCatalog, } from "./core/catalog.model.js";
+export { deserializeCatalog, serializeCatalog, stringifyCatalogSnapshot, } from "./core/catalog.snapshot.js";
+// Declarative schema export
+export { exportDeclarativeSchema } from "./core/export/index.js";
 export { applyPlan } from "./core/plan/apply.js";
-// Core operations
 export { createPlan } from "./core/plan/create.js";
+export { flattenPlanStatements, renderPlanFiles, renderPlanSql, } from "./core/plan/render.js";
+export { formatSqlStatements } from "./core/plan/sql-format.js";
+export { UnorderableCycleError } from "./core/sort/unorderable-cycle-error.js";
+// Postgres config
+export { createManagedPool } from "./core/postgres-config.js";

package/package.json

@@ -1,70 +1,108 @@
 {
   "name": "@supabase/pg-delta",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.30",
   "description": "PostgreSQL migrations made easy",
-  "type": "module",
-  "sideEffects": false,
-  "exports": {
-    ".": "./dist/index.js",
-    "./integrations/supabase": "./dist/core/integrations/supabase.js"
+  "keywords": [
+    "diff",
+    "migrations",
+    "pg",
+    "pg-delta",
+    "pgdelta",
+    "postgres"
+  ],
+  "homepage": "https://github.com/supabase/pg-toolbelt",
+  "bugs": "https://github.com/supabase/pg-toolbelt/issues",
+  "license": "MIT",
+  "author": "Supabase",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/supabase/pg-toolbelt.git",
+    "directory": "packages/pg-delta"
   },
   "bin": {
     "pgdelta": "./dist/cli/bin/cli.js"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],
-  "keywords": [
-    "pg",
-    "postgres",
-    "migrations",
-    "diff",
-    "pg-delta",
-    "pgdelta"
-  ],
-  "author": "Supabase",
-  "license": "MIT",
-  "homepage": "https://github.com/supabase/pg-delta",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/supabase/pg-delta.git"
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./integrations/supabase": {
+      "bun": "./src/core/integrations/supabase.ts",
+      "import": "./dist/core/integrations/supabase.js",
+      "require": "./dist/core/integrations/supabase.js",
+      "types": "./dist/core/integrations/supabase.d.ts",
+      "default": "./dist/core/integrations/supabase.js"
+    },
+    "./declarative": {
+      "bun": "./src/core/declarative-apply/index.ts",
+      "import": "./dist/core/declarative-apply/index.js",
+      "require": "./dist/core/declarative-apply/index.js",
+      "types": "./dist/core/declarative-apply/index.d.ts",
+      "default": "./dist/core/declarative-apply/index.js"
+    },
+    "./catalog-export": {
+      "bun": "./src/core/catalog-export/index.ts",
+      "import": "./dist/core/catalog-export/index.js",
+      "require": "./dist/core/catalog-export/index.js",
+      "types": "./dist/core/catalog-export/index.d.ts",
+      "default": "./dist/core/catalog-export/index.js"
+    }
   },
-  "bugs": "https://github.com/supabase/pg-delta/issues",
-  "engines": {
-    "node": ">=20.0.0"
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "docs": "typedoc",
+    "format-and-lint": "oxfmt --check . && oxlint --deny-warnings",
+    "format-and-lint:fix": "oxfmt . && oxlint --fix",
+    "knip": "knip",
+    "pgdelta": "bun src/cli/bin/cli.ts",
+    "sync-base-images": "bun scripts/sync-supabase-base-images.ts",
+    "test": "bun scripts/run-tests.ts",
+    "test:unit": "bun run test src/",
+    "test:integration": "bun run test tests/",
+    "update-empty-baseline": "bun scripts/update-empty-catalog-baseline.ts",
+    "version": "changeset version && bun install --no-frozen-lockfile && bun run format-and-lint:fix"
   },
   "dependencies": {
     "@stricli/core": "^1.2.4",
+    "@supabase/pg-topo": "^1.0.0-alpha.2",
     "@ts-safeql/sql-tag": "^0.2.0",
     "chalk": "^5.6.2",
     "debug": "^4.3.7",
     "pg": "^8.17.2",
+    "picomatch": "^4.0.3",
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.10",
-    "@types/pg": "^8.11.10",
-    "@changesets/cli": "^2.29.8",
+    "@supabase/bun-istanbul-coverage": "workspace:*",
     "@tsconfig/node-ts": "^23.6.2",
     "@tsconfig/node24": "^24.0.3",
+    "@types/bun": "^1.3.9",
     "@types/debug": "^4.1.12",
     "@types/node": "^24.10.4",
-    "@vitest/coverage-v8": "4.0.16",
+    "@types/pg": "^8.11.10",
+    "@types/picomatch": "^4.0.2",
     "dedent": "^1.7.1",
     "knip": "^5.75.2",
     "testcontainers": "^11.10.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "typedoc": "^0.28.17",
+    "typescript": "^5.9.3"
   },
-  "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "check-types": "tsc --noEmit",
-    "format-and-lint": "biome check . --error-on-warnings",
-    "knip": "knip",
-    "pgdelta": "node src/cli/bin/cli.ts",
-    "test": "vitest",
-    "version": "changeset version && pnpm install --no-frozen-lockfile && pnpm format-and-lint --write"
+  "engines": {
+    "node": ">=20.0.0"
   }
-}
+}

package/src/cli/app.ts

@@ -0,0 +1,52 @@
+import { buildApplication, buildRouteMap } from "@stricli/core";
+import { applyCommand } from "./commands/apply.ts";
+import { catalogExportCommand } from "./commands/catalog-export.ts";
+import { declarativeApplyCommand } from "./commands/declarative-apply.ts";
+import { declarativeExportCommand } from "./commands/declarative-export.ts";
+import { planCommand } from "./commands/plan.ts";
+import { syncCommand } from "./commands/sync.ts";
+
+const declarativeRouteMap = buildRouteMap({
+  routes: {
+    apply: declarativeApplyCommand,
+    export: declarativeExportCommand,
+  },
+  docs: {
+    brief: "Declarative schema management",
+    fullDescription: `
+Manage declarative SQL schemas.
+
+Commands:
+  apply  - Apply a declarative SQL schema to a database
+  export - Export a declarative schema from a database diff
+    `.trim(),
+  },
+});
+
+const root = buildRouteMap({
+  routes: {
+    plan: planCommand,
+    apply: applyCommand,
+    sync: syncCommand,
+    declarative: declarativeRouteMap,
+    "catalog-export": catalogExportCommand,
+  },
+  defaultCommand: "sync",
+  docs: {
+    brief: "PostgreSQL migrations made easy",
+    fullDescription: `
+pgdelta generates migration scripts by comparing two PostgreSQL databases.
+
+Commands:
+  plan           - Compute schema diff and preview changes
+  apply          - Apply a plan's migration script to a database
+  sync           - Plan and apply changes in one go
+  declarative    - Declarative schema (apply | export)
+  catalog-export - Export a database catalog as a snapshot JSON file
+    `.trim(),
+  },
+});
+
+export const app = buildApplication(root, {
+  name: "pgdelta",
+});

package/src/cli/bin/cli.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { run } from "@stricli/core";
+import { UnorderableCycleError } from "../../core/sort/unorderable-cycle-error.ts";
+import { app } from "../app.ts";
+import { getCommandExitCode } from "../exit-code.ts";
+
+await run(app, process.argv.slice(2), { process }).catch((error) => {
+  if (error instanceof UnorderableCycleError) {
+    console.error(error.message);
+    console.error(
+      "pg-delta could not find a valid execution order for these changes. Please report this plan at https://github.com/supabase/pg-toolbelt/issues.",
+    );
+  } else {
+    console.error(error);
+  }
+  process.exit(1);
+});
+
+const code = getCommandExitCode();
+if (code !== undefined) {
+  process.exitCode = code;
+}