@levnikolaevich/hex-line-mcp 1.0.0

package/lib/hash.mjs

@@ -0,0 +1,109 @@
+/**
+ * FNV-1a hashing for hash-verified file editing.
+ *
+ * Trueline-compatible: 2-char tags from 32-symbol alphabet,
+ * range checksums as FNV-1a accumulator over line hashes.
+ *
+ * Line format: {tag}.{lineNum}\t{content}
+ * Range checksum: checksum: {startLine}-{endLine}:{8hex}
+ */
+
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+
+// 32 symbols — bitwise & 0x1f (power of 2, no division)
+const TAG_CHARS = "abcdefghijklmnopqrstuvwxyz234567";
+
+/**
+ * FNV-1a 32-bit hash of a string (UTF-8 encoded).
+ * Whitespace is normalized (collapsed) before hashing.
+ */
+export function fnv1a(str) {
+    // Normalize: strip trailing \r, collapse whitespace
+    const normalized = str.replace(/\r$/, "").replace(/\s+/g, "");
+    let h = FNV_OFFSET;
+    for (let i = 0; i < normalized.length; i++) {
+        let code = normalized.charCodeAt(i);
+        // Handle surrogate pairs for codepoints > U+FFFF
+        if (code >= 0xd800 && code <= 0xdbff && i + 1 < normalized.length) {
+            const lo = normalized.charCodeAt(i + 1);
+            if (lo >= 0xdc00 && lo <= 0xdfff) {
+                code = ((code - 0xd800) << 10) + (lo - 0xdc00) + 0x10000;
+                i++;
+            }
+        }
+        // Encode as UTF-8 bytes and feed to FNV-1a
+        if (code < 0x80) {
+            h = Math.imul(h ^ code, FNV_PRIME) >>> 0;
+        } else if (code < 0x800) {
+            h = Math.imul(h ^ (0xc0 | (code >> 6)), FNV_PRIME) >>> 0;
+            h = Math.imul(h ^ (0x80 | (code & 0x3f)), FNV_PRIME) >>> 0;
+        } else if (code < 0x10000) {
+            h = Math.imul(h ^ (0xe0 | (code >> 12)), FNV_PRIME) >>> 0;
+            h = Math.imul(h ^ (0x80 | ((code >> 6) & 0x3f)), FNV_PRIME) >>> 0;
+            h = Math.imul(h ^ (0x80 | (code & 0x3f)), FNV_PRIME) >>> 0;
+        } else {
+            h = Math.imul(h ^ (0xf0 | (code >> 18)), FNV_PRIME) >>> 0;
+            h = Math.imul(h ^ (0x80 | ((code >> 12) & 0x3f)), FNV_PRIME) >>> 0;
+            h = Math.imul(h ^ (0x80 | ((code >> 6) & 0x3f)), FNV_PRIME) >>> 0;
+            h = Math.imul(h ^ (0x80 | (code & 0x3f)), FNV_PRIME) >>> 0;
+        }
+    }
+    return h;
+}
+
+/**
+ * 2-character tag from 32-bit hash.
+ * Uses bits 0-4 and 8-12 for two characters from TAG_CHARS.
+ */
+export function lineTag(hash32) {
+    return TAG_CHARS[hash32 & 0x1f] + TAG_CHARS[(hash32 >>> 8) & 0x1f];
+}
+
+/**
+ * Compute tag for a line's content.
+ */
+export function hashLine(content) {
+    return lineTag(fnv1a(content));
+}
+
+/**
+ * Format a line with hash prefix: {tag}.{lineNum}\t{content}
+ */
+export function formatLine(lineNum, content) {
+    return `${hashLine(content)}.${lineNum}\t${content}`;
+}
+
+/**
+ * Range checksum: FNV-1a accumulator over line hashes (little-endian bytes).
+ * Returns "{startLine}-{endLine}:{8hex}".
+ */
+export function rangeChecksum(lineHashes, startLine, endLine) {
+    let acc = FNV_OFFSET;
+    for (const h of lineHashes) {
+        // Feed 4 bytes of each 32-bit hash in little-endian order
+        acc = Math.imul(acc ^ (h & 0xff), FNV_PRIME) >>> 0;
+        acc = Math.imul(acc ^ ((h >>> 8) & 0xff), FNV_PRIME) >>> 0;
+        acc = Math.imul(acc ^ ((h >>> 16) & 0xff), FNV_PRIME) >>> 0;
+        acc = Math.imul(acc ^ ((h >>> 24) & 0xff), FNV_PRIME) >>> 0;
+    }
+    return `${startLine}-${endLine}:${acc.toString(16).padStart(8, "0")}`;
+}
+
+/**
+ * Parse a line reference: "ab.12" → { tag: "ab", line: 12 }
+ */
+export function parseRef(ref) {
+    const m = ref.trim().match(/^([a-z2-7]{2})\.(\d+)$/);
+    if (!m) throw new Error(`Bad ref: "${ref}". Expected "ab.12" (tag.lineNum)`);
+    return { tag: m[1], line: parseInt(m[2], 10) };
+}
+
+/**
+ * Parse a range checksum: "1-50:f7e2a1b0" → { start: 1, end: 50, hex: "f7e2a1b0" }
+ */
+export function parseChecksum(cs) {
+    const m = cs.trim().match(/^(\d+)-(\d+):([0-9a-f]{8})$/);
+    if (!m) throw new Error(`Bad checksum: "${cs}". Expected "1-50:f7e2a1b0"`);
+    return { start: parseInt(m[1], 10), end: parseInt(m[2], 10), hex: m[3] };
+}

