paean 0.9.9 → 0.10.0

package/dist/mcp/coding-tools.js

@@ -0,0 +1,920 @@
+/**
+ * Local Coding MCP Tools
+ *
+ * High-efficiency tools for file editing, code search, pattern matching,
+ * batch reading, web fetching, and persistent memory — executed locally
+ * with zero cloud round-trips.
+ *
+ * @module mcp/coding-tools
+ */
+import { readFile, writeFile, readdir, stat, mkdir, appendFile, access } from 'fs/promises';
+import { resolve, relative, join, basename } from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+// ============================================
+// Tool Definitions
+// ============================================
+export function getCodingToolDefinitions() {
+    return [
+        // ── paean_edit_file ──────────────────────────────────────
+        {
+            name: 'paean_edit_file',
+            description: 'Edit a file by searching for an exact string and replacing it. ' +
+                'Returns a unified diff showing what changed. ' +
+                'The old_string must match EXACTLY (including whitespace and indentation). ' +
+                'For creating new files, use paean_write_file instead. ' +
+                'For inserting at a specific location, set old_string to the line AFTER which you want to insert, ' +
+                'and new_string to old_string + the new content.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    filePath: {
+                        type: 'string',
+                        description: 'Absolute or relative path to the file to edit',
+                    },
+                    oldString: {
+                        type: 'string',
+                        description: 'The exact string to find in the file (must match exactly including whitespace)',
+                    },
+                    newString: {
+                        type: 'string',
+                        description: 'The replacement string',
+                    },
+                    allowMultiple: {
+                        type: 'boolean',
+                        description: 'If true, replace ALL occurrences. Default: false (replace first only, fail if ambiguous)',
+                    },
+                },
+                required: ['filePath', 'oldString', 'newString'],
+            },
+        },
+        // ── paean_grep ───────────────────────────────────────────
+        {
+            name: 'paean_grep',
+            description: 'Search file contents using regex patterns. Uses ripgrep (rg) if available for speed, ' +
+                'falls back to built-in search. Returns matching lines with file paths and line numbers. ' +
+                'Use this instead of paean_execute_shell with grep for structured, reliable results.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    pattern: {
+                        type: 'string',
+                        description: 'Regex pattern to search for (e.g., "function\\s+\\w+", "TODO")',
+                    },
+                    dirPath: {
+                        type: 'string',
+                        description: 'Directory to search in (default: current working directory)',
+                    },
+                    includePattern: {
+                        type: 'string',
+                        description: 'Glob pattern to include files (e.g., "*.ts", "*.{js,jsx}")',
+                    },
+                    excludePattern: {
+                        type: 'string',
+                        description: 'Glob pattern to exclude files (e.g., "*.test.ts")',
+                    },
+                    caseSensitive: {
+                        type: 'boolean',
+                        description: 'Case-sensitive search (default: true)',
+                    },
+                    maxMatches: {
+                        type: 'number',
+                        description: 'Maximum number of matches to return (default: 100)',
+                    },
+                    contextLines: {
+                        type: 'number',
+                        description: 'Number of context lines before/after each match (default: 0)',
+                    },
+                },
+                required: ['pattern'],
+            },
+        },
+        // ── paean_glob ───────────────────────────────────────────
+        {
+            name: 'paean_glob',
+            description: 'Find files matching a glob pattern. Returns paths sorted by modification time (newest first). ' +
+                'Respects .gitignore by default. Use this to discover files before reading them.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    pattern: {
+                        type: 'string',
+                        description: 'Glob pattern (e.g., "**/*.ts", "src/**/*.{js,jsx}", "*.md")',
+                    },
+                    dirPath: {
+                        type: 'string',
+                        description: 'Base directory for the search (default: current working directory)',
+                    },
+                    respectGitignore: {
+                        type: 'boolean',
+                        description: 'Whether to respect .gitignore rules (default: true)',
+                    },
+                    maxResults: {
+                        type: 'number',
+                        description: 'Maximum number of results (default: 200)',
+                    },
+                },
+                required: ['pattern'],
+            },
+        },
+        // ── paean_read_many_files ────────────────────────────────
+        {
+            name: 'paean_read_many_files',
+            description: 'Read multiple files in a single call. Much more efficient than calling paean_read_file repeatedly. ' +
+                'Returns contents of each file with line numbers. Skips files that don\'t exist or are too large.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    paths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Array of file paths to read',
+                    },
+                    maxTotalLines: {
+                        type: 'number',
+                        description: 'Maximum total lines across all files (default: 5000). Files are read in order; stops when limit is reached.',
+                    },
+                    maxFileSize: {
+                        type: 'number',
+                        description: 'Skip files larger than this many bytes (default: 512000 = 500KB)',
+                    },
+                },
+                required: ['paths'],
+            },
+        },
+        // ── paean_web_fetch ──────────────────────────────────────
+        {
+            name: 'paean_web_fetch',
+            description: 'Fetch content from a URL and return it as readable text. ' +
+                'HTML is stripped to extract the main text content. ' +
+                'Useful for reading documentation, API responses, or web pages.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    url: {
+                        type: 'string',
+                        description: 'The URL to fetch (must be HTTP or HTTPS)',
+                    },
+                    maxLength: {
+                        type: 'number',
+                        description: 'Maximum content length in characters (default: 50000)',
+                    },
+                    headers: {
+                        type: 'object',
+                        description: 'Optional custom headers to include in the request',
+                    },
+                },
+                required: ['url'],
+            },
+        },
+        // ── paean_memory ─────────────────────────────────────────
+        {
+            name: 'paean_memory',
+            description: 'Save a fact or context to persistent memory (.paean/PAEAN.md in the project root). ' +
+                'Memories persist across sessions and are automatically loaded as context. ' +
+                'Use this to remember user preferences, project conventions, or important decisions.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    fact: {
+                        type: 'string',
+                        description: 'The fact or context to remember. Should be a clear, concise statement.',
+                    },
+                },
+                required: ['fact'],
+            },
+        },
+    ];
+}
+// ============================================
+// Tool Name Constants
+// ============================================
+export const CODING_TOOL_NAMES = new Set([
+    'paean_edit_file',
+    'paean_grep',
+    'paean_glob',
+    'paean_read_many_files',
+    'paean_web_fetch',
+    'paean_memory',
+]);
+// ============================================
+// Tool Implementations
+// ============================================
+/**
+ * Edit a file using exact string replacement, returning unified diff
+ */
+async function editFile(args) {
+    const filePath = args.filePath;
+    const oldString = args.oldString;
+    const newString = args.newString;
+    const allowMultiple = args.allowMultiple;
+    if (!filePath)
+        return { success: false, error: 'filePath is required' };
+    if (oldString === undefined)
+        return { success: false, error: 'oldString is required' };
+    if (newString === undefined)
+        return { success: false, error: 'newString is required' };
+    if (oldString === newString)
+        return { success: false, error: 'oldString and newString are identical — no change needed' };
+    const resolvedPath = resolve(filePath);
+    // Security: block system paths
+    const blockedPrefixes = ['/etc/', '/usr/', '/bin/', '/sbin/', '/System/', '/Library/'];
+    if (blockedPrefixes.some(p => resolvedPath.startsWith(p))) {
+        return { success: false, error: `Editing system path is not allowed: ${resolvedPath}` };
+    }
+    let currentContent;
+    try {
+        currentContent = await readFile(resolvedPath, 'utf-8');
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT') {
+            return { success: false, error: `File not found: ${resolvedPath}. Use paean_write_file to create new files.` };
+        }
+        return { success: false, error: e.message || 'Failed to read file' };
+    }
+    // Count occurrences
+    const occurrences = countOccurrences(currentContent, oldString);
+    if (occurrences === 0) {
+        // Try to provide helpful context
+        const trimmedOld = oldString.trim();
+        const fuzzyCount = trimmedOld.length > 5
+            ? countOccurrences(currentContent, trimmedOld)
+            : 0;
+        const hint = fuzzyCount > 0
+            ? ` (found ${fuzzyCount} match(es) for the trimmed version — check whitespace/indentation)`
+            : '';
+        return {
+            success: false,
+            error: `old_string not found in ${resolvedPath}${hint}`,
+            hint: 'Ensure old_string matches the file content exactly, including all whitespace and indentation. Use paean_read_file to verify the current content.',
+        };
+    }
+    if (occurrences > 1 && !allowMultiple) {
+        return {
+            success: false,
+            error: `old_string appears ${occurrences} times in ${resolvedPath}. Set allowMultiple=true to replace all, or provide a more specific old_string with more surrounding context.`,
+            occurrences,
+        };
+    }
+    // Apply replacement
+    let newContent;
+    if (allowMultiple) {
+        newContent = currentContent.split(oldString).join(newString);
+    }
+    else {
+        const idx = currentContent.indexOf(oldString);
+        newContent = currentContent.slice(0, idx) + newString + currentContent.slice(idx + oldString.length);
+    }
+    // Generate unified diff
+    const diff = generateUnifiedDiff(resolvedPath, currentContent, newContent);
+    // Compute diff stats
+    const addedLines = diff.split('\n').filter(l => l.startsWith('+') && !l.startsWith('+++')).length;
+    const removedLines = diff.split('\n').filter(l => l.startsWith('-') && !l.startsWith('---')).length;
+    // Write the file
+    await writeFile(resolvedPath, newContent, 'utf-8');
+    return {
+        success: true,
+        filePath: resolvedPath,
+        replacements: allowMultiple ? occurrences : 1,
+        diff,
+        stats: {
+            linesAdded: addedLines,
+            linesRemoved: removedLines,
+            totalLines: newContent.split('\n').length,
+        },
+    };
+}
+/**
+ * Count non-overlapping occurrences of a substring
+ */
+function countOccurrences(text, search) {
+    if (!search)
+        return 0;
+    let count = 0;
+    let pos = 0;
+    while ((pos = text.indexOf(search, pos)) !== -1) {
+        count++;
+        pos += search.length;
+    }
+    return count;
+}
+/**
+ * Generate a unified diff between two strings
+ */
+function generateUnifiedDiff(filePath, oldContent, newContent) {
+    const oldLines = oldContent.split('\n');
+    const newLines = newContent.split('\n');
+    const shortPath = relative(process.cwd(), filePath) || basename(filePath);
+    const result = [
+        `--- a/${shortPath}`,
+        `+++ b/${shortPath}`,
+    ];
+    // Simple diff: find changed regions
+    const maxLen = Math.max(oldLines.length, newLines.length);
+    let i = 0;
+    while (i < maxLen) {
+        // Skip identical lines
+        if (i < oldLines.length && i < newLines.length && oldLines[i] === newLines[i]) {
+            i++;
+            continue;
+        }
+        // Find the start of a changed region
+        const changeStart = i;
+        const contextBefore = Math.max(0, changeStart - 3);
+        // Find how many old lines are different
+        let oldEnd = changeStart;
+        let newEnd = changeStart;
+        // Simple heuristic: advance until lines match again
+        while (oldEnd < oldLines.length || newEnd < newLines.length) {
+            if (oldEnd < oldLines.length && newEnd < newLines.length && oldLines[oldEnd] === newLines[newEnd]) {
+                // Check if the next few lines also match (avoid false sync)
+                let syncLen = 0;
+                while (oldEnd + syncLen < oldLines.length &&
+                    newEnd + syncLen < newLines.length &&
+                    oldLines[oldEnd + syncLen] === newLines[newEnd + syncLen]) {
+                    syncLen++;
+                    if (syncLen >= 3)
+                        break;
+                }
+                if (syncLen >= 3)
+                    break;
+            }
+            if (oldEnd < oldLines.length)
+                oldEnd++;
+            if (newEnd < newLines.length)
+                newEnd++;
+        }
+        const contextAfter = Math.min(maxLen, Math.max(oldEnd, newEnd) + 3);
+        // Emit hunk header
+        const oldStart = contextBefore + 1;
+        const oldCount = Math.min(oldEnd + 3, oldLines.length) - contextBefore;
+        const newStart = contextBefore + 1;
+        const newCount = Math.min(newEnd + 3, newLines.length) - contextBefore;
+        result.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
+        // Context before
+        for (let c = contextBefore; c < changeStart; c++) {
+            if (c < oldLines.length)
+                result.push(` ${oldLines[c]}`);
+        }
+        // Removed lines
+        for (let c = changeStart; c < oldEnd; c++) {
+            if (c < oldLines.length)
+                result.push(`-${oldLines[c]}`);
+        }
+        // Added lines
+        for (let c = changeStart; c < newEnd; c++) {
+            if (c < newLines.length)
+                result.push(`+${newLines[c]}`);
+        }
+        // Context after
+        for (let c = Math.max(oldEnd, newEnd); c < contextAfter; c++) {
+            if (c < newLines.length)
+                result.push(` ${newLines[c]}`);
+        }
+        i = contextAfter;
+    }
+    return result.join('\n');
+}
+// ─────────────────────────────────────────────────────────────────
+// paean_grep
+// ─────────────────────────────────────────────────────────────────
+let _rgAvailable = null;
+async function isRipgrepAvailable() {
+    if (_rgAvailable !== null)
+        return _rgAvailable;
+    try {
+        await execFileAsync('rg', ['--version']);
+        _rgAvailable = true;
+    }
+    catch {
+        _rgAvailable = false;
+    }
+    return _rgAvailable;
+}
+async function grepFiles(args) {
+    const pattern = args.pattern;
+    const dirPath = args.dirPath;
+    const includePattern = args.includePattern;
+    const excludePattern = args.excludePattern;
+    const caseSensitive = args.caseSensitive !== false; // default true
+    const maxMatches = Math.min(args.maxMatches || 100, 500);
+    const contextLines = Math.min(args.contextLines || 0, 5);
+    if (!pattern)
+        return { success: false, error: 'pattern is required' };
+    const searchDir = resolve(dirPath || process.cwd());
+    try {
+        await access(searchDir);
+    }
+    catch {
+        return { success: false, error: `Directory not found: ${searchDir}` };
+    }
+    const hasRg = await isRipgrepAvailable();
+    if (hasRg) {
+        return grepWithRipgrep(pattern, searchDir, {
+            includePattern, excludePattern, caseSensitive, maxMatches, contextLines,
+        });
+    }
+    return grepWithNode(pattern, searchDir, {
+        includePattern, excludePattern, caseSensitive, maxMatches, contextLines,
+    });
+}
+async function grepWithRipgrep(pattern, searchDir, opts) {
+    const rgArgs = [
+        '--line-number',
+        '--no-heading',
+        '--color', 'never',
+        '--max-count', String(Math.ceil(opts.maxMatches / 5)), // per-file limit
+        '-m', String(opts.maxMatches),
+    ];
+    if (!opts.caseSensitive)
+        rgArgs.push('-i');
+    if (opts.contextLines > 0)
+        rgArgs.push('-C', String(opts.contextLines));
+    if (opts.includePattern)
+        rgArgs.push('-g', opts.includePattern);
+    if (opts.excludePattern)
+        rgArgs.push('-g', `!${opts.excludePattern}`);
+    rgArgs.push('--', pattern, searchDir);
+    try {
+        const { stdout } = await execFileAsync('rg', rgArgs, {
+            timeout: 30000,
+            maxBuffer: 5 * 1024 * 1024,
+        });
+        const lines = stdout.trim().split('\n').filter(Boolean);
+        const matches = parseRgOutput(lines, searchDir);
+        return {
+            success: true,
+            engine: 'ripgrep',
+            matchCount: matches.length,
+            truncated: matches.length >= opts.maxMatches,
+            matches: matches.slice(0, opts.maxMatches),
+        };
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 1) {
+            return { success: true, engine: 'ripgrep', matchCount: 0, matches: [] };
+        }
+        return { success: false, error: e.stderr || e.message || 'ripgrep failed' };
+    }
+}
+function parseRgOutput(lines, baseDir) {
+    const matches = [];
+    for (const line of lines) {
+        // Format: filepath:linenum:content or filepath-linenum-content (context)
+        const match = line.match(/^(.+?)[:\-](\d+)[:\-](.*)$/);
+        if (match) {
+            const filePath = relative(baseDir, match[1]) || match[1];
+            matches.push({
+                file: filePath,
+                line: parseInt(match[2], 10),
+                content: match[3],
+            });
+        }
+    }
+    return matches;
+}
+async function grepWithNode(pattern, searchDir, opts) {
+    let regex;
+    try {
+        regex = new RegExp(pattern, opts.caseSensitive ? 'g' : 'gi');
+    }
+    catch (err) {
+        return { success: false, error: `Invalid regex pattern: ${err.message}` };
+    }
+    const matches = [];
+    const includeRe = opts.includePattern ? globToRegex(opts.includePattern) : null;
+    const excludeRe = opts.excludePattern ? globToRegex(opts.excludePattern) : null;
+    async function walkDir(dir, depth) {
+        if (depth > 10 || matches.length >= opts.maxMatches)
+            return;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (matches.length >= opts.maxMatches)
+                break;
+            if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist')
+                continue;
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walkDir(fullPath, depth + 1);
+            }
+            else if (entry.isFile()) {
+                if (includeRe && !includeRe.test(entry.name))
+                    continue;
+                if (excludeRe && excludeRe.test(entry.name))
+                    continue;
+                // Skip binary/large files
+                try {
+                    const s = await stat(fullPath);
+                    if (s.size > 512000)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                try {
+                    const content = await readFile(fullPath, 'utf-8');
+                    const lines = content.split('\n');
+                    for (let i = 0; i < lines.length && matches.length < opts.maxMatches; i++) {
+                        regex.lastIndex = 0;
+                        if (regex.test(lines[i])) {
+                            matches.push({
+                                file: relative(searchDir, fullPath),
+                                line: i + 1,
+                                content: lines[i],
+                            });
+                        }
+                    }
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+    }
+    await walkDir(searchDir, 0);
+    return {
+        success: true,
+        engine: 'node',
+        matchCount: matches.length,
+        truncated: matches.length >= opts.maxMatches,
+        matches,
+    };
+}
+function globToRegex(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '.*')
+        .replace(/\?/g, '.')
+        .replace(/\{([^}]+)\}/g, (_m, group) => `(${group.replace(/,/g, '|')})`);
+    return new RegExp(`^${escaped}$`, 'i');
+}
+// ─────────────────────────────────────────────────────────────────
+// paean_glob
+// ─────────────────────────────────────────────────────────────────
+async function globFiles(args) {
+    const pattern = args.pattern;
+    const dirPath = args.dirPath;
+    const respectGitignore = args.respectGitignore !== false;
+    const maxResults = Math.min(args.maxResults || 200, 1000);
+    if (!pattern)
+        return { success: false, error: 'pattern is required' };
+    const searchDir = resolve(dirPath || process.cwd());
+    // Try using rg --files with glob for speed + gitignore awareness
+    const hasRg = await isRipgrepAvailable();
+    if (hasRg) {
+        return globWithRipgrep(pattern, searchDir, respectGitignore, maxResults);
+    }
+    return globWithNode(pattern, searchDir, respectGitignore, maxResults);
+}
+async function globWithRipgrep(pattern, searchDir, respectGitignore, maxResults) {
+    const rgArgs = ['--files', '--glob', pattern];
+    if (!respectGitignore)
+        rgArgs.push('--no-ignore');
+    rgArgs.push(searchDir);
+    try {
+        const { stdout } = await execFileAsync('rg', rgArgs, {
+            timeout: 15000,
+            maxBuffer: 5 * 1024 * 1024,
+        });
+        let files = stdout.trim().split('\n').filter(Boolean);
+        // Stat files for modification time and sort by recency
+        const withStats = await Promise.all(files.slice(0, maxResults * 2).map(async (f) => {
+            try {
+                const s = await stat(f);
+                return { path: relative(searchDir, f), absolutePath: f, mtime: s.mtimeMs, size: s.size };
+            }
+            catch {
+                return { path: relative(searchDir, f), absolutePath: f, mtime: 0, size: 0 };
+            }
+        }));
+        withStats.sort((a, b) => b.mtime - a.mtime);
+        const results = withStats.slice(0, maxResults).map(f => ({
+            path: f.path,
+            size: f.size,
+            modifiedMs: Math.round(f.mtime),
+        }));
+        return {
+            success: true,
+            baseDir: searchDir,
+            fileCount: results.length,
+            truncated: files.length > maxResults,
+            files: results,
+        };
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 1) {
+            return { success: true, baseDir: searchDir, fileCount: 0, files: [] };
+        }
+        return { success: false, error: e.stderr || e.message || 'glob failed' };
+    }
+}
+async function globWithNode(pattern, searchDir, _respectGitignore, maxResults) {
+    const patternRe = globToRegex(pattern);
+    const results = [];
+    async function walk(dir, depth) {
+        if (depth > 10 || results.length >= maxResults * 2)
+            return;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const fullPath = join(dir, entry.name);
+            const relPath = relative(searchDir, fullPath);
+            if (entry.isDirectory()) {
+                // Check if pattern could match paths in this directory
+                await walk(fullPath, depth + 1);
+            }
+            else if (entry.isFile()) {
+                if (patternRe.test(entry.name) || patternRe.test(relPath)) {
+                    try {
+                        const s = await stat(fullPath);
+                        results.push({
+                            path: relPath,
+                            size: s.size,
+                            modifiedMs: Math.round(s.mtimeMs),
+                        });
+                    }
+                    catch {
+                        results.push({ path: relPath, size: 0, modifiedMs: 0 });
+                    }
+                }
+            }
+        }
+    }
+    await walk(searchDir, 0);
+    results.sort((a, b) => b.modifiedMs - a.modifiedMs);
+    return {
+        success: true,
+        baseDir: searchDir,
+        fileCount: Math.min(results.length, maxResults),
+        truncated: results.length > maxResults,
+        files: results.slice(0, maxResults),
+    };
+}
+// ─────────────────────────────────────────────────────────────────
+// paean_read_many_files
+// ─────────────────────────────────────────────────────────────────
+async function readManyFiles(args) {
+    const paths = args.paths;
+    const maxTotalLines = Math.min(args.maxTotalLines || 5000, 20000);
+    const maxFileSize = args.maxFileSize || 512000;
+    if (!paths || !Array.isArray(paths) || paths.length === 0) {
+        return { success: false, error: 'paths array is required and must not be empty' };
+    }
+    if (paths.length > 50) {
+        return { success: false, error: 'Maximum 50 files can be read in a single call' };
+    }
+    const results = [];
+    let totalLinesRead = 0;
+    for (const filePath of paths) {
+        if (totalLinesRead >= maxTotalLines) {
+            results.push({ path: filePath, error: 'Skipped: total line limit reached' });
+            continue;
+        }
+        const resolvedPath = resolve(filePath);
+        try {
+            const s = await stat(resolvedPath);
+            if (s.size > maxFileSize) {
+                results.push({ path: filePath, error: `Skipped: file too large (${(s.size / 1024).toFixed(0)}KB > ${(maxFileSize / 1024).toFixed(0)}KB)` });
+                continue;
+            }
+            if (s.isDirectory()) {
+                results.push({ path: filePath, error: 'Skipped: path is a directory' });
+                continue;
+            }
+        }
+        catch {
+            results.push({ path: filePath, error: 'File not found' });
+            continue;
+        }
+        try {
+            const content = await readFile(resolvedPath, 'utf-8');
+            const lines = content.split('\n');
+            const remainingLines = maxTotalLines - totalLinesRead;
+            const truncated = lines.length > remainingLines;
+            const displayLines = truncated ? lines.slice(0, remainingLines) : lines;
+            // Add line numbers
+            const numbered = displayLines.map((line, i) => `${String(i + 1).padStart(4)}|${line}`).join('\n');
+            results.push({
+                path: relative(process.cwd(), resolvedPath) || filePath,
+                content: numbered,
+                lineCount: lines.length,
+                truncated,
+            });
+            totalLinesRead += displayLines.length;
+        }
+        catch (err) {
+            results.push({ path: filePath, error: err.message || 'Failed to read' });
+        }
+    }
+    return {
+        success: true,
+        filesRead: results.filter(r => r.content !== undefined).length,
+        totalFiles: paths.length,
+        totalLinesRead,
+        results,
+    };
+}
+// ─────────────────────────────────────────────────────────────────
+// paean_web_fetch
+// ─────────────────────────────────────────────────────────────────
+async function webFetch(args) {
+    const url = args.url;
+    const maxLength = Math.min(args.maxLength || 50000, 200000);
+    const customHeaders = args.headers;
+    if (!url)
+        return { success: false, error: 'url is required' };
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(url);
+    }
+    catch {
+        return { success: false, error: 'Invalid URL format' };
+    }
+    if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
+        return { success: false, error: `Unsupported protocol: ${parsedUrl.protocol}` };
+    }
+    try {
+        const response = await fetch(url, {
+            headers: {
+                'User-Agent': 'Paean-CLI/1.0 (Bot)',
+                'Accept': 'text/html,application/xhtml+xml,application/json,text/plain,*/*',
+                ...customHeaders,
+            },
+            signal: AbortSignal.timeout(30_000),
+            redirect: 'follow',
+        });
+        if (!response.ok) {
+            return {
+                success: false,
+                error: `HTTP ${response.status} ${response.statusText}`,
+                url,
+            };
+        }
+        const contentType = response.headers.get('content-type') || '';
+        const rawText = await response.text();
+        let content;
+        if (contentType.includes('text/html') || contentType.includes('application/xhtml')) {
+            content = stripHtml(rawText);
+        }
+        else {
+            content = rawText;
+        }
+        // Truncate if necessary
+        const truncated = content.length > maxLength;
+        if (truncated) {
+            content = content.slice(0, maxLength) + '\n\n[Content truncated]';
+        }
+        return {
+            success: true,
+            url,
+            contentType,
+            contentLength: content.length,
+            truncated,
+            content,
+        };
+    }
+    catch (err) {
+        if (err.name === 'TimeoutError') {
+            return { success: false, error: 'Request timed out after 30 seconds', url };
+        }
+        return { success: false, error: err.message || 'Fetch failed', url };
+    }
+}
+/**
+ * Strip HTML to extract readable text
+ */
+function stripHtml(html) {
+    let text = html;
+    // Remove script and style blocks
+    text = text.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '');
+    text = text.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '');
+    text = text.replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript>/gi, '');
+    // Convert common block elements to newlines
+    text = text.replace(/<\/?(p|div|br|hr|h[1-6]|li|tr|blockquote|pre|section|article|header|footer|nav|main)\b[^>]*>/gi, '\n');
+    // Convert links to text [text](url) format
+    text = text.replace(/<a\b[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, '[$2]($1)');
+    // Remove remaining HTML tags
+    text = text.replace(/<[^>]+>/g, '');
+    // Decode common HTML entities
+    text = text.replace(/&amp;/g, '&');
+    text = text.replace(/&lt;/g, '<');
+    text = text.replace(/&gt;/g, '>');
+    text = text.replace(/&quot;/g, '"');
+    text = text.replace(/&#39;/g, "'");
+    text = text.replace(/&nbsp;/g, ' ');
+    text = text.replace(/&#(\d+);/g, (_m, code) => String.fromCharCode(parseInt(code, 10)));
+    // Clean up whitespace
+    text = text.replace(/[ \t]+/g, ' ');
+    text = text.replace(/\n{3,}/g, '\n\n');
+    text = text.trim();
+    return text;
+}
+// ─────────────────────────────────────────────────────────────────
+// paean_memory
+// ─────────────────────────────────────────────────────────────────
+const MEMORY_DIR = '.paean';
+const MEMORY_FILE = 'PAEAN.md';
+const MEMORY_HEADER = '## Paean Memories\n\nFacts and context remembered across sessions.\n';
+async function saveMemory(args) {
+    const fact = args.fact;
+    if (!fact || typeof fact !== 'string') {
+        return { success: false, error: 'fact is required and must be a string' };
+    }
+    const projectRoot = process.cwd();
+    const memoryDir = join(projectRoot, MEMORY_DIR);
+    const memoryPath = join(memoryDir, MEMORY_FILE);
+    try {
+        await mkdir(memoryDir, { recursive: true });
+        let existing = '';
+        try {
+            existing = await readFile(memoryPath, 'utf-8');
+        }
+        catch {
+            // File doesn't exist yet — will create
+        }
+        if (!existing) {
+            existing = MEMORY_HEADER;
+        }
+        // Check for duplicate
+        if (existing.includes(fact.trim())) {
+            return {
+                success: true,
+                message: 'This fact is already saved',
+                memoryPath,
+                duplicate: true,
+            };
+        }
+        // Append the fact with timestamp
+        const timestamp = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+        const entry = `\n- ${fact.trim()} *(${timestamp})*\n`;
+        await appendFile(memoryPath, entry, 'utf-8');
+        // Count total memories
+        const content = await readFile(memoryPath, 'utf-8');
+        const memoryCount = (content.match(/^- /gm) || []).length;
+        return {
+            success: true,
+            message: 'Memory saved',
+            memoryPath,
+            memoryCount,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err.message || 'Failed to save memory',
+        };
+    }
+}
+/**
+ * Load all memories from PAEAN.md for injection into context
+ */
+export async function loadMemories(projectRoot) {
+    const root = projectRoot || process.cwd();
+    const memoryPath = join(root, MEMORY_DIR, MEMORY_FILE);
+    try {
+        const content = await readFile(memoryPath, 'utf-8');
+        return content.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================
+// Tool Router
+// ============================================
+export async function executeCodingTool(toolName, args) {
+    switch (toolName) {
+        case 'paean_edit_file':
+            return editFile(args);
+        case 'paean_grep':
+            return grepFiles(args);
+        case 'paean_glob':
+            return globFiles(args);
+        case 'paean_read_many_files':
+            return readManyFiles(args);
+        case 'paean_web_fetch':
+            return webFetch(args);
+        case 'paean_memory':
+            return saveMemory(args);
+        default:
+            return { success: false, error: `Unknown coding tool: ${toolName}` };
+    }
+}
+//# sourceMappingURL=coding-tools.js.map