backupdrill 2.2.4 → 2.2.5

package/README.md

@@ -31,6 +31,17 @@ npm install -g backupdrill
 npx backupdrill backup
 ```
 
+## Use it from Claude Code or Cursor
+
+The [`plugin/`](plugin/) folder is a plugin for Claude Code and Cursor. It teaches the agent to run `estimate`, `backup`, `drill` and `restore` for you, keeps your keys in a gitignored `.env.backupdrill` that the agent never opens, and always does a dry run before a restore. In Claude Code:
+
+```
+/plugin marketplace add backupdrill/cli
+/plugin install backupdrill@backupdrill
+```
+
+Details are in [plugin/README.md](plugin/README.md).
+
 ## Usage
 
 Configure via **env vars**, a **config file**, or **flags** (precedence: flags > env > file).

package/dist/restore.d.ts

@@ -61,6 +61,12 @@ export declare function assertRequestApplies(manifest: Manifest, wantsDatabase:
  * 这道门要求人把目标身份亲手打一遍。
  */
 export declare function assertConfirmedTarget(confirmTarget: string | undefined, targetDatabaseUrl?: string, targetSupabaseUrl?: string): void;
+/**
+ * 空目标门的拒绝文案。"只重试 Storage"那句只对同时恢复 Storage 的运行有意义:库已写完、
+ * Storage 中途断了,重跑时才会在这道门上被拦。纯数据库恢复(托管恢复只做数据库)带上它,
+ * 用户会以为自己漏了一步,其实只需要换一个空项目。
+ */
+export declare function nonEmptyTargetMessage(schemas: string[], objectCount: number, alsoRestoringStorage: boolean): string;
 /**
  * 把一份快照恢复出来:数据库经统一引擎还原进目标(与演练同一条 pg_restore 路径与
  * 错误分类),恢复后跑同一套表级验证;Storage 提供目标凭据时回传+对账(P0-D),

package/dist/restore.js

@@ -155,6 +155,20 @@ export function assertConfirmedTarget(confirmTarget, targetDatabaseUrl, targetSu
             `(use --dry-run first to preview all checks without writing).`);
     }
 }
+/**
+ * 空目标门的拒绝文案。"只重试 Storage"那句只对同时恢复 Storage 的运行有意义:库已写完、
+ * Storage 中途断了,重跑时才会在这道门上被拦。纯数据库恢复(托管恢复只做数据库)带上它,
+ * 用户会以为自己漏了一步,其实只需要换一个空项目。
+ */
+export function nonEmptyTargetMessage(schemas, objectCount, alsoRestoringStorage) {
+    const message = `target schema(s) ${schemas.join(", ")} contain ${objectCount} existing object(s) — ` +
+        `restore only writes into an empty target. Create a fresh Supabase project ` +
+        `(or empty these schemas) and retry.`;
+    if (!alsoRestoringStorage)
+        return message;
+    return (`${message} If a previous run already restored the database and only Storage was ` +
+        `interrupted, re-run WITHOUT the database target to retry Storage alone.`);
+}
 /**
  * 空目标门(PRD §5.3.3 / 决策 D5):目标 schema 里存在任何用户对象即拒绝写入。
  * "空"的定义来自 R0 spike:不是"schema 不存在"(Supabase 恒有 public),而是
@@ -162,7 +176,7 @@ export function assertConfirmedTarget(confirmTarget, targetDatabaseUrl, targetSu
  * 全部计入:只查关系时,"目标里只有函数"会放行,然后在 pre-data 中途撞冲突,
  * 留下半截目标(评审第 7 轮)。
  */
-async function assertEmptyTarget(targetUrl, schemas) {
+async function assertEmptyTarget(targetUrl, schemas, alsoRestoringStorage) {
     const client = await connectPg(targetUrl);
     try {
         const res = await client.query(`select
@@ -175,11 +189,7 @@ async function assertEmptyTarget(targetUrl, schemas) {
          as n`, [schemas]);
         const objectCount = Number(res.rows[0].n);
         if (objectCount > 0) {
-            throw new Error(`target schema(s) ${schemas.join(", ")} contain ${objectCount} existing object(s) — ` +
-                `restore only writes into an empty target. Create a fresh Supabase project ` +
-                `(or empty these schemas) and retry. If a previous run already restored the ` +
-                `database and only Storage was interrupted, re-run WITHOUT the database target ` +
-                `to retry Storage alone.`);
+            throw new Error(nonEmptyTargetMessage(schemas, objectCount, alsoRestoringStorage));
         }
     }
     finally {
@@ -190,7 +200,7 @@ async function assertEmptyTarget(targetUrl, schemas) {
  * dry-run 只读预检(PRD §5.3.2):零写入,把正式执行会撞的墙全部提前撞一遍。
  * 逐项打印,任何 blocker 汇总后抛出(退出码非零 = "现在执行不会成功")。
  */
-async function dryRunPreflight(config, manifest, targetUrl, storageTarget) {
+async function dryRunPreflight(config, manifest, targetUrl, storageTarget, alsoRestoringStorage) {
     const blockers = [];
     const db = manifest.database;
     const mb = (n) => (n / 1024 / 1024).toFixed(1);
@@ -221,7 +231,7 @@ async function dryRunPreflight(config, manifest, targetUrl, storageTarget) {
             log.ok("target identity: distinct from source");
         }
         try {
-            await assertEmptyTarget(targetUrl, db.schemas);
+            await assertEmptyTarget(targetUrl, db.schemas, alsoRestoringStorage);
             log.ok(`target schemas (${db.schemas.join(", ")}) are empty`);
         }
         catch (error) {
@@ -376,10 +386,13 @@ export async function runRestore(config, opts) {
         storageFilesWritten: 0,
     };
     assertRequestApplies(manifest, !!opts.targetDatabaseUrl, !!storageTarget);
+    // 这次运行会不会碰 Storage(回传到目标,或下载到本地)。只有会碰时,空目标门才该
+    // 提示"库已恢复、只重试 Storage";skipStorage 的纯数据库运行(托管恢复)不该看到这句。
+    const alsoRestoringStorage = !!manifest.storage && !opts.skipStorage;
     // dry-run:只读预检后直接返回,零写入(PRD §5.3.2)
     if (opts.dryRun) {
         log.step(`Dry run for snapshot ${snapshot} — nothing will be written`);
-        await dryRunPreflight(config, manifest, opts.targetDatabaseUrl, storageTarget);
+        await dryRunPreflight(config, manifest, opts.targetDatabaseUrl, storageTarget, alsoRestoringStorage);
         result.dryRun = true;
         return result;
     }
@@ -408,7 +421,7 @@ export async function runRestore(config, opts) {
                     "at a fresh Supabase project.");
             }
             log.step("Checking target is empty…");
-            await assertEmptyTarget(targetUrl, manifest.database.schemas);
+            await assertEmptyTarget(targetUrl, manifest.database.schemas, alsoRestoringStorage);
             // 版本预检不只属于 dry-run:跳过 dry-run 直接执行时,目标比源旧照样会
             // 半途炸掉或部分恢复(评审第 8 轮)——写入前必须拦住
             const versionClient = await connectPg(targetUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backupdrill",
-  "version": "2.2.4",
+  "version": "2.2.5",
   "description": "Open-source CLI to back up a Supabase project — Postgres database and Storage files — to your own S3/R2/B2 bucket, with a checksummed manifest.",
   "type": "module",
   "bin": {