@chainlesschain/personal-data-hub 0.1.0

package/__tests__/bridges-cc-llm.test.js

@@ -0,0 +1,191 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { CcLLMAdapter, LOCAL_PROVIDERS } = require("../lib/bridges/cc-llm-adapter");
+const { AnalysisEngine } = require("../lib/analysis");
+
+describe("CcLLMAdapter construction", () => {
+  it("requires chat function", () => {
+    expect(() => new CcLLMAdapter()).toThrow();
+    expect(() => new CcLLMAdapter({})).toThrow(/chat/);
+  });
+
+  it("constructs with just chat", () => {
+    const a = new CcLLMAdapter({ chat: async () => ({}) });
+    expect(a.name).toBe("cc-llm"); // no provider/model getters → default name
+  });
+});
+
+describe("CcLLMAdapter.isLocal", () => {
+  it("returns true for ollama / llama-cpp / lm-studio / vllm-local", () => {
+    for (const p of ["ollama", "llama-cpp", "llamacpp", "vllm-local", "lm-studio", "lmstudio"]) {
+      const a = new CcLLMAdapter({
+        chat: async () => ({}),
+        getActiveProvider: () => p,
+      });
+      expect(a.isLocal).toBe(true);
+    }
+  });
+
+  it("returns false for openai / anthropic / volcengine / etc.", () => {
+    for (const p of ["openai", "anthropic", "volcengine", "gemini", "deepseek"]) {
+      const a = new CcLLMAdapter({
+        chat: async () => ({}),
+        getActiveProvider: () => p,
+      });
+      expect(a.isLocal).toBe(false);
+    }
+  });
+
+  it("returns false (conservative) when no provider getter is wired", () => {
+    const a = new CcLLMAdapter({ chat: async () => ({}) });
+    expect(a.isLocal).toBe(false);
+  });
+
+  it("getActiveProvider throws → fall through to false (defensive)", () => {
+    const a = new CcLLMAdapter({
+      chat: async () => ({}),
+      getActiveProvider: () => { throw new Error("oops"); },
+    });
+    expect(a.isLocal).toBe(false);
+  });
+
+  it("custom localProviders override the default whitelist", () => {
+    const a = new CcLLMAdapter({
+      chat: async () => ({}),
+      getActiveProvider: () => "my-private-cluster",
+      localProviders: ["my-private-cluster"],
+    });
+    expect(a.isLocal).toBe(true);
+  });
+
+  it("LOCAL_PROVIDERS contains the documented set", () => {
+    expect(LOCAL_PROVIDERS.has("ollama")).toBe(true);
+    expect(LOCAL_PROVIDERS.has("llama-cpp")).toBe(true);
+    expect(LOCAL_PROVIDERS.has("vllm-local")).toBe(true);
+    expect(LOCAL_PROVIDERS.has("openai")).toBe(false);
+  });
+});
+
+describe("CcLLMAdapter.name", () => {
+  it("uses opts.name override when provided", () => {
+    const a = new CcLLMAdapter({ chat: async () => ({}), name: "my-name" });
+    expect(a.name).toBe("my-name");
+  });
+
+  it("composes provider:model when both getters available", () => {
+    const a = new CcLLMAdapter({
+      chat: async () => ({}),
+      getActiveProvider: () => "ollama",
+      getActiveModel: () => "qwen2.5:7b",
+    });
+    expect(a.name).toBe("ollama:qwen2.5:7b");
+  });
+
+  it("falls back to model only when no provider", () => {
+    const a = new CcLLMAdapter({
+      chat: async () => ({}),
+      getActiveModel: () => "qwen",
+    });
+    expect(a.name).toBe("qwen");
+  });
+});
+
+describe("CcLLMAdapter.chat response normalization", () => {
+  it("extracts text from .content (cc llm-manager shape)", async () => {
+    const a = new CcLLMAdapter({
+      chat: async () => ({ content: "hi from cc", model: "qwen", usage: { promptTokens: 5, completionTokens: 3 } }),
+      getActiveModel: () => "qwen",
+    });
+    const r = await a.chat([{ role: "user", content: "x" }]);
+    expect(r.text).toBe("hi from cc");
+    expect(r.model).toBe("qwen");
+    expect(r.usage.promptTokens).toBe(5);
+    expect(r.usage.completionTokens).toBe(3);
+    expect(r.usage.totalTokens).toBe(8);
+  });
+
+  it("extracts text from .message.content (raw provider)", async () => {
+    const a = new CcLLMAdapter({
+      chat: async () => ({ message: { role: "assistant", content: "from msg" } }),
+    });
+    const r = await a.chat([]);
+    expect(r.text).toBe("from msg");
+  });
+
+  it("extracts text from .text (alt shape)", async () => {
+    const a = new CcLLMAdapter({ chat: async () => ({ text: "alt shape" }) });
+    const r = await a.chat([]);
+    expect(r.text).toBe("alt shape");
+  });
+
+  it("extracts text from OpenAI-style .choices[0].message.content", async () => {
+    const a = new CcLLMAdapter({
+      chat: async () => ({
+        choices: [{ message: { content: "openai-like" } }],
+      }),
+    });
+    const r = await a.chat([]);
+    expect(r.text).toBe("openai-like");
+  });
+
+  it("returns empty text for unknown shape (doesn't throw)", async () => {
+    const a = new CcLLMAdapter({ chat: async () => ({ random: "blob" }) });
+    const r = await a.chat([]);
+    expect(r.text).toBe("");
+  });
+
+  it("normalizes snake_case usage (prompt_tokens) to camelCase", async () => {
+    const a = new CcLLMAdapter({
+      chat: async () => ({
+        content: "x",
+        usage: { prompt_tokens: 10, completion_tokens: 20, total_tokens: 30 },
+      }),
+    });
+    const r = await a.chat([]);
+    expect(r.usage).toEqual({ promptTokens: 10, completionTokens: 20, totalTokens: 30 });
+  });
+
+  it("wraps underlying chat errors with cause preserved", async () => {
+    const a = new CcLLMAdapter({
+      chat: async () => { throw new Error("upstream Ollama died"); },
+    });
+    await expect(a.chat([])).rejects.toThrow(/underlying client failed/);
+  });
+
+  it("validates messages is an array", async () => {
+    const a = new CcLLMAdapter({ chat: async () => ({}) });
+    await expect(a.chat("not an array")).rejects.toThrow(/array/);
+  });
+});
+
+describe("CcLLMAdapter ↔ AnalysisEngine integration", () => {
+  it("AnalysisEngine accepts CcLLMAdapter (local-provider path)", () => {
+    const a = new CcLLMAdapter({
+      chat: async () => ({ content: "ok" }),
+      getActiveProvider: () => "ollama",
+    });
+    // Construction shouldn't throw — isLocal:true means engine accepts.
+    const fakeVault = {
+      audit: () => {},
+      queryEvents: () => [],
+      getWatermark: () => null,
+    };
+    expect(() => new AnalysisEngine({ vault: fakeVault, llm: a })).not.toThrow();
+  });
+
+  it("AnalysisEngine refuses CcLLMAdapter when provider is non-local without opt-in", async () => {
+    const a = new CcLLMAdapter({
+      chat: async () => ({ content: "ok" }),
+      getActiveProvider: () => "anthropic",
+    });
+    const fakeVault = {
+      audit: () => {},
+      queryEvents: () => [],
+      getWatermark: () => null,
+    };
+    const e = new AnalysisEngine({ vault: fakeVault, llm: a });
+    await expect(e.ask("test")).rejects.toThrow(/non-local/);
+  });
+});

