@levnikolaevich/hex-line-mcp 1.0.0

package/hook.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * Unified hook for hex-line-mcp.
+ *
+ * Handles three events:
+ *
+ * PreToolUse:
+ *   - Tool redirect: blocks Read/Edit/Write/Grep for text files,
+ *     redirecting to hex-line MCP equivalents.
+ *   - Bash redirect: blocks simple cat/head/tail/ls/grep/sed/diff
+ *     commands, redirecting to hex-line MCP equivalents.
+ *   - Dangerous command blocker: blocks rm -rf /, force push,
+ *     hard reset, DROP, chmod 777, mkfs, dd, etc.
+ *
+ * PostToolUse:
+ *   - RTK output filter: compresses verbose Bash output
+ *     (npm install, test, build, pip, git) to save context tokens.
+ *
+ * SessionStart:
+ *   - Injects tool preference list into agent context.
+ *
+ * Exit 0 = approve / no feedback / systemMessage
+ * Exit 2 = block (PreToolUse) or feedback via stderr (PostToolUse)
+ */
+
+import { deduplicateLines, smartTruncate } from "./lib/normalize.mjs";
+
+// ---- Constants ----
+
+const BINARY_EXT = 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",
+]);
+
+const TOOL_HINTS = {
+    Read:  "mcp__hex-line__read_file (not Read, not cat/head/tail)",
+    Edit:  "mcp__hex-line__edit_file (not Edit, not sed -i)",
+    Write: "mcp__hex-line__write_file (not Write)",
+    Grep:  "mcp__hex-line__grep_search (not Grep, not grep/rg)",
+    cat:   "mcp__hex-line__read_file (not cat)",
+    head:  "mcp__hex-line__read_file with offset/limit (not head)",
+    tail:  "mcp__hex-line__read_file with offset (not tail)",
+    ls:    "mcp__hex-line__directory_tree (not ls/find/tree)",
+    stat:  "mcp__hex-line__get_file_info (not stat/wc -l)",
+    grep:  "mcp__hex-line__grep_search (not grep/rg)",
+    sed:   "mcp__hex-line__edit_file (not sed -i)",
+    diff:  "mcp__hex-line__changes (not diff)",
+    outline: "mcp__hex-line__outline (before reading large code files)",
+    verify:  "mcp__hex-line__verify (staleness 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)",
+};
+
+const BASH_REDIRECTS = [
+    { regex: /^cat\s+\S+/, key: "cat" },
+    { regex: /^head\s+/, key: "head" },
+    { regex: /^tail\s+/, key: "tail" },
+    { regex: /^(ls|dir)(\s+-\S+)*\s+/, key: "ls" },
+    { regex: /^tree\s+/, key: "ls" },
+    { regex: /^find\s+.*-name/, key: "ls" },
+    { regex: /^(stat|wc\s+-l)\s+/, key: "stat" },
+    { regex: /^(grep|rg)\s+/, key: "grep" },
+    { regex: /^sed\s+-i/, key: "sed" },
+    { regex: /^diff\s+/, key: "diff" },
+];
+
+const TOOL_REDIRECT_MAP = {
+    Read: "Read",
+    Edit: "Edit",
+    Write: "Write",
+    Grep: "Grep",
+};
+
+const 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",
+    },
+];
+
+const COMPOUND_OPERATORS = /[|]|>>?|&&|\|\||;/;
+
+const 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"],
+];
+
+const LINE_THRESHOLD = 50;
+const HEAD_LINES = 15;
+const TAIL_LINES = 15;
+
+// ---- Helpers ----
+
+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 block(reason) {
+    process.stdout.write(JSON.stringify({ decision: "block", reason }));
+    process.exit(2);
+}
+
+// ---- PreToolUse handler ----
+
+function handlePreToolUse(data) {
+    const toolName = data.tool_name || "";
+    const toolInput = data.tool_input || {};
+
+    // Already using hex-line - approve silently
+    if (toolName.startsWith("mcp__hex-line__")) {
+        process.exit(0);
+    }
+
+    // Tool redirect: Read / Edit / Write / Grep
+    const hintKey = TOOL_REDIRECT_MAP[toolName];
+    if (hintKey) {
+        const filePath = toolInput.file_path || toolInput.path || "";
+
+        // Skip binary extensions
+        if (BINARY_EXT.has(extOf(filePath))) {
+            process.exit(0);
+        }
+
+        // Skip plan-mode and system paths (normalize backslashes for Windows)
+        const normalPath = filePath.replace(/\\/g, "/");
+        if (normalPath.includes(".claude/plans/") || normalPath.includes("AppData")) {
+            process.exit(0);
+        }
+
+        // Block with redirect
+        block("Obligatory use " + TOOL_HINTS[hintKey]);
+    }
+
+    // Bash tool checks
+    if (toolName === "Bash") {
+        const command = (toolInput.command || "").trim();
+
+        // User-confirmed bypass
+        if (command.includes("# hex-confirmed")) {
+            process.exit(0);
+        }
+
+        // Dangerous command blocker
+        for (const { regex, reason } of DANGEROUS_PATTERNS) {
+            if (regex.test(command)) {
+                block(
+                    `DANGEROUS: ${reason}. Ask user to confirm, then retry with: # hex-confirmed`
+                );
+            }
+        }
+
+        // Skip compound commands — pipes, redirects, chains are intentional
+        if (COMPOUND_OPERATORS.test(command)) {
+            process.exit(0);
+        }
+
+        // Simple command redirect
+        for (const { regex, key } of BASH_REDIRECTS) {
+            if (regex.test(command)) {
+                block("Obligatory use " + TOOL_HINTS[key]);
+            }
+        }
+    }
+
+    // Everything else - approve
+    process.exit(0);
+}
+
+// ---- PostToolUse handler ----
+
+function handlePostToolUse(data) {
+    const toolName = data.tool_name || "";
+
+    // Only filter Bash output
+    if (toolName !== "Bash") {
+        process.exit(0);
+    }
+
+    const toolInput = data.tool_input || {};
+    const toolResult = data.tool_result;
+    const command = toolInput.command || "";
+
+    // Nothing to filter
+    if (!toolResult || typeof toolResult !== "string") {
+        process.exit(0);
+    }
+
+    const lines = toolResult.split("\n");
+    const originalCount = lines.length;
+
+    // Short output - no filtering
+    if (originalCount < LINE_THRESHOLD) {
+        process.exit(0);
+    }
+
+    const type = detectCommandType(command);
+
+    // Pipeline: deduplicate -> smart truncate
+    const deduped = deduplicateLines(lines);
+    const dedupedText = deduped.join("\n");
+    const filtered = smartTruncate(dedupedText, HEAD_LINES, 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);
+}
+
+// ---- SessionStart: inject tool preferences ----
+
+function handleSessionStart() {
+    const seen = 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 \u2192 built-in Read");
+    lines.push("Bash OK for: npm/node/git/docker/curl, pipes, scripts");
+    const msg = "Hex-line MCP available. ALWAYS prefer:\n" + lines.join("\n");
+    process.stdout.write(JSON.stringify({ systemMessage: msg }));
+    process.exit(0);
+}
+
+// ---- Main: read stdin, route by hook_event_name ----
+
+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 (event === "SessionStart") handleSessionStart();
+        else if (event === "PreToolUse") handlePreToolUse(data);
+        else if (event === "PostToolUse") handlePostToolUse(data);
+        else process.exit(0);
+    } catch {
+        process.exit(0);
+    }
+});

