backupdrill 0.1.0

package/dist/drill.js

@@ -0,0 +1,295 @@
+import { execFile, spawn } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { Client } from "pg";
+import { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
+import { log } from "./log.js";
+const execFileAsync = promisify(execFile);
+// Storage 校验默认抽样上限(避免每次演练重下全部文件产生大量 egress);超限如实记录
+const STORAGE_SAMPLE_CAP = 100;
+async function startEphemeralPostgres(major) {
+    const image = `postgres:${major}-alpine`;
+    log.step(`Starting ephemeral ${image}…`);
+    const { stdout } = await execFileAsync("docker", [
+        "run",
+        "-d",
+        "--rm",
+        "-e",
+        "POSTGRES_PASSWORD=drill",
+        "-e",
+        "POSTGRES_DB=postgres",
+        "-p",
+        "127.0.0.1:0:5432", // 随机主机端口,避免撞端口
+        image,
+    ]);
+    const containerId = stdout.trim();
+    try {
+        const portOut = await execFileAsync("docker", [
+            "port",
+            containerId,
+            "5432/tcp",
+        ]);
+        // 形如 "127.0.0.1:54321"
+        const port = portOut.stdout.trim().split(":").pop().trim();
+        const connString = `postgresql://postgres:drill@127.0.0.1:${port}/postgres`;
+        // 等就绪(容器内 pg_isready),最多 ~30s。
+        // 必须 -h 127.0.0.1 强制走 TCP:官方镜像 initdb 阶段先起一个只听 unix socket 的临时
+        // 服务跑初始化,默认(socket)检查在该阶段就通过,pg_restore 随后连 TCP 正撞上
+        // 临时服务停止/正式服务重启的窗口 → "server closed the connection unexpectedly"。
+        // 阶段一不听 TCP,所以 TCP 检查首次通过 = 正式服务已就绪。
+        for (let i = 0; i < 60; i++) {
+            try {
+                await execFileAsync("docker", [
+                    "exec",
+                    containerId,
+                    "pg_isready",
+                    "-h",
+                    "127.0.0.1",
+                    "-U",
+                    "postgres",
+                    "-q",
+                ]);
+                return { containerId, port, connString };
+            }
+            catch {
+                await new Promise((r) => setTimeout(r, 500));
+            }
+        }
+        throw new Error("ephemeral Postgres did not become ready within 30s");
+    }
+    catch (error) {
+        await execFileAsync("docker", ["rm", "-f", containerId]).catch(() => { });
+        throw error;
+    }
+}
+function spawnPgRestore(bin, args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(bin, args, { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        proc.stderr.on("data", (d) => (stderr += d.toString()));
+        proc.on("error", reject);
+        proc.on("close", (code) => resolve({ code, stderr }));
+    });
+}
+// 演练沙箱是裸 Postgres,Supabase 托管的 schema/角色必然缺席。post-data 里
+// 引用它们的失败是"环境预期",不是备份坏了;其余失败才是演练要抓的。
+const SUPABASE_MANAGED_ERROR = /schema "(auth|storage|realtime|vault|extensions|graphql[a-z_]*)" does not exist|role "(authenticated|anon|service_role|supabase_[a-z_]+)" does not exist|\bauth\.uid\b|\bauth\.jwt\b/i;
+/** 把 pg_restore 的 stderr 拆成单个错误块并分类(Supabase 托管 vs 用户对象)。 */
+export function classifyPostDataErrors(stderr) {
+    const blocks = stderr
+        .split(/(?=pg_restore: error:)/)
+        .filter((b) => /pg_restore: error:/.test(b));
+    let supabaseSkipped = 0;
+    const failures = [];
+    for (const block of blocks) {
+        // 只对 ERROR 原因行分类,不看 "Command was:" 之后的语句文本——否则一个恰好
+        // 引用 auth.uid 的用户对象因"损坏/语法错误"失败时,会被误判成预期跳过。
+        const cause = block.split(/Command was:/i)[0];
+        if (SUPABASE_MANAGED_ERROR.test(cause)) {
+            supabaseSkipped += 1;
+        }
+        else {
+            failures.push(block.replace(/\s+/g, " ").trim().slice(0, 200));
+        }
+    }
+    return { supabaseSkipped, failures };
+}
+/**
+ * post-data 第二遍的最终裁决:分类之外,非零退出却没解析到任何错误块(被信号杀死、
+ * 归档器致命错误等)绝不能谎报"全部恢复"——记为通用失败。
+ */
+export function postDataResult(code, stderr) {
+    const result = classifyPostDataErrors(stderr);
+    if (code !== 0 && result.supabaseSkipped === 0 && result.failures.length === 0) {
+        result.failures.push(`pg_restore post-data exited with ${code === null ? "a signal" : `code ${code}`}: ` +
+            (stderr.trim().replace(/\s+/g, " ").slice(0, 200) || "(no stderr)"));
+    }
+    return result;
+}
+/**
+ * 两遍恢复(真实首演炸出的设计):
+ * 1. pre-data+data —— 表结构 + 数据。任何错误都是硬失败:数据回不来 = 演练失败。
+ * 2. post-data —— 用户自己的索引/约束/触发器**必须**恢复成功(它们是"备份完整"的
+ *    一部分,一刀切跳过会让坏备份漏网);只有引用 Supabase 托管对象的失败
+ *    (policy TO authenticated、FK → auth.users)才归类为沙箱预期,记入报告而非失败。
+ */
+async function pgRestore(dumpPath, connString) {
+    const pgRestoreBin = process.env.BACKUPDRILL_PG_RESTORE ||
+        (process.env.BACKUPDRILL_PG_DUMP
+            ? process.env.BACKUPDRILL_PG_DUMP.replace(/pg_dump$/, "pg_restore")
+            : "pg_restore");
+    const common = ["--no-owner", "--no-privileges", "--dbname", connString, dumpPath];
+    const first = await spawnPgRestore(pgRestoreBin, [
+        "--clean",
+        "--if-exists",
+        "--section=pre-data",
+        "--section=data",
+        ...common,
+    ]);
+    // pg_restore 对无害告警会返回非 0;仅在明确 error 时判失败
+    if (first.code !== 0 && /error:/i.test(first.stderr)) {
+        throw new Error(`pg_restore failed: ${first.stderr.trim()}`);
+    }
+    const second = await spawnPgRestore(pgRestoreBin, ["--section=post-data", ...common]);
+    return postDataResult(second.code, second.stderr);
+}
+// ── 校验 ────────────────────────────────────────────────────────────
+async function verifyRestored(connString, manifest) {
+    const client = new Client({ connectionString: connString });
+    await client.connect();
+    try {
+        const schemas = manifest.database.schemas;
+        const tablesRes = await client.query(`select schemaname as schema, tablename as name
+         from pg_tables where schemaname = any($1::text[])`, [schemas]);
+        const restoredTables = tablesRes.rows;
+        // 逐表精确计数(演练要证明数据真回来了,估算值不够)
+        const counts = new Map();
+        let rowTotal = 0;
+        for (const t of restoredTables) {
+            const c = await client.query(`select count(*)::bigint as n from "${t.schema}"."${t.name}"`);
+            const n = Number(c.rows[0].n);
+            counts.set(`${t.schema}.${t.name}`, n);
+            rowTotal += n;
+        }
+        const checks = [];
+        // 1. 表数量一致
+        checks.push({
+            name: "table count",
+            pass: restoredTables.length === manifest.database.tableCount,
+            detail: `restored ${restoredTables.length}, manifest ${manifest.database.tableCount}`,
+        });
+        // 2. manifest 里的每张表都还原出来了
+        const restoredSet = new Set(counts.keys());
+        const missing = manifest.database.tables.filter((t) => !restoredSet.has(`${t.schema}.${t.name}`));
+        checks.push({
+            name: "no missing tables",
+            pass: missing.length === 0,
+            detail: missing.length === 0
+                ? "all manifest tables present"
+                : `missing: ${missing.map((t) => `${t.schema}.${t.name}`).join(", ")}`,
+        });
+        // 3. 备份时有数据的表,还原后不能是空的(最阴险的"备了半个库"故障)
+        const emptied = manifest.database.tables.filter((t) => t.estimatedRows > 0 && (counts.get(`${t.schema}.${t.name}`) ?? 0) === 0);
+        checks.push({
+            name: "populated tables came back",
+            pass: emptied.length === 0,
+            detail: emptied.length === 0
+                ? "no populated table restored empty"
+                : `restored empty despite manifest rows: ${emptied
+                    .map((t) => `${t.schema}.${t.name}`)
+                    .join(", ")}`,
+        });
+        return { checks, tableCount: restoredTables.length, rowTotal };
+    }
+    finally {
+        await client.end();
+    }
+}
+/**
+ * Storage 完整性校验:从备份桶重新读回文件、比对 manifest 里记录的 sha256,
+ * 证明备份的文件副本真实存在且未损坏。文件多时抽样(默认上限),避免大量 egress。
+ */
+async function verifyStorage(s3, config, manifest, verifyAll) {
+    const files = manifest.storage.files;
+    const sample = verifyAll ? files : files.slice(0, STORAGE_SAMPLE_CAP);
+    // 备份写入时的键:<snapshot base>/storage/<bucket>/<key>,base 从 dump.key 反推
+    const base = manifest.dump.key.replace(/\/dump\.pgcustom$/, "");
+    const mismatches = [];
+    for (const f of sample) {
+        const objectKey = `${base}/storage/${f.bucket}/${f.key}`;
+        try {
+            const { sha256 } = await hashObject(s3, config.storage.bucket, objectKey);
+            if (sha256 !== f.sha256)
+                mismatches.push(`${f.bucket}/${f.key}`);
+        }
+        catch {
+            mismatches.push(`${f.bucket}/${f.key} (unreadable)`);
+        }
+    }
+    const scope = verifyAll
+        ? `all ${files.length}`
+        : `${sample.length}/${files.length} sampled`;
+    return {
+        name: "storage file integrity",
+        pass: mismatches.length === 0,
+        detail: mismatches.length === 0
+            ? `${scope} files match their manifest checksums`
+            : `${mismatches.length} of ${scope} failed: ${mismatches.slice(0, 5).join(", ")}`,
+    };
+}
+// ── 主流程 ──────────────────────────────────────────────────────────
+/**
+ * 演练核心:把一份本地 dump 恢复进临时 Postgres 并对照 manifest 校验,然后销毁容器。
+ * 与 S3 解耦,便于离线测试。`preChecks` 用于把下载阶段的校验(如归档校验和)带进报告。
+ */
+export async function drillDump(dumpPath, manifest, snapshot, preChecks = []) {
+    const checks = [...preChecks];
+    const major = parseInt(manifest.database.serverVersion, 10);
+    const pg = await startEphemeralPostgres(major);
+    try {
+        const started = Date.now();
+        log.step("Restoring into ephemeral Postgres…");
+        const postData = await pgRestore(dumpPath, pg.connString);
+        const restoreSeconds = Math.round((Date.now() - started) / 100) / 10;
+        checks.push({ name: "pg_restore", pass: true, detail: `completed in ${restoreSeconds}s` });
+        // 用户自己的 post-data 对象(索引/约束/触发器)必须全部恢复;Supabase 托管对象
+        // 的沙箱预期跳过如实写进报告(演练不假装它们恢复了)。
+        checks.push({
+            name: "post-data objects",
+            pass: postData.failures.length === 0,
+            detail: postData.failures.length > 0
+                ? `${postData.failures.length} failed: ${postData.failures[0]}`
+                : postData.supabaseSkipped > 0
+                    ? `user objects restored; ${postData.supabaseSkipped} Supabase-managed object(s) skipped (auth schema/roles do not exist in the drill sandbox)`
+                    : "all post-data objects restored",
+        });
+        const verify = await verifyRestored(pg.connString, manifest);
+        checks.push(...verify.checks);
+        return {
+            snapshot,
+            pass: checks.every((c) => c.pass),
+            checks,
+            restoreSeconds,
+            restoredTableCount: verify.tableCount,
+            restoredRowTotal: verify.rowTotal,
+        };
+    }
+    finally {
+        log.step("Tearing down ephemeral Postgres…");
+        await execFileAsync("docker", ["rm", "-f", pg.containerId]).catch(() => { });
+    }
+}
+/** 演练一份快照:从桶里下载→drillDump(含 Storage 校验)→报告。 */
+export async function runDrill(config, opts = {}) {
+    const s3 = targetClient(config);
+    const snapshotPrefix = await resolveSnapshot(s3, config, opts.snapshot);
+    const snapshot = snapshotPrefix.replace(/\/$/, "").split("/").pop();
+    log.step(`Drilling snapshot ${snapshot}`);
+    const manifest = JSON.parse(await getObjectText(s3, config.storage.bucket, `${snapshotPrefix}manifest.json`));
+    const workdir = await mkdtemp(join(tmpdir(), "backupdrill-"));
+    const dumpPath = join(workdir, "dump.pgcustom");
+    try {
+        log.step("Downloading dump…");
+        const { sha256: sha } = await downloadToFile(s3, config.storage.bucket, manifest.dump.key, dumpPath);
+        const preChecks = [
+            {
+                name: "archive integrity",
+                pass: sha === manifest.dump.sha256,
+                detail: sha === manifest.dump.sha256
+                    ? `sha256 matches (${sha.slice(0, 12)}…)`
+                    : `sha256 MISMATCH — got ${sha.slice(0, 12)}…, manifest ${manifest.dump.sha256.slice(0, 12)}…`,
+            },
+        ];
+        // Storage 文件完整性(备份含 Storage 时才校验)
+        if (manifest.storage && manifest.storage.files.length) {
+            log.step("Verifying Storage files…");
+            preChecks.push(await verifyStorage(s3, config, manifest, opts.verifyAllFiles ?? false));
+        }
+        return await drillDump(dumpPath, manifest, snapshot, preChecks);
+    }
+    finally {
+        await rm(workdir, { recursive: true, force: true }).catch(() => { });
+    }
+}

package/dist/estimate.d.ts

@@ -0,0 +1,27 @@
+import type { BackupConfig } from "./config.js";
+/**
+ * Supabase egress 定价(2026-07-04 经核实,来源见 README「Egress & cost」)。
+ * 单价 = 超出计划包含额度后的每 GB 价;included = 各计划每月包含的 egress。
+ * 备份 = 把数据拉出 Supabase = egress,计入用户账单。这是 PRD §4.3 的上线否决项:
+ * 让用户"我们帮你算过账"而不是收到意外账单。
+ */
+export interface EgressPricing {
+    pricePerGb: number;
+    includedGb: number;
+    planLabel: string;
+    hardCap: boolean;
+}
+export interface EgressProjection {
+    dbBytes: number;
+    storageBytes: number;
+    perRunGb: number;
+    rows: Array<{
+        frequency: string;
+        runsPerMonth: number;
+        monthlyEgressGb: number;
+        overageGb: number;
+        monthlyCost: number;
+    }>;
+}
+export declare function project(dbBytes: number, storageBytes: number, pricing: EgressPricing): EgressProjection;
+export declare function runEstimate(config: BackupConfig, pricing: EgressPricing): Promise<EgressProjection>;

package/dist/estimate.js

@@ -0,0 +1,102 @@
+import { Client } from "pg";
+import { measureStorage } from "./storage.js";
+import { log } from "./log.js";
+// 超出这个月度成本就该提醒用户"备份的 egress 账单快赶上订阅费了"
+const SUBSCRIPTION_FLOOR_USD = 19;
+const GB = 1024 * 1024 * 1024;
+async function measureDbBytes(databaseUrl, schemas) {
+    const client = new Client({ connectionString: databaseUrl });
+    await client.connect();
+    try {
+        // pg_total_relation_size 含索引+TOAST,是 egress 上界(真实转储经压缩、不含索引,更小)
+        const res = await client.query(`select coalesce(
+                sum(pg_total_relation_size(format('%I.%I', schemaname, relname)::regclass)),
+                0
+              )::bigint as bytes
+         from pg_stat_user_tables
+        where schemaname = any($1::text[])`, [schemas]);
+        return Number(res.rows[0].bytes);
+    }
+    finally {
+        await client.end();
+    }
+}
+export function project(dbBytes, storageBytes, pricing) {
+    const perRunGb = (dbBytes + storageBytes) / GB;
+    const frequencies = [
+        ["weekly", 52 / 12], // ≈4.33 次/月
+        ["daily", 30],
+    ];
+    const rows = frequencies.map(([frequency, runsPerMonth]) => {
+        const monthlyEgressGb = perRunGb * runsPerMonth;
+        // 保守:假设备份是该项目唯一 egress 来源;真实还要叠加应用自身流量
+        const overageGb = Math.max(0, monthlyEgressGb - pricing.includedGb);
+        return {
+            frequency,
+            runsPerMonth: Math.round(runsPerMonth * 10) / 10,
+            monthlyEgressGb: Math.round(monthlyEgressGb * 10) / 10,
+            overageGb: Math.round(overageGb * 10) / 10,
+            monthlyCost: Math.round(overageGb * pricing.pricePerGb * 100) / 100,
+        };
+    });
+    return { dbBytes, storageBytes, perRunGb, rows };
+}
+export async function runEstimate(config, pricing) {
+    log.step("Measuring database size…");
+    const dbBytes = await measureDbBytes(config.databaseUrl, config.schemas);
+    log.ok(`Database (schema ${config.schemas.join(", ")}): ${(dbBytes / GB).toFixed(2)} GB (upper bound)`);
+    let storageBytes = 0;
+    if (config.supabaseStorage) {
+        log.step("Measuring Storage size (listing only, no download)…");
+        const m = await measureStorage(config.supabaseStorage);
+        storageBytes = m.totalBytes;
+        log.ok(`Storage: ${m.fileCount} files, ${(storageBytes / GB).toFixed(2)} GB`);
+    }
+    const projection = project(dbBytes, storageBytes, pricing);
+    console.error("");
+    console.error(`  Egress per backup:  ~${projection.perRunGb.toFixed(2)} GB ` +
+        `(DB dump is smaller after compression; Storage is exact)`);
+    console.error(`  Plan: ${pricing.planLabel} — ${pricing.includedGb} GB egress included, ` +
+        `then $${pricing.pricePerGb}/GB`);
+    console.error("");
+    console.error("  Frequency   Runs/mo   Monthly egress   Overage   Est. cost/mo");
+    console.error("  ─────────   ───────   ──────────────   ───────   ────────────");
+    for (const r of projection.rows) {
+        console.error(`  ${r.frequency.padEnd(9)}   ${String(r.runsPerMonth).padStart(7)}   ` +
+            `${(r.monthlyEgressGb + " GB").padStart(14)}   ` +
+            `${(r.overageGb + " GB").padStart(7)}   ` +
+            `$${r.monthlyCost.toFixed(2)}`);
+    }
+    console.error("");
+    console.error("  Note: assumes backups are this project's only egress. Your app's own " +
+        "traffic\n  adds to the total. This is an upper bound — check manifest.json " +
+        "after a\n  real run for the actual bytes transferred.");
+    // 守护提示:egress 是把双刃剑,两种失败模式都要点破
+    const daily = projection.rows.find((r) => r.frequency === "daily");
+    const weekly = projection.rows.find((r) => r.frequency === "weekly");
+    console.error("");
+    if (pricing.hardCap) {
+        // Free:超额=限流,备份直接失败,daily 大库根本跑不完
+        if (daily && daily.overageGb > 0) {
+            log.warn(`${pricing.planLabel} egress is a HARD CAP (${pricing.includedGb} GB). ` +
+                `Daily backups (~${daily.monthlyEgressGb} GB/mo) will blow the cap and ` +
+                `get your project throttled — the backup itself will fail. ` +
+                `Use weekly at most, or upgrade to Pro.`);
+        }
+    }
+    else {
+        // Pro/Team:Spend Cap 决定是"限流"还是"账单"
+        log.warn("Spend Cap is ON by default on Pro/Team. If a backup pushes you past the " +
+            `${pricing.includedGb} GB egress quota, Supabase throttles your project's ` +
+            "egress for the rest of the month (your app's traffic too), and the backup " +
+            "fails. Turn Spend Cap OFF to allow billed overage instead — then the " +
+            "numbers above are what you'd pay.");
+        const worst = daily?.monthlyCost ?? 0;
+        if (worst >= SUBSCRIPTION_FLOOR_USD) {
+            log.warn(`At daily frequency the egress overage alone (~$${worst.toFixed(0)}/mo) is ` +
+                `in the range of a paid backup subscription. Consider weekly ` +
+                `(~$${(weekly?.monthlyCost ?? 0).toFixed(0)}/mo overage) or a smaller scope.`);
+        }
+    }
+    return projection;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { loadConfig } from "./config.js";
+import { runBackup } from "./backup.js";
+import { runEstimate } from "./estimate.js";
+import { runDrill } from "./drill.js";
+import { runRestore } from "./restore.js";
+import { log } from "./log.js";
+// Supabase egress 定价表(2026-07-04 核实,来源见 README「Egress & cost」)。
+// 备份流量 100% 未缓存,故用 uncached 单价 $0.09/GB;included 用 uncached 额度。
+// Free 硬上限(超额即限流,不计费);Pro/Team 由 Spend Cap 决定超额限流还是计费。
+const EGRESS_PRICING = {
+    free: { planLabel: "Free", includedGb: 5, pricePerGb: 0.09, hardCap: true },
+    pro: { planLabel: "Pro", includedGb: 250, pricePerGb: 0.09, hardCap: false },
+    team: { planLabel: "Team", includedGb: 250, pricePerGb: 0.09, hardCap: false },
+};
+const program = new Command();
+program
+    .name("backupdrill")
+    .description("Back up a Supabase project — Postgres database (and, soon, Storage files) — " +
+    "to your own S3/R2/B2 bucket, with a checksummed manifest.\n\n" +
+    "Want scheduling, restore drills, and alerts? → https://backupdrill.com")
+    .version(process.env.npm_package_version || "0.1.0");
+program
+    .command("backup")
+    .description("Run a one-off backup to your own bucket")
+    .option("-c, --config <path>", "path to a JSON config file", "backupdrill.config.json")
+    .option("--database-url <url>", "Supabase Session Pooler connection string")
+    .option("--project-name <name>", "readable name for this project (used in the object key)")
+    .option("--schema <name...>", "schema(s) to back up (default: public; platform schemas like auth/storage are excluded)")
+    .option("--bucket <name>", "target S3/R2/B2 bucket")
+    .option("--endpoint <url>", "S3-compatible endpoint (required for R2/B2; omit for AWS S3)")
+    .option("--region <region>", "bucket region (default: auto)")
+    .option("--prefix <prefix>", "key prefix inside the bucket (default: backupdrill)")
+    .action(async (opts) => {
+    try {
+        const config = await loadConfig({
+            configPath: opts.config,
+            overrides: {
+                databaseUrl: opts.databaseUrl,
+                projectName: opts.projectName,
+                schemas: opts.schema,
+                storage: {
+                    bucket: opts.bucket,
+                    endpoint: opts.endpoint,
+                    region: opts.region,
+                    prefix: opts.prefix,
+                },
+            },
+        });
+        const manifest = await runBackup(config);
+        const storageNote = manifest.storage
+            ? ` + ${manifest.storage.fileCount} Storage files`
+            : " (database only)";
+        log.ok(`Backup complete — ${manifest.database.tableCount} tables` +
+            `${storageNote}.`);
+        // stdout 输出机器可读结果,便于在 CI / GitHub Action 里消费
+        process.stdout.write(JSON.stringify({ ok: true, manifest }) + "\n");
+    }
+    catch (error) {
+        log.error(error.message);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("drill")
+    .description("Restore a snapshot into an ephemeral Postgres and prove it comes back (needs Docker)")
+    .option("-c, --config <path>", "path to a JSON config file", "backupdrill.config.json")
+    .option("--snapshot <timestamp>", "which snapshot to drill (default: latest)")
+    .option("--bucket <name>", "bucket the backups live in")
+    .option("--endpoint <url>", "S3-compatible endpoint (for R2/B2)")
+    .option("--region <region>", "bucket region")
+    .option("--prefix <prefix>", "key prefix inside the bucket (default: backupdrill)")
+    .option("--project-name <name>", "project name used in the object key")
+    .option("--verify-all-files", "checksum every Storage file, not just a sample")
+    .action(async (opts) => {
+    try {
+        const config = await loadConfig({
+            configPath: opts.config,
+            overrides: {
+                projectName: opts.projectName,
+                // drill 只读桶,不连源库;给 databaseUrl 占位以通过校验
+                databaseUrl: "postgresql://unused",
+                storage: {
+                    bucket: opts.bucket,
+                    endpoint: opts.endpoint,
+                    region: opts.region,
+                    prefix: opts.prefix,
+                },
+            },
+        });
+        const report = await runDrill(config, {
+            snapshot: opts.snapshot,
+            verifyAllFiles: opts.verifyAllFiles,
+        });
+        console.error("");
+        for (const c of report.checks) {
+            console.error(`  ${c.pass ? "✓" : "✗"} ${c.name} — ${c.detail}`);
+        }
+        console.error("");
+        log[report.pass ? "ok" : "error"](`Drill ${report.pass ? "PASSED" : "FAILED"} — snapshot ${report.snapshot}, ` +
+            `${report.restoredTableCount} tables / ${report.restoredRowTotal.toLocaleString()} rows ` +
+            `restored in ${report.restoreSeconds}s`);
+        process.stdout.write(JSON.stringify({ ok: report.pass, report }) + "\n");
+        if (!report.pass)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        log.error(error.message);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("restore")
+    .description("Recover a snapshot: restore the database into a target and pull Storage files down")
+    .option("-c, --config <path>", "path to a JSON config file", "backupdrill.config.json")
+    .option("--target-database-url <url>", "connection string to restore the database INTO")
+    .option("--storage-dir <path>", "local directory to write Storage files to")
+    .option("--snapshot <timestamp>", "which snapshot to restore (default: latest)")
+    .option("--bucket <name>", "bucket the backups live in")
+    .option("--endpoint <url>", "S3-compatible endpoint (for R2/B2)")
+    .option("--region <region>", "bucket region")
+    .option("--prefix <prefix>", "key prefix inside the bucket (default: backupdrill)")
+    .option("--project-name <name>", "project name used in the object key")
+    .action(async (opts) => {
+    try {
+        const config = await loadConfig({
+            configPath: opts.config,
+            overrides: {
+                projectName: opts.projectName,
+                databaseUrl: "postgresql://unused", // restore 读桶,不连源库
+                storage: {
+                    bucket: opts.bucket,
+                    endpoint: opts.endpoint,
+                    region: opts.region,
+                    prefix: opts.prefix,
+                },
+            },
+        });
+        const result = await runRestore(config, {
+            targetDatabaseUrl: opts.targetDatabaseUrl,
+            storageDir: opts.storageDir,
+            snapshot: opts.snapshot,
+        });
+        log.ok(`Restore complete — snapshot ${result.snapshot}: ` +
+            `database ${result.restoredToDatabase ? "restored" : "skipped"}, ` +
+            `${result.storageFilesWritten} Storage files written` +
+            (result.storageDir ? ` to ${result.storageDir}` : ""));
+    }
+    catch (error) {
+        log.error(error.message);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("estimate")
+    .description("Measure your DB + Storage size and project monthly Supabase egress cost")
+    .option("-c, --config <path>", "path to a JSON config file", "backupdrill.config.json")
+    .option("--database-url <url>", "Supabase Session Pooler connection string")
+    .option("--schema <name...>", "schema(s) to measure (default: public)")
+    .option("--plan <plan>", "your Supabase plan for the cost estimate: free | pro | team", "pro")
+    .action(async (opts) => {
+    try {
+        const config = await loadConfig({
+            configPath: opts.config,
+            overrides: {
+                databaseUrl: opts.databaseUrl,
+                schemas: opts.schema,
+                // estimate 不写数据,给目标桶占位以通过校验(仅用 databaseUrl + 源)
+                storage: { bucket: "estimate", accessKeyId: "estimate", secretAccessKey: "estimate" },
+            },
+        });
+        const pricing = EGRESS_PRICING[opts.plan];
+        if (!pricing)
+            throw new Error(`Unknown plan "${opts.plan}". Use free | pro | team.`);
+        await runEstimate(config, pricing);
+    }
+    catch (error) {
+        log.error(error.message);
+        process.exitCode = 1;
+    }
+});
+program.parseAsync().catch((error) => {
+    log.error(error.message);
+    process.exitCode = 1;
+});

package/dist/lib.d.ts

@@ -0,0 +1,11 @@
+export { runBackup } from "./backup.js";
+export { runDrill, drillDump } from "./drill.js";
+export { runRestore } from "./restore.js";
+export { runEstimate, project } from "./estimate.js";
+export { loadConfig } from "./config.js";
+export { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
+export type { BackupConfig, StorageConfig, SupabaseStorageConfig, } from "./config.js";
+export type { Manifest, StorageFile, TableStat } from "./manifest.js";
+export type { DrillReport, DrillCheck } from "./drill.js";
+export type { RestoreResult } from "./restore.js";
+export type { EgressPricing, EgressProjection } from "./estimate.js";

package/dist/lib.js

@@ -0,0 +1,8 @@
+// 库入口:把引擎函数暴露给下游复用(产品 worker 直接 import 这些,而不是重写)。
+// CLI(bin)是这套引擎的薄封装;worker 在其外加调度、凭据托管、告警、报告。
+export { runBackup } from "./backup.js";
+export { runDrill, drillDump } from "./drill.js";
+export { runRestore } from "./restore.js";
+export { runEstimate, project } from "./estimate.js";
+export { loadConfig } from "./config.js";
+export { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";

package/dist/log.d.ts

@@ -0,0 +1,6 @@
+export declare const log: {
+    step: (msg: string) => void;
+    ok: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};

package/dist/log.js

@@ -0,0 +1,12 @@
+// 极简日志:全部走 stderr,让 stdout 留给未来可能的机器可读输出(如 --json)
+const useColor = process.stderr.isTTY && !process.env.NO_COLOR;
+const dim = (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s);
+const green = (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s);
+const red = (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s);
+const yellow = (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s);
+export const log = {
+    step: (msg) => console.error(dim("→ ") + msg),
+    ok: (msg) => console.error(green("✓ ") + msg),
+    warn: (msg) => console.error(yellow("! ") + msg),
+    error: (msg) => console.error(red("✗ ") + msg),
+};