@levnikolaevich/hex-line-mcp 1.0.0

package/lib/search.mjs

@@ -0,0 +1,132 @@
+/**
+ * File search via ripgrep with hash-annotated results.
+ * Uses spawn with arg arrays (no shell string interpolation).
+ */
+
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { fnv1a, lineTag } from "./hash.mjs";
+import { getGraphDB, matchAnnotation, getRelativePath } from "./graph-enrich.mjs";
+
+const DEFAULT_LIMIT = 100;
+const MAX_OUTPUT = 10 * 1024 * 1024; // 10 MB
+const TIMEOUT = 30000; // 30s
+
+/**
+ * Search files using ripgrep.
+ *
+ * @param {string} pattern - regex pattern
+ * @param {object} opts - { path, glob, type, caseInsensitive, context, limit, plain }
+ * @returns {Promise<string>} formatted results
+ */
+export function grepSearch(pattern, opts = {}) {
+    return new Promise((resolve_, reject) => {
+        // Convert Git Bash /c/path → c:/path on Windows
+        const rawPath = opts.path || "";
+        const normPath = (process.platform === "win32" && /^\/[a-zA-Z]\//.test(rawPath))
+            ? rawPath[1] + ":" + rawPath.slice(2) : rawPath;
+        const target = normPath ? resolve(normPath) : process.cwd();
+        const args = ["-n", "--no-heading", "--with-filename"];
+        const plain = !!opts.plain;
+
+        if (opts.caseInsensitive) args.push("-i");
+        if (opts.context && opts.context > 0) args.push("-C", String(opts.context));
+        if (opts.glob) args.push("--glob", opts.glob);
+        if (opts.type) args.push("--type", opts.type);
+
+        const limit = (opts.limit && opts.limit > 0) ? opts.limit : DEFAULT_LIMIT;
+        args.push("-m", String(limit));
+        args.push("--", pattern, target);
+
+        let stdout = "";
+        let totalBytes = 0;
+        let killed = false;
+
+        const child = spawn("rg", args, { timeout: TIMEOUT });
+
+        child.stdout.on("data", (chunk) => {
+            totalBytes += chunk.length;
+            if (totalBytes > MAX_OUTPUT) {
+                killed = true;
+                child.kill();
+                return;
+            }
+            stdout += chunk.toString("utf-8");
+        });
+
+        let stderrBuf = "";
+        child.stderr.on("data", (chunk) => { stderrBuf += chunk.toString("utf-8"); });
+
+        child.on("error", (err) => {
+            if (err.code === "ENOENT") {
+                reject(new Error("ripgrep (rg) not found. Install: https://github.com/BurntSushi/ripgrep#installation"));
+            } else {
+                reject(new Error(`rg spawn error: ${err.message}`));
+            }
+        });
+
+        child.on("close", (code) => {
+            if (killed) {
+                resolve_("GREP_OUTPUT_TRUNCATED: exceeded 10MB. Use specific glob/path.");
+                return;
+            }
+            if (code === 1) {
+                resolve_("No matches found.");
+                return;
+            }
+            if (code !== 0 && code !== null) {
+                const reason = stderrBuf.trim() || "unknown error";
+                reject(new Error(`GREP_ERROR: rg exit ${code} — ${reason}`));
+                return;
+            }
+
+            // Format results with hash tags
+            const resultLines = stdout.trimEnd().split("\n");
+            const formatted = [];
+            const db = getGraphDB(target);
+            const relCache = new Map();
+
+            // Match line: file:42:content
+            const matchRe = /^((?:[A-Za-z]:)?[^:]*):(\d+):(.*)$/;
+            // Context line: file-42-content
+            const ctxRe = /^((?:[A-Za-z]:)?[^-]*)-(\d+)-(.*)$/;
+
+            if (plain) {
+                // Plain mode: file:line:content without hash tags
+                for (const rl of resultLines) {
+                    formatted.push(rl);
+                }
+            } else {
+                for (const rl of resultLines) {
+                    if (!rl || rl === "--") { formatted.push(rl); continue; }
+                    // Normalize backslashes for consistent regex matching on Windows
+                    const nl = rl.replace(/\\/g, "/");
+
+                    const m = matchRe.exec(nl);
+                    if (m) {
+                        const tag = lineTag(fnv1a(m[3]));
+                        let anno = "";
+                        if (db) {
+                            let rel = relCache.get(m[1]);
+                            if (rel === undefined) { rel = getRelativePath(resolve(m[1])) || ""; relCache.set(m[1], rel); }
+                            if (rel) { const a = matchAnnotation(db, rel, +m[2]); if (a) anno = `  ${a}`; }
+                        }
+                        formatted.push(`${m[1]}:>>${tag}.${m[2]}\t${m[3]}${anno}`);
+                        continue;
+                    }
+
+                    const c = ctxRe.exec(nl);
+                    if (c) {
+                        const tag = lineTag(fnv1a(c[3]));
+                        formatted.push(`${c[1]}:  ${tag}.${c[2]}\t${c[3]}`);
+                        continue;
+                    }
+
+                    formatted.push(rl);
+                }
+            }
+
+            resolve_(`\`\`\`\n${formatted.join("\n")}\n\`\`\``);
+        });
+    });
+}

package/lib/security.mjs

@@ -0,0 +1,114 @@
+/**
+ * Security boundaries for file operations.
+ *
+ * Claude Code provides its own sandbox (permissions, project scope).
+ * This module handles: path canonicalization, symlink resolution,
+ * binary file detection, and size limits.
+ */
+
+import { realpathSync, statSync, existsSync, readdirSync, openSync, readSync, closeSync } from "node:fs";
+import { resolve, isAbsolute, dirname } from "node:path";
+
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MB
+
+/**
+ * Convert Git Bash /c/Users/... → c:/Users/... on Windows.
+ * Node.js resolve() treats /c/ as absolute from current drive root, producing D:\c\Users.
+ */
+function normalizePath(p) {
+    if (process.platform === "win32" && /^\/[a-zA-Z]\//.test(p)) {
+        return p[1] + ":" + p.slice(2);
+    }
+    return p;
+}
+
+/**
+ * Validate a file path against security boundaries.
+ * Returns the canonicalized absolute path.
+ * Throws on violation.
+ */
+export function validatePath(filePath) {
+    if (!filePath) throw new Error("Empty file path");
+
+    const normalized = normalizePath(filePath);
+    const abs = isAbsolute(normalized) ? normalized : resolve(process.cwd(), normalized);
+
+    // Check existence — show parent directory contents as fallback
+    if (!existsSync(abs)) {
+        let hint = "";
+        try {
+            const parent = dirname(abs);
+            if (existsSync(parent)) {
+                const entries = readdirSync(parent, { withFileTypes: true });
+                const listing = entries.slice(0, 20).map(e =>
+                    `  ${e.isDirectory() ? "d" : "f"} ${e.name}`
+                ).join("\n");
+                hint = `\n\nParent directory ${parent} contains:\n${listing}`;
+                if (entries.length > 20) hint += `\n  ... (${entries.length - 20} more)`;
+            }
+        } catch {}
+        throw new Error(`FILE_NOT_FOUND: ${abs}${hint}`);
+    }
+
+    // Canonicalize (resolves symlinks)
+    let real;
+    try {
+        real = realpathSync(abs);
+    } catch (e) {
+        throw new Error(`Cannot resolve path: ${abs} (${e.message})`);
+    }
+
+    // Check file type
+    const stat = statSync(real);
+    if (stat.isDirectory()) return real; // directories allowed for listing
+    if (!stat.isFile()) {
+        const type = stat.isSymbolicLink() ? "symlink" : "special";
+        throw new Error(`NOT_REGULAR_FILE: ${real} (${type}). Cannot read special files.`);
+    }
+
+    // Size check
+    if (stat.size > MAX_FILE_SIZE) {
+        throw new Error(`FILE_TOO_LARGE: ${real} (${(stat.size / 1024 / 1024).toFixed(1)}MB, max ${MAX_FILE_SIZE / 1024 / 1024}MB). Use offset/limit to read a range.`);
+    }
+
+    // Binary detection (check first 8KB for null bytes — only read 8KB, not whole file)
+    const bfd = openSync(real, "r");
+    const probe = Buffer.alloc(8192);
+    const bytesRead = readSync(bfd, probe, 0, 8192, 0);
+    closeSync(bfd);
+    for (let i = 0; i < bytesRead; i++) {
+        if (probe[i] === 0) {
+            throw new Error(`BINARY_FILE: ${real}. Use built-in Read tool (supports images, PDFs, notebooks).`);
+        }
+    }
+
+    return real;
+}
+
+/**
+ * Validate path for write (does NOT require file to exist).
+ * Resolves to absolute path, validates parent exists or can be created.
+ */
+export function validateWritePath(filePath) {
+    if (!filePath) throw new Error("Empty file path");
+
+    const normalized = normalizePath(filePath);
+    const abs = isAbsolute(normalized) ? normalized : resolve(process.cwd(), normalized);
+
+    // For write, the file might not exist yet — validate the parent directory
+    if (!existsSync(abs)) {
+        const parent = resolve(abs, "..");
+        if (!existsSync(parent)) {
+            // Walk up to find an existing ancestor (parent dirs will be created by write_file)
+            let ancestor = resolve(parent, "..");
+            while (!existsSync(ancestor) && ancestor !== resolve(ancestor, "..")) {
+                ancestor = resolve(ancestor, "..");
+            }
+            if (!existsSync(ancestor)) {
+                throw new Error(`No existing ancestor directory for: ${abs}`);
+            }
+        }
+    }
+
+    return abs;
+}

package/lib/setup.mjs

@@ -0,0 +1,132 @@
+/**
+ * Setup hex-line hooks for CLI agents.
+ *
+ * Idempotent: re-running with same config produces no changes.
+ * Supports: claude (hooks in settings.local.json), gemini, codex (info only).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+
+const HOOK_COMMAND = "node mcp/hex-line-mcp/hook.mjs";
+
+const CLAUDE_HOOKS = {
+    SessionStart: {
+        matcher: "*",
+        hooks: [{ type: "command", command: HOOK_COMMAND, timeout: 5 }],
+    },
+    PreToolUse: {
+        matcher: "Read|Edit|Write|Grep|Bash",
+        hooks: [{ type: "command", command: HOOK_COMMAND, timeout: 5 }],
+    },
+    PostToolUse: {
+        matcher: "Bash",
+        hooks: [{ type: "command", command: HOOK_COMMAND, timeout: 10 }],
+    },
+};
+
+// ---- Helpers ----
+
+function readJson(filePath) {
+    if (!existsSync(filePath)) return null;
+    return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+
+function writeJson(filePath, data) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Find existing hook entry index by command substring.
+ * @param {Array} entries - Array of {matcher, hooks[]} objects
+ * @param {string} command - Command string to match
+ * @returns {number} Index or -1
+ */
+function findEntryByCommand(entries, command) {
+    return entries.findIndex(
+        (e) => Array.isArray(e.hooks) && e.hooks.some((h) => h.command === command)
+    );
+}
+
+// ---- Agent configurators ----
+
+function setupClaude() {
+    const settingsPath = resolve(process.cwd(), ".claude/settings.local.json");
+    const config = readJson(settingsPath) || {};
+
+    if (!config.hooks || typeof config.hooks !== "object") {
+        config.hooks = {};
+    }
+
+    let changed = false;
+
+    for (const [event, desired] of Object.entries(CLAUDE_HOOKS)) {
+        if (!Array.isArray(config.hooks[event])) {
+            config.hooks[event] = [];
+        }
+
+        const entries = config.hooks[event];
+        const idx = findEntryByCommand(entries, HOOK_COMMAND);
+
+        if (idx >= 0) {
+            // Entry exists — check if matcher and timeout match
+            const existing = entries[idx];
+            if (existing.matcher === desired.matcher &&
+                existing.hooks.length === desired.hooks.length &&
+                existing.hooks[0].timeout === desired.hooks[0].timeout) {
+                continue; // Already configured exactly
+            }
+            // Update in place
+            entries[idx] = { matcher: desired.matcher, hooks: [...desired.hooks] };
+            changed = true;
+        } else {
+            entries.push({ matcher: desired.matcher, hooks: [...desired.hooks] });
+            changed = true;
+        }
+    }
+
+    if (config.disableAllHooks !== false) {
+        config.disableAllHooks = false;
+        changed = true;
+    }
+
+    if (!changed) {
+        return "Claude: already configured, no changes";
+    }
+
+    writeJson(settingsPath, config);
+    return "Claude: PreToolUse + PostToolUse -> mcp/hex-line-mcp/hook.mjs OK";
+}
+
+function setupGemini() {
+    return "Gemini: Not supported (Gemini CLI does not support hooks. Add MCP Tool Preferences to GEMINI.md instead)";
+}
+
+function setupCodex() {
+    return "Codex: Not supported (Codex CLI does not support hooks. Add MCP Tool Preferences to AGENTS.md instead)";
+}
+
+// ---- Public API ----
+
+const AGENTS = { claude: setupClaude, gemini: setupGemini, codex: setupCodex };
+
+/**
+ * Configure hex-line hooks for one or all supported agents.
+ * @param {string} [agent="all"] - "claude", "gemini", "codex", or "all"
+ * @returns {string} Status report
+ */
+export function setupHooks(agent = "all") {
+    const target = (agent || "all").toLowerCase();
+
+    if (target !== "all" && !AGENTS[target]) {
+        throw new Error(`UNKNOWN_AGENT: '${agent}'. Supported: claude, gemini, codex, all`);
+    }
+
+    const targets = target === "all" ? Object.keys(AGENTS) : [target];
+    const results = targets.map((name) => "  " + AGENTS[name]());
+
+    const header = `Hooks configured for ${target}:`;
+    const footer = "\nRestart Claude Code to apply hook changes.";
+    return [header, ...results, footer].join("\n");
+}

package/lib/tree.mjs

@@ -0,0 +1,162 @@
+/**
+ * Compact directory tree with .gitignore support.
+ *
+ * Skips common build/cache dirs by default.
+ * Parses .gitignore patterns (simple subset: globs, comments, negation).
+ */
+
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { resolve, basename, join } from "node:path";
+
+const SKIP_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", "__pycache__", ".next", "coverage",
+]);
+
+/**
+ * Parse .gitignore into match functions.
+ * Supports: comments (#), negation (!), wildcards (*), dir-only trailing /.
+ */
+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);
+        // Convert glob to regex
+        const re = new RegExp(
+            "^" + pat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, ".*").replace(/\?/g, ".") + "$"
+        );
+        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 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`;
+}
+
+/**
+ * Build directory tree recursively.
+ * @param {string} dirPath - Absolute directory path
+ * @param {object} opts - { max_depth, gitignore, format }
+ * @returns {string} Formatted tree
+ */
+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);
+    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 */ }
+        }
+    }
+
+    let totalFiles = 0;
+    let totalSize = 0;
+    const lines = [];
+
+    function walk(dir, prefix, depth) {
+        if (depth > maxDepth) return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        } catch { return; }
+
+        // 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);
+        });
+
+        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);
+
+            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)`);
+                }
+                walk(full, prefix + "  ", depth + 1);
+            } else {
+                totalFiles++;
+                if (compact) {
+                    lines.push(`${prefix}${name}`);
+                } else {
+                    let size = 0;
+                    try { size = statSync(full).size; } catch { /* skip */ }
+                    totalSize += size;
+                    if (size >= 1024) {
+                        lines.push(`${prefix}${name} (${formatSize(size)})`);
+                    } else {
+                        lines.push(`${prefix}${name}`);
+                    }
+                }
+            }
+        }
+    }
+
+    function countFiles(dir, info, depth = 0) {
+        if (depth > 10) return; // safety limit for deep trees
+        let entries;
+        try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+        for (const entry of entries) {
+            if (SKIP_DIRS.has(entry.name) && entry.isDirectory()) continue;
+            if (isIgnored(entry.name, entry.isDirectory(), patterns)) continue;
+            if (entry.isDirectory()) {
+                countFiles(join(dir, entry.name), info, depth + 1);
+            } else {
+                info.files++;
+            }
+        }
+    }
+
+    const rootName = basename(abs);
+    walk(abs, "  ", 1);
+
+    const header = compact
+        ? `Directory: ${rootName}/ (${totalFiles} files)`
+        : `Directory: ${rootName}/ (${totalFiles} files, ${formatSize(totalSize)})`;
+    return `${header}\n\n${rootName}/\n${lines.join("\n")}`;
+}

