grepmax 0.26.44 → 0.26.45

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "grepmax",
       "source": "./plugins/grepmax",
       "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
-      "version": "0.26.44",
+      "version": "0.26.45",
       "author": {
         "name": "Robert Owens",
         "email": "robowens@me.com"

package/README.md

@@ -130,6 +130,8 @@ MCP is local-only: the client spawns it and communicates through stdin/stdout pi
 
 `gmax mcp` starts a stdio-based MCP server for clients that support MCP but can't run shell commands (Cursor, Windsurf, custom agents). Search-backed tools use the singleton daemon when available, avoiding a separate embedding worker per MCP session, and use an in-process worker for supported offline/secondary-store access. An unsupported daemon command requires `gmax watch restart`.
 
+`semantic_search`, `trace_calls`, `dead`, and `index_status` also advertise output schemas and return `structuredContent` with `schemaVersion: 1`, alongside the existing text. Search matches follow the same scope and display filters and include paths, one-based start/end lines, symbols, scores (null when unavailable), and warnings. Trace results preserve caller ancestry and edge confidence; unresolved callees have no location, and omitted callee/importer counts are explicit. Graph conclusions carry `approximate: true`. Index health includes embedding identity, watcher/reconciliation state, and the last compaction result; unavailable health is null or unobserved. These four tools advertise read-only, non-destructive, closed-world annotations. Other tools retain their current contracts.
+
 | Tool | Description |
 | --- | --- |
 | `semantic_search` | Search by meaning. Pointer mode matches CLI `--agent` output; `detail=code/full` returns snippets. |

package/dist/commands/mcp.js

@@ -85,6 +85,7 @@ const index_config_1 = require("../lib/index/index-config");
 const syncer_1 = require("../lib/index/syncer");
 const agent_search_formatter_1 = require("../lib/output/agent-search-formatter");
 const index_state_footer_1 = require("../lib/output/index-state-footer");
+const mcp_results_1 = require("../lib/output/mcp-results");
 const searcher_1 = require("../lib/search/searcher");
 const annotator_1 = require("../lib/skeleton/annotator");
 const skeletonizer_1 = require("../lib/skeleton/skeletonizer");
@@ -123,8 +124,8 @@ function toStringArray(val) {
     }
     return [];
 }
