backupdrill 1.0.0 → 2.0.0

package/README.md

@@ -160,20 +160,47 @@ Your command runs after all structural checks pass, with `BACKUPDRILL_SANDBOX_UR
 
 **What this can and cannot verify, honestly:** `BACKUPDRILL_SANDBOX_URL` connects as the sandbox **superuser**, and superusers bypass row-level security — plus policies referencing Supabase-managed roles (`authenticated`, `anon`) are skipped during restore, since those roles don't exist outside the platform. So use `--check-cmd` for data and business invariants ("orders reference existing users", "the row count I care about is sane"). It is **not** an RLS behavior test — verifying RLS takes an authenticated client stack with real JWTs, which no restore sandbox can fake generically.
 
-When you actually need to recover, `restore` puts the database back into a target you name and pulls the Storage files down to a local folder:
+When you actually need to recover, `restore` puts the database back into a fresh
+target project (through the same engine the drills use, with verification) and
+uploads the Storage files back — start with `--dry-run`, then confirm by typing
+the target's project ref:
 
 ```bash
-backupdrill restore \
-  --target-database-url "postgresql://…/postgres" \
-  --storage-dir ./recovered
+# credentials via hidden prompts (nothing lands in shell history); CI can inject
+# BACKUPDRILL_TARGET_DATABASE_URL / BACKUPDRILL_TARGET_SERVICE_ROLE_KEY as managed secrets instead
+backupdrill restore --database --target-supabase-url https://<ref>.supabase.co --dry-run
+backupdrill restore --database --target-supabase-url https://<ref>.supabase.co --confirm-target <ref>
 ```
 
-Or restore the dump by hand:
+Prefer files on disk instead? Skip the Storage target and pass `--storage-dir ./recovered`.
+
+Or restore the dump by hand — into an **empty** database, without `--clean`:
 
 ```bash