package/__tests__/bridges-cc-rag.test.js

@@ -0,0 +1,162 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { CcRagSink } = require("../lib/bridges/cc-rag-sink");
+
+// Mirror BM25.addDocument shape — captures everything for assertion
+function makeFakeBm25() {
+  const docs = [];
+  return {
+    docs,
+    addDocument(doc) {
+      docs.push({ ...doc });
+    },
+  };
+}
+
+const doc = (id, text, type = "event", metadata = {}) => ({
+  id,
+  type,
+  text,
+  metadata,
+});
+
+// ─── Tests ──────────────────────────────────────────────────────────────
+
+describe("CcRagSink construction", () => {
+  it("requires bm25 with addDocument", () => {
+    expect(() => new CcRagSink()).toThrow();
+    expect(() => new CcRagSink({})).toThrow(/bm25/);
+    expect(() => new CcRagSink({ bm25: {} })).toThrow(/addDocument/);
+  });
+
+  it("accepts bm25 with addDocument; optional vector + logger + transformDoc", () => {
+    const bm25 = makeFakeBm25();
+    const s = new CcRagSink({
+      bm25,
+      vector: { index: async () => {} },
+      logger: () => {},
+      transformDoc: (d) => d,
+    });
+    expect(s).toBeDefined();
+  });
+});
+
+describe("CcRagSink.write", () => {
+  it("indexes docs to BM25 in cc-expected shape", async () => {
+    const bm25 = makeFakeBm25();
+    const sink = new CcRagSink({ bm25 });
+    const r = await sink.write([
+      doc("evt-1", "妈妈生日蛋白粉 +288.50 CNY", "event", { subtype: "order", adapter: "taobao" }),
+      doc("evt-2", "按摩仪 给妈妈", "event", { subtype: "order", adapter: "taobao" }),
+    ]);
+    expect(r.indexed).toBe(2);
+    expect(r.skipped).toBe(0);
+    expect(bm25.docs.length).toBe(2);
+    expect(bm25.docs[0].id).toBe("evt-1");
+    expect(bm25.docs[0].content).toContain("妈妈生日蛋白粉");
+    expect(bm25.docs[0].title).toBe("order"); // metadata.subtype used as title
+    expect(bm25.docs[0].meta.adapter).toBe("taobao");
+    expect(bm25.docs[0].hubType).toBe("event");
+  });
+
+  it("falls back to hub type as title when no metadata.title/.subtype", async () => {
+    const bm25 = makeFakeBm25();
+    const sink = new CcRagSink({ bm25 });
+    await sink.write([doc("p-1", "妈妈 陈某某", "person", {})]);
+    expect(bm25.docs[0].title).toBe("person");
+  });
+
+  it("metadata.title overrides subtype/type", async () => {
+    const bm25 = makeFakeBm25();
+    const sink = new CcRagSink({ bm25 });
+    await sink.write([doc("x", "body", "event", { title: "custom title", subtype: "order" })]);
+    expect(bm25.docs[0].title).toBe("custom title");
+  });
+
+  it("dedupes by id within the sink lifetime", async () => {
+    const bm25 = makeFakeBm25();
+    const sink = new CcRagSink({ bm25 });
+    await sink.write([doc("evt-1", "text v1")]);
+    const r = await sink.write([doc("evt-1", "text v2")]);
+    expect(r.indexed).toBe(0);
+    expect(r.skipped).toBe(1);
+    expect(bm25.docs.length).toBe(1);
+    expect(bm25.docs[0].content).toBe("text v1"); // first write wins
+  });
+
+  it("skips empty / malformed docs", async () => {
+    const bm25 = makeFakeBm25();
+    const sink = new CcRagSink({ bm25 });
+    const r = await sink.write([
+      doc("a", ""),                              // empty text
+      doc("b", "real text"),
+      { id: "c" /* missing text */ },
+      null,
+      { /* missing id */ text: "orphan" },
+    ]);
+    expect(r.indexed).toBe(1);
+    expect(r.skipped).toBe(4);
+    expect(bm25.docs.length).toBe(1);
+  });
+
+  it("collects upstream BM25 errors without aborting batch", async () => {
+    let failOn = "evt-2";
+    const sink = new CcRagSink({
+      bm25: {
+        addDocument(d) {
+          if (d.id === failOn) throw new Error("BM25 backend full");
+        },
+      },
+    });
+    const r = await sink.write([doc("evt-1", "a"), doc("evt-2", "b"), doc("evt-3", "c")]);
+    expect(r.indexed).toBe(2);
+    expect(r.errors.length).toBe(1);
+    expect(r.errors[0].id).toBe("evt-2");
+  });
+
+  it("forwards to vector store when wired", async () => {
+    const bm25 = makeFakeBm25();
+    const vectorCalls = [];
+    const sink = new CcRagSink({
+      bm25,
+      vector: { index: async (docs) => { vectorCalls.push(docs); } },
+    });
+    const r = await sink.write([doc("a", "alpha"), doc("b", "beta")]);
+    expect(r.indexed).toBe(2);
+    expect(vectorCalls.length).toBe(1);
+    expect(vectorCalls[0].length).toBe(2);
+  });
+
+  it("vector failure is captured but BM25 indexing still succeeds", async () => {
+    const bm25 = makeFakeBm25();
+    const sink = new CcRagSink({
+      bm25,
+      vector: { index: async () => { throw new Error("qdrant down"); } },
+    });
+    const r = await sink.write([doc("a", "alpha")]);
+    expect(r.indexed).toBe(1);
+    expect(bm25.docs.length).toBe(1);
+    expect(r.errors.length).toBe(1);
+    expect(r.errors[0].phase).toBe("vector");
+  });
+
+  it("transformDoc hook lets caller rewrite the doc shape", async () => {
+    const bm25 = makeFakeBm25();
+    const sink = new CcRagSink({
+      bm25,
+      transformDoc: (d) => ({ id: d.id, title: "OVERRIDE", content: d.text.toUpperCase() }),
+    });
+    await sink.write([doc("a", "hello")]);
+    expect(bm25.docs[0].title).toBe("OVERRIDE");
+    expect(bm25.docs[0].content).toBe("HELLO");
+  });
+
+  it("returns zeros for empty input", async () => {
+    const bm25 = makeFakeBm25();
+    const sink = new CcRagSink({ bm25 });
+    const r = await sink.write([]);
+    expect(r).toEqual({ indexed: 0, skipped: 0, errors: [] });
+  });
+});

