@levnikolaevich/hex-line-mcp 1.4.0 → 1.5.0

package/README.md

@@ -32,10 +32,10 @@ Advanced / occasional:
 
 | Tool | Description | Key Feature |
 |------|-------------|-------------|
-| `read_file` | Read file with hash-annotated lines, checksums, and revision | Partial reads via `offset`/`limit` |
+| `read_file` | Read file with hash-annotated lines, checksums, and revision | Partial reads via `offset`/`limit` or `ranges`, compact output by default |
 | `edit_file` | Revision-aware anchor edits (`set_line`, `replace_lines`, `insert_after`, `replace_between`) | Batched same-file edits + conservative auto-rebase |
 | `write_file` | Create new file or overwrite, auto-creates parent dirs | Path validation, no hash overhead |
-| `grep_search` | Search with ripgrep, 3 output modes, per-group checksums | Edit-ready: grep -> edit directly with checksums |
+| `grep_search` | Search with ripgrep, 3 output modes, per-group checksums | Plain `files`/`count`, compact edit-ready `content` |
 | `outline` | AST-based structural overview via tree-sitter WASM | 95% token reduction (10 lines instead of 500) |
 | `verify` | Check if held checksums / revision are still current | Staleness check without full re-read |
 | `directory_tree` | Compact directory tree with root .gitignore support | Skips node_modules/.git, shows file sizes |
@@ -48,10 +48,10 @@ Advanced / occasional:
 
 | Event | Trigger | Action |
 |-------|---------|--------|
-| **PreToolUse** | Read/Edit/Write/Grep on text files | Blocks built-in, forces hex-line tools |
+| **PreToolUse** | Read/Edit/Write/Grep on text files | Size-aware redirect: cheap small operations may pass, expensive ones are redirected |
 | **PreToolUse** | Bash with dangerous commands | Blocks `rm -rf /`, `git push --force`, etc. Agent must confirm with user |
 | **PostToolUse** | Bash with 50+ lines output | RTK: deduplicates, truncates, shows filtered summary to Claude as feedback |
-| **SessionStart** | Session begins | Injects full tool preference list into agent context |
+| **SessionStart** | Session begins | Injects a short no-discovery workflow for hex-line tools |
 
 
 ### Bash Redirects
@@ -90,17 +90,17 @@ The `setup_hooks` tool automatically installs the output style to `~/.claude/out
 
 ## Benchmarking
 
-Two-tier benchmark architecture:
+Two benchmark layers:
 
-- `/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)
+- `/benchmark-compare` — balanced built-in vs hex-line comparison inside Claude Code, validated by scenario manifests and saved diffs
+- `npm run benchmark` — hex-line standalone workflow metrics (Node.js, all real library calls, no simulations)
 
 ```bash
 npm run benchmark -- --repo /path/to/repo
 npm run benchmark:diagnostic -- --repo /path/to/repo
 ```
 
-Current hex-line workflow metrics on the `hex-line-mcp` repo (all real library calls):
+Current standalone workflow metrics on the `hex-line-mcp` repo (all real library calls):
 
 | # | Workflow | Hex-line output | Ops |
 |---|----------|---------:|----:|