-pg_restore --clean --if-exists --no-owner --dbname "<target-connection-string>" dump.pgcustom
+pg_restore --no-owner --no-privileges --dbname "<target-connection-string>" dump.pgcustom
 ```
 
+Don't use `--clean` against a Supabase project: dropping and recreating the `public`
+schema silently wipes Supabase's default grants for `anon`/`authenticated` (the dump
+carries no ACLs), leaving the restored API returning 401s. One error is expected and
+harmless: `schema "public" already exists` — the target always has it. The
+`backupdrill restore` command above handles all of this (plus verification) for you.
+
+## 2.0 migration — `restore` flags changed
+
+Restore now refuses to take credentials on the command line (argv is visible to
+every process on the machine):
+
+- `--target-database-url <url>` was **removed**. Set `BACKUPDRILL_TARGET_DATABASE_URL`
+  (or let the hidden prompt ask) and pass `--database` to say you want the
+  database restored.
+- Writing to a target now requires `--confirm-target <target-ref>` — type the
+  target project's ref to confirm. Run `--dry-run` first to preview every check.
+- The service-role key for Storage upload comes from
+  `BACKUPDRILL_TARGET_SERVICE_ROLE_KEY` (or the hidden prompt), never a flag.
+
+`backup`, `drill` and `estimate` are unchanged.
+
 ## GitHub Action / scheduled backups
 
 Want this running on a schedule without paying for a server? Run it in GitHub Actions.
@@ -193,7 +220,7 @@ Before switching to a **daily** schedule, read the egress-cost section above —
 - [x] `estimate` — project your monthly Supabase egress cost before you schedule
 - [x] `drill` — restore a snapshot into an ephemeral Postgres and prove it comes back
 - [x] Storage-file integrity check inside the drill (checksums, sampled by default)
-- [x] `restore` — recover a snapshot into a target DB + pull Storage files down
+- [x] `restore` — recover a snapshot into a fresh Supabase project: database through the drill-grade engine with verification, Storage uploaded back with per-file reconciliation (local download remains an option)
 - [x] GitHub Action wrapper
 
 For scheduling, automated restore drills, and alerting, use the hosted service at [backupdrill.com](https://backupdrill.com).

package/dist/backup.js

@@ -7,6 +7,9 @@ import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 import { Upload } from "@aws-sdk/lib-storage";
 import { MANIFEST_SCHEMA_VERSION } from "./manifest.js";
 import { syncStorage } from "./storage.js";
+import { inspectBucketAttrs } from "./storage-catalog.js";
+import { renderRecoveryDoc } from "./recovery-doc.js";
+import { projectRefOf, refFromStorageEndpoint, assertNoHostOverride } from "./restore-engine.js";
 import { log } from "./log.js";
 import { TOOL_VERSION } from "./version.js";
 import { pgConnectOptions, dumpUrlFor } from "./supabase-ca.js";
@@ -148,6 +151,19 @@ async function dumpToS3(config, s3, key, pgDumpBin) {
     return { bytes, sha256: hash.digest("hex") };
 }
 export async function runBackup(config) {
+    // 源身份先于一切传输(评审第 12 轮):①连接串不许带 ?host=/user= 覆盖——否则
+    // 快照记的 ref 与实际读取对象脱节,恢复端的同源保护随之失真;②库与 Storage
+    // 跨项目 = 配置错误,全量 dump+同步之后才发现会白烧 egress 还留下半截快照前缀
+    assertNoHostOverride(config.databaseUrl);
+    const dbRef = projectRefOf(config.databaseUrl);
+    const storageRef = config.supabaseStorage
+        ? refFromStorageEndpoint(config.supabaseStorage.endpoint)
+        : null;
+    if (dbRef && storageRef && dbRef !== storageRef) {
+        throw new Error(`database points at Supabase project "${dbRef}" but Storage at "${storageRef}" — ` +
+            `one BackupDrill project backs up one Supabase project; fix the config before backing up.`);
+    }
+    const sourceProjectRef = dbRef ?? storageRef;
     const pgDumpBin = process.env.BACKUPDRILL_PG_DUMP || "pg_dump";
     log.step("Inspecting database…");
     const db = await inspectDatabase(config.databaseUrl, config.schemas);
@@ -186,7 +202,20 @@ export async function runBackup(config) {
             bucket: config.storage.bucket,
             base, // syncStorage 内部会加 /storage/<bucket>/<key>
         });
+        // v2 bucket 属性采集,通道 = 已有的只读库连接(per-file 元数据已随 GetObject
+        // 响应在 syncStorage 内原子捕获)。失败只降级不报错:storage schema 读不到
+        // (如收紧的 backup_reader 角色)时,manifest 缺 buckets 字段,恢复端把缺失
+        // 如实标 not captured(PRD §5.1.3)。
+        let bucketAttrs;
+        try {
+            bucketAttrs = await inspectBucketAttrs(config.databaseUrl, synced.buckets);
+        }
+        catch (error) {
+            log.warn(`Bucket attributes not captured (${error.message}); ` +
+                `this manifest will record them as absent — restore will say so instead of guessing.`);
+        }
         storageResult = {
+            ...(bucketAttrs ? { buckets: bucketAttrs } : {}),
             fileCount: synced.fileCount,
             totalBytes: synced.totalBytes,
             files: synced.files,
@@ -200,6 +229,7 @@ export async function runBackup(config) {
         toolVersion: TOOL_VERSION,
         createdAt: new Date().toISOString(),
         projectName: config.projectName,
+        ...(sourceProjectRef ? { sourceProjectRef } : {}),
         database: {
             serverVersion: db.serverVersion,
             pgDumpVersion: pgd.raw,
@@ -212,6 +242,23 @@ export async function runBackup(config) {
         dump: { key: dumpKey, format: "custom", bytes, sha256 },
         storage: storageResult,
     };
+    // RECOVERY.md(PRD §5.9.2.1)先于 manifest 落桶:manifest 是快照的"完成标记"
+    // (演练/恢复按它找快照)——先写手册再写标记,"快照完成"就蕴含"手册在场";
+    // 手册写失败 = 备份失败(同桶同权限,与 manifest 自身的写入风险一致)。
+    await s3.send(new PutObjectCommand({
+        Bucket: config.storage.bucket,
+        Key: `${base}/RECOVERY.md`,
+        Body: renderRecoveryDoc(manifest, {
+            snapshot: timestamp,
+            bucket: config.storage.bucket,
+            endpoint: config.storage.endpoint,
+            region: config.storage.region,
+            prefix: config.storage.prefix,
+            projectName: config.projectName,
+        }),
+        ContentType: "text/markdown",
+    }));
+    log.ok(`Recovery runbook written → s3://${config.storage.bucket}/${base}/RECOVERY.md`);
     await s3.send(new PutObjectCommand({
         Bucket: config.storage.bucket,
         Key: `${base}/manifest.json`,

package/dist/drill.d.ts

@@ -31,13 +31,16 @@ interface PostDataResult {
     supabaseSkipped: number;
     failures: string[];
 }
-/** 把 pg_restore 的 stderr 拆成单个错误块并分类(Supabase 托管 vs 用户对象)。 */
+/** 兼容层:历史签名保留,分类逻辑的单一权威在统一引擎(restore-engine.ts)。 */
 export declare function classifyPostDataErrors(stderr: string): PostDataResult;
-/**
- * post-data 第二遍的最终裁决:分类之外,非零退出却没解析到任何错误块(被信号杀死、
- * 归档器致命错误等)绝不能谎报"全部恢复"——记为通用失败。
- */
+/** 兼容层:见 restore-engine.ts finalizePass(非零退出且零错误块 = 通用失败)。 */
 export declare function postDataResult(code: number | null, stderr: string): PostDataResult;
+/** 导出:真实恢复(restore.ts)复用同一套表级验证——两条路径对同一快照必须同一结论。 */
+export declare function verifyRestored(connString: string, manifest: Manifest): Promise<{
+    checks: DrillCheck[];
+    tableCount: number;
+    rowTotal: number;
+}>;
 export declare const APP_CHECK_TIMEOUT_MS: number;
 /**
  * 语义层钩子:结构检查全绿后、销毁沙箱前,把沙箱连接串经 BACKUPDRILL_SANDBOX_URL

package/dist/drill.js

@@ -6,7 +6,8 @@ import { promisify } from "node:util";
 import { Client } from "pg";
 import { parseManifest } from "./manifest.js";
 import { targetClient, resolveSnapshot, getObjectText, downloadToFile, hashObject, } from "./snapshots.js";
-import { resolvePgRestoreBin } from "./pgbin.js";
+import { SANDBOX_MANAGED_ERROR, classifyBlocks, finalizePass, installExtensions, quoteIdent, restoreDatabaseArtifact, } from "./restore-engine.js";
+import { pgConnectOptions } from "./supabase-ca.js";
 import { log } from "./log.js";
 const execFileAsync = promisify(execFile);
 // Storage 校验默认抽样上限(避免每次演练重下全部文件产生大量 egress);超限如实记录
@@ -92,114 +93,42 @@ async function startEphemeralPostgres(image) {
         throw error;
     }
 }
-function quoteIdent(name) {
-    return `"${name.replace(/"/g, '""')}"`;
-}
-/**
- * 恢复前把 manifest 记录的扩展装进沙箱(--schema 转储不含 CREATE EXTENSION)。
- * 必须装进与源库相同的 schema:dump 里的类型是限定名(如 extensions.vector)。
- * 装不上的扩展如实收集返回,**不在这里失败**——Supabase 项目普遍装着沙箱镜像
- * 没有的托管扩展(pg_graphql、supabase_vault…),public 转储通常并不引用它们;
- * 只有恢复真的因此失败时才升级为分类错误(见 drillDump)。
- */
-async function installExtensions(connString, extensions) {
-    if (!extensions.length)
-        return [];
-    const client = new Client({ connectionString: connString });
-    await client.connect();
-    const unavailable = [];
-    try {
-        for (const ext of extensions) {
-            try {
-                await client.query(`create schema if not exists ${quoteIdent(ext.schema)}`);
-                // CASCADE 自动带上依赖扩展,免受 manifest 里的安装顺序摆布
-                await client.query(`create extension if not exists ${quoteIdent(ext.name)} schema ${quoteIdent(ext.schema)} cascade`);
-            }
-            catch {
-                unavailable.push(ext.name);
-            }
-        }
-    }
-    finally {
-        await client.end();
-    }
-    return unavailable;
-}
-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 }));
-    });
-}
 // 只有这些特征说明恢复失败源于沙箱缺扩展(限定类型/schema 解析不到、扩展装不上)。
 // 真实 Supabase 项目的 manifest 几乎必然含沙箱装不上的托管扩展(pg_graphql 等),
 // 若不按特征过滤,任何硬失败(归档损坏、OOM…)都会被误归因到沙箱。
 const MISSING_EXTENSION_ERROR = /type "[^"]+" does not exist|schema "[^"]+" does not exist|extension "[^"]+" is not available/i;
