chainlesschain 0.162.12 → 0.162.14

package/src/lib/__tests__/sync-engine-cli.test.js

@@ -0,0 +1,293 @@
+/**
+ * sync-engine-cli 单元测试 — Phase 3c follow-up Phase 2.
+ *
+ * 用 sql.js 内存 SQLite 模拟 dbManager.run/all/get；fake client；验证
+ * runSync 完整管线（push / conflict / hard error / tombstone drain /
+ * cursor 推进）。
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, vi } from "vitest";
+
+import {
+  runSync,
+  generateFilename,
+  generateMarkdown,
+  getCursor,
+  ensureCursor,
+  listTombstones,
+} from "../sync-engine-cli.js";
+
+class SqlJsDbManager {
+  constructor(db) {
+    this.db = db;
+  }
+  run(sql, params = []) {
+    this.db.run(sql, params);
+  }
+  get(sql, params = []) {
+    const stmt = this.db.prepare(sql);
+    stmt.bind(params);
+    let row;
+    if (stmt.step()) row = stmt.getAsObject();
+    stmt.free();
+    return row;
+  }
+  all(sql, params = []) {
+    const stmt = this.db.prepare(sql);
+    stmt.bind(params);
+    const rows = [];
+    while (stmt.step()) rows.push(stmt.getAsObject());
+    stmt.free();
+    return rows;
+  }
+}
+
+let SQL;
+let dbManager;
+
+beforeAll(async () => {
+  const initSqlJs = (await import("sql.js")).default;
+  SQL = await initSqlJs();
+});
+
+beforeEach(() => {
+  const db = new SQL.Database();
+  db.exec(`
+    CREATE TABLE knowledge_items (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      type TEXT NOT NULL DEFAULT 'note',
+      content TEXT,
+      tags TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE TABLE sync_external_provider_cursor (
+      provider_id TEXT NOT NULL,
+      account_key TEXT NOT NULL DEFAULT '',
+      last_sync_at INTEGER NOT NULL DEFAULT 0,
+      last_item_id TEXT,
+      remote_etag_map TEXT NOT NULL DEFAULT '{}',
+      remote_filename_map TEXT NOT NULL DEFAULT '{}',
+      last_run_status TEXT,
+      last_run_error TEXT,
+      last_run_duration_ms INTEGER,
+      items_pushed INTEGER NOT NULL DEFAULT 0,
+      items_skipped INTEGER NOT NULL DEFAULT 0,
+      items_deleted INTEGER NOT NULL DEFAULT 0,
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000),
+      updated_at INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000),
+      PRIMARY KEY (provider_id, account_key)
+    );
+    CREATE TABLE sync_external_tombstones (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      provider_id TEXT NOT NULL,
+      account_key TEXT NOT NULL DEFAULT '',
+      item_id TEXT NOT NULL,
+      resource_type TEXT,
+      deleted_at INTEGER NOT NULL,
+      retry_count INTEGER NOT NULL DEFAULT 0,
+      last_error TEXT,
+      UNIQUE(provider_id, account_key, item_id)
+    );
+    CREATE TRIGGER trg_sync_ext_tombstone_on_delete
+    AFTER DELETE ON knowledge_items
+    FOR EACH ROW
+    BEGIN
+      INSERT OR IGNORE INTO sync_external_tombstones
+        (provider_id, account_key, item_id, resource_type, deleted_at)
+      SELECT c.provider_id, c.account_key, OLD.id, 'KNOWLEDGE_ITEM',
+             (strftime('%s','now') * 1000)
+      FROM sync_external_provider_cursor c;
+    END;
+  `);
+  dbManager = new SqlJsDbManager(db);
+});
+
+function seedItems(items) {
+  for (const it of items) {
+    dbManager.run(
+      `INSERT INTO knowledge_items (id, title, type, content, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [
+        it.id,
+        it.title,
+        it.type ?? "note",
+        it.content ?? "body",
+        it.created_at ?? 1,
+        it.updated_at ?? 100,
+      ],
+    );
+  }
+}
+
+function makeFakeClient(overrides = {}) {
+  return {
+    putFile: vi.fn(
+      overrides.putFile ?? (async () => ({ ok: true, etag: "new-etag" })),
+    ),
+    deleteFile: vi.fn(overrides.deleteFile ?? (async () => ({ ok: true }))),
+  };
+}
+
+const baseDeps = () => ({ dbManager, providerId: "webdav", accountKey: "" });
+
+describe("sync-engine-cli · renderer helpers", () => {
+  it("generateFilename cleans unsafe chars + collapses runs", () => {
+    const fn = generateFilename({ id: "abc", title: "My / cool: note?" });
+    expect(fn).toBe("abc-My_cool_note.md");
+  });
+
+  it("generateMarkdown emits front-matter", () => {
+    const md = generateMarkdown({
+      id: "x",
+      title: "T",
+      type: "note",
+      content: "body",
+      created_at: 1,
+      updated_at: 2,
+      tags: "a,b",
+    });
+    expect(md).toContain("---");
+    expect(md).toContain('title: "T"');
+    expect(md).toContain("tags: a,b");
+    expect(md.endsWith("body\n")).toBe(true);
+  });
+});
+
+describe("sync-engine-cli · ensureCursor + getCursor", () => {
+  it("ensureCursor creates row + returns it", () => {
+    const cursor = ensureCursor(dbManager, "webdav");
+    expect(cursor).toBeDefined();
+    expect(cursor.providerId).toBe("webdav");
+    expect(cursor.itemsPushed).toBe(0);
+  });
+
+  it("getCursor returns undefined when missing", () => {
+    expect(getCursor(dbManager, "oss")).toBeUndefined();
+  });
+});
+
+describe("sync-engine-cli · runSync happy path", () => {
+  it("pushes all items + advances cursor", async () => {
+    seedItems([
+      { id: "a", title: "A", updated_at: 100 },
+      { id: "b", title: "B", updated_at: 200 },
+    ]);
+    const client = makeFakeClient();
+    const res = await runSync({ ...baseDeps(), client });
+    expect(res.success).toBe(true);
+    expect(res.status).toBe("success");
+    expect(res.pushed).toBe(2);
+    expect(client.putFile).toHaveBeenCalledTimes(2);
+    const cursor = getCursor(dbManager, "webdav");
+    expect(cursor.lastItemId).toBe("b");
+    expect(cursor.itemsPushed).toBe(2);
+  });
+
+  it("re-run from advanced cursor pushes nothing new", async () => {
+    seedItems([{ id: "a", title: "A", updated_at: 100 }]);
+    const client = makeFakeClient();
+    await runSync({ ...baseDeps(), client });
+    client.putFile.mockClear();
+    const r2 = await runSync({ ...baseDeps(), client });
+    expect(r2.pushed).toBe(0);
+    expect(client.putFile).not.toHaveBeenCalled();
+  });
+
+  it("sends If-Match etag on modified item", async () => {
+    seedItems([{ id: "a", title: "A", updated_at: 100 }]);
+    const client = makeFakeClient();
+    await runSync({ ...baseDeps(), client });
+    dbManager.run(`UPDATE knowledge_items SET updated_at = 999 WHERE id = 'a'`);
+    client.putFile.mockClear();
+    await runSync({ ...baseDeps(), client });
+    expect(client.putFile).toHaveBeenCalledWith(
+      "a-A.md",
+      expect.any(String),
+      "new-etag",
+    );
+  });
+});
+
+describe("sync-engine-cli · conflict path (412)", () => {
+  it("412 → skipped + cursor advances + status=conflict", async () => {
+    seedItems([
+      { id: "a", title: "A", updated_at: 100 },
+      { id: "b", title: "B", updated_at: 200 },
+    ]);
+    const client = makeFakeClient({
+      putFile: vi.fn(async (fn) =>
+        fn === "a-A.md"
+          ? { ok: false, conflict: true, status: 412 }
+          : { ok: true, etag: "e" },
+      ),
+    });
+    const res = await runSync({ ...baseDeps(), client });
+    expect(res.status).toBe("conflict");
+    expect(res.pushed).toBe(1);
+    expect(res.skipped).toBe(1);
+    expect(getCursor(dbManager, "webdav").lastItemId).toBe("b");
+  });
+});
+
+describe("sync-engine-cli · hard error stops loop", () => {
+  it("4xx non-conflict → no advance past failure point", async () => {
+    seedItems([
+      { id: "a", title: "A", updated_at: 100 },
+      { id: "b", title: "B", updated_at: 200 },
+    ]);
+    const client = makeFakeClient({
+      putFile: vi.fn(async (fn) =>
+        fn === "b-B.md"
+          ? { ok: false, status: 403, error: "forbidden" }
+          : { ok: true, etag: "e" },
+      ),
+    });
+    const res = await runSync({ ...baseDeps(), client });
+    expect(res.success).toBe(false);
+    expect(res.status).toBe("failed");
+    expect(res.pushed).toBe(1);
+    expect(res.error).toMatch(/forbidden/);
+    expect(getCursor(dbManager, "webdav").lastItemId).toBe("a");
+  });
+});
+
+describe("sync-engine-cli · tombstone drain", () => {
+  it("drains tombstones via deleteFile + cleans maps", async () => {
+    seedItems([{ id: "a", title: "A", updated_at: 100 }]);
+    const client = makeFakeClient();
+    await runSync({ ...baseDeps(), client });
+    dbManager.run(`DELETE FROM knowledge_items WHERE id = 'a'`);
+    const res = await runSync({ ...baseDeps(), client });
+    expect(res.deleted).toBe(1);
+    expect(client.deleteFile).toHaveBeenCalledWith("a-A.md", "new-etag");
+    expect(listTombstones(dbManager, "webdav")).toHaveLength(0);
+  });
+});
+
+describe("sync-engine-cli · provider isolation", () => {
+  it("oss cursor independent of webdav cursor", async () => {
+    seedItems([{ id: "a", title: "A", updated_at: 100 }]);
+    const client = makeFakeClient();
+    await runSync({ dbManager, client, providerId: "webdav", accountKey: "" });
+    const webdav = getCursor(dbManager, "webdav");
+    const oss = getCursor(dbManager, "oss");
+    expect(webdav.itemsPushed).toBe(1);
+    expect(oss).toBeUndefined();
+  });
+});
+
+describe("sync-engine-cli · progress callback", () => {
+  it("emits start + final events", async () => {
+    seedItems([{ id: "a", title: "A", updated_at: 100 }]);
+    const events = [];
+    await runSync({
+      ...baseDeps(),
+      client: makeFakeClient(),
+      onProgress: (e) => events.push(e),
+    });
+    expect(events.find((e) => e.phase === "start")).toBeDefined();
+    expect(events[events.length - 1].phase).toBe("success");
+  });
+});

package/src/lib/cc-android-bridge.js

@@ -0,0 +1,162 @@
+/**
+ * cc-android-bridge — Node-side facade for the Android JNI bridge.
+ *
+ * Plan A Sub-Phase A6/A7 scaffold (see `docs/design/Personal_Data_Hub_Android_Standalone_Cc.md`
+ * §4.2 + §6.1). The eventual native binding (`cc-android-bridge.node`,
+ * loaded from `android-app/app/src/main/cpp/`) exposes Java/Kotlin APIs to
+ * the in-APK Node runtime: ContentResolver query, PackageManager listings,
+ * Runtime.exec / Shizuku / Magisk su, Accessibility node tree, SAF DocumentFile
+ * read.
+ *
+ * **v0.1 status**: the native .node binding is NOT yet shipped. This file is
+ * a pure stub — every `invoke()` call rejects with ANDROID_BRIDGE_NOT_AVAILABLE.
+ * It exists so the `cc android …` commands and `system-data-android` adapter
+ * (A7 / A8) can land + be unit-tested ahead of the JNI work. When A6 ships
+ * the .node binding, this file's `loadNativeBinding()` will resolve the real
+ * module; method dispatch is already wired.
+ *
+ * Detection precedence (highest first):
+ *   1. process.env.CC_ANDROID_BRIDGE_OVERRIDE === "1" — test override; bridge
+ *      reports "available" and routes through `_deps.testInvoke` (which tests
+ *      replace with a mock). Lets us exercise the command code paths without
+ *      a real device.
+ *   2. process.platform === "android"
+ *   3. process.env.PREFIX startsWith "/data/data/com.chainlesschain.android/"
+ *      (Termux $PREFIX pattern in the bundled cc).
+ *
+ * Method names are kebab-case to match the `cc android <verb>` CLI surface,
+ * not the underlying JNI signatures (those use Java camelCase). Mapping
+ * happens in the future native binding.
+ */
+
+import { createRequire } from "node:module";
+
+const ANDROID_PREFIX = "/data/data/com.chainlesschain.android/";
+const nodeRequire = createRequire(import.meta.url);
+
+export function detectAndroid() {
+  if (process.env.CC_ANDROID_BRIDGE_OVERRIDE === "1") return true;
+  if (process.platform === "android") return true;
+  if (
+    typeof process.env.PREFIX === "string" &&
+    process.env.PREFIX.startsWith(ANDROID_PREFIX)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Lazy-load the native .node binding when we're actually on Android. Stays
+ * null elsewhere. The binding is expected at:
+ *   $APK/lib/<abi>/cc-android-bridge.node
+ * resolved via require.resolve("cc-android-bridge").
+ *
+ * Wrapped in try so a missing binding (current state pre-A6) doesn't crash
+ * the CLI on import — `invoke()` reports it as a runtime error instead.
+ */
+export function loadNativeBinding() {
+  if (!detectAndroid()) return null;
+  if (process.env.CC_ANDROID_BRIDGE_OVERRIDE === "1") return null;
+  try {
+    return nodeRequire("cc-android-bridge");
+  } catch (_e) {
+    return null;
+  }
+}
+
+export class AndroidBridgeUnavailableError extends Error {
+  constructor(reason) {
+    super(`ANDROID_BRIDGE_NOT_AVAILABLE: ${reason}`);
+    this.code = "ANDROID_BRIDGE_NOT_AVAILABLE";
+    this.reason = reason;
+  }
+}
+
+/**
+ * Invoke a bridge method.
+ *
+ * @param {string} method — kebab-case method name (e.g. "contacts.query",
+ *   "fs.read", "a11y.query", "app.list").
+ * @param {object} [params]
+ * @returns {Promise<any>}
+ *
+ * Rejects with AndroidBridgeUnavailableError when:
+ *  - Not running on Android (and CC_ANDROID_BRIDGE_OVERRIDE != 1)
+ *  - Running on Android but native binding failed to load
+ *  - Method is not registered in the native binding
+ */
+export async function invoke(method, params = {}) {
+  if (typeof method !== "string" || method.length === 0) {
+    throw new TypeError(
+      "cc-android-bridge.invoke: method must be non-empty string",
+    );
+  }
+
+  // Test path — _deps.testInvoke replaced by harness.
+  if (
+    process.env.CC_ANDROID_BRIDGE_OVERRIDE === "1" &&
+    typeof _deps.testInvoke === "function"
+  ) {
+    return await _deps.testInvoke(method, params);
+  }
+
+  if (!_deps.detectAndroid()) {
+    throw new AndroidBridgeUnavailableError(
+      `not running on Android (platform=${process.platform})`,
+    );
+  }
+
+  const native = _deps.loadNativeBinding();
+  if (!native) {
+    throw new AndroidBridgeUnavailableError(
+      "native binding cc-android-bridge.node missing — A6 JNI module not yet bundled",
+    );
+  }
+  if (typeof native.invoke !== "function") {
+    throw new AndroidBridgeUnavailableError(
+      "native binding loaded but does not export invoke()",
+    );
+  }
+  return await native.invoke(method, params);
+}
+
+/**
+ * Check whether the bridge is usable right now without throwing.
+ * Returns `{ available: boolean, reason?: string }`.
+ */
+export function caps() {
+  if (process.env.CC_ANDROID_BRIDGE_OVERRIDE === "1") {
+    return { available: true, reason: "test-override" };
+  }
+  if (!_deps.detectAndroid()) {
+    return {
+      available: false,
+      reason: `not-on-android (platform=${process.platform})`,
+    };
+  }
+  const native = _deps.loadNativeBinding();
+  if (!native) {
+    return {
+      available: false,
+      reason: "native-binding-missing (A6 pending)",
+    };
+  }
+  return { available: true };
+}
+
+// _deps injection seam (per [[feedback-vi-mock-cjs-interop]]). Tests reach in
+// and replace these to exercise both success + error paths without needing
+// a real Android device or the unloaded native binding.
+export const _deps = {
+  detectAndroid,
+  loadNativeBinding,
+  testInvoke: null,
+};
+
+export default {
+  invoke,
+  caps,
+  AndroidBridgeUnavailableError,
+  _deps,
+};

package/src/lib/personal-data-hub-aichat-wizard.js

@@ -0,0 +1,242 @@
+/**
+ * AIChat WebView 鉴权向导 — cli / web-shell wiring (Phase 10.3.4).
+ *
+ * Mirrors `desktop-app-vue/src/main/personal-data-hub/aichat-wizard-factory.js`
+ * for the cli + web-shell side. Two structural differences from desktop:
+ *
+ *   1) `fallbackMode: "paste"` is hard-wired — cc ui does NOT have a
+ *      BrowserView, so the wizard always returns the paste fallback shape.
+ *
+ *   2) Accounts store path lives under `getHub().hubDir`, same JSON file
+ *      shape as desktop (`aichat-accounts.json`). Same hub directory on
+ *      the same machine means desktop / cc ui share registered vendors
+ *      (per the memo about WAL sharing — same caveat applies).
+ *
+ * Reference: docs/design/Personal_Data_Hub_Phase_10_3_AIChat_WebView_Wizard.md §2 §11
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+
+import {
+  DEFAULT_VENDOR_SPECS,
+  HttpClient,
+  CookieAuthSession,
+} from "@chainlesschain/personal-data-hub/adapters/ai-chat-history";
+
+const _require = createRequire(import.meta.url);
+
+export const ACCOUNTS_FILE = "aichat-accounts.json";
+
+/**
+ * JSON file accountsStore (same on-disk shape as desktop). Async API but
+ * implemented sync underneath — concurrent put() ops are chained.
+ */
+export function createAccountsStore({ hubDir }) {
+  if (!hubDir || typeof hubDir !== "string") {
+    throw new Error("aichat-wizard-cli: hubDir required");
+  }
+  const filePath = join(hubDir, ACCOUNTS_FILE);
+  let writeChain = Promise.resolve();
+
+  function _readAll() {
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      return parsed && typeof parsed === "object" ? parsed : {};
+    } catch (err) {
+      if (err && err.code === "ENOENT") return {};
+      return {};
+    }
+  }
+
+  async function get(vendor) {
+    return _readAll()[vendor] || null;
+  }
+
+  async function put(vendor, entry) {
+    writeChain = writeChain.then(async () => {
+      const all = _readAll();
+      all[vendor] = entry;
+      try {
+        mkdirSync(hubDir, { recursive: true, mode: 0o700 });
+      } catch (err) {
+        if (!err || err.code !== "EEXIST") throw err;
+      }
+      writeFileSync(filePath, JSON.stringify(all, null, 2), { mode: 0o600 });
+    });
+    return writeChain;
+  }
+
+  async function del(vendor) {
+    writeChain = writeChain.then(async () => {
+      const all = _readAll();
+      if (!(vendor in all)) return;
+      delete all[vendor];
+      if (Object.keys(all).length === 0) {
+        try {
+          unlinkSync(filePath);
+        } catch (_e) {
+          /* missing is fine */
+        }
+      } else {
+        writeFileSync(filePath, JSON.stringify(all, null, 2), { mode: 0o600 });
+      }
+    });
+    return writeChain;
+  }
+
+  async function list() {
+    return Object.values(_readAll());
+  }
+
+  return { get, put, delete: del, list, _filePath: filePath };
+}
+
+/**
+ * Same bridge as desktop — translates wizard.registerVendor() into
+ * spec.validateCookie(). Kept duplicated so the cli build stays ESM-pure
+ * without reaching into desktop-app-vue.
+ */
+export function createVendorAdapterBridge({
+  specs = DEFAULT_VENDOR_SPECS,
+  _httpClientFactory,
+} = {}) {
+  // DEFAULT_VENDOR_SPECS is shipped as a vendor-keyed object; tests pass an
+  // array. Normalize to an array first so byVendor lookup works either way.
+  const arr = Array.isArray(specs)
+    ? specs
+    : specs && typeof specs === "object"
+      ? Object.values(specs)
+      : null;
+  if (!arr || arr.length === 0) {
+    throw new Error("aichat-wizard-cli: specs required");
+  }
+  const byVendor = new Map();
+  for (const s of arr) {
+    if (s && typeof s.name === "string") byVendor.set(s.name, s);
+  }
+  const buildClient =
+    _httpClientFactory ||
+    ((vendor, spec) => new HttpClient({ vendor, rateLimits: spec.rateLimits }));
+
+  async function registerVendor(vendor, cookies, _opts = {}) {
+    const spec = byVendor.get(vendor);
+    if (!spec) return { ok: false, reason: "UNKNOWN_VENDOR" };
+    if (typeof spec.validateCookie !== "function") {
+      return { ok: false, reason: "SPEC_MISSING_VALIDATE_COOKIE" };
+    }
+    let client;
+    try {
+      client = buildClient(vendor, spec);
+    } catch (err) {
+      return {
+        ok: false,
+        reason: "HTTP_CLIENT_INIT_FAILED",
+        error: err.message,
+      };
+    }
+    const session = new CookieAuthSession({
+      vendor,
+      cookies: _jarToArray(cookies),
+    });
+    try {
+      const r = await spec.validateCookie({ httpClient: client, session });
+      return r || { ok: false, reason: "VALIDATE_RETURNED_NULL" };
+    } catch (err) {
+      return { ok: false, reason: "VALIDATE_THREW", error: err.message };
+    }
+  }
+
+  return { registerVendor };
+}
+
+export function _jarToArray(input) {
+  if (Array.isArray(input)) {
+    return input.filter(
+      (c) => c && typeof c.name === "string" && typeof c.value === "string",
+    );
+  }
+  if (typeof input === "string") {
+    const out = [];
+    for (const pair of input.split(/;\s*/)) {
+      const idx = pair.indexOf("=");
+      if (idx <= 0) continue;
+      const name = pair.slice(0, idx).trim();
+      const value = pair.slice(idx + 1).trim();
+      if (name && value) out.push({ name, value });
+    }
+    return out;
+  }
+  if (input && typeof input === "object") {
+    const out = [];
+    for (const [name, value] of Object.entries(input)) {
+      if (typeof value === "string" && value.length > 0)
+        out.push({ name, value });
+    }
+    return out;
+  }
+  return [];
+}
+
+const _wizardsByHubDir = new Map();
+
+/**
+ * cli-side wizard singleton. Always builds in `fallbackMode: "paste"` —
+ * cc ui never opens a BrowserView. Tests substitute `_accountsStore` and
+ * `_vendorAdapter` for hermetic runs.
+ */
+export function getAIChatWizard({
+  hubDir,
+  _accountsStore,
+  _vendorAdapter,
+  _deps,
+} = {}) {
+  if (!hubDir) throw new Error("aichat-wizard-cli: hubDir required");
+  const isTest = !!(_accountsStore || _vendorAdapter || _deps);
+  if (!isTest && _wizardsByHubDir.has(hubDir))
+    return _wizardsByHubDir.get(hubDir);
+
+  const accountsStore = _accountsStore || createAccountsStore({ hubDir });
+  const vendorAdapter = _vendorAdapter || createVendorAdapterBridge();
+  // Paste-mode is the default for cli. Tests can override via _deps.
+  const deps = _deps || {
+    sessionFactory: () => ({}),
+    clock: () => Date.now(),
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+    fallbackMode: "paste",
+  };
+  if (deps && !deps.fallbackMode) deps.fallbackMode = "paste";
+  // The controller resolves classifier / specLookup / knownVendors itself
+  // when _deps doesn't supply them — but since we ARE supplying _deps, we
+  // must fill those slots too. Re-import the spec module to avoid coupling
+  // tests to those exact defaults.
+  if (!deps.classifier || !deps.specLookup) {
+    // Lazy require to keep top-of-file clean.
+    const spec = _require(
+      "@chainlesschain/personal-data-hub/adapters/ai-chat-history/cookie-capture-spec",
+    );
+    deps.classifier = deps.classifier || spec.classifyProbedCookies;
+    deps.specLookup = deps.specLookup || spec.getSpec;
+    deps.knownVendors = deps.knownVendors || spec.listVendors();
+    deps.cookieSpecVersion = deps.cookieSpecVersion || spec.COOKIE_SPEC_VERSION;
+  }
+  // Lazy require (same pattern as cookie-capture-spec above) — keeps
+  // module-load tolerant of older @chainlesschain/personal-data-hub
+  // versions that don't yet export this subpath.
+  const { createAIChatWizardController } = _require(
+    "@chainlesschain/personal-data-hub/adapters/ai-chat-history/wizard-controller",
+  );
+  const wiz = createAIChatWizardController({
+    accountsStore,
+    vendorAdapter,
+    _deps: deps,
+  });
+  if (!isTest) _wizardsByHubDir.set(hubDir, wiz);
+  return wiz;
+}
+
+export function _resetForTests() {
+  _wizardsByHubDir.clear();
+}