package/lib/info.mjs

@@ -0,0 +1,109 @@
+/**
+ * File metadata without reading content.
+ *
+ * Returns: size, line count, modification time, type, binary detection.
+ */
+
+import { statSync, readFileSync } from "node:fs";
+import { resolve, isAbsolute, extname, basename } from "node:path";
+
+const MAX_LINE_COUNT_SIZE = 10 * 1024 * 1024; // 10 MB
+
+const EXT_NAMES = {
+    ".ts": "TypeScript source", ".tsx": "TypeScript JSX source",
+    ".js": "JavaScript source", ".jsx": "JavaScript JSX source",
+    ".mjs": "JavaScript ESM source", ".cjs": "JavaScript CJS source",
+    ".py": "Python source", ".rb": "Ruby source", ".rs": "Rust source",
+    ".go": "Go source", ".java": "Java source", ".kt": "Kotlin source",
+    ".swift": "Swift source", ".c": "C source", ".cpp": "C++ source",
+    ".h": "C/C++ header", ".cs": "C# source", ".php": "PHP source",
+    ".sh": "Shell script", ".bash": "Bash script", ".zsh": "Zsh script",
+    ".json": "JSON data", ".yaml": "YAML data", ".yml": "YAML data",
+    ".toml": "TOML config", ".xml": "XML document", ".html": "HTML document",
+    ".css": "CSS stylesheet", ".scss": "SCSS stylesheet", ".less": "LESS stylesheet",
+    ".md": "Markdown document", ".txt": "Plain text", ".csv": "CSV data",
+    ".sql": "SQL script", ".graphql": "GraphQL schema",
+    ".png": "PNG image", ".jpg": "JPEG image", ".jpeg": "JPEG image",
+    ".gif": "GIF image", ".svg": "SVG image", ".ico": "Icon file",
+    ".pdf": "PDF document", ".zip": "ZIP archive", ".tar": "TAR archive",
+    ".gz": "Gzip archive", ".wasm": "WebAssembly binary",
+    ".lock": "Lock file", ".env": "Environment config",
+    ".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;
+    }
+    return false;
+}
+
+/**
+ * Get file metadata without reading full content.
+ * @param {string} filePath
+ * @returns {string} Formatted metadata
+ */
+export function fileInfo(filePath) {
+    if (!filePath) throw new Error("Empty file path");
+    const abs = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath);
+
+    const stat = statSync(abs);
+    if (!stat.isFile()) throw new Error(`Not a regular file: ${abs}`);
+
+    const size = stat.size;
+    const mtime = stat.mtime;
+    const ext = extname(abs).toLowerCase();
+    const name = basename(abs);
+
+    // File type
+    let typeName = EXT_NAMES[ext] || (ext ? `${ext.slice(1).toUpperCase()} file` : "Unknown type");
+    if (name === "Dockerfile") typeName = "Dockerfile";
+    if (name === "Makefile") typeName = "Makefile";
+
+    // 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;
+    }
+
+    // Format output
+    const sizeStr = lineCount !== null
+        ? `Size: ${formatSize(size)} (${lineCount} lines)`
+        : `Size: ${formatSize(size)}`;
+    const timeStr = `Modified: ${mtime.toISOString().replace("T", " ").slice(0, 19)} (${relativeTime(mtime)})`;
+
+    return [
+        `File: ${filePath}`,
+        sizeStr,
+        timeStr,
+        `Type: ${typeName}`,
+        `Binary: ${isBinary ? "yes" : "no"}`,
+    ].join("\n");
+}

