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

package/src/cli/utils/export-display.ts

@@ -0,0 +1,275 @@
+/**
+ * CLI helpers for declarative export: file tree, diff, and summary formatting.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import chalk from "chalk";
+import type { FileEntry } from "../../core/export/types.ts";
+
+// ============================================================================
+// Path safety
+// ============================================================================
+
+/**
+ * Ensure a relative file path does not escape the output directory.
+ * Uses Node.js path.resolve + startsWith as the canonical traversal check.
+ */
+export function assertSafePath(filePath: string, outputDir: string): void {
+  const resolvedOutput = path.resolve(outputDir);
+  const resolvedFile = path.resolve(outputDir, filePath);
+  if (
+    resolvedFile !== resolvedOutput &&
+    !resolvedFile.startsWith(resolvedOutput + path.sep)
+  ) {
+    throw new Error(
+      `Export path traversal detected: '${filePath}' resolves outside output directory`,
+    );
+  }
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface FileDiffResult {
+  created: string[];
+  updated: string[];
+  deleted: string[];
+  unchanged: string[];
+}
+
+// ============================================================================
+// File tree
+// ============================================================================
+
+interface BuildFileTreeOptions {
+  /** When provided, leaf paths are prefixed with + / ~ / - and colorized (created / updated / deleted). */
+  diff?: FileDiffResult;
+  /** When true, only paths that are created, updated, or deleted are shown; unchanged are omitted. Includes diff.deleted in the tree. */
+  diffFocus?: boolean;
+}
+
+type FileStatus = "created" | "updated" | "deleted" | "unchanged";
+
+function getFileStatus(path: string, diff: FileDiffResult): FileStatus {
+  if (diff.created.includes(path)) return "created";
+  if (diff.updated.includes(path)) return "updated";
+  if (diff.deleted.includes(path)) return "deleted";
+  return "unchanged";
+}
+
+function formatLeafSegment(segment: string, status: FileStatus): string {
+  switch (status) {
+    case "created":
+      return chalk.green(`+ ${segment}`);
+    case "updated":
+      return chalk.yellow(`~ ${segment}`);
+    case "deleted":
+      return chalk.red(`- ${segment}`);
+    default:
+      return chalk.dim(segment);
+  }
+}
+
+/**
+ * Build a directory tree string from file paths.
+ * Groups by directory, shows files as leaves with indentation.
+ * When options.diff is provided, leaf names are prefixed with + (created), ~ (updated), - (deleted) and colorized.
+ * When options.diffFocus is true, only changed paths (and their ancestors) are shown; unchanged files are omitted.
+ *
+ * @param files - Array of relative file paths (e.g. ["schemas/public/schema.sql", "schemas/public/tables/users.sql"])
+ * @param outputDir - Display name for the root (e.g. "declarative-schemas")
+ * @param options - Optional diff and diffFocus for symbols and filtering
+ */
+export function buildFileTree(
+  files: string[],
+  outputDir: string,
+  options?: BuildFileTreeOptions,
+): string {
+  const { diff, diffFocus } = options ?? {};
+  let pathsToShow = files;
+
+  if (diffFocus && diff) {
+    const changed = new Set<string>([
+      ...diff.created,
+      ...diff.updated,
+      ...diff.deleted,
+    ]);
+    pathsToShow = [...changed];
+    if (pathsToShow.length === 0) {
+      return chalk.dim("(no file changes)");
+    }
+  }
+
+  const tree = new Map<string, Set<string>>();
+
+  for (const filePath of pathsToShow) {
+    const segments = filePath.split("/");
+    let parent = "";
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i];
+      const fullPath = parent ? `${parent}/${segment}` : segment;
+      let children = tree.get(parent);
+      if (!children) {
+        children = new Set();
+        tree.set(parent, children);
+      }
+      children.add(fullPath);
+      parent = fullPath;
+    }
+  }
+
+  const lines: string[] = [];
+
+  function emit(relPath: string, indent: number, isLast: boolean): void {
+    const segment = relPath ? path.basename(relPath) : outputDir;
+    const prefix =
+      indent === 0 ? "" : "  ".repeat(indent) + (isLast ? "└── " : "├── ");
+    const isLeaf = !tree.has(relPath);
+    const displaySegment =
+      diff && isLeaf
+        ? formatLeafSegment(segment, getFileStatus(relPath, diff))
+        : segment;
+    lines.push(prefix + displaySegment);
+    const children = tree.get(relPath);
+    if (children) {
+      const sorted = [...children].sort((a, b) =>
+        path.basename(a).localeCompare(path.basename(b)),
+      );
+      for (let i = 0; i < sorted.length; i++) {
+        emit(sorted[i], indent + 1, i === sorted.length - 1);
+      }
+    }
+  }
+
+  emit("", 0, false);
+  return lines.join("\n");
+}
+
+// ============================================================================
+// File diff
+// ============================================================================
+
+/**
+ * Recursively collect relative paths of managed (.sql) files under a directory.
+ * Non-SQL files (README, .gitkeep, etc.) are intentionally excluded so they
+ * are never flagged as "deleted" during diff.
+ */
+async function collectExistingFiles(dir: string, base = ""): Promise<string[]> {
+  const entries = await readdir(path.join(dir, base), { withFileTypes: true });
+  const files: string[] = [];
+  for (const e of entries) {
+    const rel = base ? `${base}/${e.name}` : e.name;
+    if (e.isFile() && e.name.endsWith(".sql")) {
+      files.push(rel);
+    } else if (e.isDirectory()) {
+      files.push(...(await collectExistingFiles(dir, rel)));
+    }
+  }
+  return files;
+}
+
+/**
+ * Compare existing output directory with new file set.
+ * Returns created, updated, deleted, and unchanged paths.
+ */
+export async function computeFileDiff(
+  outputDir: string,
+  newFiles: FileEntry[],
+): Promise<FileDiffResult> {
+  const newPaths = new Set(newFiles.map((f) => f.path));
+  const newByPath = new Map(newFiles.map((f) => [f.path, f]));
+
+  let existingPaths: string[] = [];
+  try {
+    existingPaths = await collectExistingFiles(outputDir);
+  } catch {
+    // Directory doesn't exist or not readable
+    return {
+      created: [...newPaths],
+      updated: [],
+      deleted: [],
+      unchanged: [],
+    };
+  }
+
+  const existingSet = new Set(existingPaths);
+  const created: string[] = [];
+  const updated: string[] = [];
+  const deleted: string[] = [];
+  const unchanged: string[] = [];
+
+  for (const p of newPaths) {
+    if (!existingSet.has(p)) {
+      created.push(p);
+    } else {
+      const entry = newByPath.get(p);
+      if (!entry) continue;
+      try {
+        const existingContent = await readFile(
+          path.join(outputDir, p),
+          "utf-8",
+        );
+        if (existingContent.trim() !== entry.sql.trim()) {
+          updated.push(p);
+        } else {
+          unchanged.push(p);
+        }
+      } catch {
+        updated.push(p);
+      }
+    }
+  }
+
+  for (const p of existingPaths) {
+    if (!newPaths.has(p)) {
+      deleted.push(p);
+    }
+  }
+
+  return { created, updated, deleted, unchanged };
+}
+
+// ============================================================================
+// Summary formatting
+// ============================================================================
+
+/**
+ * Format the created/deleted/updated summary with colors.
+ * In dry-run mode, uses "would create/delete/update" phrasing.
+ */
+export function formatExportSummary(
+  diff: FileDiffResult,
+  dryRun: boolean,
+): string {
+  const lines: string[] = [];
+  const verb = dryRun ? "Would" : "";
+
+  if (diff.created.length > 0) {
+    lines.push(
+      chalk.green(
+        `${verb ? `${verb} create` : "Created"}: ${diff.created.length} file(s)`,
+      ),
+    );
+  }
+  if (diff.updated.length > 0) {
+    lines.push(
+      chalk.yellow(
+        `${verb ? `${verb} update` : "Updated"}: ${diff.updated.length} file(s)`,
+      ),
+    );
+  }
+  if (diff.deleted.length > 0) {
+    lines.push(
+      chalk.red(
+        `${verb ? `${verb} delete` : "Deleted"}: ${diff.deleted.length} file(s)`,
+      ),
+    );
+  }
+  if (diff.unchanged.length > 0 && !dryRun) {
+    lines.push(chalk.dim(`Unchanged: ${diff.unchanged.length} file(s)`));
+  }
+
+  return lines.length > 0 ? lines.join("\n") : "";
+}