-// 演练沙箱是裸 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 用户对象)。 */
+/** 兼容层:历史签名保留,分类逻辑的单一权威在统一引擎(restore-engine.ts)。 */
 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 };
+    const classified = classifyBlocks(stderr, SANDBOX_MANAGED_ERROR);
+    return { supabaseSkipped: classified.expectedSkips, failures: classified.failures };
 }
-/**
- * post-data 第二遍的最终裁决:分类之外,非零退出却没解析到任何错误块(被信号杀死、
- * 归档器致命错误等)绝不能谎报"全部恢复"——记为通用失败。
- */
+/** 兼容层:见 restore-engine.ts finalizePass(非零退出且零错误块 = 通用失败)。 */
 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;
+    const classified = finalizePass(code, stderr, classifyBlocks(stderr, SANDBOX_MANAGED_ERROR));
+    return { supabaseSkipped: classified.expectedSkips, failures: classified.failures };
 }
 /**
- * 两遍恢复(真实首演炸出的设计):
- * 1. pre-data+data —— 表结构 + 数据。任何错误都是硬失败:数据回不来 = 演练失败。
- * 2. post-data —— 用户自己的索引/约束/触发器**必须**恢复成功(它们是"备份完整"的
- *    一部分,一刀切跳过会让坏备份漏网);只有引用 Supabase 托管对象的失败
- *    (policy TO authenticated、FK → auth.users)才归类为沙箱预期,记入报告而非失败。
+ * 沙箱恢复 = 统一引擎(target: "sandbox")。pre-data 失败按硬失败抛出——数据回不来
+ * = 演练失败,且错误文本要供缺扩展归因(MISSING_EXTENSION_ERROR)使用;post-data
+ * 的托管对象跳过如实返回。pre-data 的 schema 冲突跳过(dump 自带 CREATE SCHEMA,
+ * 容器恒有 public)是非事件,不计入报告。
  */
 async function pgRestore(dumpPath, connString) {
-    const pgRestoreBin = resolvePgRestoreBin();
-    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 result = await restoreDatabaseArtifact({ dumpPath, connString, target: "sandbox" });
+    if (result.preData.failures.length) {
+        throw new Error(`pg_restore failed: ${result.preData.failures.join(" | ")}`);
     }
-    const second = await spawnPgRestore(pgRestoreBin, ["--section=post-data", ...common]);
-    return postDataResult(second.code, second.stderr);
+    return {
+        supabaseSkipped: result.postData.expectedSkips,
+        failures: result.postData.failures,
+    };
 }
 // ── 校验 ────────────────────────────────────────────────────────────
