@levnikolaevich/hex-line-mcp 1.3.6 → 1.4.0

package/README.md

@@ -42,7 +42,7 @@ Advanced / occasional:
 | `get_file_info` | File metadata without reading content | Size, lines, mtime, type, binary detection |
 | `setup_hooks` | Configure Claude hooks + install output style | Gemini/Codex get guidance only; no hooks |
 | `changes` | Compare file against git ref, shows added/removed/modified symbols | AST-level semantic diff |
-| `bulk_replace` | Search-and-replace across multiple files by glob | Per-file diffs, dry_run, max_files safety |
+| `bulk_replace` | Search-and-replace across multiple files by glob | Compact summary (default) or capped diffs via `format`, dry_run, max_files |
 
 ### Hooks (PreToolUse + PostToolUse)
 
@@ -90,45 +90,33 @@ The `setup_hooks` tool automatically installs the output style to `~/.claude/out
 
 ## Benchmarking
 
-`hex-line-mcp` now distinguishes:
+Two-tier benchmark architecture:
 
-- `tests` — correctness and regression safety
-- `benchmarks` — comparative workflow efficiency against built-in tools
-- `diagnostics` — modeled tool-level measurements for engineering inspection
-
-Public benchmark mode reports only comparative multi-step workflows:
+- `/benchmark-compare` — real 1:1 comparison (runs inside Claude Code, calls BOTH built-in and hex-line tools on same files)
+- `npm run benchmark` — hex-line standalone metrics (Node.js, all real library calls, no simulations)
 
 ```bash
 npm run benchmark -- --repo /path/to/repo
-```
-
-Optional diagnostics stay available separately:
-
-```bash
 npm run benchmark:diagnostic -- --repo /path/to/repo
