@levnikolaevich/hex-line-mcp 1.2.0 → 1.3.1

package/lib/tree.mjs

@@ -1,20 +1,24 @@
 /**
- * Compact directory tree with .gitignore support.
+ * Compact directory tree with root .gitignore support.
  *
  * Skips common build/cache dirs by default.
- * Parses .gitignore patterns (simple subset: globs, comments, negation).
+ * Uses `ignore` package for spec-compliant .gitignore matching (path-based, negation, dir-only).
+ * Only root .gitignore is loaded — nested .gitignore files are not supported.
  */
 
 import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
 import { resolve, basename, join, relative } from "node:path";
+import { formatSize, relativeTime, countFileLines } from "./format.mjs";
+import { normalizePath } from "./security.mjs";
+import ignore from "ignore";
 
 const SKIP_DIRS = new Set([
     "node_modules", ".git", "dist", "build", "__pycache__", ".next", "coverage",
 ]);
 
 /**
- * Convert a simple glob pattern to a RegExp.
- * Supports: * (any non-slash), ** (any), ? (single char).
+ * Convert a simple glob pattern to a RegExp for name matching.
+ * Used by pattern-mode to match entry names.
  */
 function globToRegex(pat) {
     return new RegExp(
@@ -27,40 +31,30 @@ function globToRegex(pat) {
 }
 
 /**
- * Parse .gitignore into match functions.
- * Supports: comments (#), negation (!), wildcards (*), dir-only trailing /.
+ * Load root .gitignore into an `ignore` instance.
+ * @param {string} rootDir - absolute path to tree root
+ * @returns {ReturnType<typeof ignore>|null}
  */
-function parseGitignore(content) {
-    const lines = content.replace(/\r\n/g, "\n").split("\n");
-    const patterns = [];
-    for (const raw of lines) {
-        const line = raw.trim();
-        if (!line || line.startsWith("#")) continue;
-        const negate = line.startsWith("!");
-        let pat = negate ? line.slice(1) : line;
-        // Strip leading /
-        if (pat.startsWith("/")) pat = pat.slice(1);
-        // Strip trailing /
-        const dirOnly = pat.endsWith("/");
-        if (dirOnly) pat = pat.slice(0, -1);
-        const re = globToRegex(pat);
-        patterns.push({ re, negate, dirOnly });
-    }
-    return patterns;
-}
-function isIgnored(name, isDir, patterns) {
-    let ignored = false;
-    for (const { re, negate, dirOnly } of patterns) {
-        if (dirOnly && !isDir) continue;
-        if (re.test(name)) ignored = !negate;
-    }
-    return ignored;
+function loadGitignore(rootDir) {
+    const gi = join(rootDir, ".gitignore");
+    if (!existsSync(gi)) return null;
+    try {
+        const content = readFileSync(gi, "utf-8");
+        return ignore().add(content);
+    } catch { return null; }
 }
 
-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`;
+/**
+ * Check if a relative path should be ignored.
+ * @param {ReturnType<typeof ignore>|null} ig - ignore instance (null = no gitignore)
+ * @param {string} relPath - POSIX relative path from tree root
+ * @param {boolean} isDir - true if directory
+ * @returns {boolean}
+ */
+function isIgnored(ig, relPath, isDir) {
+    if (!ig) return false;
+    // ignore package expects dir paths to end with /
+    return ig.ignores(isDir ? relPath + "/" : relPath);
 }
 
 /**
@@ -73,22 +67,12 @@ function findByPattern(dirPath, opts) {
     const re = globToRegex(opts.pattern);
     const filterType = opts.type || "all";
     const maxDepth = opts.max_depth ?? 20;
-    const useGitignore = opts.gitignore ?? true;
 
-    const normalized = (process.platform === "win32" && /^\/[a-zA-Z]\//.test(dirPath))
-        ? dirPath[1] + ":" + dirPath.slice(2) : dirPath;
-    const abs = resolve(normalized);
+    const abs = resolve(normalizePath(dirPath));
     if (!existsSync(abs)) throw new Error(`DIRECTORY_NOT_FOUND: ${abs}`);
     if (!statSync(abs).isDirectory()) throw new Error(`Not a directory: ${abs}`);
 
-    let patterns = [];
-    if (useGitignore) {
-        const gi = join(abs, ".gitignore");
-        if (existsSync(gi)) {
-            try { patterns = parseGitignore(readFileSync(gi, "utf-8")); } catch { /* skip */ }
-        }
-    }
-
+    const ig = (opts.gitignore ?? true) ? loadGitignore(abs) : null;
     const matches = [];
 
     function walk(dir, depth) {
@@ -99,15 +83,15 @@ function findByPattern(dirPath, opts) {
         for (const entry of entries) {
             const isDir = entry.isDirectory();
             if (SKIP_DIRS.has(entry.name) && isDir) continue;
-            if (isIgnored(entry.name, isDir, patterns)) continue;
 
             const full = join(dir, entry.name);
+            const rel = relative(abs, full).replace(/\\/g, "/");
+            if (isIgnored(ig, rel, isDir)) continue;
 
             if (re.test(entry.name)) {
                 if (filterType === "all" ||
                     (filterType === "dir" && isDir) ||
                     (filterType === "file" && !isDir)) {
-                    const rel = relative(abs, full).replace(/\\/g, "/");
                     matches.push(isDir ? rel + "/" : rel);
                 }
             }
@@ -137,35 +121,28 @@ export function directoryTree(dirPath, opts = {}) {
 
     const compact = opts.format === "compact";
     const maxDepth = compact ? 1 : (opts.max_depth ?? 3);
-    const useGitignore = opts.gitignore ?? true;
 
-    // Convert Git Bash /c/path → c:/path on Windows
-    const normalized = (process.platform === "win32" && /^\/[a-zA-Z]\//.test(dirPath))
-        ? dirPath[1] + ":" + dirPath.slice(2) : dirPath;
-    const abs = resolve(normalized);
+    const abs = resolve(normalizePath(dirPath));
     if (!existsSync(abs)) throw new Error(`DIRECTORY_NOT_FOUND: ${abs}. Check path or use directory_tree on parent directory.`);
     const rootStat = statSync(abs);
     if (!rootStat.isDirectory()) throw new Error(`Not a directory: ${abs}`);
 
-    // Load .gitignore
-    let patterns = [];
-    if (useGitignore) {
-        const gi = join(abs, ".gitignore");
-        if (existsSync(gi)) {
-            try { patterns = parseGitignore(readFileSync(gi, "utf-8")); } catch { /* skip */ }
-        }
-    }
+    const ig = (opts.gitignore ?? true) ? loadGitignore(abs) : null;
 
     let totalFiles = 0;
     let totalSize = 0;
     const lines = [];
 
+    /**
+     * Recursive walk. Returns total file count for entire subtree
+     * (including beyond maxDepth — count is always full, display is depth-limited).
+     * Output order: pre-order (dir line before children).
+     */
     function walk(dir, prefix, depth) {
-        if (depth > maxDepth) return;
         let entries;
         try {
             entries = readdirSync(dir, { withFileTypes: true });
-        } catch { return; }
+        } catch { return 0; }
 
         // Sort: directories first, then files, alphabetical
         entries.sort((a, b) => {
@@ -175,56 +152,78 @@ export function directoryTree(dirPath, opts = {}) {
             return a.name.localeCompare(b.name);
         });
 
+        let subTotal = 0;
+
         for (const entry of entries) {
             const name = entry.name;
             const isDir = entry.isDirectory();
 
             if (SKIP_DIRS.has(name) && isDir) continue;
-            if (isIgnored(name, isDir, patterns)) continue;
 
             const full = join(dir, name);
+            const rel = relative(abs, full).replace(/\\/g, "/");
+            if (isIgnored(ig, rel, isDir)) continue;
 
             if (isDir) {
                 if (compact) {
                     lines.push(`${prefix}${name}/`);
                 } else {
-                    // Count files in subdirectory
-                    const subInfo = { files: 0 };
-                    countFiles(full, subInfo);
-                    lines.push(`${prefix}${name}/ (${subInfo.files} files)`);
+                    // Pre-order: placeholder for dir line, patch after recursion
+                    const lineIdx = lines.length;
+                    lines.push("");
+                    const count = depth < maxDepth
+                        ? walk(full, prefix + "  ", depth + 1)
+                        : countSubtreeFiles(full, ig, abs);
+                    lines[lineIdx] = `${prefix}${name}/ (${count} files)`;
+                    subTotal += count;
                 }
-                walk(full, prefix + "  ", depth + 1);
+                if (compact) walk(full, prefix + "  ", depth + 1);
             } else {
                 totalFiles++;
+                subTotal++;
                 if (compact) {
                     lines.push(`${prefix}${name}`);
                 } else {
-                    let size = 0;
-                    try { size = statSync(full).size; } catch { /* skip */ }
+                    let size = 0, mtime = null, lineCount = null;
+                    try {
+                        const st = statSync(full);
+                        size = st.size;
+                        mtime = st.mtime;
+                    } catch { /* skip */ }
                     totalSize += size;
-                    if (size >= 1024) {
-                        lines.push(`${prefix}${name} (${formatSize(size)})`);
-                    } else {
-                        lines.push(`${prefix}${name}`);
-                    }
+                    lineCount = countFileLines(full, size);
+                    const parts = [];
+                    if (lineCount !== null) parts.push(`${lineCount}L`);
+                    parts.push(formatSize(size));
+                    if (mtime) parts.push(relativeTime(mtime, true));
+                    lines.push(`${prefix}${name} (${parts.join(", ")})`);
                 }
             }
         }
+
+        return subTotal;
     }
 
-    function countFiles(dir, info, depth = 0) {
-        if (depth > 10) return; // safety limit for deep trees
+    /**
+     * Count files in subtree without emitting lines (for dirs beyond maxDepth).
+     */
+    function countSubtreeFiles(dir, ig, rootAbs, depth = 0) {
+        if (depth > 10) return 0;
         let entries;
-        try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+        try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return 0; }
+        let count = 0;
         for (const entry of entries) {
             if (SKIP_DIRS.has(entry.name) && entry.isDirectory()) continue;
-            if (isIgnored(entry.name, entry.isDirectory(), patterns)) continue;
+            const full = join(dir, entry.name);
+            const rel = relative(rootAbs, full).replace(/\\/g, "/");
+            if (isIgnored(ig, rel, entry.isDirectory())) continue;
             if (entry.isDirectory()) {
-                countFiles(join(dir, entry.name), info, depth + 1);
+                count += countSubtreeFiles(full, ig, rootAbs, depth + 1);
             } else {
-                info.files++;
+                count++;
             }
         }
+        return count;
     }
 
     const rootName = basename(abs);

package/lib/verify.mjs

@@ -3,9 +3,9 @@
  * Validates range checksums from prior reads.
  */
 
-import { readFileSync } from "node:fs";
 import { fnv1a, rangeChecksum, parseChecksum } from "./hash.mjs";
 import { validatePath } from "./security.mjs";
+import { readText } from "./format.mjs";
 
 /**
  * Verify checksums against current file state.
@@ -16,7 +16,7 @@ import { validatePath } from "./security.mjs";
  */
 export function verifyChecksums(filePath, checksums) {
     const real = validatePath(filePath);
-    const content = readFileSync(real, "utf-8").replace(/\r\n/g, "\n");
+    const content = readText(real);
     const lines = content.split("\n");
 
     // Pre-compute all line hashes

package/output-style.md

@@ -6,7 +6,7 @@ keep-coding-instructions: true
 
 # MCP Tool Preferences
 
-When `hex-line` MCP is available, **always prefer it** over built-in file tools:
+**MANDATORY:** NEVER use built-in Read, Edit, Write, Grep. Use hex-line MCP equivalents:
 
 | Instead of | Use | Why |
 |-----------|-----|-----|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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",
@@ -25,10 +25,16 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.0",
     "diff": "^8.0.3",
+    "ignore": "^7.0.5",
     "tree-sitter-wasms": "^0.1.0",
-    "web-tree-sitter": "^0.25.0"
+    "web-tree-sitter": "^0.25.0",
+    "zod": "^3.24.0"
   },
+  "author": "Lev Nikolaevich <https://github.com/levnikolaevich>",
   "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/levnikolaevich/claude-code-skills/issues"
+  },
   "keywords": [
     "mcp",
     "hex-line",
@@ -40,8 +46,10 @@
     "hash-verified",
     "token-efficiency",
     "hook",
-    "rtk",
-    "bulk-replace"
+    "bulk-replace",
+    "claude",
+    "ai",
+    "llm"
   ],
   "engines": {
     "node": ">=18.0.0"

package/server.mjs

@@ -3,13 +3,15 @@
  * hex-line-mcp — MCP server for hash-verified file operations.
  *
  * 11 tools: read_file, edit_file, write_file, grep_search, outline, verify, directory_tree, get_file_info, setup_hooks, changes, bulk_replace
- * FNV-1a 2-char tags + range checksums (trueline-compatible)
+ * FNV-1a 2-char tags + range checksums
  * Security: root policy, path validation, binary/size rejection
  * Transport: stdio
  */
 
 import { writeFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
+import { createRequire } from "node:module";
+const { version } = createRequire(import.meta.url)("./package.json");
 import { z } from "zod";
 // LLM clients may send booleans as strings ("true"/"false").
 // z.coerce.boolean() is unsafe: Boolean("false") === true.
@@ -54,7 +56,7 @@ try {
     process.exit(1);
 }
 
-const server = new McpServer({ name: "hex-line-mcp", version: "1.2.0" });
+const server = new McpServer({ name: "hex-line-mcp", version });
 
 
 // ==================== read_file ====================
@@ -101,17 +103,19 @@ server.registerTool("read_file", {
 server.registerTool("edit_file", {
     title: "Edit File",
     description:
-        "Edit a file using hash-verified anchors or text replacement. Returns diff. " +
-        "new_text replaces anchor range exactly — include boundary lines if you want to keep them. " +
-        "Preserve indentation from read_file. For anchor edits, read_file first to get hashes.",
+        "Edit a file using hash-verified anchors or text replacement. Returns diff + post-edit checksums. " +
+        "Batch multiple edits in ONE call for atomicity (bottom-to-top auto-sorted). " +
+        "set_line: single line (from grep/read). replace_lines: range with checksum. " +
+        "replace: unique text match, or all:true for rename. insert_after: add below anchor.",
     inputSchema: z.object({
         path: z.string().describe("File to edit"),
         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_checksum":"10-15:a1b2c3d4"}} — range (range_checksum from read_file required)\n' +
+            '{"replace_lines":{"start_anchor":"ab.10","end_anchor":"cd.15","new_text":"...","range_checksum":"10-15:a1b2c3d4"}} — range\n' +
             '{"insert_after":{"anchor":"ab.20","text":"inserted"}} — insert below\n' +
-            '{"replace":{"old_text":"find","new_text":"replace","all":true}} — rename-all (all:true required)',
+            '{"replace":{"old_text":"find","new_text":"replace"}} — unique match\n' +
+            '{"replace":{"old_text":"find","new_text":"replace","all":true}} — replace all',
         ),
         dry_run: flexBool().describe("Preview changes without writing"),
         restore_indent: flexBool().describe("Auto-fix indentation to match anchor (default: false)"),
@@ -159,25 +163,36 @@ server.registerTool("write_file", {
 server.registerTool("grep_search", {
     title: "Search Files",
     description:
-        "Search file contents with ripgrep. Returns hash-annotated matches for direct editing. " +
-        "ALWAYS prefer over shell grep/rg/findstr. Use to find code before read_file or edit_file.",
+        "Search file contents with ripgrep. Returns hash-annotated matches with per-group checksums for direct editing. " +
+        "Output modes: content (default, edit-ready hashes+checksums), files (paths only), count (match counts). " +
+        "For single-line edits: grep -> set_line directly. For range edits: use checksum from grep output. " +
+        "ALWAYS prefer over shell grep/rg/findstr.",
     inputSchema: z.object({
-        pattern: z.string().describe("Regex search pattern"),
+        pattern: z.string().describe("Search pattern (regex by default, literal if literal:true)"),
         path: z.string().optional().describe("Search dir/file (default: cwd)"),
         glob: z.string().optional().describe('Glob filter (e.g. "*.ts")'),
         type: z.string().optional().describe('File type (e.g. "js", "py")'),
+        output: z.enum(["content", "files", "count"]).optional().describe('Output format (default: content)'),
         case_insensitive: flexBool().describe("Ignore case (-i)"),
-        smart_case: flexBool().describe("CI when pattern is all lowercase, CS if it has uppercase (-S)"),
-        context: flexNum().describe("Context lines around matches"),
+        smart_case: flexBool().describe("CI when pattern is all lowercase, CS if uppercase (-S)"),
+        literal: flexBool().describe("Literal string search, no regex (-F)"),
+        multiline: flexBool().describe("Pattern can span multiple lines (-U)"),
+        context: flexNum().describe("Symmetric context lines around matches (-C)"),
+        context_before: flexNum().describe("Context lines BEFORE match (-B)"),
+        context_after: flexNum().describe("Context lines AFTER match (-A)"),
         limit: flexNum().describe("Max matches per file (default: 100)"),
+        total_limit: flexNum().describe("Total match events across all files; multiline matches count as 1 (0 = unlimited)"),
         plain: flexBool().describe("Omit hash tags, return file:line:content"),
     }),
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
 }, async (rawParams) => {
-    const { pattern, path: p, glob, type, case_insensitive, smart_case, context, limit, plain } = coerceParams(rawParams);
+    const { pattern, path: p, glob, type, output, case_insensitive, smart_case, literal, multiline,
+            context, context_before, context_after, limit, total_limit, plain } = coerceParams(rawParams);
     try {
         const result = await grepSearch(pattern, {
-            path: p, glob, type, caseInsensitive: case_insensitive, smartCase: smart_case, context, limit, plain,
+            path: p, glob, type, output, caseInsensitive: case_insensitive, smartCase: smart_case,
+            literal, multiline, context, contextBefore: context_before, contextAfter: context_after,
+            limit, totalLimit: total_limit, plain,
         });
         return { content: [{ type: "text", text: result }] };
     } catch (e) {
@@ -238,7 +253,7 @@ server.registerTool("verify", {
 server.registerTool("directory_tree", {
     title: "Directory Tree",
     description:
-        "Compact directory tree with .gitignore support. " +
+        "Compact directory tree with root .gitignore support (path-based rules, negation). " +
         "Supports pattern glob to find files/dirs by name (like find -name). " +
         "Use to understand repo structure or find specific files/dirs. " +
         "Skips node_modules, .git, dist by default.",
@@ -247,7 +262,7 @@ server.registerTool("directory_tree", {
         pattern: z.string().optional().describe('Glob filter on names (e.g. "*-mcp", "*.mjs"). Returns flat match list instead of tree'),
         type: z.enum(["file", "dir", "all"]).optional().describe('"file", "dir", or "all" (default). Like find -type f/d'),
         max_depth: flexNum().describe("Max recursion depth (default: 3, or 20 in pattern mode)"),
-        gitignore: flexBool().describe("Respect .gitignore patterns (default: true)"),
+        gitignore: flexBool().describe("Respect root .gitignore patterns (default: true). Nested .gitignore not supported"),
         format: z.enum(["compact", "full"]).optional().describe('"compact" = names only, no sizes, depth 1. "full" = default with sizes'),
     }),
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
@@ -287,19 +302,19 @@ server.registerTool("get_file_info", {
 server.registerTool("setup_hooks", {
     title: "Setup Hooks",
     description:
-        "Configure hex-line hooks in CLI agent settings. " +
-        "Claude: writes hooks to ~/.claude/settings.json (global) with absolute path, " +
-        "removes old hooks from per-project settings.local.json. " +
-        "Gemini/Codex: returns guidance (no hook support). " +
-        "Idempotent: re-running produces no changes if already configured.",
+        "Install or uninstall hex-line hooks in CLI agent settings. " +
+        "install: writes hooks to ~/.claude/settings.json, removes old per-project hooks. " +
+        "uninstall: removes hex-line hooks from global settings. " +
+        "Idempotent: re-running produces no changes if already in desired state.",
     inputSchema: z.object({
         agent: z.string().optional().describe('Target agent: "claude", "gemini", "codex", or "all" (default: "all")'),
+        action: z.string().optional().describe('"install" (default) or "uninstall"'),
     }),
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 }, async (rawParams) => {
-    const { agent } = coerceParams(rawParams);
+    const { agent, action } = coerceParams(rawParams);
     try {
-        return { content: [{ type: "text", text: setupHooks(agent) }] };
+        return { content: [{ type: "text", text: setupHooks(agent, action) }] };
     } catch (e) {
         return { content: [{ type: "text", text: e.message }], isError: true };
     }
@@ -365,4 +380,4 @@ server.registerTool("bulk_replace", {
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
-void checkForUpdates("@levnikolaevich/hex-line-mcp", "1.2.0");
+void checkForUpdates("@levnikolaevich/hex-line-mcp", version);