grepmax 0.7.28 → 0.7.30

package/dist/lib/index/syncer.js

@@ -50,6 +50,7 @@ var __asyncValues = (this && this.__asyncValues) || function (o) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateSummaries = generateSummaries;
+exports.computeStaleFiles = computeStaleFiles;
 exports.initialSync = initialSync;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -178,6 +179,9 @@ function createNoopMetaCache() {
         close: () => __awaiter(this, void 0, void 0, function* () { }),
     };
 }
+function computeStaleFiles(cachedPaths, seenPaths) {
+    return Array.from(cachedPaths).filter((p) => !seenPaths.has(p));
+}
 function initialSync(options) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, e_1, _b, _c;
@@ -465,7 +469,7 @@ function initialSync(options) {
                     : new Error(String(flushError));
             }
             // Stale cleanup: only remove paths scoped to this project's root
-            const stale = Array.from(cachedPaths).filter((p) => !seenPaths.has(p));
+            const stale = computeStaleFiles(cachedPaths, seenPaths);
             if (!dryRun && stale.length > 0 && !shouldSkipCleanup) {
                 (0, logger_1.log)("index", `Stale cleanup: ${stale.length} paths`);
                 yield vectorDb.deletePaths(stale);

package/dist/lib/index/watcher-batch.js

@@ -0,0 +1,149 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processBatchCore = processBatchCore;
+exports.flushBatchToDb = flushBatchToDb;
+exports.computeRetryAction = computeRetryAction;
+const fs = __importStar(require("node:fs"));
+const cache_check_1 = require("../utils/cache-check");
+const file_utils_1 = require("../utils/file-utils");
+function processBatchCore(batch, metaCache, pool) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let reindexed = 0;
+        const changedIds = [];
+        const deletes = [];
+        const vectors = [];
+        const metaUpdates = new Map();
+        const metaDeletes = [];
+        for (const [absPath, event] of batch) {
+            if (event === "unlink") {
+                deletes.push(absPath);
+                metaDeletes.push(absPath);
+                reindexed++;
+                continue;
+            }
+            try {
+                const stats = yield fs.promises.stat(absPath);
+                if (!(0, file_utils_1.isIndexableFile)(absPath, stats.size))
+                    continue;
+                const cached = metaCache.get(absPath);
+                if ((0, cache_check_1.isFileCached)(cached, stats)) {
+                    continue;
+                }
+                const result = yield pool.processFile({
+                    path: absPath,
+                    absolutePath: absPath,
+                });
+                const metaEntry = {
+                    hash: result.hash,
+                    mtimeMs: result.mtimeMs,
+                    size: result.size,
+                };
+                if (cached && cached.hash === result.hash) {
+                    metaUpdates.set(absPath, metaEntry);
+                    continue;
+                }
+                if (result.shouldDelete) {
+                    deletes.push(absPath);
+                    metaUpdates.set(absPath, metaEntry);
+                    reindexed++;
+                    continue;
+                }
+                deletes.push(absPath);
+                if (result.vectors.length > 0) {
+                    vectors.push(...result.vectors);
+                    for (const v of result.vectors) {
+                        changedIds.push(v.id);
+                    }
+                }
+                metaUpdates.set(absPath, metaEntry);
+                reindexed++;
+            }
+            catch (err) {
+                const code = err === null || err === void 0 ? void 0 : err.code;
+                if (code === "ENOENT") {
+                    deletes.push(absPath);
+                    metaDeletes.push(absPath);
+                    reindexed++;
+                }
+            }
+        }
+        return { reindexed, changedIds, vectors, deletes, metaUpdates, metaDeletes };
+    });
+}
+function flushBatchToDb(result, vectorDb) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const newIds = result.vectors.map((v) => v.id);
+        if (result.vectors.length > 0) {
+            yield vectorDb.insertBatch(result.vectors);
+        }
+        if (result.deletes.length > 0) {
+            if (newIds.length > 0) {
+                yield vectorDb.deletePathsExcludingIds(result.deletes, newIds);
+            }
+            else {
+                yield vectorDb.deletePaths(result.deletes);
+            }
+        }
+    });
+}
+function computeRetryAction(batch, retryCount, maxRetries, isLockError, consecutiveLockFailures, debounceMs) {
+    var _a;
+    const requeued = new Map();
+    let dropped = 0;
+    for (const [absPath, event] of batch) {
+        const count = ((_a = retryCount.get(absPath)) !== null && _a !== void 0 ? _a : 0) + 1;
+        if (count >= maxRetries) {
+            retryCount.delete(absPath);
+            dropped++;
+        }
+        else {
+            requeued.set(absPath, event);
+            retryCount.set(absPath, count);
+        }
+    }
+    const effectiveFailures = isLockError ? consecutiveLockFailures + 1 : 0;
+    const backoffMs = Math.min(debounceMs * Math.pow(2, effectiveFailures), 30000);
+    return { requeued, dropped, backoffMs };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.7.28",
+  "version": "0.7.30",
   "author": "Robert Owens <robowens@me.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {

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

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

package/plugins/grepmax/hooks/start.js

@@ -89,7 +89,7 @@ async function main() {
     hookSpecificOutput: {
       hookEventName: "SessionStart",
       additionalContext:
-        "gmax MCP ready. Use semantic_search for concept-based code search (5+ words recommended). Use code_skeleton before reading large files. index_status to check health.",
+        'gmax ready. PREFER CLI over MCP tools — use Bash(gmax "query" --plain) for search, Bash(gmax trace <symbol>) for call graphs, Bash(gmax skeleton <path>) for file structure. CLI is 2x more token-efficient than MCP tool calls. Always add --plain flag.',
     },
   };
   process.stdout.write(JSON.stringify(response));

package/plugins/grepmax/skills/grepmax/SKILL.md

@@ -11,150 +11,99 @@ Semantic code search — finds code by meaning, not just strings.
 - grep/ripgrep: exact string match
 - gmax: concept match ("where do we handle auth?", "how does booking flow work?")
 
-## MCP tools
-
-### semantic_search
-Search code by meaning. Two output modes:
-
-**Pointer mode (default)** — returns metadata + LLM-generated summary per result:
-```
-handleAuth [exported ORCH C:8] src/auth/handler.ts:45-90
-  Validates JWT from Authorization header, checks RBAC permissions, returns 401 on failure
-  parent:AuthController calls:validateToken,checkRole,respond
-```
-
-**Code mode (`detail: "code"`)** — includes 4-line numbered code snippets:
-```
-handleAuth [exported ORCH C:8] src/auth/handler.ts:45-90
-  Validates JWT from Authorization header, checks RBAC permissions, returns 401 on failure
-  parent:AuthController calls:validateToken,checkRole,respond
-45│  const token = req.headers.get("Authorization");
-46│  const claims = await validateToken(token);
-47│  if (!claims) return unauthorized();
-48│  const allowed = await checkRole(claims.role, req.path);
-```
-
-Parameters:
-- `query` (required): Natural language. Be specific — 5+ words gives much better results than 1-2 words.
-- `limit` (optional): Max results (default 3, max 50)
-- `root` (optional): Absolute path to search a different indexed directory.
-- `path` (optional): Restrict to path prefix (e.g. "src/auth/"). Relative to the search root.
-- `detail` (optional): `"pointer"` (default), `"code"` (4-line snippets), or `"full"` (complete chunk with line numbers)
-- `context_lines` (optional): Include N lines before/after the chunk (like grep -C). Only with detail "code" or "full". Max 20.
-- `min_score` (optional): Filter by minimum relevance score (0-1)
-- `max_per_file` (optional): Cap results per file for diversity
-- `file` (optional): Filter to files matching this name (e.g. "syncer.ts"). Matches filename, not full path.
-- `exclude` (optional): Exclude files under this path prefix (e.g. "tests/" or "dist/")
-- `language` (optional): Filter by file extension (e.g. "ts", "py", "go"). Omit the dot.
-- `role` (optional): Filter by chunk role: "ORCHESTRATION" (logic/flow), "DEFINITION" (types), or "IMPLEMENTATION"
-- `mode` (optional): `"default"` (semantic only) or `"symbol"` (semantic + call graph appended). Use "symbol" when query is a function or class name — gets search results + callers/callees in one call.
-- `include_imports` (optional): Prepend file's import/require statements to each result. Deduped per file — see dependencies at a glance.
-- `name_pattern` (optional): Regex to filter by symbol name (e.g. "handle.*Auth"). Case-insensitive. Applied after search.
-
-**When to use which mode:**
-- `pointer` — navigation, finding locations, understanding architecture
-- `code` — comparing implementations, finding duplicates, checking syntax
-
-### search_all
-Search ALL indexed code across every directory. Same parameters as semantic_search (query, limit, detail, min_score, max_per_file, file, exclude, language, role) but without `root` or `path`.
-
-Additional parameters:
-- `projects` (optional): Comma-separated project names to include (e.g. "platform,osgrep"). Use `index_status` to see names.
-- `exclude_projects` (optional): Comma-separated project names to exclude (e.g. "capstone,power")
-
-Use sparingly. Prefer `semantic_search` when you know which directory to search.
-
-### code_skeleton
-File or directory structure — signatures with bodies collapsed (~4x fewer tokens).
-- `target` (required): File path, directory path (e.g. "src/lib/search/"), or comma-separated files
-- `limit` (optional): Max files for directory mode (default 10, max 20)
-- `format` (optional): `"text"` (default) or `"json"` (structured symbol list with name, line, signature, type, exported)
-
-### trace_calls
-Call graph — who imports a symbol, who calls it, and what it calls. Includes file:line locations. Unscoped — follows calls across all indexed directories.
-- `symbol` (required): Function/method/class name
-- `depth` (optional): Traversal depth for callers (default 1, max 3). depth: 2 shows callers-of-callers with indentation.
-
-Output: definition, "Imported by" (files with import statements), "Callers" (functions that call it), "Calls" (what it calls).
-
-### list_symbols
-List indexed symbols with definition locations, role, and export status.
-- `pattern` (optional): Filter by name (case-insensitive substring match)
-- `limit` (optional): Max results (default 20, max 100)
-- `path` (optional): Only symbols under this path prefix
-
-Output: `symbolName [ORCH] exported  src/path/file.ts:42`
-
-### summarize_project
-High-level project overview — languages, directory structure, role distribution, key symbols, entry points. Use when first exploring a new codebase.
-- `root` (optional): Project root path. Defaults to current project.
-
-### related_files
-Find files related to a given file by shared symbol references. Shows dependencies (what this file calls) and dependents (what calls this file).
-- `file` (required): File path relative to project root
-- `limit` (optional): Max results per direction (default 10)
-
-### recent_changes
-Show recently modified files in the index. Useful after pulls or merges to see what changed.
-- `limit` (optional): Max files (default 20)
-- `root` (optional): Project root (defaults to current project)
-
-### index_status
-Check centralized index health — chunks, files, indexed directories, model info, watcher status.
-
-### summarize_directory
-Generate LLM summaries for indexed code in a directory. Summaries are stored and returned in search results. Requires the summarizer server (auto-started by the plugin hook).
-- `path` (optional): Directory to summarize. Defaults to project root.
-- `limit` (optional): Max chunks to summarize per call (default 200, max 5000). Run again to continue.
+## IMPORTANT: Use CLI, not MCP tools
 
-## Workflow
+**Always prefer `Bash(gmax ...)` over MCP tool calls.** The CLI is ~2x more token-efficient because MCP tool schemas add ~800 tokens of overhead per call. The CLI has full feature parity with every MCP tool.
 
-1. **Explore** — `summarize_project` for high-level overview of a new codebase
-2. **Search** — `semantic_search` to find relevant code (pointers by default). Use `mode: "symbol"` for function/class names.
-3. **Read** — `Read file:line` for the specific ranges you need
-4. **Skeleton** — `code_skeleton` before reading large files or directories
-5. **Trace** — `trace_calls` to understand call flow, imports, and callers (use `depth: 2` for full chains)
-6. **Context** — `related_files` to see what else you need to look at when editing
-7. **Changes** — `recent_changes` after pulls to see what's been modified
+```
+Bash(gmax "auth handler" --role ORCHESTRATION --lang ts --plain -m 3)
+```
 
-## If results seem stale
+**Only use MCP tools** for `index_status` (quick health check) or `summarize_directory` (LLM summaries). For everything else, use CLI.
 
-The watcher auto-starts when the MCP server connects — it detects file changes and re-indexes in the background. Usually results are fresh without manual intervention.
+## CLI commands (use these)
 
-1. Check `index_status` — if watcher shows "syncing", wait for it to finish.
-2. To force a full re-index: `Bash(gmax index)` (indexes current directory)
-3. To add summaries without re-indexing: `Bash(gmax summarize)`
-4. Do NOT use `gmax reindex` — it doesn't exist.
+### Search — `gmax "query" --plain`
+```
+gmax "where do we handle authentication" --plain
+gmax "database connection pooling" --role ORCHESTRATION --plain -m 5
+gmax "error handling" --lang ts --exclude tests/ --plain
+gmax "VectorDB" --symbol --plain          # search + call graph in one shot
+gmax "handler" --name "handle.*" --plain   # regex filter on symbol names
+gmax "auth" --file handler.ts --plain      # filter by filename
+gmax "query" -C 5 --plain                  # include context lines
+gmax "query" --imports --plain             # show file imports
+```
 
-## Search warnings
+All flags: `--plain -m <n> --per-file <n> --min-score <n> --root <dir> --file <name> --exclude <prefix> --lang <ext> --role <role> --symbol --imports --name <regex> -C <n> --compact --content --scores --skeleton`
+
+### Trace — `gmax trace <symbol>`
+```
+gmax trace handleAuth                      # 1-hop: callers + callees
+gmax trace handleAuth -d 2                 # 2-hop: callers-of-callers
+```
+
+### Skeleton — `gmax skeleton <target>`
+```
+gmax skeleton src/lib/auth.ts              # single file
+gmax skeleton src/lib/search/              # entire directory
+gmax skeleton src/a.ts,src/b.ts            # batch
+gmax skeleton src/lib/auth.ts --json       # structured JSON output
+```
 
-If search results include a warning like "Full-text search unavailable", results may be less precise. This resolves automatically — the index retries FTS every 5 minutes.
+### Project overview — `gmax project`
+```
+gmax project                               # languages, structure, key symbols
+```
 
-## CLI vs MCP — when to use which
+### Related files — `gmax related <file>`
+```
+gmax related src/lib/index/syncer.ts       # dependencies + dependents
+```
 
-**Prefer CLI (`Bash(gmax ...)`) for repeated searches.** The CLI is ~2x more token-efficient because MCP tool schemas add ~800 tokens of overhead per call. Every CLI flag maps to an MCP param:
+### Recent changes — `gmax recent`
+```
+gmax recent                                # recently modified files
+```
 
+### Other
 ```
-Bash(gmax "auth handler" --role ORCHESTRATION --lang ts --plain -m 3)
+gmax symbols                               # list indexed symbols
+gmax symbols auth -p src/                  # filter by name and path
+gmax index                                 # reindex current directory
+gmax config                                # view/change settings
+gmax doctor                                # health check
 ```
 
-is equivalent to `semantic_search` with `role: "ORCHESTRATION", language: "ts", limit: 3` — but costs half the tokens.
+## Workflow
+
+1. **Explore** — `Bash(gmax project)` for overview of a new codebase
+2. **Search** — `Bash(gmax "query" --plain)` to find code. Add `--symbol` for function/class names.
+3. **Read** — `Read file:line` for specific ranges
+4. **Skeleton** — `Bash(gmax skeleton <path>)` before reading large files
+5. **Trace** — `Bash(gmax trace <symbol> -d 2)` for call flow
+6. **Context** — `Bash(gmax related <file>)` to see what else to look at
+7. **Changes** — `Bash(gmax recent)` after pulls
+
+## MCP tools (only when CLI isn't suitable)
 
-**CLI commands for all MCP tools:**
-- `gmax "query" --plain` → `semantic_search`
-- `gmax trace <symbol> -d 2` → `trace_calls` with depth
-- `gmax skeleton <target> --json` → `code_skeleton`
-- `gmax project` → `summarize_project`
-- `gmax related <file>` → `related_files`
-- `gmax recent` → `recent_changes`
+MCP tools are available but consume more tokens. Use them only for:
+- `index_status` — quick health check (no CLI equivalent that's cheaper)
+- `summarize_directory` — LLM summary generation
+- `semantic_search` with `detail: "pointer"` — when you need the structured pointer format
 
-**Use MCP tools when:** first exploring (tool descriptions guide usage), or when you need pointer mode output (more structured than CLI).
+Full MCP tool documentation: semantic_search (16 params), search_all, code_skeleton, trace_calls, list_symbols, index_status, summarize_project, related_files, recent_changes, summarize_directory.
 
 ## Tips
 
-- **Be specific.** "auth" returns noise. "where does the server validate JWT tokens from the Authorization header" returns exactly what you need. Aim for 5+ words.
-- **Use `--plain` for CLI searches** — agent-friendly output without ANSI codes.
-- **ORCH results contain the logic** — use `--role ORCHESTRATION` to filter noise.
-- **Summaries tell you what the code does** without reading it. Use them to decide what to `Read`.
-- **Use `--symbol` on CLI** to get search results + call graph in one shot.
-- **Don't search for exact strings** — use grep/Grep for that. gmax finds concepts, not literals.
+- **Always use `--plain`** on CLI searches — agent-friendly output without ANSI codes.
+- **Be specific.** 5+ words. "auth" returns noise. "where does the server validate JWT tokens" is specific.
+- **Use `--role ORCHESTRATION`** to skip type definitions and find the actual logic.
+- **Use `--symbol`** when the query is a function/class name — gets search + trace in one call.
+- **Don't search for exact strings** — use grep/Grep for that. gmax finds concepts.
+
+## If results seem stale
+
+The watcher auto-starts on first CLI search. Usually results are fresh without manual intervention.
+1. `Bash(gmax index)` to force re-index
+2. Do NOT use `gmax reindex` — it doesn't exist.