supaschema 0.1.0-rc.1

package/dist/cli-diff.js

@@ -0,0 +1,348 @@
+import { watch } from "node:fs";
+import { mkdir, open, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { defaultMigrationName, resolveMigrationsDir, resolveSourceDefaults, } from "./cli-defaults.js";
+import { colorizeSummaryLine } from "./cli-tools.js";
+import { diagnostic, hasErrors } from "./diagnostics.js";
+import { latestLineage } from "./lineage.js";
+import { planSchemaDiff } from "./planner.js";
+import { renderMigrationSplit } from "./render.js";
+import { extractSourceModel, filterModelBySchemas } from "./source.js";
+import { generateDatabaseTypes } from "./typegen.js";
+import { generateZodSchemas } from "./typegen-zod.js";
+export function registerDiffCommands(program, context) {
+    program
+        .command("plan")
+        .option("--from <source>", "source model before the change (default: database, then git:HEAD)")
+        .option("--to <target>", "source model after the change (default: the config schema tree)")
+        .option("--schema <names>", "comma-separated schema filter")
+        .option("--timing", "print extract/plan phase timings to stderr")
+        .description("Print the planned object-level schema diff as JSON (use `diff` to render SQL).")
+        .action(async (options) => {
+        const config = await context.loadCliConfig();
+        const plan = await buildPlan(await withSourceDefaults(options, config, context), config);
+        context.printDiagnostics(plan.diagnostics);
+        process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+        if (hasErrors(plan.diagnostics)) {
+            process.exitCode = 2;
+        }
+    });
+    program
+        .command("diff")
+        .option("--from <source>", "source model before the change (default: database, then git:HEAD)")
+        .option("--to <target>", "source model after the change (default: the config schema tree)")
+        .option("--out <file>", "output file path or stdout (default: <migrations-dir>/<UTC timestamp>_<name>.sql)")
+        .option("--name <snake_case>", "migration name (default: derived from the planned operations)")
+        .option("--migrations-dir <dir>", "migrations directory (default: config.migrationsDir)")
+        .option("--schema <names>", "comma-separated schema filter")
+        .option("--dry-run", "print the migration and target path without writing")
+        .option("--json", "print a JSON payload (fingerprint, operations, sql) instead of raw SQL")
+        .option("--fail-on-diff", "exit with code 3 when the plan contains operations (CI drift gate)")
+        .option("--no-check-chain", "skip the lineage chain gate against pending supaschema migrations in the output directory")
+        .option("--summary", "print a drift report (operation and diagnostic counts grouped by kind and schema) before any error exit")
+        .option("--write-hints <file>", "write the gated destructive object keys as a hints.destructive skeleton for review (never overwrites)")
+        .option("--timing", "print extract/plan/render phase timings to stderr")
+        .option("--watch", "re-print the drift summary whenever a dir: source changes (editor loop; implies --dry-run --summary)")
+        .description("Render a replay-safe migration from the planned schema diff (zero flags: database/git:HEAD → schema tree → migrations directory).")
+        .action(async (options) => {
+        const config = await context.loadCliConfig();
+        const resolved = await withSourceDefaults(options, config, context);
+        if (resolved.watch) {
+            await watchDiff(resolved, config, context);
+            return;
+        }
+        await runDiff(resolved, config, context);
+    });
+}
+async function withSourceDefaults(options, config, context) {
+    const resolved = await resolveSourceDefaults(options, config, () => context.resolveCliDatabaseUrl());
+    if (resolved.notice !== undefined) {
+        process.stderr.write(resolved.notice);
+    }
+    return { ...options, from: resolved.from, to: resolved.to };
+}
+async function runDiff(options, config, context) {
+    const plan = await buildPlan(options, config);
+    context.printDiagnostics(plan.diagnostics);
+    if (options.summary) {
+        process.stdout.write(renderPlanSummary(plan));
+    }
+    if (options.writeHints) {
+        const keys = [
+            ...new Set(plan.operations
+                .filter((operation) => operation.blocked && operation.destructive)
+                .map((operation) => operation.key)),
+        ].sort((left, right) => left.localeCompare(right));
+        const hintsPath = resolve(process.cwd(), options.writeHints);
+        await writeFile(hintsPath, `${JSON.stringify({ hints: { destructive: keys } }, null, 2)}\n`, {
+            flag: "wx",
+        });
+        process.stderr.write(`wrote ${keys.length} gated object keys to ${hintsPath}; review each before merging into hints.destructive\n`);
+    }
+    if (hasErrors(plan.diagnostics)) {
+        process.exitCode = 2;
+        return;
+    }
+    const renderStart = performance.now();
+    const rendered = renderMigrationSplit(plan, { config, version: context.cliVersion });
+    if (options.timing) {
+        process.stderr.write(`timing: render ${Math.round(performance.now() - renderStart)}ms\n`);
+    }
+    const migrationsDir = resolveMigrationsDir(options.migrationsDir, config);
+    const defaultedOut = options.name === undefined && options.out === undefined;
+    if (defaultedOut && plan.operations.length === 0 && !options.json) {
+        process.stderr.write("no schema changes\n");
+        return;
+    }
+    const outPath = options.name !== undefined || defaultedOut
+        ? resolve(process.cwd(), migrationsDir, `${migrationTimestamp()}_${options.name ?? defaultMigrationName(plan)}.sql`)
+        : options.out === "stdout" || options.out === undefined
+            ? undefined
+            : resolve(process.cwd(), options.out);
+    if (outPath !== undefined && options.checkChain) {
+        const chainDiagnostics = await checkLineageChain(plan, dirname(outPath));
+        if (chainDiagnostics.length > 0) {
+            context.printDiagnostics(chainDiagnostics);
+            process.exitCode = 2;
+            return;
+        }
+    }
+    const concurrentPath = rendered.concurrentSql !== undefined && outPath !== undefined
+        ? `${outPath.replace(/\.sql$/u, "")}.concurrent.sql`
+        : undefined;
+    const payload = options.json
+        ? `${JSON.stringify({
+            concurrentOut: concurrentPath,
+            concurrentSql: rendered.concurrentSql,
+            fingerprint: plan.fingerprint,
+            operations: plan.operations.map((operation) => ({
+                blocked: operation.blocked,
+                destructive: operation.destructive,
+                key: operation.key,
+                kind: operation.kind,
+            })),
+            out: outPath ?? "stdout",
+            sql: rendered.sql,
+        }, null, 2)}\n`
+        : rendered.concurrentSql !== undefined && outPath === undefined
+            ? `${rendered.sql}\n${rendered.concurrentSql}`
+            : rendered.sql;
+    if (options.dryRun || outPath === undefined) {
+        if (outPath !== undefined) {
+            process.stderr.write(`dry-run: would write ${outPath}\n`);
+        }
+        process.stdout.write(payload);
+    }
+    else {
+        try {
+            await mkdir(dirname(outPath), { recursive: true });
+            await writeFile(outPath, rendered.sql, { flag: "wx" });
+            if (rendered.concurrentSql !== undefined && concurrentPath !== undefined) {
+                await writeFile(concurrentPath, rendered.concurrentSql, { flag: "wx" });
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+                context.printDiagnostics([
+                    diagnostic("SUPA_DIFF_OUTPUT_EXISTS", "error", "the output migration file already exists; supaschema never overwrites migrations", {
+                        file: outPath,
+                        hint: "Choose a new --out path or --name, or remove the stale file.",
+                    }),
+                ]);
+                process.exitCode = 2;
+                return;
+            }
+            throw error;
+        }
+        process.stdout.write(options.json
+            ? payload
+            : `${outPath}\n${concurrentPath === undefined ? "" : `${concurrentPath}\n`}`);
+        await refreshTypesFile(options.to, config, options.schema);
+    }
+    if (options.failOnDiff && plan.operations.length > 0) {
+        process.exitCode = 3;
+    }
+}
+async function refreshTypesFile(toSource, config, schemaFilter) {
+    const targets = [
+        { generate: generateDatabaseTypes, relative: config.typesFile },
+        { generate: generateZodSchemas, relative: config.zodFile },
+    ];
+    let model;
+    for (const target of targets) {
+        let handle;
+        try {
+            handle = await open(resolve(process.cwd(), target.relative), "r+");
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                continue;
+            }
+            throw error;
+        }
+        try {
+            model = model ?? filterModel(await extractSourceModel(toSource, { config }), schemaFilter);
+            if (hasErrors(model.diagnostics)) {
+                return;
+            }
+            const generated = await target.generate(model);
+            await handle.truncate(0);
+            await handle.write(generated, 0);
+            process.stderr.write(`types: ${target.relative} refreshed from ${toSource}\n`);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+/**
+ * Editor loop: re-print the drift summary whenever a dir: source changes.
+ * Watch never writes files — it forces dry-run summary mode.
+ */
+async function watchDiff(options, config, context) {
+    const watchedDirs = [options.from, options.to]
+        .filter((source) => source.startsWith("dir:"))
+        .map((source) => resolve(process.cwd(), source.slice("dir:".length)));
+    if (watchedDirs.length === 0) {
+        process.stderr.write("--watch requires at least one dir: source to watch\n");
+        process.exitCode = 1;
+        return;
+    }
+    const watchedOptions = {
+        ...options,
+        dryRun: true,
+        summary: true,
+        watch: false,
+    };
+    let running = false;
+    let queued = false;
+    const run = async () => {
+        if (running) {
+            queued = true;
+            return;
+        }
+        running = true;
+        try {
+            const startedAt = new Date().toISOString();
+            process.stdout.write(`\nwatch: diff at ${startedAt}\n`);
+            await runDiff(watchedOptions, config, context);
+            process.exitCode = 0;
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        }
+        finally {
+            running = false;
+            if (queued) {
+                queued = false;
+                await run();
+            }
+        }
+    };
+    await run();
+    let timer;
+    for (const dir of watchedDirs) {
+        watch(dir, { recursive: true }, () => {
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                void run();
+            }, 250);
+        });
+    }
+    process.stdout.write(`watch: watching ${watchedDirs.join(", ")} (ctrl-c to exit)\n`);
+    await new Promise(() => undefined);
+}
+async function buildPlan(options, config) {
+    const extractStart = performance.now();
+    const from = filterModel(await extractSourceModel(options.from, { config }), options.schema);
+    const fromMs = performance.now() - extractStart;
+    const toStart = performance.now();
+    const to = filterModel(await extractSourceModel(options.to, { config }), options.schema);
+    const toMs = performance.now() - toStart;
+    const planStart = performance.now();
+    const plan = planSchemaDiff(from, to, { config });
+    if (options.timing) {
+        process.stderr.write(`timing: extract-from ${Math.round(fromMs)}ms · extract-to ${Math.round(toMs)}ms · plan ${Math.round(performance.now() - planStart)}ms\n`);
+    }
+    return plan;
+}
+export function filterModel(model, schemaFilter) {
+    if (!schemaFilter) {
+        return model;
+    }
+    const schemas = new Set(schemaFilter
+        .split(",")
+        .map((name) => name.trim().toLowerCase())
+        .filter(Boolean));
+    return filterModelBySchemas(model, schemas);
+}
+function migrationTimestamp() {
+    const now = new Date();
+    const pad = (value) => String(value).padStart(2, "0");
+    return [
+        now.getUTCFullYear(),
+        pad(now.getUTCMonth() + 1),
+        pad(now.getUTCDate()),
+        pad(now.getUTCHours()),
+        pad(now.getUTCMinutes()),
+        pad(now.getUTCSeconds()),
+    ].join("");
+}
+async function checkLineageChain(plan, directory) {
+    const latest = await latestLineage(directory);
+    if (!latest) {
+        return [];
+    }
+    if (latest.from === plan.fromFingerprint && latest.to === plan.toFingerprint) {
+        return [
+            diagnostic("SUPA_DIFF_LINEAGE_DUPLICATE", "error", "a pending supaschema migration already covers this exact from/to transition", {
+                file: latest.file,
+                hint: "Apply or remove the pending migration, or pass --no-check-chain to bypass.",
+            }),
+        ];
+    }
+    if (latest.to !== plan.fromFingerprint) {
+        return [
+            diagnostic("SUPA_DIFF_LINEAGE_BROKEN", "error", "the plan's from-state does not continue the newest pending supaschema migration", {
+                file: latest.file,
+                hint: `Pending migration ends at model ${latest.to.slice(0, 12)}… but this plan starts from ${plan.fromFingerprint.slice(0, 12)}…; diff from the post-migration state (e.g. --from database:<applied-db>) or pass --no-check-chain.`,
+            }),
+        ];
+    }
+    return [];
+}
+export function renderPlanSummary(plan) {
+    const lines = ["plan summary:"];
+    const operationCounts = new Map();
+    for (const operation of plan.operations) {
+        const label = `${operation.kind} ${operation.ref.kind}${operation.blocked ? " (blocked)" : ""}`;
+        const tone = operation.blocked
+            ? "blocked"
+            : operation.kind === "drop"
+                ? "drop"
+                : operation.kind === "create"
+                    ? "create"
+                    : "plain";
+        const entry = operationCounts.get(label) ?? { count: 0, tone };
+        entry.count += 1;
+        operationCounts.set(label, entry);
+    }
+    lines.push(`  operations: ${plan.operations.length}`);
+    for (const [label, entry] of [...operationCounts.entries()].sort()) {
+        lines.push(colorizeSummaryLine(`    ${entry.count} ${label}`, entry.tone));
+    }
+    const diagnosticCounts = new Map();
+    for (const item of plan.diagnostics) {
+        const scope = item.ref
+            ? ` ${item.ref.kind}${item.ref.schema ? ` ${item.ref.schema}` : ""}`
+            : "";
+        const label = `${item.severity.toUpperCase()} ${item.code}${scope}`;
+        diagnosticCounts.set(label, (diagnosticCounts.get(label) ?? 0) + 1);
+    }
+    lines.push(`  diagnostics: ${plan.diagnostics.length}`);
+    for (const [label, count] of [...diagnosticCounts.entries()].sort()) {
+        lines.push(`    ${count} ${label}`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/cli-reports.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+import type { Diagnostic, SupaschemaConfig } from "./core.js";
+export interface ReportCommandContext {
+    loadCliConfig: () => Promise<SupaschemaConfig>;
+    printDiagnostics: (diagnostics: Diagnostic[]) => void;
+    resolveCliDatabaseUrl: (explicit?: string) => Promise<string | undefined>;
+}
+export declare function registerReportCommands(program: Command, context: ReportCommandContext): void;
+//# sourceMappingURL=cli-reports.d.ts.map

package/dist/cli-reports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-reports.d.ts","sourceRoot":"","sources":["../src/cli-reports.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAO9D,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/C,gBAAgB,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,KAAK,IAAI,CAAC;IACtD,qBAAqB,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC3E;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAwH5F"}

package/dist/cli-reports.js

@@ -0,0 +1,90 @@
+import { resolve } from "node:path";
+import { auditModel, renderAuditReport } from "./audit.js";
+import { renderCorpusReport, runCorpus } from "./corpus.js";
+import { hasErrors } from "./diagnostics.js";
+import { migrationsStatus, renderMigrationsStatus } from "./migrations-status.js";
+import { extractSourceModel } from "./source.js";
+import { syncMigrations } from "./sync.js";
+export function registerReportCommands(program, context) {
+    program
+        .command("audit")
+        .requiredOption("--from <source>", "source to audit against the support matrix")
+        .option("--json", "print the report as JSON")
+        .description("Report support-matrix coverage: modeled objects and statements outside the contract.")
+        .action(async (options) => {
+        const config = await context.loadCliConfig();
+        const model = await extractSourceModel(options.from, { config });
+        const report = auditModel(model);
+        process.stdout.write(options.json === true ? `${JSON.stringify(report, null, 2)}\n` : renderAuditReport(report));
+        if (!report.supported) {
+            process.exitCode = 2;
+        }
+    });
+    program
+        .command("migrations")
+        .option("--migrations-dir <dir>", "migration files directory", "supabase/migrations")
+        .option("--database-url <url>", "target whose applied history to compare (default: SUPASCHEMA_DATABASE_URL, then the local Supabase stack); run once per target to compare local and remote")
+        .option("--history-table <schema.table>", "migration history table", undefined)
+        .option("--json", "print the report as JSON")
+        .description("Reconcile migration files on disk against a target's applied history.")
+        .action(async (options) => {
+        const databaseUrl = await context.resolveCliDatabaseUrl(options.databaseUrl);
+        const { diagnostics, report } = await migrationsStatus({
+            directory: resolve(process.cwd(), options.migrationsDir),
+            ...(databaseUrl === undefined ? {} : { databaseUrl }),
+            ...(options.historyTable === undefined ? {} : { historyTable: options.historyTable }),
+        });
+        context.printDiagnostics(diagnostics);
+        process.stdout.write(options.json === true
+            ? `${JSON.stringify(report, null, 2)}\n`
+            : renderMigrationsStatus(report));
+        if (hasErrors(diagnostics)) {
+            process.exitCode = 2;
+        }
+    });
+    program
+        .command("corpus")
+        .option("--corpus-dir <dir>", "corpus directory", "corpus/supabase-style")
+        .option("--database-url <url>", "admin URL for disposable corpus databases (default: SUPASCHEMA_DATABASE_URL, then the local Supabase stack)")
+        .option("--json", "print the report as JSON")
+        .description("Run the corpus oracle: replay the dirty-real migrations corpus, diff against its tree, apply the reconciliation twice, and require reconvergence to zero.")
+        .action(async (options) => {
+        const databaseUrl = await context.resolveCliDatabaseUrl(options.databaseUrl);
+        if (databaseUrl === undefined) {
+            process.stdout.write("corpus: skipped (no database URL resolved)\n");
+            return;
+        }
+        const { diagnostics, report } = await runCorpus({
+            corpusDir: resolve(process.cwd(), options.corpusDir),
+            databaseUrl,
+        });
+        context.printDiagnostics(diagnostics);
+        process.stdout.write(options.json === true ? `${JSON.stringify(report, null, 2)}\n` : renderCorpusReport(report));
+        if (hasErrors(diagnostics)) {
+            process.exitCode = 2;
+        }
+    });
+    program
+        .command("sync")
+        .option("--migrations-dir <dir>", "migration files directory", "supabase/migrations")
+        .option("--database-url <url>", "target whose applied history gates the sync (default: SUPASCHEMA_DATABASE_URL, then the local Supabase stack)")
+        .option("--local", "apply pending migrations to the target via `supabase migration up`")
+        .option("--remote", "push pending migrations to the linked project via `supabase db push`")
+        .description("Gate and apply pending migrations: status + replay-safety checks, then the Supabase CLI runs the actual apply/deploy. Dry run without --local/--remote.")
+        .action(async (options) => {
+        const config = await context.loadCliConfig();
+        const databaseUrl = await context.resolveCliDatabaseUrl(options.databaseUrl);
+        const result = await syncMigrations({
+            config,
+            directory: resolve(process.cwd(), options.migrationsDir),
+            ...(databaseUrl === undefined ? {} : { databaseUrl }),
+            ...(options.local === true ? { local: true } : {}),
+            ...(options.remote === true ? { remote: true } : {}),
+        });
+        context.printDiagnostics(result.diagnostics);
+        process.stdout.write(result.report);
+        if (hasErrors(result.diagnostics)) {
+            process.exitCode = 2;
+        }
+    });
+}

package/dist/cli-tools.d.ts

@@ -0,0 +1,17 @@
+import type { Command } from "commander";
+import type { SupaschemaConfig } from "./config.js";
+import type { Diagnostic } from "./core.js";
+export interface ToolCommandContext {
+    loadCliConfig: () => Promise<SupaschemaConfig>;
+    printDiagnostics: (diagnostics: Diagnostic[]) => void;
+    resolveCliDatabaseUrl: (explicit?: string) => Promise<string | undefined>;
+}
+export declare function registerToolCommands(program: Command, context: ToolCommandContext): void;
+export declare function colorEnabled(): boolean;
+export type SummaryTone = "create" | "drop" | "blocked" | "plain";
+/**
+ * Tone comes from the structured operation (kind/blocked), never from
+ * re-classifying rendered text.
+ */
+export declare function colorizeSummaryLine(line: string, tone: SummaryTone): string;
+//# sourceMappingURL=cli-tools.d.ts.map

package/dist/cli-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-tools.d.ts","sourceRoot":"","sources":["../src/cli-tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAO5C,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/C,gBAAgB,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,KAAK,IAAI,CAAC;IACtD,qBAAqB,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC3E;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAoFxF;AA8CD,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAElE;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAM3E"}

package/dist/cli-tools.js

@@ -0,0 +1,136 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { defaultTreeSource } from "./cli-defaults.js";
+import { hasErrors } from "./diagnostics.js";
+import { renderDoctorReport, runDoctor } from "./doctor.js";
+import { extractSourceModel } from "./source.js";
+import { generateDatabaseTypes } from "./typegen.js";
+import { generateZodSchemas } from "./typegen-zod.js";
+export function registerToolCommands(program, context) {
+    program
+        .command("doctor")
+        .option("--database-url <url>", "database URL to probe (default: normal resolution order)")
+        .option("--json", "print the report as JSON")
+        .description("Diagnose the environment: Node version, parser, config, URL resolution, database reachability, CREATEDB capability, migrations history, and the declarative tree.")
+        .action(async (options) => {
+        const config = await context.loadCliConfig();
+        const report = await runDoctor(config, {
+            ...(options.databaseUrl === undefined ? {} : { databaseUrl: options.databaseUrl }),
+        });
+        process.stdout.write(options.json === true ? `${JSON.stringify(report, null, 2)}\n` : renderDoctorReport(report));
+        if (!report.healthy) {
+            process.exitCode = 2;
+        }
+    });
+    program
+        .command("types")
+        .option("--from <source>", "source to type (default: the config schema tree)")
+        .option("--out <file|stdout>", "TypeScript output path (default: config.typesFile)")
+        .description("Generate Supabase-compatible TypeScript types and Zod validators straight from the schema tree — no database, no introspection, no applied migrations required.")
+        .action(async (options) => {
+        const config = await context.loadCliConfig();
+        const source = options.from ?? defaultTreeSource(config);
+        const model = await extractSourceModel(source, { config });
+        context.printDiagnostics(model.diagnostics);
+        if (hasErrors(model.diagnostics)) {
+            process.exitCode = 2;
+            return;
+        }
+        const types = await generateDatabaseTypes(model);
+        const target = options.out ?? config.typesFile;
+        if (target === "stdout") {
+            process.stdout.write(types);
+            return;
+        }
+        const outPath = resolve(process.cwd(), target);
+        await mkdir(dirname(outPath), { recursive: true });
+        await writeFile(outPath, types);
+        const zodPath = resolve(process.cwd(), config.zodFile);
+        await mkdir(dirname(zodPath), { recursive: true });
+        await writeFile(zodPath, await generateZodSchemas(model));
+        process.stdout.write(`${outPath}\n${zodPath}\n`);
+    });
+    program
+        .command("fingerprint")
+        .requiredOption("--from <source>", "source to fingerprint")
+        .description("Print only the model fingerprint for a source — two sources with equal fingerprints have identical schemas.")
+        .action(async (options) => {
+        const config = await context.loadCliConfig();
+        const model = await extractSourceModel(options.from, { config });
+        context.printDiagnostics(model.diagnostics);
+        if (hasErrors(model.diagnostics)) {
+            process.exitCode = 2;
+            return;
+        }
+        process.stdout.write(`${model.fingerprint}\n`);
+    });
+    program
+        .command("completion")
+        .argument("<shell>", "bash, zsh, or fish")
+        .description("Print a shell completion script (eval or save it into your shell's completion path).")
+        .action((shell) => {
+        const script = completionScript(shell, program);
+        if (script === undefined) {
+            process.stderr.write(`unsupported shell "${shell}"; use bash, zsh, or fish\n`);
+            process.exitCode = 1;
+            return;
+        }
+        process.stdout.write(script);
+    });
+}
+function completionScript(shell, program) {
+    const commands = program.commands.map((command) => command.name()).sort();
+    const list = commands.join(" ");
+    switch (shell) {
+        case "bash":
+            return [
+                "_supaschema_completions() {",
+                '  if [ "$COMP_CWORD" -eq 1 ]; then',
+                `    COMPREPLY=($(compgen -W "${list}" -- "\${COMP_WORDS[1]}"))`,
+                "  fi",
+                "}",
+                "complete -F _supaschema_completions supaschema",
+                "",
+            ].join("\n");
+        case "zsh":
+            return [
+                "#compdef supaschema",
+                "_supaschema() {",
+                "  local -a commands",
+                `  commands=(${commands.map((name) => `'${name}'`).join(" ")})`,
+                "  if (( CURRENT == 2 )); then",
+                "    _describe 'command' commands",
+                "  fi",
+                "}",
+                '_supaschema "$@"',
+                "",
+            ].join("\n");
+        case "fish":
+            return `${commands
+                .map((name) => `complete -c supaschema -n "__fish_use_subcommand" -a ${name}`)
+                .join("\n")}\n`;
+        default:
+            return undefined;
+    }
+}
+const esc = String.fromCharCode(27);
+const ansi = {
+    green: `${esc}[32m`,
+    red: `${esc}[31m`,
+    reset: `${esc}[0m`,
+    yellow: `${esc}[33m`,
+};
+export function colorEnabled() {
+    return process.env.NO_COLOR === undefined && process.stdout.isTTY === true;
+}
+/**
+ * Tone comes from the structured operation (kind/blocked), never from
+ * re-classifying rendered text.
+ */
+export function colorizeSummaryLine(line, tone) {
+    if (!colorEnabled() || tone === "plain") {
+        return line;
+    }
+    const color = tone === "blocked" ? ansi.yellow : tone === "drop" ? ansi.red : ansi.green;
+    return `${color}${line}${ansi.reset}`;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}