sverklo 0.2.12 → 0.2.14

package/dist/src/indexer/symbol-extractor.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import { extractReferences } from "./symbol-extractor.js";
+// Regression test for github.com/sverklo/sverklo/issues/13.
+//
+// The old implementation used a chunk-wide `seen` set to dedupe
+// references. That made sverklo_impact lossy: a symbol called N
+// times in the same function returned only one row, pointing at
+// the first call site. For refactor safety — the whole point of
+// the impact tool — this was the worst possible failure mode:
+// the user trusted the output, made the refactor, missed N-1 real
+// call sites, shipped the bug.
+//
+// The fix: per-line dedupe (still prevents double-counting when
+// two regexes both fire on the same line, e.g. `new Foo()` or
+// `Foo(Foo())`) while letting repeat calls across lines each
+// contribute their own symbol_ref row.
+describe("extractReferences — issue #13 regression", () => {
+    it("records multiple call sites of the same symbol across lines", () => {
+        const content = [
+            "function index() {",
+            "  const vectors = await embed(texts);",
+            "  // ...",
+            "  const [vector] = await embed([text]);",
+            "  return vectors;",
+            "}",
+        ].join("\n");
+        const refs = extractReferences(content, "index");
+        const embedRefs = refs.filter((r) => r.name === "embed");
+        expect(embedRefs.length).toBe(2);
+        expect(embedRefs[0].line).toBe(1);
+        expect(embedRefs[1].line).toBe(3);
+    });
+    it("still dedupes the same symbol on the same line (regex collision guard)", () => {
+        // A line with two occurrences of the same identifier should
+        // still produce only one ref entry — per-line dedupe survives.
+        const content = ["function outer() {", "  return foo(foo(x));", "}"].join("\n");
+        const refs = extractReferences(content, "outer");
+        const fooRefs = refs.filter((r) => r.name === "foo");
+        // Exactly one foo ref on line 1 — not two from the nested call.
+        expect(fooRefs.length).toBe(1);
+    });
+    it("records calls in distinct branches as distinct refs", () => {
+        const content = [
+            "function handle(x) {",
+            "  if (x > 0) {",
+            "    publish(x);",
+            "  } else {",
+            "    publish(null);",
+            "  }",
+            "}",
+        ].join("\n");
+        const refs = extractReferences(content, "handle");
+        const publishRefs = refs.filter((r) => r.name === "publish");
+        expect(publishRefs.length).toBe(2);
+    });
+    it("does not record a self-reference when selfName matches", () => {
+        const content = ["function fact(n) {", "  return n * fact(n - 1);", "}"].join("\n");
+        const refs = extractReferences(content, "fact");
+        expect(refs.filter((r) => r.name === "fact").length).toBe(0);
+    });
+    it("strips string literals before matching", () => {
+        // `foo` in a string is not a real call — must not be recorded.
+        const content = [
+            "function log() {",
+            "  const msg = 'foo was called here';",
+            '  const other = "foo";',
+            "  foo();",
+            "}",
+        ].join("\n");
+        const refs = extractReferences(content, "log");
+        const fooRefs = refs.filter((r) => r.name === "foo");
+        // Only the real call on the last line.
+        expect(fooRefs.length).toBe(1);
+        expect(fooRefs[0].line).toBe(3);
+    });
+    it("strips line comments before matching", () => {
+        const content = [
+            "function test() {",
+            "  // foo() is not actually called here",
+            "  bar();",
+            "}",
+        ].join("\n");
+        const refs = extractReferences(content, "test");
+        expect(refs.some((r) => r.name === "foo")).toBe(false);
+        expect(refs.some((r) => r.name === "bar")).toBe(true);
+    });
+});
+//# sourceMappingURL=symbol-extractor.test.js.map

package/dist/src/indexer/symbol-extractor.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-extractor.test.js","sourceRoot":"","sources":["../../../src/indexer/symbol-extractor.test.ts"],"names":[],"mappings":"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"}

package/dist/src/indexer/watcher.js