-function ok(text) {
-    return { content: [{ type: "text", text }] };
+function ok(text, structuredContent) {
+    return Object.assign({ content: [{ type: "text", text }] }, (structuredContent ? { structuredContent } : {}));
 }
 function err(text) {
     return { content: [{ type: "text", text }], isError: true };
@@ -256,13 +257,13 @@ function searchResultPath(r) {
 }
 function searchResultStartLine(r) {
     var _a;
-    var _b, _c;
-    return Number((_c = (_b = r === null || r === void 0 ? void 0 : r.start_line) !== null && _b !== void 0 ? _b : (_a = r === null || r === void 0 ? void 0 : r.generated_metadata) === null || _a === void 0 ? void 0 : _a.start_line) !== null && _c !== void 0 ? _c : 0);
+    var _b, _c, _d;
+    return Number((_d = (_c = (_b = r === null || r === void 0 ? void 0 : r.startLine) !== null && _b !== void 0 ? _b : r === null || r === void 0 ? void 0 : r.start_line) !== null && _c !== void 0 ? _c : (_a = r === null || r === void 0 ? void 0 : r.generated_metadata) === null || _a === void 0 ? void 0 : _a.start_line) !== null && _d !== void 0 ? _d : 0);
 }
 function searchResultEndLine(r, fallbackStart = 0) {
     var _a;
-    var _b, _c;
-    return Number((_c = (_b = r === null || r === void 0 ? void 0 : r.end_line) !== null && _b !== void 0 ? _b : (_a = r === null || r === void 0 ? void 0 : r.generated_metadata) === null || _a === void 0 ? void 0 : _a.end_line) !== null && _c !== void 0 ? _c : fallbackStart);
+    var _b, _c, _d;
+    return Number((_d = (_c = (_b = r === null || r === void 0 ? void 0 : r.endLine) !== null && _b !== void 0 ? _b : r === null || r === void 0 ? void 0 : r.end_line) !== null && _c !== void 0 ? _c : (_a = r === null || r === void 0 ? void 0 : r.generated_metadata) === null || _a === void 0 ? void 0 : _a.end_line) !== null && _d !== void 0 ? _d : fallbackStart);
 }
 function filterMcpSearchResults(data, options = {}) {
     var _a, _b;
@@ -772,6 +773,26 @@ exports.mcp = new commander_1.Command("mcp")
                     return (candidate.length > 0 &&
                         allowedRoots.some((root) => (0, path_containment_1.isPathWithin)(root, candidate)));
                 });
+                const structuredSearch = (matches) => { var _a; return ({
+                    schemaVersion: 1,
+                    query,
+                    roots: allowedRoots,
+                    warnings: ((_a = result.warnings) !== null && _a !== void 0 ? _a : []).filter(Boolean),
+                    matches: matches.map((r) => {
+                        var _a;
+                        const startLine = searchResultStartLine(r);
+                        return {
+                            path: chunkAbsPath(r),
+                            startLine: startLine + 1,
+                            endLine: searchResultEndLine(r, startLine) + 1,
+                            symbols: chunkSymbols(r),
+                            role: String((_a = r.role) !== null && _a !== void 0 ? _a : "IMPLEMENTATION"),
+                            score: typeof r.score === "number" && Number.isFinite(r.score)
+                                ? r.score
+                                : null,
+                        };
+                    }),
+                }); };
                 // Prepend any searcher warnings to whatever body we return.
                 const prefixNotes = (body) => {
                     var _a;
@@ -779,7 +800,7 @@ exports.mcp = new commander_1.Command("mcp")
                     return notes.length ? `${notes.join("\n")}\n\n${body}` : body;
                 };
                 if (!result.data || result.data.length === 0) {
-                    return ok(prefixNotes("No matches found. Try broadening your query, using fewer keywords, or check `gmax status` to verify the project is indexed."));
+                    return ok(prefixNotes("No matches found. Try broadening your query, using fewer keywords, or check `gmax status` to verify the project is indexed."), structuredSearch([]));
                 }
                 const minScore = typeof args.min_score === "number" ? args.min_score : 0;
                 const maxPerFile = typeof args.max_per_file === "number" ? args.max_per_file : 0;
@@ -809,21 +830,25 @@ exports.mcp = new commander_1.Command("mcp")
                         getImportsForFile,
                         query,
                     });