-async function verifyRestored(connString, manifest) {
-    const client = new Client({ connectionString: connString });
+/** 导出:真实恢复(restore.ts)复用同一套表级验证——两条路径对同一快照必须同一结论。 */
+export async function verifyRestored(connString, manifest) {
+    // pgConnectOptions:真实 Supabase 目标(restore 复用本函数)需要打包根 CA;
+    // 沙箱的 docker 连接串非 Supabase 主机,原样透传,行为不变
+    const client = new Client(pgConnectOptions(connString));
     await client.connect();
     try {
         const schemas = manifest.database.schemas;
@@ -229,7 +158,9 @@ async function verifyRestored(connString, manifest) {
                 unpopulatedMatviews.add(key);
                 continue;
             }
-            const c = await client.query(`select count(*)::bigint as n from "${t.schema}"."${t.name}"`);
+            // 名字来自恢复出的库(= 来自 dump = 桶里的数据):必须走标识符转义,
+            // 内嵌引号的合法名不炸,构造名不注入
+            const c = await client.query(`select count(*)::bigint as n from ${quoteIdent(t.schema)}.${quoteIdent(t.name)}`);
             const n = Number(c.rows[0].n);
             counts.set(key, n);
             // 分区父表的 count(*) 是子分区行的总和,子分区又各自计一次;

package/dist/index.js

@@ -4,7 +4,28 @@ 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 { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+import { runRestore, NO_SOURCE_DATABASE } from "./restore.js";
+/** 隐藏式秘密输入(PRD §5.3.1):终端不回显;无 TTY(CI/脚本)时明确要求走环境变量。 */
+async function promptSecret(label) {
+    if (!process.stdin.isTTY) {
+        throw new Error(`${label} is required — set the environment variable (no TTY available for a prompt).`);
+    }
+    const muted = new Writable({ write: (_chunk, _enc, cb) => cb() });
+    const rl = createInterface({ input: process.stdin, output: muted, terminal: true });
+    process.stderr.write(`${label} (hidden): `);
+    try {
+        const value = (await rl.question("")).trim();
+        process.stderr.write("\n");
+        if (!value)
+            throw new Error(`${label} was empty.`);
+        return value;
+    }
+    finally {
+        rl.close();
+    }
+}
 import { log } from "./log.js";
 import { TOOL_VERSION } from "./version.js";
 // Supabase egress 定价表(2026-07-10 核实,来源见 README「Egress & cost」)。
@@ -125,10 +146,18 @@ program
 });
 program
     .command("restore")
-    .description("Recover a snapshot: restore the database into a target and pull Storage files down")
+    .description("Recover a snapshot into a FRESH Supabase project: database via the drill-grade engine, " +
+    "Storage files uploaded back (or downloaded locally). Start with --dry-run.")
     .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("--database", "restore the database — connection string via env BACKUPDRILL_TARGET_DATABASE_URL or a hidden prompt " +
+    "(2.0: the credential-bearing --target-database-url flag was removed; argv is visible to every process)")
+    .option("--target-supabase-url <url>", "target project URL (https://<ref>.supabase.co) to upload Storage files into; " +
+    "service-role key via env BACKUPDRILL_TARGET_SERVICE_ROLE_KEY or a hidden prompt")
+    .option("--confirm-target <ref>", "type the TARGET project ref to confirm writing to it")
+    .option("--dry-run", "run every read-only preflight check and write nothing")
+    .option("--acknowledge-unverified-source", "proceed although the source identity cannot be verified (legacy snapshot without config) — " +
+    "same-source protection is inert; double-check the target first")
+    .option("--storage-dir <path>", "local directory to write Storage files to (when not uploading)")
     .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)")
@@ -137,28 +166,79 @@ program
     .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,
-                },
+        // 源库连接串不再无条件屏蔽:配置/环境里有真实源时,runRestore 的同源阻断门
+        // 要拿它比对;纯 flag 驱动(无任何源配置)才退回占位符
+        const overrides = {
+            projectName: opts.projectName,
+            storage: {
+                bucket: opts.bucket,
+                endpoint: opts.endpoint,
+                region: opts.region,
+                prefix: opts.prefix,
             },
-        });
+        };
+        let config;
+        try {
+            config = await loadConfig({ configPath: opts.config, overrides });
+        }
+        catch (error) {
+            if (!/databaseUrl/.test(error.message))
+                throw error;
+            config = await loadConfig({
+                configPath: opts.config,
+                overrides: { ...overrides, databaseUrl: NO_SOURCE_DATABASE },
+            });
+        }
+        // 凭据形态(决策 D6,2.0 起):env 或隐藏式交互输入,绝不经 argv。
+        // --database 只表达意图,秘密自身不上命令行
+        // 秘密只随各自的意图旗标读取(评审第 9/10 轮):环境变量残留不能把 storage-only
+        // 变成意外的数据库恢复,也不能把无 Storage 目标的运行拖进凭据配对检查;
+        // 空串按缺失处理(误 export 空值不许静默吞掉一个显式请求)
+        let targetDatabaseUrl;
+        if (opts.database) {
+            targetDatabaseUrl =
+                process.env.BACKUPDRILL_TARGET_DATABASE_URL?.trim() ||
+                    (await promptSecret("Target database connection string (BACKUPDRILL_TARGET_DATABASE_URL)"));
+        }
+        let targetServiceRoleKey;
+        if (opts.targetSupabaseUrl) {
+            targetServiceRoleKey =
+                process.env.BACKUPDRILL_TARGET_SERVICE_ROLE_KEY?.trim() ||
+                    (await promptSecret("Target service-role key (BACKUPDRILL_TARGET_SERVICE_ROLE_KEY)"));
+        }
         const result = await runRestore(config, {
-            targetDatabaseUrl: opts.targetDatabaseUrl,
+            targetDatabaseUrl,
+            targetSupabaseUrl: opts.targetSupabaseUrl,
+            targetServiceRoleKey,
+            confirmTarget: opts.confirmTarget,
+            dryRun: opts.dryRun,
+            acknowledgeUnverifiedSource: opts.acknowledgeUnverifiedSource,
             storageDir: opts.storageDir,
             snapshot: opts.snapshot,
         });