-npm run benchmark:diagnostic:graph -- --repo /path/to/repo
 ```
 
-The diagnostics output includes synthetic tool-level comparisons such as read, grep, verify, and graph-enrichment helpers. Those numbers are useful for inspecting output shape and token behavior, but they are not the public workflow benchmark score.
-
-Current sample run on the `hex-line-mcp` repo with session-derived workflows:
-
-| ID | Workflow | Built-in | hex-line | Savings | Ops |
-|----|----------|---------:|---------:|--------:|----:|
-| W1 | Debug hook file-listing redirect | 23,143 chars | 882 chars | 96% | 3→2 |
-| W2 | Adjust `setup_hooks` guidance and verify | 24,877 chars | 1,637 chars | 93% | 3→3 |
-| W3 | Repo-wide benchmark wording refresh | 137,796 chars | 38,918 chars | 72% | 15→1 |
-| W4 | Inspect large smoke test before edit | 49,566 chars | 2,104 chars | 96% | 3→3 |
+Current hex-line workflow metrics on the `hex-line-mcp` repo (all real library calls):
 
-Workflow summary: `89%` average token savings, `24→9` tool calls (`63%` fewer).
+| # | Workflow | Hex-line output | Ops |
+|---|----------|---------:|----:|
+| W1 | Debug hook file-listing redirect | 882 chars | 2 |
+| W2 | Adjust `setup_hooks` guidance and verify | 1,719 chars | 3 |
+| W3 | Repo-wide benchmark wording refresh | 213 chars | 1 |
+| W4 | Inspect large smoke test before edit | 2,322 chars | 3 |
+| W5 | Follow-up edit after unrelated line shift | 1,267 chars | 3 |
 
-These workflows are derived from recent real Claude sessions, but executed against local reproducible fixtures in the repository. They should be read as workflow-efficiency measurements, not as correctness or semantic-quality claims.
+Workflow total: `6,403` chars across `12` ops. Run `/benchmark-compare` in Claude Code for full built-in vs hex-line comparison with real tool calls on both sides.
 
 ### Optional Graph Enrichment
 
-If a project already has `.codegraph/index.db`, `hex-line` can add lightweight graph hints to `read_file`, `outline`, `grep_search`, and `edit_file`.
+If a project already has `.hex-skills/codegraph/index.db`, `hex-line` can add lightweight graph hints to `read_file`, `outline`, `grep_search`, and `edit_file`.
 
-- Graph enrichment is optional. If `.codegraph/index.db` is missing, `hex-line` falls back to standard behavior silently.
+- Graph enrichment is optional. If `.hex-skills/codegraph/index.db` is missing, `hex-line` falls back to standard behavior silently.
 - `better-sqlite3` is optional. If it is unavailable, `hex-line` still works without graph hints.
 - `edit_file` reports **Call impact**, not full semantic blast radius. The warning uses call-graph callers only.
 
@@ -160,7 +148,7 @@ Use `replace_between` inside `edit_file` when you know stable start/end anchors
 
 ### Literal rename / refactor
 
-Use `bulk_replace` for text rename patterns across one or more files. Do not use it as a substitute for structured block rewrites.
+Use `bulk_replace` for text rename patterns across one or more files. Returns compact summary by default; pass `format: "full"` for capped diffs. Do not use it as a substitute for structured block rewrites.
 
 ### read_file
 

package/dist/hook.mjs

@@ -91,13 +91,13 @@ var BINARY_EXT = /* @__PURE__ */ new Set([
 ]);
 var REVERSE_TOOL_HINTS = {
   "mcp__hex-line__read_file": "Read (file_path, offset, limit)",
-  "mcp__hex-line__edit_file": "Edit (revision-aware hash edits, block rewrite, auto-rebase)",
+  "mcp__hex-line__edit_file": "Edit (old_string, new_string, replace_all)",
   "mcp__hex-line__write_file": "Write (file_path, content)",
   "mcp__hex-line__grep_search": "Grep (pattern, path)",
   "mcp__hex-line__directory_tree": "Glob (pattern) or Bash(ls)",
   "mcp__hex-line__get_file_info": "Bash(stat/wc)",
   "mcp__hex-line__outline": "Read with offset/limit",
-  "mcp__hex-line__verify": "Verify held checksums / revision without reread",
+  "mcp__hex-line__verify": "Read (re-read file to check freshness)",
   "mcp__hex-line__changes": "Bash(git diff)",
   "mcp__hex-line__bulk_replace": "Edit (text rename/refactor across files)",
   "mcp__hex-line__setup_hooks": "Not available (hex-line disabled)"
@@ -114,10 +114,10 @@ var TOOL_HINTS = {
   stat: "mcp__hex-line__get_file_info (not stat/wc/file)",
   grep: "mcp__hex-line__grep_search (not grep/rg). Params: output, literal, context_before, context_after, multiline",
   sed: "mcp__hex-line__edit_file for hash edits, or mcp__hex-line__bulk_replace for text rename (not sed -i)",
-  diff: "mcp__hex-line__changes (not diff). Git-based semantic diff",
+  diff: "mcp__hex-line__changes (not diff). Git diff with change symbols",
   outline: "mcp__hex-line__outline (before reading large code files)",
   verify: "mcp__hex-line__verify (staleness / revision check without re-read)",
-  changes: "mcp__hex-line__changes (semantic AST diff)",
+  changes: "mcp__hex-line__changes (git diff with change symbols)",
   bulk: "mcp__hex-line__bulk_replace (multi-file search-replace)",
   setup: "mcp__hex-line__setup_hooks (configure hooks for agents)"
 };

package/dist/server.mjs

@@ -6,7 +6,7 @@ import { dirname as dirname4 } from "node:path";
 import { z as z2 } from "zod";
 
 // ../hex-common/src/runtime/mcp-bootstrap.mjs
-async function createServerRuntime({ name, version: version2, installDir }) {
+async function createServerRuntime({ name, version: version2 }) {
   let McpServer, StdioServerTransport2;
   try {
     ({ McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js"));
@@ -14,11 +14,16 @@ async function createServerRuntime({ name, version: version2, installDir }) {
   } catch {
     process.stderr.write(
       `${name}: @modelcontextprotocol/sdk not found.
