chainlesschain 0.162.14 → 0.162.16

package/src/commands/__tests__/hub-wechat.test.js

@@ -41,19 +41,27 @@ function fakeHub(overrides = {}) {
         ...overrides.register,
       };
     }),
-    listWechatAccounts: vi.fn(() => overrides.list || [
-      {
-        uin: "1234567890",
-        dbPath: "/tmp/EnMicroMsg.db",
-        hasWechatDataPath: true,
-        chosenKeyProvider: "md5",
-        registeredAt: 1716280000000,
-        lastSyncAt: null,
-      },
-    ]),
+    listWechatAccounts: vi.fn(
+      () =>
+        overrides.list || [
+          {
+            uin: "1234567890",
+            dbPath: "/tmp/EnMicroMsg.db",
+            hasWechatDataPath: true,
+            chosenKeyProvider: "md5",
+            registeredAt: 1716280000000,
+            lastSyncAt: null,
+          },
+        ],
+    ),
     unregisterWechatAdapter: vi.fn(async (uin) => {
       if (!uin) return { ok: false, reason: "UIN_REQUIRED" };
-      return { ok: true, removed: uin === "1234567890", uin, ...overrides.unregister };
+      return {
+        ok: true,
+        removed: uin === "1234567890",
+        uin,
+        ...overrides.unregister,
+      };
     }),
   };
 }
@@ -106,9 +114,21 @@ describe("cc hub wechat register", () => {
       _internal.cmdWechatRegister({ _getHub: async () => hub, json: true }),
     ).rejects.toThrow(/process\.exit/);
     const allOut =
-      logSpy.mock.calls.map((c) => c.map((p) => (typeof p === "string" ? p : JSON.stringify(p))).join(" ")).join("\n") +
+      logSpy.mock.calls
+        .map((c) =>
+          c
+            .map((p) => (typeof p === "string" ? p : JSON.stringify(p)))
+            .join(" "),
+        )
+        .join("\n") +
       "\n" +
-      errSpy.mock.calls.map((c) => c.map((p) => (typeof p === "string" ? p : JSON.stringify(p))).join(" ")).join("\n");
+      errSpy.mock.calls
+        .map((c) =>
+          c
+            .map((p) => (typeof p === "string" ? p : JSON.stringify(p)))
+            .join(" "),
+        )
+        .join("\n");
     expect(allOut).toMatch(/--uin|uin/i);
   });
 
