pi-webdav-backup 1.0.1 → 1.0.2

package/README.md

@@ -88,6 +88,8 @@ node ~/.pi/agent/extensions/webdav-backup/cli.mjs restore --list
 node ~/.pi/agent/extensions/webdav-backup/cli.mjs restore --file pi-agent-20260924-120000.tar.gz --to D:\restore
 ```
 
+输出末行固定是 JSON 汇总（`--json` 时只输出该行，人类模式则前面还有日志行），脚本可直接解析；退出码 0 成功 / 1 失败。
+
 ---
 
 ## 密钥不明文落盘
@@ -326,7 +328,7 @@ npm test
 node extensions/webdav-backup/verify-load.mjs
 ```
 
-6 个测试文件、284 项断言，用内置的内存 WebDAV 服务端做真实 HTTP 往返：
+8 个测试文件、310 项断言，用内置的内存 WebDAV 服务端做真实 HTTP 往返：
 
 | 文件 | 覆盖 |
 |---|---|
@@ -334,6 +336,8 @@ node extensions/webdav-backup/verify-load.mjs
 | `test-cli.mjs` | 真实子进程调用 CLI、退出备份、DPAPI 端到端、doctor、日志、状态 |
 | `test-restore.mjs` | 归档/加密/快照恢复、目录穿越防护 |
 | `test-redact.mjs` | 脱敏（含「字段名无关但值是密钥」的回归用例） |
+| `test-json.mjs` | CLI 输出 JSON 解析容错（回归：空输出曾抛裸 JSON 错误吞掉 stderr） |
+| `test-empty-cmd.mjs` | 空参数/子命令解析、输出契约（回归：`/backup` 不带参数曾报「未知命令：」、完成提醒拿不到 JSON 汇总） |
 | `test-secrets.mjs` | dpapi/$ENV/file/!命令/plain 各分支、明文告警、三种迁移方式 |
 | `test-auth-migrate.mjs` | `auth.json` 明文密钥审计与迁移（迁移前自动备份、可回滚） |
 

package/extensions/webdav-backup/args.mjs

@@ -0,0 +1,27 @@
+/**
+ * args.mjs — 子命令解析（扩展入口 webdav-backup.ts 与 cli.mjs 共用）
+ *
+ * 背景：早期写法 `tokens[0] ?? fallback` 在 tokens[0] 为空串时不会兜底
+ * （`??` 只认 null/undefined，空串是"有值"），于是 `/backup` 不带参数时
+ * `"".trim().split(/\s+/)` 得到 `[""]`，空串被当成命令传给 CLI，
+ * 最终报出冒号后为空的「未知命令：」。这里统一做空 token 容错。
+ */
+
+/**
+ * 从 token 列表里取第一个非空 token（小写）作为子命令；
+ * 全是空 token（或列表为空/缺失）时返回 fallback。
+ *
+ * 保持「第一个参数就是命令」的既有语义：flag（`-` 开头）不当作空 token
+ * 跳过，它照样会被当成命令并得到明确的「未知命令：xxx」报错。
+ *
+ * @param {readonly (string | null | undefined)[] | null | undefined} tokens
+ * @param {string} fallback
+ * @returns {string}
+ */
+export function pickCommand(tokens, fallback) {
+  for (const t of tokens ?? []) {
+    const s = String(t ?? "").trim();
+    if (s) return s.toLowerCase();
+  }
+  return fallback;
+}

package/extensions/webdav-backup/cli.mjs

@@ -18,7 +18,8 @@
  *   node cli.mjs install-cron [--time HH:MM]   安装 Windows 计划任务（每日备份）
  *   node cli.mjs uninstall-cron           移除计划任务
  *
- * 输出人类可读文本或 JSON（--json），退出码 0 成功 / 1 失败。
+ * 输出人类可读文本，末行固定是 JSON 汇总；加 --json 则只输出该汇总行。
+ * 退出码 0 成功 / 1 失败。
  *   --value 优先，其次读 stdin（避免密钥出现在进程列表里）
  */
 
@@ -36,9 +37,11 @@ import {
   resolveSecret,
   isPlaintextSecret,
 } from "./secrets.mjs";
+import { pickCommand } from "./args.mjs";
 
 const args = process.argv.slice(2);