@@ -29,6 +29,9 @@ export function startWatcher(indexer, rootPath) {
         const lang = detectLanguage(absolutePath);
         if (!lang)
             return;
+        // Any real change invalidates the freshness cache immediately so the
+        // next sverklo_status reflects reality without waiting for the TTL.
+        indexer.invalidateFreshnessCache();
         // Debounce
         const existing = pending.get(rel);
         if (existing)
@@ -44,6 +47,7 @@ export function startWatcher(indexer, rootPath) {
     watcher.on("unlink", (absolutePath) => {
         const rel = relative(rootPath, absolutePath);
         log(`File removed: ${rel}`);
+        indexer.invalidateFreshnessCache();
         indexer.removeFile(rel);
     });
     log("File watcher started");

package/dist/src/indexer/watcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../../src/indexer/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAGzC,MAAM,UAAU,YAAY,CAAC,OAAgB,EAAE,QAAgB;IAC7D,MAAM,YAAY,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAElD,gCAAgC;IAChC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAClD,MAAM,WAAW,GAAG,GAAG,CAAC;IAExB,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE;QAC9B,OAAO,EAAE,CAAC,IAAY,EAAE,EAAE;YACxB,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACrC,IAAI,CAAC,GAAG;gBAAE,OAAO,KAAK,CAAC;YACvB,IAAI,CAAC;gBACH,OAAO,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACnC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,UAAU,EAAE,IAAI;QAChB,aAAa,EAAE,IAAI;QACnB,gBAAgB,EAAE,EAAE,kBAAkB,EAAE,GAAG,EAAE;KAC9C,CAAC,CAAC;IAEH,SAAS,YAAY,CAAC,YAAoB;QACxC,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QAC7C,MAAM,IAAI,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI;YAAE,OAAO;QAElB,WAAW;QACX,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,QAAQ;YAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;QAErC,OAAO,CAAC,GAAG,CACT,GAAG,EACH,UAAU,CAAC,KAAK,IAAI,EAAE;YACpB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,GAAG,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;YAC5B,MAAM,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QACrD,CAAC,EAAE,WAAW,CAAC,CAChB,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,YAAoB,EAAE,EAAE;QAC5C,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QAC7C,GAAG,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;QAC5B,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../../src/indexer/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAGzC,MAAM,UAAU,YAAY,CAAC,OAAgB,EAAE,QAAgB;IAC7D,MAAM,YAAY,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAElD,gCAAgC;IAChC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAClD,MAAM,WAAW,GAAG,GAAG,CAAC;IAExB,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE;QAC9B,OAAO,EAAE,CAAC,IAAY,EAAE,EAAE;YACxB,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACrC,IAAI,CAAC,GAAG;gBAAE,OAAO,KAAK,CAAC;YACvB,IAAI,CAAC;gBACH,OAAO,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACnC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,UAAU,EAAE,IAAI;QAChB,aAAa,EAAE,IAAI;QACnB,gBAAgB,EAAE,EAAE,kBAAkB,EAAE,GAAG,EAAE;KAC9C,CAAC,CAAC;IAEH,SAAS,YAAY,CAAC,YAAoB;QACxC,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QAC7C,MAAM,IAAI,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI;YAAE,OAAO;QAElB,qEAAqE;QACrE,oEAAoE;QACpE,OAAO,CAAC,wBAAwB,EAAE,CAAC;QAEnC,WAAW;QACX,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,QAAQ;YAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;QAErC,OAAO,CAAC,GAAG,CACT,GAAG,EACH,UAAU,CAAC,KAAK,IAAI,EAAE;YACpB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,GAAG,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;YAC5B,MAAM,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QACrD,CAAC,EAAE,WAAW,CAAC,CAChB,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,YAAoB,EAAE,EAAE;QAC5C,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QAC7C,GAAG,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;QAC5B,OAAO,CAAC,wBAAwB,EAAE,CAAC;QACnC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,sBAAsB,CAAC,CAAC;AAC9B,CAAC"}

package/dist/src/memory/journal.d.ts

@@ -0,0 +1,62 @@
+export type JournalOp = "remember" | "forget" | "invalidate" | "promote" | "demote" | "touch";
+export interface JournalEntry {
+    op: JournalOp;
+    id: number;
+    ts: string;
+    content?: string;
+    category?: string;
+    tags?: string[] | null;
+    confidence?: number;
+    git_sha?: string | null;
+    git_branch?: string | null;
+    related_files?: string[] | null;
+    tier?: string;
+    invalidated_at_sha?: string | null;
+    replaced_by_id?: number | null;
+    new_tier?: string;
+}
+/**
+ * MemoryJournal writes append-only JSONL to <project>/.sverklo/memories.jsonl.
+ *
+ * Writes are synchronous on purpose: the journal must be committed
+ * before the corresponding SQLite write returns to the caller, so we
+ * never have a window where SQLite succeeds and the journal is missing
+ * the record. Agent workloads are low-frequency on the memory side
+ * (dozens of writes per session, not thousands) so sync writes are
+ * fine. If memory write volume grows we can batch.
+ *
+ * Errors are swallowed with a log. The journal is advisory for 0.2.x —
+ * a broken journal must not break memory.
+ */
+export declare class MemoryJournal {
+    private path;
+    private ready;
+    constructor(projectRoot: string);
+    private ensureDir;
+    private write;
+    remember(params: {
+        id: number;
+        content: string;
+        category: string;
+        tags?: string[] | null;
+        confidence: number;
+        git_sha?: string | null;
+        git_branch?: string | null;
+        related_files?: string[] | null;
+        tier: string;
+    }): void;
+    forget(id: number): void;
+    invalidate(id: number, atSha: string | null, replacedById: number | null): void;
+    promote(id: number, newTier: string): void;
+    demote(id: number, newTier: string): void;
+    /**
+     * Return the path to the journal file so callers can show it in
+     * error messages ("see .sverklo/memories.jsonl for the write log").
+     */
+    get filePath(): string;
+    /**
+     * True if the journal file exists on disk. Useful for the doctor
+     * command to report journal presence.
+     */
+    exists(): boolean;
+}

package/dist/src/memory/journal.js

@@ -0,0 +1,136 @@
+// Append-only JSONL journal for memory writes (issue #7).
+//
+// Sverklo's memory layer lives in SQLite for query speed, but users
+// can't easily inspect, diff, or sync a binary database. The Memory
+// MCP reference server showed that append-only JSONL is the right
+// format for user-facing memory: human-readable, git-diffable,
+// trivially syncable, and impossible to corrupt in interesting ways.
+//
+// This module ships the JSONL format as a *mirror* of SQLite, not a
+// replacement. Every memory write (remember / forget / promote /
+// demote / invalidate) lands in both places. If the two ever
+// disagree, SQLite is still the source of truth for 0.2.x — the
+// migration to "JSONL as source of truth" is a later, more invasive
+// step tracked in the same issue.
+//
+// Why mirror, not replace, in this step:
+//   - Zero risk to existing users. If the journal is broken, memory
+//     still works from SQLite.
+//   - Users get the user-visible benefit today (cat / git diff /
+//     grep the journal) without waiting for the full migration.
+//   - The journal can be replayed into a fresh SQLite if the index
+//     is ever deleted — a cheap disaster-recovery path.
+//
+// Format: one JSON object per line, one operation per object. Writes
+// are append-only. Tombstones (forget) are records, not file rewrites.
+// Compaction is a later feature — for now we just grow.
+//
+// File location: `<project>/.sverklo/memories.jsonl`. This lives
+// inside the project root on purpose so users can commit it alongside
+// their code. `.sverklo/index.db` and friends stay in `~/.sverklo/`
+// (the user cache) because those are machine-specific.
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { logError } from "../utils/logger.js";
+/**
+ * MemoryJournal writes append-only JSONL to <project>/.sverklo/memories.jsonl.
+ *
+ * Writes are synchronous on purpose: the journal must be committed
+ * before the corresponding SQLite write returns to the caller, so we
+ * never have a window where SQLite succeeds and the journal is missing
+ * the record. Agent workloads are low-frequency on the memory side
+ * (dozens of writes per session, not thousands) so sync writes are
+ * fine. If memory write volume grows we can batch.
+ *
+ * Errors are swallowed with a log. The journal is advisory for 0.2.x —
+ * a broken journal must not break memory.
+ */
+export class MemoryJournal {
+    path;
+    ready = false;
+    constructor(projectRoot) {
+        this.path = join(projectRoot, ".sverklo", "memories.jsonl");
+    }
+    ensureDir() {
+        if (this.ready)
+            return;
+        try {
+            mkdirSync(dirname(this.path), { recursive: true });
+            this.ready = true;
+        }
+        catch (err) {
+            logError("MemoryJournal: could not create .sverklo directory", err);
+        }
+    }
+    write(entry) {
+        this.ensureDir();
+        try {
+            appendFileSync(this.path, JSON.stringify(entry) + "\n", "utf-8");
+        }
+        catch (err) {
+            logError("MemoryJournal: append failed", err);
+        }
+    }
+    remember(params) {
+        this.write({
+            op: "remember",
+            id: params.id,
+            ts: new Date().toISOString(),
+            content: params.content,
+            category: params.category,
+            tags: params.tags ?? null,
+            confidence: params.confidence,
+            git_sha: params.git_sha ?? null,
+            git_branch: params.git_branch ?? null,
+            related_files: params.related_files ?? null,
+            tier: params.tier,
+        });
+    }
+    forget(id) {
+        this.write({
+            op: "forget",
+            id,
+            ts: new Date().toISOString(),
+        });
+    }
+    invalidate(id, atSha, replacedById) {
+        this.write({
+            op: "invalidate",
+            id,
+            ts: new Date().toISOString(),
+            invalidated_at_sha: atSha ?? null,
+            replaced_by_id: replacedById ?? null,
+        });
+    }
+    promote(id, newTier) {
+        this.write({
+            op: "promote",
+            id,
+            ts: new Date().toISOString(),
+            new_tier: newTier,
+        });
+    }
+    demote(id, newTier) {
+        this.write({
+            op: "demote",
+            id,
+            ts: new Date().toISOString(),
+            new_tier: newTier,
+        });
+    }
+    /**
+     * Return the path to the journal file so callers can show it in
+     * error messages ("see .sverklo/memories.jsonl for the write log").
+     */
+    get filePath() {
+        return this.path;
+    }
+    /**
+     * True if the journal file exists on disk. Useful for the doctor
+     * command to report journal presence.
+     */
+    exists() {
+        return existsSync(this.path);
+    }
+}
+//# sourceMappingURL=journal.js.map

package/dist/src/memory/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../../src/memory/journal.ts"],"names":[],"mappings":"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"}

package/dist/src/memory/journal.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/memory/journal.test.js

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MemoryJournal } from "./journal.js";
+describe("MemoryJournal", () => {
+    let projectRoot;
+    beforeEach(() => {
+        projectRoot = mkdtempSync(join(tmpdir(), "sverklo-journal-"));
+    });
+    afterEach(() => {
+        try {
+            rmSync(projectRoot, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it("creates the .sverklo directory and writes an append-only file", () => {
+        const j = new MemoryJournal(projectRoot);
+        j.remember({
+            id: 1,
+            content: "All timestamps are UTC.",
+            category: "procedural",
+            tags: ["timezone"],
+            confidence: 1.0,
+            git_sha: "abc123",
+            git_branch: "main",
+            related_files: ["src/time.ts"],
+            tier: "core",
+        });
+        const path = join(projectRoot, ".sverklo", "memories.jsonl");
+        expect(existsSync(path)).toBe(true);
+        const content = readFileSync(path, "utf-8");
+        expect(content.split("\n").filter(Boolean).length).toBe(1);
+        const entry = JSON.parse(content.trim());
+        expect(entry.op).toBe("remember");
+        expect(entry.id).toBe(1);
+        expect(entry.content).toBe("All timestamps are UTC.");
+        expect(entry.tier).toBe("core");
+        expect(entry.git_sha).toBe("abc123");
+        expect(typeof entry.ts).toBe("string");
+    });
+    it("appends multiple operations in order", () => {
+        const j = new MemoryJournal(projectRoot);
+        j.remember({
+            id: 1,
+            content: "First",
+            category: "decision",
+            confidence: 1.0,
+            tier: "archive",
+        });
+        j.promote(1, "core");
+        j.forget(1);
+        const path = join(projectRoot, ".sverklo", "memories.jsonl");
+        const lines = readFileSync(path, "utf-8").trim().split("\n");
+        expect(lines.length).toBe(3);
+        const ops = lines.map((l) => JSON.parse(l).op);
+        expect(ops).toEqual(["remember", "promote", "forget"]);
+    });
+    it("records tombstones for forget so the journal stays replayable", () => {
+        const j = new MemoryJournal(projectRoot);
+        j.remember({ id: 5, content: "x", category: "context", confidence: 1.0, tier: "archive" });
+        j.forget(5);
+        const path = join(projectRoot, ".sverklo", "memories.jsonl");
+        const content = readFileSync(path, "utf-8");
+        // Second line is the tombstone — forget must not rewrite/truncate.
+        expect(content).toContain('"op":"remember"');
+        expect(content).toContain('"op":"forget"');
+    });
+    it("records invalidate with atSha and replacedById", () => {
+        const j = new MemoryJournal(projectRoot);
+        j.invalidate(3, "def456", 7);
+        const path = join(projectRoot, ".sverklo", "memories.jsonl");
+        const entry = JSON.parse(readFileSync(path, "utf-8").trim());
+        expect(entry.op).toBe("invalidate");
+        expect(entry.id).toBe(3);
+        expect(entry.invalidated_at_sha).toBe("def456");
+        expect(entry.replaced_by_id).toBe(7);
+    });
+    it("is robust to optional fields being undefined", () => {
+        const j = new MemoryJournal(projectRoot);
+        j.remember({
+            id: 2,
+            content: "minimal",
+            category: "context",
+            confidence: 1.0,
+            tier: "archive",
+        });
+        const entry = JSON.parse(readFileSync(join(projectRoot, ".sverklo", "memories.jsonl"), "utf-8").trim());
+        expect(entry.tags).toBeNull();
+        expect(entry.git_sha).toBeNull();
+        expect(entry.related_files).toBeNull();
+    });
+    it("exposes the file path via filePath getter", () => {
+        const j = new MemoryJournal(projectRoot);
+        expect(j.filePath).toBe(join(projectRoot, ".sverklo", "memories.jsonl"));
+    });
+});
+//# sourceMappingURL=journal.test.js.map

package/dist/src/memory/journal.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.test.js","sourceRoot":"","sources":["../../../src/memory/journal.test.ts"],"names":[],"mappings":"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"}

package/dist/src/modes.d.ts

@@ -0,0 +1,16 @@
+export type SverkloMode = "embedded" | "shared" | "cloud";
+export interface ModeResolution {
+    mode: SverkloMode;
+    reason: string;
+}
+export declare function resolveMode(argv: string[], env?: NodeJS.ProcessEnv): ModeResolution;
+export declare class SverkloModeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Produce a clear, user-facing error for modes that are reserved but
+ * not yet implemented. Called from the CLI before attempting to start
+ * the server in an unsupported mode. We explicitly link the tracking
+ * issue so users have a concrete next step.
+ */
+export declare function notYetImplemented(mode: SverkloMode): string;

package/dist/src/modes.js

@@ -0,0 +1,104 @@
+// Runtime mode selection (issue #12).
+//
+// Sverklo is local-first by default and intentionally so. But a shared /
+// team / cloud story is a natural monetization path for later. To avoid
+// painting ourselves into a corner, we introduce the mode concept now
+// as a single seam the rest of the code can branch on.
+//
+// Three modes:
+//
+//   embedded (default)
+//     Current behavior. Indexes live in ~/.sverklo/<project>/, one
+//     process per project, nothing remote. Zero config. Everything
+//     works without opting in.
+//
+//   shared (reserved)
+//     A local daemon process holds indexes for multiple projects and
+//     multiple MCP server invocations connect to it. Useful for teams
+//     running multiple checkouts on the same laptop, or for the
+//     eventual "team cache" feature. NOT YET IMPLEMENTED.
+//
+//   cloud (reserved)
+//     A hosted sverklo endpoint running the same tool set against
+//     centrally-indexed repos. For the eventual Sverklo Team tier.
+//     NOT YET IMPLEMENTED.
+//
+// The mode resolver below is the single place where the CLI flag /
+// env var is parsed. If you need mode-specific behavior, call
+// getMode() and branch on the return value — don't re-parse.
+//
+// Hard-failure rule (inspired by Qdrant MCP's QDRANT_LOCAL_PATH vs
+// QDRANT_URL split): ambiguous config is an error, never a silent
+// fallback. If a user sets BOTH --mode cloud AND a local path, crash
+// with a clear message so they know to pick one.
+export function resolveMode(argv, env = process.env) {
+    // Precedence: CLI flag > env var > default.
+    let fromArgv = null;
+    for (const arg of argv) {
+        if (arg.startsWith("--mode=")) {
+            const val = arg.split("=")[1];
+            if (isSverkloMode(val))
+                fromArgv = val;
+        }
+    }
+    if (fromArgv) {
+        return { mode: fromArgv, reason: `--mode=${fromArgv}` };
+    }
+    const fromEnv = env.SVERKLO_MODE;
+    if (fromEnv && isSverkloMode(fromEnv)) {
+        return { mode: fromEnv, reason: `SVERKLO_MODE=${fromEnv}` };
+    }
+    if (fromEnv && !isSverkloMode(fromEnv)) {
+        throw new SverkloModeError(`Invalid SVERKLO_MODE=${fromEnv}. Must be one of: embedded, shared, cloud.`);
+    }
+    return { mode: "embedded", reason: "default" };
+}
+export class SverkloModeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SverkloModeError";
+    }
+}
+function isSverkloMode(value) {
+    return value === "embedded" || value === "shared" || value === "cloud";
+}
+/**
+ * Produce a clear, user-facing error for modes that are reserved but
+ * not yet implemented. Called from the CLI before attempting to start
+ * the server in an unsupported mode. We explicitly link the tracking
+ * issue so users have a concrete next step.
+ */
+export function notYetImplemented(mode) {
+    if (mode === "shared") {
+        return [
+            "Sverklo 'shared' mode is reserved for a future release and not yet implemented.",
+            "",
+            "Shared mode will let a local sverklo daemon hold indexes for multiple",
+            "projects and serve multiple MCP server invocations. Tracked in:",
+            "",
+            "  https://github.com/sverklo/sverklo/issues/12",
+            "",
+            "For now, run each project with the default 'embedded' mode:",
+            "",
+            "  sverklo /path/to/project",
+            "",
+        ].join("\n");
+    }
+    if (mode === "cloud") {
+        return [
+            "Sverklo 'cloud' mode is reserved for the eventual Sverklo Team tier",
+            "and not yet implemented.",
+            "",
+            "Cloud mode will talk to a hosted sverklo endpoint running the same",
+            "tool set against centrally-indexed repos. Tracked in:",
+            "",
+            "  https://github.com/sverklo/sverklo/issues/12",
+            "",
+            "For now, use 'embedded' mode (the default) — everything stays local",
+            "and private.",
+            "",
+        ].join("\n");
+    }
+    return "";
+}
+//# sourceMappingURL=modes.js.map

package/dist/src/modes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modes.js","sourceRoot":"","sources":["../../src/modes.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,yEAAyE;AACzE,wEAAwE;AACxE,sEAAsE;AACtE,uDAAuD;AACvD,EAAE;AACF,eAAe;AACf,EAAE;AACF,uBAAuB;AACvB,mEAAmE;AACnE,mEAAmE;AACnE,+BAA+B;AAC/B,EAAE;AACF,sBAAsB;AACtB,qEAAqE;AACrE,sEAAsE;AACtE,gEAAgE;AAChE,0DAA0D;AAC1D,EAAE;AACF,qBAAqB;AACrB,kEAAkE;AAClE,mEAAmE;AACnE,2BAA2B;AAC3B,EAAE;AACF,mEAAmE;AACnE,8DAA8D;AAC9D,6DAA6D;AAC7D,EAAE;AACF,mEAAmE;AACnE,kEAAkE;AAClE,qEAAqE;AACrE,iDAAiD;AASjD,MAAM,UAAU,WAAW,CACzB,IAAc,EACd,MAAyB,OAAO,CAAC,GAAG;IAEpC,4CAA4C;IAC5C,IAAI,QAAQ,GAAuB,IAAI,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9B,IAAI,aAAa,CAAC,GAAG,CAAC;gBAAE,QAAQ,GAAG,GAAG,CAAC;QACzC,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,QAAQ,EAAE,EAAE,CAAC;IAC1D,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,CAAC,YAAY,CAAC;IACjC,IAAI,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,OAAO,EAAE,EAAE,CAAC;IAC9D,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,gBAAgB,CACxB,wBAAwB,OAAO,4CAA4C,CAC5E,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,SAAS,aAAa,CAAC,KAAyB;IAC9C,OAAO,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,OAAO,CAAC;AACzE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAiB;IACjD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO;YACL,iFAAiF;YACjF,EAAE;YACF,uEAAuE;YACvE,iEAAiE;YACjE,EAAE;YACF,gDAAgD;YAChD,EAAE;YACF,6DAA6D;YAC7D,EAAE;YACF,4BAA4B;YAC5B,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IACD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,OAAO;YACL,qEAAqE;YACrE,0BAA0B;YAC1B,EAAE;YACF,oEAAoE;YACpE,uDAAuD;YACvD,EAAE;YACF,gDAAgD;YAChD,EAAE;YACF,qEAAqE;YACrE,cAAc;YACd,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/src/modes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/modes.test.js

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { resolveMode, notYetImplemented, SverkloModeError } from "./modes.js";
+describe("resolveMode", () => {
+    it("defaults to embedded when nothing is set", () => {
+        const result = resolveMode([], {});
+        expect(result.mode).toBe("embedded");
+        expect(result.reason).toBe("default");
+    });
+    it("reads --mode=embedded from argv", () => {
+        const result = resolveMode(["--mode=embedded"], {});
+        expect(result.mode).toBe("embedded");
+        expect(result.reason).toContain("embedded");
+    });
+    it("reads SVERKLO_MODE from env", () => {
+        const result = resolveMode([], { SVERKLO_MODE: "shared" });
+        expect(result.mode).toBe("shared");
+        expect(result.reason).toContain("shared");
+    });
+    it("argv takes precedence over env", () => {
+        const result = resolveMode(["--mode=cloud"], { SVERKLO_MODE: "embedded" });
+        expect(result.mode).toBe("cloud");
+    });
+    it("throws on invalid SVERKLO_MODE value", () => {
+        expect(() => resolveMode([], { SVERKLO_MODE: "lol" })).toThrow(SverkloModeError);
+    });
+    it("ignores invalid --mode= value and falls back to default", () => {
+        // We don't throw on invalid CLI arg because the user might have a
+        // typo and we want to fail loud only via env (which is harder to
+        // typo-correct). Behavior: invalid CLI flag is silently ignored,
+        // env takes over, default applies.
+        const result = resolveMode(["--mode=bogus"], {});
+        expect(result.mode).toBe("embedded");
+    });
+});
+describe("notYetImplemented", () => {
+    it("returns a non-empty message for shared", () => {
+        expect(notYetImplemented("shared")).toContain("not yet implemented");
+        expect(notYetImplemented("shared")).toContain("issues/12");
+    });
+    it("returns a non-empty message for cloud", () => {
+        expect(notYetImplemented("cloud")).toContain("not yet implemented");
+        expect(notYetImplemented("cloud")).toContain("issues/12");
+    });
+    it("returns empty string for embedded (which is implemented)", () => {
+        expect(notYetImplemented("embedded")).toBe("");
+    });
+});
+//# sourceMappingURL=modes.test.js.map

package/dist/src/modes.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modes.test.js","sourceRoot":"","sources":["../../src/modes.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9E,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACrC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,iBAAiB,CAAC,EAAE,EAAE,CAAC,CAAC;QACpD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACrC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACrC,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3D,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,CAAC;QAC3E,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,kEAAkE;QAClE,iEAAiE;QACjE,iEAAiE;QACjE,mCAAmC;QACnC,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC;QACjD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC;QACrE,MAAM,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC;QACpE,MAAM,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAClE,MAAM,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}