@supabase/pg-delta 1.0.0-alpha.4 → 1.0.0-alpha.6

package/src/cli/commands/declarative-export.ts

@@ -0,0 +1,330 @@
+/**
+ * Declarative export command - export a declarative SQL schema from a database diff.
+ */
+
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { buildCommand, type CommandContext } from "@stricli/core";
+import chalk from "chalk";
+import type { CatalogSnapshot } from "../../core/catalog.snapshot.ts";
+import { exportDeclarativeSchema } from "../../core/export/index.ts";
+import type { Grouping, GroupingPattern } from "../../core/export/types.ts";
+import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
+import type { ChangeFilter } from "../../core/integrations/filter/filter.types.ts";
+import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
+import type { ChangeSerializer } from "../../core/integrations/serialize/serialize.types.ts";
+import { createPlan } from "../../core/plan/index.ts";
+import type { SqlFormatOptions } from "../../core/plan/sql-format.ts";
+import {
+  assertSafePath,
+  buildFileTree,
+  computeFileDiff,
+  formatExportSummary,
+} from "../utils/export-display.ts";
+import { loadIntegrationDSL } from "../utils/integrations.ts";
+import { isPostgresUrl, loadCatalogFromFile } from "../utils/resolve-input.ts";
+
+function parseJsonFlag<T>(label: string, value: string): T {
+  try {
+    return JSON.parse(value) as T;
+  } catch (error) {
+    throw new Error(
+      `Invalid ${label} JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+export const declarativeExportCommand = buildCommand({
+  parameters: {
+    flags: {
+      source: {
+        kind: "parsed",
+        brief:
+          "Source (current state): postgres URL or catalog snapshot file path. Omit to export all objects from target.",
+        parse: String,
+        optional: true,
+      },
+      target: {
+        kind: "parsed",
+        brief:
+          "Target (desired state): postgres URL or catalog snapshot file path",
+        parse: String,
+      },
+      output: {
+        kind: "parsed",
+        brief: "Output directory path for declarative schema files",
+        parse: String,
+      },
+      integration: {
+        kind: "parsed",
+        brief:
+          "Integration name (e.g., 'supabase') or path to integration JSON file",
+        parse: String,
+        optional: true,
+      },
+      filter: {
+        kind: "parsed",
+        brief: 'Filter DSL as inline JSON (e.g., \'{"schema":"public"}\')',
+        parse: (v: string) => parseJsonFlag<FilterDSL>("filter", v),
+        optional: true,
+      },
+      serialize: {
+        kind: "parsed",
+        brief:
+          'Serialize DSL as inline JSON array (e.g., \'[{"when":{"type":"schema"},"options":{"skipAuthorization":true}}]\')',
+        parse: (v: string) => parseJsonFlag<SerializeDSL>("serialize", v),
+        optional: true,
+      },
+      "grouping-mode": {
+        kind: "enum",
+        brief: "How grouped entities are organized on disk",
+        values: ["single-file", "subdirectory"] as const,
+        optional: true,
+      },
+      "group-patterns": {
+        kind: "parsed",
+        brief:
+          'JSON array of {pattern, name} objects (e.g., \'[{"pattern":"^auth","name":"auth"}]\')',
+        parse: (v: string) => {
+          const parsed = parseJsonFlag<GroupingPattern[]>("group-patterns", v);
+          if (!Array.isArray(parsed)) {
+            throw new Error("group-patterns must be a JSON array");
+          }
+          return parsed;
+        },
+        optional: true,
+      },
+      "flat-schemas": {
+        kind: "parsed",
+        brief:
+          "Comma-separated list of schemas to flatten (e.g., partman,pgboss,audit)",
+        parse: String,
+        optional: true,
+      },
+      "format-options": {
+        kind: "parsed",
+        brief:
+          'SQL format options as inline JSON (e.g., \'{"keywordCase":"lower","maxWidth":180}\')',
+        parse: (v: string) =>
+          parseJsonFlag<SqlFormatOptions>("format-options", v),
+        optional: true,
+      },
+      force: {
+        kind: "boolean",
+        brief: "Remove entire output directory before writing",
+        optional: true,
+      },
+      "dry-run": {
+        kind: "boolean",
+        brief: "Show tree and summary without writing files",
+        optional: true,
+      },
+      "diff-focus": {
+        kind: "boolean",
+        brief:
+          "Show only files that changed (created/updated/deleted) in the tree",
+        optional: true,
+      },
+      verbose: {
+        kind: "boolean",
+        brief: "Show detailed output",
+        optional: true,
+      },
+    },
+    aliases: {
+      s: "source",
+      t: "target",
+      o: "output",
+    },
+  },
+  docs: {
+    brief: "Export a declarative schema from a database diff",
+    fullDescription: `
+Export a declarative SQL schema by comparing two databases (source → target).
+Writes .sql files to the output directory, grouped by object type and optional
+grouping rules.
+
+When --source is omitted, all objects from the target database are exported
+(equivalent to diffing from an empty database).
+
+Flags:
+  source         - Source database connection URL (optional; omit for full export)
+  target         - Target database connection URL (desired state)
+  output         - Directory path for generated .sql files
+  integration    - Integration name or path (e.g., supabase) for filter/serialize
+  filter         - Filter DSL as JSON to include/exclude changes
+  serialize      - Serialize DSL as JSON array for custom SQL generation
+  grouping-mode  - single-file or subdirectory for grouped entities
+  group-patterns - JSON array of {pattern, name} for name-based grouping
+  flat-schemas   - Comma-separated schemas to merge into one file per category
+  format-options - SQL format options as JSON
+  force          - Remove output directory before writing (full replace)
+  dry-run        - Show tree and summary only, do not write files
+  diff-focus     - Show only changed files (created/updated/deleted) in the tree
+  verbose        - Show detailed output
+
+After export, a tip is printed with the command to apply the schema to an empty database.
+    `.trim(),
+  },
+  async func(
+    this: CommandContext,
+    flags: {
+      source?: string;
+      target: string;
+      output: string;
+      integration?: string;
+      filter?: FilterDSL;
+      serialize?: SerializeDSL;
+      "grouping-mode"?: "single-file" | "subdirectory";
+      "group-patterns"?: GroupingPattern[];
+      "flat-schemas"?: string;
+      "format-options"?: SqlFormatOptions;
+      force?: boolean;
+      "dry-run"?: boolean;
+      "diff-focus"?: boolean;
+      verbose?: boolean;
+    },
+  ) {
+    const { compileSerializeDSL } = await import(
+      "../../core/integrations/serialize/dsl.ts"
+    );
+
+    let filterOption: FilterDSL | ChangeFilter | undefined = flags.filter;
+    let serializeOption: SerializeDSL | ChangeSerializer | undefined =
+      flags.serialize;
+    let integrationEmptyCatalog: CatalogSnapshot | undefined;
+    if (flags.integration) {
+      const integrationDSL = await loadIntegrationDSL(flags.integration);
+      filterOption = filterOption ?? integrationDSL.filter;
+      serializeOption = serializeOption ?? integrationDSL.serialize;
+      integrationEmptyCatalog = integrationDSL.emptyCatalog;
+    }
+
+    const resolvedSource = flags.source
+      ? isPostgresUrl(flags.source)
+        ? flags.source
+        : await loadCatalogFromFile(flags.source)
+      : integrationEmptyCatalog
+        ? (await import("../../core/catalog.snapshot.ts")).deserializeCatalog(
+            integrationEmptyCatalog,
+          )
+        : null;
+
+    const resolvedTarget = isPostgresUrl(flags.target)
+      ? flags.target
+      : await loadCatalogFromFile(flags.target);
+
+    // Pass raw DSL to createPlan (not pre-compiled functions).
+    // createPlan compiles them internally and uses the DSL type to correctly
+    // determine cascade behavior: DSL filters disable cascading by default
+    // (unless cascade:true is set), preventing unintended exclusion of
+    // changes that depend on filtered objects (e.g. RLS policies that
+    // reference auth.uid() when the auth schema is filtered out).
+    const planResult = await createPlan(resolvedSource, resolvedTarget, {
+      filter: filterOption,
+      serialize: serializeOption,
+      skipDefaultPrivilegeSubtraction: true,
+    });
+
+    if (!planResult) {
+      this.process.stdout.write("No changes detected.\n");
+      return;
+    }
+
+    const hasGrouping =
+      flags["grouping-mode"] !== undefined ||
+      (flags["group-patterns"] !== undefined &&
+        flags["group-patterns"].length > 0) ||
+      (flags["flat-schemas"] !== undefined && flags["flat-schemas"].length > 0);
+
+    let grouping: Grouping | undefined;
+    if (hasGrouping) {
+      grouping = {
+        mode: flags["grouping-mode"] ?? "single-file",
+        groupPatterns: flags["group-patterns"],
+        autoGroupPartitions: true,
+        flatSchemas:
+          flags["flat-schemas"] !== undefined
+            ? flags["flat-schemas"]
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : undefined,
+      };
+    }
+
+    const serializeFn =
+      serializeOption !== undefined
+        ? compileSerializeDSL(serializeOption)
+        : undefined;
+
+    const output = exportDeclarativeSchema(planResult, {
+      integration:
+        serializeFn !== undefined ? { serialize: serializeFn } : undefined,
+      formatOptions: flags["format-options"] ?? undefined,
+      grouping,
+      onWarning: (msg) => {
+        this.process.stderr.write(chalk.yellow(`Warning: ${msg}\n`));
+      },
+    });
+
+    const outputDir = path.resolve(flags.output);
+    const applyTip = (dir: string) =>
+      `\nTip: To apply this schema to an empty database, run:\n  pgdelta declarative apply --path ${dir} --target <database_url>\n`;
+    const diff = await computeFileDiff(outputDir, output.files);
+
+    this.process.stdout.write("\n");
+    this.process.stdout.write(
+      `${buildFileTree(
+        output.files.map((f) => f.path),
+        path.basename(outputDir) || outputDir,
+        { diff, diffFocus: !!flags["diff-focus"] },
+      )}\n`,
+    );
+    this.process.stdout.write("\n");
+    this.process.stdout.write(
+      `${chalk.green("+")} created   ${chalk.yellow("~")} updated   ${chalk.red("-")} deleted\n`,
+    );
+    this.process.stdout.write("\n");
+
+    const summary = formatExportSummary(diff, !!flags["dry-run"]);
+    if (summary) {
+      this.process.stdout.write(`${summary}\n`);
+    }
+
+    const totalChanges = planResult.sortedChanges.length;
+    const totalStatements = output.files.reduce((s, f) => s + f.statements, 0);
+    this.process.stdout.write(
+      `Changes: ${totalChanges} | Files: ${output.files.length} | Statements: ${totalStatements}\n`,
+    );
+
+    if (flags["dry-run"]) {
+      this.process.stdout.write(chalk.dim("\n(dry-run: no files written)\n"));
+      this.process.stdout.write(chalk.cyan(applyTip(outputDir)));
+      return;
+    }
+
+    if (flags.force) {
+      await rm(outputDir, { recursive: true, force: true });
+      await mkdir(outputDir, { recursive: true });
+    } else if (diff.deleted.length > 0) {
+      this.process.stderr.write(
+        chalk.yellow(
+          `Warning: ${diff.deleted.length} existing file(s) will no longer be present. Use --force to replace the output directory.\n`,
+        ),
+      );
+    }
+
+    for (const file of output.files) {
+      assertSafePath(file.path, outputDir);
+      const filePath = path.join(outputDir, file.path);
+      await mkdir(path.dirname(filePath), { recursive: true });
+      await writeFile(filePath, file.sql);
+    }
+
+    this.process.stdout.write(
+      chalk.green(`Wrote ${output.files.length} file(s) to ${outputDir}\n`),
+    );
+    this.process.stdout.write(chalk.cyan(applyTip(outputDir)));
+  },
+});

package/src/cli/commands/plan.ts

@@ -10,7 +10,9 @@ import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
 import type { ChangeSerializer } from "../../core/integrations/serialize/serialize.types.ts";
 import { createPlan } from "../../core/plan/index.ts";
 import type { SqlFormatOptions } from "../../core/plan/sql-format.ts";
+import { setCommandExitCode } from "../exit-code.ts";
 import { loadIntegrationDSL } from "../utils/integrations.ts";
+import { isPostgresUrl, loadCatalogFromFile } from "../utils/resolve-input.ts";
 import { formatPlanForDisplay } from "../utils.ts";
 
 export const planCommand = buildCommand({
@@ -18,12 +20,15 @@ export const planCommand = buildCommand({
     flags: {
       source: {
         kind: "parsed",
-        brief: "Source database connection URL (current state)",
+        brief:
+          "Source (current state): postgres URL or catalog snapshot file path. Omit for empty baseline.",
         parse: String,
+        optional: true,
       },
       target: {
         kind: "parsed",
-        brief: "Target database connection URL (desired state)",
+        brief:
+          "Target (desired state): postgres URL or catalog snapshot file path",
         parse: String,
       },
       format: {
@@ -121,7 +126,7 @@ json/sql outputs are available for artifacts or piping.
   async func(
     this: CommandContext,
     flags: {
-      source: string;
+      source?: string;
       target: string;
       format?: "json" | "sql";
       output?: string;
@@ -133,18 +138,34 @@ json/sql outputs are available for artifacts or piping.
       "sql-format-options"?: SqlFormatOptions;
     },
   ) {
-    // Load integration if provided and extract filter/serialize DSL
     let filterOption: FilterDSL | ChangeFilter | undefined = flags.filter;
     let serializeOption: SerializeDSL | ChangeSerializer | undefined =
       flags.serialize;
+    let integrationEmptyCatalog:
+      | import("../../core/catalog.snapshot.ts").CatalogSnapshot
+      | undefined;
     if (flags.integration) {
       const integrationDSL = await loadIntegrationDSL(flags.integration);
-      // Use integration DSL if explicit flags not provided
       filterOption = filterOption ?? integrationDSL.filter;
       serializeOption = serializeOption ?? integrationDSL.serialize;
+      integrationEmptyCatalog = integrationDSL.emptyCatalog;
     }
 
-    const planResult = await createPlan(flags.source, flags.target, {
+    const resolvedSource = flags.source
+      ? isPostgresUrl(flags.source)
+        ? flags.source
+        : await loadCatalogFromFile(flags.source)
+      : integrationEmptyCatalog
+        ? (await import("../../core/catalog.snapshot.ts")).deserializeCatalog(
+            integrationEmptyCatalog,
+          )
+        : null;
+
+    const resolvedTarget = isPostgresUrl(flags.target)
+      ? flags.target
+      : await loadCatalogFromFile(flags.target);
+
+    const planResult = await createPlan(resolvedSource, resolvedTarget, {
       role: flags.role,
       filter: filterOption,
       serialize: serializeOption,
@@ -190,6 +211,6 @@ json/sql outputs are available for artifacts or piping.
     }
 
     // Exit code 2 indicates changes were detected
-    process.exitCode = 2;
+    setCommandExitCode(2);
   },
 });

package/src/cli/exit-code.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+import { getCommandExitCode, setCommandExitCode } from "./exit-code.ts";
+
+describe("exit-code", () => {
+  test("getCommandExitCode returns undefined when never set", () => {
+    expect(getCommandExitCode()).toBeUndefined();
+  });
+
+  test("setCommandExitCode then getCommandExitCode returns the value", () => {
+    setCommandExitCode(2);
+    expect(getCommandExitCode()).toBe(2);
+  });
+
+  test("setCommandExitCode overwrites previous value", () => {
+    setCommandExitCode(2);
+    setCommandExitCode(0);
+    expect(getCommandExitCode()).toBe(0);
+  });
+});

package/src/cli/exit-code.ts

@@ -0,0 +1,7 @@
+let _exitCode: number | undefined;
+export function setCommandExitCode(code: number) {
+  _exitCode = code;
+}
+export function getCommandExitCode() {
+  return _exitCode;
+}

package/src/cli/formatters/tree/tree.ts

@@ -18,7 +18,7 @@ export function formatTree(plan: HierarchicalPlan): string {
   lines.push(
     chalk.bold(`📋 Migration Plan: ${total} change${total !== 1 ? "s" : ""}`),
   );
-  const summary = buildSummaryLine(plan);
+  const summary = buildPlanSummaryTable(plan);
   if (summary) {
     lines.push("");
     lines.push(summary);
@@ -54,8 +54,9 @@ function countTotalChanges(plan: HierarchicalPlan): number {
 
 /**
  * Build summary as a table showing counts by entity type and operation.
+ * Exported for use by declarative-export to show the same summary style.
  */
-function buildSummaryLine(plan: HierarchicalPlan): string {
+function buildPlanSummaryTable(plan: HierarchicalPlan): string {
   // Count by object type
   const byType: Record<
     string,