@chainlesschain/personal-data-hub 0.4.0 → 0.4.2

package/README.md

@@ -4,25 +4,38 @@ Personal Data Hub — UnifiedSchema, validators, batch helpers, SQLCipher
 LocalVault, and AdapterRegistry for the "data back to the individual"
 middleware.
 
-> **Phase 0 + Phase 1 + Phase 2 + Phase 3 + Phase 3.5 landed** of the 13-phase plan in
-> [`docs/design/Personal_Data_Hub_Architecture.md`](../../docs/design/Personal_Data_Hub_Architecture.md).
-> Phase 0 covers schema + validation + ID generation.
-> Phase 1 adds SQLCipher LocalVault + pluggable key providers + migrations.
-> Phase 2 adds AdapterRegistry + KG/RAG derivation + MockAdapter (1000
-> events ingest in ~600ms — 50× under the 30s target).
-> Phase 3 adds the natural-language AnalysisEngine: query parser → vault
-> facts → prompt builder → LLM → citation validation, with a privacy gate
-> that refuses non-local LLMs unless caller opts in. **MockLLMClient**
-> for tests, **OllamaClient** for standalone use.
-> Phase 3.5 wires production bridges: **CcLLMAdapter** wraps the existing
-> cc llm-manager (Ollama / Volcengine / Anthropic / Gemini / DeepSeek)
-> via dependency injection; **CcKgSink** translates hub triples into the
-> existing knowledge-graph addEntity + addRelation; **CcRagSink** feeds
-> hub RagDocs into BM25 (Qdrant vector store wiring left as future work).
-> Hub package stays decoupled — bridges take cc functions as constructor
-> args rather than importing cc modules directly.
-> Sync engine UI, real KG/RAG wiring, and the actual adapters (Email,
-> Alipay, AI Chat × 8, WeChat, ...) come in later phases.
+> **v0.4.0 (ships with ChainlessChain v5.0.3.99, 2026-06-08).** Phase 0–13
+> of the 13-phase plan in
+> [`docs/design/Personal_Data_Hub_Architecture.md`](../../docs/design/Personal_Data_Hub_Architecture.md)
+> have landed, plus the multi-platform collection layer. The foundation is
+> unchanged: schema + validation + UUID v7 (Phase 0); SQLCipher LocalVault +
+> pluggable key providers + migrations (Phase 1); AdapterRegistry + KG/RAG
+> derivation (Phase 2); the natural-language AnalysisEngine with a hard
+> privacy gate that refuses non-local LLMs unless the caller opts in
+> (Phase 3); and production bridges — **CcLLMAdapter** (wraps cc llm-manager:
+> Ollama / Volcengine / Anthropic / Gemini / DeepSeek), **CcKgSink**, **CcRagSink**
+> — injected at the desktop/CLI entry so this package stays decoupled (Phase 3.5).
+>
+> **51 adapters are now live** (no longer "later phases"): Email IMAP,
+> Alipay bill, 9 AI-chat vendors, WeChat / QQ / Weibo / Bilibili / Douyin /
+> Xiaohongshu / Toutiao / Kuaishou social, Telegram / WhatsApp messaging,
+> Taobao / JD / Meituan / Pinduoduo shopping, Amap / Baidu-map / Tencent-map /
+> Ctrip / 12306 travel, system-data (contacts / calls / sms / location),
+> and the developer-activity set (git / shell / vscode / browser-history /
+> local-files / win-recent).
+>
+> **New in v0.4.0 (v5.0.3.99):** adapter **readiness** — split out from the
+> loose `healthCheck` sync gate into a real ready/needs_setup/unavailable
+> judgment (`registry.readiness()`) with a one-line reason, so "config looks
+> fine but nothing collects" is no longer silent; an `adapter-guide.js`
+> single-source of import steps reused across web-shell / desktop / CLI /
+> Android; new local-direct-read sources (Douyin, WeChat PC, QQ-NT, DingTalk,
+> Feishu, WeRead, Apple Health, NetEase Music); email-bill LLM gap-fill
+> (Phase 5.5); and iOS encrypted-backup decryption (Phase 7.5b).
+>
+> Editing `lib/**` requires bumping the package version + `npm publish` +
+> the Android `USR_VERSION` sentinel, or real devices keep running stale code
+> (see hidden-risk-traps #27/#28).
 
 ## What's in here
 
@@ -40,6 +53,14 @@ lib/
 │                     typed put/get, queryEvents, watermarks, audit, key
 │                     rotation (WAL-safe), destroy
 ├── adapter-spec.js   PersonalDataAdapter contract + assertAdapter check
+├── adapter-readiness.js readiness() — ready/needs_setup/unavailable + reason,
+│                     split out from the loose healthCheck sync gate
+├── adapter-guide.js  category-driven import guides (single source of import
+│                     steps reused across web-shell / desktop / CLI / Android)
+├── adapters/         51 live adapters (email-imap, alipay-bill, ai-chat-history,
+│                     wechat / wechat-pc, qq-pc, dingtalk-pc, feishu-pc, weread,
+│                     apple-health, netease-music, social-*, shopping-*,
+│                     travel-*, system-data, git-activity, vscode, ...)
 ├── kg-derive.js      UnifiedSchema → KG triples (rdf:type / by / involves /
 │                     happened-at / etc.) — engine-agnostic
 ├── rag-derive.js     UnifiedSchema → RAG (text, metadata) docs for indexing
@@ -217,7 +238,7 @@ cd packages/personal-data-hub
 npm test
 ```
 
-**268 tests** across 17 files covering ID generation, all 5 entity validators,
+**2040 tests** across 121 files covering ID generation, all 5 entity validators,
 batch helpers, key providers, vault open/migrations, entity round-trips,
 transactional putBatch with rollback, raw_events archive, queryEvents
 filters + pagination, sync watermarks, audit log, key rotation (WAL-safe),
@@ -230,11 +251,10 @@ tolerance), and the 1k events <30s ingest perf gate.
 
 | Concern               | Lives in                                          |
 |-----------------------|---------------------------------------------------|
-| Platform KeyProviders (DPAPI/Keychain/Keystore) | Phase 1.5 — desktop-app-vue main process bridge |
-| AdapterRegistry       | Phase 2 — same package or sibling                  |
-| KG ingestor / RAG     | Phase 2/4 — wired into existing KG / RAG engines  |
-| Email/Alipay/AI/WeChat adapters | Phase 5-12 — separate sub-packages       |
-| AI analysis skills    | Phase 11 — `skills/personal-analysis-*/`          |
+| Platform KeyProviders (DPAPI/Keychain/Keystore) | desktop-app-vue main-process bridge (the package ships the contract + InMemory/File providers) |
+| Qdrant vector retrieval | wired into the existing RAG engine at the cc entry (BM25 derivation ships here) |
+| AI analysis skills    | `skills/personal-analysis-*/` (the 5 built-in analysis skills) |
+| Native SQLCipher build | `better-sqlite3-multiple-ciphers` — host/Electron ABI dual-load handled at the cc entry |
 
 ## License
 

package/__tests__/adapter-guide.test.js

@@ -0,0 +1,47 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { getAdapterGuide, ADAPTER_OVERRIDES } = require("../lib/adapter-guide");
+
+describe("adapter-guide", () => {
+  it("wechat-pc guide reflects the 4.0 one-click reality (no manual PyWxDump as primary)", () => {
+    const g = getAdapterGuide("wechat-pc", "device");
+    // primary method is the automatic one-click, not manual decryption
+    const primary = g.methods[0];
+    expect(primary.recommended).toBe(true);
+    expect(primary.label).toMatch(/一键|自动/);
+    expect(primary.steps.join(" ")).toMatch(/一键采集|自动/);
+    // summary mentions the full coverage we now capture
+    expect(g.summary).toMatch(/公众号/);
+    expect(g.summary).toMatch(/朋友圈/);
+    expect(g.summary).toMatch(/收藏/);
+    // manual 3.x path is still offered as a fallback
+    expect(g.methods.some((m) => /3\.x|PyWxDump|手动/.test(m.label + m.steps.join(" ")))).toBe(true);
+  });
+
+  it("the 6 social platforms all have a tailored one-click ADB guide", () => {
+    for (const name of [
+      "social-bilibili",
+      "social-weibo",
+      "social-douyin",
+      "social-xiaohongshu",
+      "social-toutiao",
+      "social-kuaishou",
+    ]) {
+      expect(ADAPTER_OVERRIDES[name]).toBeTruthy();
+      const g = getAdapterGuide(name, "device");
+      const primary = g.methods[0];
+      expect(primary.recommended).toBe(true);
+      // recommended path is root-phone + one-click, not "go log in on the web"
+      expect(primary.label + primary.steps.join(" ")).toMatch(/一键|ADB|USB|root/i);
+    }
+  });
+
+  it("unknown adapter falls back to a category guide without throwing", () => {
+    const g = getAdapterGuide("totally-unknown", "snapshot");
+    expect(g.category).toBe("snapshot");
+    expect(Array.isArray(g.methods)).toBe(true);
+    expect(g.methods.length).toBeGreaterThan(0);
+  });
+});

package/__tests__/adapters/local-im-pc.test.js

@@ -107,12 +107,17 @@ describe.each([
   ["DingTalkPcAdapter", DingTalkPcAdapter, "dingtalk"],
   ["FeishuPcAdapter", FeishuPcAdapter, "feishu"],
 ])("%s (honest best-effort)", (_label, Cls, platform) => {
-  it("no-arg construct + DB_NOT_PULLED readiness + legalGate", async () => {
+  it("no-arg construct + APP_NOT_INSTALLED when nothing discoverable + legalGate", async () => {
     const a = new Cls();
+    a._deps.discoveryDeps = {
+      fs: { existsSync: () => false, readdirSync: () => [], statSync: () => ({ size: 0 }), constants: { R_OK: 4 } },
+      home: "/no-home",
+      env: {},
+    };
     expect(a.extractMode).toBe("device-pull");
     expect(a.dataDisclosure.legalGate).toBe(true);
     const r = await a.authenticate({ readinessOnly: true });
-    expect(r.reason).toBe("DB_NOT_PULLED");
+    expect(r.reason).toBe("APP_NOT_INSTALLED");
   });
 
   it("reads messages → valid events, platform tag, raw preserved", async () => {

package/__tests__/adapters/pc-local-discovery.test.js

@@ -0,0 +1,141 @@
+"use strict";
+
+/**
+ * Unit tests for _pc-local-discovery against a synthetic filesystem — no real
+ * App needs to be installed. Uses posix path so assertions are host-agnostic.
+ */
+
+import { describe, it, expect } from "vitest";
+const path = require("node:path");
+const { discover, SUPPORTED_APPS } = require("../../lib/adapters/_pc-local-discovery");
+
+// Build a fake fs from a map of { dirPath: [entryName...] } + a set of file paths.
+function makeFakeFs({ tree = {}, files = {}, sizes = {} } = {}) {
+  const norm = (p) => p.replace(/\\/g, "/");
+  const fileSet = new Set(Object.keys(files).map(norm));
+  const dirSet = new Set(Object.keys(tree).map(norm));
+  return {
+    existsSync: (p) => fileSet.has(norm(p)) || dirSet.has(norm(p)),
+    readdirSync: (p) => {
+      const entries = tree[norm(p)] || [];
+      return entries.map((e) => ({
+        name: e.name,
+        isDirectory: () => e.type === "dir",
+        isFile: () => e.type === "file",
+      }));
+    },
+    statSync: (p) => ({ size: sizes[norm(p)] || 1 }),
+    constants: { R_OK: 4 },
+  };
+}
+
+const D = (name) => ({ name, type: "dir" });
+const F = (name) => ({ name, type: "file" });
+
+describe("_pc-local-discovery", () => {
+  it("supports the expected app keys", () => {
+    expect(SUPPORTED_APPS).toEqual(["wechat-pc", "qq-pc", "dingtalk-pc", "feishu-pc"]);
+  });
+
+  it("returns installed:false for an unknown app key (never throws)", () => {
+    const r = discover("totally-unknown", { fs: makeFakeFs(), home: "/h", env: {}, path: path.posix });
+    expect(r.installed).toBe(false);
+    expect(r.note).toMatch(/不支持/);
+  });
+
+  it("returns installed:false when nothing is on disk", () => {
+    const r = discover("wechat-pc", { fs: makeFakeFs(), home: "/h", env: {}, path: path.posix });
+    expect(r.installed).toBe(false);
+    expect(r.primaryDb).toBe(null);
+  });
+
+  it("discovers a WeChat 4.x account and picks message_0.db as primary", () => {
+    const base = "/h/Documents/xwechat_files";
+    const acc = `${base}/wxid_demo_42`;
+    const fs = makeFakeFs({
+      tree: {
+        [base]: [D("wxid_demo_42"), D("all_users")],
+        [`${acc}/db_storage/message`]: [F("message_0.db"), F("biz_message_0.db"), F("message_fts.db")],
+      },
+      files: {
+        [`${acc}/db_storage`]: 1,
+        [`${acc}/db_storage/message/message_0.db`]: 1,
+        [`${acc}/db_storage/contact/contact.db`]: 1,
+        [`${acc}/db_storage/sns/sns.db`]: 1,
+      },
+      sizes: {
+        [`${acc}/db_storage/message/message_0.db`]: 99,
+        [`${acc}/db_storage/message/biz_message_0.db`]: 50,
+      },
+    });
+    const r = discover("wechat-pc", { fs, home: "/h", env: {}, path: path.posix });
+    expect(r.installed).toBe(true);
+    expect(r.layout).toBe("4.x");
+    expect(r.encrypted).toBe(true);
+    expect(r.accounts).toHaveLength(1);
+    expect(r.accounts[0].id).toBe("wxid_demo");
+    expect(r.primaryDb).toContain("message_0.db");
+    // message_fts.db must NOT be picked up as a message db
+    const purposes = r.accounts[0].dbs.map((d) => d.purpose).sort();
+    expect(purposes).toContain("message");
+    expect(purposes).toContain("contact");
+    expect(r.accounts[0].dbs.some((d) => /message_fts/.test(d.path))).toBe(false);
+  });
+
+  it("discovers a WeChat 3.x account (MSG*.db + MicroMsg.db)", () => {
+    const base = "/h/Documents/WeChat Files";
+    const acc = `${base}/wxid_old`;
+    const fs = makeFakeFs({
+      tree: {
+        [base]: [D("wxid_old"), D("All Users")],
+        [`${acc}/Msg/Multi`]: [F("MSG0.db"), F("MSG1.db")],
+      },
+      files: {
+        [`${acc}/Msg/Multi/MSG0.db`]: 1,
+        [`${acc}/Msg/Multi/MSG1.db`]: 1,
+        [`${acc}/Msg/MicroMsg.db`]: 1,
+      },
+    });
+    const r = discover("wechat-pc", { fs, home: "/h", env: {}, path: path.posix });
+    expect(r.installed).toBe(true);
+    expect(r.layout).toBe("3.x");
+    expect(r.accounts[0].dbs.filter((d) => d.purpose === "message")).toHaveLength(2);
+  });
+
+  it("discovers a QQ NT account by numeric uin dir", () => {
+    const base = "/h/Documents/Tencent Files";
+    const acc = `${base}/896075341`;
+    const fs = makeFakeFs({
+      tree: { [base]: [D("896075341"), D("nt_qq")] },
+      files: {
+        [`${acc}/nt_qq/nt_db/nt_msg.db`]: 1,
+        [`${acc}/nt_qq/nt_db/group_info.db`]: 1,
+      },
+    });
+    const r = discover("qq-pc", { fs, home: "/h", env: {}, path: path.posix });
+    expect(r.installed).toBe(true);
+    expect(r.accounts[0].id).toBe("896075341");
+    expect(r.primaryDb).toContain("nt_msg.db");
+    expect(r.encrypted).toBe(true);
+  });
+
+  it("dingtalk best-effort scan finds plaintext db (encrypted:false)", () => {
+    const root = "/appdata/DingTalk";
+    const fs = makeFakeFs({
+      tree: {
+        [root]: [D("user1")],
+        [`${root}/user1`]: [F("im_message.db"), F("cache.db")],
+      },
+      files: {
+        [`${root}/user1/im_message.db`]: 1,
+        [`${root}/user1/cache.db`]: 1,
+      },
+      sizes: { [`${root}/user1/im_message.db`]: 100 },
+    });
+    const r = discover("dingtalk-pc", { fs, home: "/h", env: { APPDATA: "/appdata" }, path: path.posix });
+    expect(r.installed).toBe(true);
+    expect(r.encrypted).toBe(false);
+    expect(r.bestEffort).toBe(true);
+    expect(r.primaryDb).toContain("im_message.db");
+  });
+});

package/__tests__/adapters/qq-pc-direct-read.test.js

@@ -105,12 +105,17 @@ async function collect(iter) {
 }
 
 describe("QQPcAdapter — readiness + construction", () => {
-  it("no-arg construct + DB_NOT_PULLED readiness", async () => {
+  it("no-arg construct + APP_NOT_INSTALLED when nothing discoverable", async () => {
     const a = new QQPcAdapter();
+    a._deps.discoveryDeps = {
+      fs: { existsSync: () => false, readdirSync: () => [], statSync: () => ({ size: 0 }), constants: { R_OK: 4 } },
+      home: "/no-home",
+      env: {},
+    };
     expect(a.name).toBe("qq-pc");
     expect(a.dataDisclosure.legalGate).toBe(true);
     const r = await a.authenticate({ readinessOnly: true });
-    expect(r.reason).toBe("DB_NOT_PULLED");
+    expect(r.reason).toBe("APP_NOT_INSTALLED");
   });
 });
 

package/__tests__/adapters/social-douyin-adb-db-extension.test.js

@@ -0,0 +1,114 @@
+"use strict";
+
+/**
+ * Phase 2a (Douyin C 路径) — cover for the douyin.pull-im-db ADB extension's
+ * IM-db discovery + classification.
+ *
+ * Real-device verification (2026-06-08, Xiaomi chopin / MIUI 13, Douyin
+ * logged in) found CURRENT Douyin no longer keeps a plaintext social-DM IM
+ * db. The databases/ dir instead holds:
+ *   - encrypted_<uid>_im.db  → SQLCipher social DM (header NOT `SQLite format 3`)
+ *   - im_database_<uid>      → Room db, but it is the in-app 豆包/Doubao AI
+ *                              assistant chat, not social DMs
+ * The extension must classify these and emit a precise typed error rather
+ * than the misleading DOUYIN_NO_IM_DB.
+ *
+ * Strategy: scripted fake `ctx.adb` returns a canned `ls` body modeled on
+ * the real device listing — no ADB / device needed.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+
+const {
+  createDouyinDbExtension,
+  ENCRYPTED_IM_DB_PATTERN,
+  DOUBAO_IM_DB_PATTERN,
+  _internals,
+} = require("../../lib/adapters/social-douyin-adb/db-extension");
+
+/** Fake ctx: matches the first substring pattern in `responses`. */
+function fakeCtx(responses) {
+  const adb = vi.fn(async (args) => {
+    const key = args.join(" ");
+    for (const [pattern, body] of responses) {
+      if (key.includes(pattern)) {
+        return typeof body === "function" ? body(args) : body;
+      }
+    }
+    throw new Error(`fake adb: no scripted response for: ${key}`);
+  });
+  return { adb, pickDevice: vi.fn(async () => "FAKE_SERIAL"), parseContentQueryRows: () => [] };
+}
+
+// Real device listing (trimmed to the IM-relevant files).
+const REAL_DEVICE_LS = [
+  "aweme_database_92585448288",
+  "encrypted_92585448288_im.db",
+  "encrypted_92585448288_im_customer_box.db",
+  "im_database_",
+  "im_database_6951980119394929011",
+  "push_message.db",
+].join("\n");
+
+describe("patterns", () => {
+  it("ENCRYPTED_IM_DB_PATTERN matches encrypted_<uid>_im.db only", () => {
+    expect("encrypted_92585448288_im.db".match(ENCRYPTED_IM_DB_PATTERN)?.[1]).toBe(
+      "92585448288",
+    );
+    // customer_box variant must NOT be mistaken for the DM store
+    expect("encrypted_92585448288_im_customer_box.db".match(ENCRYPTED_IM_DB_PATTERN)).toBe(
+      null,
+    );
+  });
+
+  it("DOUBAO_IM_DB_PATTERN matches im_database_<uid> with a real uid", () => {
+    expect("im_database_6951980119394929011".match(DOUBAO_IM_DB_PATTERN)?.[1]).toBe(
+      "6951980119394929011",
+    );
+    // empty-uid `im_database_` must not match (needs ≥6 digits)
+    expect("im_database_".match(DOUBAO_IM_DB_PATTERN)).toBe(null);
+  });
+});
+
+describe("listImDbs classification (real-device listing)", () => {
+  it("buckets encrypted + doubao, finds no legacy plaintext", async () => {
+    const ctx = fakeCtx([["ls ", REAL_DEVICE_LS]]);
+    const r = await _internals.listImDbs(ctx.adb, "FAKE_SERIAL", {});
+    expect(r.candidates).toEqual([]); // no legacy `<19digit>_im.db`
+    expect(r.encryptedCandidates.map((c) => c.fileName)).toEqual([
+      "encrypted_92585448288_im.db",
+    ]);
+    expect(r.doubaoCandidates.map((c) => c.fileName)).toEqual([
+      "im_database_6951980119394929011",
+    ]);
+  });
+});
+
+describe("createDouyinDbExtension — precise typed errors", () => {
+  it("throws DOUYIN_IM_DB_ENCRYPTED when only the SQLCipher DM db exists", async () => {
+    const ctx = fakeCtx([
+      ["id -u", "0"],
+      ["ls ", "encrypted_92585448288_im.db\nim_database_6951980119394929011"],
+    ]);
+    const ext = createDouyinDbExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(/DOUYIN_IM_DB_ENCRYPTED/);
+  });
+
+  it("throws DOUYIN_ONLY_DOUBAO_AI_CHAT when only the Doubao Room db exists", async () => {
+    const ctx = fakeCtx([
+      ["id -u", "0"],
+      ["ls ", "im_database_6951980119394929011\npush_message.db"],
+    ]);
+    const ext = createDouyinDbExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(/DOUYIN_ONLY_DOUBAO_AI_CHAT/);
+  });
+
+  it("still throws DOUYIN_NO_IM_DB when nothing relevant exists", async () => {
+    const ctx = fakeCtx([
+      ["id -u", "0"],
+      ["ls ", "push_message.db\naweme.db"],
+    ]);
+    const ext = createDouyinDbExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(/DOUYIN_NO_IM_DB/);
+  });
+});

package/__tests__/adapters/social-weibo-adb-cookies-extension.test.js

@@ -0,0 +1,167 @@
+"use strict";
+
+/**
+ * Phase 3a (Weibo C 路径) — cover for the weibo.cookies ADB extension
+ * factory, focused on the WebView-profile-dir discovery fix.
+ *
+ * Real-device verification (2026-06-08, Xiaomi chopin / MIUI 13, Weibo
+ * logged in) found current Weibo stores its Chromium cookies under a
+ * SUFFIXED profile dir `app_webview_com.sina.weibo/Default/Cookies`, not
+ * the legacy `app_webview/Default/Cookies` the collector hardcoded — so the
+ * old code threw WEIBO_NOT_INSTALLED on a perfectly logged-in phone. The
+ * fix globs `app_webview*` and uses the first match.
+ *
+ * Strategy mirrors social-bilibili-adb-cookies-extension.test.js: build a
+ * real chromium-shape Cookies sqlite, base64 it, and feed it back through a
+ * scripted fake `ctx.adb` — no real ADB / device.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import Database from "better-sqlite3";
+
+const {
+  createWeiboCookiesExtension,
+  WEIBO_COOKIES_REMOTE_GLOB,
+  WEIBO_COOKIES_REMOTE_PATH,
+} = require("../../lib/adapters/social-weibo-adb/cookies-extension");
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "cc-weibo-ext-test-"));
+});
+
+afterEach(() => {
+  try {
+    rmSync(tmpDir, { recursive: true, force: true });
+  } catch (_e) {
+    // ignore
+  }
+});
+
+/** Build a chromium-shape Cookies sqlite + return its base64. */
+function buildCookiesAsBase64(cookies) {
+  const dbPath = join(tmpDir, "fixture-cookies");
+  const db = new Database(dbPath);
+  db.exec(`
+    CREATE TABLE cookies(
+      creation_utc INTEGER,
+      host_key TEXT,
+      name TEXT,
+      value TEXT,
+      encrypted_value BLOB,
+      path TEXT,
+      expires_utc INTEGER,
+      is_secure INTEGER,
+      is_httponly INTEGER,
+      is_persistent INTEGER
+    );
+  `);
+  const insert = db.prepare(
+    "INSERT INTO cookies(host_key, name, value, path, expires_utc, is_secure, is_httponly, is_persistent) VALUES(?, ?, ?, '/', 0, 0, 1, 1)",
+  );
+  for (const c of cookies) {
+    insert.run(c.hostKey || ".m.weibo.cn", c.name, c.value);
+  }
+  db.close();
+  const buf = readFileSync(dbPath);
+  rmSync(dbPath);
+  return buf.toString("base64");
+}
+
+/**
+ * Scripted fake ctx. `responses` is an array of [substringPattern, body];
+ * the first pattern that the joined args contain wins.
+ */
+function fakeCtx(responses) {
+  const adb = vi.fn(async (args) => {
+    const key = args.join(" ");
+    for (const [pattern, body] of responses) {
+      if (key.includes(pattern)) {
+        return typeof body === "function" ? body(args) : body;
+      }
+    }
+    throw new Error(`fake adb: no scripted response for: ${key}`);
+  });
+  return {
+    ctx: { adb, pickDevice: vi.fn(async () => "FAKE_SERIAL"), parseContentQueryRows: () => [] },
+    adb,
+  };
+}
+
+const SUFFIXED_PATH =
+  "/data/data/com.sina.weibo/app_webview_com.sina.weibo/Default/Cookies";
+
+describe("constants", () => {
+  it("glob covers both legacy and suffixed app_webview layouts", () => {
+    expect(WEIBO_COOKIES_REMOTE_GLOB).toBe(
+      "/data/data/com.sina.weibo/app_webview*/Default/Cookies",
+    );
+    // The legacy constant is kept for reference / back-compat callers.
+    expect(WEIBO_COOKIES_REMOTE_PATH).toBe(
+      "/data/data/com.sina.weibo/app_webview/Default/Cookies",
+    );
+  });
+});
+
+describe("createWeiboCookiesExtension — WebView profile dir discovery", () => {
+  it("resolves the SUFFIXED app_webview_com.sina.weibo dir + pulls from it", async () => {
+    const b64 = buildCookiesAsBase64([{ name: "SUB", value: "sessionTokenXYZ" }]);
+    const { ctx, adb } = fakeCtx([
+      ["ls -d", SUFFIXED_PATH], // glob resolves to suffixed dir
+      ["id -u", "0"],
+      ["base64", b64],
+    ]);
+    const ext = createWeiboCookiesExtension();
+    const result = await ext({}, ctx);
+
+    expect(result.cookie).toContain("SUB=sessionTokenXYZ");
+    expect(result.diagnostic.hasSub).toBe(true);
+
+    // The base64 pull MUST target the resolved suffixed path, not the
+    // legacy hardcoded one — this is the regression guard for the fix.
+    const base64Call = adb.mock.calls.find((c) => c[0].join(" ").includes("base64"));
+    expect(base64Call[0].join(" ")).toContain(SUFFIXED_PATH);
+    expect(base64Call[0].join(" ")).not.toContain("app_webview/Default");
+  });
+
+  it("still works with the legacy app_webview path (back-compat)", async () => {
+    const b64 = buildCookiesAsBase64([{ name: "SUB", value: "legacyTok" }]);
+    const { ctx } = fakeCtx([
+      ["ls -d", WEIBO_COOKIES_REMOTE_PATH],
+      ["id -u", "0"],
+      ["base64", b64],
+    ]);
+    const ext = createWeiboCookiesExtension();
+    const result = await ext({}, ctx);
+    expect(result.cookie).toContain("SUB=legacyTok");
+  });
+
+  it("throws WEIBO_NOT_INSTALLED when glob matches nothing", async () => {
+    const { ctx } = fakeCtx([
+      ["ls -d", "NOT_FOUND"],
+      ["id -u", "0"],
+    ]);
+    const ext = createWeiboCookiesExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(/WEIBO_NOT_INSTALLED/);
+  });
+
+  it("throws WEIBO_NOT_INSTALLED when shell echoes the unexpanded glob", async () => {
+    // Some shells, when the glob matches nothing AND nullglob is off, echo
+    // the literal pattern. The `*`-guard must treat that as not-found.
+    const { ctx } = fakeCtx([
+      ["ls -d", WEIBO_COOKIES_REMOTE_GLOB],
+      ["id -u", "0"],
+    ]);
+    const ext = createWeiboCookiesExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(/WEIBO_NOT_INSTALLED/);
+  });
+
+  it("rejects when ctx missing required functions", async () => {
+    const ext = createWeiboCookiesExtension();
+    await expect(ext({}, {})).rejects.toThrow(/ctx must provide/);
+  });
+});