@levnikolaevich/hex-line-mcp 1.2.0 → 1.3.1

package/lib/edit.mjs

@@ -8,11 +8,12 @@
  * - dry_run preview, noop detection, diff output
  */
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { writeFileSync } from "node:fs";
 import { diffLines } from "diff";
-import { fnv1a, lineTag, rangeChecksum } from "./hash.mjs";
+import { fnv1a, lineTag, rangeChecksum, parseChecksum, parseRef } from "./hash.mjs";
 import { validatePath } from "./security.mjs";
 import { getGraphDB, blastRadius, getRelativePath } from "./graph-enrich.mjs";
+import { readText } from "./format.mjs";
 
 // Unicode characters visually similar to ASCII hyphen-minus (U+002D)
 const CONFUSABLE_HYPHENS = /[\u2010\u2011\u2012\u2013\u2014\u2212\uFE63\uFF0D]/g;
@@ -40,6 +41,24 @@ function restoreIndent(origLines, newLines) {
     });
 }
 
+/**
+ * Build hash-annotated snippet around a position for error messages.
+ * @param {string[]} lines - file lines
+ * @param {number} centerIdx - 0-based center index
+ * @param {number} radius - lines before/after center (default 5)
+ * @returns {{ start: number, end: number, text: string }}
+ */
+function buildErrorSnippet(lines, centerIdx, radius = 5) {
+    const start = Math.max(0, centerIdx - radius);
+    const end = Math.min(lines.length, centerIdx + radius + 1);
+    const text = lines.slice(start, end).map((line, i) => {
+        const num = start + i + 1;
+        const tag = lineTag(fnv1a(line));
+        return `${tag}.${num}\t${line}`;
+    }).join("\n");
+    return { start: start + 1, end, text };
+}
+
 /**
  * Build a hash index of all lines, keeping only unique tags.
  * 2-char tags have collisions — duplicates are excluded to avoid wrong relocations.
@@ -65,21 +84,11 @@ function buildHashIndex(lines) {
 function findLine(lines, lineNum, expectedTag, hashIndex) {
     const idx = lineNum - 1;
     if (idx < 0 || idx >= lines.length) {
-        const start = idx >= lines.length
-            ? Math.max(0, lines.length - 10)
-            : 0;
-        const end = idx >= lines.length
-            ? lines.length
-            : Math.min(lines.length, 10);
-        const snippet = lines.slice(start, end).map((line, i) => {
-            const num = start + i + 1;
-            const tag = lineTag(fnv1a(line));
-            return `${tag}.${num}\t${line}`;
-        }).join("\n");
-
+        const center = idx >= lines.length ? lines.length - 1 : 0;
+        const snip = buildErrorSnippet(lines, center);
         throw new Error(
             `Line ${lineNum} out of range (1-${lines.length}).\n\n` +
-            `Current content (lines ${start + 1}-${end}):\n${snippet}\n\n` +
+            `Current content (lines ${snip.start}-${snip.end}):\n${snip.text}\n\n` +
             `Tip: Use updated hashes above for retry.`
         );
     }
@@ -116,30 +125,14 @@ function findLine(lines, lineNum, expectedTag, hashIndex) {
         if (relocated !== undefined) return relocated;
     }
 
-    // Build snippet with fresh hashes so agent can retry without re-reading
-    const start = Math.max(0, idx - 5);
-    const end = Math.min(lines.length, idx + 6);
-    const snippet = lines.slice(start, end).map((line, i) => {
-        const num = start + i + 1;
-        const tag = lineTag(fnv1a(line));
-        return `${tag}.${num}\t${line}`;
-    }).join("\n");
-
+    const snip = buildErrorSnippet(lines, idx);
     throw new Error(
-        `Hash mismatch line ${lineNum}: expected ${expectedTag}, got ${actual}.\n\n` +
-        `Current content (lines ${start + 1}-${end}):\n${snippet}\n\n` +
+        `HASH_MISMATCH: line ${lineNum} expected ${expectedTag}, got ${actual}.\n\n` +
+        `Current content (lines ${snip.start}-${snip.end}):\n${snip.text}\n\n` +
         `Tip: Use updated hashes above for retry.`
     );
 }
 
-/**
- * Parse a ref string: "ab.12" → { tag: "ab", line: 12 }
- */
-function parseRef(ref) {
-    const m = ref.trim().match(/^([a-z2-7]{2})\.(\d+)$/);
-    if (!m) throw new Error(`Bad ref: "${ref}". Expected "ab.12"`);
-    return { tag: m[1], line: parseInt(m[2], 10) };
-}
 
 /**
  * Context diff via `diff` package (Myers O(ND) algorithm).
@@ -243,7 +236,20 @@ function textReplace(content, oldText, newText, all) {
     const normNew = newText.replace(/\r\n/g, "\n");
 
     if (!all) {
-        throw new Error("replace requires all:true (rename-all mode). For single replacements, use set_line or replace_lines with hash anchors.");
+        // Uniqueness check: count occurrences
+        const parts = norm.split(normOld);
+        const count = parts.length - 1;
+        if (count === 0) {
+            // Fall through to TEXT_NOT_FOUND below
+        } else if (count === 1) {
+            // Unique match — safe to replace single occurrence
+            return parts.join(normNew);
+        } else {
+            throw new Error(
+                `AMBIGUOUS_MATCH: "${normOld.slice(0, 80)}" found ${count} times. ` +
+                `Use all:true to replace all, or use set_line/replace_lines for a specific occurrence.`
+            );
+        }
     }
     let idx = norm.indexOf(normOld);
     let confusableMatch = false;
@@ -299,9 +305,10 @@ function textReplace(content, oldText, newText, all) {
  */
 export function editFile(filePath, edits, opts = {}) {
     const real = validatePath(filePath);
-    const original = readFileSync(real, "utf-8").replace(/\r\n/g, "\n");
+    const original = readText(real);
     const lines = original.split("\n");
     const origLines = [...lines];
+    const hadTrailingNewline = original.endsWith("\n");
 
     // Build hash index once for global relocation in findLine
     const hashIndex = buildHashIndex(lines);
@@ -313,7 +320,35 @@ export function editFile(filePath, edits, opts = {}) {
     for (const e of edits) {
         if (e.set_line || e.replace_lines || e.insert_after) anchored.push(e);
         else if (e.replace) texts.push(e);
-        else throw new Error(`Unknown edit type: ${JSON.stringify(e)}`);
+        else throw new Error(`BAD_INPUT: unknown edit type: ${JSON.stringify(e)}`);
+    }
+
+    // Overlap validation: reject duplicate/overlapping edit targets
+    const editTargets = [];
+    for (const e of anchored) {
+        if (e.set_line) {
+            const line = parseRef(e.set_line.anchor).line;
+            editTargets.push({ start: line, end: line });
+        } else if (e.replace_lines) {
+            const s = parseRef(e.replace_lines.start_anchor).line;
+            const en = parseRef(e.replace_lines.end_anchor).line;
+            editTargets.push({ start: s, end: en });
+        } else if (e.insert_after) {
+            const line = parseRef(e.insert_after.anchor).line;
+            editTargets.push({ start: line, end: line, insert: true });
+        }
+    }
+    for (let i = 0; i < editTargets.length; i++) {
+        for (let j = i + 1; j < editTargets.length; j++) {
+            const a = editTargets[i], b = editTargets[j];
+            if (a.insert || b.insert) continue; // insert_after doesn't overlap
+            if (a.start <= b.end && b.start <= a.end) {
+                throw new Error(
+                    `OVERLAPPING_EDITS: lines ${a.start}-${a.end} and ${b.start}-${b.end} overlap. ` +
+                    `Split into separate edit_file calls.`
+                );
+            }
+        }
     }
 
     // Sort anchor edits bottom-to-top
@@ -348,12 +383,45 @@ export function editFile(filePath, edits, opts = {}) {
             // Range checksum verification (mandatory)
             const rc = e.replace_lines.range_checksum;
             if (!rc) throw new Error("range_checksum required for replace_lines. Read the range first via read_file, then pass its checksum.");
-            const rcHex = rc.includes(":") ? rc.split(":")[1] : rc;
+
+            // Checksum's range is authoritative (from read_file), not anchor range
+            const { start: csStart, end: csEnd, hex: csHex } = parseChecksum(rc);
+
+            // Coverage check: checksum range must contain ACTUAL edit range (after relocation)
+            const actualStart = si + 1;
+            const actualEnd = ei + 1;
+            if (csStart > actualStart || csEnd < actualEnd) {
+                const snip = buildErrorSnippet(origLines, actualStart - 1);
+                throw new Error(
+                    `CHECKSUM_RANGE_GAP: range ${csStart}-${csEnd} does not cover edit range ${actualStart}-${actualEnd}.\n\n` +
+                    `Current content (lines ${snip.start}-${snip.end}):\n${snip.text}\n\n` +
+                    `Tip: Use updated hashes above for retry.`
+                );
+            }
+
+            // Verify freshness over checksum's own range using origLines snapshot
+            const csStartIdx = csStart - 1;
+            const csEndIdx = csEnd - 1;
+            if (csStartIdx < 0 || csEndIdx >= origLines.length) {
+                const snip = buildErrorSnippet(origLines, origLines.length - 1);
+                throw new Error(
+                    `CHECKSUM_OUT_OF_BOUNDS: range ${csStart}-${csEnd} exceeds file length ${origLines.length}.\n\n` +
+                    `Current content (lines ${snip.start}-${snip.end}):\n${snip.text}\n\n` +
+                    `Tip: Use updated hashes above for retry.`
+                );
+            }
             const lineHashes = [];
-            for (let i = si; i <= ei; i++) lineHashes.push(fnv1a(lines[i]));
-            const actual = rangeChecksum(lineHashes, s.line, en.line);
+            for (let i = csStartIdx; i <= csEndIdx; i++) lineHashes.push(fnv1a(origLines[i]));
+            const actual = rangeChecksum(lineHashes, csStart, csEnd);
             const actualHex = actual.split(":")[1];
-            if (rcHex !== actualHex) throw new Error(`Range checksum mismatch: expected ${rc}, got ${actual}. File changed \u2014 re-read lines ${s.line}-${en.line}.`);
+            if (csHex !== actualHex) {
+                const snip = buildErrorSnippet(origLines, csStartIdx);
+                throw new Error(
+                    `CHECKSUM_MISMATCH: expected ${rc}, got ${actual}. File changed \u2014 re-read lines ${csStart}-${csEnd}.\n\n` +
+                    `Current content (lines ${snip.start}-${snip.end}):\n${snip.text}\n\n` +
+                    `Retry with fresh checksum ${actual}, or use set_line with hashes above.`
+                );
+            }
 
             const txt = e.replace_lines.new_text;
             if (!txt && txt !== 0) {
@@ -375,6 +443,8 @@ export function editFile(filePath, edits, opts = {}) {
 
     // Apply text replacements
     let content = lines.join("\n");
+    if (hadTrailingNewline && !content.endsWith("\n")) content += "\n";
+    if (!hadTrailingNewline && content.endsWith("\n")) content = content.slice(0, -1);
     for (const e of texts) {
         if (!e.replace.old_text) throw new Error("replace.old_text required");
         content = textReplace(content, e.replace.old_text, e.replace.new_text || "", e.replace.all || false);
@@ -421,5 +491,34 @@ export function editFile(filePath, edits, opts = {}) {
         }
     } catch { /* silent */ }
 
+    // Post-edit context: hash-annotated lines around changed region + checksums
+    const newLines = content.split("\n");
+    if (diff) {
+        const diffArr = diff.split("\n");
+        let minLine = Infinity, maxLine = 0;
+        for (const dl of diffArr) {
+            const m = dl.match(/^[+-](\d+)\|/);
+            if (m) { const n = +m[1]; if (n < minLine) minLine = n; if (n > maxLine) maxLine = n; }
+        }
+        if (minLine <= maxLine) {
+            const ctxStart = Math.max(0, minLine - 6);
+            const ctxEnd = Math.min(newLines.length, maxLine + 5);
+            const ctxLines = [];
+            const ctxHashes = [];
+            for (let i = ctxStart; i < ctxEnd; i++) {
+                const h = fnv1a(newLines[i]);
+                ctxHashes.push(h);
+                ctxLines.push(`${lineTag(h)}.${i + 1}\t${newLines[i]}`);
+            }
+            const ctxCs = rangeChecksum(ctxHashes, ctxStart + 1, ctxEnd);
+            msg += `\n\nPost-edit (lines ${ctxStart + 1}-${ctxEnd}):\n${ctxLines.join("\n")}\nchecksum: ${ctxCs}`;
+        }
+    }
+    // File-level checksum
+    const fileHashes = [];
+    for (let i = 0; i < newLines.length; i++) fileHashes.push(fnv1a(newLines[i]));
+    const fileCs = rangeChecksum(fileHashes, 1, newLines.length);
+    msg += `\nfile: ${fileCs}`;
+
     return msg;
 }

package/lib/format.mjs

@@ -0,0 +1,138 @@
+/**
+ * Shared format helpers for hex-line-mcp.
+ * Single source of truth for formatSize, relativeTime, countFileLines, listDirectory, readText, MAX_OUTPUT_CHARS.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Format bytes as human-readable size string.
+ * @param {number} bytes
+ * @returns {string}
+ */
+export function formatSize(bytes) {
+    if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+    if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${bytes}B`;
+}
+
+/**
+ * Format a Date as relative time string.
+ * @param {Date} date
+ * @param {boolean} compact - true: "5m ago", false: "5 min ago"
+ * @returns {string}
+ */
+export function relativeTime(date, compact = false) {
+    const sec = Math.round((Date.now() - date.getTime()) / 1000);
+    if (compact) {
+        if (sec < 60) return "now";
+        if (sec < 3600) return `${Math.floor(sec / 60)}m ago`;
+        if (sec < 86400) return `${Math.floor(sec / 3600)}h ago`;
+        if (sec < 604800) return `${Math.floor(sec / 86400)}d ago`;
+        if (sec < 2592000) return `${Math.floor(sec / 604800)}w ago`;
+        return `${Math.floor(sec / 2592000)}mo ago`;
+    }
+    if (sec < 60) return "just now";
+    const min = Math.floor(sec / 60);
+    if (min < 60) return `${min} min ago`;
+    const hrs = Math.floor(min / 60);
+    if (hrs < 24) return `${hrs} hour${hrs === 1 ? "" : "s"} ago`;
+    const days = Math.floor(hrs / 24);
+    if (days < 30) return `${days} day${days === 1 ? "" : "s"} ago`;
+    const months = Math.floor(days / 30);
+    if (months < 12) return `${months} month${months === 1 ? "" : "s"} ago`;
+    const years = Math.floor(months / 12);
+    return `${years} year${years === 1 ? "" : "s"} ago`;
+}
+
+/**
+ * Count lines in a text file. Returns null for binary or oversized files.
+ * Buffer-based single-pass with built-in binary detection.
+ * @param {string} filePath
+ * @param {number} size - file size in bytes
+ * @param {number} maxSize - skip if larger (default 1MB)
+ * @returns {number|null}
+ */
+export function countFileLines(filePath, size, maxSize = 1_000_000) {
+    if (size === 0 || size > maxSize) return null;
+    try {
+        const buf = readFileSync(filePath);
+        const checkLen = Math.min(buf.length, 8192);
+        for (let i = 0; i < checkLen; i++) if (buf[i] === 0) return null; // binary
+        let count = 1;
+        for (let i = 0; i < buf.length; i++) if (buf[i] === 0x0A) count++;
+        return count;
+    } catch { return null; }
+}
+
+/**
+ * Flat single-level directory listing with optional metadata.
+ * Sorted: directories first, then files, alphabetical.
+ * @param {string} dirPath - absolute directory path
+ * @param {object} opts
+ * @param {number} opts.limit - max entries (0 = all, default 0)
+ * @param {boolean} opts.metadata - show size/lines/time per entry (default false)
+ * @param {boolean} opts.compact - compact time format (default false)
+ * @param {string} opts.indent - prefix per line (default "  ")
+ * @returns {{ text: string, total: number }}
+ */
+export function listDirectory(dirPath, opts = {}) {
+    const { limit = 0, metadata = false, compact = false, indent = "  " } = opts;
+
+    let entries;
+    try {
+        entries = readdirSync(dirPath, { withFileTypes: true });
+    } catch {
+        return { text: "", total: 0 };
+    }
+
+    // Sort: directories first, then files, alphabetical
+    entries.sort((a, b) => {
+        const aDir = a.isDirectory() ? 0 : 1;
+        const bDir = b.isDirectory() ? 0 : 1;
+        if (aDir !== bDir) return aDir - bDir;
+        return a.name.localeCompare(b.name);
+    });
+
+    const total = entries.length;
+    const visible = limit > 0 ? entries.slice(0, limit) : entries;
+
+    const lines = visible.map(entry => {
+        const isDir = entry.isDirectory();
+        if (!metadata) {
+            return `${indent}${isDir ? "d" : "f"} ${entry.name}`;
+        }
+        if (isDir) {
+            return `${indent}${entry.name}/`;
+        }
+        // File with metadata
+        const full = join(dirPath, entry.name);
+        const parts = [];
+        try {
+            const st = statSync(full);
+            const lineCount = countFileLines(full, st.size);
+            if (lineCount !== null) parts.push(`${lineCount}L`);
+            parts.push(formatSize(st.size));
+            if (st.mtime) parts.push(relativeTime(st.mtime, compact));
+        } catch {
+            parts.push("?");
+        }
+        return `${indent}${entry.name} (${parts.join(", ")})`;
+    });
+
+    return { text: lines.join("\n"), total };
+}
+
+
+/** Max output characters for read_file and bulk_replace. */
+export const MAX_OUTPUT_CHARS = 80000;
+
+/**
+ * Read a text file with CRLF normalization.
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function readText(filePath) {
+    return readFileSync(filePath, "utf-8").replace(/\r\n/g, "\n");
+}

package/lib/hash.mjs

@@ -1,7 +1,7 @@
 /**
  * FNV-1a hashing for hash-verified file editing.
  *
- * Trueline-compatible: 2-char tags from 32-symbol alphabet,
+ * 2-char tags from 32-symbol alphabet,
  * range checksums as FNV-1a accumulator over line hashes.
  *
  * Line format: {tag}.{lineNum}\t{content}

package/lib/info.mjs

@@ -4,8 +4,10 @@
  * Returns: size, line count, modification time, type, binary detection.
  */
 
-import { statSync, readFileSync } from "node:fs";
+import { statSync, openSync, readSync, closeSync } from "node:fs";
 import { resolve, isAbsolute, extname, basename } from "node:path";
+import { normalizePath } from "./security.mjs";
+import { formatSize, relativeTime, countFileLines } from "./format.mjs";
 
 const MAX_LINE_COUNT_SIZE = 10 * 1024 * 1024; // 10 MB
 
@@ -31,32 +33,15 @@ const EXT_NAMES = {
     ".dockerfile": "Dockerfile", ".vue": "Vue component", ".svelte": "Svelte component",
 };
 
-function formatSize(bytes) {
-    if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
-    if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-    return `${bytes}B`;
-}
-
-function relativeTime(mtime) {
-    const diff = Date.now() - mtime.getTime();
-    const secs = Math.floor(diff / 1000);
-    if (secs < 60) return "just now";
-    const mins = Math.floor(secs / 60);
-    if (mins < 60) return `${mins} minute${mins > 1 ? "s" : ""} ago`;
-    const hours = Math.floor(mins / 60);
-    if (hours < 24) return `${hours} hour${hours > 1 ? "s" : ""} ago`;
-    const days = Math.floor(hours / 24);
-    if (days < 30) return `${days} day${days > 1 ? "s" : ""} ago`;
-    const months = Math.floor(days / 30);
-    return `${months} month${months > 1 ? "s" : ""} ago`;
-}
 
 function detectBinary(filePath, size) {
     if (size === 0) return false;
-    const fd = readFileSync(filePath, { encoding: null, flag: "r" });
-    const checkLen = Math.min(fd.length, 8192);
-    for (let i = 0; i < checkLen; i++) {
-        if (fd[i] === 0) return true;
+    const fd = openSync(filePath, "r");
+    const probe = Buffer.alloc(Math.min(size, 8192));
+    const bytesRead = readSync(fd, probe, 0, probe.length, 0);
+    closeSync(fd);
+    for (let i = 0; i < bytesRead; i++) {
+        if (probe[i] === 0) return true;
     }
     return false;
 }
@@ -68,7 +53,8 @@ function detectBinary(filePath, size) {
  */
 export function fileInfo(filePath) {
     if (!filePath) throw new Error("Empty file path");
-    const abs = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath);
+    const normalized = normalizePath(filePath);
+    const abs = isAbsolute(normalized) ? normalized : resolve(process.cwd(), normalized);
 
     const stat = statSync(abs);
     if (!stat.isFile()) throw new Error(`Not a regular file: ${abs}`);
@@ -86,12 +72,8 @@ export function fileInfo(filePath) {
     // Binary detection
     const isBinary = size > 0 ? detectBinary(abs, size) : false;
 
-    // Line count (only for non-binary, <10MB)
-    let lineCount = null;
-    if (!isBinary && size <= MAX_LINE_COUNT_SIZE && size > 0) {
-        const content = readFileSync(abs, "utf-8");
-        lineCount = content.split("\n").length;
-    }
+    // Line count (only for non-binary, <=10MB)
+    const lineCount = !isBinary && size > 0 ? countFileLines(abs, size, MAX_LINE_COUNT_SIZE) : null;
 
     // Format output
     const sizeStr = lineCount !== null

package/lib/read.mjs

@@ -5,31 +5,13 @@
  * Appends: checksum: {start}-{end}:{8hex}
  */
 
-import { readFileSync, statSync, readdirSync } from "node:fs";
+import { statSync } from "node:fs";
 import { fnv1a, lineTag, rangeChecksum } from "./hash.mjs";
 import { validatePath } from "./security.mjs";
 import { getGraphDB, fileAnnotations, getRelativePath } from "./graph-enrich.mjs";
-
-/**
- * Format a Date as relative time string: "just now", "5 min ago", etc.
- */
-function relativeTime(date) {
-    const sec = Math.round((Date.now() - date.getTime()) / 1000);
-    if (sec < 60) return "just now";
-    const min = Math.floor(sec / 60);
-    if (min < 60) return `${min} min ago`;
-    const hrs = Math.floor(min / 60);
-    if (hrs < 24) return `${hrs} hour${hrs === 1 ? "" : "s"} ago`;
-    const days = Math.floor(hrs / 24);
-    if (days < 30) return `${days} day${days === 1 ? "" : "s"} ago`;
-    const months = Math.floor(days / 30);
-    if (months < 12) return `${months} month${months === 1 ? "" : "s"} ago`;
-    const years = Math.floor(months / 12);
-    return `${years} year${years === 1 ? "" : "s"} ago`;
-}
+import { relativeTime, listDirectory, readText, MAX_OUTPUT_CHARS } from "./format.mjs";
 
 const DEFAULT_LIMIT = 2000;
-const MAX_OUTPUT_CHARS = 80000;
 
 /**
  * Read a file with hash-annotated lines.
@@ -44,12 +26,11 @@ export function readFile(filePath, opts = {}) {
 
     // Directory listing fallback
     if (stat.isDirectory()) {
-        const entries = readdirSync(real, { withFileTypes: true });
-        const listing = entries.map((e) => `${e.isDirectory() ? "d" : "f"} ${e.name}`).join("\n");
-        return `Directory: ${filePath}\n\n\`\`\`\n${listing}\n\`\`\``;
+        const { text } = listDirectory(real, { metadata: true });
+        return `Directory: ${filePath}\n\n\`\`\`\n${text}\n\`\`\``;
     }
 
-    const content = readFileSync(real, "utf-8").replace(/\r\n/g, "\n");
+    const content = readText(real);
     const lines = content.split("\n");
     const total = lines.length;