package/lib/bulk-replace.mjs

@@ -0,0 +1,55 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { resolve } from "node:path";
+import { simpleDiff } from "./edit.mjs";
+
+export function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
+    const { dryRun = false, maxFiles = 100 } = opts;
+    const abs = resolve(rootDir);
+
+    // Find files via ripgrep (respects .gitignore)
+    let files;
+    try {
+        const rgOut = execSync(`rg --files -g "${globPattern}" "${abs}"`, { encoding: "utf-8", timeout: 10000 });
+        files = rgOut.trim().split("\n").filter(Boolean);
+    } catch (e) {
+        if (e.status === 1) return "No files matched the glob pattern.";
+        throw new Error(`GREP_ERROR: ${e.message}`);
+    }
+
+    if (files.length > maxFiles) {
+        return `TOO_MANY_FILES: Found ${files.length} files, max_files is ${maxFiles}. Use more specific glob or increase max_files.`;
+    }
+
+    const results = [];
+    let changed = 0, skipped = 0, errors = 0;
+
+    for (const file of files) {
+        try {
+            const original = readFileSync(file, "utf-8").replace(/\r\n/g, "\n");
+            let content = original;
+
+            for (const { old: oldText, new: newText } of replacements) {
+                content = content.split(oldText).join(newText);
+            }
+
+            if (content === original) { skipped++; continue; }
+
+            const diff = simpleDiff(original.split("\n"), content.split("\n"));
+
+            if (!dryRun) {
+                writeFileSync(file, content, "utf-8");
+            }
+
+            const relPath = file.replace(abs, "").replace(/^[/\\]/, "");
+            results.push(`--- ${relPath}\n${diff || "(no visible diff)"}`);
+            changed++;
+        } catch (e) {
+            results.push(`ERROR: ${file}: ${e.message}`);
+            errors++;
+        }
+    }
+
+    const header = `Bulk replace: ${changed} files changed, ${skipped} skipped, ${errors} errors (dry_run: ${dryRun})`;
+    return results.length ? `${header}\n\n${results.join("\n\n")}` : header;
+}

