lmgrep 0.1.18 → 0.2.0

package/dist/presentation/mcp/LmgrepCore.js

@@ -0,0 +1,178 @@
+import { LmgrepFactory } from "../../application/LmgrepFactory.js";
+import { HealthMonitor, } from "../../application/operations/HealthMonitor.js";
+import { AiSdkChatModel } from "../../infrastructure/ai/AiSdkChatModel.js";
+import { SilentLogger } from "../../infrastructure/fs/Loggers.js";
+import { ProjectRegistry } from "../../infrastructure/fs/ProjectRegistry.js";
+import { StateDirectory } from "../../infrastructure/fs/StateDirectory.js";
+import { HitFormatter } from "./HitFormatter.js";
+import { IndexWatchController } from "./IndexWatchController.js";
+import { ToolDescriptions } from "./ToolDescriptions.js";
+/**
+ * The tool surface shared by the MCP server and the Pi extension.
+ *
+ * It owns the health story: an agent must be told, in the tool description
+ * itself, when search cannot work and what to do instead — a tool that silently
+ * returns nothing teaches the agent to stop using it.
+ */
+export class LmgrepCore {
+    lmgrep;
+    health;
+    watching;
+    registry;
+    askAvailable;
+    constructor(lmgrep, health, watching, registry, askAvailable) {
+        this.lmgrep = lmgrep;
+        this.health = health;
+        this.watching = watching;
+        this.registry = registry;
+        this.askAvailable = askAvailable;
+    }
+    static async open(options) {
+        const lmgrep = await new LmgrepFactory().open({
+            cwd: options.cwd,
+            database: options.database,
+            // stdout is the MCP transport; a stray log line corrupts it, and
+            // that includes configuration warnings.
+            logger: new SilentLogger(),
+            onWarning: () => { },
+        });
+        const registry = new ProjectRegistry(new StateDirectory());
+        const isIndexed = () => lmgrep.isIndexed();
+        const watching = new IndexWatchController(lmgrep, isIndexed);
+        const health = new HealthMonitor({
+            isIndexed,
+            inspect: async () => {
+                const info = await lmgrep.status();
+                return {
+                    fileCount: info.fileCount,
+                    embeddingOk: info.embeddingOk,
+                    searchOk: info.searchOk,
+                };
+            },
+            ensureWatching: () => watching.ensureStarted(),
+        }, lmgrep.config);
+        return new LmgrepCore(lmgrep, health, watching, registry, 
+        // `ask` needs a chat model on top of the embedder; only expose the
+        // tool when one is configured, so agents never see a tool they
+        // cannot use.
+        new AiSdkChatModel(lmgrep.config).isConfigured);
+    }
+    get cwd() {
+        return this.lmgrep.cwd;
+    }
+    get searchParams() {
+        return ToolDescriptions.SEARCH_PARAMS;
+    }
+    get listProjectsDescription() {
+        return ToolDescriptions.LIST_PROJECTS;
+    }
+    get askParam() {
+        return ToolDescriptions.ASK_PARAM;
+    }
+    get askDescription() {
+        return ToolDescriptions.ASK;
+    }
+    currentHealth() {
+        return this.health.current;
+    }
+    onHealthChange(listener) {
+        return this.health.onChange(listener);
+    }
+    start() {
+        this.health.start();
+    }
+    buildSearchDescription() {
+        const state = this.health.current;
+        if (state.healthy)
+            return ToolDescriptions.SEARCH_HEALTHY;
+        return ToolDescriptions.unavailable(state.reason, this.otherProjects().length > 0);
+    }
+    async executeSearch(args) {
+        return this.guarded(async () => {
+            const hits = await this.lmgrep.search(args.query, {
+                limit: args.limit ?? ToolDescriptions.SEARCH_PARAMS.limit.default,
+                filePrefix: args.filePrefix,
+                type: args.type,
+                language: args.language,
+                project: args.project,
+            });
+            // A successful search proves the embedder is reachable and the index
+            // is queryable — no need to keep pinging and keep it awake.
+            this.health.markHealthy();
+            return hits.isEmpty
+                ? { text: "No results found." }
+                : { text: HitFormatter.hits(hits.toArray()) };
+        });
+    }
+    async executeAsk(args) {
+        if (this.health.current.reason === "embedding_failed") {
+            return { text: ToolDescriptions.EMBEDDER_DOWN, isError: true };
+        }
+        try {
+            const result = await this.lmgrep.ask(args.question);
+            // A completed run proves the embedder and index are both healthy.
+            this.health.markHealthy();
+            return { text: HitFormatter.answer(result) };
+        }
+        catch (err) {
+            // research() degrades internally for provider and search errors; it
+            // only throws when no chat model is configured, which is worth
+            // surfacing verbatim.
+            return {
+                text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                isError: true,
+            };
+        }
+    }
+    async executeListProjects() {
+        const others = this.otherProjects();
+        return others.length === 0
+            ? { text: "No other indexed projects found." }
+            : { text: HitFormatter.projects(others) };
+    }
+    async dispose() {
+        this.health.dispose();
+        this.watching.release();
+        await this.lmgrep.close();
+    }
+    /** Shared failure handling: report, and arm recovery polling. */
+    async guarded(run) {
+        if (this.health.current.reason === "embedding_failed") {
+            return { text: ToolDescriptions.EMBEDDER_DOWN, isError: true };
+        }
+        try {
+            return await run();
+        }
+        catch (err) {
+            // The embedder may be down; poll so recovery updates the tool
+            // description without the user restarting anything.
+            this.health.markFailed();
+            return {
+                text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                isError: true,
+            };
+        }
+    }
+    /**
+     * Projects an agent can actually reach with the `project` parameter.
+     *
+     * Standalone indexes are excluded: they are addressed by name, and their
+     * recorded root is merely where they were built from, so offering one as a
+     * project path would resolve to a different database.
+     */
+    otherProjects() {
+        const current = this.lmgrep.location.path;
+        const seen = new Set();
+        const out = [];
+        for (const entry of this.registry.list()) {
+            if (entry.name || entry.databasePath === current)
+                continue;
+            if (seen.has(entry.root))
+                continue;
+            seen.add(entry.root);
+            out.push({ root: entry.root, remote: entry.remote });
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=LmgrepCore.js.map

package/dist/presentation/mcp/LmgrepCore.js.map

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

package/dist/presentation/mcp/McpServer.d.ts

@@ -0,0 +1,18 @@
+import type { LmgrepCore } from "./LmgrepCore.js";
+/**
+ * Exposes lmgrep over MCP.
+ *
+ * The search tool's description is re-published whenever health changes, so an
+ * agent's next turn sees an accurate account of whether search works — that
+ * live update is the reason this server holds a health monitor at all.
+ */
+export declare class LmgrepMcpServer {
+    private readonly core;
+    private readonly server;
+    constructor(core: LmgrepCore);
+    serve(): Promise<void>;
+    private registerSearch;
+    private registerListProjects;
+    private registerAsk;
+    private toContent;
+}

package/dist/presentation/mcp/McpServer.js

@@ -0,0 +1,63 @@
+import { McpServer as Server } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+/**
+ * Exposes lmgrep over MCP.
+ *
+ * The search tool's description is re-published whenever health changes, so an
+ * agent's next turn sees an accurate account of whether search works — that
+ * live update is the reason this server holds a health monitor at all.
+ */
+export class LmgrepMcpServer {
+    core;
+    server;
+    constructor(core) {
+        this.core = core;
+        this.server = new Server({ name: "lmgrep", version: "0.1.0" });
+    }
+    async serve() {
+        const search = this.registerSearch();
+        this.registerListProjects();
+        if (this.core.askAvailable)
+            this.registerAsk();
+        this.core.onHealthChange(() => {
+            search.update({ description: this.core.buildSearchDescription() });
+        });
+        this.core.start();
+        await this.server.connect(new StdioServerTransport());
+    }
+    registerSearch() {
+        const params = this.core.searchParams;
+        return this.server.tool("search", this.core.buildSearchDescription(), {
+            query: z.string().describe(params.query.description),
+            limit: z
+                .number()
+                .optional()
+                .default(params.limit.default)
+                .describe(params.limit.description),
+            filePrefix: z
+                .string()
+                .optional()
+                .describe(params.filePrefix.description),
+            type: z.array(z.string()).optional().describe(params.type.description),
+            language: z
+                .array(z.string())
+                .optional()
+                .describe(params.language.description),
+            project: z.string().optional().describe(params.project.description),
+        }, async (args) => this.toContent(await this.core.executeSearch(args)));
+    }
+    registerListProjects() {
+        return this.server.tool("list_other_indexed_projects", this.core.listProjectsDescription, {}, async () => this.toContent(await this.core.executeListProjects()));
+    }
+    registerAsk() {
+        return this.server.tool("ask", this.core.askDescription, { question: z.string().describe(this.core.askParam.description) }, async (args) => this.toContent(await this.core.executeAsk(args)));
+    }
+    toContent(result) {
+        return {
+            content: [{ type: "text", text: result.text }],
+            ...(result.isError ? { isError: true } : {}),
+        };
+    }
+}
+//# sourceMappingURL=McpServer.js.map

package/dist/presentation/mcp/McpServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpServer.js","sourceRoot":"","sources":["../../../src/presentation/mcp/McpServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,MAAM,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAGE;IAFZ,MAAM,CAAS;IAEhC,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;QAC5C,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,KAAK;QACV,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QACrC,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC5B,IAAI,IAAI,CAAC,IAAI,CAAC,YAAY;YAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QAE/C,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE;YAC7B,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAElB,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACvD,CAAC;IAEO,cAAc;QACrB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CACtB,QAAQ,EACR,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAClC;YACC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC;YACpD,KAAK,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;iBAC7B,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC;YACpC,UAAU,EAAE,CAAC;iBACX,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,WAAW,CAAC;YACzC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;YACtE,QAAQ,EAAE,CAAC;iBACT,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;iBACjB,QAAQ,EAAE;iBACV,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC;YACvC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC;SACnE,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CACnE,CAAC;IACH,CAAC;IAEO,oBAAoB;QAC3B,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CACtB,6BAA6B,EAC7B,IAAI,CAAC,IAAI,CAAC,uBAAuB,EACjC,EAAE,EACF,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC,CACjE,CAAC;IACH,CAAC;IAEO,WAAW;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CACtB,KAAK,EACL,IAAI,CAAC,IAAI,CAAC,cAAc,EACxB,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,EACjE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAChE,CAAC;IACH,CAAC;IAEO,SAAS,CAAC,MAA2C;QAC5D,OAAO;YACN,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;YACvD,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5C,CAAC;IACH,CAAC;CACD"}

package/dist/presentation/mcp/ToolDescriptions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The text an MCP client sees for each tool.
+ *
+ * These are prompts, not documentation: they are what decides whether an agent
+ * reaches for lmgrep or falls back to grep, and they were tuned by watching
+ * agents choose. Treat edits here as behaviour changes.
+ */
+export declare class ToolDescriptions {
+    static readonly SEARCH_PARAMS: {
+        query: {
+            description: string;
+        };
+        limit: {
+            description: string;
+            default: number;
+        };
+        filePrefix: {
+            description: string;
+        };
+        type: {
+            description: string;
+        };
+        language: {
+            description: string;
+        };
+        project: {
+            description: string;
+        };
+    };
+    static readonly LIST_PROJECTS: string;
+    static readonly ASK_PARAM: {
+        description: string;
+    };
+    static readonly ASK: string;
+    /** Shown while search is working. */
+    static readonly SEARCH_HEALTHY: string;
+    /** Shown when search is unavailable, explaining why and what still works. */
+    static unavailable(reason: "not_indexed" | "embedding_failed" | "search_empty" | "ok", otherProjectsAvailable: boolean): string;
+    static readonly EMBEDDER_DOWN = "lmgrep is unavailable: the embedding provider is unreachable. Ask the user to check their lmgrep configuration (`lmgrep status`) before retrying.";
+}

package/dist/presentation/mcp/ToolDescriptions.js

@@ -0,0 +1,85 @@
+/**
+ * The text an MCP client sees for each tool.
+ *
+ * These are prompts, not documentation: they are what decides whether an agent
+ * reaches for lmgrep or falls back to grep, and they were tuned by watching
+ * agents choose. Treat edits here as behaviour changes.
+ */
+export class ToolDescriptions {
+    static SEARCH_PARAMS = {
+        query: {
+            description: 'Natural-language description of what you\'re looking for — phrase it as a question or intent, not keywords. Good: "how are webhooks authenticated", "where is user deletion handled", "what happens when a record is created". Bad: "webhook auth", "deleteUser", "createRecord".',
+        },
+        limit: {
+            description: "Maximum number of results",
+            default: 5,
+        },
+        filePrefix: {
+            description: "Restrict to files under this path (e.g. 'src/lib')",
+        },
+        type: {
+            description: "AST node types to filter by (e.g. ['function_declaration', 'class_declaration'])",
+        },
+        language: {
+            description: "File extensions to filter by (e.g. ['.ts', '.py'])",
+        },
+        project: {
+            description: "Search a different indexed project by its root path instead of the current one",
+        },
+    };
+    static LIST_PROJECTS = "List all indexed projects other than the current one. " +
+        "Use this to discover what projects are available for cross-project search " +
+        "via the `project` parameter on the search tool.";
+    static ASK_PARAM = {
+        description: 'The question to answer, in natural language — phrase it as a real question about the code. Good: "how does the file watcher trigger reindexing", "where are webhooks authenticated and what token format", "what happens when a user is deleted".',
+    };
+    static ASK = [
+        "**Ask a question about this codebase and get back a synthesized, cited answer** — instead of raw search results you have to read yourself. A local model runs a short research loop (searches the index, reads the matching code, writes a grounded answer), so you spend one tool call and a paragraph instead of several searches and pages of chunks.",
+        "",
+        '**Use `ask` when you want a question *answered*:** "how does X work", "where is Y handled and what does it do", "what happens when Z", "how do these pieces fit together". The retrieval loop runs on a local model — cheap on your context.',
+        "",
+        "**Use `search` instead when you want the raw code** to read yourself (exact snippets, or to browse many hits). `ask` complements `search`; it does not replace it.",
+        "",
+        "**Every claim is cited** as `[n]` → `file:line`, listed under the answer, so you can verify or open the sources. If an answer looks off or thin, fall back to `search` for the raw chunks.",
+        "",
+        "**Tradeoff:** `ask` runs a local model, so it's slower than `search` — roughly ~10s to a couple of minutes depending on the question and hardware — but it does the searching and reading for you.",
+    ].join("\n");
+    /** Shown while search is working. */
+    static SEARCH_HEALTHY = [
+        "**lmgrep — primary search tool for this codebase.** Semantic code search powered by a local embedding model; lmgrep understands intent, not string patterns. Prefer lmgrep over Grep/Glob/find/ripgrep for almost all exploration and lookup tasks.",
+        "",
+        '**Use lmgrep for:** finding where something is handled, how something works, locating relevant code, discovering related files, understanding unfamiliar code, tracing side effects, finding usage patterns, answering "where is X?" or "how does Y work?". One good lmgrep query is usually enough to understand how to proceed.',
+        "",
+        "**Query lmgrep as natural questions or intent descriptions**, not keyword dumps:",
+        '- "how are webhooks authenticated" → finds middleware, token validation, auth checks',
+        '- "where is user deletion handled" → finds the handler and related cleanup logic',
+        '- "what happens when a record is created" → finds controllers, event emitters, side effects',
+        '- "config loading and validation"',
+        '- "how to run the playwright tests" → finds config, scripts, prerequisites',
+        "",
+        "**lmgrep results include** file paths, line numbers, AST node types, and surrounding context (scope, leading comments, role) — often enough to act on directly without re-reading the file. Trust lmgrep results; don't follow up with Glob/Read on files already surfaced by lmgrep unless you genuinely need content that wasn't returned.",
+        "",
+        "**Fall back to Grep only** when you need exact string or regex matches (specific identifiers, literal constants, error messages, TODO markers). Don't use Grep/Glob/find for conceptual or intent-based search — lmgrep will do better.",
+    ].join("\n");
+    /** Shown when search is unavailable, explaining why and what still works. */
+    static unavailable(reason, otherProjectsAvailable) {
+        const suffix = otherProjectsAvailable
+            ? " You can still search other indexed projects via the `project` parameter — call `list_other_indexed_projects` to see what's available."
+            : "";
+        switch (reason) {
+            case "not_indexed":
+                return ("This project is not indexed. Semantic search is not available for the current directory." +
+                    suffix);
+            case "embedding_failed":
+                return ("The embedding provider is unreachable. Semantic search is temporarily unavailable for the current directory." +
+                    suffix);
+            case "search_empty":
+                return ("The index for the current branch appears empty or stale — a smoke query returned no results. Re-run `lmgrep index` to rebuild." +
+                    suffix);
+            default:
+                return `Semantic search is unavailable.${suffix}`;
+        }
+    }
+    static EMBEDDER_DOWN = "lmgrep is unavailable: the embedding provider is unreachable. Ask the user to check their lmgrep configuration (`lmgrep status`) before retrying.";
+}
+//# sourceMappingURL=ToolDescriptions.js.map

package/dist/presentation/mcp/ToolDescriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolDescriptions.js","sourceRoot":"","sources":["../../../src/presentation/mcp/ToolDescriptions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IAC5B,MAAM,CAAU,aAAa,GAAG;QAC/B,KAAK,EAAE;YACN,WAAW,EACV,mRAAmR;SACpR;QACD,KAAK,EAAE;YACN,WAAW,EAAE,2BAA2B;YACxC,OAAO,EAAE,CAAC;SACV;QACD,UAAU,EAAE;YACX,WAAW,EAAE,oDAAoD;SACjE;QACD,IAAI,EAAE;YACL,WAAW,EACV,kFAAkF;SACnF;QACD,QAAQ,EAAE;YACT,WAAW,EAAE,oDAAoD;SACjE;QACD,OAAO,EAAE;YACR,WAAW,EACV,gFAAgF;SACjF;KACD,CAAC;IAEF,MAAM,CAAU,aAAa,GAC5B,wDAAwD;QACxD,4EAA4E;QAC5E,iDAAiD,CAAC;IAEnD,MAAM,CAAU,SAAS,GAAG;QAC3B,WAAW,EACV,mPAAmP;KACpP,CAAC;IAEF,MAAM,CAAU,GAAG,GAAG;QACrB,0VAA0V;QAC1V,EAAE;QACF,8OAA8O;QAC9O,EAAE;QACF,oKAAoK;QACpK,EAAE;QACF,4LAA4L;QAC5L,EAAE;QACF,oMAAoM;KACpM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,qCAAqC;IACrC,MAAM,CAAU,cAAc,GAAG;QAChC,qPAAqP;QACrP,EAAE;QACF,mUAAmU;QACnU,EAAE;QACF,kFAAkF;QAClF,sFAAsF;QACtF,kFAAkF;QAClF,6FAA6F;QAC7F,mCAAmC;QACnC,4EAA4E;QAC5E,EAAE;QACF,8UAA8U;QAC9U,EAAE;QACF,yOAAyO;KACzO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,6EAA6E;IAC7E,MAAM,CAAC,WAAW,CACjB,MAAkE,EAClE,sBAA+B;QAE/B,MAAM,MAAM,GAAG,sBAAsB;YACpC,CAAC,CAAC,wIAAwI;YAC1I,CAAC,CAAC,EAAE,CAAC;QAEN,QAAQ,MAAM,EAAE,CAAC;YAChB,KAAK,aAAa;gBACjB,OAAO,CACN,0FAA0F;oBAC1F,MAAM,CACN,CAAC;YACH,KAAK,kBAAkB;gBACtB,OAAO,CACN,8GAA8G;oBAC9G,MAAM,CACN,CAAC;YACH,KAAK,cAAc;gBAClB,OAAO,CACN,gIAAgI;oBAChI,MAAM,CACN,CAAC;YACH;gBACC,OAAO,kCAAkC,MAAM,EAAE,CAAC;QACpD,CAAC;IACF,CAAC;IAED,MAAM,CAAU,aAAa,GAC5B,mJAAmJ,CAAC"}

package/package.json

@@ -1,91 +1,86 @@
 {
-  "name": "lmgrep",
-  "version": "0.1.18",
-  "description": "Semantic code search with any AI embedding provider",
-  "type": "module",
-  "bin": {
-    "lmgrep": "./dist/cli.js",
-    "lmgrep-mcp": "./dist/mcp.js"
-  },
-  "pi": {
-    "extensions": [
-      "./pi-extension/index.ts"
-    ]
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node dist/cli.js",
-    "check": "biome check --write .",
-    "lint": "biome lint ."
-  },
-  "keywords": [
-    "semantic-search",
-    "code-search",
-    "embeddings",
-    "tree-sitter",
-    "ai"
-  ],
-  "author": "",
-  "license": "GPL-3.0-only",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Aetherall/lmgrep.git"
-  },
-  "files": [
-    "dist",
-    "completions",
-    "README.md"
-  ],
-  "packageManager": "pnpm@10.28.0",
-  "dependencies": {
-    "@lancedb/lancedb": "^0.27.2",
-    "@lumis-sh/wasm-bash": "^0.26.1",
-    "@lumis-sh/wasm-c": "^0.26.1",
-    "@lumis-sh/wasm-cpp": "^0.26.0",
-    "@lumis-sh/wasm-csharp": "^0.26.1",
-    "@lumis-sh/wasm-css": "^0.26.2",
-    "@lumis-sh/wasm-go": "^0.26.1",
-    "@lumis-sh/wasm-html": "^0.26.1",
-    "@lumis-sh/wasm-java": "^0.26.1",
-    "@lumis-sh/wasm-javascript": "^0.26.2",
-    "@lumis-sh/wasm-json": "^0.26.2",
-    "@lumis-sh/wasm-kotlin": "^0.26.3",
-    "@lumis-sh/wasm-lua": "^0.26.1",
-    "@lumis-sh/wasm-markdown": "^0.26.1",
-    "@lumis-sh/wasm-nix": "^0.26.0",
-    "@lumis-sh/wasm-php": "^0.26.2",
-    "@lumis-sh/wasm-python": "^0.26.1",
-    "@lumis-sh/wasm-ruby": "^0.26.1",
-    "@lumis-sh/wasm-rust": "^0.26.3",
-    "@lumis-sh/wasm-scala": "^0.26.1",
-    "@lumis-sh/wasm-swift": "^0.26.1",
-    "@lumis-sh/wasm-toml": "^0.26.0",
-    "@lumis-sh/wasm-tsx": "^0.26.1",
-    "@lumis-sh/wasm-typescript": "^0.26.1",
-    "@lumis-sh/wasm-vue": "^0.26.0",
-    "@lumis-sh/wasm-yaml": "^0.26.0",
-    "@lumis-sh/wasm-zig": "^0.26.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "ai": "^6.0.149",
-    "apache-arrow": "^21.1.0",
-    "cli-progress": "^3.12.0",
-    "commander": "^14.0.3",
-    "glob": "^13.0.6",
-    "ignore": "^7.0.5",
-    "stemmer": "^2.0.1",
-    "web-tree-sitter": "^0.26.9",
-    "yaml": "^2.8.3",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@ai-sdk/openai": "^3.0.51",
-    "@biomejs/biome": "^2.4.10",
-    "@types/cli-progress": "^3.11.6",
-    "@types/node": "^25.5.2",
-    "typescript": "^6.0.2"
-  },
-  "optionalDependencies": {
-    "hyperswarm": "^4.17.0"
-  }
+	"name": "lmgrep",
+	"version": "0.2.0",
+	"description": "Semantic code search with any AI embedding provider",
+	"type": "module",
+	"bin": {
+		"lmgrep": "./dist/cli.js",
+		"lmgrep-mcp": "./dist/mcp.js"
+	},
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --watch",
+		"start": "node dist/cli.js",
+		"check": "biome check --write .",
+		"lint": "biome lint ."
+	},
+	"keywords": [
+		"semantic-search",
+		"code-search",
+		"embeddings",
+		"tree-sitter",
+		"ai"
+	],
+	"author": "",
+	"license": "GPL-3.0-only",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Aetherall/lmgrep.git"
+	},
+	"files": [
+		"dist",
+		"completions",
+		"README.md"
+	],
+	"packageManager": "pnpm@10.28.0",
+	"dependencies": {
+		"@lancedb/lancedb": "^0.27.2",
+		"@lumis-sh/wasm-bash": "^0.26.1",
+		"@lumis-sh/wasm-c": "^0.26.1",
+		"@lumis-sh/wasm-cpp": "^0.26.0",
+		"@lumis-sh/wasm-csharp": "^0.26.1",
+		"@lumis-sh/wasm-css": "^0.26.2",
+		"@lumis-sh/wasm-go": "^0.26.1",
+		"@lumis-sh/wasm-html": "^0.26.1",
+		"@lumis-sh/wasm-java": "^0.26.1",
+		"@lumis-sh/wasm-javascript": "^0.26.2",
+		"@lumis-sh/wasm-json": "^0.26.2",
+		"@lumis-sh/wasm-kotlin": "^0.26.3",
+		"@lumis-sh/wasm-lua": "^0.26.1",
+		"@lumis-sh/wasm-markdown": "^0.26.1",
+		"@lumis-sh/wasm-nix": "^0.26.0",
+		"@lumis-sh/wasm-php": "^0.26.2",
+		"@lumis-sh/wasm-python": "^0.26.1",
+		"@lumis-sh/wasm-ruby": "^0.26.1",
+		"@lumis-sh/wasm-rust": "^0.26.3",
+		"@lumis-sh/wasm-scala": "^0.26.1",
+		"@lumis-sh/wasm-swift": "^0.26.1",
+		"@lumis-sh/wasm-toml": "^0.26.0",
+		"@lumis-sh/wasm-tsx": "^0.26.1",
+		"@lumis-sh/wasm-typescript": "^0.26.1",
+		"@lumis-sh/wasm-vue": "^0.26.0",
+		"@lumis-sh/wasm-yaml": "^0.26.0",
+		"@lumis-sh/wasm-zig": "^0.26.0",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"ai": "^6.0.149",
+		"apache-arrow": "^21.1.0",
+		"cli-progress": "^3.12.0",
+		"commander": "^14.0.3",
+		"glob": "^13.0.6",
+		"ignore": "^7.0.5",
+		"stemmer": "^2.0.1",
+		"web-tree-sitter": "^0.26.9",
+		"yaml": "^2.8.3",
+		"zod": "^4.3.6"
+	},
+	"devDependencies": {
+		"@ai-sdk/openai": "^3.0.51",
+		"@biomejs/biome": "^2.4.10",
+		"@types/cli-progress": "^3.11.6",
+		"@types/node": "^25.5.2",
+		"typescript": "^6.0.2"
+	},
+	"optionalDependencies": {
+		"hyperswarm": "^4.17.0"
+	}
 }

package/dist/lib/build.d.ts

@@ -1,21 +0,0 @@
-import { type Embedder } from "./embedder.js";
-import { type Store } from "./store.js";
-import type { Chunker, Logger, LmgrepConfig, BuildOptions } from "./types.js";
-export declare function build(cwd: string, store: Store, config: LmgrepConfig, embedder: Embedder, chunker: Chunker, opts?: BuildOptions, logger?: Logger): Promise<{
-    succeeded: number;
-    failed: number;
-}>;
-/**
- * Extract vocab terms from newly indexed chunks, embed those not already
- * present in the vocab table, and append the new entries. Keeps the vocab
- * table in sync with the chunk content incrementally.
- */
-export declare function buildVocab(store: Store, chunks: Iterable<{
-    name: string;
-    content: string;
-}>, embedder: Embedder, log: (msg: string) => void, opts?: {
-    minDf?: number;
-    embedBatch?: number;
-}): Promise<{
-    added: number;
-}>;