@@ -110,7 +110,7 @@ Current hex-line workflow metrics on the `hex-line-mcp` repo (all real library c
 | W4 | Inspect large smoke test before edit | 2,322 chars | 3 |
 | W5 | Follow-up edit after unrelated line shift | 1,267 chars | 3 |
 
-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.
+Workflow total: `6,403` chars across `12` ops. Run `/benchmark-compare` for the balanced scenario suite with activation checks and diff-based correctness.
 
 ### Optional Graph Enrichment
 
@@ -152,7 +152,7 @@ Use `bulk_replace` for text rename patterns across one or more files. Returns co
 
 ### read_file
 
-Read a file with FNV-1a hash-annotated lines, range checksums, file checksum, and revision. Supports directory listing.
+Read a file with FNV-1a hash-annotated lines, range checksums, file checksum, and revision. Supports batch reads, multi-range reads, and directory listing.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -160,17 +160,22 @@ Read a file with FNV-1a hash-annotated lines, range checksums, file checksum, an
 | `paths` | string[] | no | Array of file paths to read (batch mode) |
 | `offset` | number | no | Start line, 1-indexed (default: 1) |
 | `limit` | number | no | Max lines to return (default: 2000, 0 = all) |
+| `ranges` | array | no | Explicit line ranges, e.g. `[{ "start": 10, "end": 30 }]` |
+| `include_graph` | boolean | no | Opt in to graph annotations when the graph index exists |
 | `plain` | boolean | no | Omit hashes, output `lineNum\|content` instead |
 
-Output format:
+Default output is compact:
 
 ```
+File: lib/search.mjs
+meta: lines 1-20 of 282
+revision: rev-12-a1b2c3d4
+file: 1-282:beefcafe
+
 ab.1    import { resolve } from "node:path";
 cd.2    import { readFileSync } from "node:fs";
 ...
 checksum: 1-50:f7e2a1b0
-revision: rev-12-a1b2c3d4
-file: 1-120:beefcafe
 ```
 
 ### edit_file
@@ -203,6 +208,7 @@ Result footer includes:
 - `revision: ...`
 - `file: ...`
 - `changed_ranges: ...` when relevant
+- `remapped_refs: ...` when stale anchors were uniquely relocated
 - `retry_checksum: ...` on local conflicts
 
 ### write_file
@@ -216,7 +222,7 @@ Create a new file or overwrite an existing one. Creates parent directories autom
 
 ### grep_search
 
-Search file contents using ripgrep. Three output modes: `content` (hash-annotated with checksums), `files` (paths only), `count` (match counts).
+Search file contents using ripgrep. Three output modes: `content` (hash-annotated with checksums), `files` (plain path list), `count` (plain `file:count` list).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -236,7 +242,7 @@ Search file contents using ripgrep. Three output modes: `content` (hash-annotate
 | `total_limit` | number | no | Total match events across all files; multiline matches count as 1 (0 = unlimited) |
 | `plain` | boolean | no | Omit hash tags, return `file:line:content` |
 
-**Content mode** returns per-group checksums enabling direct `replace_lines` from grep results without intermediate `read_file`.
+`content` mode returns per-group checksums enabling direct `replace_lines` from grep results without intermediate `read_file`.
 
 ### outline
 
@@ -257,7 +263,7 @@ Check if range checksums from a prior read are still valid, optionally relative
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | string | yes | File path |
-| `checksums` | string | yes | JSON array of checksum strings, e.g. `["1-50:f7e2a1b0"]` |
+| `checksums` | string[] | yes | Array of checksum strings, e.g. `["1-50:f7e2a1b0"]` |
 | `base_revision` | string | no | Prior revision to compare against latest state |
 
 Returns a single-line confirmation or lists changed ranges.
@@ -318,7 +324,7 @@ Configuration constants in `hook.mjs`:
 
 ### SessionStart: Tool Preferences
 
-Injects hex-line tool preference list into agent context at session start.
+Injects a short operational workflow into agent context at session start: no `ToolSearch`, prefer `outline -> read_file -> edit_file -> verify`, and use targeted reads over full-file reads.
 
 ## Architecture
 

package/dist/hook.mjs

@@ -54,7 +54,7 @@ function normalizeOutput(text, opts = {}) {
 }
 
 // hook.mjs
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -183,10 +183,31 @@ var CMD_PATTERNS = [
 var LINE_THRESHOLD = 50;
 var HEAD_LINES = 15;
 var TAIL_LINES = 15;
+var LARGE_FILE_BYTES = 15 * 1024;
+var LARGE_EDIT_CHARS = 1200;
 function extOf(filePath) {
   const dot = filePath.lastIndexOf(".");
   return dot !== -1 ? filePath.slice(dot).toLowerCase() : "";
 }
+function getFilePath(toolInput) {
+  return toolInput.file_path || toolInput.path || "";
+}
+function resolveToolPath(filePath) {
+  if (!filePath) return "";
+  if (filePath.startsWith("~/")) return resolve(homedir(), filePath.slice(2));
+  return resolve(process.cwd(), filePath);
+}
+function getFileSize(filePath) {
+  if (!filePath) return null;
+  try {
+    return statSync(resolveToolPath(filePath)).size;
+  } catch {
+    return null;
+  }
+}
+function isPartialRead(toolInput) {
+  return [toolInput.offset, toolInput.limit, toolInput.start_line, toolInput.end_line, toolInput.ranges].some((value) => value !== void 0 && value !== null && value !== "");
+}
 function detectCommandType(cmd) {
   for (const [re, type] of CMD_PATTERNS) {
     if (re.test(cmd)) return type;
@@ -249,7 +270,8 @@ function handlePreToolUse(data) {
   }
   const hintKey = TOOL_REDIRECT_MAP[toolName];
   if (hintKey) {
-    const filePath = toolInput.file_path || toolInput.path || "";
+    const filePath = getFilePath(toolInput);
+    const fileSize = getFileSize(filePath);
     if (BINARY_EXT.has(extOf(filePath))) {
       process.exit(0);
     }
@@ -272,10 +294,30 @@ function handlePreToolUse(data) {
         process.exit(0);
       }
     }
-    const hint = TOOL_HINTS[hintKey];
-    const toolName2 = hint.split(" (")[0];
-    const pathNote = filePath ? ` with path="${filePath}"` : "";
-    block(`Use ${toolName2}${pathNote}`, hint);
+    if (toolName === "Read") {
+      if (isPartialRead(toolInput) || fileSize !== null && fileSize <= LARGE_FILE_BYTES) {
+        process.exit(0);
+      }
+      const target = filePath ? `Use mcp__hex-line__outline or mcp__hex-line__read_file with path="${filePath}"` : "Use mcp__hex-line__directory_tree or mcp__hex-line__read_file";
+      block(target, "For large or unknown full reads: call outline first, then read_file with offset/limit or ranges. Do not use built-in Read here.");
+    }
+    if (toolName === "Edit") {
+      const oldText = String(toolInput.old_string || "");
+      const isLargeEdit = Boolean(toolInput.replace_all) || oldText.length > LARGE_EDIT_CHARS || fileSize !== null && fileSize > LARGE_FILE_BYTES;
+      if (!isLargeEdit) {
+        process.exit(0);
+      }
+      const target = filePath ? `Use mcp__hex-line__grep_search or mcp__hex-line__read_file, then mcp__hex-line__edit_file with path="${filePath}"` : "Use mcp__hex-line__grep_search or mcp__hex-line__read_file, then mcp__hex-line__edit_file";
+      block(target, "For large or repeated edits: locate anchors/checksums first, then call edit_file once with batched edits.");
+    }
+    if (toolName === "Write") {
+      const pathNote = filePath ? ` with path="${filePath}"` : "";
+      block(`Use mcp__hex-line__write_file${pathNote}`, TOOL_HINTS.Write);
+    }
+    if (toolName === "Grep") {
+      const pathNote = filePath ? ` with path="${filePath}"` : "";
+      block(`Use mcp__hex-line__grep_search${pathNote}`, TOOL_HINTS.Grep);
+    }
   }
   if (toolName === "Bash") {
     const command = (toolInput.command || "").trim();
@@ -381,22 +423,8 @@ function handleSessionStart() {
     } catch {
     }
   }
-  if (styleActive) {
-    process.stdout.write(JSON.stringify({ systemMessage: "hex-line Output Style active." }));
-    process.exit(0);
-  }
-  const seen = /* @__PURE__ */ new Set();
-  const lines = [];
-  for (const hint of Object.values(TOOL_HINTS)) {
-    const tool = hint.split(" ")[0];
-    if (!seen.has(tool)) {
-      seen.add(tool);
-      lines.push(`- ${hint}`);
-    }
-  }
-  lines.push("Exceptions: images, PDFs, notebooks, .claude/settings.json, .claude/settings.local.json \u2192 built-in Read; Glob always OK");
-  lines.push("Bash OK for: npm/node/git/docker/curl, pipes, scripts");
-  const msg = "Hex-line MCP available. Workflow:\n- Discovery: read_file, grep_search, outline, directory_tree\n- Same-file edits: prefer ONE edit_file call per file, carry revision/base_revision\n- Hash edits: edit_file (set_line, replace_lines, insert_after, replace_between)\n- Large rewrites: replace_between instead of reciting old blocks\n- Text rename: bulk_replace (multi-file search-replace)\n- Verify staleness: verify before considering reread\n- Write new: write_file\n" + lines.join("\n");
+  const prefix = styleActive ? "Hex-line MCP available. Output style active.\n" : "Hex-line MCP available.\n";
+  const msg = prefix + "Call hex-line tools directly. Do not use ToolSearch for hex-line tools.\nWorkflow:\n- Discovery: outline for large code files, read_file for targeted reads, grep_search for symbol/text lookup\n- Read cheaply: prefer offset/limit or ranges; avoid full-file Read on large files\n- Edit safely: read/grep first, then one batched edit_file call per file with base_revision when available\n- Verify before reread: use verify to check checksums or revision freshness\n- Multi-file rename/refactor: use bulk_replace\n- New files: use write_file\nExceptions: images, PDFs, notebooks, .claude/settings.json, .claude/settings.local.json use built-in Read. Glob is always OK.";
   process.stdout.write(JSON.stringify({ systemMessage: msg }));
   process.exit(0);
 }

package/dist/server.mjs

@@ -669,6 +669,24 @@ function buildRangeChecksum(snapshot, startLine, endLine) {
 
 // lib/read.mjs
 var DEFAULT_LIMIT = 2e3;
+function parseRangeEntry(entry, total) {
+  if (typeof entry === "string") {
+    const match = entry.trim().match(/^(\d+)(?:-(\d*)?)?$/);
+    if (!match) throw new Error(`Invalid range "${entry}". Use "10", "10-25", or "10-"`);
+    const start2 = Number(match[1]);
+    const end2 = match[2] === void 0 || match[2] === "" ? total : Number(match[2]);
+    return { start: start2, end: end2 };
+  }
+  if (!entry || typeof entry !== "object") {
+    throw new Error("ranges entries must be strings or {start,end} objects");
+  }
+  const start = Number(entry.start ?? 1);
+  const end = entry.end === void 0 || entry.end === null ? total : Number(entry.end);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    throw new Error("ranges entries must contain numeric start/end values");
+  }
+  return { start, end };
+}
 function readFile2(filePath, opts = {}) {
   filePath = normalizePath(filePath);
   const real = validatePath(filePath);
@@ -686,10 +704,13 @@ ${text}
   const total = lines.length;
   let ranges;
   if (opts.ranges && opts.ranges.length > 0) {
-    ranges = opts.ranges.map((r) => ({
-      start: Math.max(1, r.start || 1),
-      end: Math.min(total, r.end || total)
-    }));
+    ranges = opts.ranges.map((entry) => {
+      const parsed = parseRangeEntry(entry, total);
+      return {
+        start: Math.max(1, parsed.start),
+        end: Math.min(total, parsed.end)
+      };
+    });
   } else {
     const startLine = Math.max(1, opts.offset || 1);
     const maxLines = opts.limit && opts.limit > 0 ? opts.limit : DEFAULT_LIMIT;
@@ -719,24 +740,22 @@ ${text}
     range.end = actualEnd;
     parts.push(formatted.join("\n"));
     const cs = rangeChecksum(lineHashes, range.start, actualEnd);
-    parts.push(`
-checksum: ${cs}`);
+    parts.push(`checksum: ${cs}`);
     if (cappedAtLine) break;
   }
   const sizeKB = (stat.size / 1024).toFixed(1);
-  const mtime = stat.mtime;
-  const ago = relativeTime(mtime);
-  let header = `File: ${filePath} (${total} lines, ${sizeKB}KB, ${ago})`;
+  const ago = relativeTime(stat.mtime);
+  let meta = `${total} lines, ${sizeKB}KB, ${ago}`;
   if (ranges.length === 1) {
     const r = ranges[0];
     if (r.start > 1 || r.end < total) {
-      header += ` [showing ${r.start}-${r.end}]`;
+      meta += `, showing ${r.start}-${r.end}`;
     }
     if (r.end < total) {
-      header += ` (${total - r.end} more below)`;
+      meta += `, ${total - r.end} more below`;
     }
   }
-  const db = getGraphDB(real);
+  const db = opts.includeGraph ? getGraphDB(real) : null;
   const relFile = db ? getRelativePath(real) : null;
   let graphLine = "";
   if (db && relFile) {
@@ -750,18 +769,12 @@ checksum: ${cs}`);
 Graph: ${items.join(" | ")}`;
     }
   }
-  let result = `${header}${graphLine}
+  let result = `File: ${filePath}${graphLine}
+meta: ${meta}
 revision: ${snapshot.revision}
 file: ${snapshot.fileChecksum}
 
-\`\`\`
-${parts.join("\n")}
-\`\`\``;
-  if (total > 200 && (!opts.offset || opts.offset <= 1) && !cappedAtLine) {
-    result += `
-
-\u26A1 Tip: This file has ${total} lines. Use outline first, then read_file with offset/limit for 75% fewer tokens.`;
-  }
+${parts.join("\n\n")}`;
   if (cappedAtLine) {
     result += `
 
@@ -794,6 +807,26 @@ function buildErrorSnippet(lines, centerIdx, radius = 5) {
   }).join("\n");
   return { start: start + 1, end, text };
 }
+function stripAnchorOrDiffPrefix(line) {
+  let next = line;
+  next = next.replace(/^\s*(?:>>|  )?[a-z2-7]{2}\.\d+\t/, "");
+  next = next.replace(/^.+:(?:>>|  )[a-z2-7]{2}\.\d+\t/, "");
+  next = next.replace(/^[ +-]\d+\|\s?/, "");
+  return next;
+}
+function sanitizeEditText(text) {
+  const original = String(text ?? "");
+  const hadTrailingNewline = original.endsWith("\n");
+  let lines = original.split("\n");
+  const nonEmpty = lines.filter((line) => line.length > 0);
+  if (nonEmpty.length > 0 && nonEmpty.every((line) => /^\+(?!\+)/.test(line))) {
+    lines = lines.map((line) => line.startsWith("+") && !line.startsWith("++") ? line.slice(1) : line);
+  }
+  lines = lines.map(stripAnchorOrDiffPrefix);
+  let cleaned = lines.join("\n");
+  if (hadTrailingNewline && !cleaned.endsWith("\n")) cleaned += "\n";
+  return cleaned;
+}
 function findLine(lines, lineNum, expectedTag, hashIndex) {
   const idx = lineNum - 1;
   if (idx < 0 || idx >= lines.length) {
@@ -909,6 +942,7 @@ function buildConflictMessage({
   centerIdx,
   changedRanges,
   retryChecksum,
+  remaps,
   details
 }) {
   const safeCenter = Math.max(0, Math.min(lines.length - 1, centerIdx));
@@ -921,6 +955,9 @@ file: ${fileChecksum}`;
 changed_ranges: ${describeChangedRanges(changedRanges)}`;
   if (retryChecksum) msg += `
 retry_checksum: ${retryChecksum}`;
+  if (remaps?.length) msg += `
+remapped_refs:
+${remaps.map(({ from, to }) => `${from} -> ${to}`).join("\n")}`;
   msg += `
 
 ${details}
@@ -955,6 +992,8 @@ function editFile(filePath, edits, opts = {}) {
   const hadTrailingNewline = original.endsWith("\n");
   const hashIndex = currentSnapshot.uniqueTagIndex;
   let autoRebased = false;
+  const remaps = [];
+  const remapKeys = /* @__PURE__ */ new Set();
   const anchored = [];
   for (const e of edits) {
     if (e.set_line || e.replace_lines || e.insert_after || e.replace_between) anchored.push(e);
@@ -1011,12 +1050,24 @@ function editFile(filePath, edits, opts = {}) {
       centerIdx,
       changedRanges: staleRevision && hasBaseSnapshot ? changedRanges : null,
       retryChecksum,
+      remaps,
       details
     });
   };
+  const trackRemap = (ref, idx) => {
+    const actualRef = `${lineTag(fnv1a(lines[idx]))}.${idx + 1}`;
+    const expectedRef = `${ref.tag}.${ref.line}`;
+    if (actualRef === expectedRef) return;
+    const key = `${expectedRef}->${actualRef}`;
+    if (remapKeys.has(key)) return;
+    remapKeys.add(key);
+    remaps.push({ from: expectedRef, to: actualRef });
+  };
   const locateOrConflict = (ref, reason = "stale_anchor") => {
     try {
-      return findLine(lines, ref.line, ref.tag, hashIndex);
+      const idx = findLine(lines, ref.line, ref.tag, hashIndex);
+      trackRemap(ref, idx);
+      return idx;
     } catch (e) {
       if (conflictPolicy !== "conservative" || !staleRevision) throw e;
       const centerIdx = Math.max(0, Math.min(lines.length - 1, ref.line - 1));
@@ -1058,7 +1109,7 @@ function editFile(filePath, edits, opts = {}) {
           lines.splice(idx, 1);
         } else {
           const origLine = [lines[idx]];
-          const raw = String(txt).split("\n");
+          const raw = sanitizeEditText(txt).split("\n");
           const newLines = opts.restoreIndent ? restoreIndent(origLine, raw) : raw;
           lines.splice(idx, 1, ...newLines);
         }
@@ -1070,7 +1121,7 @@ function editFile(filePath, edits, opts = {}) {
         if (typeof idx === "string") return idx;
         const conflict = ensureRevisionContext(idx + 1, idx + 1, idx);
         if (conflict) return conflict;
-        let insertLines = e.insert_after.text.split("\n");
+        let insertLines = sanitizeEditText(e.insert_after.text).split("\n");
         if (opts.restoreIndent) insertLines = restoreIndent([lines[idx]], insertLines);
         lines.splice(idx + 1, 0, ...insertLines);
         continue;
@@ -1134,7 +1185,7 @@ Retry with fresh checksum ${actual}, or use set_line with hashes above.`
           lines.splice(si, ei - si + 1);
         } else {
           const origRange = lines.slice(si, ei + 1);
-          let newLines = String(txt).split("\n");
+          let newLines = sanitizeEditText(txt).split("\n");
           if (opts.restoreIndent) newLines = restoreIndent(origRange, newLines);
           lines.splice(si, ei - si + 1, ...newLines);
         }
@@ -1158,7 +1209,7 @@ Retry with fresh checksum ${actual}, or use set_line with hashes above.`
         const conflict = ensureRevisionContext(targetRange.start, targetRange.end, si);
         if (conflict) return conflict;
         const txt = e.replace_between.new_text;
-        let newLines = String(txt ?? "").split("\n");
+        let newLines = sanitizeEditText(txt ?? "").split("\n");
         const sliceStart = boundaryMode === "exclusive" ? si + 1 : si;
         const removeCount = boundaryMode === "exclusive" ? Math.max(0, ei - si - 1) : ei - si + 1;
         const origRange = lines.slice(sliceStart, sliceStart + removeCount);
@@ -1219,6 +1270,11 @@ file: ${nextSnapshot.fileChecksum}`;
   if (autoRebased && staleRevision && hasBaseSnapshot) {
     msg += `
 changed_ranges: ${describeChangedRanges(changedRanges)}`;
+  }
+  if (remaps.length > 0) {
+    msg += `
+remapped_refs:
+${remaps.map(({ from, to }) => `${from} -> ${to}`).join("\n")}`;
   }
   msg += `
 Updated ${filePath} (${content.split("\n").length} lines)`;
@@ -1334,9 +1390,7 @@ async function filesMode(pattern, target, opts) {
   if (code !== 0 && code !== null) throw new Error(`GREP_ERROR: rg exit ${code} \u2014 ${stderr.trim() || "unknown error"}`);
   const lines = stdout.trimEnd().split("\n").filter(Boolean);
   const normalized = lines.map((l) => l.replace(/\\/g, "/"));
-  return `\`\`\`
-${normalized.join("\n")}
-\`\`\``;
+  return normalized.join("\n");
 }
 async function countMode(pattern, target, opts) {
   const realArgs = ["-c"];
@@ -1353,9 +1407,7 @@ async function countMode(pattern, target, opts) {
   if (code !== 0 && code !== null) throw new Error(`GREP_ERROR: rg exit ${code} \u2014 ${stderr.trim() || "unknown error"}`);
   const lines = stdout.trimEnd().split("\n").filter(Boolean);
   const normalized = lines.map((l) => l.replace(/\\/g, "/"));
-  return `\`\`\`
-${normalized.join("\n")}
-\`\`\``;
+  return normalized.join("\n");
 }
 async function contentMode(pattern, target, opts, plain, totalLimit) {
   const realArgs = ["--json"];
@@ -1462,16 +1514,12 @@ async function contentMode(pattern, target, opts, plain, totalLimit) {
       if (totalLimit > 0 && matchCount >= totalLimit) {
         flushGroup();
         formatted.push(`--- total_limit reached (${totalLimit}) ---`);
-        return `\`\`\`
-${formatted.join("\n")}
-\`\`\``;
+        return formatted.join("\n");
       }
     }
   }
   flushGroup();
-  return `\`\`\`
-${formatted.join("\n")}
-\`\`\``;
+  return formatted.join("\n");
 }
 
 // lib/outline.mjs
@@ -1609,6 +1657,26 @@ function extractOutline(rootNode, config, sourceLines) {
   walk(rootNode, 0);
   return { entries, skippedRanges };
 }
+function fallbackOutline(sourceLines) {
+  const entries = [];
+  for (let index = 0; index < sourceLines.length; index++) {
+    const line = sourceLines[index];
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = trimmed.match(
+      /^(?:export\s+)?(?:async\s+)?function\s+[\w$]+|^(?:export\s+)?(?:const|let|var)\s+[\w$]+\s*=|^(?:export\s+)?class\s+[\w$]+|^(?:export\s+)?interface\s+[\w$]+|^(?:export\s+)?type\s+[\w$]+\s*=|^(?:export\s+)?enum\s+[\w$]+|^(?:export\s+default\s+)?[\w$]+\s*=>/
+    );
+    if (!match) continue;
+    entries.push({
+      start: index + 1,
+      end: index + 1,
+      depth: 0,
+      text: trimmed.slice(0, 120),
+      name: trimmed.match(/([\w$]+)/)?.[1] || null
+    });
+  }
+  return entries;
+}
 async function outlineFromContent(content, ext) {
   const config = LANG_CONFIGS[ext];
   const grammar = grammarForExtension(ext);
@@ -1625,8 +1693,9 @@ async function outlineFromContent(content, ext) {
   const tree = parser.parse(content);
   return extractOutline(tree.rootNode, config, sourceLines);
 }
-function formatOutline(entries, skippedRanges, sourceLineCount, db, relFile) {
+function formatOutline(entries, skippedRanges, sourceLineCount, db, relFile, note = "") {
   const lines = [];
+  if (note) lines.push(note, "");
   if (skippedRanges.length > 0) {
     const first = skippedRanges[0].start;
     const last = skippedRanges[skippedRanges.length - 1].end;
@@ -1652,11 +1721,13 @@ async function fileOutline(filePath) {
   }
   const content = readUtf8Normalized(real);
   const result = await outlineFromContent(content, ext);
+  const entries = result.entries.length > 0 ? result.entries : fallbackOutline(content.split("\n"));
+  const note = result.entries.length > 0 || entries.length === 0 ? "" : "Fallback outline: heuristic symbols shown because parser returned no structural entries.";
   const db = getGraphDB(real);
   const relFile = db ? getRelativePath(real) : null;
   return `File: ${filePath}
 
-${formatOutline(result.entries, result.skippedRanges, content.split("\n").length, db, relFile)}`;
+${formatOutline(entries, result.skippedRanges, content.split("\n").length, db, relFile, note)}`;
 }
 
 // lib/verify.mjs
@@ -2275,7 +2346,7 @@ Summary: ${summary}`);
 }
 
 // lib/bulk-replace.mjs
-import { writeFileSync as writeFileSync3, readdirSync as readdirSync3 } from "node:fs";
+import { writeFileSync as writeFileSync3, readdirSync as readdirSync3, renameSync, unlinkSync } from "node:fs";
 import { resolve as resolve7, relative as relative3, join as join6 } from "node:path";
 var ignoreMod;
 try {
@@ -2348,7 +2419,17 @@ function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
         continue;
       }
       if (!dryRun) {
-        writeFileSync3(file, content, "utf-8");
+        const tempPath = `${file}.hexline-tmp-${process.pid}`;
+        try {
+          writeFileSync3(tempPath, content, "utf-8");
+          renameSync(tempPath, file);
+        } catch (error) {
+          try {
+            unlinkSync(tempPath);
+          } catch {
+          }
+          throw error;
+        }
       }
       const relPath = relative3(abs, file).replace(/\\/g, "/");
       totalReplacements += replacementCount;
@@ -2384,7 +2465,7 @@ OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
 }
 
 // server.mjs
-var version = true ? "1.4.0" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.5.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
   version
@@ -2392,6 +2473,21 @@ var { server, StdioServerTransport } = await createServerRuntime({
 var replacementPairsSchema = z2.array(
   z2.object({ old: z2.string().min(1), new: z2.string() })
 ).min(1);
+var readRangeSchema = z2.union([
+  z2.string(),
+  z2.object({
+    start: flexNum().optional(),
+    end: flexNum().optional()
+  })
+]);
+function parseReadRanges(rawRanges) {
+  if (!rawRanges) return void 0;
+  const parsed = Array.isArray(rawRanges) ? rawRanges : JSON.parse(rawRanges);
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error("ranges must be a non-empty array");
+  }
+  return parsed;
+}
 function coerceEdit(e) {
   if (!e || typeof e !== "object" || Array.isArray(e)) return e;
   if (e.set_line || e.replace_lines || e.insert_after || e.replace_between || e.replace) return e;
@@ -2412,23 +2508,26 @@ function coerceEdit(e) {
 }
 server.registerTool("read_file", {
   title: "Read File",
-  description: "Read a file with hash-annotated lines, range checksums, and current revision. Use offset/limit for targeted reads; use outline first for large code files.",
+  description: "Read file lines with hashes, checksums, and revision metadata.",
   inputSchema: z2.object({
     path: z2.string().optional().describe("File or directory path"),
     paths: z2.array(z2.string()).optional().describe("Array of file paths to read (batch mode)"),
     offset: flexNum().describe("Start line (1-indexed, default: 1)"),
     limit: flexNum().describe("Max lines (default: 2000, 0 = all)"),
+    ranges: z2.union([z2.string(), z2.array(readRangeSchema)]).optional().describe('Line ranges, e.g. ["10-25", {"start":40,"end":55}]'),
+    include_graph: flexBool().describe("Include graph annotations"),
     plain: flexBool().describe("Omit hashes (lineNum|content)")
   }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
 }, async (rawParams) => {
-  const { path: p, paths: multi, offset, limit, plain } = coerceParams(rawParams);
+  const { path: p, paths: multi, offset, limit, ranges: rawRanges, include_graph, plain } = coerceParams(rawParams);
   try {
+    const ranges = parseReadRanges(rawRanges);
     if (multi && multi.length > 0 && !p) {
       const results = [];
       for (const fp of multi) {
         try {
-          results.push(readFile2(fp, { offset, limit, plain }));
+          results.push(readFile2(fp, { offset, limit, ranges, includeGraph: include_graph, plain }));
         } catch (e) {
           results.push(`File: ${fp}
 
@@ -2438,14 +2537,14 @@ ERROR: ${e.message}`);
       return { content: [{ type: "text", text: results.join("\n\n---\n\n") }] };
     }
     if (!p) throw new Error("Either 'path' or 'paths' is required");
-    return { content: [{ type: "text", text: readFile2(p, { offset, limit, plain }) }] };
+    return { content: [{ type: "text", text: readFile2(p, { offset, limit, ranges, includeGraph: include_graph, plain }) }] };
   } catch (e) {
     return { content: [{ type: "text", text: e.message }], isError: true };
   }
 });
 server.registerTool("edit_file", {
   title: "Edit File",
-  description: "Apply revision-aware partial edits to one file. Prefer one batched call per file. Supports set_line, replace_lines, insert_after, and replace_between. For text rename/refactor use bulk_replace.",
+  description: "Apply verified partial edits to one file.",
   inputSchema: z2.object({
     path: z2.string().describe("File to edit"),
     edits: z2.union([z2.string(), z2.array(z2.any())]).describe(
@@ -2504,7 +2603,7 @@ server.registerTool("write_file", {
 });
 server.registerTool("grep_search", {
   title: "Search Files",
-  description: "Search file contents with ripgrep. Returns hash-annotated matches with checksums. Modes: content (default), files, count. Use checksums with set_line/replace_lines. Prefer over shell grep/rg.",
+  description: "Search file contents with ripgrep and return edit-ready matches.",
   inputSchema: z2.object({
     pattern: z2.string().describe("Search pattern (regex by default, literal if literal:true)"),
     path: z2.string().optional().describe("Search dir/file (default: cwd)"),
@@ -2581,19 +2680,20 @@ server.registerTool("outline", {
 });
 server.registerTool("verify", {
   title: "Verify Checksums",
-  description: "Check whether held checksums and optional base_revision are still current, without rereading the file.",
+  description: "Verify held checksums without rereading the file.",
   inputSchema: z2.object({
     path: z2.string().describe("File path"),
-    checksums: z2.string().describe('JSON array of checksum strings, e.g. ["1-50:f7e2a1b0", "51-100:abcd1234"]'),
+    checksums: z2.array(z2.string()).describe('Checksum strings, e.g. ["1-50:f7e2a1b0", "51-100:abcd1234"]'),
     base_revision: z2.string().optional().describe("Optional prior revision to compare against latest state.")
   }),
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
 }, async (rawParams) => {
   const { path: p, checksums, base_revision } = coerceParams(rawParams);
   try {
-    const parsed = JSON.parse(checksums);
-    if (!Array.isArray(parsed)) throw new Error("checksums must be a JSON array of strings");
-    return { content: [{ type: "text", text: verifyChecksums(p, parsed, { baseRevision: base_revision }) }] };
+    if (!Array.isArray(checksums) || checksums.length === 0) {
+      throw new Error("checksums must be a non-empty array of strings");
+    }
+    return { content: [{ type: "text", text: verifyChecksums(p, checksums, { baseRevision: base_revision }) }] };
   } catch (e) {
     return { content: [{ type: "text", text: e.message }], isError: true };
   }
@@ -2667,7 +2767,7 @@ 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. 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.",
+  description: "Search-and-replace across multiple files with compact or full diff output.",
   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}")'),

package/output-style.md

@@ -1,33 +1,33 @@
 ---
 name: hex-line
-description: hex-line MCP tool preferences + explanatory coding style with insights
+description: hex-line MCP tool preferences with compact coding style
 keep-coding-instructions: true
 ---
 
 # MCP Tool Preferences
 
-**PREFER** hex-line MCP for code files — hash-annotated reads enable safe edits:
+**PREFER** hex-line MCP for code files. Hash-annotated reads and verified edits keep context cheap and safe.
 
 | Instead of | Use | Why |
 |-----------|-----|-----|
 | 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` | No prior Read needed |
-| Grep | `mcp__hex-line__grep_search` | Hash-annotated matches |
+| Grep | `mcp__hex-line__grep_search` | Edit-ready 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 (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
+For unfamiliar code files >100 lines, prefer:
+1. `outline` first
+2. `read_file` with `offset`/`limit` or `ranges`
+3. `paths` or `ranges` when batching several targets
 
-Avoid reading a large file in full — outline+targeted read saves 75% tokens.
+Avoid reading a large file in full. Prefer compact, targeted reads.
 
 Bash OK for: npm/node/git/docker/curl, pipes, compound commands.
-**Built-in OK for:** images, PDFs, notebooks, Glob (always), `.claude/settings.json` and `.claude/settings.local.json`.
+**Built-in OK for:** images, PDFs, notebooks, Glob (always), `.claude/settings.json`, `.claude/settings.local.json`.
 
 ## Edit Workflow
 
@@ -35,24 +35,24 @@ 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. 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
+4. use `set_line`, `replace_lines`, `insert_after`, `replace_between` based on scope
+5. use `verify` before rereading after staleness
 
 Avoid:
 - chained same-file `edit_file` calls when all edits are already known
 - full-file rewrites for local changes
 - using `bulk_replace` for structural block rewrites
 
-# Explanatory Style
+# Response Style
 
-Provide educational insights about the codebase alongside task completion. When providing insights, you may exceed typical length constraints, but remain focused and relevant.
+Keep responses compact and operational. Explain only what is needed to complete the task or justify a non-obvious decision.
 
-## Insights
-
-Before and after writing code, provide brief educational explanations about implementation choices using:
-
-"`\u2736 Insight \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`
-[2-3 key educational points]
-`\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`"
+Prefer:
+- short progress updates
+- direct tool calls without discovery chatter
+- concise summaries of edits and verification
 
-Focus on insights specific to the codebase or the code just written, not general programming concepts.
+Avoid:
+- mandatory educational blocks
+- long prose around tool usage
+- repeating obvious implementation details

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.4.0",
+  "version": "1.5.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.",