-const cmd = (args[0] ?? "backup").toLowerCase();
+// 注意：不能写 `args[0] ?? "backup"`——空串会绕过 ?? 兜底（见 args.mjs）
+const cmd = pickCommand(args, "backup");
 const has = (f) => args.includes(f);
 const val = (f, d = null) => {
   const i = args.indexOf(f);
@@ -58,7 +61,9 @@ function logTo(line) {
 }
 
 function finish(payload, code) {
-  if (asJson) process.stdout.write(`${JSON.stringify(payload)}\n`);
+  // JSON 汇总固定作为最后一行输出：扩展入口按「最后一行 JSON」解析结果
+  // 并渲染完成提醒；--json 模式下前面没有日志行，只有这一行。
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
   process.exit(code ?? (payload.ok ? 0 : 1));
 }
 

package/extensions/webdav-backup/json.mjs

@@ -0,0 +1,33 @@
+/**
+ * json.mjs — 安全解析子进程 CLI 输出的 JSON
+ *
+ * 背景：早期实现直接 JSON.parse(输出最后一行)，CLI 一旦 spawn 失败
+ * 或输出为空，就抛裸的 "Unexpected end of JSON input"，
+ * 把真正有用的错误（stderr）吞掉。这里做统一容错。
+ */
+
+/**
+ * 解析 CLI 输出中最后一个非空行的 JSON。
+ * 解析失败时抛出带【真实原因】的错误（stderr 优先），
+ * 绝不抛裸的 JSON 语法错误。
+ *
+ * @param {{stdout?: string, stderr?: string, code?: number|null}} result
+ * @returns {any} 解析成功的 JSON 值
+ */
+export function parseCliJson(result) {
+  const { stdout = "", stderr = "", code = null } = result ?? {};
+  const line = String(stdout)
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .pop();
+  if (line) {
+    try {
+      return JSON.parse(line);
+    } catch {
+      /* 继续走下面的友好错误 */
+    }
+  }
+  const hint = String(stderr).trim() || String(stdout).trim();
+  throw new Error(hint || `命令失败（退出码 ${code}）`);
+}

package/extensions/webdav-backup/test-empty-cmd.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * test-empty-cmd.mjs — 空参数 / 子命令解析回归测试
+ *
+ * 事故回归：`/backup` 不带参数时 `"".trim().split(/\s+/)[0]` 是 `""`
+ * （不是 undefined），`?? "run"` 兜底失效，空串被当命令传给 CLI，
+ * 报出「未知命令：」（冒号后为空）。这里锁住三层防御：
+ *   1. pickCommand() 的单元语义（ts 入口与 cli.mjs 共用）
+ *   2. 源码不变量：两个入口都必须走 pickCommand，禁止退回 ?? 写法
+ *   3. cli.mjs 真实子进程：空 token 默认 backup / 被跳过 / 真未知命令仍报错
+ *
+ * 用法：node test-empty-cmd.mjs
+ */
+
+import { spawn } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { pickCommand } from "./args.mjs";
+import { startDavServer } from "./dav-mock.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const CLI = join(here, "cli.mjs");
+
+let pass = 0;
+let fail = 0;
+const check = (name, cond, detail = "") => {
+  if (cond) {
+    pass++;
+    console.log(`  ✅ ${name}`);
+  } else {
+    fail++;
+    console.log(`  ❌ ${name}${detail ? ` — ${detail}` : ""}`);
+  }
+};
+
+function runCli(args, env) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [CLI, ...args], {
+      env: { ...process.env, ...env },
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d.toString("utf8")));
+    child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+const lastJson = (out) => {
+  const line = out.trim().split("\n").filter((l) => l.trim().startsWith("{")).pop();
+  try {
+    return JSON.parse(line ?? "{}");
+  } catch {
+    return {};
+  }
+};
+
+async function main() {
+  console.log("pi WebDAV 备份 — 空参数解析回归测试\n");
+
+  // ── 1. pickCommand 单元语义
+  check('pickCommand(["run"], "backup") → "run"', pickCommand(["run"], "backup") === "run");
+  check('pickCommand([""], "run") → 兜底 "run"（事故场景）', pickCommand([""], "run") === "run");
+  check('pickCommand([], "run") → 兜底', pickCommand([], "run") === "run");
+  check('pickCommand(null, "backup") → 兜底', pickCommand(null, "backup") === "backup");
+  check('pickCommand(["", "", ""], "run") → 兜底', pickCommand(["", "", ""], "run") === "run");
+  check('pickCommand(["", "check", "--json"], "run") → "check"', pickCommand(["", "check", "--json"], "run") === "check");
+  check('pickCommand(["", "backup", "--reason", "manual"], "run") → "backup"', pickCommand(["", "backup", "--reason", "manual"], "run") === "backup");
+  check('pickCommand(["  Run  "], "run") → "run"（trim + 小写）', pickCommand(["  Run  "], "run") === "run");
+
+  // ── 2. 源码不变量：两个入口都必须走 pickCommand（防退回 ?? 空串绕过的写法）
+  // 反模式断言只查代码行：注释里引用的反例不算
+  const codeOnly = (src) =>
+    src
+      .split("\n")
+      .filter((l) => !l.trim().startsWith("//"))
+      .join("\n");
+  const tsSrc = readFileSync(join(here, "..", "webdav-backup.ts"), "utf8");
+  const cliSrc = readFileSync(CLI, "utf8");
+  check("入口 webdav-backup.ts 用 pickCommand 解析子命令", tsSrc.includes("pickCommand(args.trim()"));
+  check('入口不再有 `?? "run"` 兜底写法', !codeOnly(tsSrc).includes('?? "run"'));
+  check('cli.mjs 用 pickCommand 解析命令', cliSrc.includes('pickCommand(args, "backup")'));
+  check('cli.mjs 不再有 `args[0] ?? "backup"` 写法', !codeOnly(cliSrc).includes('args[0] ?? "backup"'));
+
+  // ── 3. cli.mjs 真实子进程行为（内存 WebDAV + 临时 agentDir）
+  const dav = await startDavServer();
+  const baseUrl = `http://127.0.0.1:${dav.port}/dav`;
+  dav.dirs.add("/dav");
+
+  const agentDir = mkdtempSync(join(tmpdir(), "pi-emptycmd-test-"));
+  mkdirSync(join(agentDir, "extensions"), { recursive: true });
+  writeFileSync(join(agentDir, "extensions", "a.ts"), "export default () => {};\n");
+  writeFileSync(join(agentDir, "settings.json"), '{"theme":"dark"}\n');
+  writeFileSync(
+    join(agentDir, "webdav-backup.json"),
+    JSON.stringify({
+      enabled: true,
+      remote: { url: baseUrl, username: "user", password: "pass", remoteDir: "bk", remoteName: "pi" },
+      scope: ["."],
+      includeSessions: false,
+      encrypt: false,
+      keepVersions: 3,
+    }),
+  );
+  const env = { PI_CODING_AGENT_DIR: agentDir };
+
+  // 3a. 事故路径：命令 token 为空串 → 默认 backup，绝不报「未知命令：」
+  const empty = await runCli([""], env);
+  check(
+    'cli.mjs [""] 默认执行 backup（事故路径回归）',
+    empty.code === 0 && empty.stdout.includes("完成"),
+    `code=${empty.code} out=${empty.stdout.trim()} err=${empty.stderr.trim()}`,
+  );
+  check(
+    "空命令不再出现「未知命令：」",
+    !empty.stdout.includes("未知命令"),
+    empty.stdout.trim(),
+  );
+
+  // 3b. 空 token 被跳过，其后的真命令正常执行
+  const chk = await runCli(["", "check", "--json"], env);
+  const chkJson = lastJson(chk.stdout);
+  check(
+    'cli.mjs ["", "check"] 跳过空 token 执行 check',
+    chk.code === 0 && chkJson.ok === true,
+    `code=${chk.code} out=${chk.stdout.trim()}`,
+  );
+
+  // 3c. 真正的未知命令仍要明确报错（错误里带命令名）
+  const bad = await runCli(["no-such-cmd", "--json"], env);
+  const badJson = lastJson(bad.stdout);
+  check(
+    "未知命令仍报错且带命令名",
+    bad.code === 1 && badJson.ok === false && String(badJson.error).includes("no-such-cmd"),
+    JSON.stringify(badJson),
+  );
+
+  // 3d. 输出契约：人类模式末行必须是 JSON 汇总（/backup 的「备份完成 ✅」提醒靠它）
+  const sum = lastJson(empty.stdout);
+  check(
+    "人类模式末行是 JSON 汇总（ok + remotePath + files）",
+    sum.ok === true && typeof sum.remotePath === "string" && Number(sum.files) >= 1,
+    empty.stdout.trim().split("\n").pop(),
+  );
+
+  // 3e. 失败时汇总必须带非空 error（否则前端只能弹「失败：」空提醒）
+  const noConfDir = mkdtempSync(join(tmpdir(), "pi-emptycmd-noconf-"));
+  const noConf = await runCli(["backup"], { PI_CODING_AGENT_DIR: noConfDir });
+  const noConfJson = lastJson(noConf.stdout);
+  check(
+    "失败时 JSON 汇总带非空 error",
+    noConf.code === 1 && noConfJson.ok === false && Boolean(String(noConfJson.error).trim()),
+    JSON.stringify(noConfJson),
+  );
+
+  console.log(`\n结果：${pass} 通过，${fail} 失败`);
+  process.exit(fail ? 1 : 0);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/extensions/webdav-backup/test-json.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * test-json.mjs — CLI 输出 JSON 解析的容错性
+ *
+ * 回归背景：空输出曾抛 "Unexpected end of JSON input"，
+ * 在 pi 里显示为 Extension "command:backup" error，真实错误被吞掉。
+ */
+import { parseCliJson } from "./json.mjs";
+
+let pass = 0;
+let fail = 0;
+const check = (n, c, d = "") => {
+  if (c) {
+    pass++;
+    console.log(`  ✅ ${n}`);
+  } else {
+    fail++;
+    console.log(`  ❌ ${n}${d ? ` — ${d}` : ""}`);
+  }
+};
+
+console.log("pi WebDAV 备份 — CLI JSON 解析容错测试\n");
+
+// 正常：取最后一个非空行解析
+const r1 = parseCliJson({ stdout: '日志行\n{"ok":true,"files":3}\n', stderr: "", code: 0 });
+check("取最后一个非空行解析", r1 && r1.ok === true && r1.files === 3);
+
+const r2 = parseCliJson({ stdout: '{"a":{"b":1}}' });
+check("单行 JSON 也正常", r2 && r2.a && r2.a.b === 1);
+
+// 回归：空输出 + stderr → 抛出含真实原因的错误
+let thrown = null;
+try {
+  parseCliJson({ stdout: "", stderr: "Cannot find module cli.mjs", code: 1 });
+} catch (e) {
+  thrown = e;
+}
+check(
+  "空输出抛出含 stderr 的错误（回归）",
+  thrown !== null &&
+    /Cannot find module/.test(thrown.message) &&
+    !/Unexpected end of JSON/.test(thrown.message),
+  thrown?.message,
+);
+
+thrown = null;
+try {
+  parseCliJson({ stdout: "\n  \n", stderr: "boom", code: 2 });
+} catch (e) {
+  thrown = e;
+}
+check("纯空白输出同样容错", thrown !== null && /boom/.test(thrown.message), thrown?.message);
+
+thrown = null;
+try {
+  parseCliJson({ stdout: "", stderr: "", code: 7 });
+} catch (e) {
+  thrown = e;
+}
+check("无输出无 stderr 时提示退出码", thrown !== null && /退出码 7/.test(thrown.message), thrown?.message);
+
+// 非 JSON 文本 → 友好错误，不抛裸 JSON 语法错
+thrown = null;
+try {
+  parseCliJson({ stdout: "连接失败：401", stderr: "", code: 1 });
+} catch (e) {
+  thrown = e;
+}
+check(
+  "非 JSON 输出不抛裸语法错误",
+  thrown !== null &&
+    !/Unexpected end of JSON/.test(thrown.message) &&
+    /连接失败/.test(thrown.message),
+  thrown?.message,
+);
+
+// 边界
+thrown = null;
+try {
+  parseCliJson(null);
+} catch (e) {
+  thrown = e;
+}
+check("null 输入不崩溃", thrown !== null);
+
+check("JSON 标量也可返回", parseCliJson({ stdout: "42" }) === 42);
+
+console.log(`\n结果：${pass} 通过，${fail} 失败`);
+process.exit(fail ? 1 : 0);

package/extensions/webdav-backup.ts

@@ -33,6 +33,8 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseCliJson } from "./webdav-backup/json.mjs";
+import { pickCommand } from "./webdav-backup/args.mjs";
 
 // bundler/jiti 下 import.meta.url 可能不可用，做兜底
 const EXT_DIR = (() => {
@@ -104,7 +106,9 @@ function runCli(
       const text = d.toString("utf8");
       stdout += text;
       for (const line of text.split("\n")) {
-        if (line.trim()) ctx.ui.setStatus("webdav-backup", line.slice(0, 90));
+        const t = line.trim();
+        // 末行 JSON 汇总是给程序读的，不刷到状态栏
+        if (t && !t.startsWith("{")) ctx.ui.setStatus("webdav-backup", line.slice(0, 90));
       }
     });
     child.stderr?.on("data", (d: Buffer) => {
@@ -210,7 +214,8 @@ export default function webdavBackupExtension(pi: ExtensionAPI) {
       return f.length ? f.map((s) => ({ value: s, label: s })) : null;
     },
     handler: async (args, ctx) => {
-      const sub = (args.trim().split(/\s+/)[0] ?? "run").toLowerCase();
+      // 注意：不能写 `split(/\s+/)[0] ?? "run"`——空串会绕过 ?? 兜底（见 args.mjs）
+      const sub = pickCommand(args.trim().split(/\s+/), "run");
 
       if (sub === "help") {
         ctx.ui.notify(
@@ -245,8 +250,7 @@ export default function webdavBackupExtension(pi: ExtensionAPI) {
       // ── 体检：报告密钥来源与明文告警
       if (sub === "verify") {
         const r = await runCli(["doctor", "--json"], ctx, { timeoutMs: 60_000 });
-        const line = r.stdout.trim().split("\n").pop() ?? "{}";
-        const d = JSON.parse(line) as {
+        const d = parseCliJson(r) as {
           ok?: boolean;
           url?: string;
           username?: string;
@@ -279,8 +283,7 @@ export default function webdavBackupExtension(pi: ExtensionAPI) {
 
         if (action === "list") {
           const r = await runCli(["list-secrets", "--json"], ctx, { timeoutMs: 60_000 });
-          const line = r.stdout.trim().split("\n").pop() ?? "{}";
-          const d = JSON.parse(line) as {
+          const d = parseCliJson(r) as {
             available?: boolean;
             secrets?: { name: string; updatedAt?: string }[];
           };
@@ -399,8 +402,7 @@ export default function webdavBackupExtension(pi: ExtensionAPI) {
       if (sub === "restore") {
         const autoYes = /(^|\s)(-y|--yes)(\s|$)/.test(args);
         const listRun = await runCli(["restore", "--list", "--json"], ctx, { timeoutMs: 60_000 });
-        const raw = listRun.stdout.trim().split("\n").pop() ?? "{}";
-        const listing = JSON.parse(raw) as {
+        const listing = parseCliJson(listRun) as {
           archives?: { name: string; size: number }[];
           snapshot?: { name: string; fileCount: number } | null;
         };
@@ -441,7 +443,7 @@ export default function webdavBackupExtension(pi: ExtensionAPI) {
         if (rr.ok && info.ok) {
           ctx.ui.notify(`恢复完成：${info.files} 个文件 → ${info.dest}`, "info");
         } else {
-          ctx.ui.notify(`恢复失败：${info.error ?? rr.stderr.trim()}`, "error");
+          ctx.ui.notify(`恢复失败：${info.error || rr.stderr.trim() || `退出码 ${rr.code}`}`, "error");
         }
         return;
       }
@@ -451,8 +453,7 @@ export default function webdavBackupExtension(pi: ExtensionAPI) {
 
       // status/list/check 用 JSON 结果做友好展示
       if (sub === "status") {
-        const line = r.stdout.trim().split("\n").pop() ?? "{}";
-        const parsed = JSON.parse(line) as { state?: BackupState };
+        const parsed = parseCliJson(r) as { state?: BackupState };
         ctx.ui.notify(
           parsed.state?.lastBackupAt
             ? `上次备份：${new Date(parsed.state.lastBackupAt).toLocaleString()}（${parsed.state.lastReason ?? "?"}）`
@@ -463,8 +464,7 @@ export default function webdavBackupExtension(pi: ExtensionAPI) {
       }
 
       if (sub === "check" || sub === "list") {
-        const line = r.stdout.trim().split("\n").pop() ?? "{}";
-        const parsed = JSON.parse(line) as {
+        const parsed = parseCliJson(r) as {
           ok?: boolean;
           error?: string;
           status?: number;
@@ -526,7 +526,7 @@ export default function webdavBackupExtension(pi: ExtensionAPI) {
           ctx.ui.notify("完成", "info");
         }
       } else {
-        ctx.ui.notify(`失败：${summary.error ?? r.stderr.trim() ?? `退出码 ${r.code}`}`, "error");
+        ctx.ui.notify(`失败：${summary.error || r.stderr.trim() || `退出码 ${r.code}`}`, "error");
       }
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-webdav-backup",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "pi 配置自动备份到 WebDAV（坚果云 / Nextcloud / 群晖 / 自建）：归档与快照两种模式、AES-256-GCM 加密、DPAPI 密钥管理、敏感字段脱敏、退出自动备份与每日定时备份。",
   "keywords": [
     "pi-package",