package/__tests__/ids.test.js

@@ -0,0 +1,45 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { newId, timestampFromId } = require("../lib/ids");
+
+describe("ids", () => {
+  it("newId returns a 36-char UUID v7 string", () => {
+    const id = newId();
+    expect(typeof id).toBe("string");
+    expect(id.length).toBe(36);
+    expect(id.charAt(14)).toBe("7"); // version nibble
+  });
+
+  it("newId generates unique IDs", () => {
+    const ids = new Set();
+    for (let i = 0; i < 1000; i++) ids.add(newId());
+    expect(ids.size).toBe(1000);
+  });
+
+  it("newId generates time-ordered IDs (sortable by string compare)", async () => {
+    const a = newId();
+    // Wait > 1ms so the embedded timestamp definitely advances.
+    await new Promise((r) => setTimeout(r, 5));
+    const b = newId();
+    expect(a < b).toBe(true);
+  });
+
+  it("timestampFromId returns a recent unix ms timestamp for v7 IDs", () => {
+    const now = Date.now();
+    const id = newId();
+    const ts = timestampFromId(id);
+    expect(ts).not.toBeNull();
+    // Embedded timestamp should be within 2s of now (allow CI jitter).
+    expect(Math.abs(ts - now)).toBeLessThan(2000);
+  });
+
+  it("timestampFromId returns null for non-v7 input", () => {
+    // A canonical v4 UUID has version nibble "4"
+    const v4 = "550e8400-e29b-41d4-a716-446655440000";
+    expect(timestampFromId(v4)).toBeNull();
+    expect(timestampFromId("not-a-uuid")).toBeNull();
+    expect(timestampFromId(undefined)).toBeNull();
+  });
+});