-                    return ok(prefixNotes(output));
+                    return ok(prefixNotes(output), structuredSearch(filterMcpSearchResults(result.data, {
+                        minScore,
+                        maxPerFile,
+                        namePattern,
+                    })));
                 }
                 let results = result.data.map((r) => {
-                    var _a, _b, _c;
-                    var _d, _e, _f, _g, _h, _j, _k, _l, _m;
-                    const absPath = (_e = (_d = r.path) !== null && _d !== void 0 ? _d : (_a = r.metadata) === null || _a === void 0 ? void 0 : _a.path) !== null && _e !== void 0 ? _e : "";
+                    var _a;
+                    var _b, _c, _d, _e, _f;
+                    const absPath = (_c = (_b = r.path) !== null && _b !== void 0 ? _b : (_a = r.metadata) === null || _a === void 0 ? void 0 : _a.path) !== null && _c !== void 0 ? _c : "";
                     const relPath = absPath.startsWith(displayRoot)
                         ? absPath.slice(displayRoot.length + 1)
                         : absPath;
-                    const startLine = (_g = (_f = r.startLine) !== null && _f !== void 0 ? _f : (_b = r.generated_metadata) === null || _b === void 0 ? void 0 : _b.start_line) !== null && _g !== void 0 ? _g : 0;
-                    const endLine = (_j = (_h = r.endLine) !== null && _h !== void 0 ? _h : (_c = r.generated_metadata) === null || _c === void 0 ? void 0 : _c.end_line) !== null && _j !== void 0 ? _j : 0;
-                    const defs = toStringArray((_k = r.definedSymbols) !== null && _k !== void 0 ? _k : r.defined_symbols);
-                    const refs = toStringArray((_l = r.referenced_symbols) !== null && _l !== void 0 ? _l : r.referencedSymbols);
+                    const startLine = searchResultStartLine(r);
+                    const endLine = searchResultEndLine(r, startLine);
+                    const defs = toStringArray((_d = r.definedSymbols) !== null && _d !== void 0 ? _d : r.defined_symbols);
+                    const refs = toStringArray((_e = r.referenced_symbols) !== null && _e !== void 0 ? _e : r.referencedSymbols);
                     const symbol = defs[0] || "(anonymous)";
-                    const role = ((_m = r.role) !== null && _m !== void 0 ? _m : "IMPL").slice(0, 4).toUpperCase();
+                    const role = ((_f = r.role) !== null && _f !== void 0 ? _f : "IMPL").slice(0, 4).toUpperCase();
                     const exported = r.is_exported ? "exported " : "";
                     const complexity = typeof r.complexity === "number" && r.complexity > 0
                         ? ` C:${Math.round(r.complexity)}`
@@ -855,7 +880,7 @@ exports.mcp = new commander_1.Command("mcp")
                                             .map((l, i) => `${ctxStart + i + 1}│${l}`)
                                             .join("\n");
                             }
-                            catch (_o) {
+                            catch (_g) {
                                 // Fall through to chunk content
                             }
                         }
@@ -885,6 +910,7 @@ exports.mcp = new commander_1.Command("mcp")
                         }
                     }
                     return {
+                        row: r,
                         absPath,
                         text,
                         score: typeof r.score === "number" ? r.score : 0,
@@ -957,7 +983,7 @@ exports.mcp = new commander_1.Command("mcp")
                         // Trace failed — return search results without trace
                     }
                 }
-                return ok(prefixNotes(output));
+                return ok(prefixNotes(output), structuredSearch(results.map((r) => r.row)));
             }
             catch (e) {
                 return toolError("Search failed", e);
@@ -1105,8 +1131,9 @@ exports.mcp = new commander_1.Command("mcp")
                     render: (resp) => resp.graph,
                     inProcess: () => localStore((deps) => (0, graph_handler_1.runGraphTrace)(deps.vectorDb, { symbol, hops: depth, scope })),
                 });
+                const structured = (0, mcp_results_1.traceResult)(symbol, root, graph);
                 if (!graph.center) {
-                    return ok(`Symbol '${symbol}' not found in the index. Check \`gmax status\` to see which projects are indexed, or try \`gmax search ${symbol}\` to find similar symbols.`);
+                    return ok(`Symbol '${symbol}' not found in the index. Check \`gmax status\` to see which projects are indexed, or try \`gmax search ${symbol}\` to find similar symbols.`, structured);
                 }
                 const lines = [];
                 // Center
@@ -1165,7 +1192,7 @@ exports.mcp = new commander_1.Command("mcp")
                 else {
                     lines.push("Calls: none");
                 }
-                return ok(lines.join("\n"));
+                return ok(lines.join("\n"), structured);
             }
             catch (e) {
                 return toolError("Trace failed", e);
@@ -1406,16 +1433,17 @@ exports.mcp = new commander_1.Command("mcp")
                     render: (resp) => resp.dead,
                     inProcess: () => localStore((deps) => (0, graph_handler_1.runGraphDead)(deps.vectorDb, { symbol, scope })),
                 });
