@levnikolaevich/hex-line-mcp 1.3.2 → 1.3.3

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/benchmark/workflows.mjs

@@ -9,7 +9,7 @@
  * - targeted edit inside a large smoke test
  */
 
-import { copyFileSync, mkdirSync, rmSync, unlinkSync } from "node:fs";
+import { copyFileSync, mkdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fnv1a, lineTag, rangeChecksum } from "../lib/hash.mjs";
@@ -255,5 +255,96 @@ export async function runWorkflows(config) {
         }
     }
 
+    // W5: revision-aware follow-up edit after unrelated line shift
+    {
+        const tempPath = resolve(tmpdir(), `hex-line-wf5-${Date.now()}.mjs`);
+        const prefix = Array.from({ length: 80 }, (_, i) => `pre-${i}`);
+        const suffix = Array.from({ length: 80 }, (_, i) => `post-${i}`);
+        const sourceLines = [
+            ...prefix,
+            "head1",
+            "head2",
+            "targetA",
+            "targetB",
+            "tail",
+            ...suffix,
+            "",
+        ];
+        const sourceText = sourceLines.join("\n");
+        mkdirSync(dirname(tempPath), { recursive: true });
+        writeFileSync(tempPath, sourceText, "utf-8");
+
+        const head1Idx = prefix.length;
+        const targetAIdx = prefix.length + 2;
+        const targetBIdx = prefix.length + 3;
+        const withInsert = [
+            ...prefix,
+            "head1",
+            "inserted",
+            "head2",
+            "targetA",
+            "targetB",
+            "tail",
+            ...suffix,
+            "",
+        ];
+        const updatedLines = [
+            ...prefix,
+            "head1",
+            "inserted",
+            "head2",
+            "targetA",
+            "updatedB",
+            "tail",
+            ...suffix,
+            "",
+        ];
+
+        const { value: without } = runN(() => {
+            let total = 0;
+            total += simBuiltInReadFull(tempPath, sourceLines).length;
+            total += simBuiltInEdit(tempPath, sourceLines, withInsert).length;
+            total += simBuiltInReadFull(tempPath, withInsert).length;
+            total += simBuiltInEdit(tempPath, withInsert, updatedLines).length;
+            return total;
+        });
+
+        const { value: withSL } = runN(() => {
+            let total = 0;
+            writeFileSync(tempPath, sourceText, "utf-8");
+            const baseRead = readFile(tempPath, { offset: head1Idx + 1, limit: 8 });
+            total += baseRead.length;
+            const baseRevision = baseRead.match(/revision: (\S+)/)?.[1];
+            const headTag = lineTag(fnv1a(sourceLines[head1Idx]));
+            total += editFile(tempPath, [{ insert_after: { anchor: `${headTag}.${head1Idx + 1}`, text: "inserted" } }]).length;
+            const startTag = lineTag(fnv1a(sourceLines[targetAIdx]));
+            const endTag = lineTag(fnv1a(sourceLines[targetBIdx]));
+            const rc = rangeChecksum(
+                [fnv1a(sourceLines[targetAIdx]), fnv1a(sourceLines[targetBIdx])],
+                targetAIdx + 1,
+                targetBIdx + 1,
+            );
+            total += editFile(tempPath, [{
+                replace_lines: {
+                    start_anchor: `${startTag}.${targetAIdx + 1}`,
+                    end_anchor: `${endTag}.${targetBIdx + 1}`,
+                    new_text: "targetA\nupdatedB",
+                    range_checksum: rc,
+                }
+            }], { baseRevision, conflictPolicy: "conservative" }).length;
+            return total;
+        });
+
+        workflowResults.push({
+            id: "W5",
+            scenario: "Follow-up edit after unrelated line shift",
+            without,
+            withSL,
+            opsWithout: 4,
+            opsWith: 3,
+        });
+        try { unlinkSync(tempPath); } catch {}
+    }
+
     return workflowResults;
 }

package/hook.mjs

@@ -24,7 +24,7 @@
  * Exit 2 = block (PreToolUse) or stderr feedback (PostToolUse)
  */
 
-import { normalizeOutput } from "./lib/normalize.mjs";
+import { normalizeOutput } from "@levnikolaevich/hex-common/output/normalize";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
@@ -42,13 +42,13 @@ const BINARY_EXT = new Set([
 
 const REVERSE_TOOL_HINTS = {
     "mcp__hex-line__read_file":      "Read (file_path, offset, limit)",
-    "mcp__hex-line__edit_file":      "Edit (anchor-based hash edits only)",
+    "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":         "Read the file again with Read",
+    "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)",
@@ -56,7 +56,7 @@ const REVERSE_TOOL_HINTS = {
 
 const 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 hash-verified edits (not Edit). For text rename use bulk_replace",
+    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)",
@@ -68,7 +68,7 @@ const TOOL_HINTS = {
     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 check without re-read)",
+    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)",
@@ -425,7 +425,7 @@ function handleSessionStart() {
     }
     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- Hash edits: edit_file (set_line, replace_lines, insert_after)\n- Text rename: bulk_replace (multi-file search-replace)\n- Write new: write_file\n" + lines.join("\n");
+    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);
 }

package/lib/benchmark-helpers.mjs

@@ -2,7 +2,7 @@ import { readFileSync, statSync, readdirSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { performance } from "node:perf_hooks";
 import { resolve, extname, join } from "node:path";
-import { fnv1a, lineTag } from "./hash.mjs";
+import { fnv1a, lineTag } from "@levnikolaevich/hex-common/text-protocol/hash";
 import { readFile } from "./read.mjs";
 
 // ---------------------------------------------------------------------------

package/lib/coerce.mjs

@@ -1,2 +1 @@
-/** No aliases — canonical parameter names only. */
-export function coerceParams(params) { return params; }
+export * from "@levnikolaevich/hex-common/runtime/coerce";