@maxgfr/codeindex 2.16.0 → 2.17.1

package/README.md

@@ -192,17 +192,65 @@ Full details incl. the HTTP protocol (build your own server):
 
 ## Use as an MCP server
 
-`codeindex mcp` (or `node scripts/cli.mjs mcp`) serves the engine over stdio —
-tools: `scan_summary`, `graph`, `symbols`, `callers`, `workspaces`, `churn`,
-`grep`. Register it in Claude Code with:
+`codeindex mcp` (or `node scripts/cli.mjs mcp`) serves the engine over stdio.
+Register it in Claude Code with:
 
 ```sh
 claude mcp add codeindex -- codeindex mcp
 ```
 
+**26 tools**, grouped by what they answer:
+
+| group | tools |
+|---|---|
+| orient | `scan_summary`, `repo_map`, `graph`, `mermaid`, `workspaces` |
+| find | `search`, `grep`, `find_symbol`, `symbols`, `symbols_overview` |
+| impact | `find_references`, `callers`, `dead_code` |
+| risk | `hotspots`, `churn`, `coupling`, `complexity`, `check_rules` |
+| edit *(write)* | `replace_symbol_body`, `insert_after_symbol`, `insert_before_symbol` |
+| memory | `write_memory`, `read_memory`, `list_memories`, `delete_memory` *(write except reads)* |
+| embeddings | `embed_status` |
+
+### Pinning the server to one repository
+
+Every tool takes a `repo` argument. A host that runs one server per workspace
+can pin it instead, so `repo` becomes optional on every tool — the pin is
+reflected in the advertised schema, not merely tolerated at call time:
+
+```sh
+codeindex mcp --repo /path/to/workspace
+```
+
+An explicit per-call `repo` still wins, so a pinned server can still answer
+about another checkout. `--server-name <name>` overrides the announced
+`serverInfo.name` for hosts that embed the server under their own identity.
+
+**Prime the index first** and activation becomes a load, not a rebuild:
+`codeindex index --repo <dir> --out <dir>/.codeindex`. The first tool call
+deserializes those artifacts when the engine version, commit and artifact
+hashes all match.
+
 `engine.mjs` is a pure side-effect-free library (safe for consumers to inline
 into their own CLIs); `cli.mjs` is the thin standalone CLI/MCP wrapper.
 