+                const structured = (0, mcp_results_1.deadResult)(symbol, root, facts);
                 if (!facts.found) {
-                    return ok(`Symbol '${symbol}' not found in the index. Check \`gmax status\` to see which projects are indexed, or try \`gmax search ${symbol}\` to find similar symbols.`);
+                    return ok(`Symbol '${symbol}' not found in the index. Check \`gmax status\` to see which projects are indexed, or try \`gmax search ${symbol}\` to find similar symbols.`, structured);
                 }
                 const rel = (p) => p.startsWith(root) ? p.slice(root.length + 1) : p;
                 const defLoc = `${rel(facts.defPath)}:${facts.defLine + 1}`;
                 if (facts.callerCount === 0) {
                     if (facts.isExported) {
-                        return ok(`PUBLIC EXPORT  ${defLoc} defines ${symbol} — no internal callers found; check external usage`);
+                        return ok(`PUBLIC EXPORT  ${defLoc} defines ${symbol} — no internal callers found; check external usage`, structured);
                     }
-                    return ok(`DEAD  ${defLoc} defines ${symbol}`);
+                    return ok(`DEAD  ${defLoc} defines ${symbol}`, structured);
                 }
                 const top = facts.topCallers;
                 const lines = [
@@ -1424,7 +1452,7 @@ exports.mcp = new commander_1.Command("mcp")
                 for (const c of top) {
                     lines.push(`  ${rel(c.file)}:${c.line + 1}`);
                 }
-                return ok(lines.join("\n"));
+                return ok(lines.join("\n"), structured);
             }
             catch (e) {
                 return toolError("Dead check failed", e);
@@ -1782,7 +1810,7 @@ exports.mcp = new commander_1.Command("mcp")
     }
     function handleIndexStatus() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+            var _a, _b, _c, _d, _e;
             try {
                 const globalConfig = storeConfig();
                 const projects = storeProjects();
@@ -1834,7 +1862,36 @@ exports.mcp = new commander_1.Command("mcp")
                     (0, compaction_result_1.formatCompactionStatus)(daemonStatus.compaction),
                     `Projects: ${projects.length} indexed (call list_projects for names + per-project chunk counts)`,
                 ].filter(Boolean);