-Run: cd ${installDir} && npm install
+Run: npm install @modelcontextprotocol/sdk
 `
     );
     process.exit(1);
   }
+  const shutdown = () => {
+    process.exit(0);
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
   return {
     server: new McpServer({ name, version: version2 }),
     StdioServerTransport: StdioServerTransport2
@@ -250,6 +255,8 @@ function listDirectory(dirPath, opts = {}) {
 }
 var MAX_OUTPUT_CHARS = 8e4;
 var MAX_DIFF_CHARS = 3e4;
+var MAX_BULK_OUTPUT_CHARS = 3e4;
+var MAX_PER_FILE_DIFF_LINES = 50;
 function readText(filePath) {
   return readFileSync(filePath, "utf-8").replace(/\r\n/g, "\n");
 }
@@ -340,7 +347,7 @@ function getGraphDB(filePath) {
   try {
     const projectRoot = findProjectRoot(filePath);
     if (!projectRoot) return null;
-    const dbPath = join3(projectRoot, ".codegraph", "index.db");
+    const dbPath = join3(projectRoot, ".hex-skills/codegraph", "index.db");
     if (!existsSync2(dbPath)) return null;
     if (_dbs.has(dbPath)) return _dbs.get(dbPath);
     const require2 = createRequire(import.meta.url);
@@ -454,7 +461,7 @@ function getRelativePath(filePath) {
 function findProjectRoot(filePath) {
   let dir = dirname2(filePath);
   for (let i = 0; i < 10; i++) {
-    if (existsSync2(join3(dir, ".codegraph", "index.db"))) return dir;
+    if (existsSync2(join3(dir, ".hex-skills/codegraph", "index.db"))) return dir;
     const parent = dirname2(dir);
     if (parent === dir) break;
     dir = parent;
@@ -1964,19 +1971,18 @@ function fileInfo(filePath) {
 }
 
 // lib/setup.mjs
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync5, mkdirSync } from "node:fs";
-import { resolve as resolve6, dirname as dirname3 } from "node:path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync5, mkdirSync, copyFileSync } from "node:fs";
+import { resolve as resolve6, dirname as dirname3, join as join5 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+var STABLE_HOOK_DIR = resolve6(homedir(), ".claude", "hex-line");
+var STABLE_HOOK_PATH = join5(STABLE_HOOK_DIR, "hook.mjs").replace(/\\/g, "/");
+var HOOK_COMMAND = `node ${STABLE_HOOK_PATH}`;
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname3(__filename);
-var HOOK_SCRIPT = resolve6(__dirname, "..", "hook.mjs").replace(/\\/g, "/");
-var HOOK_COMMAND = `node ${HOOK_SCRIPT}`;
-var HOOK_SIGNATURE = "hex-line-mcp/hook.mjs";
-var NPX_MARKERS = ["_npx", "npx-cache", ".npm/_npx"];
-function isEphemeralInstall(scriptPath) {
-  return NPX_MARKERS.some((m) => scriptPath.includes(m));
-}
+var SOURCE_HOOK = resolve6(__dirname, "..", "hook.mjs");
+var DIST_HOOK = resolve6(__dirname, "hook.mjs");
+var HOOK_SIGNATURE = "hex-line";
 var CLAUDE_HOOKS = {
   SessionStart: {
     matcher: "*",
@@ -2038,7 +2044,7 @@ function writeHooksToFile(settingsPath, label) {
     return `Claude (${label}): already configured`;
   }
   writeJson(settingsPath, config);
-  return `Claude (${label}): hooks -> ${HOOK_SCRIPT} OK`;
+  return `Claude (${label}): hooks -> ${STABLE_HOOK_PATH} OK`;
 }
 function cleanLocalHooks() {
   const localPath = resolve6(process.cwd(), ".claude/settings.local.json");
@@ -2084,10 +2090,14 @@ function installOutputStyle() {
   return msg;
 }
 function setupClaude() {
-  if (isEphemeralInstall(HOOK_SCRIPT)) {
-    return "Claude: SKIPPED \u2014 hook.mjs is in npx cache (ephemeral). Install permanently: npm i -g @levnikolaevich/hex-line-mcp, then re-run setup_hooks.";
-  }
   const results = [];
+  const hookSource = existsSync5(DIST_HOOK) ? DIST_HOOK : SOURCE_HOOK;
+  if (!existsSync5(hookSource)) {
+    return "Claude: FAILED \u2014 hook.mjs not found. Reinstall @levnikolaevich/hex-line-mcp.";
+  }
+  mkdirSync(STABLE_HOOK_DIR, { recursive: true });
+  copyFileSync(hookSource, STABLE_HOOK_PATH);
+  results.push(`hook.mjs -> ${STABLE_HOOK_PATH}`);
   const globalPath = resolve6(homedir(), ".claude/settings.json");
   results.push(writeHooksToFile(globalPath, "global"));
   results.push(cleanLocalHooks());
@@ -2266,7 +2276,7 @@ Summary: ${summary}`);
 
 // lib/bulk-replace.mjs
 import { writeFileSync as writeFileSync3, readdirSync as readdirSync3 } from "node:fs";
