@levnikolaevich/hex-line-mcp 1.3.2 → 1.3.4

package/README.md

@@ -13,14 +13,31 @@ Every line carries an FNV-1a content hash. Every edit must present those hashes
 
 ### 11 MCP Tools
 
+Core day-to-day tools:
+
+- `read_file`
+- `edit_file`
+- `grep_search`
+- `outline`
+- `verify`
+- `bulk_replace`
+
+Advanced / occasional:
+
+- `write_file`
+- `directory_tree`
+- `get_file_info`
+- `changes`
+- `setup_hooks`
+
 | Tool | Description | Key Feature |
 |------|-------------|-------------|
-| `read_file` | Read file with hash-annotated lines and range checksums | Partial reads via `offset`/`limit` |
-| `edit_file` | Hash-verified anchor edits (set_line, replace_lines, insert_after) | Returns compact diff via `diff` package |
+| `read_file` | Read file with hash-annotated lines, checksums, and revision | Partial reads via `offset`/`limit` |
+| `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) |
-| `verify` | Check if held range checksums are still valid | Single-line response avoids full re-read |
+| `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 |
 | `setup_hooks` | Configure Claude hooks + install output style | Gemini/Codex get guidance only; no hooks |
@@ -49,6 +66,8 @@ npm i -g @levnikolaevich/hex-line-mcp
 claude mcp add -s user hex-line -- hex-line-mcp
 ```
 
+ripgrep is bundled via `@vscode/ripgrep` — no manual install needed for `grep_search`.
+
 ### Hooks
 
 Automatic setup (run once after MCP install):
@@ -121,9 +140,31 @@ If a project already has `.codegraph/index.db`, `hex-line` can add lightweight g
 
 ## Tools Reference
 
+## Common Workflows
+
+### Local code edit in one file
+
+1. `outline` for large code files
+2. `read_file` for the exact range you need
+3. `edit_file` with all known hunks in one call
+
+### Follow-up edit on the same file
+
+1. Carry `revision` from the earlier `read_file` or `edit_file`
+2. Pass it back as `base_revision`
+3. Use `verify` before rereading the file
+
+### Rewrite a long block
+
+Use `replace_between` inside `edit_file` when you know stable start/end anchors and want to replace a large function, class, or config block without reciting the old body.
+
+### 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.
+
 ### read_file
 
-Read a file with FNV-1a hash-annotated lines and range checksums. Supports directory listing.
+Read a file with FNV-1a hash-annotated lines, range checksums, file checksum, and revision. Supports directory listing.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -140,11 +181,13 @@ 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
 
-Edit using hash-verified anchors. For text rename use bulk_replace.
+Edit using revision-aware hash-verified anchors. Prefer one batched call per file. For text rename use bulk_replace.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -152,17 +195,28 @@ Edit using hash-verified anchors. For text rename use bulk_replace.
 | `edits` | string | yes | JSON array of edit operations (see below) |
 | `dry_run` | boolean | no | Preview changes without writing |
 | `restore_indent` | boolean | no | Auto-fix indentation to match anchor context (default: false) |
+| `base_revision` | string | no | Prior revision from `read_file` / `edit_file` for same-file follow-up edits |
+| `conflict_policy` | enum | no | `conservative` or `strict` (default: `conservative`) |
 
 Edit operations (JSON array):
 
 ```json
 [
   {"set_line": {"anchor": "ab.12", "new_text": "replacement line"}},
-  {"replace_lines": {"start_anchor": "ab.10", "end_anchor": "cd.15", "new_text": "..."}},
+  {"replace_lines": {"start_anchor": "ab.10", "end_anchor": "cd.15", "new_text": "...", "range_checksum": "10-15:a1b2c3d4"}},
   {"insert_after": {"anchor": "ab.20", "text": "inserted line"}},
+  {"replace_between": {"start_anchor": "ab.30", "end_anchor": "cd.80", "new_text": "...", "boundary_mode": "inclusive"}}
 ]
 ```
 
+Result footer includes:
+
+- `status: OK | AUTO_REBASED | CONFLICT`
+- `revision: ...`
+- `file: ...`
+- `changed_ranges: ...` when relevant
+- `retry_checksum: ...` on local conflicts
+
 ### write_file
 
 Create a new file or overwrite an existing one. Creates parent directories automatically.
@@ -210,12 +264,13 @@ Not for `.md`, `.json`, `.yaml`, `.txt` -- use `read_file` directly for those.
 
 ### verify
 
-Check if range checksums from a prior read are still valid.
+Check if range checksums from a prior read are still valid, optionally relative to a prior `base_revision`.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | string | yes | File path |
 | `checksums` | string | yes | JSON 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.
 

package/dist/hook.mjs

@@ -0,0 +1,428 @@
+#!/usr/bin/env node
+
+// ../hex-common/src/output/normalize.mjs
+var NORM_RULES = [
+  [/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<UUID>"],
+  [/\d{4}-\d{2}-\d{2}\s\d{2}:\d{2}:\d{2}/g, "<TS>"],
+  [/\d{2}-\d{2}-\d{4}\s\d{2}:\d{2}:\d{2}/g, "<TS>"],
+  [/\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}(:\d+)?/g, "<IP>"],
+  [/\/[0-9a-f]{8,}/gi, "/<ID>"],
+  [/\b\d{3,}(?=\b|[a-zA-Z])/g, "<N>"],
+  [/trace_id=[0-9a-fA-F]{1,8}/g, "trace_id=<TRACE>"]
+];
+function normalizeLine(line) {
+  let result = line;
+  for (const [rx, repl] of NORM_RULES) {
+    result = result.replace(rx, repl);
+  }
+  return result;
+}
+function deduplicateLines(lines) {
+  const groups = /* @__PURE__ */ new Map();
+  const order = [];
+  for (const line of lines) {
+    const norm = normalizeLine(line);
+    if (groups.has(norm)) groups.get(norm).count++;
+    else {
+      groups.set(norm, { representative: line, count: 1 });
+      order.push(norm);
+    }
+  }
+  order.sort((a, b) => groups.get(b).count - groups.get(a).count);
+  return order.map((norm) => {
+    const { representative, count } = groups.get(norm);
+    return count > 1 ? `${representative}  (x${count})` : representative;
+  });
+}
+function smartTruncate(text, headLines = 40, tailLines = 20) {
+  const lines = text.split("\n");
+  const total = lines.length;
+  const maxLines = headLines + tailLines;
+  if (total <= maxLines) return text;
+  const head = lines.slice(0, headLines);
+  const tail = lines.slice(total - tailLines);
+  const skipped = total - maxLines;
+  return [...head, `
+--- ${skipped} lines omitted ---
+`, ...tail].join("\n");
+}
+function normalizeOutput(text, opts = {}) {
+  const { deduplicate = true, headLines = 40, tailLines = 20 } = opts;
+  const lines = text.split("\n");
+  const processed = deduplicate ? deduplicateLines(lines) : lines;
+  return smartTruncate(processed.join("\n"), headLines, tailLines);
+}
+
+// hook.mjs
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+var BINARY_EXT = /* @__PURE__ */ new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".bmp",
+  ".webp",
+  ".svg",
+  ".ico",
+  ".pdf",
+  ".ipynb",
+  ".zip",
+  ".tar",
+  ".gz",
+  ".7z",
+  ".rar",
+  ".exe",
+  ".dll",
+  ".so",
+  ".dylib",
+  ".wasm",
+  ".mp3",
+  ".mp4",
+  ".wav",
+  ".avi",
+  ".mkv",
+  ".ttf",
+  ".otf",
+  ".woff",
+  ".woff2"
+]);
+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__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__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)"
+};
+var TOOL_HINTS = {
+  Read: "mcp__hex-line__read_file (not Read). For writing: write_file (no prior Read needed)",
+  Edit: "mcp__hex-line__edit_file for revision-aware hash edits. Batch same-file hunks, carry base_revision, use replace_between for block rewrites",
+  Write: "mcp__hex-line__write_file (not Write). No prior Read needed",
+  Grep: "mcp__hex-line__grep_search (not Grep). Params: output, literal, context_before, context_after, multiline",
+  cat: "mcp__hex-line__read_file (not cat/head/tail/less/more)",
+  head: "mcp__hex-line__read_file with limit param (not head)",
+  tail: "mcp__hex-line__read_file with offset param (not tail)",
+  ls: "mcp__hex-line__directory_tree with pattern param (not ls/find/tree). E.g. pattern='*-mcp' type='dir'",
+  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",
+  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)",
+  bulk: "mcp__hex-line__bulk_replace (multi-file search-replace)",
+  setup: "mcp__hex-line__setup_hooks (configure hooks for agents)"
+};
+var BASH_REDIRECTS = [
+  { regex: /^cat\s+\S+/, key: "cat" },
+  { regex: /^head\s+/, key: "head" },
+  { regex: /^tail\s+(?!-[fF])/, key: "tail" },
+  { regex: /^(less|more)\s+/, key: "cat" },
+  { regex: /^ls\s+-\S*R(\s|$)/, key: "ls" },
+  // ls -R, ls -laR (recursive only)
+  { regex: /^dir\s+\/[sS](\s|$)/, key: "ls" },
+  // dir /s, dir /S (recursive only)
+  { regex: /^tree\s+/, key: "ls" },
+  { regex: /^find\s+/, key: "ls" },
+  { regex: /^(stat|wc)\s+/, key: "stat" },
+  { regex: /^(grep|rg)\s+/, key: "grep" },
+  { regex: /^sed\s+-i/, key: "sed" }
+];
+var TOOL_REDIRECT_MAP = {
+  Read: "Read",
+  Edit: "Edit",
+  Write: "Write",
+  Grep: "Grep"
+};
+var DANGEROUS_PATTERNS = [
+  {
+    regex: /rm\s+(-[rf]+\s+)*[/~]/,
+    reason: "rm -rf on root/home directory"
+  },
+  {
+    regex: /git\s+push\s+(-f|--force)/,
+    reason: "force push can overwrite remote history"
+  },
+  {
+    regex: /git\s+reset\s+--hard/,
+    reason: "hard reset discards uncommitted changes"
+  },
+  {
+    regex: /DROP\s+(TABLE|DATABASE)/i,
+    reason: "DROP destroys data permanently"
+  },
+  {
+    regex: /chmod\s+777/,
+    reason: "chmod 777 removes all access restrictions"
+  },
+  {
+    regex: /mkfs/,
+    reason: "filesystem format destroys all data"
+  },
+  {
+    regex: /dd\s+if=\/dev\/zero/,
+    reason: "direct disk write destroys data"
+  }
+];
+var COMPOUND_OPERATORS = /[|]|>>?|&&|\|\||;/;
+var CMD_PATTERNS = [
+  [/npm (install|ci|update|add)/i, "npm-install"],
+  [/npm test|jest|vitest|mocha|pytest|cargo test/i, "test"],
+  [/npm run build|tsc|webpack|vite build|cargo build/i, "build"],
+  [/pip install/i, "pip-install"],
+  [/git (log|diff|status)/i, "git"]
+];
+var LINE_THRESHOLD = 50;
+var HEAD_LINES = 15;
+var TAIL_LINES = 15;
+function extOf(filePath) {
+  const dot = filePath.lastIndexOf(".");
+  return dot !== -1 ? filePath.slice(dot).toLowerCase() : "";
+}
+function detectCommandType(cmd) {
+  for (const [re, type] of CMD_PATTERNS) {
+    if (re.test(cmd)) return type;
+  }
+  return "generic";
+}
+function extractBashText(response) {
+  if (typeof response === "string") return response;
+  if (response && typeof response === "object") {
+    const parts = [];
+    if (response.stdout) parts.push(response.stdout);
+    if (response.stderr) parts.push(response.stderr);
+    return parts.join("\n") || "";
+  }
+  return "";
+}
+var _hexLineDisabled = null;
+function isHexLineDisabled(configPath) {
+  if (_hexLineDisabled !== null) return _hexLineDisabled;
+  _hexLineDisabled = false;
+  try {
+    const p = configPath || resolve(homedir(), ".claude.json");
+    const claudeJson = JSON.parse(readFileSync(p, "utf-8"));
+    const projects = claudeJson.projects;
+    if (!projects || typeof projects !== "object") return _hexLineDisabled;
+    const cwd = process.cwd().replace(/\\/g, "/").replace(/\/$/, "").toLowerCase();
+    for (const [path, config] of Object.entries(projects)) {
+      if (path.replace(/\\/g, "/").replace(/\/$/, "").toLowerCase() === cwd) {
+        const disabled = config.disabledMcpServers;
+        if (Array.isArray(disabled) && disabled.includes("hex-line")) {
+          _hexLineDisabled = true;
+        }
+        break;
+      }
+    }
+  } catch {
+  }
+  return _hexLineDisabled;
+}
+function _resetHexLineDisabledCache() {
+  _hexLineDisabled = null;
+}
+function block(reason, context) {
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason
+    }
+  };
+  if (context) output.hookSpecificOutput.additionalContext = context;
+  process.stdout.write(JSON.stringify(output));
+  process.exit(2);
+}
+function handlePreToolUse(data) {
+  const toolName = data.tool_name || "";
+  const toolInput = data.tool_input || {};
+  if (toolName.startsWith("mcp__hex-line__")) {
+    process.exit(0);
+  }
+  const hintKey = TOOL_REDIRECT_MAP[toolName];
+  if (hintKey) {
+    const filePath = toolInput.file_path || toolInput.path || "";
+    if (BINARY_EXT.has(extOf(filePath))) {
+      process.exit(0);
+    }
+    const normalPath = filePath.replace(/\\/g, "/");
+    if (normalPath.includes(".claude/plans/") || normalPath.includes("AppData")) {
+      process.exit(0);
+    }
+    const ALLOWED_CONFIGS = /* @__PURE__ */ new Set(["settings.json", "settings.local.json"]);
+    const fileName = normalPath.split("/").pop();
+    if (ALLOWED_CONFIGS.has(fileName)) {
+      let candidate = filePath;
+      if (candidate.startsWith("~/")) {
+        candidate = homedir().replace(/\\/g, "/") + candidate.slice(1);
+      }
+      const absPath = resolve(process.cwd(), candidate).replace(/\\/g, "/");
+      const projectClaude = resolve(process.cwd(), ".claude").replace(/\\/g, "/") + "/";
+      const globalClaude = resolve(homedir(), ".claude").replace(/\\/g, "/") + "/";
+      const cmp = process.platform === "win32" ? (a, b) => a.toLowerCase().startsWith(b.toLowerCase()) : (a, b) => a.startsWith(b);
+      if (cmp(absPath, projectClaude) || cmp(absPath, globalClaude)) {
+        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 === "Bash") {
+    const command = (toolInput.command || "").trim();
+    if (command.includes("# hex-confirmed")) {
+      process.exit(0);
+    }
+    const cmdCheck = command.replace(/<<['"]?(\w+)['"]?\s*\n[\s\S]*?\n\1/g, "");
+    for (const { regex, reason } of DANGEROUS_PATTERNS) {
+      if (regex.test(cmdCheck)) {
+        block(
+          `DANGEROUS: ${reason}. Ask user to confirm, then retry with: # hex-confirmed`,
+          `Original command: ${command.slice(0, 100)}`
+        );
+      }
+    }
+    if (COMPOUND_OPERATORS.test(command)) {
+      const firstCmd = command.split(/\s*[|;&>]\s*/)[0].trim();
+      for (const { regex, key } of BASH_REDIRECTS) {
+        if (regex.test(firstCmd)) {
+          const hint = TOOL_HINTS[key];
+          const toolName2 = hint.split(" (")[0];
+          block(`Use ${toolName2} instead of piped command`, hint);
+        }
+      }
+      process.exit(0);
+    }
+    for (const { regex, key } of BASH_REDIRECTS) {
+      if (regex.test(command)) {
+        const hint = TOOL_HINTS[key];
+        const toolName2 = hint.split(" (")[0];
+        const args = command.split(/\s+/).slice(1).join(" ");
+        const argsNote = args ? ` \u2014 args: "${args}"` : "";
+        block(`Use ${toolName2}${argsNote}`, hint);
+      }
+    }
+  }
+  process.exit(0);
+}
+function handlePreToolUseReverse(data) {
+  const toolName = data.tool_name || "";
+  if (toolName.startsWith("mcp__hex-line__")) {
+    const builtIn = REVERSE_TOOL_HINTS[toolName];
+    if (builtIn) {
+      const target = builtIn.split(" ")[0];
+      block(
+        `hex-line is disabled in this project. Use ${target}`,
+        `hex-line disabled. Use built-in: ${builtIn}`
+      );
+    }
+    block("hex-line is disabled in this project", "Disabled via project settings");
+  }
+  process.exit(0);
+}
+function handlePostToolUse(data) {
+  const toolName = data.tool_name || "";
+  if (toolName !== "Bash") {
+    process.exit(0);
+  }
+  const toolInput = data.tool_input || {};
+  const rawText = extractBashText(data.tool_response);
+  const command = toolInput.command || "";
+  if (!rawText) {
+    process.exit(0);
+  }
+  const lines = rawText.split("\n");
+  const originalCount = lines.length;
+  if (originalCount < LINE_THRESHOLD) {
+    process.exit(0);
+  }
+  const type = detectCommandType(command);
+  const filtered = normalizeOutput(lines.join("\n"), { headLines: HEAD_LINES, tailLines: TAIL_LINES });
+  const filteredCount = filtered.split("\n").length;
+  const header = `RTK FILTERED: ${type} (${originalCount} lines -> ${filteredCount} lines)`;
+  const output = [
+    "=".repeat(50),
+    header,
+    "=".repeat(50),
+    "",
+    filtered,
+    "",
+    "-".repeat(50),
+    `Original: ${originalCount} lines | Filtered: ${filteredCount} lines`,
+    "=".repeat(50)
+  ].join("\n");
+  process.stderr.write(output);
+  process.exit(2);
+}
+function handleSessionStart() {
+  const settingsFiles = [
+    resolve(process.cwd(), ".claude/settings.local.json"),
+    resolve(process.cwd(), ".claude/settings.json"),
+    resolve(homedir(), ".claude/settings.json")
+  ];
+  let styleActive = false;
+  for (const f of settingsFiles) {
+    try {
+      const config = JSON.parse(readFileSync(f, "utf-8"));
+      if (config.outputStyle === "hex-line") {
+        styleActive = true;
+        break;
+      }
+      if (config.outputStyle) break;
+    } 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");
+  process.stdout.write(JSON.stringify({ systemMessage: msg }));
+  process.exit(0);
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  let input = "";
+  process.stdin.on("data", (chunk) => {
+    input += chunk;
+  });
+  process.stdin.on("end", () => {
+    try {
+      const data = JSON.parse(input);
+      const event = data.hook_event_name || "";
+      if (isHexLineDisabled()) {
+        if (event === "PreToolUse") handlePreToolUseReverse(data);
+        process.exit(0);
+      }
+      if (event === "SessionStart") handleSessionStart();
+      else if (event === "PreToolUse") handlePreToolUse(data);
+      else if (event === "PostToolUse") handlePostToolUse(data);
+      else process.exit(0);
+    } catch {
+      process.exit(0);
+    }
+  });
+}
+export {
+  _resetHexLineDisabledCache,
+  isHexLineDisabled
+};