akm-cli 0.6.0 → 0.7.0-rc1

package/dist/tests/embedding-model-config.test.js

@@ -0,0 +1,379 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+mock.module("@huggingface/transformers", () => ({
+    pipeline: async () => {
+        return async () => ({
+            data: (() => {
+                const vector = new Float32Array(384);
+                vector[0] = 0.1;
+                vector[1] = 0.2;
+                vector[2] = 0.3;
+                return vector;
+            })(),
+        });
+    },
+}));
+beforeEach(async () => {
+    const { clearEmbeddingCache, resetLocalEmbedder } = await import("../src/llm/embedder");
+    clearEmbeddingCache();
+    resetLocalEmbedder();
+});
+// ── Test 1: DEFAULT_LOCAL_MODEL constant is exported and correct ──────────
+describe("DEFAULT_LOCAL_MODEL", () => {
+    test("is exported and has the expected value", async () => {
+        const { DEFAULT_LOCAL_MODEL } = await import("../src/llm/embedder");
+        expect(DEFAULT_LOCAL_MODEL).toBe("Xenova/bge-small-en-v1.5");
+    });
+    test("is a non-empty string", async () => {
+        const { DEFAULT_LOCAL_MODEL } = await import("../src/llm/embedder");
+        expect(typeof DEFAULT_LOCAL_MODEL).toBe("string");
+        expect(DEFAULT_LOCAL_MODEL.length).toBeGreaterThan(0);
+    });
+});
+// ── Test 2: EmbeddingConnectionConfig accepts localModel field ────────────
+describe("EmbeddingConnectionConfig localModel field", () => {
+    test("accepts localModel as an optional string field", () => {
+        // This is a type-level test — if it compiles, the field is accepted
+        const config = {
+            endpoint: "http://localhost:11434/v1/embeddings",
+            model: "nomic-embed-text",
+            localModel: "Xenova/all-MiniLM-L6-v2",
+        };
+        expect(config.localModel).toBe("Xenova/all-MiniLM-L6-v2");
+    });
+    test("works without localModel (backward compatible)", () => {
+        const config = {
+            endpoint: "http://localhost:11434/v1/embeddings",
+            model: "nomic-embed-text",
+        };
+        expect(config.localModel).toBeUndefined();
+    });
+});
+// ── Test 3: embed() uses DEFAULT_LOCAL_MODEL when no config ───────────────
+describe("embed model selection", () => {
+    test("embed() falls back to local when no config is provided", async () => {
+        const { embed } = await import("../src/llm/embedder");
+        const result = await embed("hello");
+        expect(Array.isArray(result)).toBe(true);
+        expect(result.length).toBeGreaterThan(0);
+    });
+    test("embed() uses localModel from config when no remote endpoint", async () => {
+        const { embed } = await import("../src/llm/embedder");
+        const config = {
+            endpoint: "",
+            model: "",
+            localModel: "Xenova/all-MiniLM-L6-v2",
+        };
+        const result = await embed("hello", config);
+        expect(Array.isArray(result)).toBe(true);
+    });
+});
+// ── Test 4: EmbeddingConnectionConfig type accepts localModel field ───────
+describe("EmbeddingConnectionConfig type accepts localModel field", () => {
+    test("AkmConfig embedding field accepts localModel", () => {
+        // Type-system validation: verifies the interface accepts localModel
+        const config = {
+            semanticSearchMode: "auto",
+            embedding: {
+                endpoint: "http://localhost:11434/v1/embeddings",
+                model: "nomic-embed-text",
+                localModel: "Xenova/bge-small-en-v1.5",
+            },
+        };
+        expect(config.embedding?.localModel).toBe("Xenova/bge-small-en-v1.5");
+    });
+    test("old configs without localModel still work", () => {
+        const config = {
+            semanticSearchMode: "auto",
+            embedding: {
+                endpoint: "http://localhost:11434/v1/embeddings",
+                model: "nomic-embed-text",
+            },
+        };
+        expect(config.embedding?.localModel).toBeUndefined();
+        // The config is valid and should not cause errors
+        expect(config.embedding?.endpoint).toBe("http://localhost:11434/v1/embeddings");
+        expect(config.embedding?.model).toBe("nomic-embed-text");
+    });
+});
+// ── Test 5: Remote endpoint config still works independently ──────────────
+describe("remote endpoint independence", () => {
+    test("setting localModel does not affect remote endpoint behavior", async () => {
+        // Create a mock embedding server
+        const server = Bun.serve({
+            port: 0,
+            async fetch(request) {
+                const body = (await request.json());
+                return new Response(JSON.stringify({
+                    data: [{ embedding: [0.5, 0.6, 0.7] }],
+                    model: body.model,
+                    usage: { prompt_tokens: 5, total_tokens: 5 },
+                }), { headers: { "Content-Type": "application/json" } });
+            },
+        });
+        try {
+            const { embed } = await import("../src/llm/embedder");
+            const config = {
+                endpoint: `http://localhost:${server.port}`,
+                model: "remote-model",
+                localModel: "Xenova/bge-small-en-v1.5",
+            };
+            // Remote embedding should still work — localModel should not interfere
+            const result = await embed("hello world", config);
+            expect(result.length).toBe(3);
+            // Result should be L2-normalized
+            const norm = Math.sqrt(result.reduce((sum, v) => sum + v * v, 0));
+            expect(norm).toBeCloseTo(1.0, 5);
+        }
+        finally {
+            server.stop();
+        }
+    });
+    test("remote embed does not send localModel to the API", async () => {
+        let capturedBody;
+        const server = Bun.serve({
+            port: 0,
+            async fetch(request) {
+                capturedBody = (await request.json());
+                return new Response(JSON.stringify({
+                    data: [{ embedding: [0.1, 0.2] }],
+                    model: "test",
+                    usage: { prompt_tokens: 5, total_tokens: 5 },
+                }), { headers: { "Content-Type": "application/json" } });
+            },
+        });
+        try {
+            const { embed } = await import("../src/llm/embedder");
+            const config = {
+                endpoint: `http://localhost:${server.port}`,
+                model: "remote-model",
+                localModel: "Xenova/bge-small-en-v1.5",
+            };
+            await embed("test", config);
+            // The request body should use `model` (not localModel) and should
+            // not include localModel as a field
+            expect(capturedBody).toBeDefined();
+            expect(capturedBody?.model).toBe("remote-model");
+            expect(capturedBody).not.toHaveProperty("localModel");
+        }
+        finally {
+            server.stop();
+        }
+    });
+});
+// ── Test 6: Dimension consistency ─────────────────────────────────────────
+describe("dimension consistency on model change", () => {
+    test("cosineSimilarity returns 0 for dimension mismatch (different models produce different dims)", async () => {
+        const { cosineSimilarity } = await import("../src/llm/embedder");
+        const originalWarn = console.warn;
+        const warnings = [];
+        // Simulate a 384-dim vector (old model) vs 768-dim vector (new model)
+        const vec384 = Array(384).fill(1 / Math.sqrt(384));
+        const vec768 = Array(768).fill(1 / Math.sqrt(768));
+        try {
+            console.warn = (...args) => {
+                warnings.push(args.map(String).join(" "));
+            };
+            const similarity = cosineSimilarity(vec384, vec768);
+            expect(similarity).toBe(0);
+            expect(warnings.some((warning) => warning.includes("vector dimension mismatch"))).toBe(true);
+        }
+        finally {
+            console.warn = originalWarn;
+        }
+    });
+    test("db dimension mismatch triggers vec table recreation", async () => {
+        // This is already tested in db.test.ts but we verify the concept:
+        // when embedding dimensions change (due to model change), the
+        // database handles it by recreating the vec table
+        const { openDatabase, closeDatabase, getMeta, isVecAvailable } = await import("../src/indexer/db");
+        const fs = await import("node:fs");
+        const os = await import("node:os");
+        const path = await import("node:path");
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-embed-model-"));
+        const dbPath = path.join(tmpDir, "test.db");
+        try {
+            // Open with old model dimension (384 = all-MiniLM-L6-v2)
+            let db = openDatabase(dbPath, { embeddingDim: 384 });
+            if (isVecAvailable(db)) {
+                expect(getMeta(db, "embeddingDim")).toBe("384");
+            }
+            closeDatabase(db);
+            // Open with new model dimension (384 = bge-small-en-v1.5, same dims)
+            // Both models happen to be 384-dim, so no recreation needed
+            db = openDatabase(dbPath, { embeddingDim: 384 });
+            if (isVecAvailable(db)) {
+                expect(getMeta(db, "embeddingDim")).toBe("384");
+            }
+            closeDatabase(db);
+            // But if someone uses a different-dimension model (e.g. 768), it should recreate
+            db = openDatabase(dbPath, { embeddingDim: 768 });
+            if (isVecAvailable(db)) {
+                expect(getMeta(db, "embeddingDim")).toBe("768");
+            }
+            closeDatabase(db);
+        }
+        finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
+// ── Test 7: Config parsing roundtrip for localModel via loadConfig ────────
+describe("config file parsing for localModel", () => {
+    test("parseEmbeddingConfig preserves localModel from raw config object", async () => {
+        const { loadConfig } = await import("../src/core/config");
+        const fs = await import("node:fs");
+        const os = await import("node:os");
+        const path = await import("node:path");
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-config-test-"));
+        const configData = {
+            semanticSearchMode: "auto",
+            embedding: {
+                endpoint: "http://localhost:11434/v1/embeddings",
+                model: "nomic-embed-text",
+                localModel: "Xenova/bge-small-en-v1.5",
+            },
+        };
+        // Save and restore environment
+        const origXDG = process.env.XDG_CONFIG_HOME;
+        try {
+            // Point config to our temp directory
+            process.env.XDG_CONFIG_HOME = tmpDir;
+            // Create the akm subdirectory structure expected by getConfigPath
+            const akmDir = path.join(tmpDir, "akm");
+            fs.mkdirSync(akmDir, { recursive: true });
+            fs.writeFileSync(path.join(akmDir, "config.json"), JSON.stringify(configData));
+            // Actually call loadConfig to test the parsing path
+            const config = loadConfig();
+            expect(config.embedding).toBeDefined();
+            expect(config.embedding?.localModel).toBe("Xenova/bge-small-en-v1.5");
+            expect(config.embedding?.endpoint).toBe("http://localhost:11434/v1/embeddings");
+            expect(config.embedding?.model).toBe("nomic-embed-text");
+        }
+        finally {
+            if (origXDG === undefined) {
+                delete process.env.XDG_CONFIG_HOME;
+            }
+            else {
+                process.env.XDG_CONFIG_HOME = origXDG;
+            }
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+    test("parseEmbeddingConfig returns local-only config for localModel without endpoint", async () => {
+        const { loadConfig } = await import("../src/core/config");
+        const fs = await import("node:fs");
+        const os = await import("node:os");
+        const path = await import("node:path");
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-config-test-"));
+        const configData = {
+            semanticSearchMode: "auto",
+            embedding: {
+                localModel: "Xenova/bge-small-en-v1.5",
+            },
+        };
+        const origXDG = process.env.XDG_CONFIG_HOME;
+        try {
+            process.env.XDG_CONFIG_HOME = tmpDir;
+            const akmDir = path.join(tmpDir, "akm");
+            fs.mkdirSync(akmDir, { recursive: true });
+            fs.writeFileSync(path.join(akmDir, "config.json"), JSON.stringify(configData));
+            const config = loadConfig();
+            expect(config.embedding).toBeDefined();
+            expect(config.embedding?.localModel).toBe("Xenova/bge-small-en-v1.5");
+            // Sentinel empty strings for local-only config
+            expect(config.embedding?.endpoint).toBe("");
+            expect(config.embedding?.model).toBe("");
+        }
+        finally {
+            if (origXDG === undefined) {
+                delete process.env.XDG_CONFIG_HOME;
+            }
+            else {
+                process.env.XDG_CONFIG_HOME = origXDG;
+            }
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
+// ── Test 8: endpoint+localModel+no-model warns and uses local-only ────────
+describe("parseEmbeddingConfig edge cases", () => {
+    test("warns when endpoint present but model missing with localModel set", async () => {
+        const { loadConfig } = await import("../src/core/config");
+        const fs = await import("node:fs");
+        const os = await import("node:os");
+        const path = await import("node:path");
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-config-test-"));
+        const configData = {
+            semanticSearchMode: "auto",
+            embedding: {
+                endpoint: "http://localhost:11434/v1/embeddings",
+                localModel: "Xenova/bge-small-en-v1.5",
+                // Note: model is intentionally missing
+            },
+        };
+        const origXDG = process.env.XDG_CONFIG_HOME;
+        const origWarn = console.warn;
+        const warnings = [];
+        try {
+            console.warn = (...args) => {
+                warnings.push(args.map(String).join(" "));
+            };
+            process.env.XDG_CONFIG_HOME = tmpDir;
+            const akmDir = path.join(tmpDir, "akm");
+            fs.mkdirSync(akmDir, { recursive: true });
+            fs.writeFileSync(path.join(akmDir, "config.json"), JSON.stringify(configData));
+            const config = loadConfig();
+            // Should return local-only config (endpoint discarded)
+            expect(config.embedding).toBeDefined();
+            expect(config.embedding?.localModel).toBe("Xenova/bge-small-en-v1.5");
+            expect(config.embedding?.endpoint).toBe("");
+            expect(config.embedding?.model).toBe("");
+            // Should have emitted a warning about the ignored endpoint
+            const relevantWarning = warnings.find((w) => w.includes("ignored") && w.includes("model is required"));
+            expect(relevantWarning).toBeDefined();
+        }
+        finally {
+            console.warn = origWarn;
+            if (origXDG === undefined) {
+                delete process.env.XDG_CONFIG_HOME;
+            }
+            else {
+                process.env.XDG_CONFIG_HOME = origXDG;
+            }
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+    test("returns undefined when endpoint present but model and localModel both missing", async () => {
+        const { loadConfig } = await import("../src/core/config");
+        const fs = await import("node:fs");
+        const os = await import("node:os");
+        const path = await import("node:path");
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-config-test-"));
+        const configData = {
+            semanticSearchMode: "auto",
+            embedding: {
+                endpoint: "http://localhost:11434/v1/embeddings",
+                // No model, no localModel
+            },
+        };
+        const origXDG = process.env.XDG_CONFIG_HOME;
+        try {
+            process.env.XDG_CONFIG_HOME = tmpDir;
+            const akmDir = path.join(tmpDir, "akm");
+            fs.mkdirSync(akmDir, { recursive: true });
+            fs.writeFileSync(path.join(akmDir, "config.json"), JSON.stringify(configData));
+            const config = loadConfig();
+            // parseEmbeddingConfig returns undefined => no embedding config set
+            expect(config.embedding).toBeUndefined();
+        }
+        finally {
+            if (origXDG === undefined) {
+                delete process.env.XDG_CONFIG_HOME;
+            }
+            else {
+                process.env.XDG_CONFIG_HOME = origXDG;
+            }
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/tests/feedback-command.test.js

@@ -0,0 +1,172 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { akmSearch } from "../src/commands/search";
+import { saveConfig } from "../src/core/config";
+import { getDbPath } from "../src/core/paths";
+import { closeDatabase, openDatabase } from "../src/indexer/db";
+import { akmIndex } from "../src/indexer/indexer";
+const CLI = path.join(__dirname, "..", "src", "cli.ts");
+const tempDirs = [];
+const savedEnv = {
+    AKM_STASH_DIR: process.env.AKM_STASH_DIR,
+    XDG_CACHE_HOME: process.env.XDG_CACHE_HOME,
+    XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
+};
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function writeFile(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+}
+function runCli(args) {
+    const result = spawnSync("bun", [CLI, ...args], {
+        encoding: "utf8",
+        timeout: 30_000,
+        env: { ...process.env },
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+function parseJsonOutput(result) {
+    const payload = result.stdout.trim() || result.stderr.trim();
+    return JSON.parse(payload);
+}
+function isLocalHit(hit) {
+    return hit.type !== "registry";
+}
+async function buildIndex(stashDir) {
+    process.env.AKM_STASH_DIR = stashDir;
+    saveConfig({ semanticSearchMode: "off" });
+    await akmIndex({ stashDir, full: true });
+}
+afterEach(() => {
+    if (savedEnv.AKM_STASH_DIR === undefined)
+        delete process.env.AKM_STASH_DIR;
+    else
+        process.env.AKM_STASH_DIR = savedEnv.AKM_STASH_DIR;
+    if (savedEnv.XDG_CACHE_HOME === undefined)
+        delete process.env.XDG_CACHE_HOME;
+    else
+        process.env.XDG_CACHE_HOME = savedEnv.XDG_CACHE_HOME;
+    if (savedEnv.XDG_CONFIG_HOME === undefined)
+        delete process.env.XDG_CONFIG_HOME;
+    else
+        process.env.XDG_CONFIG_HOME = savedEnv.XDG_CONFIG_HOME;
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe("akm feedback", () => {
+    test("accepts indexed memory and vault refs without surfacing vault values", async () => {
+        const stashDir = makeTempDir("akm-feedback-stash-");
+        process.env.XDG_CACHE_HOME = makeTempDir("akm-feedback-cache-");
+        process.env.XDG_CONFIG_HOME = makeTempDir("akm-feedback-config-");
+        writeFile(path.join(stashDir, "memories", "deployment-notes.md"), "---\ndescription: deployment memory\n---\nRemember the VPN before deploy.\n");
+        writeFile(path.join(stashDir, "vaults", "prod.env"), "API_KEY=super-secret-value\nREGION=us-east-1\n");
+        await buildIndex(stashDir);
+        const memoryResult = runCli(["feedback", "memory:deployment-notes", "--positive", "--format=json"]);
+        expect(memoryResult.status).toBe(0);
+        expect(parseJsonOutput(memoryResult)).toMatchObject({
+            ok: true,
+            ref: "memory:deployment-notes",
+            signal: "positive",
+        });
+        const vaultResult = runCli(["feedback", "vault:prod", "--positive", "--format=json"]);
+        expect(vaultResult.status).toBe(0);
+        expect(parseJsonOutput(vaultResult)).toMatchObject({
+            ok: true,
+            ref: "vault:prod",
+            signal: "positive",
+        });
+        expect(vaultResult.stdout).not.toContain("super-secret-value");
+        expect(vaultResult.stdout).not.toContain("REGION");
+        const db = openDatabase(getDbPath());
+        try {
+            const events = db
+                .prepare("SELECT entry_ref, entry_id, signal FROM usage_events WHERE event_type = 'feedback' ORDER BY entry_ref ASC")
+                .all();
+            expect(events).toHaveLength(2);
+            expect(events[0]?.entry_ref).toBe("memory:deployment-notes");
+            expect(events[0]?.entry_id).toEqual(expect.any(Number));
+            expect(events[0]?.signal).toBe("positive");
+            expect(events[1]?.entry_ref).toBe("vault:prod");
+            expect(events[1]?.entry_id).toEqual(expect.any(Number));
+            expect(events[1]?.signal).toBe("positive");
+        }
+        finally {
+            closeDatabase(db);
+        }
+    });
+    test("rejects refs that are validly formatted but not in the current index", async () => {
+        const stashDir = makeTempDir("akm-feedback-stash-");
+        process.env.XDG_CACHE_HOME = makeTempDir("akm-feedback-cache-");
+        process.env.XDG_CONFIG_HOME = makeTempDir("akm-feedback-config-");
+        writeFile(path.join(stashDir, "memories", "known.md"), "---\ndescription: known memory\n---\nKnown.\n");
+        await buildIndex(stashDir);
+        const result = runCli(["feedback", "memory:missing", "--positive", "--format=json"]);
+        expect(result.status).not.toBe(0);
+        expect(parseJsonOutput(result)).toMatchObject({
+            ok: false,
+            error: 'Ref "memory:missing" is not in the current index. Run "akm index" and try again.',
+        });
+    });
+    // ── #284 GAP-HIGH 8: feedback --note metadata round-trip ────────────────
+    test("feedback --note threads metadata into events.jsonl", async () => {
+        const stashDir = makeTempDir("akm-feedback-stash-");
+        process.env.XDG_CACHE_HOME = makeTempDir("akm-feedback-cache-");
+        process.env.XDG_CONFIG_HOME = makeTempDir("akm-feedback-config-");
+        writeFile(path.join(stashDir, "memories", "deployment-notes.md"), "---\ndescription: deployment memory\n---\nRemember the VPN before deploy.\n");
+        await buildIndex(stashDir);
+        const result = runCli([
+            "feedback",
+            "memory:deployment-notes",
+            "--positive",
+            "--note",
+            "saved me 30 minutes",
+            "--format=json",
+        ]);
+        expect(result.status).toBe(0);
+        const parsed = parseJsonOutput(result);
+        expect(parsed).toMatchObject({
+            ok: true,
+            ref: "memory:deployment-notes",
+            signal: "positive",
+            note: "saved me 30 minutes",
+        });
+        // Read events.jsonl directly and verify the note was persisted in metadata.
+        const { readEvents } = await import("../src/core/events");
+        const { events } = readEvents({ type: "feedback", ref: "memory:deployment-notes" });
+        expect(events.length).toBeGreaterThan(0);
+        const md = (events.at(-1)?.metadata ?? {});
+        expect(md.note).toBe("saved me 30 minutes");
+        expect(md.signal).toBe("positive");
+    });
+    test("positive feedback affects subsequent ranking after re-indexing", async () => {
+        const stashDir = makeTempDir("akm-feedback-stash-");
+        process.env.XDG_CACHE_HOME = makeTempDir("akm-feedback-cache-");
+        process.env.XDG_CONFIG_HOME = makeTempDir("akm-feedback-config-");
+        writeFile(path.join(stashDir, "memories", "alpha.md"), "---\ndescription: shared deployment incident memory\n---\nUse the same deployment incident checklist.\n");
+        writeFile(path.join(stashDir, "memories", "omega.md"), "---\ndescription: shared deployment incident memory\n---\nUse the same deployment incident checklist.\n");
+        await buildIndex(stashDir);
+        const before = await akmSearch({ query: "shared deployment incident", source: "local" });
+        const beforeMemories = before.hits.filter(isLocalHit).filter((hit) => hit.type === "memory");
+        expect(beforeMemories.slice(0, 2).map((hit) => hit.ref)).toEqual(["memory:alpha", "memory:omega"]);
+        expect(beforeMemories[0]?.score).toBe(beforeMemories[1]?.score);
+        const feedback = runCli(["feedback", "memory:omega", "--positive", "--format=json"]);
+        expect(feedback.status).toBe(0);
+        await buildIndex(stashDir);
+        const after = await akmSearch({ query: "shared deployment incident", source: "local" });
+        const afterMemories = after.hits.filter(isLocalHit).filter((hit) => hit.type === "memory");
+        expect(afterMemories[0]?.ref).toBe("memory:omega");
+        expect(afterMemories[0]?.whyMatched).toContain("usage history boost");
+    });
+});