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

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/integrations.ts

@@ -0,0 +1,42 @@
+/**
+ * Utilities for loading integrations from files.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { IntegrationDSL } from "../../core/integrations/integration-dsl.ts";
+
+/**
+ * Load an integration DSL from a file or core integration.
+ * If the path ends with .json, treats it as a JSON file path directly.
+ * Otherwise, tries to load from core integrations (TypeScript) first,
+ * then falls back to treating as a JSON file path.
+ *
+ * @param nameOrPath - Integration name (e.g., "supabase") or file path (e.g., "./my-integration.json")
+ * @returns The loaded IntegrationDSL
+ */
+export async function loadIntegrationDSL(
+  nameOrPath: string,
+): Promise<IntegrationDSL> {
+  // If path ends with .json, treat it as a JSON file path directly
+  if (nameOrPath.endsWith(".json")) {
+    const content = await readFile(nameOrPath, "utf-8");
+    return JSON.parse(content) as IntegrationDSL;
+  }
+
+  // Try loading from core integrations (TypeScript) first
+  try {
+    const module = await import(`../../core/integrations/${nameOrPath}.ts`);
+    // Core integrations export using the integration name directly (e.g., "supabase")
+    const integrationName = nameOrPath;
+    if (integrationName in module) {
+      return module[integrationName] as IntegrationDSL;
+    }
+    // If no matching export, fall through to JSON file loading
+  } catch {
+    // Module not found or not a core integration, fall through to JSON file loading
+  }
+
+  // Fallback to treating as JSON file path
+  const content = await readFile(nameOrPath, "utf-8");
+  return JSON.parse(content) as IntegrationDSL;
+}

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/cli/utils.ts