-        log.ok(`Restore complete — snapshot ${result.snapshot}: ` +
+        // stdout = 机器可读通道(人读日志全在 stderr):完整结构化结果供脚本/报告消费
+        console.log(JSON.stringify(result));
+        if (result.dryRun)
+            return; // 预检自行打印结论;走到这里 = 零 blocker
+        const failedChecks = (result.databaseChecks ?? []).filter((c) => !c.pass);
+        const rec = result.storageSummary?.reconcile;
+        const storageProblems = (result.storageSummary?.filesFailed.length ?? 0) +
+            (result.storageSummary?.checksumSample.mismatched.length ?? 0) +
+            // 属性漂移进裁决(评审第 10 轮):访问行为与快照不一致不算干净恢复
+            (result.storageSummary?.bucketAttrDrift.length ?? 0) +
+            (rec ? rec.missing.length + rec.sizeMismatched.length + rec.extras : 0);
+        const summary = `snapshot ${result.snapshot}: ` +
             `database ${result.restoredToDatabase ? "restored" : "skipped"}, ` +
-            `${result.storageFilesWritten} Storage files written` +
-            (result.storageDir ? ` to ${result.storageDir}` : ""));
+            `${result.storageFilesWritten} Storage files ${result.storageSummary ? "uploaded to target" : "written"}` +
+            (result.storageDir ? ` to ${result.storageDir}` : "");
+        if (failedChecks.length || storageProblems) {
+            log.error(`Restore finished with issues (${failedChecks.length} failed check(s), ` +
+                `${storageProblems} storage problem(s)) — ${summary}`);
+            process.exitCode = 1;
+        }
+        else {
+            log.ok(`Restore complete — ${summary}`);
+        }
     }
     catch (error) {
         log.error(error.message);

package/dist/lib.d.ts

@@ -6,7 +6,7 @@ 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 { ExtensionInfo, Manifest, StorageFile, TableStat } from "./manifest.js";
+export type { BucketAttrs, ExtensionInfo, 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/manifest.d.ts

@@ -7,6 +7,23 @@ export interface TableStat {
     schema: string;
     name: string;
     estimatedRows: number;
+    primaryKeyColumns?: string[];
+    exactRows?: number;
+    sampleHash?: string;
+    sampleAlgorithm?: string;
+    freshnessColumn?: string;
+    freshnessValue?: string;
+}
+/**
+ * 源 bucket 的可恢复属性(v2,读自源库 storage.buckets——S3 兼容端点拿不到这些)。
+ * 值为 null = 源端就没设置;字段整体缺失 = 当次备份没捕获到(如 storage schema 无读权限),
+ * 恢复端遇缺失须如实标 "not captured",不得猜测(PRD §5.1.3)。
+ */
+export interface BucketAttrs {
+    name: string;
+    public?: boolean | null;
+    fileSizeLimit?: number | null;
+    allowedMimeTypes?: string[] | null;
 }
 /**
  * 源库安装的非内置扩展(pg_extension,排除必装的 plpgsql)。
@@ -27,14 +44,21 @@ export interface ExtensionInfo {
  *  - 缺失该字段的 manifest = 版本 1(1.0 之前写出的旧快照)
  *  - 读取端遇到**更高**的版本必须明确报错,而不是按旧结构硬解析出错误结果
  *    ——对备份工具来说,"旧程序静默误读新归档"是最不能接受的失败方式。
+ *
+ * 版本史:
+ *  - 1:初始格式。
+ *  - 2(恢复闭环 PRD §5.1):storage 增加 buckets 属性清单(public/大小/MIME 限制),
+ *    files 增加 contentType/cacheControl/metadata 等恢复所需元数据;tables 预留
+ *    验证升级字段(本期不生成)。全部为**可加字段**——v2 读取端兼容 v1 快照。
  */
-export declare const MANIFEST_SCHEMA_VERSION = 1;
+export declare const MANIFEST_SCHEMA_VERSION = 2;
 export interface Manifest {
     schemaVersion?: number;
     tool: "backupdrill-cli";
     toolVersion: string;
     createdAt: string;
     projectName: string;
+    sourceProjectRef?: string;
     database: {
         serverVersion: string;
         pgDumpVersion: string;
@@ -51,6 +75,7 @@ export interface Manifest {
         sha256: string;
     };
     storage: null | {
+        buckets?: BucketAttrs[];
         fileCount: number;
         totalBytes: number;
         files: StorageFile[];
@@ -61,9 +86,15 @@ export interface StorageFile {
     key: string;
     bytes: number;
     sha256: string;
+    contentType?: string;
+    cacheControl?: string;
+    contentEncoding?: string;
+    metadata?: Record<string, unknown>;
+    lastModified?: string;
 }
 /**
  * 解析桶里的 manifest.json,并做**向前兼容**校验:比本程序更新的格式一律拒绝,
  * 明确告诉用户升级,绝不按旧结构硬解析(那会静默产出错误的演练/恢复结果)。
+ * 版本关之后再做结构校验(assertManifestShape)——两类失败要给出不同的处置指引。
  */
 export declare function parseManifest(json: string): Manifest;