-import { resolve as resolve7, relative as relative3, join as join5 } from "node:path";
+import { resolve as resolve7, relative as relative3, join as join6 } from "node:path";
 var ignoreMod;
 try {
   ignoreMod = await import("ignore");
@@ -2282,7 +2292,7 @@ function walkFiles(dir, rootDir, ig) {
   }
   for (const e of entries) {
     if (e.name === ".git" || e.name === "node_modules") continue;
-    const full = join5(dir, e.name);
+    const full = join6(dir, e.name);
     const rel = relative3(rootDir, full).replace(/\\/g, "/");
     if (ig && ig.ignores(rel)) continue;
     if (e.isDirectory()) {
@@ -2294,21 +2304,21 @@ function walkFiles(dir, rootDir, ig) {
   return results;
 }
 function globMatch(filename, pattern) {
-  const re = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, ".*").replace(/\?/g, ".");
+  const re = pattern.replace(/\./g, "\\.").replace(/\{([^}]+)\}/g, (_, alts) => "(" + alts.split(",").join("|") + ")").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, ".*").replace(/\?/g, ".");
   return new RegExp("^" + re + "$").test(filename);
 }
 function loadGitignore2(rootDir) {
   if (!ignoreMod) return null;
   const ig = (ignoreMod.default || ignoreMod)();
   try {
-    const content = readText(join5(rootDir, ".gitignore"));
+    const content = readText(join6(rootDir, ".gitignore"));
     ig.add(content);
   } catch {
   }
   return ig;
 }
 function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
-  const { dryRun = false, maxFiles = 100 } = opts;
+  const { dryRun = false, maxFiles = 100, format = "compact" } = opts;
   const abs = resolve7(normalizePath(rootDir));
   const ig = loadGitignore2(abs);
   const allFiles = walkFiles(abs, abs, ig);
@@ -2321,51 +2331,63 @@ function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
     return `TOO_MANY_FILES: Found ${files.length} files, max_files is ${maxFiles}. Use more specific glob or increase max_files.`;
   }
   const results = [];
-  let changed = 0, skipped = 0, errors = 0;
-  const MAX_OUTPUT2 = MAX_OUTPUT_CHARS;
-  let totalChars = 0;
+  let changed = 0, skipped = 0, errors = 0, totalReplacements = 0;
   for (const file of files) {
     try {
       const original = readText(file);
       let content = original;
+      let replacementCount = 0;
       for (const { old: oldText, new: newText } of replacements) {
-        content = content.split(oldText).join(newText);
+        if (oldText === newText) continue;
+        const parts = content.split(oldText);
+        replacementCount += parts.length - 1;
+        content = parts.join(newText);
       }
       if (content === original) {
         skipped++;
         continue;
       }
-      const diff = simpleDiff(original.split("\n"), content.split("\n"));
       if (!dryRun) {
         writeFileSync3(file, content, "utf-8");
       }
-      const relPath = file.replace(abs, "").replace(/^[/\\]/, "");
-      results.push(`--- ${relPath}
-${diff || "(no visible diff)"}`);
+      const relPath = relative3(abs, file).replace(/\\/g, "/");
+      totalReplacements += replacementCount;
       changed++;
-      totalChars += results[results.length - 1].length;
-      if (totalChars > MAX_OUTPUT2) {
-        const remaining = files.length - files.indexOf(file) - 1;
-        if (remaining > 0) results.push(`OUTPUT_CAPPED: ${remaining} more files not shown. Output exceeded ${MAX_OUTPUT2} chars.`);
-        break;
+      if (format === "full") {
+        const diff = simpleDiff(original.split("\n"), content.split("\n"));
+        let diffText = diff || "(no visible diff)";
+        const diffLines3 = diffText.split("\n");
+        if (diffLines3.length > MAX_PER_FILE_DIFF_LINES) {
+          const omitted = diffLines3.length - MAX_PER_FILE_DIFF_LINES;
+          diffText = diffLines3.slice(0, MAX_PER_FILE_DIFF_LINES).join("\n") + `
+--- ${omitted} lines omitted ---`;
+        }
+        results.push(`--- ${relPath}: ${replacementCount} replacements
+${diffText}`);
+      } else {
+        results.push(`--- ${relPath}: ${replacementCount} replacements`);
       }
     } catch (e) {
       results.push(`ERROR: ${file}: ${e.message}`);
       errors++;
     }
   }
-  const header = `Bulk replace: ${changed} files changed, ${skipped} skipped, ${errors} errors (dry_run: ${dryRun})`;
-  return results.length ? `${header}
+  const header = `Bulk replace: ${changed} files changed (${totalReplacements} replacements), ${skipped} skipped, ${errors} errors (dry_run: ${dryRun})`;
+  let output = results.length ? `${header}
 
 ${results.join("\n\n")}` : header;
+  if (output.length > MAX_BULK_OUTPUT_CHARS) {
+    output = output.slice(0, MAX_BULK_OUTPUT_CHARS) + `
+OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
+  }
+  return output;
 }
 
 // server.mjs