@@ -0,0 +1,231 @@
+/**
+ * Shared utility functions for CLI commands.
+ */
+
+import { createInterface } from "node:readline";
+import type { CommandContext } from "@stricli/core";
+import chalk from "chalk";
+import type { Change } from "../core/change.types.ts";
+import type { DiffContext } from "../core/context.ts";
+import { groupChangesHierarchically } from "../core/plan/hierarchy.ts";
+import { type Plan, serializePlan } from "../core/plan/index.ts";
+import { classifyChangesRisk } from "../core/plan/risk.ts";
+import type { SqlFormatOptions } from "../core/plan/sql-format.ts";
+import { formatSqlScript } from "../core/plan/statements.ts";
+import { formatTree } from "./formatters/index.ts";
+
+// Re-export ApplyPlanResult type for convenience
+type ApplyPlanResult =
+  | { status: "invalid_plan"; message: string }
+  | { status: "fingerprint_mismatch"; current: string; expected: string }
+  | { status: "already_applied" }
+  | { status: "applied"; statements: number; warnings?: string[] }
+  | { status: "failed"; error: unknown; script: string };
+
+type PlanResult = {
+  plan: Plan;
+  sortedChanges: Change[];
+  ctx: DiffContext;
+};
+
+interface FormatPlanOptions {
+  disableColors?: boolean;
+  showUnsafeFlagSuggestion?: boolean;
+  sqlFormatOptions?: SqlFormatOptions;
+}
+
+/**
+ * Formats a plan result for display in various formats.
+ */
+export function formatPlanForDisplay(
+  planResult: PlanResult,
+  format: "tree" | "json" | "sql",
+  options: FormatPlanOptions = {},
+): { content: string; label: string } {
+  const { plan, sortedChanges, ctx } = planResult;
+  const risk = plan.risk ?? classifyChangesRisk(sortedChanges);
+  const planWithRisk = plan.risk ? plan : { ...plan, risk };
+
+  switch (format) {
+    case "sql": {
+      const content = [
+        `-- Risk: ${risk.level === "data_loss" ? `data-loss (${risk.statements.length})` : "safe"}`,
+        formatSqlScript(plan.statements, options.sqlFormatOptions),
+      ].join("\n");
+      return { content, label: "Migration script" };
+    }
+    case "json": {
+      const content = serializePlan(planWithRisk);
+      return { content, label: "Plan" };
+    }
+    default: {
+      const hierarchy = groupChangesHierarchically(ctx, sortedChanges);
+      const previousLevel = chalk.level;
+      if (options.disableColors) {
+        chalk.level = 0;
+      }
+      try {
+        let treeContent = formatTree(hierarchy);
+        if (risk.level === "data_loss") {
+          const warningLines = [
+            "",
+            chalk.yellow("⚠ Data-loss operations detected:"),
+            ...risk.statements.map((statement: string) =>
+              chalk.yellow(`- ${statement}`),
+            ),
+          ];
+          if (options.showUnsafeFlagSuggestion !== false) {
+            warningLines.push(
+              chalk.yellow(
+                "Use `--unsafe` to allow applying these operations.",
+              ),
+            );
+          }
+          const treeLines = treeContent.split("\n");
+          // Insert warning after the legend (at the end of the output)
+          // Find the legend line which contains "create", "alter", and "drop"
+          let insertIndex = treeLines.length;
+          const ansiPattern = new RegExp(
+            `${String.fromCharCode(27)}\\[[0-9;]*m`,
+            "g",
+          );
+          // Search from the end backwards for the legend
+          for (let i = treeLines.length - 1; i >= 0; i--) {
+            const line = treeLines[i];
+            const stripped = line.replace(ansiPattern, "").trim();
+            // Legend format: "+ create   ~ alter   - drop" (or variations)
+            if (
+              stripped.includes("create") &&
+              stripped.includes("alter") &&
+              stripped.includes("drop")
+            ) {
+              insertIndex = i + 1;
+              break;
+            }
+          }
+          // Fallback: if legend not found, append at the end
+          if (insertIndex === treeLines.length) {
+            insertIndex = treeLines.length;
+          }
+          treeLines.splice(insertIndex, 0, ...warningLines);
+          treeContent = treeLines.join("\n");
+        }
+        // add newline for nicer stdout when in tree mode
+        if (!treeContent.endsWith("\n")) {
+          treeContent = `${treeContent}\n`;
+        }
+        return { content: treeContent, label: "Human-readable plan" };
+      } finally {
+        if (options.disableColors) {
+          chalk.level = previousLevel;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Validates plan risk and handles unsafe operations.
+ * Returns validation result with optional exit code.
+ */
+export function validatePlanRisk(
+  plan: Plan,
+  unsafe: boolean,
+  context: CommandContext,
+  options?: { suppressWarning?: boolean },
+): { valid: boolean; exitCode?: number } {
+  if (!unsafe) {
+    if (!plan.risk) {
+      context.process.stderr.write(
+        "Plan is missing risk metadata. Regenerate the plan with the current pgdelta or re-run with --unsafe to apply anyway.\n",
+      );
+      return { valid: false, exitCode: 1 };
+    }
+    if (plan.risk.level === "data_loss") {
+      if (!options?.suppressWarning) {
+        const warningLines = [
+          chalk.yellow("⚠ Data-loss operations detected:"),
+          ...plan.risk.statements.map((statement: string) =>
+            chalk.yellow(`- ${statement}`),
+          ),
+          chalk.yellow("Use `--unsafe` to allow applying these operations."),
+        ];
+        context.process.stderr.write(`${warningLines.join("\n")}\n`);
+      }
+      return { valid: false, exitCode: 1 };
+    }
+  }
+  return { valid: true };
+}
+
+/**
+ * Handles applyPlan results and writes appropriate output.
+ * Returns the exit code that should be set.
+ */
+export function handleApplyResult(
+  result: ApplyPlanResult,
+  context: CommandContext,
+): { exitCode: number } {
+  switch (result.status) {
+    case "invalid_plan":
+      context.process.stderr.write(`${result.message}\n`);
+      return { exitCode: 1 };
+    case "fingerprint_mismatch":
+      context.process.stderr.write(
+        "Target database does not match plan source fingerprint. Aborting.\n",
+      );
+      return { exitCode: 1 };
+    case "already_applied":
+      context.process.stdout.write(
+        "Plan already applied (target fingerprint matches desired state).\n",
+      );
+      return { exitCode: 0 };
+    case "failed": {
+      context.process.stderr.write(
+        `Failed to apply changes: ${result.error instanceof Error ? result.error.message : String(result.error)}\n`,
+      );
+      context.process.stderr.write(`Migration script:\n${result.script}\n`);
+      return { exitCode: 1 };
+    }
+    case "applied": {
+      context.process.stdout.write(
+        `Applying ${result.statements} changes to database...\n`,
+      );
+      context.process.stdout.write("Successfully applied all changes.\n");
+      if (result.warnings?.length) {
+        for (const warning of result.warnings) {
+          context.process.stderr.write(`Warning: ${warning}\n`);
+        }
+      }
+      return { exitCode: 0 };
+    }
+  }
+}
+
+/**
+ * Prompts user for confirmation using readline.
+ * Returns true for 'y'/'yes', false otherwise.
+ */
+export function promptConfirmation(
+  question: string,
+  context: CommandContext,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    // Access stdin/stdout from the process object
+    // Type assertion needed because CommandContext.process may not expose stdin in its type
+    const process = context.process as unknown as {
+      stdin: NodeJS.ReadableStream;
+      stdout: NodeJS.WritableStream;
+    };
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(question, (answer) => {
+      rl.close();
+      const normalized = answer.trim().toLowerCase();
+      resolve(normalized === "y" || normalized === "yes");
+    });
+  });
+}

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";