@aakrit512/gatekeep 1.0.0

package/dist/functions/toolExecutor.js

@@ -0,0 +1,1044 @@
+import { execFileSync, execSync } from 'child_process';
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+const DEFAULT_IGNORES = [
+    '.git',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+    '.turbo',
+    '.cache',
+];
+const DEFAULT_RESULT_LIMIT = 100;
+const MAX_RESULT_LIMIT = 1000;
+const DEFAULT_CHUNK_LIMIT = 200;
+const MAX_CHUNK_LIMIT = 1000;
+const SOURCE_EXTENSIONS = new Set([
+    '.cjs',
+    '.css',
+    '.go',
+    '.html',
+    '.java',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.py',
+    '.rs',
+    '.sh',
+    '.ts',
+    '.tsx',
+]);
+const DEPENDENCY_FILE_PATTERNS = [
+    'package.json',
+    'pnpm-lock.yaml',
+    'package-lock.json',
+    'yarn.lock',
+    'bun.lockb',
+    'Dockerfile',
+    'docker-compose.yml',
+    'docker-compose.yaml',
+    'Cargo.toml',
+    'go.mod',
+    'requirements.txt',
+    'pyproject.toml',
+    'pom.xml',
+    'build.gradle',
+    'build.gradle.kts',
+];
+const MANIFEST_FILE_PATTERNS = [
+    'package.json',
+    'pnpm-workspace.yaml',
+    'pnpm-workspace.yml',
+    'turbo.json',
+    'tsconfig.json',
+    'tsconfig.*.json',
+    'docker-compose.yml',
+    'docker-compose.yaml',
+    'Dockerfile',
+    'README*',
+    '.github/workflows/*',
+    'vite.config.*',
+    'next.config.*',
+    'nuxt.config.*',
+    'astro.config.*',
+    'webpack.config.*',
+    'rollup.config.*',
+    'eslint.config.*',
+    '.eslintrc*',
+    '.prettierrc*',
+];
+const ROUTE_METHODS = ['all', 'delete', 'get', 'head', 'options', 'patch', 'post', 'put'];
+function readStringArg(args, key, fallback = '') {
+    const value = args[key];
+    return typeof value === 'string' ? value : fallback;
+}
+function readNumberArg(args, key, fallback) {
+    const value = args[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function readBooleanArg(args, key, fallback) {
+    const value = args[key];
+    return typeof value === 'boolean' ? value : fallback;
+}
+function readStringArrayArg(args, key) {
+    const value = args[key];
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function clampInteger(value, min, max) {
+    return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+function toPosixPath(filePath) {
+    return filePath.split(path.sep).join('/');
+}
+function workspacePath(inputPath) {
+    return path.resolve(process.cwd(), inputPath || '.');
+}
+function relativeFromWorkspace(filePath) {
+    return toPosixPath(path.relative(process.cwd(), filePath)) || '.';
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function globToRegExp(glob) {
+    const normalized = toPosixPath(glob);
+    let source = '';
+    for (let i = 0; i < normalized.length; i += 1) {
+        const char = normalized[i];
+        const next = normalized[i + 1];
+        if (char === '*' && next === '*') {
+            source += '.*';
+            i += 1;
+        }
+        else if (char === '*') {
+            source += '[^/]*';
+        }
+        else if (char === '?') {
+            source += '[^/]';
+        }
+        else {
+            source += escapeRegExp(char);
+        }
+    }
+    return new RegExp(`^${source}$`);
+}
+function looksLikeGlob(pattern) {
+    return /[*?[\]{}]/.test(pattern);
+}
+function matchesPattern(relativePath, pattern) {
+    const normalizedPattern = toPosixPath(pattern);
+    if (looksLikeGlob(normalizedPattern)) {
+        return globToRegExp(normalizedPattern).test(relativePath);
+    }
+    return relativePath.includes(normalizedPattern) || path.basename(relativePath).includes(normalizedPattern);
+}
+function matchesIgnorePattern(relativePath, pattern) {
+    const normalizedPattern = toPosixPath(pattern);
+    if (looksLikeGlob(normalizedPattern)) {
+        return globToRegExp(normalizedPattern).test(relativePath);
+    }
+    return relativePath === normalizedPattern
+        || relativePath.startsWith(`${normalizedPattern}/`)
+        || relativePath.split('/').includes(normalizedPattern);
+}
+function shouldSkip(relativePath, dirent, options) {
+    const baseName = dirent.name;
+    if (!options.includeHidden && baseName.startsWith('.')) {
+        return true;
+    }
+    return options.ignorePatterns.some((pattern) => matchesIgnorePattern(relativePath, pattern));
+}
+function walkFiles(startPath, options) {
+    const results = [];
+    const visit = (currentPath) => {
+        if (results.length >= options.maxEntries) {
+            return;
+        }
+        const entries = fs.readdirSync(currentPath, { withFileTypes: true }).sort((a, b) => {
+            if (a.isDirectory() !== b.isDirectory()) {
+                return a.isDirectory() ? -1 : 1;
+            }
+            return a.name.localeCompare(b.name);
+        });
+        for (const entry of entries) {
+            const absolutePath = path.join(currentPath, entry.name);
+            const relativePath = relativeFromWorkspace(absolutePath);
+            if (shouldSkip(relativePath, entry, options)) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                visit(absolutePath);
+            }
+            else if (entry.isFile()) {
+                results.push(absolutePath);
+            }
+            if (results.length >= options.maxEntries) {
+                break;
+            }
+        }
+    };
+    visit(startPath);
+    return results;
+}
+function inferLanguage(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    const byExtension = {
+        '.cjs': 'JavaScript',
+        '.css': 'CSS',
+        '.go': 'Go',
+        '.html': 'HTML',
+        '.java': 'Java',
+        '.js': 'JavaScript',
+        '.json': 'JSON',
+        '.jsx': 'JavaScript React',
+        '.md': 'Markdown',
+        '.mjs': 'JavaScript',
+        '.py': 'Python',
+        '.rs': 'Rust',
+        '.sh': 'Shell',
+        '.ts': 'TypeScript',
+        '.tsx': 'TypeScript React',
+        '.yml': 'YAML',
+        '.yaml': 'YAML',
+    };
+    return byExtension[extension] ?? (extension ? extension.slice(1).toUpperCase() : 'Unknown');
+}
+function isSourceFile(filePath) {
+    return SOURCE_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+function isDependencyFile(relativePath) {
+    const baseName = path.basename(relativePath);
+    return DEPENDENCY_FILE_PATTERNS.some((pattern) => relativePath === pattern || baseName === pattern);
+}
+function isManifestFile(relativePath) {
+    return MANIFEST_FILE_PATTERNS.some((pattern) => (matchesPattern(relativePath, pattern) || matchesPattern(path.basename(relativePath), pattern)));
+}
+function readTextFile(filePath) {
+    return fs.readFileSync(filePath, 'utf-8');
+}
+function readLines(filePath) {
+    return readTextFile(filePath).split(/\r?\n/);
+}
+function extractDefinition(line, lineNumber, filePath) {
+    const trimmed = line.trim();
+    const exported = /\bexport\b/.test(trimmed);
+    const relativePath = relativeFromWorkspace(filePath);
+    const patterns = [
+        {
+            kind: 'class',
+            regex: /^(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)\b/,
+        },
+        {
+            kind: 'function',
+            regex: /^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\b/,
+        },
+        {
+            kind: 'interface',
+            regex: /^(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)\b/,
+        },
+        {
+            kind: 'type',
+            regex: /^(?:export\s+)?type\s+([A-Za-z_$][\w$]*)\b/,
+        },
+        {
+            kind: 'enum',
+            regex: /^(?:export\s+)?(?:const\s+)?enum\s+([A-Za-z_$][\w$]*)\b/,
+        },
+        {
+            kind: 'const',
+            regex: /^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\b/,
+        },
+        {
+            kind: 'let',
+            regex: /^(?:export\s+)?let\s+([A-Za-z_$][\w$]*)\b/,
+        },
+        {
+            kind: 'var',
+            regex: /^(?:export\s+)?var\s+([A-Za-z_$][\w$]*)\b/,
+        },
+    ];
+    for (const pattern of patterns) {
+        const match = trimmed.match(pattern.regex);
+        if (match) {
+            return {
+                kind: pattern.kind,
+                name: match[1],
+                file: relativePath,
+                line: lineNumber,
+                text: trimmed,
+                exported,
+            };
+        }
+    }
+    return null;
+}
+function collectSourceFiles(dirPath, maxEntries = MAX_RESULT_LIMIT * 20) {
+    return walkFiles(dirPath, {
+        includeHidden: false,
+        ignorePatterns: DEFAULT_IGNORES,
+        maxEntries,
+    }).filter(isSourceFile);
+}
+function collectDefinitions(filePath) {
+    return readLines(filePath)
+        .map((line, index) => extractDefinition(line, index + 1, filePath))
+        .filter((definition) => definition !== null);
+}
+function parseImportsExports(filePath) {
+    const lines = readLines(filePath);
+    const imports = [];
+    const exports = [];
+    lines.forEach((line, index) => {
+        const trimmed = line.trim();
+        const importMatch = trimmed.match(/^import\s+(?:.+?\s+from\s+)?['"]([^'"]+)['"];?$/);
+        const exportFromMatch = trimmed.match(/^export\s+.+?\s+from\s+['"]([^'"]+)['"];?$/);
+        if (importMatch) {
+            imports.push({
+                line: index + 1,
+                source: importMatch[1],
+                specifier: trimmed,
+            });
+        }
+        if (trimmed.startsWith('export ')) {
+            exports.push({
+                line: index + 1,
+                source: exportFromMatch?.[1] ?? null,
+                specifier: trimmed,
+            });
+        }
+    });
+    return { imports, exports };
+}
+function purposeHint(filePath, lines) {
+    const baseName = path.basename(filePath);
+    const firstComment = lines
+        .map((line) => line.trim())
+        .find((line) => line.startsWith('//') || line.startsWith('/*') || line.startsWith('*') || line.startsWith('#'));
+    if (firstComment) {
+        return firstComment.replace(/^\/\*+|^\*+\/?|^\/\/|^#+/g, '').trim();
+    }
+    if (/test|spec/.test(baseName)) {
+        return 'Test or specification file.';
+    }
+    if (/config/.test(baseName)) {
+        return 'Configuration file.';
+    }
+    if (/server|handler|route|controller/.test(baseName)) {
+        return 'Request or service boundary file.';
+    }
+    return 'No explicit purpose comment found.';
+}
+function detectSideEffects(lines) {
+    const text = lines.join('\n');
+    const sideEffects = [];
+    if (/\bprocess\.env\b/.test(text)) {
+        sideEffects.push('reads environment variables');
+    }
+    if (/\bexecSync\b|\bspawn\b|\bexec\b/.test(text)) {
+        sideEffects.push('runs child processes');
+    }
+    if (/\bfs\.(write|mkdir|rm|unlink|append|rename)/.test(text)) {
+        sideEffects.push('writes filesystem state');
+    }
+    if (/\bfs\.(read|readdir|stat)/.test(text)) {
+        sideEffects.push('reads filesystem state');
+    }
+    if (/\bfetch\s*\(|\baxios\b|\bhttp\.|\bhttps\./.test(text)) {
+        sideEffects.push('performs network I/O');
+    }
+    return sideEffects;
+}
+function readJsonFile(filePath) {
+    return JSON.parse(readTextFile(filePath));
+}
+function packageEntrypoints(packageJsonPath) {
+    const packageJson = readJsonFile(packageJsonPath);
+    const file = relativeFromWorkspace(packageJsonPath);
+    const entries = [];
+    for (const field of ['main', 'module', 'types', 'typings']) {
+        if (typeof packageJson[field] === 'string') {
+            entries.push({
+                kind: field,
+                file: toPosixPath(path.join(path.dirname(file), packageJson[field])),
+                source: file,
+                detail: packageJson[field],
+            });
+        }
+    }
+    if (typeof packageJson.bin === 'string') {
+        entries.push({
+            kind: 'bin',
+            file: toPosixPath(path.join(path.dirname(file), packageJson.bin)),
+            source: file,
+            detail: packageJson.bin,
+        });
+    }
+    else if (typeof packageJson.bin === 'object' && packageJson.bin) {
+        for (const [command, target] of Object.entries(packageJson.bin)) {
+            if (typeof target === 'string') {
+                entries.push({
+                    kind: 'bin',
+                    file: toPosixPath(path.join(path.dirname(file), target)),
+                    source: file,
+                    detail: { command, target },
+                });
+            }
+        }
+    }
+    const scripts = typeof packageJson.scripts === 'object' && packageJson.scripts
+        ? packageJson.scripts
+        : {};
+    for (const scriptName of ['start', 'dev', 'serve', 'worker', 'cli']) {
+        const script = scripts[scriptName];
+        if (typeof script === 'string') {
+            entries.push({
+                kind: `script:${scriptName}`,
+                file,
+                source: file,
+                detail: script,
+            });
+        }
+    }
+    return entries;
+}
+function entrypointKind(relativePath) {
+    const baseName = path.basename(relativePath).toLowerCase();
+    const pathParts = relativePath.toLowerCase().split('/');
+    if (/^(cli|command|bin)\.(c|m)?[jt]sx?$/.test(baseName) || pathParts.includes('bin')) {
+        return 'cli';
+    }
+    if (/^(worker|queue|job|processor)\.(c|m)?[jt]sx?$/.test(baseName) || pathParts.includes('workers')) {
+        return 'worker';
+    }
+    if (/^(server|app|main|index)\.(c|m)?[jt]sx?$/.test(baseName)) {
+        return 'bootstrap';
+    }
+    if (/^(page|route|layout)\.[jt]sx?$/.test(baseName) || pathParts.includes('routes') || pathParts.includes('pages')) {
+        return 'route_root';
+    }
+    return null;
+}
+function nextRouteFromFile(relativePath) {
+    const normalized = relativePath.replace(/\.(tsx|ts|jsx|js)$/, '');
+    const parts = normalized.split('/');
+    const appIndex = parts.findIndex((part) => part === 'app' || part === 'pages');
+    if (appIndex === -1) {
+        return null;
+    }
+    const routeParts = parts.slice(appIndex + 1);
+    const last = routeParts[routeParts.length - 1];
+    if (!last || !['page', 'route', 'index'].includes(last)) {
+        return null;
+    }
+    const visibleParts = routeParts
+        .slice(0, -1)
+        .filter((part) => !part.startsWith('(') && !part.startsWith('_'))
+        .map((part) => part.replace(/^\[\.{3}(.+)]$/, ':$1*').replace(/^\[(.+)]$/, ':$1'));
+    return `/${visibleParts.join('/')}`.replace(/\/+/g, '/') || '/';
+}
+function routeFilePathHint(relativePath) {
+    const route = nextRouteFromFile(relativePath);
+    if (route) {
+        return route;
+    }
+    const normalized = relativePath.replace(/\.(tsx|ts|jsx|js)$/, '');
+    const parts = normalized.split('/');
+    const routeIndex = parts.findIndex((part) => part === 'routes');
+    if (routeIndex === -1) {
+        return null;
+    }
+    const routeParts = parts
+        .slice(routeIndex + 1)
+        .filter((part) => part !== 'index')
+        .map((part) => part.replace(/^\[(.+)]$/, ':$1').replace(/^_/, ':'));
+    return `/${routeParts.join('/')}`.replace(/\/+/g, '/') || '/';
+}
+function normalizeRoutePath(routePath, controllerPrefix = '') {
+    const cleanPrefix = controllerPrefix.replace(/^\/|\/$/g, '');
+    const cleanPath = routePath.replace(/^\/|\/$/g, '');
+    const joined = [cleanPrefix, cleanPath].filter(Boolean).join('/');
+    return `/${joined}`.replace(/\/+/g, '/');
+}
+function parseRoutesInFile(filePath) {
+    const relativePath = relativeFromWorkspace(filePath);
+    const lines = readLines(filePath);
+    const routes = [];
+    const conventionRoute = routeFilePathHint(relativePath);
+    let controllerPrefix = '';
+    if (conventionRoute) {
+        routes.push({
+            file: relativePath,
+            line: null,
+            method: null,
+            path: conventionRoute,
+            source: 'file_convention',
+        });
+    }
+    lines.forEach((line, index) => {
+        const trimmed = line.trim();
+        const controllerMatch = trimmed.match(/@Controller\(\s*['"`]([^'"`]*)['"`]\s*\)/);
+        const decoratorMatch = trimmed.match(/@(Get|Post|Put|Patch|Delete|Options|Head|All)\(\s*(?:['"`]([^'"`]*)['"`])?\s*\)/);
+        const expressMatch = trimmed.match(/\b(?:app|router|server)\.(get|post|put|patch|delete|options|head|all)\(\s*['"`]([^'"`]+)['"`]/i);
+        const fastifyMatch = trimmed.match(/\b(?:fastify|server|app)\.route\(\s*\{\s*method:\s*['"`]([^'"`]+)['"`]\s*,\s*url:\s*['"`]([^'"`]+)['"`]/i);
+        if (controllerMatch) {
+            controllerPrefix = controllerMatch[1];
+        }
+        if (decoratorMatch) {
+            routes.push({
+                file: relativePath,
+                line: index + 1,
+                method: decoratorMatch[1].toUpperCase(),
+                path: normalizeRoutePath(decoratorMatch[2] ?? '', controllerPrefix),
+                source: 'nest_decorator',
+            });
+        }
+        if (expressMatch) {
+            routes.push({
+                file: relativePath,
+                line: index + 1,
+                method: expressMatch[1].toUpperCase(),
+                path: expressMatch[2],
+                source: 'router_call',
+            });
+        }
+        if (fastifyMatch) {
+            routes.push({
+                file: relativePath,
+                line: index + 1,
+                method: fastifyMatch[1].toUpperCase(),
+                path: fastifyMatch[2],
+                source: 'fastify_route',
+            });
+        }
+    });
+    return routes;
+}
+function parseGitStatus(rawStatus) {
+    const status = {
+        staged: [],
+        unstaged: [],
+        untracked: [],
+        renamed: [],
+    };
+    rawStatus.split(/\r?\n/).filter(Boolean).forEach((line) => {
+        const indexStatus = line[0];
+        const worktreeStatus = line[1];
+        const filePath = line.slice(3);
+        if (indexStatus === '?' && worktreeStatus === '?') {
+            status.untracked.push(filePath);
+            return;
+        }
+        if (indexStatus && indexStatus !== ' ') {
+            status.staged.push(filePath);
+        }
+        if (worktreeStatus && worktreeStatus !== ' ') {
+            status.unstaged.push(filePath);
+        }
+        if (indexStatus === 'R' || worktreeStatus === 'R') {
+            status.renamed.push(filePath);
+        }
+    });
+    return status;
+}
+export function executeTool(name, args) {
+    try {
+        if (name === 'list_directory') {
+            const dirPath = readStringArg(args, 'dir_path', '.');
+            const targetPath = workspacePath(dirPath);
+            const items = fs.readdirSync(targetPath, { withFileTypes: true });
+            return items
+                .map((item) => `${item.isDirectory() ? '[DIR]' : '[FILE]'} ${item.name}`)
+                .join('\n');
+        }
+        if (name === 'read_file') {
+            const filePath = readStringArg(args, 'file_path');
+            const targetPath = workspacePath(filePath);
+            return fs.readFileSync(targetPath, 'utf-8');
+        }
+        if (name === 'read_file_chunk') {
+            const filePath = readStringArg(args, 'file_path');
+            const targetPath = workspacePath(filePath);
+            const lines = fs.readFileSync(targetPath, 'utf-8').split(/\r?\n/);
+            const hasStartLine = typeof args.start_line === 'number' && Number.isFinite(args.start_line);
+            const limit = clampInteger(readNumberArg(args, 'limit', DEFAULT_CHUNK_LIMIT), 1, MAX_CHUNK_LIMIT);
+            const startLine = hasStartLine
+                ? clampInteger(readNumberArg(args, 'start_line', 1), 1, Math.max(lines.length, 1))
+                : clampInteger(readNumberArg(args, 'offset', 0), 0, Math.max(lines.length - 1, 0)) + 1;
+            const endLine = hasStartLine && typeof args.end_line === 'number' && Number.isFinite(args.end_line)
+                ? clampInteger(readNumberArg(args, 'end_line', startLine + limit - 1), startLine, lines.length)
+                : Math.min(lines.length, startLine + limit - 1);
+            const excerpt = lines
+                .slice(startLine - 1, endLine)
+                .map((line, index) => `${startLine + index}: ${line}`)
+                .join('\n');
+            return [
+                `File: ${relativeFromWorkspace(targetPath)}`,
+                `Lines: ${startLine}-${endLine} of ${lines.length}`,
+                excerpt,
+            ].join('\n');
+        }
+        if (name === 'search_files') {
+            const query = readStringArg(args, 'query');
+            const dirPath = readStringArg(args, 'dir_path', '.');
+            const includeHidden = readBooleanArg(args, 'include_hidden', false);
+            const maxResults = clampInteger(readNumberArg(args, 'max_results', DEFAULT_RESULT_LIMIT), 1, MAX_RESULT_LIMIT);
+            const targetPath = workspacePath(dirPath);
+            const files = walkFiles(targetPath, {
+                includeHidden,
+                ignorePatterns: DEFAULT_IGNORES,
+                maxEntries: MAX_RESULT_LIMIT * 20,
+            });
+            const matches = files
+                .map(relativeFromWorkspace)
+                .filter((relativePath) => {
+                if (query.startsWith('.') && !looksLikeGlob(query)) {
+                    return path.extname(relativePath) === query;
+                }
+                return matchesPattern(relativePath, query);
+            })
+                .slice(0, maxResults);
+            return matches.length > 0 ? matches.join('\n') : 'No matching files found.';
+        }
+        if (name === 'grep_code') {
+            const pattern = readStringArg(args, 'pattern');
+            const dirPath = readStringArg(args, 'dir_path', '.');
+            const includeGlobs = readStringArrayArg(args, 'include_globs');
+            const excludeGlobs = readStringArrayArg(args, 'exclude_globs');
+            const caseSensitive = readBooleanArg(args, 'case_sensitive', true);
+            const useRegex = readBooleanArg(args, 'regex', false);
+            const maxResults = clampInteger(readNumberArg(args, 'max_results', DEFAULT_RESULT_LIMIT), 1, MAX_RESULT_LIMIT);
+            const flags = caseSensitive ? 'g' : 'gi';
+            const matcher = useRegex
+                ? new RegExp(pattern, flags)
+                : new RegExp(escapeRegExp(pattern), flags);
+            const targetPath = workspacePath(dirPath);
+            const files = walkFiles(targetPath, {
+                includeHidden: false,
+                ignorePatterns: [...DEFAULT_IGNORES, ...excludeGlobs],
+                maxEntries: MAX_RESULT_LIMIT * 20,
+            });
+            const results = [];
+            for (const file of files) {
+                const relativePath = relativeFromWorkspace(file);
+                if (includeGlobs.length > 0 && !includeGlobs.some((glob) => matchesPattern(relativePath, glob))) {
+                    continue;
+                }
+                const stat = fs.statSync(file);
+                if (stat.size > 2_000_000) {
+                    continue;
+                }
+                const lines = fs.readFileSync(file, 'utf-8').split(/\r?\n/);
+                for (let index = 0; index < lines.length; index += 1) {
+                    matcher.lastIndex = 0;
+                    if (matcher.test(lines[index])) {
+                        results.push(`${relativePath}:${index + 1}: ${lines[index]}`);
+                    }
+                    if (results.length >= maxResults) {
+                        break;
+                    }
+                }
+                if (results.length >= maxResults) {
+                    break;
+                }
+            }
+            return results.length > 0 ? results.join('\n') : 'No matches found.';
+        }
+        if (name === 'get_file_metadata') {
+            const filePath = readStringArg(args, 'file_path');
+            const targetPath = workspacePath(filePath);
+            const content = fs.readFileSync(targetPath);
+            const stat = fs.statSync(targetPath);
+            const text = content.toString('utf-8');
+            const lineCount = text.length === 0 ? 0 : text.split(/\r?\n/).length;
+            const checksum = createHash('sha256').update(content).digest('hex');
+            return [
+                `Path: ${relativeFromWorkspace(targetPath)}`,
+                `Size: ${stat.size} bytes`,
+                `Modified: ${stat.mtime.toISOString()}`,
+                `Lines: ${lineCount}`,
+                `Language: ${inferLanguage(targetPath)}`,
+                `SHA-256: ${checksum}`,
+            ].join('\n');
+        }
+        if (name === 'get_project_tree') {
+            const dirPath = readStringArg(args, 'dir_path', '.');
+            const depth = clampInteger(readNumberArg(args, 'depth', 3), 0, 20);
+            const includeHidden = readBooleanArg(args, 'include_hidden', false);
+            const maxEntries = clampInteger(readNumberArg(args, 'max_entries', 500), 1, 5000);
+            const ignorePatterns = [...DEFAULT_IGNORES, ...readStringArrayArg(args, 'ignore')];
+            const targetPath = workspacePath(dirPath);
+            const output = [relativeFromWorkspace(targetPath)];
+            let entryCount = 0;
+            let truncated = false;
+            const visit = (currentPath, currentDepth, prefix) => {
+                if (currentDepth >= depth || truncated) {
+                    return;
+                }
+                const entries = fs.readdirSync(currentPath, { withFileTypes: true })
+                    .filter((entry) => !shouldSkip(relativeFromWorkspace(path.join(currentPath, entry.name)), entry, {
+                    includeHidden,
+                    ignorePatterns,
+                    maxEntries,
+                }))
+                    .sort((a, b) => {
+                    if (a.isDirectory() !== b.isDirectory()) {
+                        return a.isDirectory() ? -1 : 1;
+                    }
+                    return a.name.localeCompare(b.name);
+                });
+                entries.forEach((entry, index) => {
+                    if (entryCount >= maxEntries) {
+                        truncated = true;
+                        return;
+                    }
+                    const isLast = index === entries.length - 1;
+                    const connector = isLast ? '`-- ' : '|-- ';
+                    const childPrefix = `${prefix}${isLast ? '    ' : '|   '}`;
+                    const absolutePath = path.join(currentPath, entry.name);
+                    const displayName = entry.isDirectory() ? `${entry.name}/` : entry.name;
+                    output.push(`${prefix}${connector}${displayName}`);
+                    entryCount += 1;
+                    if (entry.isDirectory()) {
+                        visit(absolutePath, currentDepth + 1, childPrefix);
+                    }
+                });
+            };
+            visit(targetPath, 0, '');
+            if (truncated) {
+                output.push(`...truncated after ${maxEntries} entries`);
+            }
+            return output.join('\n');
+        }
+        if (name === 'find_symbol') {
+            const symbol = readStringArg(args, 'symbol');
+            const kind = readStringArg(args, 'kind');
+            const dirPath = readStringArg(args, 'dir_path', '.');
+            const maxResults = clampInteger(readNumberArg(args, 'max_results', 50), 1, MAX_RESULT_LIMIT);
+            const targetPath = workspacePath(dirPath);
+            const files = collectSourceFiles(targetPath);
+            const matches = [];
+            for (const file of files) {
+                const definitions = collectDefinitions(file).filter((definition) => {
+                    const kindMatches = kind ? definition.kind === kind : true;
+                    return definition.name === symbol && kindMatches;
+                });
+                matches.push(...definitions);
+                if (matches.length >= maxResults) {
+                    break;
+                }
+            }
+            return matches.length > 0
+                ? JSON.stringify(matches.slice(0, maxResults), null, 2)
+                : `No definitions found for symbol "${symbol}".`;
+        }
+        if (name === 'find_references') {
+            const symbol = readStringArg(args, 'symbol');
+            const dirPath = readStringArg(args, 'dir_path', '.');
+            const includeDefinitions = readBooleanArg(args, 'include_definitions', false);
+            const maxResults = clampInteger(readNumberArg(args, 'max_results', DEFAULT_RESULT_LIMIT), 1, MAX_RESULT_LIMIT);
+            const targetPath = workspacePath(dirPath);
+            const files = collectSourceFiles(targetPath);
+            const symbolRegex = new RegExp(`\\b${escapeRegExp(symbol)}\\b`);
+            const references = [];
+            for (const file of files) {
+                const lines = readLines(file);
+                for (let index = 0; index < lines.length; index += 1) {
+                    const line = lines[index];
+                    if (!symbolRegex.test(line)) {
+                        continue;
+                    }
+                    const definition = extractDefinition(line, index + 1, file);
+                    if (!includeDefinitions && definition?.name === symbol) {
+                        continue;
+                    }
+                    references.push({
+                        file: relativeFromWorkspace(file),
+                        line: index + 1,
+                        kind: /\b[A-Za-z_$][\w$]*\s*\(/.test(line) && line.includes(symbol)
+                            ? 'call_or_usage'
+                            : 'usage',
+                        text: line.trim(),
+                    });
+                    if (references.length >= maxResults) {
+                        break;
+                    }
+                }
+                if (references.length >= maxResults) {
+                    break;
+                }
+            }
+            return references.length > 0
+                ? JSON.stringify(references, null, 2)
+                : `No references found for symbol "${symbol}".`;
+        }
+        if (name === 'get_imports_exports') {
+            const filePath = readStringArg(args, 'file_path');
+            const targetPath = workspacePath(filePath);
+            const moduleShape = parseImportsExports(targetPath);
+            return JSON.stringify({
+                file: relativeFromWorkspace(targetPath),
+                imports: moduleShape.imports,
+                exports: moduleShape.exports,
+            }, null, 2);
+        }
+        if (name === 'summarize_file') {
+            const filePath = readStringArg(args, 'file_path');
+            const maxSymbols = clampInteger(readNumberArg(args, 'max_symbols', 30), 1, MAX_RESULT_LIMIT);
+            const targetPath = workspacePath(filePath);
+            const lines = readLines(targetPath);
+            const moduleShape = parseImportsExports(targetPath);
+            const symbols = collectDefinitions(targetPath).slice(0, maxSymbols);
+            const dependencies = [...new Set(moduleShape.imports.map((item) => item.source).filter(Boolean))];
+            const exportedSymbols = symbols.filter((symbol) => symbol.exported).map((symbol) => symbol.name);
+            return JSON.stringify({
+                file: relativeFromWorkspace(targetPath),
+                language: inferLanguage(targetPath),
+                lines: lines.length,
+                purpose: purposeHint(targetPath, lines),
+                symbols,
+                dependencies,
+                exports: {
+                    statements: moduleShape.exports,
+                    symbols: exportedSymbols,
+                },
+                side_effects: detectSideEffects(lines),
+            }, null, 2);
+        }
+        if (name === 'list_dependencies') {
+            const dirPath = readStringArg(args, 'dir_path', '.');
+            const includeDev = readBooleanArg(args, 'include_dev', true);
+            const maxFiles = clampInteger(readNumberArg(args, 'max_files', 50), 1, MAX_RESULT_LIMIT);
+            const targetPath = workspacePath(dirPath);
+            const files = walkFiles(targetPath, {
+                includeHidden: false,
+                ignorePatterns: DEFAULT_IGNORES,
+                maxEntries: MAX_RESULT_LIMIT * 20,
+            })
+                .map(relativeFromWorkspace)
+                .filter(isDependencyFile)
+                .slice(0, maxFiles);
+            const packageFiles = files.filter((file) => path.basename(file) === 'package.json');
+            const packages = packageFiles.map((file) => {
+                const packageJson = JSON.parse(readTextFile(workspacePath(file)));
+                const dependencies = typeof packageJson.dependencies === 'object' && packageJson.dependencies
+                    ? packageJson.dependencies
+                    : {};
+                const devDependencies = includeDev
+                    && typeof packageJson.devDependencies === 'object'
+                    && packageJson.devDependencies
+                    ? packageJson.devDependencies
+                    : {};
+                const peerDependencies = typeof packageJson.peerDependencies === 'object' && packageJson.peerDependencies
+                    ? packageJson.peerDependencies
+                    : {};
+                const optionalDependencies = typeof packageJson.optionalDependencies === 'object' && packageJson.optionalDependencies
+                    ? packageJson.optionalDependencies
+                    : {};
+                return {
+                    file,
+                    name: packageJson.name ?? null,
+                    runtime: dependencies,
+                    development: devDependencies,
+                    peer: peerDependencies,
+                    optional: optionalDependencies,
+                    scripts: packageJson.scripts ?? {},
+                    packageManager: packageJson.packageManager ?? null,
+                    engines: packageJson.engines ?? {},
+                    devEngines: packageJson.devEngines ?? {},
+                };
+            });
+            const dockerFiles = files
+                .filter((file) => path.basename(file) === 'Dockerfile')
+                .map((file) => ({
+                file,
+                baseImages: readLines(workspacePath(file))
+                    .map((line) => line.trim().match(/^FROM\s+(.+)$/i)?.[1])
+                    .filter(Boolean),
+            }));
+            return JSON.stringify({
+                scanned_from: relativeFromWorkspace(targetPath),
+                dependency_files: files,
+                packages,
+                docker: dockerFiles,
+                lockfiles: files.filter((file) => /lock|pnpm-lock|yarn\.lock/.test(path.basename(file))),
+                build_files: files.filter((file) => /Cargo\.toml|go\.mod|requirements\.txt|pyproject\.toml|pom\.xml|build\.gradle/.test(path.basename(file))),
+            }, null, 2);
+        }
+        if (name === 'read_manifest_files') {
+            const dirPath = readStringArg(args, 'dir_path', '.');
+            const maxFiles = clampInteger(readNumberArg(args, 'max_files', 40), 1, MAX_RESULT_LIMIT);
+            const maxBytesPerFile = clampInteger(readNumberArg(args, 'max_bytes_per_file', 20_000), 1000, 100_000);
+            const targetPath = workspacePath(dirPath);
+            const files = walkFiles(targetPath, {
+                includeHidden: true,
+                ignorePatterns: DEFAULT_IGNORES,
+                maxEntries: MAX_RESULT_LIMIT * 20,
+            })
+                .map(relativeFromWorkspace)
+                .filter(isManifestFile)
+                .slice(0, maxFiles);
+            const manifests = files.map((file) => {
+                const absolutePath = workspacePath(file);
+                const content = readTextFile(absolutePath);
+                const truncated = Buffer.byteLength(content, 'utf-8') > maxBytesPerFile;
+                return {
+                    file,
+                    size_bytes: fs.statSync(absolutePath).size,
+                    truncated,
+                    content: truncated ? content.slice(0, maxBytesPerFile) : content,
+                };
+            });
+            return JSON.stringify({
+                scanned_from: relativeFromWorkspace(targetPath),
+                files,
+                manifests,
+            }, null, 2);
+        }
+        if (name === 'list_git_status') {
+            const rawStatus = execFileSync('git', ['status', '--porcelain=v1'], {
+                cwd: process.cwd(),
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            const status = parseGitStatus(rawStatus);
+            return JSON.stringify({
+                ...status,
+                clean: status.staged.length === 0
+                    && status.unstaged.length === 0
+                    && status.untracked.length === 0
+                    && status.renamed.length === 0,
+            }, null, 2);
+        }
+        if (name === 'blame_file_range') {
+            const filePath = readStringArg(args, 'file_path');
+            const startLine = clampInteger(readNumberArg(args, 'start_line', 1), 1, Number.MAX_SAFE_INTEGER);
+            const endLine = clampInteger(readNumberArg(args, 'end_line', startLine), startLine, startLine + MAX_CHUNK_LIMIT - 1);
+            const targetPath = workspacePath(filePath);
+            const relativePath = relativeFromWorkspace(targetPath);
+            const blame = execFileSync('git', [
+                'blame',
+                '--line-porcelain',
+                `-L${startLine},${endLine}`,
+                '--',
+                relativePath,
+            ], {
+                cwd: process.cwd(),
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            const entries = [];
+            let current = null;
+            blame.split(/\r?\n/).forEach((line) => {
+                const header = line.match(/^([0-9a-f]{40})\s+/);
+                if (header) {
+                    current = {
+                        commit: header[1],
+                        author: null,
+                        author_time: null,
+                        summary: null,
+                    };
+                }
+                else if (current && line.startsWith('author ')) {
+                    current.author = line.slice('author '.length);
+                }
+                else if (current && line.startsWith('author-time ')) {
+                    const timestamp = Number(line.slice('author-time '.length));
+                    current.author_time = Number.isFinite(timestamp)
+                        ? new Date(timestamp * 1000).toISOString()
+                        : null;
+                }
+                else if (current && line.startsWith('summary ')) {
+                    current.summary = line.slice('summary '.length);
+                }
+                else if (current && line.startsWith('\t')) {
+                    entries.push({
+                        ...current,
+                        line: line.slice(1),
+                    });
+                }
+            });
+            return JSON.stringify({
+                file: relativePath,
+                range: `${startLine}-${endLine}`,
+                entries,
+            }, null, 2);
+        }
+        if (name === 'find_entrypoints') {
+            const dirPath = readStringArg(args, 'dir_path', '.');
+            const maxResults = clampInteger(readNumberArg(args, 'max_results', DEFAULT_RESULT_LIMIT), 1, MAX_RESULT_LIMIT);
+            const targetPath = workspacePath(dirPath);
+            const files = walkFiles(targetPath, {
+                includeHidden: false,
+                ignorePatterns: DEFAULT_IGNORES,
+                maxEntries: MAX_RESULT_LIMIT * 20,
+            });
+            const packageEntries = files
+                .filter((file) => path.basename(file) === 'package.json')
+                .flatMap(packageEntrypoints);
+            const conventionEntries = files
+                .map(relativeFromWorkspace)
+                .map((file) => {
+                const kind = entrypointKind(file);
+                return kind
+                    ? { kind, file, source: 'filename_or_directory_convention', detail: null }
+                    : null;
+            })
+                .filter((entry) => entry !== null);
+            const entries = [...packageEntries, ...conventionEntries].slice(0, maxResults);
+            return JSON.stringify({
+                scanned_from: relativeFromWorkspace(targetPath),
+                entrypoints: entries,
+            }, null, 2);
+        }
+        if (name === 'list_routes') {
+            const dirPath = readStringArg(args, 'dir_path', '.');
+            const maxResults = clampInteger(readNumberArg(args, 'max_results', 200), 1, MAX_RESULT_LIMIT);
+            const targetPath = workspacePath(dirPath);
+            const files = collectSourceFiles(targetPath);
+            const routes = files.flatMap(parseRoutesInFile).slice(0, maxResults);
+            return JSON.stringify({
+                scanned_from: relativeFromWorkspace(targetPath),
+                routes,
+            }, null, 2);
+        }
+        if (name === 'write_file') {
+            const filePath = readStringArg(args, 'file_path');
+            const content = readStringArg(args, 'content');
+            const targetPath = workspacePath(filePath);
+            const relativePath = path.relative(process.cwd(), targetPath).split(path.sep).join('/');
+            if (relativePath !== 'docs/intro.md') {
+                return `Error executing tool: write_file is restricted to ./docs/intro.md during initialization. Refused path: ${filePath}`;
+            }
+            fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+            fs.writeFileSync(targetPath, content, 'utf-8');
+            return `Success: Wrote ${content.length} characters to ${filePath}`;
+        }
+        if (name === 'get_git_diff') {
+            // Helper: run a git command and return stdout, or '' on failure (e.g. no commits yet)
+            const tryGit = (cmd) => {
+                try {
+                    return execSync(cmd, { stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim();
+                }
+                catch {
+                    return '';
+                }
+            };
+            const working = tryGit('git diff');
+            const staged = tryGit('git diff --cached');
+            const log = tryGit('git log --oneline --stat -10');
+            const sections = [
+                `## Uncommitted changes (working tree)\n${working || 'None.'}`,
+                `## Staged changes (index)\n${staged || 'None.'}`,
+                `## Recent commits (last 10)\n${log || 'No commits found.'}`,
+            ];
+            return sections.join('\n\n');
+        }
+        return `Tool ${name} not found.`;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `Error executing tool: ${message}`;
+    }
+}