package/lib/changes.mjs

@@ -0,0 +1,174 @@
+/**
+ * Semantic diff: compare file against git ref using AST outlines.
+ *
+ * Shows added/removed/modified symbols — no line-level noise.
+ * Uses outlineFromContent() to parse both current and git versions
+ * without temp files.
+ */
+
+import { execSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { extname } from "node:path";
+import { validatePath } from "./security.mjs";
+import { outlineFromContent } from "./outline.mjs";
+
+/**
+ * Extract symbol name from outline text.
+ * Strips parameters, braces, generics — keeps the identifier.
+ *
+ * "export async function fileOutline(filePath)" → "fileOutline"
+ * "const LANG_CONFIGS = {"                      → "LANG_CONFIGS"
+ * "class MyClass extends Base {"                 → "MyClass"
+ */
+function symbolName(text) {
+    // Remove trailing { and whitespace
+    const clean = text.replace(/\s*\{?\s*$/, "").trim();
+    // Remove everything from first ( onward (params)
+    const noParams = clean.replace(/\(.*$/, "").trim();
+    // Take last word — that's the identifier
+    const parts = noParams.split(/\s+/);
+    // Skip assignment: "const X = ..." → take word before "="
+    const eqIdx = parts.indexOf("=");
+    if (eqIdx > 0) return parts[eqIdx - 1];
+    return parts[parts.length - 1] || text;
+}
+
+/**
+ * Parse outline entries into comparable symbol list.
+ */
+function toSymbolMap(entries) {
+    const map = new Map();
+    for (const e of entries) {
+        const name = symbolName(e.text);
+        const lines = e.end - e.start + 1;
+        map.set(name, { name, text: e.text, lines, start: e.start, end: e.end });
+    }
+    return map;
+}
+
+/**
+ * Get relative path from git root for `git show`.
+ */
+function gitRelativePath(absPath) {
+    const root = execSync("git rev-parse --show-toplevel", {
+        cwd: absPath.replace(/[/\\][^/\\]+$/, ""),
+        encoding: "utf-8",
+        timeout: 5000,
+    }).trim().replace(/\\/g, "/");
+
+    const normalized = absPath.replace(/\\/g, "/");
+    // Ensure root and path are comparable (case-insensitive on Windows)
+    const rootLower = root.toLowerCase();
+    const pathLower = normalized.toLowerCase();
+    if (!pathLower.startsWith(rootLower)) {
+        throw new Error(`File ${absPath} is not inside git repo ${root}`);
+    }
+    return normalized.slice(root.length + 1);
+}
+
+/**
+ * Compare file against git ref, returning semantic symbol diff.
+ *
+ * @param {string} filePath        File path (absolute or relative)
+ * @param {string} compareAgainst  Git ref (default: "HEAD")
+ * @returns {Promise<string>}      Formatted diff
+ */
+export async function fileChanges(filePath, compareAgainst = "HEAD") {
+    const real = validatePath(filePath);
+
+    // Directory: return git diff --stat (compact file list, no content reads)
+    if (statSync(real).isDirectory()) {
+        try {
+            const stat = execSync(`git diff --stat "${compareAgainst}" -- .`, {
+                cwd: real,
+                encoding: "utf-8",
+                timeout: 10000,
+            }).trim();
+            if (!stat) return `No changes in ${filePath} vs ${compareAgainst}`;
+            return `Changed files in ${filePath} vs ${compareAgainst}:\n\n${stat}\n\nUse changes on a specific file for symbol-level diff.`;
+        } catch {
+            return `No git history for ${filePath} or not a git repository.`;
+        }
+    }
+
+    const ext = extname(real).toLowerCase();
+
+    // Check if outline supports this extension
+    const currentContent = readFileSync(real, "utf-8").replace(/\r\n/g, "\n");
+    const currentResult = await outlineFromContent(currentContent, ext);
+    if (!currentResult) {
+        return `Cannot outline ${ext} files. Supported: .js .mjs .ts .py .go .rs .java .c .cpp .cs .rb .php .kt .swift .sh .bash`;
+    }
+
+    // Get git version
+    const relPath = gitRelativePath(real);
+    let gitContent;
+    try {
+        gitContent = execSync(`git show "${compareAgainst}:${relPath}"`, {
+            cwd: real.replace(/[/\\][^/\\]+$/, ""),
+            encoding: "utf-8",
+            timeout: 5000,
+        }).replace(/\r\n/g, "\n");
+    } catch {
+        return `NEW FILE: ${filePath} (not in ${compareAgainst})`;
+    }
+
+    // Outline the git version from content — no temp files
+    const gitResult = await outlineFromContent(gitContent, ext);
+    if (!gitResult) {
+        return `Cannot outline git version of ${filePath}`;
+    }
+
+    // Compare symbol maps
+    const currentMap = toSymbolMap(currentResult.entries);
+    const gitMap = toSymbolMap(gitResult.entries);
+
+    const added = [];
+    const removed = [];
+    const modified = [];
+
+    for (const [name, sym] of currentMap) {
+        if (!gitMap.has(name)) {
+            added.push(sym);
+        } else {
+            const gitSym = gitMap.get(name);
+            if (gitSym.lines !== sym.lines) {
+                modified.push({ current: sym, git: gitSym });
+            }
+        }
+    }
+    for (const [name, sym] of gitMap) {
+        if (!currentMap.has(name)) {
+            removed.push(sym);
+        }
+    }
+
+    // Format
+    const parts = [`Changes in ${filePath} vs ${compareAgainst}:`];
+
+    if (added.length) {
+        parts.push("\nAdded:");
+        for (const s of added) parts.push(`  + ${s.start}-${s.end}: ${s.text}`);
+    }
+    if (removed.length) {
+        parts.push("\nRemoved:");
+        for (const s of removed) parts.push(`  - ${s.start}-${s.end}: ${s.text}`);
+    }
+    if (modified.length) {
+        parts.push("\nModified:");
+        for (const m of modified) {
+            const delta = m.current.lines - m.git.lines;
+            const sign = delta > 0 ? "+" : "";
+            parts.push(`  ~ ${m.current.start}-${m.current.end}: ${m.current.text}  (${sign}${delta} lines)`);
+        }
+    }
+
+    if (!added.length && !removed.length && !modified.length) {
+        parts.push("\nNo symbol changes detected.");
+    }
+
+    const summary = `${added.length} added, ${removed.length} removed, ${modified.length} modified`;
+    parts.push(`\nSummary: ${summary}`);
+
+    return parts.join("\n");
+}

package/lib/coerce.mjs

@@ -0,0 +1,43 @@
+/**
+ * Parameter aliases: common alternative names -> canonical schema names.
+ * Applied BEFORE Zod validation so agents sending wrong param names still work.
+ */
+
+const ALIASES = {
+    // read_file
+    file_path: "path",
+    filePath: "path",
+    file: "path",
+
+    // grep_search
+    query: "pattern",
+    search: "pattern",
+    max_results: "limit",
+    maxResults: "limit",
+    maxMatches: "limit",
+    max_matches: "limit",
+    contextLines: "context",
+    context_lines: "context",
+    ignoreCase: "case_insensitive",
+    ignore_case: "case_insensitive",
+
+    // edit_file
+    dryRun: "dry_run",
+    "dry-run": "dry_run",
+
+    // directory_tree
+    maxDepth: "max_depth",
+    depth: "max_depth",
+};
+
+export function coerceParams(params) {
+    if (!params || typeof params !== "object") return params;
+    const result = { ...params };
+    for (const [alias, canonical] of Object.entries(ALIASES)) {
+        if (alias in result && !(canonical in result)) {
+            result[canonical] = result[alias];
+            delete result[alias];
+        }
+    }
+    return result;
+}