@rohirik/openltm-core 2.8.0

package/src/__tests__/events/index.test.ts

@@ -0,0 +1,32 @@
+/**
+ * events/index.test.ts — dormant-path contract for the graph-app liveness bus.
+ * Without an external libhonker_ext binary, notify must report false and the
+ * listener must return an inert handle so the caller keeps its fs.watch +
+ * 3s-debounce file-watcher fallback.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { notifyLtm, startLtmListener, LTM_CHANNEL } from "../../events/index.js";
+import { _resetHonkerForTesting } from "../../lib/honker.js";
+
+describe("events — dormant path (no honker)", () => {
+  beforeEach(() => {
+    _resetHonkerForTesting();
+    delete process.env["LTM_HONKER_EXT"];
+  });
+
+  it("exposes the stable channel name", () => {
+    expect(LTM_CHANNEL).toBe("ltm");
+  });
+
+  it("notifyLtm returns false when honker is unavailable", () => {
+    expect(notifyLtm({ type: "refresh" })).toBe(false);
+  });
+
+  it("startLtmListener returns an inert handle and never invokes the callback", async () => {
+    let calls = 0;
+    const h = startLtmListener(() => { calls++; });
+    expect(h.running).toBe(false);
+    await expect(h.stop()).resolves.toBeUndefined();
+    expect(calls).toBe(0);
+  });
+});

package/src/__tests__/extensions.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import {
+  locateSystemSqlite,
+  ensureCustomSqlite,
+  loadExtensions,
+  getCapabilities,
+  resetCapabilitiesForTesting,
+} from "../extensions.js";
+
+describe("extensions — capability probe", () => {
+  beforeEach(() => {
+    resetCapabilitiesForTesting();
+  });
+
+  it("locateSystemSqlite returns a string path or null, never throws", () => {
+    const p = locateSystemSqlite();
+    expect(p === null || typeof p === "string").toBe(true);
+  });
+
+  it("getCapabilities before any probe returns all-false without throwing", () => {
+    const caps = getCapabilities();
+    expect(caps).toEqual({ customSqlite: false, vec: false, honker: false });
+  });
+
+  it("loadExtensions never throws and returns a Capabilities shape", () => {
+    ensureCustomSqlite();
+    const db = new Database(":memory:");
+    const caps = loadExtensions(db);
+    expect(typeof caps.customSqlite).toBe("boolean");
+    expect(typeof caps.vec).toBe("boolean");
+    expect(typeof caps.honker).toBe("boolean");
+  });
+
+  it("honker is false when no LTM_HONKER_EXT binary is configured", () => {
+    const prev = process.env["LTM_HONKER_EXT"];
+    delete process.env["LTM_HONKER_EXT"];
+    ensureCustomSqlite();
+    const db = new Database(":memory:");
+    const caps = loadExtensions(db);
+    expect(caps.honker).toBe(false);
+    if (prev) process.env["LTM_HONKER_EXT"] = prev;
+  });
+
+  it("respects LTM_DISABLE_VEC — vec capability is false when force-disabled", () => {
+    const prev = process.env["LTM_DISABLE_VEC"];
+    process.env["LTM_DISABLE_VEC"] = "1";
+    const db = new Database(":memory:");
+    const caps = loadExtensions(db);
+    expect(caps.vec).toBe(false);
+    if (prev === undefined) delete process.env["LTM_DISABLE_VEC"];
+    else process.env["LTM_DISABLE_VEC"] = prev;
+  });
+
+  it("when customSqlite is active, vec loads and vec0 KNN works end-to-end", () => {
+    ensureCustomSqlite();
+    const db = new Database(":memory:");
+    const caps = loadExtensions(db);
+    // setCustomSQLite is process-global and only takes effect before the first
+    // Database opens. In a shared test process an earlier file may have already
+    // opened a bundled-sqlite connection, leaving customSqlite false — that is
+    // the graceful-degradation path, so skip the KNN assertion there.
+    if (!caps.customSqlite || process.env["LTM_DISABLE_VEC"]) return;
+    expect(caps.vec).toBe(true);
+    db.run("create virtual table t using vec0(embedding float[4])");
+    const q = new Uint8Array(new Float32Array([1, 2, 3, 4]).buffer);
+    db.run("insert into t(rowid, embedding) values (1, ?)", [q]);
+    const r = db
+      .query("select rowid, distance from t where embedding match ? order by distance limit 1")
+      .all(q) as Array<{ rowid: number; distance: number }>;
+    expect(r[0]?.rowid).toBe(1);
+    expect(r[0]?.distance).toBe(0);
+  });
+
+  it("getCapabilities returns the cached result after loadExtensions", () => {
+    ensureCustomSqlite();
+    const db = new Database(":memory:");
+    const caps = loadExtensions(db);
+    expect(getCapabilities()).toEqual(caps);
+  });
+});

package/src/__tests__/migrations/retention.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, writeFileSync, rmSync, utimesSync, statSync, existsSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { enforceRetention, getRetentionDefault } from "../../migrations.js";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "ltm-retention-"));
+});
+
+afterEach(() => {
+  if (existsSync(tmpDir)) rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function makeBak(name: string, ageSeconds: number = 120): string {
+  const path = join(tmpDir, name);
+  writeFileSync(path, "x".repeat(100));
+  const past = new Date(Date.now() - ageSeconds * 1000);
+  utimesSync(path, past, past);
+  return path;
+}
+
+describe("enforceRetention", () => {
+  it("returns empty result on empty directory", async () => {
+    const result = await enforceRetention(1, { dbPath: join(tmpDir, "openltm.db") });
+    expect(result.deleted).toEqual([]);
+    expect(result.kept).toEqual([]);
+    expect(result.warnings).toEqual([]);
+  });
+
+  it("keeps all files when under max", async () => {
+    const a = makeBak("openltm.db.bak-2026-01-01T00-00-00-000Z", 200);
+    const b = makeBak("openltm.db.bak-2026-01-02T00-00-00-000Z", 200);
+    const result = await enforceRetention(5, { dbPath: join(tmpDir, "openltm.db") });
+    expect(result.deleted).toEqual([]);
+    expect(result.kept.sort()).toEqual([a, b].sort());
+    expect(existsSync(a)).toBe(true);
+    expect(existsSync(b)).toBe(true);
+  });
+
+  it("deletes oldest when over max", async () => {
+    const f1 = makeBak("openltm.db.bak-2026-01-01T00-00-00-000Z", 200);
+    const f2 = makeBak("openltm.db.bak-2026-01-02T00-00-00-000Z", 200);
+    const f3 = makeBak("openltm.db.bak-2026-01-03T00-00-00-000Z", 200);
+    const f4 = makeBak("openltm.db.bak-2026-01-04T00-00-00-000Z", 200);
+    const f5 = makeBak("openltm.db.bak-2026-01-05T00-00-00-000Z", 200);
+    const result = await enforceRetention(2, { dbPath: join(tmpDir, "openltm.db") });
+    expect(result.deleted.sort()).toEqual([f1, f2, f3].sort());
+    expect(result.kept.sort()).toEqual([f4, f5].sort());
+    expect(existsSync(f1)).toBe(false);
+    expect(existsSync(f5)).toBe(true);
+  });
+
+  it("never deletes the currentBackupPath", async () => {
+    const f1 = makeBak("openltm.db.bak-2026-01-01T00-00-00-000Z", 200);
+    const f2 = makeBak("openltm.db.bak-2026-01-02T00-00-00-000Z", 200);
+    const f3 = makeBak("openltm.db.bak-2026-01-03T00-00-00-000Z", 200);
+    const result = await enforceRetention(1, {
+      dbPath: join(tmpDir, "openltm.db"),
+      currentBackupPath: f2,
+    });
+    expect(result.deleted).not.toContain(f2);
+    expect(result.kept).toContain(f2);
+  });
+
+  it("skips files newer than gracePeriodMs", async () => {
+    const old = makeBak("openltm.db.bak-2026-01-01T00-00-00-000Z", 200);
+    const fresh = makeBak("openltm.db.bak-2026-06-03T16-00-00-000Z", 0);
+    const result = await enforceRetention(0, {
+      dbPath: join(tmpDir, "openltm.db"),
+      gracePeriodMs: 60_000,
+    });
+    expect(result.deleted).toEqual([old]);
+    expect(result.kept).toEqual([fresh]);
+    expect(existsSync(fresh)).toBe(true);
+  });
+
+  it("reads LTM_BACKUP_RETENTION env var as default", () => {
+    const original = process.env["LTM_BACKUP_RETENTION"];
+    try {
+      process.env["LTM_BACKUP_RETENTION"] = "5";
+      expect(getRetentionDefault()).toBe(5);
+      process.env["LTM_BACKUP_RETENTION"] = "invalid";
+      expect(getRetentionDefault()).toBe(1);
+      process.env["LTM_BACKUP_RETENTION"] = "-1";
+      expect(getRetentionDefault()).toBe(1);
+      delete process.env["LTM_BACKUP_RETENTION"];
+      expect(getRetentionDefault()).toBe(1);
+    } finally {
+      if (original === undefined) delete process.env["LTM_BACKUP_RETENTION"];
+      else process.env["LTM_BACKUP_RETENTION"] = original;
+    }
+  });
+
+  it("does not touch non-.bak files", async () => {
+    writeFileSync(join(tmpDir, "openltm.db"), "active");
+    writeFileSync(join(tmpDir, "openltm.db-shm"), "shm");
+    writeFileSync(join(tmpDir, "openltm.db-wal"), "wal");
+    const bak = makeBak("openltm.db.bak-2026-01-01T00-00-00-000Z", 200);
+    const result = await enforceRetention(0, { dbPath: join(tmpDir, "openltm.db") });
+    expect(result.deleted).toEqual([bak]);
+    expect(existsSync(join(tmpDir, "openltm.db"))).toBe(true);
+    expect(existsSync(join(tmpDir, "openltm.db-shm"))).toBe(true);
+    expect(existsSync(join(tmpDir, "openltm.db-wal"))).toBe(true);
+  });
+
+  it("is idempotent and silent when files disappear before the call", async () => {
+    const f1 = makeBak("openltm.db.bak-2026-01-01T00-00-00-000Z", 200);
+    const f2 = makeBak("openltm.db.bak-2026-01-02T00-00-00-000Z", 200);
+    rmSync(f1);
+    const result = await enforceRetention(0, { dbPath: join(tmpDir, "openltm.db") });
+    expect(result.deleted).toEqual([f2]);
+    expect(result.warnings).toEqual([]);
+    expect(result.kept).toEqual([]);
+  });
+});

package/src/__tests__/queue/index.test.ts

@@ -0,0 +1,61 @@
+/**
+ * queue/index.test.ts — dormant-path contract for the Honker embedding queue.
+ *
+ * Honker requires an externally-built libhonker_ext binary (LTM_HONKER_EXT)
+ * that is absent in CI, so every queue/worker export must degrade to a graceful
+ * no-op without throwing. The live claim/ack/retry path is exercised only where
+ * the binary is present.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import {
+  getEmbeddingQueue,
+  enqueueEmbedding,
+  parseEmbeddingJob,
+  EMBED_QUEUE,
+} from "../../queue/index.js";
+import { startEmbeddingWorker } from "../../queue/worker.js";
+import { isHonkerAvailable, _resetHonkerForTesting } from "../../lib/honker.js";
+
+describe("queue — dormant path (no honker)", () => {
+  beforeEach(() => {
+    _resetHonkerForTesting();
+  });
+
+  it("EMBED_QUEUE has a stable name", () => {
+    expect(EMBED_QUEUE).toBe("ltm-embeddings");
+  });
+
+  it("honker is unavailable without LTM_HONKER_EXT", () => {
+    delete process.env["LTM_HONKER_EXT"];
+    expect(isHonkerAvailable()).toBe(false);
+  });
+
+  it("getEmbeddingQueue returns null when honker is unavailable", () => {
+    expect(getEmbeddingQueue()).toBeNull();
+  });
+
+  it("enqueueEmbedding returns null (caller falls back to inline) when unavailable", () => {
+    expect(enqueueEmbedding(123)).toBeNull();
+  });
+
+  it("startEmbeddingWorker returns an inert handle when unavailable", async () => {
+    const w = startEmbeddingWorker();
+    expect(w.running).toBe(false);
+    await expect(w.stop()).resolves.toBeUndefined();
+  });
+});
+
+describe("parseEmbeddingJob", () => {
+  it("accepts a valid positive-integer memoryId", () => {
+    expect(parseEmbeddingJob({ memoryId: 42 })).toEqual({ memoryId: 42 });
+  });
+
+  it("rejects malformed payloads", () => {
+    expect(parseEmbeddingJob(null)).toBeNull();
+    expect(parseEmbeddingJob({})).toBeNull();
+    expect(parseEmbeddingJob({ memoryId: "5" })).toBeNull();
+    expect(parseEmbeddingJob({ memoryId: 0 })).toBeNull();
+    expect(parseEmbeddingJob({ memoryId: -3 })).toBeNull();
+    expect(parseEmbeddingJob({ memoryId: 1.5 })).toBeNull();
+  });
+});

package/src/__tests__/scheduler/index.test.ts

@@ -0,0 +1,39 @@
+/**
+ * scheduler/index.test.ts — dormant-path contract for the Honker janitor cron.
+ * Without an external libhonker_ext binary, registration and the leader loop
+ * must degrade to graceful no-ops so the caller keeps startAutoRun()+HTTP poll.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import {
+  registerJanitorSchedule,
+  startJanitorScheduler,
+  JANITOR_SCHEDULE_NAME,
+  JANITOR_QUEUE,
+  JANITOR_CHANNEL,
+  DEFAULT_JANITOR_CRON,
+} from "../../scheduler/index.js";
+import { _resetHonkerForTesting } from "../../lib/honker.js";
+
+describe("scheduler — dormant path (no honker)", () => {
+  beforeEach(() => {
+    _resetHonkerForTesting();
+    delete process.env["LTM_HONKER_EXT"];
+  });
+
+  it("exposes stable names + default cron", () => {
+    expect(JANITOR_SCHEDULE_NAME).toBe("ltm-janitor");
+    expect(JANITOR_QUEUE).toBe("ltm-janitor-queue");
+    expect(JANITOR_CHANNEL).toBe("janitor");
+    expect(DEFAULT_JANITOR_CRON).toBe("@every 6h");
+  });
+
+  it("registerJanitorSchedule returns false when honker is unavailable", () => {
+    expect(registerJanitorSchedule()).toBe(false);
+  });
+
+  it("startJanitorScheduler returns an inert handle when unavailable", async () => {
+    const s = startJanitorScheduler();
+    expect(s.running).toBe(false);
+    await expect(s.stop()).resolves.toBeUndefined();
+  });
+});

package/src/__tests__/vec/index.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeAll } from "bun:test";
+import { Database } from "bun:sqlite";
+import { ensureCustomSqlite, loadExtensions, getCapabilities } from "../../extensions.js";
+import {
+  ensureVecTable,
+  upsertVec,
+  deleteVec,
+  knnVec,
+  rebuildVecIndex,
+  getActiveEmbedDim,
+  isVecAvailable,
+  DEFAULT_EMBED_DIM,
+} from "../../vec/index.js";
+
+const DIM = 4;
+const blob = (a: number[]) => new Uint8Array(new Float32Array(a).buffer);
+
+function seedEmbeddingsTable(db: Database): void {
+  db.exec(`CREATE TABLE memory_embeddings (
+    memory_id INTEGER PRIMARY KEY, embedding BLOB NOT NULL,
+    model TEXT NOT NULL DEFAULT 'unknown', dim INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')))`);
+  db.exec(`CREATE TABLE settings (key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at TEXT)`);
+}
+
+describe("vec module", () => {
+  let db: Database;
+  let vecOn: boolean;
+
+  beforeAll(() => {
+    ensureCustomSqlite();
+    db = new Database(":memory:");
+    loadExtensions(db);
+    vecOn = getCapabilities().vec;
+    seedEmbeddingsTable(db);
+  });
+
+  it("getActiveEmbedDim defaults to 768 with no settings row", () => {
+    expect(getActiveEmbedDim(db)).toBe(DEFAULT_EMBED_DIM);
+  });
+
+  it("getActiveEmbedDim reads the ltm.embed.dim setting", () => {
+    db.run("INSERT OR REPLACE INTO settings(key,value) VALUES ('ltm.embed.dim','512')");
+    expect(getActiveEmbedDim(db)).toBe(512);
+    db.run("DELETE FROM settings WHERE key='ltm.embed.dim'");
+  });
+
+  it("isVecAvailable mirrors getCapabilities().vec", () => {
+    expect(isVecAvailable()).toBe(vecOn);
+  });
+
+  it("all ops are graceful no-ops when vec is unavailable", () => {
+    if (vecOn) return; // covered by the active-path tests below
+    expect(ensureVecTable(db, DIM)).toBe(false);
+    expect(upsertVec(db, 1, blob([1, 0, 0, 0]))).toBe(false);
+    expect(deleteVec(db, 1)).toBe(false);
+    expect(knnVec(db, blob([1, 0, 0, 0]), 3)).toEqual([]);
+    expect(rebuildVecIndex(db, { dim: DIM })).toBe(-1);
+  });
+
+  it("ensure + upsert + KNN returns nearest by cosine similarity", () => {
+    if (!vecOn) return;
+    expect(ensureVecTable(db, DIM)).toBe(true);
+    expect(upsertVec(db, 10, blob([1, 0, 0, 0]))).toBe(true);
+    expect(upsertVec(db, 20, blob([0, 1, 0, 0]))).toBe(true);
+    expect(upsertVec(db, 30, blob([1, 1, 0, 0]))).toBe(true);
+
+    const hits = knnVec(db, blob([1, 0, 0, 0]), 3);
+    expect(hits[0]?.id).toBe(10);
+    expect(hits[0]?.similarity).toBeCloseTo(1, 5);
+    // orthogonal vector ranks last
+    expect(hits[hits.length - 1]?.id).toBe(20);
+  });
+
+  it("upsert overwrites an existing vector (update path)", () => {
+    if (!vecOn) return;
+    upsertVec(db, 20, blob([1, 0, 0, 0])); // was orthogonal, now identical
+    const hits = knnVec(db, blob([1, 0, 0, 0]), 1);
+    expect(hits[0]?.similarity).toBeCloseTo(1, 5);
+  });
+
+  it("deleteVec removes a row from the index", () => {
+    if (!vecOn) return;
+    expect(deleteVec(db, 30)).toBe(true);
+    const hits = knnVec(db, blob([1, 1, 0, 0]), 5);
+    expect(hits.some((h) => h.id === 30)).toBe(false);
+  });
+
+  it("rebuildVecIndex repopulates from memory_embeddings for the active dim", () => {
+    if (!vecOn) return;
+    db.exec("DELETE FROM memory_embeddings");
+    for (let i = 1; i <= 5; i++) {
+      db.run("INSERT INTO memory_embeddings(memory_id, embedding, model, dim) VALUES (?,?,?,?)", [
+        i,
+        blob([i, 0, 0, 0]),
+        "nomic-embed-text",
+        DIM,
+      ]);
+    }
+    // a stray row at a different dim must be excluded
+    db.run("INSERT INTO memory_embeddings(memory_id, embedding, model, dim) VALUES (?,?,?,?)", [
+      99,
+      new Uint8Array(new Float32Array([1, 2]).buffer),
+      "nomic-embed-text",
+      2,
+    ]);
+    const n = rebuildVecIndex(db, { dim: DIM, model: "nomic-embed-text" });
+    expect(n).toBe(5);
+    const hits = knnVec(db, blob([5, 0, 0, 0]), 1);
+    expect(hits[0]?.id).toBe(5);
+  });
+
+  it("scales to 1k vectors and returns the exact nearest", () => {
+    if (!vecOn) return;
+    rebuildVecIndex(db, { dim: DIM }); // clear
+    ensureVecTable(db, DIM);
+    db.transaction(() => {
+      for (let i = 1; i <= 1000; i++) {
+        upsertVec(db, i, blob([Math.random(), Math.random(), Math.random(), Math.random()]));
+      }
+    })();
+    const target = blob([0.123, 0.456, 0.789, 0.321]);
+    upsertVec(db, 7777, target);
+    const t0 = performance.now();
+    const hits = knnVec(db, target, 5);
+    const ms = performance.now() - t0;
+    expect(hits[0]?.id).toBe(7777);
+    expect(ms).toBeLessThan(500); // generous bound — ANN over 1k must be fast
+  });
+});

package/src/__tests__/vec/parity.test.ts

@@ -0,0 +1,70 @@
+/**
+ * parity.test.ts — proves the sqlite-vec vec0 KNN ranking agrees with the
+ * brute-force JS-cosine ranking that getSimilarMemories falls back to. These
+ * are the two code paths the read path switches between, so their top-K order
+ * over identical data must match.
+ */
+import { describe, it, expect, beforeAll } from "bun:test";
+import { Database } from "bun:sqlite";
+import { ensureCustomSqlite, loadExtensions, getCapabilities } from "../../extensions.js";
+import { ensureVecTable, upsertVec, knnVec } from "../../vec/index.js";
+
+const DIM = 8;
+const blob = (a: number[]) => new Uint8Array(new Float32Array(a).buffer);
+
+function cosine(a: Float32Array, b: Float32Array): number {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += (a[i] as number) * (b[i] as number);
+    na += (a[i] as number) ** 2;
+    nb += (b[i] as number) ** 2;
+  }
+  const d = Math.sqrt(na) * Math.sqrt(nb);
+  return d === 0 ? 0 : dot / d;
+}
+
+describe("vec/brute-force recall parity", () => {
+  let db: Database;
+  let vecOn: boolean;
+  const vectors = new Map<number, Float32Array>();
+
+  beforeAll(() => {
+    ensureCustomSqlite();
+    db = new Database(":memory:");
+    loadExtensions(db);
+    vecOn = getCapabilities().vec;
+    if (!vecOn) return;
+    ensureVecTable(db, DIM);
+    for (let id = 1; id <= 200; id++) {
+      const v = Array.from({ length: DIM }, () => Math.random());
+      vectors.set(id, new Float32Array(v));
+      upsertVec(db, id, blob(v));
+    }
+  });
+
+  it("top-5 KNN ids match the top-5 by JS cosine", () => {
+    if (!vecOn) return;
+    const query = Array.from({ length: DIM }, () => Math.random());
+    const qVec = new Float32Array(query);
+
+    const knnIds = knnVec(db, blob(query), 5).map((h) => h.id);
+
+    const bruteIds = [...vectors.entries()]
+      .map(([id, v]) => ({ id, sim: cosine(qVec, v) }))
+      .sort((a, b) => b.sim - a.sim)
+      .slice(0, 5)
+      .map((r) => r.id);
+
+    expect(knnIds).toEqual(bruteIds);
+  });
+
+  it("KNN similarity equals JS cosine for each returned hit", () => {
+    if (!vecOn) return;
+    const query = Array.from({ length: DIM }, () => Math.random());
+    const qVec = new Float32Array(query);
+    const hits = knnVec(db, blob(query), 5);
+    for (const h of hits) {
+      expect(h.similarity).toBeCloseTo(cosine(qVec, vectors.get(h.id)!), 4);
+    }
+  });
+});