-var version = true ? "1.3.6" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.4.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
-  version,
-  installDir: "mcp/hex-line-mcp"
+  version
 });
 var replacementPairsSchema = z2.array(
   z2.object({ old: z2.string().min(1), new: z2.string() })
@@ -2645,13 +2667,14 @@ server.registerTool("changes", {
 });
 server.registerTool("bulk_replace", {
   title: "Bulk Replace",
-  description: "Search-and-replace across multiple files. Finds files by glob, applies ordered text replacements, returns per-file diffs. Use dry_run:true to preview. For single-file rename, set glob to the filename.",
+  description: "Search-and-replace across multiple files. Finds files by glob, applies ordered text replacements. Default format is compact (summary only); use format:'full' for capped diffs. Use dry_run:true to preview. For single-file rename, set glob to the filename.",
   inputSchema: z2.object({
     replacements: z2.union([z2.string(), replacementPairsSchema]).describe('JSON array of {old, new} pairs: [{"old":"foo","new":"bar"}]'),
     glob: z2.string().optional().describe('File glob (default: "**/*.{md,mjs,json,yml,ts,js}")'),
     path: z2.string().optional().describe("Root directory (default: cwd)"),
     dry_run: flexBool().describe("Preview without writing (default: false)"),
-    max_files: flexNum().describe("Max files to process (default: 100)")
+    max_files: flexNum().describe("Max files to process (default: 100)"),
+    format: z2.enum(["compact", "full"]).optional().describe('"compact" (default) = summary only, "full" = include capped diffs')
   }),
   annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false }
 }, async (rawParams) => {
@@ -2669,7 +2692,7 @@ server.registerTool("bulk_replace", {
       params.path || process.cwd(),
       params.glob || "**/*.{md,mjs,json,yml,ts,js}",
       replacements,
-      { dryRun: params.dry_run || false, maxFiles: params.max_files || 100 }
+      { dryRun: params.dry_run || false, maxFiles: params.max_files || 100, format: params.format }
     );
     return { content: [{ type: "text", text: result }] };
   } catch (e) {

package/output-style.md

@@ -12,15 +12,17 @@ keep-coding-instructions: true
 |-----------|-----|-----|
 | Read | `mcp__hex-line__read_file` | Hash-annotated, revision-aware |
 | Edit | `mcp__hex-line__edit_file` | Hash-verified anchors + conservative auto-rebase |
-| Write | `mcp__hex-line__write_file` | Consistent workflow |
+| Write | `mcp__hex-line__write_file` | No prior Read needed |
 | Grep | `mcp__hex-line__grep_search` | Hash-annotated matches |
 | Edit (text rename) | `mcp__hex-line__bulk_replace` | Multi-file text rename/refactor |
+| Bash `find`/`tree` | `mcp__hex-line__directory_tree` | Pattern search, gitignore-aware |
 
 ## Efficient File Reading
 
 For UNFAMILIAR code files >100 lines, PREFER:
-1. `outline` first (10-20 lines of structure)
+1. `outline` first (code files only — not .md/.json/.yaml)
 2. `read_file` with offset/limit for the specific section you need
+3. Batch: `paths` array reads multiple files in one call
 
 Avoid reading a large file in full — outline+targeted read saves 75% tokens.
 
@@ -33,7 +35,7 @@ Prefer:
 1. collect all known hunks for one file
 2. send one `edit_file` call with batched edits
 3. carry `revision` from `read_file` into `base_revision` on follow-up edits
-4. use `replace_between` for large block rewrites
+4. edit types: `set_line` (1 line), `replace_lines` (range + checksum), `insert_after`, `replace_between` (large blocks)
 5. use `verify` before rereading a file after staleness
 
 Avoid:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.3.6",
+  "version": "1.4.0",
   "mcpName": "io.github.levnikolaevich/hex-line-mcp",
   "type": "module",
   "description": "Hash-verified file editing MCP + token efficiency hook for AI coding agents. 11 tools: read, edit, write, grep, outline, verify, directory_tree, file_info, setup_hooks, changes, bulk_replace.",
@@ -28,7 +28,7 @@
   "_dep_notes": {
     "web-tree-sitter": "Pinned ^0.25.0: v0.26 ABI incompatible with tree-sitter-wasms 0.1.x (built with tree-sitter-cli 0.20.8). Language.load() silently fails.",
     "zod": "Pinned ^3.25.0: zod 4 breaks zod-to-json-schema (used by MCP SDK internally). Tool parameter descriptions not sent to clients. Revisit when MCP SDK switches to z.toJSONSchema().",
-    "better-sqlite3": "Optional. Used only by lib/graph-enrich.mjs for readonly access to hex-graph .codegraph/index.db. Graceful fallback if absent."
+    "better-sqlite3": "Optional. Used only by lib/graph-enrich.mjs for readonly access to hex-graph .hex-skills/codegraph/index.db. Graceful fallback if absent."
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",