package/lib/normalize.mjs

@@ -0,0 +1,106 @@
+/**
+ * Output normalization and smart truncation.
+ * Based on shared/references/output_normalization.md patterns.
+ *
+ * - Normalizes runtime values (IPs, timestamps, UUIDs, large numbers)
+ * - Deduplicates identical normalized lines with (xN) counts
+ * - Smart truncation: first N + last N lines with gap indicator
+ */
+
+// Normalization patterns (applied in order)
+const NORM_RULES = [
+    [/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<UUID>"],
+    [/\d{4}-\d{2}-\d{2}\s\d{2}:\d{2}:\d{2}/g, "<TS>"],
+    [/\d{2}-\d{2}-\d{4}\s\d{2}:\d{2}:\d{2}/g, "<TS>"],
+    [/\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}(:\d+)?/g, "<IP>"],
+    [/\/[0-9a-f]{8,}/gi, "/<ID>"],
+    [/\b\d{3,}(?=\b|[a-zA-Z])/g, "<N>"],
+    [/trace_id=[0-9a-fA-F]{1,8}/g, "trace_id=<TRACE>"],
+];
+
+/**
+ * Normalize a single line by replacing runtime-specific values.
+ */
+function normalizeLine(line) {
+    let result = line;
+    for (const [rx, repl] of NORM_RULES) {
+        result = result.replace(rx, repl);
+    }
+    return result;
+}
+
+/**
+ * Deduplicate lines: group identical normalized lines, append (xN).
+ *
+ * @param {string[]} lines - raw output lines
+ * @returns {string[]} deduplicated lines
+ */
+export function deduplicateLines(lines) {
+    const groups = new Map();
+    const order = [];
+
+    for (const line of lines) {
+        const norm = normalizeLine(line);
+        if (groups.has(norm)) {
+            groups.get(norm).count++;
+        } else {
+            const entry = { representative: line, count: 1 };
+            groups.set(norm, entry);
+            order.push(norm);
+        }
+    }
+
+    // Sort by count descending (stable within same count)
+    order.sort((a, b) => groups.get(b).count - groups.get(a).count);
+
+    return order.map((norm) => {
+        const { representative, count } = groups.get(norm);
+        return count > 1 ? `${representative}  (x${count})` : representative;
+    });
+}
+
+/**
+ * Smart truncation: keep first N + last N lines with gap indicator.
+ *
+ * @param {string} text - full output text
+ * @param {number} [headLines=40] - lines to keep from start
+ * @param {number} [tailLines=20] - lines to keep from end
+ * @returns {string} truncated text
+ */
+export function smartTruncate(text, headLines = 40, tailLines = 20) {
+    const lines = text.split("\n");
+    const total = lines.length;
+    const maxLines = headLines + tailLines;
+
+    if (total <= maxLines) return text;
+
+    const head = lines.slice(0, headLines);
+    const tail = lines.slice(total - tailLines);
+    const skipped = total - maxLines;
+
+    return [
+        ...head,
+        `\n--- ${skipped} lines omitted ---\n`,
+        ...tail,
+    ].join("\n");
+}
+
+/**
+ * Full normalization pipeline: normalize -> deduplicate -> truncate.
+ *
+ * @param {string} text - raw output
+ * @param {object} [opts]
+ * @param {boolean} [opts.deduplicate=true]
+ * @param {number} [opts.headLines=40]
+ * @param {number} [opts.tailLines=20]
+ * @returns {string}
+ */
+export function normalizeOutput(text, opts = {}) {
+    const { deduplicate = true, headLines = 40, tailLines = 20 } = opts;
+    const lines = text.split("\n");
+
+    const processed = deduplicate ? deduplicateLines(lines) : lines;
+    const result = processed.join("\n");
+
+    return smartTruncate(result, headLines, tailLines);
+}

package/lib/outline.mjs