package/lib/update-check.mjs

@@ -0,0 +1,56 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const CACHE_FILE = join(tmpdir(), "hex-line-mcp-update.json");
+const CHECK_INTERVAL = 24 * 60 * 60 * 1000; // 24 hours
+const TIMEOUT = 3000;
+
+async function readCache() {
+    try {
+        return JSON.parse(await readFile(CACHE_FILE, "utf-8"));
+    } catch { return null; }
+}
+
+async function writeCache(entry) {
+    await writeFile(CACHE_FILE, JSON.stringify(entry)).catch(() => {});
+}
+
+async function fetchLatest(packageName) {
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), TIMEOUT);
+        const res = await fetch(`https://registry.npmjs.org/${packageName}/latest`, { signal: ctrl.signal });
+        clearTimeout(timer);
+        if (!res.ok) return null;
+        const data = await res.json();
+        return data.version ?? null;
+    } catch { return null; }
+}
+
+function compareVersions(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+        if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    }
+    return 0;
+}
+
+export async function checkForUpdates(packageName, currentVersion) {
+    const cached = await readCache();
+    if (cached && Date.now() - cached.timestamp < CHECK_INTERVAL) {
+        if (cached.latest && compareVersions(currentVersion, cached.latest) < 0) {
+            process.stderr.write(`${packageName} update: ${currentVersion} → ${cached.latest}. Run: npm install -g ${packageName}\n`);
+        }
+        return;
+    }
+    const latest = await fetchLatest(packageName);
+    if (latest) {
+        await writeCache({ timestamp: Date.now(), latest });
+        if (compareVersions(currentVersion, latest) < 0) {
+            process.stderr.write(`${packageName} update: ${currentVersion} → ${latest}. Run: npm install -g ${packageName}\n`);
+        }
+    }
+}

