@chainlesschain/personal-data-hub 0.2.4 → 0.3.1

package/__tests__/adapters/git-activity.test.js

@@ -0,0 +1,216 @@
+"use strict";
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+const {
+  GitActivityAdapter,
+  GIT_ACTIVITY_NAME,
+  GIT_ACTIVITY_VERSION,
+} = require("../../lib/adapters/git-activity");
+const { assertAdapter } = require("../../lib/adapter-spec");
+const { EVENT_SUBTYPES } = require("../../lib/constants");
+const { validateEvent } = require("../../lib/schemas");
+
+let tmpDir;
+let codeRoot;
+
+// Anchor fixtures to "now - 1h" so the default --since=180.days filter
+// never drops them. Bumping the literal in one place avoids drift if the
+// adapter's default window changes.
+const FIXTURE_NOW = Date.now();
+function ts(offsetSec = 0) {
+  return FIXTURE_NOW - 3_600_000 + offsetSec * 1000;
+}
+
+// Build a single throwaway repo with N commits — each committed with
+// GIT_AUTHOR_DATE so the timestamps are deterministic.
+function makeRepo(name, commits) {
+  const dir = join(codeRoot, name);
+  mkdirSync(dir, { recursive: true });
+  const G = (args, env = {}) =>
+    execFileSync("git", ["-C", dir, ...args], {
+      encoding: "utf-8",
+      env: {
+        ...process.env,
+        GIT_CONFIG_NOSYSTEM: "1",
+        ...env,
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  G(["init", "-q", "-b", "main"]);
+  G(["config", "user.email", "test@example.com"]);
+  G(["config", "user.name", "Test"]);
+  G(["config", "commit.gpgsign", "false"]);
+  let i = 0;
+  for (const c of commits) {
+    const file = join(dir, `f${i}.txt`);
+    writeFileSync(file, `content ${i}\n`, "utf-8");
+    G(["add", "."]);
+    const dt = new Date(c.tsMs).toISOString();
+    G(["commit", "-m", c.subject, "--author", `${c.author || "Test User"} <test@example.com>`], {
+      GIT_AUTHOR_DATE: dt,
+      GIT_COMMITTER_DATE: dt,
+    });
+    i++;
+  }
+  return dir;
+}
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "git-act-test-"));
+  codeRoot = join(tmpDir, "code");
+  mkdirSync(codeRoot, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("GitActivityAdapter — contract + identity", () => {
+  it("conforms to PersonalDataAdapter contract", () => {
+    expect(assertAdapter(new GitActivityAdapter())).toEqual({ ok: true });
+  });
+
+  it("identifies as git-activity with sync:git-log-local capability", () => {
+    const a = new GitActivityAdapter();
+    expect(a.name).toBe(GIT_ACTIVITY_NAME);
+    expect(a.name).toBe("git-activity");
+    expect(a.version).toBe(GIT_ACTIVITY_VERSION);
+    expect(a.capabilities).toContain("sync:git-log-local");
+  });
+});
+
+describe("GitActivityAdapter.authenticate", () => {
+  it("NO_GIT_REPOS when codeRoot empty", async () => {
+    const a = new GitActivityAdapter({ codeRoots: [codeRoot] });
+    const r = await a.authenticate({});
+    expect(r.ok).toBe(false);
+    expect(r.reason).toBe("NO_GIT_REPOS");
+  });
+
+  it("ok when at least one repo exists", async () => {
+    makeRepo("a", [{ subject: "init", tsMs: ts(0) }]);
+    const a = new GitActivityAdapter({ codeRoots: [codeRoot] });
+    const r = await a.authenticate({});
+    expect(r.ok).toBe(true);
+    expect(r.repoCount).toBe(1);
+  });
+});
+
+describe("GitActivityAdapter.sync", () => {
+  it("yields commits with author+subject+ts, originalId stable across syncs", async () => {
+    makeRepo("a", [
+      { subject: "first commit", tsMs: ts(1), author: "Alice" },
+      { subject: "second commit", tsMs: ts(2), author: "Alice" },
+    ]);
+    const a = new GitActivityAdapter({ codeRoots: [codeRoot] });
+    const raws1 = [];
+    for await (const r of a.sync()) raws1.push(r);
+    expect(raws1).toHaveLength(2);
+    expect(raws1[0].payload.subject).toBeTruthy();
+    expect(raws1[0].payload.authorName).toBe("Alice");
+    expect(raws1[0].payload.repoName).toBe("a");
+    expect(raws1[0].originalId).toMatch(/^git-commit:/);
+    // Re-sync — originalIds should match (idempotent)
+    const raws2 = [];
+    for await (const r of a.sync()) raws2.push(r);
+    const ids1 = raws1.map((r) => r.originalId).sort();
+    const ids2 = raws2.map((r) => r.originalId).sort();
+    expect(ids2).toEqual(ids1);
+  });
+
+  it("multi-repo: enumerates every .git dir under the root", async () => {
+    makeRepo("repo-a", [{ subject: "a1", tsMs: ts(1) }]);
+    makeRepo("repo-b", [{ subject: "b1", tsMs: ts(2) }]);
+    makeRepo("repo-c", [{ subject: "c1", tsMs: ts(3) }]);
+    const a = new GitActivityAdapter({ codeRoots: [codeRoot] });
+    const raws = [];
+    for await (const r of a.sync()) raws.push(r);
+    const repoNames = new Set(raws.map((r) => r.payload.repoName));
+    expect(repoNames).toEqual(new Set(["repo-a", "repo-b", "repo-c"]));
+  });
+
+  it("respects limit", async () => {
+    makeRepo("a", [
+      { subject: "1", tsMs: ts(1) },
+      { subject: "2", tsMs: ts(2) },
+      { subject: "3", tsMs: ts(3) },
+    ]);
+    const a = new GitActivityAdapter({ codeRoots: [codeRoot] });
+    const raws = [];
+    for await (const r of a.sync({ limit: 2 })) raws.push(r);
+    expect(raws).toHaveLength(2);
+  });
+
+  it("skips non-.git directories silently", async () => {
+    makeRepo("real-repo", [{ subject: "x", tsMs: ts(1) }]);
+    mkdirSync(join(codeRoot, "not-a-repo"), { recursive: true });
+    writeFileSync(join(codeRoot, "not-a-repo", "README.md"), "no .git here", "utf-8");
+    const a = new GitActivityAdapter({ codeRoots: [codeRoot] });
+    const raws = [];
+    for await (const r of a.sync()) raws.push(r);
+    expect(raws).toHaveLength(1);
+    expect(raws[0].payload.repoName).toBe("real-repo");
+  });
+});
+
+describe("GitActivityAdapter.normalize", () => {
+  it("maps commit → schema-valid Event(OTHER) with author as actor", () => {
+    const a = new GitActivityAdapter();
+    const { events } = a.normalize({
+      kind: "commit",
+      originalId: "git-commit:/code/foo:abc",
+      capturedAt: 1_700_000_005_000,
+      payload: {
+        sha: "abcdef0123456789",
+        shortSha: "abcdef01",
+        authoredAtMs: 1_700_000_001_000,
+        authorName: "Alice",
+        authorEmail: "alice@example.com",
+        subject: "Fix the bug",
+        repoDir: "/code/foo",
+        repoName: "foo",
+      },
+    });
+    expect(events).toHaveLength(1);
+    const e = events[0];
+    expect(e.subtype).toBe(EVENT_SUBTYPES.OTHER);
+    expect(e.actor).toBe("Alice");
+    expect(e.content.title).toBe("Fix the bug");
+    expect(e.occurredAt).toBe(1_700_000_001_000);
+    expect(e.extra.repoName).toBe("foo");
+    expect(e.extra.sha).toBe("abcdef0123456789");
+    expect(validateEvent(e).valid).toBe(true);
+  });
+
+  it("truncates long commit subjects to 100 chars in title", () => {
+    const a = new GitActivityAdapter();
+    const longSubj = "x".repeat(200);
+    const { events } = a.normalize({
+      kind: "commit",
+      capturedAt: 1_700_000_000_000,
+      originalId: "git-commit:foo:long",
+      payload: {
+        sha: "deadbeef",
+        shortSha: "deadbeef",
+        authoredAtMs: 1_700_000_000_000,
+        subject: longSubj,
+        authorName: "X",
+        repoName: "r",
+      },
+    });
+    expect(events[0].content.title.length).toBeLessThanOrEqual(101);
+    expect(events[0].content.title.endsWith("…")).toBe(true);
+    expect(events[0].content.text).toBe(longSubj);
+  });
+
+  it("throws on unknown raw.kind", () => {
+    expect(() => new GitActivityAdapter().normalize({ kind: "bogus" })).toThrow(
+      /unknown raw\.kind=bogus/,
+    );
+  });
+});

package/__tests__/adapters/local-files.test.js

@@ -0,0 +1,264 @@
+"use strict";
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, utimesSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const {
+  LocalFilesAdapter,
+  LOCAL_FILES_NAME,
+  LOCAL_FILES_VERSION,
+} = require("../../lib/adapters/local-files");
+const { assertAdapter } = require("../../lib/adapter-spec");
+const { EVENT_SUBTYPES } = require("../../lib/constants");
+const { validateEvent } = require("../../lib/schemas");
+
+let tmpDir;
+
+function makeFile(rel, content, mtimeMs) {
+  const p = join(tmpDir, rel);
+  mkdirSync(join(tmpDir, rel, ".."), { recursive: true });
+  writeFileSync(p, content, "utf-8");
+  if (mtimeMs) utimesSync(p, mtimeMs / 1000, mtimeMs / 1000);
+  return p;
+}
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "local-files-test-"));
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("LocalFilesAdapter — contract + identity", () => {
+  it("conforms to PersonalDataAdapter contract", () => {
+    expect(assertAdapter(new LocalFilesAdapter())).toEqual({ ok: true });
+  });
+
+  it("identifies as local-files with sync:local-file-walk capability", () => {
+    const a = new LocalFilesAdapter();
+    expect(a.name).toBe(LOCAL_FILES_NAME);
+    expect(a.name).toBe("local-files");
+    expect(a.version).toBe(LOCAL_FILES_VERSION);
+    expect(a.capabilities).toContain("sync:local-file-walk");
+  });
+});
+
+describe("LocalFilesAdapter.sync", () => {
+  it("yields one row per file across multiple roots", async () => {
+    const r1 = join(tmpDir, "root1");
+    const r2 = join(tmpDir, "root2");
+    mkdirSync(r1);
+    mkdirSync(r2);
+    makeFile("root1/a.txt", "a", 1_700_000_001_000);
+    makeFile("root1/b.md", "b", 1_700_000_002_000);
+    makeFile("root2/c.pdf", "c", 1_700_000_003_000);
+    const a = new LocalFilesAdapter({ roots: [r1, r2] });
+    const raws = [];
+    for await (const r of a.sync()) raws.push(r);
+    expect(raws).toHaveLength(3);
+    expect(raws.every((r) => r.kind === "local-file")).toBe(true);
+    const names = raws.map((r) => r.payload.name).sort();
+    expect(names).toEqual(["a.txt", "b.md", "c.pdf"]);
+  });
+
+  it("walks subdirectories within maxDepth", async () => {
+    const r = join(tmpDir, "r");
+    mkdirSync(r);
+    makeFile("r/sub/nested/deep.txt", "x", 1_700_000_001_000);
+    const a = new LocalFilesAdapter({ roots: [r] });
+    const raws = [];
+    for await (const x of a.sync()) raws.push(x);
+    expect(raws).toHaveLength(1);
+    expect(raws[0].payload.name).toBe("deep.txt");
+  });
+
+  it("excludes xwechat_files / WXWork / node_modules / .git by default", async () => {
+    const r = join(tmpDir, "r");
+    mkdirSync(r);
+    makeFile("r/normal.txt", "ok", 1_700_000_001_000);
+    makeFile("r/xwechat_files/x.txt", "skip", 1_700_000_001_000);
+    makeFile("r/WXWork/y.txt", "skip", 1_700_000_001_000);
+    makeFile("r/node_modules/lib/index.js", "skip", 1_700_000_001_000);
+    makeFile("r/.git/config", "skip", 1_700_000_001_000);
+    const a = new LocalFilesAdapter({ roots: [r] });
+    const raws = [];
+    for await (const x of a.sync()) raws.push(x);
+    expect(raws.map((r) => r.payload.name)).toEqual(["normal.txt"]);
+  });
+
+  it("custom excludes override defaults", async () => {
+    const r = join(tmpDir, "r");
+    mkdirSync(r);
+    makeFile("r/.git/config", "kept-now", 1_700_000_001_000);
+    makeFile("r/build/out.txt", "skipped-now", 1_700_000_001_000);
+    const a = new LocalFilesAdapter({ roots: [r], excludes: ["build"] });
+    const raws = [];
+    for await (const x of a.sync()) raws.push(x);
+    // .git is hidden (leading '.') so still skipped even without default rule
+    expect(raws.map((r) => r.payload.name)).toEqual([]);
+  });
+
+  it("skips hidden files / dirs (leading '.')", async () => {
+    const r = join(tmpDir, "r");
+    mkdirSync(r);
+    makeFile("r/.hidden", "skip", 1_700_000_001_000);
+    makeFile("r/.cache/sub.txt", "skip", 1_700_000_001_000);
+    makeFile("r/visible.txt", "ok", 1_700_000_001_000);
+    const a = new LocalFilesAdapter({ roots: [r] });
+    const raws = [];
+    for await (const x of a.sync()) raws.push(x);
+    expect(raws.map((r) => r.payload.name)).toEqual(["visible.txt"]);
+  });
+
+  it("respects since filter (file mtime granularity)", async () => {
+    const r = join(tmpDir, "r");
+    mkdirSync(r);
+    makeFile("r/old.txt", "x", 1_700_000_001_000);
+    makeFile("r/new.txt", "x", 1_700_000_005_000);
+    const a = new LocalFilesAdapter({ roots: [r] });
+    const raws = [];
+    for await (const x of a.sync({ since: 1_700_000_003_000 })) raws.push(x);
+    expect(raws.map((r) => r.payload.name)).toEqual(["new.txt"]);
+  });
+
+  it("respects limit", async () => {
+    const r = join(tmpDir, "r");
+    mkdirSync(r);
+    for (let i = 0; i < 5; i++) makeFile(`r/f${i}.txt`, "x", 1_700_000_001_000);
+    const a = new LocalFilesAdapter({ roots: [r] });
+    const raws = [];
+    for await (const x of a.sync({ limit: 2 })) raws.push(x);
+    expect(raws).toHaveLength(2);
+  });
+
+  it("missing roots silently produce nothing", async () => {
+    const a = new LocalFilesAdapter({ roots: [join(tmpDir, "nonexistent")] });
+    const raws = [];
+    for await (const x of a.sync()) raws.push(x);
+    expect(raws).toHaveLength(0);
+  });
+
+  it("originalId encodes path + mtime so re-saved files dedupe per mtime", async () => {
+    const r = join(tmpDir, "r");
+    mkdirSync(r);
+    const p = makeFile("r/a.txt", "x", 1_700_000_001_000);
+    const a = new LocalFilesAdapter({ roots: [r] });
+    const first = [];
+    for await (const x of a.sync()) first.push(x);
+    expect(first[0].originalId).toBe(`local-file:${p}:1700000001000`);
+    // change mtime -> new originalId so adapter does not collapse history
+    utimesSync(p, 1_700_000_009 / 1000, 1_700_000_009);
+    const second = [];
+    for await (const x of a.sync()) second.push(x);
+    expect(second[0].originalId).not.toBe(first[0].originalId);
+  });
+});
+
+describe("LocalFilesAdapter.authenticate + healthCheck", () => {
+  it("authenticate returns ok=true with resolved roots when defaults exist", async () => {
+    const r = join(tmpDir, "r");
+    mkdirSync(r);
+    const a = new LocalFilesAdapter({ roots: [r] });
+    const result = await a.authenticate();
+    expect(result.ok).toBe(true);
+    expect(result.mode).toBe("file-import");
+    expect(result.roots).toEqual([r]);
+  });
+
+  it("authenticate returns NO_DATA_ROOTS when roots is empty", async () => {
+    const a = new LocalFilesAdapter({ roots: [] });
+    // Constructor coerces empty array to override=null, so defaults kick in.
+    // Force empty roots via context arg path is not exposed; verify the
+    // adapter at least returns ok when defaults present. This test verifies
+    // the no-roots branch by stubbing defaultRoots to return [].
+    a._deps.defaultRoots = () => [];
+    const result = await a.authenticate();
+    expect(result.ok).toBe(false);
+    expect(result.reason).toBe("NO_DATA_ROOTS");
+  });
+
+  it("healthCheck always returns ok=true (file-import adapter has no live dep)", async () => {
+    const a = new LocalFilesAdapter();
+    const r = await a.healthCheck();
+    expect(r.ok).toBe(true);
+    expect(typeof r.lastChecked).toBe("number");
+  });
+});
+
+describe("LocalFilesAdapter.normalize", () => {
+  it("maps local-file → Event(OTHER) with [file] title prefix", () => {
+    const a = new LocalFilesAdapter();
+    const { events } = a.normalize({
+      kind: "local-file",
+      originalId: "local-file:/home/u/Documents/report.pdf:1700000005000",
+      capturedAt: 1_700_000_010_000,
+      payload: {
+        path: "/home/u/Documents/report.pdf",
+        name: "report.pdf",
+        ext: "pdf",
+        size: 4096,
+        mtimeMs: 1_700_000_005_000,
+        root: "/home/u/Documents",
+      },
+    });
+    expect(events).toHaveLength(1);
+    const e = events[0];
+    expect(e.subtype).toBe(EVENT_SUBTYPES.OTHER);
+    expect(e.actor).toBe("self");
+    expect(e.content.title).toBe("[file] report.pdf");
+    expect(e.content.text).toBe("/home/u/Documents/report.pdf");
+    expect(e.occurredAt).toBe(1_700_000_005_000);
+    expect(e.extra.kind).toBe("local-file");
+    expect(e.extra.ext).toBe("pdf");
+    expect(e.extra.size).toBe(4096);
+    expect(validateEvent(e).valid).toBe(true);
+  });
+
+  it("truncates long filenames in title (keeps full path in text)", () => {
+    const a = new LocalFilesAdapter();
+    const longName = "x".repeat(300) + ".txt";
+    const { events } = a.normalize({
+      kind: "local-file",
+      originalId: "local-file:/r/big.txt:1700000000000",
+      capturedAt: 1_700_000_000_000,
+      payload: {
+        path: "/r/" + longName,
+        name: longName,
+        ext: "txt",
+        size: 0,
+        mtimeMs: 1_700_000_000_000,
+        root: "/r",
+      },
+    });
+    expect(events[0].content.title.length).toBeLessThanOrEqual(101);
+    expect(events[0].content.title.endsWith("…")).toBe(true);
+    expect(events[0].content.text).toContain(longName);
+  });
+
+  it("uses '(无名)' for empty filename", () => {
+    const a = new LocalFilesAdapter();
+    const { events } = a.normalize({
+      kind: "local-file",
+      originalId: "local-file::1700000000000",
+      capturedAt: 1_700_000_000_000,
+      payload: {
+        path: "",
+        name: "",
+        ext: "",
+        size: 0,
+        mtimeMs: 1_700_000_000_000,
+        root: "",
+      },
+    });
+    expect(events[0].content.title).toBe("[file] (无名)");
+  });
+
+  it("throws on unknown raw.kind", () => {
+    expect(() => new LocalFilesAdapter().normalize({ kind: "bogus" })).toThrow(
+      /unknown raw\.kind=bogus/,
+    );
+  });
+});