package/src/adapterTypes.ts

@@ -0,0 +1,23 @@
+/** Configuration injected by the host adapter (Claude Code, OpenCode, Pi). */
+export interface LtmCoreConfig {
+  dbPath: string;
+  schemaPath?: string;
+  migrationsDir?: string;
+  docsDir?: string;
+  decayEnabled?: boolean;
+  graphReasoning?: boolean;
+  semanticFallback?: boolean;
+  autoRelate?: boolean;
+}
+
+/** Session context passed from the host to openltm-core hooks. */
+export interface LtmAdapterContext {
+  cwd: string;
+  project?: string;
+}
+
+/** Options provided to the adapter factory. */
+export interface LtmAdapterOptions {
+  config: LtmCoreConfig;
+  pluginDataDir?: string;
+}

package/src/cli/_shared.ts

@@ -0,0 +1,120 @@
+/**
+ * cli/_shared.ts — Pure wiring helpers shared by all per-target installers.
+ *
+ * No filesystem access — all functions are pure transformations over plain
+ * objects. This makes them easy to unit-test and safe to compose.
+ */
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface McpServerEntry {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+export interface ClaudeSettings {
+  mcpServers?: Record<string, McpServerEntry>;
+  hooks?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Deep-compare two MCP server entries for structural equivalence.
+ * Returns true only if command, args, and env are all identical.
+ */
+function entriesEqual(a: McpServerEntry, b: McpServerEntry): boolean {
+  if (a.command !== b.command) return false;
+  const aArgs = JSON.stringify(a.args ?? []);
+  const bArgs = JSON.stringify(b.args ?? []);
+  if (aArgs !== bArgs) return false;
+  const aEnv = JSON.stringify(a.env ?? {});
+  const bEnv = JSON.stringify(b.env ?? {});
+  return aEnv === bEnv;
+}
+
+/**
+ * mergeMcpEntry — add or replace a named MCP server entry in settings.
+ *
+ * - If `name` is already present with the same shape → return `settings`
+ *   unchanged (no new object allocation).
+ * - Otherwise → return a new settings object with the entry added/replaced.
+ *
+ * @param settings - Existing Claude settings object (not mutated).
+ * @param name     - Key under `mcpServers` (e.g. `"ltm"`).
+ * @param entry    - The MCP server config to set.
+ */
+export function mergeMcpEntry(
+  settings: ClaudeSettings,
+  name: string,
+  entry: McpServerEntry,
+): ClaudeSettings {
+  const existing = settings.mcpServers?.[name];
+  if (existing && entriesEqual(existing, entry)) {
+    return settings;
+  }
+  return {
+    ...settings,
+    mcpServers: {
+      ...(settings.mcpServers ?? {}),
+      [name]: entry,
+    },
+  };
+}
+
+/**
+ * wireHooks — add a hook command under `settings.hooks[hookName]` if not
+ * already present.
+ *
+ * The hook format expected by Claude Code is an array of matchers under each
+ * event name. We store hooks as:
+ *   { hooks: { [hookName]: [ { command, args } ] } }
+ *
+ * Idempotency: a hook is considered present if any existing entry has the
+ * same `command` and `args[0]` (package name).
+ *
+ * @param settings - Existing Claude settings object (not mutated).
+ * @param hookName - Event name e.g. `"SessionStart"`.
+ * @param command  - Executable e.g. `"bunx"`.
+ * @param args     - Argument list e.g. `["@rohirik/openltm-core", "hook", "--name", "SessionStart"]`.
+ */
+export function wireHooks(
+  settings: ClaudeSettings,
+  hookName: string,
+  command: string,
+  args: string[],
+): ClaudeSettings {
+  const existing = (settings.hooks ?? {}) as Record<string, unknown>;
+  const hookList = existing[hookName];
+  const newEntry = { command, args };
+
+  if (Array.isArray(hookList)) {
+    const alreadyPresent = hookList.some(
+      (h): h is { command: string; args: string[] } =>
+        typeof h === "object" &&
+        h !== null &&
+        (h as { command?: string }).command === command &&
+        Array.isArray((h as { args?: unknown[] }).args) &&
+        (h as { args: unknown[] }).args[0] === args[0],
+    );
+    if (alreadyPresent) return settings;
+
+    return {
+      ...settings,
+      hooks: {
+        ...existing,
+        [hookName]: [...hookList, newEntry],
+      },
+    };
+  }
+
+  return {
+    ...settings,
+    hooks: {
+      ...existing,
+      [hookName]: [newEntry],
+    },
+  };
+}