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

package/dist/cli/commands/declarative-export.js

@@ -0,0 +1,245 @@
+/**
+ * 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 } from "@stricli/core";
+import chalk from "chalk";
+import { exportDeclarativeSchema } from "../../core/export/index.js";
+import { createPlan } from "../../core/plan/index.js";
+import { assertSafePath, buildFileTree, computeFileDiff, formatExportSummary, } from "../utils/export-display.js";
+import { loadIntegrationDSL } from "../utils/integrations.js";
+import { isPostgresUrl, loadCatalogFromFile } from "../utils/resolve-input.js";
+function parseJsonFlag(label, value) {
+    try {
+        return JSON.parse(value);
+    }
+    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) => parseJsonFlag("filter", v),
+                optional: true,
+            },
+            serialize: {
+                kind: "parsed",
+                brief: 'Serialize DSL as inline JSON array (e.g., \'[{"when":{"type":"schema"},"options":{"skipAuthorization":true}}]\')',
+                parse: (v) => parseJsonFlag("serialize", v),
+                optional: true,
+            },
+            "grouping-mode": {
+                kind: "enum",
+                brief: "How grouped entities are organized on disk",
+                values: ["single-file", "subdirectory"],
+                optional: true,
+            },
+            "group-patterns": {
+                kind: "parsed",
+                brief: 'JSON array of {pattern, name} objects (e.g., \'[{"pattern":"^auth","name":"auth"}]\')',
+                parse: (v) => {
+                    const parsed = parseJsonFlag("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) => parseJsonFlag("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(flags) {
+        const { compileSerializeDSL } = await import("../../core/integrations/serialize/dsl.js");
+        let filterOption = flags.filter;
+        let serializeOption = flags.serialize;
+        let integrationEmptyCatalog;
+        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.js")).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;
+        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) => `\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/dist/cli/commands/plan.js

@@ -4,19 +4,22 @@
 import { writeFile } from "node:fs/promises";
 import { buildCommand } from "@stricli/core";
 import { createPlan } from "../../core/plan/index.js";
+import { setCommandExitCode } from "../exit-code.js";
 import { loadIntegrationDSL } from "../utils/integrations.js";
+import { isPostgresUrl, loadCatalogFromFile } from "../utils/resolve-input.js";
 import { formatPlanForDisplay } from "../utils.js";
 export const planCommand = buildCommand({
     parameters: {
         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: {
@@ -103,16 +106,26 @@ json/sql outputs are available for artifacts or piping.
     `.trim(),
     },
     async func(flags) {
-        // Load integration if provided and extract filter/serialize DSL
         let filterOption = flags.filter;
         let serializeOption = flags.serialize;
+        let integrationEmptyCatalog;
         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.js")).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,
@@ -153,6 +166,6 @@ json/sql outputs are available for artifacts or piping.
             }
         }
         // Exit code 2 indicates changes were detected
-        process.exitCode = 2;
+        setCommandExitCode(2);
     },
 });

package/dist/cli/exit-code.d.ts

@@ -0,0 +1,2 @@
+export declare function setCommandExitCode(code: number): void;
+export declare function getCommandExitCode(): number | undefined;

package/dist/cli/exit-code.js

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

package/dist/cli/formatters/tree/tree.js

@@ -12,7 +12,7 @@ export function formatTree(plan) {
     // Summary
     const total = countTotalChanges(plan);
     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);
@@ -38,8 +38,9 @@ function countTotalChanges(plan) {
 }
 /**
  * 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) {
+function buildPlanSummaryTable(plan) {
     // Count by object type
     const byType = {};
     countFromHierarchy(plan, byType);

package/dist/cli/utils/apply-display.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Display utilities for the declarative-apply command.
+ *
+ * Pure formatting and location-resolution functions — no CLI framework dependency.
+ * Used to:
+ * - Map pg-topo diagnostics into display items (optionally grouped by message/code).
+ * - Resolve statement IDs to file paths and line/column for error output.
+ * - Format StatementErrors in a pgAdmin-style multi-line block.
+ */
+import type { Diagnostic } from "@supabase/pg-topo";
+import type { StatementError } from "../../core/declarative-apply/round-apply.ts";
+/**
+ * Convert a 1-based character offset in a string to 1-based line and column.
+ * Used when mapping PostgreSQL error positions (in SQL) to file locations.
+ */
+export declare function positionToLineColumn(sql: string, position: number): {
+    line: number;
+    column: number;
+};
+/** Input to buildDiagnosticDisplayItems: a pg-topo diagnostic plus optional location and object key. */
+export type DiagnosticDisplayEntry = {
+    diagnostic: Diagnostic;
+    location?: string;
+    requiredObjectKey?: string;
+};
+/** One display row for a diagnostic (or a group of same-code diagnostics with multiple locations). */
+type DiagnosticDisplayItem = {
+    code: string;
+    message: string;
+    suggestedFix?: string;
+    requiredObjectKey?: string;
+    locations: string[];
+};
+/** Extract requiredObjectKey from a pg-topo diagnostic if present and non-empty. */
+export declare const requiredObjectKeyFromDiagnostic: (diagnostic: Diagnostic) => string | undefined;
+/**
+ * Turn diagnostic entries into display items. If grouped is true, entries with
+ * the same code/message/suggestedFix are merged into one item with multiple locations.
+ */
+export declare const buildDiagnosticDisplayItems: (entries: DiagnosticDisplayEntry[], grouped: boolean) => DiagnosticDisplayItem[];
+/**
+ * Resolve the full path to a .sql file from the schema path (directory or single file)
+ * and a relative file path (e.g. from a statement id). If schemaPath is a file, its
+ * directory is used as the base.
+ */
+export declare function resolveSqlFilePath(schemaPath: string, relativeFilePath: string): Promise<string>;
+/**
+ * Format a StatementError in pgAdmin-style: ERROR, Detail, SQL state, optional
+ * Context, Hint, and Location (resolving the .sql file and line/column when possible).
+ */
+export declare function formatStatementError(err: StatementError, schemaPath: string): Promise<string>;
+export {};