-                return ok(lines.join("\n"));
+                const compaction = mcp_results_1.compactionSchema.safeParse(daemonStatus.compaction);
+                return ok(lines.join("\n"), {
+                    schemaVersion: 1,
+                    root: currentRoot(),
+                    store: storeDir(),
+                    secondary: secondary(),
+                    chunks,
+                    files,
+                    projects: projects.length,
+                    embedding: {
+                        state: identity.state,
+                        configured: {
+                            tier: identity.configured.tier,
+                            vectorDim: identity.configured.vectorDim,
+                            fingerprint: identity.configured.fingerprint,
+                        },
+                        built: identity.built
+                            ? {
+                                tier: identity.built.tier,
+                                vectorDim: identity.built.vectorDim,
+                                fingerprint: identity.built.fingerprint,
+                            }
+                            : null,
+                    },
+                    watcher: {
+                        status: (_d = (_c = daemonProject === null || daemonProject === void 0 ? void 0 : daemonProject.status) !== null && _c !== void 0 ? _c : watcher === null || watcher === void 0 ? void 0 : watcher.status) !== null && _d !== void 0 ? _d : (secondary() || !daemonStatus.ok ? "unobserved" : "not_running"),
+                        indexState: (_e = daemonProject === null || daemonProject === void 0 ? void 0 : daemonProject.indexState) !== null && _e !== void 0 ? _e : null,
+                    },
+                    compaction: compaction.success ? compaction.data : null,
+                });
             }
             catch (e) {
                 return toolError("Status check failed", e);
@@ -2620,7 +2677,16 @@ exports.mcp = new commander_1.Command("mcp")
     // shapes give us free input validation (the SDK rejects calls that violate
     // the schema before the handler runs); handlers stay defensively coded.
     function tool(name, config, handler) {
-        server.registerTool(name, Object.assign(Object.assign({}, config), { inputSchema: Object.assign({ root: zod_1.z.string().optional() }, config.inputSchema) }), (rawArgs) => __awaiter(this, void 0, void 0, function* () {
+        server.registerTool(name, Object.assign(Object.assign(Object.assign({}, config), (mcp_results_1.MCP_READ_OUTPUT_SCHEMAS[name]
+            ? {
+                outputSchema: mcp_results_1.MCP_READ_OUTPUT_SCHEMAS[name],
+                annotations: {
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    openWorldHint: false,
+                },
+            }
+            : {})), { inputSchema: Object.assign({ root: zod_1.z.string().optional() }, config.inputSchema) }), (rawArgs) => __awaiter(this, void 0, void 0, function* () {
             let args = (rawArgs !== null && rawArgs !== void 0 ? rawArgs : {});
             const startMs = Date.now();
             let target = projectRoot;

package/dist/lib/output/mcp-results.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_READ_OUTPUT_SCHEMAS = exports.compactionSchema = void 0;
+exports.traceResult = traceResult;
+exports.deadResult = deadResult;
+const zod_1 = require("zod");
+const location = zod_1.z.object({
+    path: zod_1.z.string(),
+    line: zod_1.z.number().int().positive().describe("One-based source line"),
+});
+const graphNode = zod_1.z.object({
+    symbol: zod_1.z.string(),
+    location: location.nullable(),
+    role: zod_1.z.string(),
+    resolution: zod_1.z.enum(["indexed", "not_indexed", "ambiguous_member"]),
+    edgeKind: zod_1.z.enum(["free", "member", "type"]).optional(),
+    confidence: zod_1.z.enum(["EXTRACTED", "INFERRED"]).optional(),
+});
+const search = {
+    schemaVersion: zod_1.z.literal(1),
+    query: zod_1.z.string(),
+    roots: zod_1.z.array(zod_1.z.string()),
+    warnings: zod_1.z.array(zod_1.z.string()),
+    matches: zod_1.z
+        .array(zod_1.z.object({
+        path: zod_1.z.string(),
+        startLine: zod_1.z.number().int().positive(),
+        endLine: zod_1.z.number().int().positive(),
+        symbols: zod_1.z.array(zod_1.z.string()),
+        role: zod_1.z.string(),
+        score: zod_1.z
+            .number()
+            .nullable()
+            .describe("Search score; null when unavailable"),
+    }))
+        .max(50),
+};
+exports.compactionSchema = zod_1.z.object({
+    status: zod_1.z.enum(["completed", "skipped", "failed"]),
+    at: zod_1.z.number(),
+    attempts: zod_1.z.number(),
+    elapsedMs: zod_1.z.number(),
+    reason: zod_1.z.string().optional(),
+    logicalBytes: zod_1.z.number().optional(),
+    diskBytesBefore: zod_1.z.number().optional(),
+    diskBytesAfter: zod_1.z.number().optional(),
+    freeBytesBefore: zod_1.z.number().optional(),
+    freeBytesAfter: zod_1.z.number().optional(),
+    bytesReclaimed: zod_1.z.number().optional(),
+});
+const embedding = zod_1.z.object({
+    tier: zod_1.z.string(),
+    vectorDim: zod_1.z.number(),
+    fingerprint: zod_1.z.string(),
+});
+/** Only tools with a complete success contract advertise an output schema. */
+exports.MCP_READ_OUTPUT_SCHEMAS = {
+    semantic_search: search,
+    trace_calls: {
+        schemaVersion: zod_1.z.literal(1),
+        symbol: zod_1.z.string(),
+        root: zod_1.z.string(),
+        found: zod_1.z.boolean(),
+        center: graphNode.nullable(),
+        callers: zod_1.z.array(zod_1.z.object({
+            node: graphNode,
+            depth: zod_1.z.number().int().positive(),
+            parentIndex: zod_1.z
+                .number()
+                .int()
+                .nonnegative()
+                .nullable()
+                .describe("Index of the parent in callers; null for a direct caller of center"),
+        })),
+        callees: zod_1.z.array(graphNode).max(15),
+        importers: zod_1.z.array(zod_1.z.string()).max(10),
+        omittedCallees: zod_1.z.number().int().nonnegative(),
+        omittedImporters: zod_1.z.number().int().nonnegative(),
+        approximate: zod_1.z.literal(true),
+    },
+    dead: {
+        schemaVersion: zod_1.z.literal(1),
+        symbol: zod_1.z.string(),
+        root: zod_1.z.string(),
+        status: zod_1.z.enum(["not_found", "public_export", "dead", "live"]),
+        definition: location.nullable(),
+        isExported: zod_1.z.boolean(),
+        callerCount: zod_1.z.number().int().nonnegative(),
+        callers: zod_1.z.array(location),
+        approximate: zod_1.z.literal(true),
+    },
+    index_status: {
+        schemaVersion: zod_1.z.literal(1),
+        root: zod_1.z.string(),
+        store: zod_1.z.string(),
+        secondary: zod_1.z.boolean(),
+        chunks: zod_1.z.number().int().nonnegative(),
+        files: zod_1.z.number().int().nonnegative(),
+        projects: zod_1.z.number().int().nonnegative(),
+        embedding: zod_1.z.object({
+            state: zod_1.z.string(),
+            configured: embedding,
+            built: embedding.nullable(),
+        }),
+        watcher: zod_1.z.object({
+            status: zod_1.z.string(),
+            indexState: zod_1.z
+                .object({
+                indexing: zod_1.z.boolean(),
+                pendingFiles: zod_1.z.number(),
+                verifying: zod_1.z.boolean().optional(),
+                failedFiles: zod_1.z.number().optional(),
+                degraded: zod_1.z.boolean().optional(),
+                watcherMode: zod_1.z.enum(["native", "polling", "recovering"]).optional(),
+                catchupRunning: zod_1.z.boolean().optional(),
+                lastReconciledAt: zod_1.z.number().optional(),
+                overflowCount: zod_1.z.number().optional(),
+                catchupMs: zod_1.z.number().optional(),
+            })
+                .nullable(),
+        }),
+        compaction: exports.compactionSchema.nullable(),
+    },
+};
+function nodeResult(node) {
+    return Object.assign(Object.assign({ symbol: node.symbol, location: node.file ? { path: node.file, line: node.line + 1 } : null, role: node.role, resolution: node.file
+            ? "indexed"
+            : node.resolution === "ambiguous-member"
+                ? "ambiguous_member"
+                : "not_indexed" }, (node.edgeKind ? { edgeKind: node.edgeKind } : {})), (node.confidence ? { confidence: node.confidence } : {}));
+}
+function traceResult(symbol, root, graph) {
+    const callers = [];
+    function visit(trees, depth, parentIndex) {
+        for (const tree of trees) {
+            const index = callers.length;
+            callers.push({ node: nodeResult(tree.node), depth, parentIndex });
+            visit(tree.callers, depth + 1, index);
+        }
+    }
+    visit(graph.callerTree, 1, null);
+    const importers = graph.importers.filter((p) => { var _a; return p !== ((_a = graph.center) === null || _a === void 0 ? void 0 : _a.file); });
+    return {
+        schemaVersion: 1,
+        symbol,
+        root,
+        found: graph.center !== null,
+        center: graph.center ? nodeResult(graph.center) : null,
+        callers,
+        callees: graph.callees.slice(0, 15).map(nodeResult),
+        importers: importers.slice(0, 10),
+        omittedCallees: Math.max(0, graph.callees.length - 15),
+        omittedImporters: Math.max(0, importers.length - 10),
+        approximate: true,
+    };
+}
+function deadResult(symbol, root, facts) {
+    return {
+        schemaVersion: 1,
+        symbol,
+        root,
+        status: !facts.found
+            ? "not_found"
+            : facts.callerCount > 0
+                ? "live"
+                : facts.isExported
+                    ? "public_export"
+                    : "dead",
+        definition: facts.found
+            ? { path: facts.defPath, line: facts.defLine + 1 }
+            : null,
+        isExported: facts.isExported,
+        callerCount: facts.callerCount,
+        callers: facts.topCallers.map((c) => ({ path: c.file, line: c.line + 1 })),
+        approximate: true,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.26.44",
+  "version": "0.26.45",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {

package/plugins/grepmax/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.26.44",
+  "version": "0.26.45",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",