@levnikolaevich/hex-line-mcp 1.4.0 → 1.6.0

package/README.md

@@ -32,11 +32,11 @@ 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 |
-| `outline` | AST-based structural overview via tree-sitter WASM | 95% token reduction (10 lines instead of 500) |
+| `grep_search` | Search with ripgrep, 3 output modes, per-group checksums | Plain `files`/`count`, compact edit-ready `content` |
+| `outline` | AST-based structural overview with hash anchors via tree-sitter WASM. Supports code (15+ langs) and fence-aware markdown headings | 95% token reduction, direct edit anchors |
 | `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 |
 | `get_file_info` | File metadata without reading content | Size, lines, mtime, type, binary detection |
@@ -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
@@ -88,29 +88,24 @@ mcp__hex-line__setup_hooks(agent="claude")
 
 The `setup_hooks` tool automatically installs the output style to `~/.claude/output-styles/hex-line.md` and activates it if no other style is set. To activate manually: `/config` > Output style > hex-line.
 
-## Benchmarking
+## Validation
 
-Two-tier benchmark architecture:
-
-- `/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)
+Use the normal package checks:
 
 ```bash
-npm run benchmark -- --repo /path/to/repo
-npm run benchmark:diagnostic -- --repo /path/to/repo
+npm test
+npm run lint
+npm run check
 ```
 
-Current hex-line workflow metrics on the `hex-line-mcp` repo (all real library calls):
+Maintainers can also run the internal scenario harness when they want reproducible repo-local workflow regressions:
 
-| # | 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 |
+```bash
+npm run scenarios -- --repo /path/to/repo
+npm run scenarios:diagnostic -- --repo /path/to/repo
+```
 
-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.
+Comparative built-in vs hex-line benchmarks are maintained outside this package.
 
 ### Optional Graph Enrichment
 
@@ -152,7 +147,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 as canonical edit-ready blocks. Each valid range becomes a `read_range` block with absolute span, line entries, and a checksum covering exactly the emitted lines. Invalid ranges become explicit diagnostic blocks. Supports batch reads, multi-range reads, and directory listing.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -160,17 +155,24 @@ 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 but block-structured:
 
 ```
+File: lib/search.mjs
+meta: 282 lines, 10.2KB, 2 hours ago
+revision: rev-12-a1b2c3d4
+file: 1-282:beefcafe
+
+block: read_range
+span: 1-3
 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
+ef.3    ...
+checksum: 1-3:f7e2a1b0
 ```
 
 ### edit_file
@@ -203,6 +205,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 +219,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` (canonical `search_hunk` blocks), `files` (plain path list), `count` (plain `file:count` list).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -234,13 +237,13 @@ Search file contents using ripgrep. Three output modes: `content` (hash-annotate
 | `context_after` | number | no | Context lines AFTER match (`-A`) |
 | `limit` | number | no | Max matches per file (default: 100) |
 | `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` |
+| `plain` | boolean | no | Omit hash tags inside block entries, return `lineNum\|content` |
 
-**Content mode** returns per-group checksums enabling direct `replace_lines` from grep results without intermediate `read_file`.
+`content` mode returns canonical `search_hunk` blocks with per-hunk checksums enabling direct `replace_lines` from grep results without intermediate `read_file`.
 
 ### outline
 
-AST-based structural outline: functions, classes, interfaces with line ranges.
+AST-based structural outline with hash anchors for direct `edit_file` usage. Supports code files (15+ languages) and fence-aware markdown heading navigation (`.md`/`.mdx`). Each entry includes a hash tag for immediate anchor use without intermediate `read_file`.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -248,19 +251,30 @@ AST-based structural outline: functions, classes, interfaces with line ranges.
 
 Supported languages: JavaScript, TypeScript (JSX/TSX), Python, Go, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Bash -- 15+ via tree-sitter WASM.
 
-Not for `.md`, `.json`, `.yaml`, `.txt` -- use `read_file` directly for those.
+Not for `.json`, `.yaml`, `.txt` -- use `read_file` directly for those.
 
 ### verify
 
-Check if range checksums from a prior read are still valid, optionally relative to a prior `base_revision`.
+Check if range checksums from prior read/search blocks are still valid, optionally relative to a prior `base_revision`. Returns a deterministic verification report with `status`, `summary`, and one line per checksum entry.
 
 | 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.
+Example output:
+
+```text
+status: STALE
+revision: rev-17-deadbeef
+file: 1-120:abc123ef
+summary: valid=0 stale=1 invalid=0
+base_revision: rev-16-feedcafe
+changed_ranges: 10-12(replace)
+
+STALE 10-12 checksum: 10-12:oldc0de0 current=10-12:newc0de0
+```
 
 ### directory_tree
 
@@ -318,7 +332,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
 
@@ -392,7 +406,7 @@ The edit is rejected with an error showing which lines changed since the last re
 <details>
 <summary><b>Is outline available for all file types?</b></summary>
 
-Outline works on code files only (15+ languages via tree-sitter WASM). For markdown, JSON, YAML, and text files use `read_file` directly -- these formats don't benefit from structural outline.
+Outline works on code files (15+ languages via tree-sitter WASM) and markdown heading navigation (`.md`/`.mdx`, fenced code blocks ignored). For JSON, YAML, and text files use `read_file` directly. Each outline entry includes a hash anchor (`tag.line-range: symbol`) for direct use in `edit_file`.
 
 </details>
 

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;
@@ -241,6 +262,16 @@ function block(reason, context) {
   process.stdout.write(JSON.stringify(output));
   process.exit(2);
 }
+function advise(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "approve",
+      permissionDecisionReason: reason
+    }
+  }));
+  process.exit(0);
+}
 function handlePreToolUse(data) {
   const toolName = data.tool_name || "";
   const toolInput = data.tool_input || {};
@@ -249,7 +280,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 +304,33 @@ 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)) {
+        process.exit(0);
+      }
+      if (fileSize !== null && fileSize <= LARGE_FILE_BYTES) {
+        advise("hex-line read_file returns hash-annotated lines for verified edit workflow. For code files, outline gives a compact structural map first.");
+      }
+      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 +436,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 code and markdown 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);
 }