package/dist/cli/utils/apply-display.js

@@ -0,0 +1,183 @@
+/**
+ * Display utilities for the declarative-apply command.
+ *
+ * Pure formatting and location-resolution functions — no CLI framework dependency.
+ * Used to:
+ * - Map pg-topo diagnostics into display items (optionally grouped by message/code).
+ * - Resolve statement IDs to file paths and line/column for error output.
+ * - Format StatementErrors in a pgAdmin-style multi-line block.
+ */
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Convert a 1-based character offset in a string to 1-based line and column.
+ * Used when mapping PostgreSQL error positions (in SQL) to file locations.
+ */
+export function positionToLineColumn(sql, position) {
+    const lines = sql.split("\n");
+    let offset = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const lineLen = lines[i].length + (i < lines.length - 1 ? 1 : 0);
+        if (position <= offset + lineLen) {
+            return { line: i + 1, column: position - offset };
+        }
+        offset += lineLen;
+    }
+    const last = lines.length;
+    const lastLineLen = lines[last - 1]?.length ?? 0;
+    return { line: last, column: lastLineLen + 1 };
+}
+/**
+ * Parse a statement id in the form "filePath:statementIndex" into components.
+ * The last colon separates path from index (paths may contain colons).
+ * Returns null if the format is invalid.
+ */
+function parseStatementId(id) {
+    const lastColon = id.lastIndexOf(":");
+    if (lastColon === -1)
+        return null;
+    const filePath = id.slice(0, lastColon);
+    const n = Number.parseInt(id.slice(lastColon + 1), 10);
+    if (!Number.isInteger(n) || n < 0)
+        return null;
+    return { filePath, statementIndex: n };
+}
+/** Extract requiredObjectKey from a pg-topo diagnostic if present and non-empty. */
+export const requiredObjectKeyFromDiagnostic = (diagnostic) => {
+    const value = diagnostic.details?.requiredObjectKey;
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+};
+/** Build a stable key for grouping diagnostics with the same code, message, and suggested fix. */
+const diagnosticDisplayGroupKey = (entry) => [
+    entry.diagnostic.code,
+    entry.diagnostic.message,
+    entry.diagnostic.suggestedFix ?? "",
+    entry.requiredObjectKey ?? "",
+].join("\u0000");
+/**
+ * Turn diagnostic entries into display items. If grouped is true, entries with
+ * the same code/message/suggestedFix are merged into one item with multiple locations.
+ */
+export const buildDiagnosticDisplayItems = (entries, grouped) => {
+    if (!grouped) {
+        return entries.map((entry) => ({
+            code: entry.diagnostic.code,
+            message: entry.diagnostic.message,
+            suggestedFix: entry.diagnostic.suggestedFix,
+            requiredObjectKey: entry.requiredObjectKey,
+            locations: entry.location ? [entry.location] : [],
+        }));
+    }
+    const groupedItems = new Map();
+    for (const entry of entries) {
+        const key = diagnosticDisplayGroupKey(entry);
+        const existing = groupedItems.get(key);
+        if (!existing) {
+            groupedItems.set(key, {
+                code: entry.diagnostic.code,
+                message: entry.diagnostic.message,
+                suggestedFix: entry.diagnostic.suggestedFix,
+                requiredObjectKey: entry.requiredObjectKey,
+                locations: entry.location ? [entry.location] : [],
+            });
+            continue;
+        }
+        if (entry.location && !existing.locations.includes(entry.location)) {
+            existing.locations.push(entry.location);
+        }
+    }
+    return [...groupedItems.values()];
+};
+/**
+ * Resolve the full path to a .sql file from the schema path (directory or single file)
+ * and a relative file path (e.g. from a statement id). If schemaPath is a file, its
+ * directory is used as the base.
+ */
+export async function resolveSqlFilePath(schemaPath, relativeFilePath) {
+    try {
+        const statResult = await stat(schemaPath);
+        const baseDir = statResult.isFile() ? path.dirname(schemaPath) : schemaPath;
+        return path.join(baseDir, relativeFilePath);
+    }
+    catch {
+        return path.join(schemaPath, relativeFilePath);
+    }
+}
+/**
+ * Find the 0-based start offset of statementSql in fileContent.
+ * Tries exact match first, then trimmed match. Returns -1 if not found.
+ */
+function findStatementStartInFile(fileContent, statementSql) {
+    const exact = fileContent.indexOf(statementSql);
+    if (exact !== -1)
+        return exact;
+    const trimmedStmt = statementSql.trim();
+    if (!trimmedStmt)
+        return -1;
+    const trimmed = fileContent.indexOf(trimmedStmt);
+    if (trimmed !== -1)
+        return trimmed;
+    return -1;
+}
+/**
+ * Format a StatementError in pgAdmin-style: ERROR, Detail, SQL state, optional
+ * Context, Hint, and Location (resolving the .sql file and line/column when possible).
+ */
+export async function formatStatementError(err, schemaPath) {
+    const lines = [];
+    lines.push(`ERROR:  ${err.message}`);
+    if (err.detail) {
+        lines.push(`Detail: ${err.detail}`);
+    }
+    lines.push(`SQL state: ${err.code}`);
+    if (err.position !== undefined && err.statement.sql.length > 0) {
+        lines.push(`Character: ${err.position}`);
+        const pos = Math.max(0, Math.min(err.position - 1, err.statement.sql.length));
+        const contextStart = Math.max(0, pos - 40);
+        const contextEnd = Math.min(err.statement.sql.length, pos + 40);
+        const snippet = err.statement.sql.slice(contextStart, contextEnd);
+        const oneLine = snippet.replace(/\s+/g, " ").trim();
+        lines.push(`Context: ${oneLine || "(empty)"}`);
+    }
+    if (err.hint) {
+        lines.push(`Hint: ${err.hint}`);
+    }
+    const parsed = parseStatementId(err.statement.id);
+    if (parsed) {
+        let locationLine;
+        try {
+            const fullPath = await resolveSqlFilePath(schemaPath, parsed.filePath);
+            const fileContent = await readFile(fullPath, "utf-8");
+            const statementStart = findStatementStartInFile(fileContent, err.statement.sql);
+            if (statementStart !== -1) {
+                if (err.position !== undefined && err.statement.sql.length > 0) {
+                    const fileErrorOffset = statementStart + (err.position - 1);
+                    const fileErrorPosition = Math.min(fileErrorOffset + 1, fileContent.length);
+                    const { line, column } = positionToLineColumn(fileContent, Math.max(1, fileErrorPosition));
+                    locationLine = `Location: ${parsed.filePath}:${line}:${column}`;
+                }
+                else {
+                    const { line } = positionToLineColumn(fileContent, statementStart + 1);
+                    locationLine = `Location: ${parsed.filePath}:${line}`;
+                }
+            }
+            else {
+                locationLine = `Location: ${parsed.filePath} (statement ${parsed.statementIndex})`;
+            }
+        }
+        catch {
+            if (err.position !== undefined && err.statement.sql.length > 0) {
+                const { line, column } = positionToLineColumn(err.statement.sql, err.position);
+                locationLine = `Location: ${parsed.filePath} (statement ${parsed.statementIndex}, line ${line}, column ${column})`;
+            }
+            else {
+                locationLine = `Location: ${parsed.filePath} (statement ${parsed.statementIndex})`;
+            }
+        }
+        lines.push(locationLine);
+    }
+    else {
+        lines.push(`Location: ${err.statement.id}`);
+    }
+    return lines.map((l) => `  ${l}`).join("\n");
+}

package/dist/cli/utils/export-display.d.ts

@@ -0,0 +1,43 @@
+/**
+ * CLI helpers for declarative export: file tree, diff, and summary formatting.
+ */
+import type { FileEntry } from "../../core/export/types.ts";
+/**
+ * Ensure a relative file path does not escape the output directory.
+ * Uses Node.js path.resolve + startsWith as the canonical traversal check.
+ */
+export declare function assertSafePath(filePath: string, outputDir: string): void;
+interface FileDiffResult {
+    created: string[];
+    updated: string[];
+    deleted: string[];
+    unchanged: string[];
+}
+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;
+}
+/**
+ * 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 declare function buildFileTree(files: string[], outputDir: string, options?: BuildFileTreeOptions): string;
+/**
+ * Compare existing output directory with new file set.
+ * Returns created, updated, deleted, and unchanged paths.
+ */
+export declare function computeFileDiff(outputDir: string, newFiles: FileEntry[]): Promise<FileDiffResult>;
+/**
+ * Format the created/deleted/updated summary with colors.
+ * In dry-run mode, uses "would create/delete/update" phrasing.
+ */
+export declare function formatExportSummary(diff: FileDiffResult, dryRun: boolean): string;
+export {};