package/__tests__/adapters/shell-history.test.js

@@ -0,0 +1,180 @@
+"use strict";
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, utimesSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const {
+  ShellHistoryAdapter,
+  SHELL_HISTORY_NAME,
+  SHELL_HISTORY_VERSION,
+} = require("../../lib/adapters/shell-history");
+const { assertAdapter } = require("../../lib/adapter-spec");
+const { EVENT_SUBTYPES } = require("../../lib/constants");
+const { validateEvent } = require("../../lib/schemas");
+
+let tmpDir;
+
+function makeHistFile(name, lines, mtimeMs) {
+  const p = join(tmpDir, name);
+  writeFileSync(p, lines.join("\n") + "\n", "utf-8");
+  if (mtimeMs) utimesSync(p, mtimeMs / 1000, mtimeMs / 1000);
+  return p;
+}
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "shell-hist-test-"));
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("ShellHistoryAdapter — contract + identity", () => {
+  it("conforms to PersonalDataAdapter contract", () => {
+    expect(assertAdapter(new ShellHistoryAdapter())).toEqual({ ok: true });
+  });
+
+  it("identifies as shell-history with sync:shell-history-files capability", () => {
+    const a = new ShellHistoryAdapter();
+    expect(a.name).toBe(SHELL_HISTORY_NAME);
+    expect(a.name).toBe("shell-history");
+    expect(a.version).toBe(SHELL_HISTORY_VERSION);
+    expect(a.capabilities).toContain("sync:shell-history-files");
+  });
+});
+
+describe("ShellHistoryAdapter.sync", () => {
+  it("yields one row per non-blank line per configured shell", async () => {
+    const pwshFile = makeHistFile("pwsh.txt", ["ls", "git status", "", "npm test"], 1_700_000_010_000);
+    const bashFile = makeHistFile("bash.txt", ["cd /tmp", "make"], 1_700_000_020_000);
+    const a = new ShellHistoryAdapter({
+      sources: [
+        { shell: "pwsh", file: pwshFile },
+        { shell: "bash", file: bashFile },
+      ],
+    });
+    const raws = [];
+    for await (const r of a.sync()) raws.push(r);
+    expect(raws).toHaveLength(5); // 3 pwsh (blank skipped) + 2 bash
+    expect(raws[0].payload.shell).toBe("pwsh");
+    expect(raws[0].payload.value).toBe("ls");
+    expect(raws[0].payload.snapshotTs).toBe(1_700_000_010_000);
+    expect(raws[3].payload.shell).toBe("bash");
+    expect(raws[3].payload.value).toBe("cd /tmp");
+  });
+
+  it("strips zsh extended history prefix", async () => {
+    const zshFile = makeHistFile(
+      "zsh.txt",
+      [
+        ": 1700000001:0;ls -la",
+        ": 1700000002:5;npm install",
+        "plain-line-without-prefix",
+      ],
+      1_700_000_030_000,
+    );
+    const a = new ShellHistoryAdapter({ sources: [{ shell: "zsh", file: zshFile }] });
+    const raws = [];
+    for await (const r of a.sync()) raws.push(r);
+    expect(raws.map((r) => r.payload.value)).toEqual([
+      "ls -la",
+      "npm install",
+      "plain-line-without-prefix",
+    ]);
+  });
+
+  it("originalId disambiguates same command at different sourceIndex", async () => {
+    const f = makeHistFile("h.txt", ["ls", "ls", "ls"], 1_700_000_001_000);
+    const a = new ShellHistoryAdapter({ sources: [{ shell: "bash", file: f }] });
+    const raws = [];
+    for await (const r of a.sync()) raws.push(r);
+    const ids = raws.map((r) => r.originalId);
+    expect(new Set(ids).size).toBe(3);
+  });
+
+  it("respects since filter (file mtime granularity)", async () => {
+    const oldF = makeHistFile("old.txt", ["a"], 1_700_000_001_000);
+    const newF = makeHistFile("new.txt", ["b"], 1_700_000_005_000);
+    const a = new ShellHistoryAdapter({
+      sources: [
+        { shell: "pwsh", file: oldF },
+        { shell: "bash", file: newF },
+      ],
+    });
+    const raws = [];
+    for await (const r of a.sync({ since: 1_700_000_003_000 })) raws.push(r);
+    expect(raws.map((r) => r.payload.value)).toEqual(["b"]);
+  });
+
+  it("respects limit", async () => {
+    const f = makeHistFile("h.txt", ["1", "2", "3", "4", "5"], 1_700_000_001_000);
+    const a = new ShellHistoryAdapter({ sources: [{ shell: "pwsh", file: f }] });
+    const raws = [];
+    for await (const r of a.sync({ limit: 2 })) raws.push(r);
+    expect(raws).toHaveLength(2);
+  });
+
+  it("missing files silently produce nothing", async () => {
+    const a = new ShellHistoryAdapter({
+      sources: [{ shell: "pwsh", file: join(tmpDir, "nonexistent.txt") }],
+    });
+    const raws = [];
+    for await (const r of a.sync()) raws.push(r);
+    expect(raws).toHaveLength(0);
+  });
+});
+
+describe("ShellHistoryAdapter.normalize", () => {
+  it("maps shell-command → Event(OTHER) with [shell] title prefix", () => {
+    const a = new ShellHistoryAdapter();
+    const { events } = a.normalize({
+      kind: "shell-command",
+      originalId: "shell-cmd:bash:0:abc",
+      capturedAt: 1_700_000_005_000,
+      payload: {
+        shell: "bash",
+        file: "/home/u/.bash_history",
+        value: "git status",
+        sourceIndex: 0,
+        snapshotTs: 1_700_000_001_000,
+      },
+    });
+    expect(events).toHaveLength(1);
+    const e = events[0];
+    expect(e.subtype).toBe(EVENT_SUBTYPES.OTHER);
+    expect(e.actor).toBe("self");
+    expect(e.content.title).toBe("[bash] git status");
+    expect(e.content.text).toBe("git status");
+    expect(e.occurredAt).toBe(1_700_000_001_000);
+    expect(e.extra.kind).toBe("shell-command");
+    expect(e.extra.shell).toBe("bash");
+    expect(validateEvent(e).valid).toBe(true);
+  });
+
+  it("truncates long commands in title (keeps full text)", () => {
+    const a = new ShellHistoryAdapter();
+    const longCmd = "echo " + "x".repeat(300);
+    const { events } = a.normalize({
+      kind: "shell-command",
+      capturedAt: 1_700_000_000_000,
+      originalId: "shell-cmd:pwsh:0:long",
+      payload: {
+        shell: "pwsh",
+        value: longCmd,
+        sourceIndex: 0,
+        snapshotTs: 1_700_000_000_000,
+      },
+    });
+    expect(events[0].content.title.length).toBeLessThanOrEqual(101);
+    expect(events[0].content.title.endsWith("…")).toBe(true);
+    expect(events[0].content.text).toBe(longCmd);
+  });
+
+  it("throws on unknown raw.kind", () => {
+    expect(() => new ShellHistoryAdapter().normalize({ kind: "bogus" })).toThrow(
+      /unknown raw\.kind=bogus/,
+    );
+  });
+});