@chainlesschain/personal-data-hub 0.3.1 → 0.3.6

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

@@ -0,0 +1,343 @@
+"use strict";
+
+/**
+ * Phase 1a (Bilibili C 路径) — unit cover for the bilibili.cookies ADB
+ * extension factory.
+ *
+ * Strategy: build a real chromium-shape Cookies sqlite via better-sqlite3,
+ * read it back as bytes, base64-encode, and feed the encoded string back
+ * to the extension via a fake `ctx.adb` that returns canned ADB stdout
+ * per-command. This exercises the full pipeline (probe → su id-u check →
+ * base64 stream → decode → sqlite magic check → parse → header assemble →
+ * temp-file cleanup) without any real ADB / device.
+ *
+ * Covered:
+ *  - Happy path: pulls + parses + returns {cookie, uid, ...}
+ *  - File not found on phone → BILIBILI_NOT_INSTALLED_OR_NEVER_LOGGED_IN
+ *  - Phone not rooted (id -u returns non-zero/non-root) → BILIBILI_NO_ROOT
+ *  - Empty base64 stream → BILIBILI_COOKIES_EMPTY
+ *  - Truncated stream (decoded <1KB) → BILIBILI_COOKIES_TRUNCATED
+ *  - Wrong magic header (not sqlite) → BILIBILI_NOT_SQLITE
+ *  - Cookies DB present but missing required cookies → BILIBILI_COOKIES_INCOMPLETE
+ *  - Invalid DedeUserID (non-integer / negative) → BILIBILI_INVALID_UID
+ *  - Cleanup: temp file deleted on both success and failure
+ *  - Bridge integration via createHostAdbBridge({ extensions: {...} })
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  mkdtempSync,
+  rmSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  readdirSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import Database from "better-sqlite3";
+
+const {
+  createBilibiliCookiesExtension,
+  BILIBILI_COOKIES_REMOTE_PATH,
+} = require("../../lib/adapters/social-bilibili-adb/cookies-extension");
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "cc-bilibili-ext-test-"));
+});
+
+afterEach(() => {
+  try {
+    rmSync(tmpDir, { recursive: true, force: true });
+  } catch (_e) {
+    // ignore
+  }
+});
+
+/**
+ * Build a chromium-shape Cookies sqlite + return its raw bytes + base64.
+ * cookies = array of {name, value, hostKey?}.
+ */
+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 || ".bilibili.com", c.name, c.value);
+  }
+  db.close();
+  const buf = readFileSync(dbPath);
+  rmSync(dbPath);
+  return buf.toString("base64");
+}
+
+/**
+ * Build a fake ctx with a scripted adb response. `responses` is a Map
+ * keyed by the joined args (whitespace-stripped) → string stdout.
+ *
+ * `pickDevice` returns a fixed serial. `parseContentQueryRows` isn't
+ * used by the bilibili extension but is part of the ctx contract.
+ */
+function fakeCtx(responses) {
+  return {
+    adb: vi.fn(async (args, _opts) => {
+      const key = args.join(" ");
+      // Allow exact key OR keyword-contains match (the extension only
+      // checks substrings; the test can opt into "first arg matching ..."
+      // by registering with a unique substring).
+      for (const [pattern, body] of responses) {
+        if (key === pattern || key.includes(pattern)) {
+          return typeof body === "function" ? body(args) : body;
+        }
+      }
+      throw new Error(`fake adb: no scripted response for: ${key}`);
+    }),
+    pickDevice: vi.fn(async () => "FAKE_SERIAL"),
+    parseContentQueryRows: () => [],
+  };
+}
+
+const FULL_BILIBILI_COOKIES = [
+  { name: "SESSDATA", value: "abcSESSDATA123" },
+  { name: "bili_jct", value: "csrfTokenXYZ" },
+  { name: "DedeUserID", value: "1234567890" },
+  { name: "DedeUserID__ckMd5", value: "deadbeef0000" },
+  { name: "buvid3", value: "buvid-uniq-id" },
+];
+
+describe("bilibili.cookies extension — happy path", () => {
+  it("pulls + parses + returns {cookie, uid, ...}", async () => {
+    const b64 = buildCookiesAsBase64(FULL_BILIBILI_COOKIES);
+    const ctx = fakeCtx([
+      [`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, BILIBILI_COOKIES_REMOTE_PATH + "\n"],
+      ["id -u", "0\n"],
+      [`base64 ${BILIBILI_COOKIES_REMOTE_PATH}`, b64],
+    ]);
+    const ext = createBilibiliCookiesExtension();
+    const result = await ext({}, ctx);
+
+    expect(result.cookie).toContain("SESSDATA=abcSESSDATA123");
+    expect(result.cookie).toContain("bili_jct=csrfTokenXYZ");
+    expect(result.cookie).toContain("DedeUserID=1234567890");
+    expect(result.cookie).toContain("buvid3=buvid-uniq-id");
+    expect(result.uid).toBe(1234567890);
+    expect(result.extractedAt).toBeGreaterThan(0);
+    expect(result.diagnostic.cookieCount).toBe(5);
+    expect(result.diagnostic.hadEncrypted).toBe(false);
+  });
+
+  it("uid is parsed as positive integer", async () => {
+    const b64 = buildCookiesAsBase64(FULL_BILIBILI_COOKIES);
+    const ctx = fakeCtx([
+      [`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, BILIBILI_COOKIES_REMOTE_PATH],
+      ["id -u", "uid=0(root) gid=0(root)\n"], // alternate id -u format
+      [`base64 ${BILIBILI_COOKIES_REMOTE_PATH}`, b64],
+    ]);
+    const ext = createBilibiliCookiesExtension();
+    const result = await ext({}, ctx);
+    expect(Number.isInteger(result.uid)).toBe(true);
+    expect(result.uid).toBeGreaterThan(0);
+  });
+});
+
+describe("bilibili.cookies extension — failure modes", () => {
+  it("BILIBILI_NOT_INSTALLED_OR_NEVER_LOGGED_IN when ls returns NOT_FOUND", async () => {
+    const ctx = fakeCtx([[`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, "NOT_FOUND\n"]]);
+    const ext = createBilibiliCookiesExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(
+      /BILIBILI_NOT_INSTALLED_OR_NEVER_LOGGED_IN/,
+    );
+  });
+
+  it("BILIBILI_NO_ROOT when id -u not 0", async () => {
+    const ctx = fakeCtx([
+      [`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, BILIBILI_COOKIES_REMOTE_PATH],
+      ["id -u", "2000\n"], // shell user, not root
+    ]);
+    const ext = createBilibiliCookiesExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(/BILIBILI_NO_ROOT/);
+  });
+
+  it("BILIBILI_COOKIES_EMPTY when base64 stream is empty", async () => {
+    const ctx = fakeCtx([
+      [`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, BILIBILI_COOKIES_REMOTE_PATH],
+      ["id -u", "0\n"],
+      [`base64 ${BILIBILI_COOKIES_REMOTE_PATH}`, "   \r\n"],
+    ]);
+    const ext = createBilibiliCookiesExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(/BILIBILI_COOKIES_EMPTY/);
+  });
+
+  it("BILIBILI_COOKIES_TRUNCATED when decoded file too small", async () => {
+    // 50 bytes of base64 → ~37 bytes decoded, way below 1KB threshold
+    const tinyB64 = Buffer.from("a".repeat(100)).toString("base64");
+    const ctx = fakeCtx([
+      [`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, BILIBILI_COOKIES_REMOTE_PATH],
+      ["id -u", "0\n"],
+      [`base64 ${BILIBILI_COOKIES_REMOTE_PATH}`, tinyB64],
+    ]);
+    const ext = createBilibiliCookiesExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(/BILIBILI_COOKIES_TRUNCATED/);
+  });
+
+  it("BILIBILI_NOT_SQLITE when magic header missing", async () => {
+    // 2KB of non-sqlite garbage
+    const garbage = Buffer.alloc(2048, "X").toString("base64");
+    const ctx = fakeCtx([
+      [`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, BILIBILI_COOKIES_REMOTE_PATH],
+      ["id -u", "0\n"],
+      [`base64 ${BILIBILI_COOKIES_REMOTE_PATH}`, garbage],
+    ]);
+    const ext = createBilibiliCookiesExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(/BILIBILI_NOT_SQLITE/);
+  });
+
+  it("BILIBILI_COOKIES_INCOMPLETE when required cookies missing", async () => {
+    const b64 = buildCookiesAsBase64([
+      { name: "SESSDATA", value: "abc" },
+      { name: "bili_jct", value: "csrf" },
+      // missing DedeUserID + DedeUserID__ckMd5 + buvid3
+    ]);
+    const ctx = fakeCtx([
+      [`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, BILIBILI_COOKIES_REMOTE_PATH],
+      ["id -u", "0\n"],
+      [`base64 ${BILIBILI_COOKIES_REMOTE_PATH}`, b64],
+    ]);
+    const ext = createBilibiliCookiesExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(/BILIBILI_COOKIES_INCOMPLETE/);
+  });
+
+  it("BILIBILI_INVALID_UID when DedeUserID is non-numeric", async () => {
+    const b64 = buildCookiesAsBase64([
+      { name: "SESSDATA", value: "abc" },
+      { name: "bili_jct", value: "csrf" },
+      { name: "DedeUserID", value: "not-a-number" },
+      { name: "DedeUserID__ckMd5", value: "deadbeef" },
+      { name: "buvid3", value: "x" },
+    ]);
+    const ctx = fakeCtx([
+      [`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, BILIBILI_COOKIES_REMOTE_PATH],
+      ["id -u", "0\n"],
+      [`base64 ${BILIBILI_COOKIES_REMOTE_PATH}`, b64],
+    ]);
+    const ext = createBilibiliCookiesExtension();
+    await expect(ext({}, ctx)).rejects.toThrow(/BILIBILI_INVALID_UID/);
+  });
+});
+
+describe("bilibili.cookies extension — temp file cleanup", () => {
+  function countTempFiles() {
+    // Count cc-bilibili-cookies-*.db files in os.tmpdir() at the time
+    // of inspection. We snapshot before/after to compare delta.
+    try {
+      return readdirSync(tmpdir()).filter((n) =>
+        n.startsWith("cc-bilibili-cookies-"),
+      ).length;
+    } catch (_e) {
+      return 0;
+    }
+  }
+
+  it("removes temp file on success", async () => {
+    const before = countTempFiles();
+    const b64 = buildCookiesAsBase64(FULL_BILIBILI_COOKIES);
+    const ctx = fakeCtx([
+      [`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, BILIBILI_COOKIES_REMOTE_PATH],
+      ["id -u", "0\n"],
+      [`base64 ${BILIBILI_COOKIES_REMOTE_PATH}`, b64],
+    ]);
+    const ext = createBilibiliCookiesExtension();
+    await ext({}, ctx);
+    const after = countTempFiles();
+    expect(after).toBe(before);
+  });
+
+  it("removes temp file on parse failure", async () => {
+    const before = countTempFiles();
+    const b64 = buildCookiesAsBase64([
+      { name: "SESSDATA", value: "abc" }, // incomplete → throws
+    ]);
+    const ctx = fakeCtx([
+      [`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, BILIBILI_COOKIES_REMOTE_PATH],
+      ["id -u", "0\n"],
+      [`base64 ${BILIBILI_COOKIES_REMOTE_PATH}`, b64],
+    ]);
+    const ext = createBilibiliCookiesExtension();
+    await expect(ext({}, ctx)).rejects.toThrow();
+    const after = countTempFiles();
+    expect(after).toBe(before); // cleanup still ran via try/finally
+  });
+});
+
+describe("bilibili.cookies extension — ctx contract", () => {
+  it("throws TypeError when ctx missing adb fn", async () => {
+    const ext = createBilibiliCookiesExtension();
+    await expect(
+      ext({}, { pickDevice: async () => "x" }),
+    ).rejects.toThrow(TypeError);
+  });
+
+  it("throws TypeError when ctx missing pickDevice fn", async () => {
+    const ext = createBilibiliCookiesExtension();
+    await expect(
+      ext({}, { adb: async () => "" }),
+    ).rejects.toThrow(TypeError);
+  });
+});
+
+describe("bilibili.cookies extension — bridge integration", () => {
+  it("works through createHostAdbBridge plugin point", async () => {
+    // Use createHostAdbBridge to verify the extension actually dispatches
+    // via the host-adb-bridge plugin pipeline (Phase B0 contract).
+    const { createHostAdbBridge } = await import(
+      "../../../cli/src/lib/host-adb-bridge.js"
+    );
+    const b64 = buildCookiesAsBase64(FULL_BILIBILI_COOKIES);
+
+    // The real createHostAdbBridge uses its own internal adb fn (calls
+    // real `execFile`), which would fail on CI without a device. To
+    // smoke-test the dispatch wiring we construct an extension that
+    // ignores ctx and returns the same shape directly — that proves
+    // the bridge invokes our handler.
+    const ext = createBilibiliCookiesExtension();
+
+    // Replace the ctx that the real bridge would build by giving the
+    // extension a wrapper that swaps in our fake ctx.
+    const wrappedExt = (params, _realCtx) => ext(params, fakeCtxClosure());
+
+    function fakeCtxClosure() {
+      return fakeCtx([
+        [`ls ${BILIBILI_COOKIES_REMOTE_PATH}`, BILIBILI_COOKIES_REMOTE_PATH],
+        ["id -u", "0\n"],
+        [`base64 ${BILIBILI_COOKIES_REMOTE_PATH}`, b64],
+      ]);
+    }
+
+    const bridge = createHostAdbBridge({
+      extensions: { "bilibili.cookies": wrappedExt },
+    });
+
+    expect(bridge.extensionMethods()).toContain("bilibili.cookies");
+    const result = await bridge.invoke("bilibili.cookies");
+    expect(result.uid).toBe(1234567890);
+    expect(result.cookie).toContain("SESSDATA=");
+  });
+});

package/__tests__/adapters/social-bilibili-adb-snapshot-builder.test.js

@@ -0,0 +1,296 @@
+"use strict";
+
+/**
+ * Phase 1b — unit cover for snapshot-builder (API responses → snapshot JSON).
+ *
+ * What we cover:
+ *  - schemaVersion + snapshottedAt + account shape match adapter.js
+ *    snapshot mode contract
+ *  - 4 kinds (history/favourite/dynamic/follow) all populate correct fields
+ *  - capturedAt comes from the kind-specific field (viewAt / savedAt /
+ *    publishedAt / followedAt)
+ *  - id derivation: stable for items with bvid/rid/mid, fallback to index
+ *  - displayName defaults to empty string when omitted
+ *  - Edge cases: empty arrays / null items / missing fields don't crash
+ *  - writeSnapshotJson / cleanupSnapshotJson disk lifecycle
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { existsSync, readFileSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const {
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+  SNAPSHOT_SCHEMA_VERSION,
+} = require("../../lib/adapters/social-bilibili-adb/snapshot-builder");
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "cc-snapshot-test-"));
+});
+
+afterEach(() => {
+  try {
+    rmSync(tmpDir, { recursive: true, force: true });
+  } catch (_e) {
+    // ignore
+  }
+});
+
+// ─── buildSnapshot ──────────────────────────────────────────────────────
+
+describe("buildSnapshot — schema contract", () => {
+  it("returns the documented schema shape", () => {
+    const snap = buildSnapshot({
+      uid: 12345,
+      displayName: "alice",
+      history: [],
+      favourites: [],
+      dynamics: [],
+      follows: [],
+      snapshottedAt: 1716383021000,
+    });
+    expect(snap.schemaVersion).toBe(SNAPSHOT_SCHEMA_VERSION);
+    expect(snap.schemaVersion).toBe(1);
+    expect(snap.snapshottedAt).toBe(1716383021000);
+    expect(snap.account).toEqual({ uid: "12345", displayName: "alice" });
+    expect(Array.isArray(snap.events)).toBe(true);
+  });
+
+  it("converts uid to string in account", () => {
+    const snap = buildSnapshot({ uid: 42 });
+    expect(snap.account.uid).toBe("42");
+    expect(typeof snap.account.uid).toBe("string");
+  });
+
+  it("defaults displayName to empty string", () => {
+    const snap = buildSnapshot({ uid: 1 });
+    expect(snap.account.displayName).toBe("");
+  });
+
+  it("defaults snapshottedAt to Date.now() when omitted", () => {
+    const before = Date.now();
+    const snap = buildSnapshot({ uid: 1 });
+    const after = Date.now();
+    expect(snap.snapshottedAt).toBeGreaterThanOrEqual(before);
+    expect(snap.snapshottedAt).toBeLessThanOrEqual(after);
+  });
+
+  it("rejects non-positive uid", () => {
+    expect(() => buildSnapshot({ uid: 0 })).toThrow(TypeError);
+    expect(() => buildSnapshot({ uid: -1 })).toThrow(TypeError);
+    expect(() => buildSnapshot({ uid: "string" })).toThrow(TypeError);
+  });
+
+  it("rejects null / non-object input", () => {
+    expect(() => buildSnapshot(null)).toThrow(TypeError);
+    expect(() => buildSnapshot("string")).toThrow(TypeError);
+  });
+});
+
+describe("buildSnapshot — events", () => {
+  it("maps history items → kind=history events", () => {
+    const snap = buildSnapshot({
+      uid: 1,
+      history: [
+        {
+          bvid: "BV1xx",
+          avid: 100,
+          title: "Test",
+          viewAt: 1716383021,
+          duration: 300,
+          uploader: "u1",
+          uploaderMid: 999,
+          part: "Part1",
+        },
+      ],
+    });
+    expect(snap.events).toHaveLength(1);
+    expect(snap.events[0]).toMatchObject({
+      kind: "history",
+      id: "BV1xx",
+      capturedAt: 1716383021,
+      title: "Test",
+      bvid: "BV1xx",
+      avid: 100,
+      duration: 300,
+      uploader: "u1",
+      uploaderMid: 999,
+      part: "Part1",
+    });
+  });
+
+  it("maps favourite items → kind=favourite + id prefix", () => {
+    const snap = buildSnapshot({
+      uid: 1,
+      favourites: [
+        {
+          bvid: "BVfav1",
+          title: "F1",
+          savedAt: 1716383021000,
+          folderName: "MyFolder",
+          uploader: "u1",
+        },
+      ],
+    });
+    expect(snap.events[0].kind).toBe("favourite");
+    expect(snap.events[0].id).toBe("fav-BVfav1");
+    expect(snap.events[0].capturedAt).toBe(1716383021000);
+    expect(snap.events[0].folderName).toBe("MyFolder");
+  });
+
+  it("maps dynamic items → kind=dynamic + id prefix", () => {
+    const snap = buildSnapshot({
+      uid: 1,
+      dynamics: [
+        {
+          rid: "dyn-rid-1",
+          summary: "hi",
+          dynamicType: "av",
+          publishedAt: 1716383021000,
+          authorMid: 999,
+          authorName: "x",
+        },
+      ],
+    });
+    expect(snap.events[0].kind).toBe("dynamic");
+    expect(snap.events[0].id).toBe("dyn-dyn-rid-1");
+    expect(snap.events[0].capturedAt).toBe(1716383021000);
+    expect(snap.events[0].dynamicType).toBe("av");
+  });
+
+  it("maps follow items → kind=follow + id prefix + mid as string", () => {
+    const snap = buildSnapshot({
+      uid: 1,
+      follows: [
+        {
+          mid: 42,
+          uname: "Friend",
+          face: "https://x.png",
+          sign: "hi",
+          followedAt: 1716383021000,
+        },
+      ],
+    });
+    expect(snap.events[0].kind).toBe("follow");
+    expect(snap.events[0].id).toBe("follow-42");
+    expect(snap.events[0].mid).toBe("42");
+    expect(typeof snap.events[0].mid).toBe("string");
+  });
+
+  it("preserves event order: history → favourite → dynamic → follow", () => {
+    const snap = buildSnapshot({
+      uid: 1,
+      history: [{ bvid: "BV1", title: "h", viewAt: 1 }],
+      favourites: [{ bvid: "BV2", title: "f", savedAt: 2 }],
+      dynamics: [{ rid: "r1", summary: "d", dynamicType: "av", publishedAt: 3 }],
+      follows: [{ mid: 1, uname: "x", followedAt: 4 }],
+    });
+    const kinds = snap.events.map((e) => e.kind);
+    expect(kinds).toEqual(["history", "favourite", "dynamic", "follow"]);
+  });
+
+  it("uses snapshottedAt as fallback when capturedAt source is missing", () => {
+    const snap = buildSnapshot({
+      uid: 1,
+      snapshottedAt: 999,
+      history: [{ bvid: "BV1", title: "h" /* no viewAt */ }],
+    });
+    expect(snap.events[0].capturedAt).toBe(999);
+  });
+
+  it("uses index-based fallback id when key field missing", () => {
+    const snap = buildSnapshot({
+      uid: 1,
+      history: [{ title: "no bvid", viewAt: 1 }],
+      favourites: [{ title: "no bvid", savedAt: 1 }],
+      dynamics: [{ summary: "no rid", dynamicType: "av", publishedAt: 1 }],
+      follows: [{ uname: "no mid", followedAt: 1 }],
+    });
+    const ids = snap.events.map((e) => e.id);
+    expect(ids).toEqual(["history-0", "fav-0", "dyn-0", "follow-0"]);
+  });
+
+  it("skips null / non-object items", () => {
+    const snap = buildSnapshot({
+      uid: 1,
+      history: [null, { bvid: "BV1", title: "ok", viewAt: 1 }, undefined, "not an object"],
+    });
+    expect(snap.events).toHaveLength(1);
+    expect(snap.events[0].id).toBe("BV1");
+  });
+
+  it("handles empty / missing arrays", () => {
+    const snap = buildSnapshot({ uid: 1 });
+    expect(snap.events).toEqual([]);
+  });
+
+  it("handles non-array input fields gracefully", () => {
+    const snap = buildSnapshot({
+      uid: 1,
+      history: "not an array",
+      favourites: null,
+      dynamics: 42,
+      follows: { x: 1 },
+    });
+    expect(snap.events).toEqual([]);
+  });
+});
+
+// ─── writeSnapshotJson / cleanupSnapshotJson ────────────────────────────
+
+describe("writeSnapshotJson + cleanupSnapshotJson", () => {
+  it("writes JSON to default tmpdir path", () => {
+    const snap = buildSnapshot({ uid: 1 });
+    const filePath = writeSnapshotJson(snap);
+    expect(existsSync(filePath)).toBe(true);
+    expect(filePath).toContain("cc-bilibili-snapshot-");
+    expect(filePath).toMatch(/\.json$/);
+    const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+    expect(parsed.schemaVersion).toBe(1);
+    cleanupSnapshotJson(filePath);
+    expect(existsSync(filePath)).toBe(false);
+  });
+
+  it("respects custom dir", () => {
+    const snap = buildSnapshot({ uid: 1 });
+    const filePath = writeSnapshotJson(snap, { dir: tmpDir });
+    expect(filePath.startsWith(tmpDir)).toBe(true);
+    expect(existsSync(filePath)).toBe(true);
+  });
+
+  it("respects custom fileName", () => {
+    const snap = buildSnapshot({ uid: 1 });
+    const filePath = writeSnapshotJson(snap, {
+      dir: tmpDir,
+      fileName: "custom.json",
+    });
+    expect(filePath).toBe(join(tmpDir, "custom.json"));
+  });
+
+  it("rejects fileName with path separators", () => {
+    const snap = buildSnapshot({ uid: 1 });
+    expect(() =>
+      writeSnapshotJson(snap, { dir: tmpDir, fileName: "../escape.json" }),
+    ).toThrow(/must be a basename/);
+    expect(() =>
+      writeSnapshotJson(snap, { dir: tmpDir, fileName: "sub/path.json" }),
+    ).toThrow(/must be a basename/);
+  });
+
+  it("cleanupSnapshotJson is no-op on missing file", () => {
+    cleanupSnapshotJson(join(tmpDir, "nonexistent.json"));
+    // Should not throw
+  });
+
+  it("cleanupSnapshotJson tolerates null / empty", () => {
+    cleanupSnapshotJson(null);
+    cleanupSnapshotJson("");
+    cleanupSnapshotJson(undefined);
+    // Should not throw
+  });
+});