chainlesschain 0.162.13 → 0.162.15

package/src/commands/android.js

@@ -0,0 +1,284 @@
+/**
+ * `cc android` — Android-side data + control commands.
+ *
+ * Plan A Sub-Phase A7 scaffold. Exposes the bridge surface from
+ * `lib/cc-android-bridge.js` as commander subcommands. Method shapes mirror
+ * `docs/design/Personal_Data_Hub_Android_Standalone_Cc.md` §6.1.
+ *
+ * **v0.1 status**: native JNI bridge (`cc-android-bridge.node`) not yet
+ * bundled (A6 in progress). On non-Android hosts every command exits non-zero
+ * with `ANDROID_BRIDGE_NOT_AVAILABLE`. On Android with a missing binding,
+ * same error with a different reason string. This lets the surface land and
+ * be tested ahead of the JNI shipping work.
+ *
+ * All commands support `--json` for scripting and exit non-zero on error.
+ */
+
+import chalk from "chalk";
+import { logger } from "../lib/logger.js";
+import * as bridgeModule from "../lib/cc-android-bridge.js";
+
+function printJson(obj) {
+  console.log(JSON.stringify(obj, null, 2));
+}
+
+function fail(err, asJson) {
+  const msg = err && err.message ? err.message : String(err);
+  const code = err && err.code ? err.code : null;
+  if (asJson) {
+    printJson({ error: msg, code });
+  } else {
+    logger.error(chalk.red(`✗ ${msg}`));
+  }
+  process.exit(1);
+}
+
+async function run(method, params, options) {
+  try {
+    const result = await _deps.bridge.invoke(method, params);
+    if (options.json) {
+      printJson(result);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+  } catch (err) {
+    fail(err, options.json);
+  }
+}
+
+// ─── caps ────────────────────────────────────────────────────────────
+
+async function cmdCaps(options) {
+  const capsResult = _deps.bridge.caps();
+  if (options.json) {
+    printJson(capsResult);
+    return;
+  }
+  if (capsResult.available) {
+    logger.log(chalk.green("✓ android bridge available"));
+  } else {
+    logger.log(
+      chalk.yellow(`⚠ android bridge unavailable: ${capsResult.reason}`),
+    );
+  }
+}
+
+// ─── contacts / sms / calls — P1 ContentResolver ─────────────────────
+
+function cmdContactsPull(options) {
+  return run(
+    "contacts.query",
+    { since: options.since ? Number(options.since) : undefined },
+    options,
+  );
+}
+function cmdSmsPull(options) {
+  return run(
+    "sms.query",
+    { since: options.since ? Number(options.since) : undefined },
+    options,
+  );
+}
+function cmdCallsPull(options) {
+  return run(
+    "calls.query",
+    { since: options.since ? Number(options.since) : undefined },
+    options,
+  );
+}
+
+// ─── app — PackageManager ────────────────────────────────────────────
+
+function cmdAppList(options) {
+  return run("app.list", { includeSystem: !!options.system }, options);
+}
+function cmdAppLaunch(pkg, options) {
+  return run("app.launch", { pkg }, options);
+}
+function cmdAppIntent(pkg, action, options) {
+  const extras = {};
+  if (Array.isArray(options.extra)) {
+    for (const kv of options.extra) {
+      const idx = kv.indexOf("=");
+      if (idx > 0) extras[kv.slice(0, idx)] = kv.slice(idx + 1);
+    }
+  }
+  return run("app.intent", { pkg, action, extras }, options);
+}
+
+// ─── fs — SAF / sandbox ──────────────────────────────────────────────
+
+function cmdFsRead(target, options) {
+  return run("fs.read", { target }, options);
+}
+function cmdFsList(target, options) {
+  return run("fs.list", { target }, options);
+}
+
+// ─── a11y — Accessibility Service ────────────────────────────────────
+
+function cmdA11yQuery(options) {
+  return run("a11y.query", { filter: options.filter }, options);
+}
+function cmdA11yClick(nodeId, options) {
+  return run("a11y.click", { nodeId }, options);
+}
+function cmdA11yType(text, options) {
+  return run("a11y.type", { text }, options);
+}
+
+// ─── shizuku / root ──────────────────────────────────────────────────
+
+function cmdShizukuExec(cmd, options) {
+  return run("shizuku.exec", { cmd }, options);
+}
+function cmdRootExec(cmd, options) {
+  return run("root.exec", { cmd }, options);
+}
+
+// ─── perms ────────────────────────────────────────────────────────────
+
+function cmdPerms(name, options) {
+  return run("perms.check", { name }, options);
+}
+
+// ─── Commander wire-up ───────────────────────────────────────────────
+
+export function registerAndroidCommand(program) {
+  const android = program
+    .command("android")
+    .description(
+      "Android-native bridge: ContentResolver / SAF / Accessibility / Shizuku / root (Plan A A7)",
+    );
+
+  android
+    .command("caps")
+    .description("Probe what bridge capabilities are available on this device")
+    .option("--json", "Output JSON")
+    .action(cmdCaps);
+
+  const contacts = android
+    .command("contacts")
+    .description("ContentResolver: contacts");
+  contacts
+    .command("pull")
+    .description("Pull contacts (READ_CONTACTS runtime permission required)")
+    .option("--since <ms>", "Watermark — only newer entries")
+    .option("--json", "Output JSON")
+    .action(cmdContactsPull);
+
+  const sms = android.command("sms").description("ContentResolver: SMS");
+  sms
+    .command("pull")
+    .description("Pull SMS (READ_SMS runtime permission required)")
+    .option("--since <ms>", "Watermark")
+    .option("--json", "Output JSON")
+    .action(cmdSmsPull);
+
+  const calls = android
+    .command("calls")
+    .description("ContentResolver: call log");
+  calls
+    .command("pull")
+    .description("Pull call log (READ_CALL_LOG runtime permission required)")
+    .option("--since <ms>", "Watermark")
+    .option("--json", "Output JSON")
+    .action(cmdCallsPull);
+
+  const app = android
+    .command("app")
+    .description("PackageManager: app inventory + Intent");
+  app
+    .command("list")
+    .description("List installed packages")
+    .option("--system", "Include system packages")
+    .option("--json", "Output JSON")
+    .action(cmdAppList);
+  app
+    .command("launch <pkg>")
+    .description("Launch app by package id (default activity)")
+    .option("--json", "Output JSON")
+    .action(cmdAppLaunch);
+  app
+    .command("intent <pkg> <action>")
+    .description("Fire an Intent at <pkg> with <action>")
+    .option(
+      "--extra <kv...>",
+      "Repeatable extras as KEY=VAL (e.g. --extra foo=bar --extra n=1)",
+    )
+    .option("--json", "Output JSON")
+    .action(cmdAppIntent);
+
+  const fs = android.command("fs").description("SAF / sandbox filesystem");
+  fs.command("read <target>")
+    .description("Read file (sandbox path OR SAF tree URI)")
+    .option("--json", "Output JSON")
+    .action(cmdFsRead);
+  fs.command("list <target>")
+    .description("List directory")
+    .option("--json", "Output JSON")
+    .action(cmdFsList);
+
+  const a11y = android.command("a11y").description("Accessibility Service");
+  a11y
+    .command("query")
+    .description("Dump current screen's node tree")
+    .option("--filter <css>", "css-like filter")
+    .option("--json", "Output JSON")
+    .action(cmdA11yQuery);
+  a11y
+    .command("click <nodeId>")
+    .description("Click a node")
+    .option("--json", "Output JSON")
+    .action(cmdA11yClick);
+  a11y
+    .command("type <text>")
+    .description("Type text into focused field")
+    .option("--json", "Output JSON")
+    .action(cmdA11yType);
+
+  const shizuku = android
+    .command("shizuku")
+    .description("Shizuku ADB-like privileges");
+  shizuku
+    .command("exec <cmd>")
+    .description("Run shell via Shizuku")
+    .option("--json", "Output JSON")
+    .action(cmdShizukuExec);
+
+  const root = android.command("root").description("Magisk root su");
+  root
+    .command("exec <cmd>")
+    .description("Run shell as root")
+    .option("--json", "Output JSON")
+    .action(cmdRootExec);
+
+  android
+    .command("perms <name>")
+    .description("Check (and request) a runtime permission")
+    .option("--json", "Output JSON")
+    .action(cmdPerms);
+}
+
+// _deps injection seam — tests reach in and replace `bridge` with a mock so
+// the cmd* functions exercise the routing code without a real bridge.
+export const _deps = { bridge: bridgeModule };
+
+// Test-only exports.
+export const _cmds = {
+  cmdCaps,
+  cmdContactsPull,
+  cmdSmsPull,
+  cmdCallsPull,
+  cmdAppList,
+  cmdAppLaunch,
+  cmdAppIntent,
+  cmdFsRead,
+  cmdFsList,
+  cmdA11yQuery,
+  cmdA11yClick,
+  cmdA11yType,
+  cmdShizukuExec,
+  cmdRootExec,
+  cmdPerms,
+};

package/src/commands/hub.js

@@ -191,6 +191,9 @@ async function cmdSyncAdapter(name, options) {
     if (options.since) opts.since = Number(options.since);
     if (options.until) opts.until = Number(options.until);
     if (options.limit) opts.limit = Number(options.limit);
+    // Plan A v0.1 — system-data-android needs a snapshot file path. Generic
+    // pass-through so other input-driven adapters reuse the same flag.
+    if (options.input) opts.inputPath = String(options.input);
     const report = await hub.registry.syncAdapter(name, opts);
     if (spinner) spinner.succeed(`synced ${name}`);
     if (options.json) {
@@ -496,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 =
@@ -566,13 +574,25 @@ async function cmdWechatEnvProbe(options) {
       return;
     }
     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")}`);
-    for (const reason of probe.reasons || []) logger.log(`  · ${chalk.gray(reason)}`);
-    for (const w of probe.warnings || []) logger.log(`  ${chalk.yellow("!")} ${chalk.yellow(w)}`);
+    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")}`,
+    );
+    for (const reason of probe.reasons || [])
+      logger.log(`  · ${chalk.gray(reason)}`);
+    for (const w of probe.warnings || [])
+      logger.log(`  ${chalk.yellow("!")} ${chalk.yellow(w)}`);
   } catch (err) {
     fail(null, err, options.json);
   }
@@ -589,16 +609,21 @@ async function cmdWechatRegister(options) {
       dbPath: options.db || null,
       wechatDataPath: options.wechatDataPath || null,
       keyProviderOverride: options.forceProvider || null,
-      fridaOpts: options.fridaDeviceId ? { deviceId: options.fridaDeviceId } : null,
+      fridaOpts: options.fridaDeviceId
+        ? { deviceId: options.fridaDeviceId }
+        : null,
     });
     if (options.json) {
       printJson(r);
       return;
     }
     if (!r.ok) {
-      logger.error(chalk.red(`✗ ${r.reason || "register failed"}: ${r.message || ""}`));
+      logger.error(
+        chalk.red(`✗ ${r.reason || "register failed"}: ${r.message || ""}`),
+      );
       if (r.probe) {
-        for (const reason of r.probe.reasons || []) logger.error(chalk.gray("  · " + reason));
+        for (const reason of r.probe.reasons || [])
+          logger.error(chalk.gray("  · " + reason));
       }
       process.exit(1);
     }