@@ -0,0 +1,200 @@
+/**
+ * AST-based file outline via tree-sitter WASM.
+ *
+ * Returns structural overview: functions, classes, interfaces with line ranges.
+ * 10-20 lines instead of 500 → 95% token reduction.
+ * Output maps directly to read_file ranges.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve, extname } from "node:path";
+import { validatePath } from "./security.mjs";
+import { getGraphDB, symbolAnnotation, getRelativePath } from "./graph-enrich.mjs";
+
+// Language configs: extension → { grammar, outline, skip, recurse }
+const LANG_CONFIGS = {
+    ".js":   { grammar: "javascript", outline: ["function_declaration", "class_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
+    ".mjs":  { grammar: "javascript", outline: ["function_declaration", "class_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
+    ".jsx":  { grammar: "javascript", outline: ["function_declaration", "class_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
+    ".ts":   { grammar: "typescript", outline: ["function_declaration", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
+    ".tsx":  { grammar: "tsx", outline: ["function_declaration", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration", "variable_declaration", "export_statement", "lexical_declaration"], skip: ["import_statement"], recurse: ["class_body"] },
+    ".py":   { grammar: "python", outline: ["function_definition", "class_definition", "decorated_definition"], skip: ["import_statement", "import_from_statement"], recurse: ["class_body", "block"] },
+    ".go":   { grammar: "go", outline: ["function_declaration", "method_declaration", "type_declaration"], skip: ["import_declaration"], recurse: [] },
+    ".rs":   { grammar: "rust", outline: ["function_item", "struct_item", "enum_item", "impl_item", "trait_item", "const_item", "static_item"], skip: ["use_declaration"], recurse: ["impl_item"] },
+    ".java": { grammar: "java", outline: ["class_declaration", "interface_declaration", "method_declaration", "enum_declaration"], skip: ["import_declaration"], recurse: ["class_body"] },
+    ".c":    { grammar: "c", outline: ["function_definition", "struct_specifier", "enum_specifier", "type_definition"], skip: ["preproc_include"], recurse: [] },
+    ".h":    { grammar: "c", outline: ["function_definition", "struct_specifier", "enum_specifier", "type_definition"], skip: ["preproc_include"], recurse: [] },
+    ".cpp":  { grammar: "cpp", outline: ["function_definition", "class_specifier", "struct_specifier", "namespace_definition"], skip: ["preproc_include"], recurse: ["class_specifier"] },
+    ".cs":   { grammar: "c_sharp", outline: ["class_declaration", "interface_declaration", "method_declaration", "namespace_declaration"], skip: ["using_directive"], recurse: ["class_body"] },
+    ".rb":   { grammar: "ruby", outline: ["method", "class", "module"], skip: ["require", "require_relative"], recurse: ["class", "module"] },
+    ".php":  { grammar: "php", outline: ["function_definition", "class_declaration", "method_declaration"], skip: ["namespace_use_declaration"], recurse: ["class_body"] },
+    ".kt":   { grammar: "kotlin", outline: ["function_declaration", "class_declaration", "object_declaration"], skip: ["import_header"], recurse: ["class_body"] },
+    ".swift": { grammar: "swift", outline: ["function_declaration", "class_declaration", "struct_declaration", "protocol_declaration"], skip: ["import_declaration"], recurse: ["class_body"] },
+    ".sh":   { grammar: "bash", outline: ["function_definition"], skip: [], recurse: [] },
+    ".bash": { grammar: "bash", outline: ["function_definition"], skip: [], recurse: [] },
+};
+
+// Parser cache (init once)
+let _parser = null;
+const _langCache = new Map();
+
+async function getParser() {
+    if (_parser) return _parser;
+    try {
+        const { Parser } = await import("web-tree-sitter");
+        await Parser.init();
+        _parser = new Parser();
+        return _parser;
+    } catch (e) {
+        throw new Error(`tree-sitter init failed: ${e.message}. Run: cd mcp/hex-line-mcp && npm install`);
+    }
+}
+
+async function getLanguage(grammar) {
+    if (_langCache.has(grammar)) return _langCache.get(grammar);
+    await getParser(); // ensure init
+    try {
+        const { Language } = await import("web-tree-sitter");
+        const { createRequire } = await import("node:module");
+        const require = createRequire(import.meta.url);
+        // Absolute path for Windows compatibility (Gemini finding #3)
+        const wasmPath = resolve(require.resolve("tree-sitter-wasms/package.json"), "..", "out", `tree-sitter-${grammar}.wasm`);
+        const lang = await Language.load(wasmPath);
+        _langCache.set(grammar, lang);
+        return lang;
+    } catch (e) {
+        throw new Error(`Language "${grammar}" not available: ${e.message}`);
+    }
+}
+
+/**
+ * Extract structural outline entries from AST.
+ */
+function extractOutline(rootNode, config, sourceLines) {
+    const entries = [];
+    const skipTypes = new Set(config.skip);
+    const outlineTypes = new Set(config.outline);
+    const recurseTypes = new Set(config.recurse);
+
+    function walk(node, depth) {
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            const type = child.type;
+            const startLine = child.startPosition.row + 1;
+            const endLine = child.endPosition.row + 1;
+
+            if (skipTypes.has(type)) continue;
+
+            if (outlineTypes.has(type)) {
+                const firstLine = sourceLines[startLine - 1] || "";
+                // Extract symbol name for graph annotation
+                const nameMatch = firstLine.match(/(?:function|class|interface|type|enum|struct|def|fn|pub\s+fn)\s+(\w+)|(?:const|let|var|export\s+(?:const|let|var|function|class))\s+(\w+)/);
+                const name = nameMatch ? (nameMatch[1] || nameMatch[2]) : null;
+
+                entries.push({
+                    start: startLine,
+                    end: endLine,
+                    depth,
+                    text: firstLine.trim().slice(0, 120),
+                    name,
+                });
+
+                // Recurse into class/struct bodies
+                for (let j = 0; j < child.childCount; j++) {
+                    const sub = child.child(j);
+                    if (recurseTypes.has(sub.type)) {
+                        walk(sub, depth + 1);
+                    }
+                }
+            }
+        }
+    }
+
+    // Collect skipped ranges for summary
+    const skippedRanges = [];
+    for (let i = 0; i < rootNode.childCount; i++) {
+        const child = rootNode.child(i);
+        if (skipTypes.has(child.type)) {
+            skippedRanges.push({
+                start: child.startPosition.row + 1,
+                end: child.endPosition.row + 1,
+            });
+        }
+    }
+
+    walk(rootNode, 0);
+    return { entries, skippedRanges };
+}
+
+/**
+ * Parse content string into outline entries.
+ * Reusable core — no file I/O, no validatePath.
+ *
+ * @param {string} content  Source text (LF-normalized)
+ * @param {string} ext      Lowercase extension including dot (e.g. ".mjs")
+ * @returns {Promise<{entries: Array, skippedRanges: Array} | null>}  null if unsupported ext
+ */
+export async function outlineFromContent(content, ext) {
+    const config = LANG_CONFIGS[ext];
+    if (!config) return null;
+
+    const sourceLines = content.split("\n");
+
+    let lang;
+    try {
+        lang = await getLanguage(config.grammar);
+    } catch (e) {
+        throw new Error(`Outline error: ${e.message}`);
+    }
+
+    const parser = await getParser();
+    parser.setLanguage(lang);
+    const tree = parser.parse(content);
+    return extractOutline(tree.rootNode, config, sourceLines);
+}
+
+/**
+ * Format outline entries into display string.
+ */
+function formatOutline(entries, skippedRanges, sourceLineCount, db, relFile) {
+    const lines = [];
+
+    if (skippedRanges.length > 0) {
+        const first = skippedRanges[0].start;
+        const last = skippedRanges[skippedRanges.length - 1].end;
+        const count = skippedRanges.reduce((sum, r) => sum + (r.end - r.start + 1), 0);
+        lines.push(`${first}-${last}: (${count} imports/declarations)`);
+    }
+
+    for (const e of entries) {
+        const indent = "  ".repeat(e.depth);
+        const anno = db ? symbolAnnotation(db, relFile, e.name) : null;
+        const suffix = anno ? `  ${anno}` : "";
+        lines.push(`${indent}${e.start}-${e.end}: ${e.text}${suffix}`);
+    }
+
+    lines.push("");
+    lines.push(`(${entries.length} symbols, ${sourceLineCount} source lines)`);
+    return lines.join("\n");
+}
+
+/**
+ * Generate file outline.
+ *
+ * @param {string} filePath
+ * @returns {Promise<string>} formatted outline
+ */
+export async function fileOutline(filePath) {
+    const real = validatePath(filePath);
+    const ext = extname(real).toLowerCase();
+
+    if (!LANG_CONFIGS[ext]) {
+        return `Outline unavailable for ${ext} files. Use read_file directly for non-code files (markdown, config, text). Supported code extensions: ${Object.keys(LANG_CONFIGS).join(", ")}`;
+    }
+
+    const content = readFileSync(real, "utf-8").replace(/\r\n/g, "\n");
+    const result = await outlineFromContent(content, ext);
+    const db = getGraphDB(real);
+    const relFile = db ? getRelativePath(real) : null;
+    return `File: ${filePath}\n\n${formatOutline(result.entries, result.skippedRanges, content.split("\n").length, db, relFile)}`;
+}