@@ -217,7 +237,9 @@ describe("cc hub wechat list", () => {
 describe("cc hub wechat unregister", () => {
   it("calls hub with uin + reports removed", async () => {
     const hub = fakeHub();
-    await _internal.cmdWechatUnregister("1234567890", { _getHub: async () => hub });
+    await _internal.cmdWechatUnregister("1234567890", {
+      _getHub: async () => hub,
+    });
     expect(hub.unregisterWechatAdapter).toHaveBeenCalledWith("1234567890");
     const out = logSpy.mock.calls.map((c) => c.join(" ")).join("\n");
     expect(out).toMatch(/removed wechat account.*1234567890/);
@@ -238,6 +260,155 @@ describe("cc hub wechat unregister", () => {
     });
     const out = logSpy.mock.calls.map((c) => c[0]).join("\n");
     const parsed = JSON.parse(out);
-    expect(parsed).toEqual(expect.objectContaining({ ok: true, removed: true, uin: "1234567890" }));
+    expect(parsed).toEqual(
+      expect.objectContaining({ ok: true, removed: true, uin: "1234567890" }),
+    );
+  });
+});
+
+// ─── Phase 12.9 — `cc hub wechat doctor` ──────────────────────────────
+
+describe("interpretWechatProbe (pure)", () => {
+  const { interpretWechatProbe } = _internal;
+
+  it("device unreachable → blocked + adb hint", () => {
+    const r = interpretWechatProbe({
+      device: { reachable: false },
+      wechat: {},
+      root: {},
+      frida: {},
+    });
+    expect(r.readiness).toBe("blocked");
+    expect(r.blockers.join(" ")).toMatch(/adb/);
+    expect(r.nextSteps.join(" ")).toMatch(/adb devices/);
+  });
+
+  it("WeChat not installed → blocked + install hint", () => {
+    const r = interpretWechatProbe({
+      device: { reachable: true },
+      wechat: { installed: false },
+      root: {},
+      frida: {},
+    });
+    expect(r.readiness).toBe("blocked");
+    expect(r.blockers.join(" ")).toMatch(/com\.tencent\.mm/);
+  });
+
+  it("WeChat < 8 + md5 path → ready with adb pull instructions", () => {
+    const r = interpretWechatProbe({
+      device: { reachable: true },
+      wechat: { installed: true, majorVersion: 7, versionName: "7.0.22" },
+      root: { detected: false },
+      frida: {},
+      suggestedKeyProvider: "md5",
+    });
+    expect(r.readiness).toBe("ready");
+    expect(r.nextSteps.some((s) => /adb pull/.test(s))).toBe(true);
+    expect(r.nextSteps.some((s) => /cc hub wechat register/.test(s))).toBe(
+      true,
+    );
+    // non-root warning when MD5 path lacks root (backup subset only)
+    expect(r.warnings.some((w) => /非 root|backup 子集/.test(w))).toBe(true);
+  });
+
+  it("WeChat ≥ 8 + no root → blocked with root requirement", () => {
+    const r = interpretWechatProbe({
+      device: { reachable: true },
+      wechat: { installed: true, majorVersion: 8, versionName: "8.0.45" },
+      root: { detected: false },
+      frida: { serverRunning: false },
+      suggestedKeyProvider: "frida",
+    });
+    expect(r.readiness).toBe("blocked");
+    expect(r.blockers.join(" ")).toMatch(/root/);
+    expect(r.nextSteps.join(" ")).toMatch(/Magisk/);
+  });
+
+  it("WeChat ≥ 8 + root + no frida → partial with setup pointer", () => {
+    const r = interpretWechatProbe({
+      device: { reachable: true },
+      wechat: { installed: true, majorVersion: 8, versionName: "8.0.45" },
+      root: { detected: true },
+      frida: { serverRunning: false },
+      suggestedKeyProvider: "frida",
+    });
+    expect(r.readiness).toBe("partial");
+    expect(r.blockers.join(" ")).toMatch(/Frida server/i);
+    expect(r.nextSteps.join(" ")).toMatch(/Frida_Setup/);
+  });
+
+  it("WeChat ≥ 8 + root + frida running → ready", () => {
+    const r = interpretWechatProbe({
+      device: { reachable: true },
+      wechat: { installed: true, majorVersion: 8, versionName: "8.0.45" },
+      root: { detected: true },
+      frida: { serverRunning: true, port: 27042 },
+      suggestedKeyProvider: "frida",
+    });
+    expect(r.readiness).toBe("ready");
+    expect(r.nextSteps.some((s) => /register/.test(s))).toBe(true);
+    expect(r.nextSteps.some((s) => /前台运行/.test(s))).toBe(true);
+  });
+
+  it("env-probe judges unsupported → blocked with reasons", () => {
+    const r = interpretWechatProbe({
+      device: { reachable: true },
+      wechat: { installed: true, majorVersion: 8, versionName: "8.0.50" },
+      root: { detected: true },
+      frida: { serverRunning: true },
+      suggestedKeyProvider: "unsupported",
+      reasons: [
+        "MMKV-only storage on this build — neither MD5 nor Frida path works",
+      ],
+    });
+    expect(r.readiness).toBe("blocked");
+    expect(r.blockers.join(" ")).toMatch(/MMKV-only/);
+  });
+});
+
+describe("cc hub wechat doctor", () => {
+  it("--json includes probe + doctor.readiness/blockers/nextSteps", async () => {
+    const hub = fakeHub();
+    await _internal.cmdWechatDoctor({ _getHub: async () => hub, json: true });
+    const out = logSpy.mock.calls.map((c) => c[0]).join("\n");
+    const parsed = JSON.parse(out);
+    expect(parsed.probe).toEqual(
+      expect.objectContaining({ suggestedKeyProvider: "md5" }),
+    );
+    expect(parsed.doctor).toEqual(
+      expect.objectContaining({
+        readiness: "ready",
+        nextSteps: expect.any(Array),
+      }),
+    );
+  });
+
+  it("human-readable surfaces trap table reference + telemetry capture cmd", async () => {
+    const hub = fakeHub();
+    await _internal.cmdWechatDoctor({ _getHub: async () => hub });
+    const out = logSpy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/Doctor:/);
+    expect(out).toMatch(/READY|PARTIAL|BLOCKED/);
+    expect(out).toMatch(/fridaTelemetry/);
+    expect(out).toMatch(/trap table|§5\.1|Runbook/i);
+  });
+
+  it("device unreachable: omits telemetry capture section (no point if blocked)", async () => {
+    const hub = fakeHub({
+      probe: {
+        ok: false,
+        suggestedKeyProvider: "unsupported",
+        device: { reachable: false },
+        wechat: {},
+        root: {},
+        frida: {},
+        reasons: [],
+        warnings: [],
+      },
+    });
+    await _internal.cmdWechatDoctor({ _getHub: async () => hub });
+    const out = logSpy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/BLOCKED/);
+    expect(out).not.toMatch(/fridaTelemetry/);
   });
 });