package/src/cli/utils/integrations.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { loadIntegrationDSL } from "./integrations.ts";
+
+describe("loadIntegrationDSL", () => {
+  test("loads from .json file path", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-integration-"));
+    const jsonPath = path.join(dir, "custom.json");
+    try {
+      await writeFile(
+        jsonPath,
+        JSON.stringify({
+          filter: { schema: "app" },
+        }),
+      );
+      const dsl = await loadIntegrationDSL(jsonPath);
+      expect(dsl).toBeDefined();
+      expect(dsl.filter).toEqual({ schema: "app" });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("loads core integration by name (supabase)", async () => {
+    const dsl = await loadIntegrationDSL("supabase");
+    expect(dsl).toBeDefined();
+    expect(dsl.filter).toBeDefined();
+    expect(dsl.serialize).toBeDefined();
+  });
+
+  test("fallback to file path when core module not found", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-integration-"));
+    const filePath = path.join(dir, "custom-dsl");
+    await writeFile(filePath, JSON.stringify({ serialize: [] }));
+    try {
+      const dsl = await loadIntegrationDSL(filePath);
+      expect(dsl).toEqual({ serialize: [] });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/cli/utils/resolve-input.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { isPostgresUrl, loadCatalogFromFile } from "./resolve-input.ts";
+
+describe("isPostgresUrl", () => {
+  test("returns true for postgres:// URL", () => {
+    expect(isPostgresUrl("postgres://user:pass@localhost:5432/db")).toBe(true);
+  });
+
+  test("returns true for postgresql:// URL", () => {
+    expect(isPostgresUrl("postgresql://localhost/db")).toBe(true);
+  });
+
+  test("returns false for file path", () => {
+    expect(isPostgresUrl("/path/to/catalog.json")).toBe(false);
+    expect(isPostgresUrl("catalog.json")).toBe(false);
+  });
+
+  test("returns false for other strings", () => {
+    expect(isPostgresUrl("")).toBe(false);
+    expect(isPostgresUrl("postgres")).toBe(false);
+  });
+});
+
+describe("loadCatalogFromFile", () => {
+  test("loads and deserializes catalog from JSON file", async () => {
+    const fixturePath = path.join(
+      import.meta.dir,
+      "../../core/fixtures/empty-catalogs/postgres-15-16-baseline.json",
+    );
+    const catalog = await loadCatalogFromFile(fixturePath);
+    expect(catalog).toBeDefined();
+    expect(catalog.version).toBeGreaterThan(0);
+    expect(typeof catalog.currentUser).toBe("string");
+    expect(catalog.schemas).toBeDefined();
+    expect(catalog.depends).toEqual(expect.any(Array));
+  });
+});

package/src/cli/utils/resolve-input.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared utilities for resolving CLI --source/--target inputs that
+ * can be either a PostgreSQL connection URL or a catalog snapshot file path.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { Catalog } from "../../core/catalog.model.ts";
+import { deserializeCatalog } from "../../core/catalog.snapshot.ts";
+
+export function isPostgresUrl(input: string): boolean {
+  return input.startsWith("postgres://") || input.startsWith("postgresql://");
+}
+
+export async function loadCatalogFromFile(path: string): Promise<Catalog> {
+  const json = await readFile(path, "utf-8");
+  return deserializeCatalog(JSON.parse(json));
+}

package/src/core/catalog-export/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Catalog export – programmatic API for extracting a database catalog
+ * and serializing it to a JSON snapshot.
+ *
+ * Use this subpath when you only need catalog export (e.g. Supabase CLI
+ * edge-runtime templates) without pulling in the full pg-delta API.
+ */
+
+export {
+  Catalog,
+  createEmptyCatalog,
+  extractCatalog,
+} from "../catalog.model.ts";
+export type { CatalogSnapshot } from "../catalog.snapshot.ts";
+export {
+  deserializeCatalog,
+  serializeCatalog,
+  stringifyCatalogSnapshot,
+} from "../catalog.snapshot.ts";
+export { createManagedPool } from "../postgres-config.ts";

package/src/core/catalog.diff.ts

@@ -37,10 +37,55 @@ import { diffRanges } from "./objects/type/range/range.diff.ts";
 import { stringifyWithBigInt } from "./objects/utils.ts";
 import { diffViews } from "./objects/view/view.diff.ts";
 
+type PrivilegeChange = Extract<Change, { scope: "privilege" }>;
+
+/**
+ * Get the stableId of the target object for a privilege change.
+ * Used to filter out redundant REVOKE statements for dropped objects.
+ */
+function getPrivilegeTargetStableId(change: PrivilegeChange): string {
+  switch (change.objectType) {
+    case "composite_type":
+      return change.compositeType.stableId;
+    case "domain":
+      return change.domain.stableId;
+    case "enum":
+      return change.enum.stableId;
+    case "language":
+      return change.language.stableId;
+    case "materialized_view":
+      return change.materializedView.stableId;
+    case "aggregate":
+      return change.aggregate.stableId;
+    case "procedure":
+      return change.procedure.stableId;
+    case "range":
+      return change.range.stableId;
+    case "schema":
+      return change.schema.stableId;
+    case "sequence":
+      return change.sequence.stableId;
+    case "table":
+      return change.table.stableId;
+    case "view":
+      return change.view.stableId;
+    case "foreign_data_wrapper":
+      return change.foreignDataWrapper.stableId;
+    case "server":
+      return change.server.stableId;
+    case "foreign_table":
+      return change.foreignTable.stableId;
+    default: {
+      const _exhaustive: never = change;
+      return _exhaustive;
+    }
+  }
+}
+
 export function diffCatalogs(
   main: Catalog,
   branch: Catalog,
-  options?: { role?: string },
+  options?: { role?: string; skipDefaultPrivilegeSubtraction?: boolean },
 ) {
   const changes: Change[] = [];
 
@@ -56,24 +101,33 @@ export function diffCatalogs(
   // This represents what defaults will be in effect after all ALTER DEFAULT PRIVILEGES
   // Since ALTER DEFAULT PRIVILEGES runs before CREATE (via constraint spec),
   // all created objects will use these final defaults.
-  const defaultPrivilegeState = new DefaultPrivilegeState(main.roles);
-  for (const change of roleChanges) {
-    if (change instanceof GrantRoleDefaultPrivileges) {
-      defaultPrivilegeState.applyGrant(
-        change.role.name,
-        change.objtype,
-        change.inSchema,
-        change.grantee,
-        change.privileges,
-      );
-    } else if (change instanceof RevokeRoleDefaultPrivileges) {
-      defaultPrivilegeState.applyRevoke(
-        change.role.name,
-        change.objtype,
-        change.inSchema,
-        change.grantee,
-        change.privileges,
-      );
+  //
+  // When skipDefaultPrivilegeSubtraction is true, we use an empty state so that
+  // getEffectiveDefaults always returns [] -- no privileges are subtracted and
+  // every GRANT is emitted explicitly.  This is needed for declarative export
+  // where the output must be self-contained regardless of statement execution order.
+  const defaultPrivilegeState = options?.skipDefaultPrivilegeSubtraction
+    ? new DefaultPrivilegeState({})
+    : new DefaultPrivilegeState(main.roles);
+  if (!options?.skipDefaultPrivilegeSubtraction) {
+    for (const change of roleChanges) {
+      if (change instanceof GrantRoleDefaultPrivileges) {
+        defaultPrivilegeState.applyGrant(
+          change.role.name,
+          change.objtype,
+          change.inSchema,
+          change.grantee,
+          change.privileges,
+        );
+      } else if (change instanceof RevokeRoleDefaultPrivileges) {
+        defaultPrivilegeState.applyRevoke(
+          change.role.name,
+          change.objtype,
+          change.inSchema,
+          change.grantee,
+          change.privileges,
+        );
+      }
     }
   }
 
@@ -88,6 +142,7 @@ export function diffCatalogs(
     currentUser: effectiveUser,
     defaultPrivilegeState,
     mainRoles: main.roles,
+    skipDefaultPrivilegeSubtraction: options?.skipDefaultPrivilegeSubtraction,
   };
 
   // Step 4: Diff all other objects with default privileges context
@@ -95,11 +150,7 @@ export function diffCatalogs(
     ...diffAggregates(diffContext, main.aggregates, branch.aggregates),
   );
   changes.push(
-    ...diffCollations(
-      { currentUser: effectiveUser },
-      main.collations,
-      branch.collations,
-    ),
+    ...diffCollations(diffContext, main.collations, branch.collations),
   );
   changes.push(
     ...diffCompositeTypes(
@@ -122,18 +173,10 @@ export function diffCatalogs(
     ),
   );
   changes.push(
-    ...diffSubscriptions(
-      { currentUser: effectiveUser },
-      main.subscriptions,
-      branch.subscriptions,
-    ),
+    ...diffSubscriptions(diffContext, main.subscriptions, branch.subscriptions),
   );
   changes.push(
-    ...diffPublications(
-      { currentUser: effectiveUser },
-      main.publications,
-      branch.publications,
-    ),
+    ...diffPublications(diffContext, main.publications, branch.publications),
   );
   changes.push(
     ...diffProcedures(diffContext, main.procedures, branch.procedures),
@@ -153,11 +196,7 @@ export function diffCatalogs(
     ...diffTriggers(main.triggers, branch.triggers, branch.indexableObjects),
   );
   changes.push(
-    ...diffEventTriggers(
-      { currentUser: effectiveUser },
-      main.eventTriggers,
-      branch.eventTriggers,
-    ),
+    ...diffEventTriggers(diffContext, main.eventTriggers, branch.eventTriggers),
   );
   changes.push(...diffRules(main.rules, branch.rules));
   changes.push(...diffRanges(diffContext, main.ranges, branch.ranges));
@@ -188,45 +227,7 @@ export function diffCatalogs(
   }
   let filteredChanges = changes.filter((change) => {
     if (change.operation === "alter" && change.scope === "privilege") {
-      switch (change.objectType) {
-        case "composite_type":
-          return !droppedObjectStableIds.has(change.compositeType.stableId);
-        case "domain":
-          return !droppedObjectStableIds.has(change.domain.stableId);
-        case "enum":
-          return !droppedObjectStableIds.has(change.enum.stableId);
-        case "language":
-          return !droppedObjectStableIds.has(change.language.stableId);
-        case "materialized_view":
-          return !droppedObjectStableIds.has(change.materializedView.stableId);
-        case "aggregate":
-          return !droppedObjectStableIds.has(change.aggregate.stableId);
-        case "procedure":
-          return !droppedObjectStableIds.has(change.procedure.stableId);
-        case "range":
-          return !droppedObjectStableIds.has(change.range.stableId);
-        case "schema":
-          return !droppedObjectStableIds.has(change.schema.stableId);
-        case "sequence":
-          return !droppedObjectStableIds.has(change.sequence.stableId);
-        case "table":
-          return !droppedObjectStableIds.has(change.table.stableId);
-        case "view":
-          return !droppedObjectStableIds.has(change.view.stableId);
-        case "foreign_data_wrapper":
-          return !droppedObjectStableIds.has(
-            change.foreignDataWrapper.stableId,
-          );
-        case "server":
-          return !droppedObjectStableIds.has(change.server.stableId);
-        case "foreign_table":
-          return !droppedObjectStableIds.has(change.foreignTable.stableId);
-        default: {
-          // exhaustiveness check
-          const _exhaustive: never = change;
-          return _exhaustive;
-        }
-      }
+      return !droppedObjectStableIds.has(getPrivilegeTargetStableId(change));
     }
     return true;
   });