package/lib/verify.mjs

@@ -0,0 +1,54 @@
+/**
+ * Checksum verification without re-reading full file.
+ * Validates range checksums from prior reads.
+ */
+
+import { readFileSync } from "node:fs";
+import { fnv1a, rangeChecksum, parseChecksum } from "./hash.mjs";
+import { validatePath } from "./security.mjs";
+
+/**
+ * Verify checksums against current file state.
+ *
+ * @param {string} filePath
+ * @param {string[]} checksums - array of "start-end:8hex" strings
+ * @returns {string} verification result
+ */
+export function verifyChecksums(filePath, checksums) {
+    const real = validatePath(filePath);
+    const content = readFileSync(real, "utf-8").replace(/\r\n/g, "\n");
+    const lines = content.split("\n");
+
+    // Pre-compute all line hashes
+    const lineHashes = lines.map((l) => fnv1a(l));
+
+    const results = [];
+    let allValid = true;
+
+    for (const cs of checksums) {
+        const parsed = parseChecksum(cs);
+
+        if (parsed.start < 1 || parsed.end > lines.length) {
+            results.push(`${cs}: INVALID (range ${parsed.start}-${parsed.end} exceeds file length ${lines.length})`);
+            allValid = false;
+            continue;
+        }
+
+        const currentHashes = lineHashes.slice(parsed.start - 1, parsed.end);
+        const current = rangeChecksum(currentHashes, parsed.start, parsed.end);
+        const currentHex = current.split(":")[1];
+
+        if (currentHex === parsed.hex) {
+            results.push(`${cs}: valid`);
+        } else {
+            results.push(`${cs}: STALE → current: ${current}`);
+            allValid = false;
+        }
+    }
+
+    if (allValid && checksums.length > 0) {
+        return `All ${checksums.length} checksum(s) valid for ${filePath}`;
+    }
+
+    return results.join("\n");
+}