@levnikolaevich/hex-line-mcp 1.1.0 → 1.1.2

package/README.md

@@ -43,13 +43,8 @@ PreToolUse also intercepts simple Bash commands: cat, head, tail, ls, tree, find
 ### MCP Server
 
 ```bash
-claude mcp add -s user hex-line -- node path/to/mcp/hex-line-mcp/server.mjs
-```
-
-Then install dependencies:
-
-```bash
-cd mcp/hex-line-mcp && npm install
+npm i -g @levnikolaevich/hex-line-mcp
+claude mcp add -s user hex-line -- hex-line-mcp
 ```
 
 ### Hooks
@@ -60,16 +55,7 @@ Automatic setup (run once after MCP install):
 mcp__hex-line__setup_hooks(agent="claude")
 ```
 
-Or manual — add to `.claude/settings.local.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [{"matcher": "Read|Edit|Write|Grep|Bash", "hooks": [{"type": "command", "command": "node mcp/hex-line-mcp/hook.mjs", "timeout": 5}]}],
-    "PostToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "node mcp/hex-line-mcp/hook.mjs", "timeout": 10}]}]
-  }
-}
-```
+Hooks are written to global `~/.claude/settings.json` with absolute path to `hook.mjs` from the global npm install. Manual configuration is not needed.
 
 ### Output Style
 

package/hook.mjs

@@ -62,17 +62,14 @@ const TOOL_HINTS = {
 const BASH_REDIRECTS = [
     { regex: /^cat\s+\S+/, key: "cat" },
     { regex: /^head\s+/, key: "head" },
-    { regex: /^tail\s+/, key: "tail" },
+    { regex: /^tail\s+(?!-[fF])/, key: "tail" },
     { regex: /^(less|more)\s+/, key: "cat" },
     { regex: /^(ls|dir)(\s+-\S+)*\s+/, key: "ls" },
     { regex: /^tree\s+/, key: "ls" },
     { regex: /^find\s+/, key: "ls" },
-    { regex: /^du\s+/, key: "ls" },
     { regex: /^(stat|wc)\s+/, key: "stat" },
-    { regex: /^file\s+/, key: "stat" },
     { regex: /^(grep|rg)\s+/, key: "grep" },
     { regex: /^sed\s+-i/, key: "sed" },
-    { regex: /^diff\s+/, key: "diff" },
 ];
 
 const TOOL_REDIRECT_MAP = {
@@ -197,9 +194,13 @@ function handlePreToolUse(data) {
             process.exit(0);
         }
 
+        // Strip heredoc bodies to avoid false positives on data content
+        // e.g. gh api -f body="$(cat <<'EOF'\n...rm -rf...\nEOF)"
+        const cmdCheck = command.replace(/<<['"]?(\w+)['"]?\s*\n[\s\S]*?\n\1/g, "");
+
         // Dangerous command blocker
         for (const { regex, reason } of DANGEROUS_PATTERNS) {
-            if (regex.test(command)) {
+            if (regex.test(cmdCheck)) {
                 block(
                     `DANGEROUS: ${reason}. Ask user to confirm, then retry with: # hex-confirmed`,
                     `Original command: ${command.slice(0, 100)}`
@@ -207,8 +208,16 @@ function handlePreToolUse(data) {
             }
         }
 
-        // Skip compound commands — pipes, redirects, chains are intentional
+        // Compound commands: check first command in pipe before skipping
         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);
         }
 

package/lib/edit.mjs

@@ -10,7 +10,7 @@
 
 import { readFileSync, writeFileSync } from "node:fs";
 import { diffLines } from "diff";
-import { fnv1a, lineTag } from "./hash.mjs";
+import { fnv1a, lineTag, rangeChecksum } from "./hash.mjs";
 import { validatePath } from "./security.mjs";
 import { getGraphDB, blastRadius, getRelativePath } from "./graph-enrich.mjs";
 