package/src/commands/hub.js

@@ -43,9 +43,16 @@ async function cmdAsk(question, options) {
   try {
     const hub = await getHub();
     if (!hub.engine) throw new Error("Analysis engine unavailable");
+    // 推文 §三道锁第二把 "默认不许问云端" — acceptNonLocal 默认 false (拒云)。
+    // 优先 --accept-non-local CLI 旗，其次 env CC_HUB_ALLOW_NON_LOCAL (Android UI
+    // 拒云 toggle 通过 LocalCcRunner.askQuestion 透传)，否则维持 false。
+    const envAllow =
+      process.env.CC_HUB_ALLOW_NON_LOCAL === "1" ||
+      process.env.CC_HUB_ALLOW_NON_LOCAL === "true";
+    const acceptNonLocal = !!options.acceptNonLocal || envAllow;
     const result = await hub.engine.ask(question, {
       useRag: options.useRag !== false,
-      acceptNonLocal: !!options.acceptNonLocal,
+      acceptNonLocal,
     });
     if (spinner) spinner.stop();
     if (options.json) {
@@ -306,6 +313,140 @@ async function cmdRegisterMock(options) {
   }
 }
 
+// ─── event-detail ────────────────────────────────────────────────────
+
+/**
+ * `cc hub event-detail <eventId> [--json]`
+ *
+ * 推文 §"AI 回答必须给出处" 的兑现路径——点 citation chip → 调本命令 → 显
+ * 原文。Returns the full event row from the vault, including subtype /
+ * source / actor / title / timestamps / payload-derived fields.
+ *
+ * Caller is typically the Android UI (HubAskCard citation chip click) or
+ * desktop renderer. Returns `null` shape `{ found: false, eventId }` when
+ * the id doesn't match (e.g. event was deleted by destroy after the ask).
+ */
+async function cmdEventDetail(eventId, options) {
+  if (!eventId) {
+    const msg = "eventId argument required";
+    if (options.json) printJson({ error: msg });
+    else logger.error(chalk.red(`✗ ${msg}`));
+    process.exit(1);
+  }
+  try {
+    const hub = await getHub();
+    const event = hub.vault.getEvent(eventId);
+    if (!event) {
+      const result = { found: false, eventId };
+      if (options.json) printJson(result);
+      else logger.log(chalk.yellow(`(no event with id ${eventId})`));
+      return;
+    }
+    if (options.json) {
+      printJson({ found: true, event });
+    } else {
+      logger.log(chalk.bold(`event ${event.id}`));
+      logger.log(`  subtype:  ${event.subtype}`);
+      logger.log(`  source:   ${event.source}`);
+      if (event.title) logger.log(`  title:    ${event.title}`);
+      if (event.actor) logger.log(`  actor:    ${event.actor}`);
+      if (event.amount != null) {
+        logger.log(`  amount:   ${event.amount} ${event.currency || ""}`);
+      }
+      if (event.startedAt) {
+        logger.log(`  started:  ${new Date(event.startedAt).toISOString()}`);
+      }
+    }
+  } catch (err) {
+    fail(null, err, options.json);
+  }
+}
+
+// ─── export ──────────────────────────────────────────────────────────
+
+/**
+ * `cc hub export --output <path> [--json]`
+ *
+ * 推文 §"一键带走"。Closes the vault, copies vault.db (+ WAL/SHM if present)
+ * to the destination path, then reopens. Resulting file is SQLCipher-encrypted
+ * exactly as on disk — caller (Android UI) hands the bytes off via SAF
+ * picker. Desktop side can `cc hub import-vault <path>` to reimport.
+ *
+ * No re-encryption / re-keying. The file IS the export. Key handling is
+ * out of scope here — the file is useless without the user's keystore-backed
+ * key material (which is bound to device by KeyProvider).
+ */
+async function cmdExport(options) {
+  if (!options.output) {
+    const msg = "--output <path> required";
+    if (options.json) printJson({ error: msg });
+    else logger.error(chalk.red(`✗ ${msg}`));
+    process.exit(1);
+  }
+  try {
+    const fs = await import("node:fs");
+    const path = await import("node:path");
+    const hub = await getHub();
+    const src = hub.vault.path;
+    if (!src) throw new Error("vault path unavailable (hub not initialized?)");
+
+    // Resolve output → absolute path. Make parent directory if missing.
+    const outAbs = path.resolve(options.output);
+    fs.mkdirSync(path.dirname(outAbs), { recursive: true });
+
+    // Close the vault so we copy a consistent snapshot. better-sqlite3 keeps
+    // WAL pages buffered; closing flushes everything to disk. We reopen at
+    // end so the running hub session continues to work.
+    try {
+      hub.vault.close?.();
+    } catch (_e) {
+      // ignore — closing failure is rare and we still try to copy
+    }
+
+    // Copy main db file. WAL / SHM are sidecars — only copy if present (they
+    // may or may not exist depending on WAL mode + last checkpoint).
+    let bytes = 0;
+    fs.copyFileSync(src, outAbs);
+    bytes += fs.statSync(outAbs).size;
+    for (const suffix of ["-wal", "-shm"]) {
+      const sidecar = src + suffix;
+      if (fs.existsSync(sidecar)) {
+        const outSidecar = outAbs + suffix;
+        fs.copyFileSync(sidecar, outSidecar);
+        bytes += fs.statSync(outSidecar).size;
+      }
+    }
+
+    // Reopen so the same hub instance can keep serving.
+    try {
+      hub.vault.open?.();
+    } catch (e) {
+      // If reopen fails the next operation will surface it; don't block export.
+      logger.warn?.(
+        chalk.yellow(
+          `! vault.open after export failed: ${e?.message || e} — restart cc`,
+        ),
+      );
+    }
+
+    const result = {
+      ok: true,
+      source: src,
+      output: outAbs,
+      bytes,
+      // Hint to caller (e.g. Android UI) that this is encrypted at rest.
+      encrypted: true,
+    };
+    if (options.json) {
+      printJson(result);
+    } else {
+      logger.log(chalk.green(`✓ exported ${bytes} bytes to ${outAbs}`));
+    }
+  } catch (err) {
+    fail(null, err, options.json);
+  }
+}
+
 // ─── destroy ─────────────────────────────────────────────────────────
 
 async function cmdDestroy(options) {
@@ -499,8 +640,13 @@ async function cmdAIChatHealth(options) {
     const factoryDeps = options._factoryDeps || {};
     const hubDir =
       factoryDeps.hubDir || (await (options._getHub || getHub)()).hubDir;
-    const { createAIChatHealthChecker } =
-      await import("@chainlesschain/personal-data-hub/adapters/ai-chat-history/health-checker");
+    // Bypass vite import-analysis (which can't resolve subpath exports
+    // for dynamic imports in vitest SSR mode) by composing the specifier
+    // at runtime — the static analyzer skips non-literal arguments.
+    const hcSpecifier =
+      "@chainlesschain/personal-data-hub" +
+      "/adapters/ai-chat-history/health-checker";
+    const { createAIChatHealthChecker } = await import(hcSpecifier);
     const { createAccountsStore, createVendorAdapterBridge } =
       await import("../lib/personal-data-hub-aichat-wizard.js");
     const accountsStore =
@@ -653,6 +799,193 @@ async function cmdWechatList(options) {
   }
 }
 
+/**
+ * `cc hub wechat doctor` — env-probe + actionable interpretation +
+ * inline reference to the Phase 12.9 §5.1 Frida hook trap table.
+ *
+ * Designed to be the single command user runs on a rooted Android during
+ * Phase 12.9 real-device E2E to figure out "what should I do next?" —
+ * combines env-probe output + readiness checklist (per md5 vs frida
+ * path) + post-register telemetry fields to capture if hook fails.
+ *
+ * Returns the same JSON as env-probe + a `doctor` block under --json so
+ * scripts can branch on `doctor.readiness === 'ready' | 'blocked' | 'partial'`.
+ */
+async function cmdWechatDoctor(options) {
+  try {
+    const hub = await (options._getHub || getHub)();
+    const probe = await hub.probeWechatEnv();
+
+    // Determine readiness + concrete next-action based on probe shape.
+    const advice = interpretWechatProbe(probe);
+
+    if (options.json) {
+      printJson({ probe, doctor: advice });
+      return;
+    }
+
+    // Human-readable: re-use env-probe formatting then append advice.
+    logger.log(chalk.bold("WeChat env-probe:"));
+    logger.log(
+      `  ${probe.ok ? chalk.green("✓") : chalk.red("✗")} suggested: ${chalk.cyan(probe.suggestedKeyProvider)}`,
+    );
+    logger.log(
+      `  device: ${probe.device.reachable ? chalk.green("reachable") : chalk.red("unreachable")}${probe.device.serial ? " (" + probe.device.serial + ")" : ""} abi=${probe.device.abi || "?"}`,
+    );
+    logger.log(
+      `  root: ${probe.root.detected ? chalk.green("yes") : chalk.gray("no")} magisk=${probe.root.magiskInstalled ? "yes" : "no"}`,
+    );
+    logger.log(
+      `  frida-server: ${probe.frida.serverRunning ? chalk.green("running") : chalk.gray("not running")}${probe.frida.port ? " :" + probe.frida.port : ""}`,
+    );
+    logger.log(
+      `  wechat: ${probe.wechat.installed ? chalk.green(probe.wechat.versionName) : chalk.gray("not installed")}`,
+    );
+
+    logger.log("");
+    const statusColor =
+      advice.readiness === "ready"
+        ? chalk.green
+        : advice.readiness === "partial"
+          ? chalk.yellow
+          : chalk.red;
+    logger.log(
+      chalk.bold(`Doctor: ${statusColor(advice.readiness.toUpperCase())}`),
+    );
+    for (const blocker of advice.blockers) {
+      logger.log(`  ${chalk.red("✗")} ${blocker}`);
+    }
+    for (const w of advice.warnings) {
+      logger.log(`  ${chalk.yellow("!")} ${w}`);
+    }
+    for (const step of advice.nextSteps) {
+      logger.log(`  ${chalk.cyan("→")} ${step}`);
+    }
+
+    if (advice.readiness !== "blocked") {
+      logger.log("");
+      logger.log(
+        chalk.bold("After `cc hub wechat register`, capture telemetry:"),
+      );
+      logger.log(
+        chalk.gray(
+          "  cc hub wechat register --uin <UIN> --db ... --json | jq '.fridaTelemetry'",
+        ),
+      );
+      logger.log(
+        chalk.gray(
+          "  Expected fields: hooked / keySource / keySig / keyFormat / keyLength / keyAlt / errors / durationMs",
+        ),
+      );
+      logger.log("");
+      logger.log(
+        chalk.bold("If hook fails, match telemetry against trap table:"),
+      );
+      logger.log(
+        chalk.gray(
+          "  A — hooked:[] empty           → libWCDB.so module name (try OEM custom names)",
+        ),
+      );
+      logger.log(
+        chalk.gray(
+          "  B — keySig:v2 but DB won't open → sqlite3_key_v2 args index wrong",
+        ),
+      );
+      logger.log(
+        chalk.gray(
+          "  C — keyFormat:raw-bytes but len=64 → ascii-hex path missed",
+        ),
+      );
+      logger.log(
+        chalk.gray(
+          "  Full table: docs/design/Personal_Data_Hub_Phase_12_9_*Runbook.md §5.1",
+        ),
+      );
+    }
+  } catch (err) {
+    fail(null, err, options.json);
+  }
+}
+
+/**
+ * Interpret env-probe result into { readiness, blockers, warnings, nextSteps }.
+ * Pure function — testable without device.
+ *
+ * @param {object} probe  output of hub.probeWechatEnv()
+ * @returns {{readiness: 'ready'|'partial'|'blocked', blockers: string[],
+ *   warnings: string[], nextSteps: string[]}}
+ */
+function interpretWechatProbe(probe) {
+  const blockers = [];
+  const warnings = [];
+  const nextSteps = [];
+
+  if (!probe || !probe.device || !probe.device.reachable) {
+    blockers.push("adb 设备未连接 (USB 调试 / drivers / authorize?)");
+    nextSteps.push("`adb devices` 应列出至少一台 device 状态");
+    return { readiness: "blocked", blockers, warnings, nextSteps };
+  }
+
+  if (!probe.wechat || !probe.wechat.installed) {
+    blockers.push("WeChat (com.tencent.mm) 未安装");
+    nextSteps.push("先把 WeChat 装上 + 登一次产生 EnMicroMsg.db");
+    return { readiness: "blocked", blockers, warnings, nextSteps };
+  }
+
+  const ver = probe.wechat.majorVersion || 0;
+  const suggested = probe.suggestedKeyProvider;
+
+  if (ver < 8 && suggested === "md5") {
+    nextSteps.push(
+      "MD5 path: `adb pull /data/data/com.tencent.mm/ /tmp/wechat-data/`",
+    );
+    nextSteps.push(
+      "拉到本地后跑: `cc hub wechat register --uin <UIN> --db /tmp/wechat-data/MicroMsg/<md5-uin>/EnMicroMsg.db --wechat-data-path /tmp/wechat-data/`",
+    );
+    if (!probe.root.detected) {
+      warnings.push(
+        "非 root 设备只能 adb pull WeChat backup 子集 — 可能拿不到全部 db / 文件",
+      );
+    }
+    return { readiness: "ready", blockers, warnings, nextSteps };
+  }
+
+  if (ver >= 8 && suggested === "frida") {
+    if (!probe.root.detected) {
+      blockers.push("WeChat ≥ 8.0 必须 root + Frida hook，当前设备未 root");
+      nextSteps.push("Magisk 刷入 → 重启 → 重跑 doctor");
+      return { readiness: "blocked", blockers, warnings, nextSteps };
+    }
+    if (!probe.frida.serverRunning) {
+      blockers.push("Frida server 未运行");
+      nextSteps.push(
+        "见 docs/design/Adapter_WeChat_SQLCipher_Frida_Setup.md §2 启 frida-server",
+      );
+      return { readiness: "partial", blockers, warnings, nextSteps };
+    }
+    nextSteps.push(
+      "Frida path 就绪。register: `cc hub wechat register --uin <wxid>`（无需 --db / --wechat-data-path）",
+    );
+    nextSteps.push("WeChat 必须前台运行（已登录），register 期间不要切走");
+    return { readiness: "ready", blockers, warnings, nextSteps };
+  }
+
+  if (suggested === "unsupported") {
+    blockers.push("env-probe 判定为 unsupported");
+    for (const reason of probe.reasons || []) blockers.push(reason);
+    nextSteps.push(
+      "见 docs/design/Adapter_WeChat_SQLCipher.md §13 — 检查 WeChat 版本兼容矩阵",
+    );
+    return { readiness: "blocked", blockers, warnings, nextSteps };
+  }
+
+  // Fallback — probe shape we don't recognize
+  warnings.push(
+    `未识别的 suggested='${suggested}' (version=${probe.wechat.versionName || "?"})`,
+  );
+  return { readiness: "partial", blockers, warnings, nextSteps };
+}
+
 async function cmdWechatUnregister(uin, options) {
   try {
     if (!uin) throw new Error("uin argument required");
@@ -794,6 +1127,26 @@ export function registerHubCommand(program) {
     .option("--json", "Output JSON")
     .action(cmdRunSkill);
 
+  hub
+    .command("event-detail <eventId>")
+    .description(
+      "推文 §AI 给出处: fetch full event row from local vault by id (used by citation chip deeplink).",
+    )
+    .option("--json", "Output JSON")
+    .action(cmdEventDetail);
+
+  hub
+    .command("export")
+    .description(
+      "推文 §一键带走: copy SQLCipher vault.db (+ WAL/SHM) to <path>. Encrypted at rest; reimport via cc hub import-vault on desktop.",
+    )
+    .requiredOption(
+      "--output <path>",
+      "Destination file path for the vault copy",
+    )
+    .option("--json", "Output JSON")
+    .action(cmdExport);
+
   hub
     .command("destroy")
     .description(
@@ -901,6 +1254,16 @@ export function registerHubCommand(program) {
     )
     .option("--json", "Output JSON")
     .action(cmdWechatUnregister);
+
+  // Phase 12.9 — diagnostic helper for real-device E2E. Combines env-probe
+  // with actionable readiness checklist + inline §5.1 Frida trap reference.
+  wechat
+    .command("doctor")
+    .description(
+      "Diagnose WeChat setup — env-probe + readiness checklist + Phase 12.9 trap reference",
+    )
+    .option("--json", "Output JSON")
+    .action(cmdWechatDoctor);
 }
 
 // exported for tests — handler functions can be invoked directly with
@@ -917,5 +1280,7 @@ export const _internal = {
   cmdWechatRegister,
   cmdWechatList,
   cmdWechatUnregister,
+  cmdWechatDoctor,
+  interpretWechatProbe,
   _defaultKnownVendors,
 };