+## Command rewriting
+
+`codeindex rewrite '<command line>'` maps an expensive tree-wide search onto
+its indexed equivalent, for agent harnesses that intercept shell commands
+(iterion's `rewriters` plugin kind, generalizing rtk):
+
+```sh
+$ codeindex rewrite 'grep -rn TODO src'
+codeindex grep TODO --scope src
+```
+
+It prints the replacement and exits `0`, or exits `1` with empty stdout when it
+has no opinion — run the original. The parser is deliberately conservative: any
+shell metacharacter (pipe, redirect, substitution, chaining), any unrecognized
+flag, a non-recursive `grep`, or more than one search path all refuse the
+rewrite. A refusal costs nothing; a wrong rewrite silently changes what the
+agent asked for.
+
 ## Versioning
 
 - `ENGINE_VERSION` — the release tag, embedded greppably in the bundle.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxgfr/codeindex",
-  "version": "2.16.0",
+  "version": "2.17.1",
   "description": "Self-contained, deterministic repo-indexing engine: walk + language detection + symbol/import extraction (tree-sitter AST with regex fallback) + import resolution + typed cross-file link-graph + analytics. Ships as a single zero-dependency engine.mjs that consumer tools vendor.",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
@@ -77,7 +77,7 @@
     "tsup": "^8.3.0",
     "typescript": "^5.5.0",
     "vitest": "^4.1.0",
-    "web-tree-sitter": "^0.26.10"
+    "web-tree-sitter": "^0.26.11"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/scripts/engine.d.mts

@@ -1,4 +1,4 @@
-declare const ENGINE_VERSION = "2.16.0";
+declare const ENGINE_VERSION = "2.17.1";
 declare const SCHEMA_VERSION = 4;
 declare const EXTRACTOR_VERSION = 10;
 type FileKind = "code" | "doc" | "config" | "asset" | "other";
@@ -255,7 +255,7 @@ declare function extractAst(rel: string, ext: string, content: string, opts?: {
     maxCalls?: number;
 }): AstResult | undefined;
 
-declare const DEFAULT_GRAMMARS_URL = "https://github.com/maxgfr/codeindex/releases/download/v2.16.0/grammars-2.16.0.tar.gz";
+declare const DEFAULT_GRAMMARS_URL = "https://github.com/maxgfr/codeindex/releases/download/v2.17.1/grammars-2.17.1.tar.gz";
 interface GrammarsPullTarget {
     url: string;
     sha256Url?: string;
@@ -745,9 +745,12 @@ interface McpServerOptions {
         name?: string;
         version?: string;
     };
+    defaultRepo?: string;
 }
 declare function runMcpServer(opts?: McpServerOptions): Promise<void>;
 
+declare function rewriteCommand(cmd: string, bin?: string): string | undefined;
+
 declare function sha1(s: string | Uint8Array): string;
 declare function shortHash(s: string, n?: number): string;
 
@@ -777,6 +780,6 @@ declare function keywords(question: string): string[];
 declare function rankedKeywords(question: string): string[];
 declare function rrf<T>(lists: T[][], keyOf: (item: T) => string, k?: number): Map<string, number>;
 
-declare function runCli(argv: string[]): Promise<void>;
+declare function runCli(rawArgv: string[]): Promise<void>;
 
-export { type ArchRule, type BuildIndexOptions, type BuiltinRule, type CallerEntry, type CallerIndex, type CallerIndexOptions, type CallerSite, type ChangeCoupling, type CodeInfo, type CodeSymbol, type CouplingOptions, DEFAULT_GRAMMARS_URL, DEFAULT_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, EMBED_VERSION, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type EmbedEndpointOptions, type EmbedPullTarget, type EmbeddingIndex, type EmbeddingRecord, type EmbeddingUnit, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type GrammarsPullResult, type GrammarsPullTarget, type GrammarsTier, type GrammarsTierName, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type McpServerOptions, type MermaidOptions, type ModuleInfo, type ModuleNode, type RawCallerIndex, type RawCallerSite, type RawRef, type RenderScipOptions, type RepoMapOptions, type RepoScan, type Resolution, type ResolveContext, type RiskHotspot, type RuleSeverity, type RuleViolation, SCHEMA_VERSION, type ScanOptions, type SearchHit, type SearchOptions, type SearchResult, type SemanticSearchOptions, type SemanticSearchResult, type ShResult, type StaticEmbedModel, type SurpriseEdge, type SymbolComplexity, type SymbolIndex, type SymbolMatch, type SymbolReferences, type TestMap, type Tier, type WalkOptions, type WalkResult, type WalkedFile, type WarmGrammarsOptions, type WarmGrammarsResult, type WorkspaceInfo, type WorkspaceKind, type WorkspacePackage, allGrammarKeys, applyCentrality, basicTokenize, betweennessOf, buildArtifactsFromScan, buildCallerIndex, buildEmbeddingIndex, buildEndpointIndex, buildGraph, buildIndexArtifacts, buildModules, buildRawCallerIndex, buildResolveContext, buildSymbolIndex, byKey, byStr, categorize, changeCoupling, changedSince, checkRules, classify, clip, clipInline, communityOf, compileGlobs, complexityOfSource, computeImportPairs, computeSurprises, computeSymbolRefs, computeTestMap, deleteMemory, deserializeEmbeddings, detectCommunities, detectWorkspaces, diffFiles, diffHunks, embedEndpointUrl, embedViaEndpoint, embeddingUnits, enclosingSymbol, encode, encodeQueryViaEndpoint, ensureGrammars, escapeRegExp, extToLang, extractAst, extractCode, extractGrammarsTarball, extractMarkdown, extractSymbols, extractTarInto, fetchExpectedSha256, fetchGrammarsTarball, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarKeysForExts, grammarReady, grepRepo, hasEmbedModel, have, headCommit, healthzUrl, insertAfterSymbol, insertBeforeSymbol, intDot, isCode, isDoc, isGitWorktree, isIgnored, isSurprising, isTestFile, isTestPath, keywords, languageOf, listMemories, loadEmbedModel, pagerankOf, parseGitignore, parseRules, probeEndpoint, pullGrammars, quantize, rankHotspots, rankedKeywords, readMemory, readText, renderGraphJson, renderMermaid, renderRepoMap, renderScip, renderSymbolsJson, replaceSymbolBody, resolveBaseRef, resolveCallEdges, resolveDocLink, resolveEmbedEndpoint, resolveEmbedModelDir, resolveEmbedPullUrl, resolveGrammarsDir, resolveGrammarsPullTarget, resolveGrammarsTier, resolveImport, resolveUniqueSymbol, riskHotspots, roundHalfToEven, rrf, runCli, runMcpServer, scanRepo, searchIndex, searchSemantic, serializeEmbeddings, sh, sha1, sharedGrammarsCacheDir, shortHash, slugify, subtokens, symbolComplexity, symbolsOverview, testsForModule, tierForPath, tokenize, uniqueSymbolDefs, untestedModules, untrackedFiles, walk, warmGrammars, wordpiece, writeMemory };
+export { type ArchRule, type BuildIndexOptions, type BuiltinRule, type CallerEntry, type CallerIndex, type CallerIndexOptions, type CallerSite, type ChangeCoupling, type CodeInfo, type CodeSymbol, type CouplingOptions, DEFAULT_GRAMMARS_URL, DEFAULT_MAX_FILES, type DeadSymbol, type DiffFile, type DiffSpec, EMBED_VERSION, ENGINE_VERSION, EXTRACTOR_VERSION, type Edge, type EdgeKind, type EditResult, type EmbedEndpointOptions, type EmbedPullTarget, type EmbeddingIndex, type EmbeddingRecord, type EmbeddingUnit, type FileCategory, type FileKind, type FileNode, type FileRecord, type FindSymbolOptions, type ForbiddenEdgeRule, type GrammarsPullResult, type GrammarsPullTarget, type GrammarsTier, type GrammarsTierName, type Graph, type GrepOptions, type Hotspot, type Hunk, type IgnoreRule, type IndexArtifacts, MARKDOWN_EXT, type MarkdownInfo, type McpServerOptions, type MermaidOptions, type ModuleInfo, type ModuleNode, type RawCallerIndex, type RawCallerSite, type RawRef, type RenderScipOptions, type RepoMapOptions, type RepoScan, type Resolution, type ResolveContext, type RiskHotspot, type RuleSeverity, type RuleViolation, SCHEMA_VERSION, type ScanOptions, type SearchHit, type SearchOptions, type SearchResult, type SemanticSearchOptions, type SemanticSearchResult, type ShResult, type StaticEmbedModel, type SurpriseEdge, type SymbolComplexity, type SymbolIndex, type SymbolMatch, type SymbolReferences, type TestMap, type Tier, type WalkOptions, type WalkResult, type WalkedFile, type WarmGrammarsOptions, type WarmGrammarsResult, type WorkspaceInfo, type WorkspaceKind, type WorkspacePackage, allGrammarKeys, applyCentrality, basicTokenize, betweennessOf, buildArtifactsFromScan, buildCallerIndex, buildEmbeddingIndex, buildEndpointIndex, buildGraph, buildIndexArtifacts, buildModules, buildRawCallerIndex, buildResolveContext, buildSymbolIndex, byKey, byStr, categorize, changeCoupling, changedSince, checkRules, classify, clip, clipInline, communityOf, compileGlobs, complexityOfSource, computeImportPairs, computeSurprises, computeSymbolRefs, computeTestMap, deleteMemory, deserializeEmbeddings, detectCommunities, detectWorkspaces, diffFiles, diffHunks, embedEndpointUrl, embedViaEndpoint, embeddingUnits, enclosingSymbol, encode, encodeQueryViaEndpoint, ensureGrammars, escapeRegExp, extToLang, extractAst, extractCode, extractGrammarsTarball, extractMarkdown, extractSymbols, extractTarInto, fetchExpectedSha256, fetchGrammarsTarball, findDeadCode, findReferences, findSymbol, foldText, gitChurn, grammarKeyForExt, grammarKeysForExts, grammarReady, grepRepo, hasEmbedModel, have, headCommit, healthzUrl, insertAfterSymbol, insertBeforeSymbol, intDot, isCode, isDoc, isGitWorktree, isIgnored, isSurprising, isTestFile, isTestPath, keywords, languageOf, listMemories, loadEmbedModel, pagerankOf, parseGitignore, parseRules, probeEndpoint, pullGrammars, quantize, rankHotspots, rankedKeywords, readMemory, readText, renderGraphJson, renderMermaid, renderRepoMap, renderScip, renderSymbolsJson, replaceSymbolBody, resolveBaseRef, resolveCallEdges, resolveDocLink, resolveEmbedEndpoint, resolveEmbedModelDir, resolveEmbedPullUrl, resolveGrammarsDir, resolveGrammarsPullTarget, resolveGrammarsTier, resolveImport, resolveUniqueSymbol, rewriteCommand, riskHotspots, roundHalfToEven, rrf, runCli, runMcpServer, scanRepo, searchIndex, searchSemantic, serializeEmbeddings, sh, sha1, sharedGrammarsCacheDir, shortHash, slugify, subtokens, symbolComplexity, symbolsOverview, testsForModule, tierForPath, tokenize, uniqueSymbolDefs, untestedModules, untrackedFiles, walk, warmGrammars, wordpiece, writeMemory };

package/scripts/engine.mjs

@@ -14,7 +14,7 @@ var ENGINE_VERSION, SCHEMA_VERSION, EXTRACTOR_VERSION;
 var init_types = __esm({
   "src/types.ts"() {
     "use strict";
-    ENGINE_VERSION = "2.16.0";
+    ENGINE_VERSION = "2.17.1";
     SCHEMA_VERSION = 4;
     EXTRACTOR_VERSION = 10;
   }
@@ -10440,8 +10440,8 @@ async function warmGrammarsForRepo(repo) {
   const { files } = walk(repo, {});
   await ensureGrammars(grammarKeysForExts(files.map((f) => f.ext)));
 }
-async function callTool(name2, args2) {
-  const repo = str(args2.repo);
+async function callTool(name2, args2, defaultRepo) {
+  const repo = str(args2.repo) ?? defaultRepo;
   if (!repo) throw new Error("`repo` is required (absolute path to the repository root)");
   const scanOpts = { scope: str(args2.scope), include: strArray(args2.include), exclude: strArray(args2.exclude) };
   if (!SCANLESS_TOOLS.has(name2)) await warmGrammarsForRepo(repo);
@@ -10636,11 +10636,26 @@ async function callTool(name2, args2) {
   }
   throw new Error(`unknown tool: ${name2}`);
 }
+function toolsFor(defaultRepo) {
+  if (!defaultRepo) return TOOLS;
+  return TOOLS.map((t) => ({
+    ...t,
+    inputSchema: {
+      ...t.inputSchema,
+      properties: {
+        ...t.inputSchema.properties,
+        repo: { type: "string", description: `Absolute path to the repository root (optional \u2014 defaults to ${defaultRepo})` }
+      },
+      required: t.inputSchema.required.filter((r) => r !== "repo")
+    }
+  }));
+}
 async function runMcpServer(opts = {}) {
   const serverInfo = {
     name: opts.serverInfo?.name ?? "codeindex",
     version: opts.serverInfo?.version ?? ENGINE_VERSION
   };
+  const tools = toolsFor(opts.defaultRepo);
   const send = (msg) => {
     process.stdout.write(JSON.stringify({ jsonrpc: "2.0", ...msg }) + "\n");
   };
@@ -10673,13 +10688,13 @@ async function runMcpServer(opts = {}) {
       } else if (req.method === "ping") {
         send({ id: req.id, result: {} });
       } else if (req.method === "tools/list") {
-        send({ id: req.id, result: { tools: TOOLS } });
+        send({ id: req.id, result: { tools } });
       } else if (req.method === "tools/call") {
         const params = req.params ?? {};
         const name2 = str(params.name) ?? "";
         const args2 = params.arguments ?? {};
         try {
-          const text = await callTool(name2, args2);
+          const text = await callTool(name2, args2, opts.defaultRepo);
           send({ id: req.id, result: { content: [{ type: "text", text }] } });
         } catch (e) {
           send({
@@ -10989,6 +11004,121 @@ var init_mcp = __esm({
   }
 });
 
+// src/rewrite.ts
+var rewrite_exports = {};
+__export(rewrite_exports, {
+  rewriteCommand: () => rewriteCommand,
+  shellQuote: () => shellQuote,
+  tokenize: () => tokenize2
+});
+function tokenize2(line) {
+  const out2 = [];
+  let cur = "";
+  let quote;
+  let started = false;
+  for (let i2 = 0; i2 < line.length; i2++) {
+    const c2 = line[i2];
+    if (quote) {
+      if (c2 === quote) quote = void 0;
+      else cur += c2;
+      continue;
+    }
+    if (c2 === '"' || c2 === "'") {
+      quote = c2;
+      started = true;
+      continue;
+    }
+    if (c2 === " " || c2 === "	") {
+      if (started || cur) out2.push(cur);
+      cur = "";
+      started = false;
+      continue;
+    }
+    cur += c2;
+  }
+  if (quote) return void 0;
+  if (started || cur) out2.push(cur);
+  return out2;
+}
+function shellQuote(s) {
+  if (s !== "" && !/[^A-Za-z0-9_\-./=@:]/.test(s)) return s;
+  return "'" + s.replace(/'/g, `'\\''`) + "'";
+}
+function parseSearch(bin, args2) {
+  const p = { ignoreCase: false, includes: [], recursive: bin !== "grep" && bin !== "egrep" };
+  const positionals = [];
+  for (let i2 = 0; i2 < args2.length; i2++) {
+    const a = args2[i2];
+    if (a === void 0) continue;
+    if (a === "--") {
+      positionals.push(...args2.slice(i2 + 1));
+      break;
+    }
+    if (!a.startsWith("-") || a === "-") {
+      positionals.push(a);
+      continue;
+    }
+    if (a === "-i" || a === "--ignore-case") {
+      p.ignoreCase = true;
+    } else if (a === "-r" || a === "-R" || a === "--recursive") {
+      p.recursive = true;
+    } else if (a === "-n" || a === "--line-number" || a === "-H" || a === "--with-filename" || a === "--no-heading") {
+    } else if (a === "-e" || a === "--regexp") {
+      const v = args2[++i2];
+      if (v === void 0 || p.pattern !== void 0) return void 0;
+      p.pattern = v;
+    } else if (a.startsWith("--include=")) {
+      p.includes.push(a.slice("--include=".length));
+    } else if (a === "--include" || a === "-g" || a === "--glob") {
+      const v = args2[++i2];
+      if (v === void 0) return void 0;
+      p.includes.push(v);
+    } else if (a.length > 2 && /^-[a-zA-Z]+$/.test(a)) {
+      const expanded = a.slice(1).split("").map((c2) => `-${c2}`);
+      args2.splice(i2, 1, ...expanded);
+      i2--;
+    } else {
+      return void 0;
+    }
+  }
+  if (p.pattern === void 0) {
+    const first = positionals.shift();
+    if (first === void 0 || first === "") return void 0;
+    p.pattern = first;
+  }
+  if (positionals.length > 1) return void 0;
+  p.path = positionals[0];
+  return p;
+}
+function rewriteCommand(cmd, bin = "codeindex") {
+  const line = cmd.trim();
+  if (!line || SHELL_METACHARS.test(line)) return void 0;
+  const tokens = tokenize2(line);
+  if (!tokens || tokens.length < 2) return void 0;
+  const [head, ...args2] = tokens;
+  if (head === void 0 || !GREP_BINARIES.has(head)) return void 0;
+  const p = parseSearch(head, args2);
+  if (!p || p.pattern === void 0) return void 0;
+  const pattern = p.pattern;
+  if (!p.recursive) return void 0;
+  const path = p.path;
+  const out2 = [bin, "grep", shellQuote(pattern)];
+  if (path && path !== "." && path !== "./") {
+    out2.push("--scope", shellQuote(path.replace(/\/+$/, "")));
+  }
+  if (p.ignoreCase) out2.push("--ignore-case");
+  for (const g of p.includes) out2.push("--include", shellQuote(g));
+  return out2.join(" ");
+}
+var SHELL_METACHARS, GREP_BINARIES;
+var init_rewrite = __esm({
+  "src/rewrite.ts"() {
+    "use strict";
+    SHELL_METACHARS = /[|&;<>`\n\r$(){}]/;
+    GREP_BINARIES = /* @__PURE__ */ new Set(["grep", "egrep", "rg", "ripgrep"]);
+  }
+});
+
 // src/engine.ts
 init_types();
 init_walk();
@@ -11601,6 +11731,7 @@ init_deadcode();
 init_complexity();
 init_viz();
 init_mcp();
+init_rewrite();
 init_hash();
 init_sort();
 init_util();
@@ -11677,11 +11808,31 @@ Commands:
   repomap     Token-budgeted map of the highest-PageRank files (--budget-tokens)
   hotspots    Churn \xD7 size ranking of the files where work concentrates (JSON)
   coupling    Change coupling: files that change together (JSON; --since <ref>)
-  mcp         Run as an MCP server over stdio (tools: scan_summary, graph,
-              symbols, callers, workspaces, churn, grep)
+  deadcode    Dead-code candidates in two labeled tiers: 'unreferenced' (no
+              call site binds AND nothing references the name) and 'uncalled'
+              (referenced \u2014 re-export, type position \u2014 but never called)
+  complexity  Cyclomatic-complexity estimates, most-complex first. Pass a file
+              positional for one file; omit for the repo-wide top
+  risk        Complexity \xD7 git-churn ranking (JSON; --since <ref> to bound)
+  mermaid     Mermaid diagram of the module graph; pass a module positional to
+              focus on one neighborhood
+  rewrite     Map an expensive tree-wide search onto its indexed equivalent:
+              cli.mjs rewrite '<command line>'. Prints the replacement command
+              and exits 0, or exits 1 when it has no opinion (run the original).
+              Deliberately conservative \u2014 any shell metacharacter or unknown
+              flag refuses the rewrite
+  mcp         Run as an MCP server over stdio (26 tools: scan_summary, graph,
+              symbols, callers, workspaces, churn, symbols_overview,
+              find_symbol, find_references, repo_map, hotspots, coupling,
+              dead_code, complexity, mermaid, grep, search, embed_status,
+              check_rules, the memory quartet and the three symbolic-edit
+              writes). Flags: --repo <dir> pins ONE repository so the per-tool
+              repo argument becomes optional (an explicit per-call repo still
+              wins); --server-name <name> overrides the announced serverInfo
   version     Print the engine version
 
-Flags:
+Flags (accepted before OR after the subcommand: '--repo X scan' and
+'scan --repo X' are equivalent):
   --repo <dir>        Repo root (default: cwd)
   --out <file>        Write output to a file instead of stdout (\`scip\`: --out -
                       writes the binary index to stdout)
@@ -11708,6 +11859,8 @@ Flags:
   --recall            \`callers\`: recall-oriented binding (issue #7) \u2014 relaxes
                       the JS/TS import gate to unique repo-wide names and labels
                       each site corroborated|unique-name
+  --ignore-case       \`grep\`: case-insensitive matching
+  --max-hits <n>      \`grep\`: cap returned hits (default 200)
 `;
 function parseFlags(args2) {
   const flags2 = { repo: process.cwd(), include: [], exclude: [], gitignore: true, ignoreDirs: [], noAst: false, fuzzy: true, semantic: false };
@@ -11774,7 +11927,62 @@ function scanOptions(flags2, precomputedWalk) {
   };
 }
 var SCANLESS_COMMANDS = /* @__PURE__ */ new Set(["grep", "churn", "coupling", "workspaces", "grammars"]);
-async function runCli(argv) {
+function parseMcpFlags(argv) {
+  let defaultRepo;
+  let name2;
+  for (let i2 = 0; i2 < argv.length; i2++) {
+    const a = argv[i2];
+    if (a === "--repo") {
+      const v = argv[++i2];
+      if (!v) throw new Error("--repo requires a directory");
+      defaultRepo = resolve2(v);
+    } else if (a === "--server-name") {
+      const v = argv[++i2];
+      if (!v) throw new Error("--server-name requires a value");
+      name2 = v;
+    } else {
+      throw new Error(`unknown flag for \`mcp\`: ${a}`);
+    }
+  }
+  if (defaultRepo && !existsSync5(defaultRepo)) throw new Error(`--repo path does not exist: ${defaultRepo}`);
+  return { defaultRepo, serverInfo: name2 ? { name: name2 } : void 0 };
+}
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--repo",
+  "--out",
+  "--project-root",
+  "--include",
+  "--exclude",
+  "--scope",
+  "--ignore-dir",
+  "--max-files",
+  "--max-bytes",
+  "--max-calls",
+  "--max-hits",
+  "--budget-tokens",
+  "--since",
+  "--config",
+  "--limit",
+  "--server-name"
+]);
+function hoistLeadingFlags(argv) {
+  const lead = [];
+  let i2 = 0;
+  while (i2 < argv.length) {
+    const a = argv[i2];
+    if (a === void 0 || !a.startsWith("-")) break;
+    lead.push(a);
+    i2++;
+    if (VALUE_FLAGS.has(a) && i2 < argv.length) {
+      lead.push(argv[i2]);
+      i2++;
+    }
+  }
+  if (lead.length === 0 || i2 >= argv.length) return argv;
+  return [argv[i2], ...lead, ...argv.slice(i2 + 1)];
+}
+async function runCli(rawArgv) {
+  const argv = hoistLeadingFlags(rawArgv);
   const [cmd, ...rest] = argv;
   if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
     process.stdout.write(HELP);
@@ -11784,9 +11992,19 @@ async function runCli(argv) {
     process.stdout.write(ENGINE_VERSION + "\n");
     return;
   }
+  if (cmd === "rewrite") {
+    const { rewriteCommand: rewriteCommand2 } = await Promise.resolve().then(() => (init_rewrite(), rewrite_exports));
+    const rewritten = rewriteCommand2(rest.join(" "));
+    if (!rewritten) {
+      process.exitCode = 1;
+      return;
+    }
+    process.stdout.write(rewritten + "\n");
+    return;
+  }
   if (cmd === "mcp") {
     const { runMcpServer: runMcpServer2 } = await Promise.resolve().then(() => (init_mcp(), mcp_exports));
-    await runMcpServer2();
+    await runMcpServer2(parseMcpFlags(rest));
     return;
   }
   const flags2 = parseFlags(rest);
@@ -12117,7 +12335,8 @@ async function runCli(argv) {
     emit(renderMermaid(graph, { module: flags2.positional }), flags2.out);
   } else if (cmd === "grep") {
     if (!flags2.positional) throw new Error("grep needs a pattern: cli.mjs grep <pattern> --repo <dir>");
-    const globs = [...flags2.include, ...flags2.exclude.map((g) => `!${g}`)];
+    const scopeGlobs = flags2.scope ? [`${flags2.scope.replace(/\/+$/, "")}/**`] : [];
+    const globs = [...scopeGlobs, ...flags2.include, ...flags2.exclude.map((g) => `!${g}`)];
     const hits = grepRepo(flags2.repo, flags2.positional, {
       globs: globs.length ? globs : void 0,
       ignoreCase: flags2.ignoreCase,
@@ -12246,6 +12465,7 @@ export {
   resolveGrammarsTier,
   resolveImport,
   resolveUniqueSymbol,
+  rewriteCommand,
   riskHotspots,
   roundHalfToEven,
   rrf,

package/src/engine-cli.ts

@@ -77,11 +77,31 @@ Commands:
   repomap     Token-budgeted map of the highest-PageRank files (--budget-tokens)
   hotspots    Churn × size ranking of the files where work concentrates (JSON)
   coupling    Change coupling: files that change together (JSON; --since <ref>)
-  mcp         Run as an MCP server over stdio (tools: scan_summary, graph,
-              symbols, callers, workspaces, churn, grep)
+  deadcode    Dead-code candidates in two labeled tiers: 'unreferenced' (no
+              call site binds AND nothing references the name) and 'uncalled'
+              (referenced — re-export, type position — but never called)
+  complexity  Cyclomatic-complexity estimates, most-complex first. Pass a file
+              positional for one file; omit for the repo-wide top
+  risk        Complexity × git-churn ranking (JSON; --since <ref> to bound)
+  mermaid     Mermaid diagram of the module graph; pass a module positional to
+              focus on one neighborhood
+  rewrite     Map an expensive tree-wide search onto its indexed equivalent:
+              cli.mjs rewrite '<command line>'. Prints the replacement command
+              and exits 0, or exits 1 when it has no opinion (run the original).
+              Deliberately conservative — any shell metacharacter or unknown
+              flag refuses the rewrite
+  mcp         Run as an MCP server over stdio (26 tools: scan_summary, graph,
+              symbols, callers, workspaces, churn, symbols_overview,
+              find_symbol, find_references, repo_map, hotspots, coupling,
+              dead_code, complexity, mermaid, grep, search, embed_status,
+              check_rules, the memory quartet and the three symbolic-edit
+              writes). Flags: --repo <dir> pins ONE repository so the per-tool
+              repo argument becomes optional (an explicit per-call repo still
+              wins); --server-name <name> overrides the announced serverInfo
   version     Print the engine version
 
-Flags:
+Flags (accepted before OR after the subcommand: '--repo X scan' and
+'scan --repo X' are equivalent):
   --repo <dir>        Repo root (default: cwd)
   --out <file>        Write output to a file instead of stdout (\`scip\`: --out -
                       writes the binary index to stdout)
@@ -108,6 +128,8 @@ Flags:
   --recall            \`callers\`: recall-oriented binding (issue #7) — relaxes
                       the JS/TS import gate to unique repo-wide names and labels
                       each site corroborated|unique-name
+  --ignore-case       \`grep\`: case-insensitive matching
+  --max-hits <n>      \`grep\`: cap returned hits (default 200)
 `;
 
 interface CliFlags {
@@ -212,7 +234,85 @@ function scanOptions(flags: CliFlags, precomputedWalk?: WalkResult): BuildIndexO
 // version/help/mcp return before we get there.
 const SCANLESS_COMMANDS = new Set(["grep", "churn", "coupling", "workspaces", "grammars"]);
 
-export async function runCli(argv: string[]): Promise<void> {
+// Flags for `codeindex mcp`. Kept separate from parseFlags on purpose (see the
+// dispatch site). `--repo` is resolved to an absolute path and must exist: a
+// server pinned to a typo'd directory would otherwise answer every tool call
+// with the same confusing per-call error instead of failing at startup.
+export function parseMcpFlags(argv: string[]): { defaultRepo?: string; serverInfo?: { name?: string } } {
+  let defaultRepo: string | undefined;
+  let name: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--repo") {
+      const v = argv[++i];
+      if (!v) throw new Error("--repo requires a directory");
+      defaultRepo = resolve(v);
+    } else if (a === "--server-name") {
+      const v = argv[++i];
+      if (!v) throw new Error("--server-name requires a value");
+      name = v;
+    } else {
+      throw new Error(`unknown flag for \`mcp\`: ${a}`);
+    }
+  }
+  if (defaultRepo && !existsSync(defaultRepo)) throw new Error(`--repo path does not exist: ${defaultRepo}`);
+  return { defaultRepo, serverInfo: name ? { name } : undefined };
+}
+
+// Flags that consume the following argv element. Needed to hoist leading flags
+// past the subcommand without mistaking a flag's VALUE for the command name
+// (`--repo /x scan`: `/x` must not be read as the command).
+const VALUE_FLAGS = new Set([
+  "--repo",
+  "--out",
+  "--project-root",
+  "--include",
+  "--exclude",
+  "--scope",
+  "--ignore-dir",
+  "--max-files",
+  "--max-bytes",
+  "--max-calls",
+  "--max-hits",
+  "--budget-tokens",
+  "--since",
+  "--config",
+  "--limit",
+  "--server-name",
+]);
+
+// Accept global flags BEFORE the subcommand as well as after, so
+// `codeindex --repo /x scan` and `codeindex scan --repo /x` agree. A strict
+// subcommand-first parser reads the leading flag as the command name and fails
+// with a baffling "unknown flag: scan".
+//
+// This is not only ergonomics. A host that wraps the CLI may splice a flag in
+// right after the binary name — iterion's rewriter `inject_flag` does exactly
+// that, turning `codeindex grep foo` into `codeindex --max-hits 40 grep foo` —
+// and without hoisting that command cannot run at all.
+//
+// Returns argv unchanged when there is nothing to hoist, so `--help`,
+// `--version` and a bare subcommand all keep their existing behaviour.
+export function hoistLeadingFlags(argv: string[]): string[] {
+  const lead: string[] = [];
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === undefined || !a.startsWith("-")) break;
+    lead.push(a);
+    i++;
+    if (VALUE_FLAGS.has(a) && i < argv.length) {
+      lead.push(argv[i] as string);
+      i++;
+    }
+  }
+  // No leading flags, or they were the whole line (`--help`, `--version`).
+  if (lead.length === 0 || i >= argv.length) return argv;
+  return [argv[i] as string, ...lead, ...argv.slice(i + 1)];
+}
+
+export async function runCli(rawArgv: string[]): Promise<void> {
+  const argv = hoistLeadingFlags(rawArgv);
   const [cmd, ...rest] = argv;
   if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
     process.stdout.write(HELP);
@@ -222,9 +322,28 @@ export async function runCli(argv: string[]): Promise<void> {
     process.stdout.write(ENGINE_VERSION + "\n");
     return;
   }
+  if (cmd === "rewrite") {
+    // Host contract (iterion's `rewriters` kind, rtk's generalization): stdin
+    // is nothing, argv is ONE full command line, stdout is the command to run
+    // instead, and the exit code says whether to use it. Exit 1 = "no opinion,
+    // run the original" — the overwhelmingly common, deliberately cheap case.
+    const { rewriteCommand } = await import("./rewrite.js");
+    const rewritten = rewriteCommand(rest.join(" "));
+    if (!rewritten) {
+      process.exitCode = 1;
+      return;
+    }
+    process.stdout.write(rewritten + "\n");
+    return;
+  }
   if (cmd === "mcp") {
+    // `mcp` takes a deliberately tiny, self-contained flag set rather than
+    // going through parseFlags: the shared parser owns positional/scope
+    // semantics that mean nothing to a long-lived server, and every unknown
+    // flag there is fatal. Pinning is OPT-IN — a bare `codeindex mcp` keeps
+    // the historical contract where each tool call carries its own `repo`.
     const { runMcpServer } = await import("./mcp.js");
-    await runMcpServer();
+    await runMcpServer(parseMcpFlags(rest));
     return;
   }
 
@@ -646,7 +765,12 @@ export async function runCli(argv: string[]): Promise<void> {
     emit(renderMermaid(graph, { module: flags.positional }), flags.out);
   } else if (cmd === "grep") {
     if (!flags.positional) throw new Error("grep needs a pattern: cli.mjs grep <pattern> --repo <dir>");
-    const globs = [...flags.include, ...flags.exclude.map((g) => `!${g}`)];
+    // `--scope <dir>` is documented as global sugar for `--include '<dir>/**'`;
+    // every other command gets it via scanOptions, but grep bypasses the scan
+    // and builds its own glob list — so it has to fold the sugar in itself, or
+    // the flag would be silently ignored here alone.
+    const scopeGlobs = flags.scope ? [`${flags.scope.replace(/\/+$/, "")}/**`] : [];
+    const globs = [...scopeGlobs, ...flags.include, ...flags.exclude.map((g) => `!${g}`)];
     const hits = grepRepo(flags.repo, flags.positional, {
       globs: globs.length ? globs : undefined,
       ignoreCase: flags.ignoreCase,

package/src/engine.ts

@@ -185,6 +185,13 @@ export type { RepoMapOptions } from "./repomap.js";
 export { runMcpServer } from "./mcp.js";
 export type { McpServerOptions } from "./mcp.js";
 
+// Command rewriting: an expensive tree-wide search → its indexed equivalent.
+// Exported so a host can decide for itself rather than shelling out to
+// `engine.mjs rewrite` (same conservative refusal semantics either way).
+// Only the decision function is public — the tokenizer/quoter are internal
+// details, and `tokenize` is already taken here by the wordpiece tokenizer.
+export { rewriteCommand } from "./rewrite.js";
+
 // General-purpose helpers shared by consumers (deterministic, dependency-free).
 export { sha1, shortHash } from "./hash.js";
 export { byStr, byKey } from "./sort.js";

package/src/mcp.ts

@@ -667,8 +667,11 @@ const SCANLESS_TOOLS = new Set([
   "embed_status",
 ]);
 
-async function callTool(name: string, args: Record<string, unknown>): Promise<string> {
-  const repo = str(args.repo);
+async function callTool(name: string, args: Record<string, unknown>, defaultRepo?: string): Promise<string> {
+  // An explicit per-call `repo` always wins; `defaultRepo` is the server-level
+  // pin (`codeindex mcp --repo <dir>`) that lets a host bind one server process
+  // to one workspace, so agents need not know — or restate — the absolute path.
+  const repo = str(args.repo) ?? defaultRepo;
   if (!repo) throw new Error("`repo` is required (absolute path to the repository root)");
   const scanOpts = { scope: str(args.scope), include: strArray(args.include), exclude: strArray(args.exclude) };
   // Scan-needing tools warm the present-language grammars (re-derived per call)
@@ -886,11 +889,36 @@ async function callTool(name: string, args: Record<string, unknown>): Promise<st
   throw new Error(`unknown tool: ${name}`);
 }
 
+// The advertised tool list. Without a server-level repo pin this is TOOLS
+// verbatim (byte-compat for existing consumers). With one, every tool drops
+// `repo` from its `required` set and documents the default — so a client that
+// omits it is spec-correct rather than relying on the server being lenient.
+// The pin is reflected in the schema, not just honoured at call time.
+function toolsFor(defaultRepo?: string): readonly unknown[] {
+  if (!defaultRepo) return TOOLS;
+  return TOOLS.map((t) => ({
+    ...t,
+    inputSchema: {
+      ...t.inputSchema,
+      properties: {
+        ...t.inputSchema.properties,
+        repo: { type: "string", description: `Absolute path to the repository root (optional — defaults to ${defaultRepo})` },
+      },
+      required: (t.inputSchema.required as readonly string[]).filter((r) => r !== "repo"),
+    },
+  }));
+}
+
 export interface McpServerOptions {
   // Override the serverInfo announced in the initialize response — for
   // downstream consumers embedding this server under their own identity.
   // Omitted fields keep the defaults (name "codeindex", ENGINE_VERSION).
   serverInfo?: { name?: string; version?: string };
+  // Bind the server to ONE repository, so `repo` becomes optional on every
+  // tool (an explicit per-call `repo` still wins). This is what lets a host
+  // spawn one server per workspace — `codeindex mcp --repo <dir>` — instead of
+  // requiring the agent to thread an absolute path through every single call.
+  defaultRepo?: string;
 }
 
 export async function runMcpServer(opts: McpServerOptions = {}): Promise<void> {
@@ -898,6 +926,8 @@ export async function runMcpServer(opts: McpServerOptions = {}): Promise<void> {
     name: opts.serverInfo?.name ?? "codeindex",
     version: opts.serverInfo?.version ?? ENGINE_VERSION,
   };
+  // Derived ONCE: the pin cannot change mid-session, so neither can the list.
+  const tools = toolsFor(opts.defaultRepo);
   // No startup warm: each scan-needing tool warms the present-language grammars
   // for its repo before it runs (warmGrammarsForRepo re-derives them per call),
   // so a session that never scans — or only touches one language — loads no
@@ -940,13 +970,13 @@ export async function runMcpServer(opts: McpServerOptions = {}): Promise<void> {
       } else if (req.method === "ping") {
         send({ id: req.id, result: {} });
       } else if (req.method === "tools/list") {
-        send({ id: req.id, result: { tools: TOOLS } });
+        send({ id: req.id, result: { tools } });
       } else if (req.method === "tools/call") {
         const params = req.params ?? {};
         const name = str(params.name) ?? "";
         const args = (params.arguments ?? {}) as Record<string, unknown>;
         try {
-          const text = await callTool(name, args);
+          const text = await callTool(name, args, opts.defaultRepo);
           send({ id: req.id, result: { content: [{ type: "text", text }] } });
         } catch (e) {
           send({

package/src/rewrite.ts

@@ -0,0 +1,169 @@
+// Command rewriting: map an expensive full-tree text search onto the engine's
+// indexed equivalent, so an agent shell that runs `grep -r foo .` gets bounded,
+// structured, gitignore-correct hits instead of an unbounded wall of text.
+//
+// The contract is a HOST contract, not a shell one: the caller hands us a full
+// command line and takes our stdout as the command to run instead (iterion's
+// `rewriters` plugin kind, rtk's generalization). That makes a wrong rewrite
+// far worse than no rewrite — it silently changes what the agent asked for.
+// So this module is deliberately, aggressively conservative:
+//
+//   * anything the parser cannot prove it understands → NO rewrite
+//   * any shell metacharacter at all → NO rewrite (we refuse to reason about
+//     pipelines, redirection, substitution or chaining)
+//   * any flag not on the explicit allowlist → NO rewrite
+//
+// A refusal is cheap (the original command runs untouched); a bad rewrite is
+// not. Every branch here defaults to refusing.
+
+// Shell constructs we will not reason about. Their presence anywhere in the
+// line — quoted or not — refuses the rewrite. Over-refusing is the point: a
+// pattern containing a literal `|` is rare, mis-rewriting a pipeline is fatal.
+const SHELL_METACHARS = /[|&;<>`\n\r$(){}]/;
+
+// `grep` output is line-oriented text; `codeindex grep` returns JSON hits. That
+// is the intended trade (bounded + structured), but it means we only rewrite
+// invocations whose INTENT is "search the tree", never "search this one file"
+// (cheap already) and never anything whose flags shape the output format.
+const GREP_BINARIES = new Set(["grep", "egrep", "rg", "ripgrep"]);
+
+interface Parsed {
+  pattern?: string;
+  path?: string;
+  ignoreCase: boolean;
+  includes: string[];
+  recursive: boolean;
+}
+
+// Split on whitespace honouring single/double quotes. Returns undefined on an
+// unterminated quote — an unparseable line is a refusal, not a guess.
+export function tokenize(line: string): string[] | undefined {
+  const out: string[] = [];
+  let cur = "";
+  let quote: '"' | "'" | undefined;
+  let started = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === quote) quote = undefined;
+      else cur += c;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      quote = c;
+      started = true;
+      continue;
+    }
+    if (c === " " || c === "\t") {
+      if (started || cur) out.push(cur);
+      cur = "";
+      started = false;
+      continue;
+    }
+    cur += c;
+  }
+  if (quote) return undefined; // unterminated quote
+  if (started || cur) out.push(cur);
+  return out;
+}
+
+// Wrap a token so the shell reproduces it verbatim. Single-quoting is total
+// (no escapes are interpreted inside), so the only case needing care is a
+// literal single quote, spliced via the standard '\'' idiom.
+export function shellQuote(s: string): string {
+  if (s !== "" && !/[^A-Za-z0-9_\-./=@:]/.test(s)) return s;
+  return "'" + s.replace(/'/g, `'\\''`) + "'";
+}
+
+// Parse a grep/rg invocation into the fields we can faithfully re-express.
+// Returns undefined the moment anything is unrecognized.
+function parseSearch(bin: string, args: string[]): Parsed | undefined {
+  const p: Parsed = { ignoreCase: false, includes: [], recursive: bin !== "grep" && bin !== "egrep" };
+  const positionals: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === undefined) continue;
+    if (a === "--") {
+      // Everything after `--` is positional by definition.
+      positionals.push(...args.slice(i + 1));
+      break;
+    }
+    if (!a.startsWith("-") || a === "-") {
+      positionals.push(a);
+      continue;
+    }
+    if (a === "-i" || a === "--ignore-case") {
+      p.ignoreCase = true;
+    } else if (a === "-r" || a === "-R" || a === "--recursive") {
+      p.recursive = true;
+    } else if (a === "-n" || a === "--line-number" || a === "-H" || a === "--with-filename" || a === "--no-heading") {
+      // Pure output-shaping flags whose effect codeindex already provides
+      // unconditionally (every hit carries file + line). Safe to drop.
+    } else if (a === "-e" || a === "--regexp") {
+      const v = args[++i];
+      if (v === undefined || p.pattern !== undefined) return undefined;
+      p.pattern = v;
+    } else if (a.startsWith("--include=")) {
+      p.includes.push(a.slice("--include=".length));
+    } else if (a === "--include" || a === "-g" || a === "--glob") {
+      const v = args[++i];
+      if (v === undefined) return undefined;
+      p.includes.push(v);
+    } else if (a.length > 2 && /^-[a-zA-Z]+$/.test(a)) {
+      // A bundled short-flag cluster (-rn, -ri, -rni…). Expand and re-check;
+      // any member outside the allowlist refuses the whole line.
+      const expanded = a.slice(1).split("").map((c) => `-${c}`);
+      args.splice(i, 1, ...expanded);
+      i--;
+    } else {
+      return undefined; // unknown flag → refuse
+    }
+  }
+
+  // With an -e pattern already bound, every positional is a path; otherwise the
+  // first positional is the pattern. Either way at most ONE path may remain —
+  // multi-path search has no single-scope equivalent, so it refuses.
+  if (p.pattern === undefined) {
+    const first = positionals.shift();
+    if (first === undefined || first === "") return undefined;
+    p.pattern = first;
+  }
+  if (positionals.length > 1) return undefined;
+  p.path = positionals[0];
+  return p;
+}
+
+// Rewrite `cmd` to its codeindex equivalent, or return undefined to leave it
+// alone. `bin` is the codeindex executable name to emit (the host may have it
+// on PATH under a mount point of its choosing).
+export function rewriteCommand(cmd: string, bin = "codeindex"): string | undefined {
+  const line = cmd.trim();
+  if (!line || SHELL_METACHARS.test(line)) return undefined;
+
+  const tokens = tokenize(line);
+  if (!tokens || tokens.length < 2) return undefined;
+
+  // Refuse env-prefixed or path-qualified invocations (`FOO=1 grep …`,
+  // `/usr/bin/grep …`): resolving those faithfully is not worth the risk.
+  const [head, ...args] = tokens;
+  if (head === undefined || !GREP_BINARIES.has(head)) return undefined;
+
+  const p = parseSearch(head, args);
+  if (!p || p.pattern === undefined) return undefined;
+  const pattern = p.pattern;
+  // A non-recursive `grep pattern file.ts` is already cheap and its semantics
+  // (one file, text output) are not what the indexed search provides.
+  if (!p.recursive) return undefined;
+
+  // A path that is not the tree root means "search this subtree"; express it as
+  // a scope rather than silently widening to the whole repo.
+  const path = p.path;
+  const out = [bin, "grep", shellQuote(pattern)];
+  if (path && path !== "." && path !== "./") {
+    out.push("--scope", shellQuote(path.replace(/\/+$/, "")));
+  }
+  if (p.ignoreCase) out.push("--ignore-case");
+  for (const g of p.includes) out.push("--include", shellQuote(g));
+  return out.join(" ");
+}

package/src/types.ts

@@ -1,7 +1,7 @@
 // Single source of truth for the engine version the bundle reports. Kept in
 // lockstep with package.json by the release pipeline. Do not edit by hand
 // outside a release.
-export const ENGINE_VERSION = "2.16.0";
+export const ENGINE_VERSION = "2.17.1";
 
 // Bumped whenever the on-disk artifact shape changes, so a consumer can reject
 // an index written by an incompatible engine instead of misreading it. The