package/__tests__/key-providers.test.js

@@ -0,0 +1,126 @@
+"use strict";
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const {
+  generateKeyHex,
+  isValidKeyHex,
+  InMemoryKeyProvider,
+  FileKeyProvider,
+  KEY_HEX_LEN,
+} = require("../lib/key-providers");
+
+describe("generateKeyHex / isValidKeyHex", () => {
+  it("generateKeyHex returns 64 hex chars", () => {
+    const k = generateKeyHex();
+    expect(typeof k).toBe("string");
+    expect(k.length).toBe(KEY_HEX_LEN);
+    expect(/^[0-9a-f]+$/.test(k)).toBe(true);
+  });
+
+  it("generateKeyHex returns unique keys", () => {
+    const set = new Set();
+    for (let i = 0; i < 50; i++) set.add(generateKeyHex());
+    expect(set.size).toBe(50);
+  });
+
+  it("isValidKeyHex accepts valid 64-hex strings", () => {
+    expect(isValidKeyHex(generateKeyHex())).toBe(true);
+    expect(isValidKeyHex("A".repeat(64))).toBe(true);
+  });
+
+  it("isValidKeyHex rejects wrong length, non-hex, non-string", () => {
+    expect(isValidKeyHex("a".repeat(63))).toBe(false);
+    expect(isValidKeyHex("a".repeat(65))).toBe(false);
+    expect(isValidKeyHex("z".repeat(64))).toBe(false);
+    expect(isValidKeyHex(null)).toBe(false);
+    expect(isValidKeyHex(undefined)).toBe(false);
+    expect(isValidKeyHex(Buffer.alloc(32))).toBe(false);
+  });
+});
+
+describe("InMemoryKeyProvider", () => {
+  it("get returns null for unknown name", async () => {
+    const p = new InMemoryKeyProvider();
+    expect(await p.get("missing")).toBeNull();
+    expect(await p.has("missing")).toBe(false);
+  });
+
+  it("set then get round-trip", async () => {
+    const p = new InMemoryKeyProvider();
+    const k = generateKeyHex();
+    await p.set("vault:abc", k);
+    expect(await p.has("vault:abc")).toBe(true);
+    expect(await p.get("vault:abc")).toBe(k);
+  });
+
+  it("set validates hex shape", async () => {
+    const p = new InMemoryKeyProvider();
+    await expect(p.set("bad", "notatall")).rejects.toThrow(/hex/);
+  });
+
+  it("del removes the entry", async () => {
+    const p = new InMemoryKeyProvider();
+    await p.set("vault:abc", generateKeyHex());
+    await p.del("vault:abc");
+    expect(await p.has("vault:abc")).toBe(false);
+    expect(await p.get("vault:abc")).toBeNull();
+  });
+});
+
+describe("FileKeyProvider", () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pdh-keytest-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("set creates a file under dir; get reads it back", async () => {
+    const p = new FileKeyProvider(tmpDir);
+    const k = generateKeyHex();
+    await p.set("vault:test", k);
+    expect(await p.has("vault:test")).toBe(true);
+    expect(await p.get("vault:test")).toBe(k);
+    // colons get sanitized to underscores in filename
+    expect(fs.existsSync(path.join(tmpDir, "vault_test.key"))).toBe(true);
+  });
+
+  it("get returns null for unknown name (does not create file)", async () => {
+    const p = new FileKeyProvider(tmpDir);
+    expect(await p.get("never-set")).toBeNull();
+    expect(fs.readdirSync(tmpDir).length).toBe(0);
+  });
+
+  it("get throws on corrupted stored file", async () => {
+    const p = new FileKeyProvider(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, "vault_corrupt.key"), "not-real-hex");
+    await expect(p.get("vault:corrupt")).rejects.toThrow(/valid hex/);
+  });
+
+  it("del removes the file", async () => {
+    const p = new FileKeyProvider(tmpDir);
+    await p.set("vault:bye", generateKeyHex());
+    await p.del("vault:bye");
+    expect(await p.has("vault:bye")).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, "vault_bye.key"))).toBe(false);
+  });
+
+  it("constructor creates missing dir recursively", () => {
+    const nested = path.join(tmpDir, "a", "b", "c");
+    const p = new FileKeyProvider(nested);
+    expect(p.dir).toBe(nested);
+    expect(fs.existsSync(nested)).toBe(true);
+  });
+
+  it("set validates hex shape", async () => {
+    const p = new FileKeyProvider(tmpDir);
+    await expect(p.set("bad", "xx")).rejects.toThrow(/hex/);
+  });
+});