@@ -242,6 +242,9 @@ function textReplace(content, oldText, newText, all) {
     const normOld = oldText.replace(/\r\n/g, "\n");
     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.");
+    }
     let idx = norm.indexOf(normOld);
     let confusableMatch = false;
     if (idx === -1) {
@@ -267,74 +270,25 @@ function textReplace(content, oldText, newText, all) {
     // Determine the match length in original content (same as normOld.length for both paths)
     const matchLen = normOld.length;
 
-    if (all) {
-        if (confusableMatch) {
-            // Replace all via normalized matching
-            const normContent = normalizeConfusables(norm);
-            const normSearch = normalizeConfusables(normOld);
-            let result = "";
-            let pos = 0;
-            let searchIdx = normContent.indexOf(normSearch, pos);
-            while (searchIdx !== -1) {
-                result += norm.slice(pos, searchIdx) + normNew;
-                pos = searchIdx + matchLen;
-                searchIdx = normContent.indexOf(normSearch, pos);
-            }
-            result += norm.slice(pos);
-            return result;
-        }
-        return norm.split(normOld).join(normNew);
-    }
-
-    // Check for multiple matches — return hash-hint instead of opaque error
-    const positions = [];
     if (confusableMatch) {
+        // Replace all via normalized matching
         const normContent = normalizeConfusables(norm);
         const normSearch = normalizeConfusables(normOld);
-        let searchPos = 0;
-        while ((searchPos = normContent.indexOf(normSearch, searchPos)) !== -1) {
-            positions.push(searchPos);
-            searchPos += normSearch.length;
-        }
-    } else {
-        let searchPos = 0;
-        while ((searchPos = norm.indexOf(normOld, searchPos)) !== -1) {
-            positions.push(searchPos);
-            searchPos += normOld.length;
+        let result = "";
+        let pos = 0;
+        let searchIdx = normContent.indexOf(normSearch, pos);
+        while (searchIdx !== -1) {
+            result += norm.slice(pos, searchIdx) + normNew;
+            pos = searchIdx + matchLen;
+            searchIdx = normContent.indexOf(normSearch, pos);
         }
+        result += norm.slice(pos);
+        return result;
     }
-
-    if (positions.length > 1) {
-        const allLines = norm.split("\n");
-        const matchLineCount = normOld.split("\n").length;
-        const snippets = positions.map((charPos, i) => {
-            let cumLen = 0, matchLine = 0;
-            for (let l = 0; l < allLines.length; l++) {
-                cumLen += allLines[l].length + 1;
-                if (cumLen > charPos) { matchLine = l; break; }
-            }
-            const start = Math.max(0, matchLine - 1);
-            const end = Math.min(allLines.length, matchLine + matchLineCount + 1);
-            const lines = allLines.slice(start, end).map((line, j) => {
-                const num = start + j + 1;
-                const tag = lineTag(fnv1a(line));
-                return `${tag}.${num}\t${line}`;
-            });
-            return `Match ${i + 1} (lines ${start + 1}-${end}):\n${lines.join("\n")}`;
-        });
-
-        throw new Error(
-            `HASH_HINT: Found ${positions.length} match(es) for replace. Use anchor-based edit for precision.\n\n` +
-            snippets.join("\n\n") +
-            `\n\nRetry with: [{"set_line":{"anchor":"XX.NN","new_text":"..."}}] or [{"replace_lines":{"start_anchor":"XX.NN","end_anchor":"YY.MM","new_text":"..."}}]`
-        );
-    }
-
-    return norm.slice(0, idx) + normNew + norm.slice(idx + matchLen);
+    return norm.split(normOld).join(normNew);
 }
 
 
-
 /**
  * Apply edits to a file.
  *
@@ -390,6 +344,17 @@ export function editFile(filePath, edits, opts = {}) {
             const en = parseRef(e.replace_lines.end_anchor);
             const si = findLine(lines, s.line, s.tag, hashIndex);
             const ei = findLine(lines, en.line, en.tag, hashIndex);
+
+            // 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;
+            const lineHashes = [];
+            for (let i = si; i <= ei; i++) lineHashes.push(fnv1a(lines[i]));
+            const actual = rangeChecksum(lineHashes, s.line, en.line);
+            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}.`);
+
             const txt = e.replace_lines.new_text;
             if (!txt && txt !== 0) {
                 lines.splice(si, ei - si + 1);

package/lib/setup.mjs

@@ -171,26 +171,32 @@ function installOutputStyle() {
     mkdirSync(dirname(target), { recursive: true });
     writeFileSync(target, readFileSync(source, "utf-8"), "utf-8");
 
-    // Check outputStyle in all scopes (Local > Project > User)
-    const scopes = [
-        { path: resolve(process.cwd(), ".claude/settings.local.json"), label: "local" },
-        { path: resolve(process.cwd(), ".claude/settings.json"), label: "project" },
-        { path: resolve(homedir(), ".claude/settings.json"), label: "user" },
-    ];
-
-    for (const scope of scopes) {
-        const config = readJson(scope.path);
-        if (config && config.outputStyle) {
-            return `Output style 'hex-line' installed to ~/.claude/output-styles/. Current style '${config.outputStyle}' preserved (scope: ${scope.label}). Switch via /config > Output style`;
-        }
-    }
-
-    // No outputStyle set anywhere — activate hex-line at user level
+    // Set hex-line at user (global) level
     const userSettings = resolve(homedir(), ".claude/settings.json");
     const config = readJson(userSettings) || {};
+    const prev = config.outputStyle;
     config.outputStyle = "hex-line";
     writeJson(userSettings, config);
-    return "Output style 'hex-line' installed and activated in ~/.claude/settings.json";
+
+    // Remove outputStyle from local/project scopes so global is not overridden
+    const overrides = [
+        resolve(process.cwd(), ".claude/settings.local.json"),
+        resolve(process.cwd(), ".claude/settings.json"),
+    ];
+    const cleared = [];
+    for (const p of overrides) {
+        const c = readJson(p);
+        if (c && c.outputStyle) {
+            cleared.push(`${c.outputStyle} (${p.includes("local") ? "local" : "project"})`);
+            delete c.outputStyle;
+            writeJson(p, c);
+        }
+    }
+
+    let msg = "Output style 'hex-line' installed and activated globally";
+    if (prev && prev !== "hex-line") msg += ` (was '${prev}')`;
+    if (cleared.length) msg += `. Removed overrides: ${cleared.join(", ")}`;
+    return msg;
 }
 
 // ---- Agent configurators ----

package/output-style.md

@@ -1,6 +1,6 @@
 ---
 name: hex-line
-description: Prefer hex-line MCP tools over built-in Read/Edit/Write/Grep
+description: hex-line MCP tool preferences + explanatory coding style with insights
 keep-coding-instructions: true
 ---
 
@@ -25,3 +25,17 @@ NEVER read a large file in full — outline+targeted read saves 75% tokens.
 
 Bash OK for: npm/node/git/docker/curl, pipes, compound commands.
 **Exceptions** (use built-in Read): images, PDFs, Jupyter notebooks.
+
+# Explanatory Style
+
+Provide educational insights about the codebase alongside task completion. When providing insights, you may exceed typical length constraints, but remain focused and relevant.
+
+## 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`"
+
+Focus on insights specific to the codebase or the code just written, not general programming concepts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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.",
   "main": "server.mjs",

package/server.mjs

@@ -54,7 +54,7 @@ try {
     process.exit(1);
 }
 
-const server = new McpServer({ name: "hex-line-mcp", version: "1.1.0" });
+const server = new McpServer({ name: "hex-line-mcp", version: "1.1.2" });
 
 
 // ==================== read_file ====================
@@ -109,9 +109,9 @@ server.registerTool("edit_file", {
         edits: z.string().describe(
             'JSON array. Examples:\n' +
             '{"set_line":{"anchor":"ab.12","new_text":"new"}} — replace line\n' +
-            '{"replace_lines":{"start_anchor":"ab.10","end_anchor":"cd.15","new_text":"..."}} — range\n' +
+            '{"replace_lines":{"start_anchor":"ab.10","end_anchor":"cd.15","new_text":"...","range_checksum":"10-15:a1b2c3d4"}} — range (range_checksum from read_file required)\n' +
             '{"insert_after":{"anchor":"ab.20","text":"inserted"}} — insert below\n' +
-            '{"replace":{"old_text":"find","new_text":"replace","all":false}} — text match',
+            '{"replace":{"old_text":"find","new_text":"replace","all":true}} — rename-all (all:true required)',
         ),
         dry_run: flexBool().describe("Preview changes without writing"),
         restore_indent: flexBool().describe("Auto-fix indentation to match anchor (default: false)"),
@@ -364,4 +364,4 @@ server.registerTool("bulk_replace", {
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
-void checkForUpdates("@levnikolaevich/hex-line-mcp", "1.0.0");
+void checkForUpdates("@levnikolaevich/hex-line-mcp", "1.1.2");