chainlesschain 0.162.14 → 0.162.15

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

@@ -499,8 +499,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 +658,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");
@@ -901,6 +1093,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 +1119,7 @@ export const _internal = {
   cmdWechatRegister,
   cmdWechatList,
   cmdWechatUnregister,
+  cmdWechatDoctor,
+  interpretWechatProbe,
   _defaultKnownVendors,
 };