@@ -624,13 +649,202 @@ async function cmdWechatList(options) {
     }
     logger.log(chalk.bold("Registered WeChat accounts:"));
     for (const row of rows) {
-      logger.log(`  • uin=${chalk.cyan(row.uin)} provider=${row.chosenKeyProvider || "?"} db=${row.dbPath || "(none)"} regAt=${row.registeredAt ? new Date(row.registeredAt).toISOString() : "?"}`);
+      logger.log(
+        `  • uin=${chalk.cyan(row.uin)} provider=${row.chosenKeyProvider || "?"} db=${row.dbPath || "(none)"} regAt=${row.registeredAt ? new Date(row.registeredAt).toISOString() : "?"}`,
+      );
+    }
+  } catch (err) {
+    fail(null, err, options.json);
+  }
+}
+
+/**
+ * `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");
@@ -644,8 +858,12 @@ async function cmdWechatUnregister(uin, options) {
       logger.error(chalk.red(`✗ ${r.reason || "unregister failed"}`));
       process.exit(1);
     }
-    if (r.removed) logger.log(chalk.green(`✓ removed wechat account (uin=${uin})`));
-    else logger.log(chalk.gray(`(uin=${uin} was not registered — nothing removed)`));
+    if (r.removed)
+      logger.log(chalk.green(`✓ removed wechat account (uin=${uin})`));
+    else
+      logger.log(
+        chalk.gray(`(uin=${uin} was not registered — nothing removed)`),
+      );
   } catch (err) {
     fail(null, err, options.json);
   }
@@ -712,6 +930,10 @@ export function registerHubCommand(program) {
     .option("--since <ms>", "Override watermark — sync from this unix-ms")
     .option("--until <ms>", "Stop at this unix-ms")
     .option("--limit <n>", "Cap ingested events")
+    .option(
+      "--input <path>",
+      "Path to a snapshot file produced by a UI layer (system-data-android, etc.)",
+    )
     .option("--json", "Output JSON")
     .action(cmdSyncAdapter);
 
@@ -833,7 +1055,9 @@ export function registerHubCommand(program) {
 
   wechat
     .command("env-probe")
-    .description("Probe attached Android device for adb / root / frida-server / WeChat version")
+    .description(
+      "Probe attached Android device for adb / root / frida-server / WeChat version",
+    )
     .option("--json", "Output JSON")
     .action(cmdWechatEnvProbe);
 
@@ -844,9 +1068,15 @@ export function registerHubCommand(program) {
     )
     .requiredOption("--uin <id>", "WeChat numeric UIN (≤ 8.0) or wxid (8.0+)")
     .option("--db <path>", "Local path to the already-pulled EnMicroMsg.db")
-    .option("--wechat-data-path <dir>", "Local pulled /data/data/com.tencent.mm/ tree (required for md5 path)")
+    .option(
+      "--wechat-data-path <dir>",
+      "Local pulled /data/data/com.tencent.mm/ tree (required for md5 path)",
+    )
     .option("--force-provider <md5|frida>", "Override env-probe suggestion")
-    .option("--frida-device-id <id>", "Frida device id (defaults to first USB device)")
+    .option(
+      "--frida-device-id <id>",
+      "Frida device id (defaults to first USB device)",
+    )
     .option("--json", "Output JSON")
     .action(cmdWechatRegister);
 
@@ -858,9 +1088,21 @@ export function registerHubCommand(program) {
 
   wechat
     .command("unregister <uin>")
-    .description("Remove a registered WeChat account (does not touch vault data)")
+    .description(
+      "Remove a registered WeChat account (does not touch vault data)",
+    )
     .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
@@ -877,5 +1119,7 @@ export const _internal = {
   cmdWechatRegister,
   cmdWechatList,
   cmdWechatUnregister,
+  cmdWechatDoctor,
+  interpretWechatProbe,
   _defaultKnownVendors,
 };