package/lib/read.mjs

@@ -0,0 +1,129 @@
+/**
+ * File read with FNV-1a hash annotations and range checksums.
+ *
+ * Output format: {tag}.{lineNum}\t{content}
+ * Appends: checksum: {start}-{end}:{8hex}
+ */
+
+import { readFileSync, statSync, readdirSync } 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`;
+}
+
+const DEFAULT_LIMIT = 2000;
+
+/**
+ * Read a file with hash-annotated lines.
+ *
+ * @param {string} filePath
+ * @param {object} opts - { offset, limit, plain, ranges }
+ * @returns {string} formatted output
+ */
+export function readFile(filePath, opts = {}) {
+    const real = validatePath(filePath);
+    const stat = statSync(real);
+
+    // 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 content = readFileSync(real, "utf-8").replace(/\r\n/g, "\n");
+    const lines = content.split("\n");
+    const total = lines.length;
+
+    // Determine ranges to read
+    let ranges;
+    if (opts.ranges && opts.ranges.length > 0) {
+        ranges = opts.ranges.map((r) => ({
+            start: Math.max(1, r.start || 1),
+            end: Math.min(total, r.end || total),
+        }));
+    } else {
+        const startLine = Math.max(1, opts.offset || 1);
+        const maxLines = (opts.limit && opts.limit > 0) ? opts.limit : DEFAULT_LIMIT;
+        ranges = [{ start: startLine, end: Math.min(total, startLine - 1 + maxLines) }];
+    }
+
+    const parts = [];
+
+    for (const range of ranges) {
+        const selected = lines.slice(range.start - 1, range.end);
+        const lineHashes = [];
+
+        let formatted;
+        if (opts.plain) {
+            formatted = selected.map((line, i) => {
+                const num = range.start + i;
+                lineHashes.push(fnv1a(line));
+                return `${num}|${line}`;
+            }).join("\n");
+        } else {
+            formatted = selected.map((line, i) => {
+                const num = range.start + i;
+                const hash32 = fnv1a(line);
+                lineHashes.push(hash32);
+                const tag = lineTag(hash32);
+                return `${tag}.${num}\t${line}`;
+            }).join("\n");
+        }
+
+        parts.push(formatted);
+
+        // Range checksum
+        const cs = rangeChecksum(lineHashes, range.start, range.end);
+        parts.push(`\nchecksum: ${cs}`);
+    }
+
+    // Header
+    const sizeKB = (stat.size / 1024).toFixed(1);
+    const mtime = stat.mtime;
+    const ago = relativeTime(mtime);
+    let header = `File: ${filePath} (${total} lines, ${sizeKB}KB, ${ago})`;
+    if (ranges.length === 1) {
+        const r = ranges[0];
+        if (r.start > 1 || r.end < total) {
+            header += ` [showing ${r.start}-${r.end}]`;
+        }
+        if (r.end < total) {
+            header += ` (${total - r.end} more below)`;
+        }
+    }
+
+    // Graph enrichment (optional — silent if no DB)
+    const db = getGraphDB(real);
+    const relFile = db ? getRelativePath(real) : null;
+    let graphLine = "";
+    if (db && relFile) {
+        const annos = fileAnnotations(db, relFile);
+        if (annos.length > 0) {
+            const items = annos.map(a => {
+                const counts = (a.callees || a.callers) ? ` ${a.callees}\u2193 ${a.callers}\u2191` : "";
+                return `${a.name} [${a.kind}${counts}]`;
+            });
+            graphLine = `\nGraph: ${items.join(" | ")}`;
+        }
+    }
+
+    return `${header}${graphLine}\n\n\`\`\`\n${parts.join("\n")}\n\`\`\``;
+}