@aria-cli/tools 1.0.12 → 1.0.14

package/dist/executors/code-intelligence.js

@@ -1,882 +0,0 @@
-/**
- * @aria/tools - Code intelligence executors
- *
- * 7 native tools wrapping external CLI binaries:
- * rg (ripgrep), ug (ugrep), probe, sg (ast-grep),
- * cbm (codebase-memory-mcp), serena, fff
- */
-import { execFile, spawn as cpSpawn } from "node:child_process";
-import { promisify } from "node:util";
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { resolve as pathResolve, dirname, join as pathJoin } from "node:path";
-import { createConnection } from "node:net";
-import { success, fail } from "./utils.js";
-const execFileAsync = promisify(execFile);
-// ---------------------------------------------------------------------------
-// Shared helpers
-// ---------------------------------------------------------------------------
-const binaryCache = new Map();
-async function hasBinary(name) {
-    if (binaryCache.has(name))
-        return binaryCache.get(name);
-    try {
-        await execFileAsync("which", [name]);
-        binaryCache.set(name, true);
-    }
-    catch {
-        binaryCache.set(name, false);
-    }
-    return binaryCache.get(name);
-}
-async function shellExec(cmd, args, opts) {
-    return execFileAsync(cmd, args, {
-        cwd: opts.cwd,
-        timeout: opts.timeout ?? 30_000,
-        signal: opts.signal,
-        maxBuffer: 10 * 1024 * 1024, // 10MB
-    });
-}
-function pushIf(args, condition, ...flags) {
-    if (condition)
-        args.push(...flags);
-}
-function mergeExtraArgs(args, extra) {
-    if (extra?.length)
-        args.push(...extra);
-}
-function escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function asExecError(err) {
-    if (err && typeof err === "object")
-        return err;
-    return { message: String(err) };
-}
-// ---------------------------------------------------------------------------
-// 1. rg — ripgrep
-// ---------------------------------------------------------------------------
-export async function executeRg(input, ctx) {
-    if (ctx.abortSignal?.aborted)
-        return fail("Operation cancelled");
-    if (!(await hasBinary("rg")))
-        return fail("ripgrep (rg) not installed. Install: brew install ripgrep");
-    // When count mode is active, rg -c outputs plain text (file:count) even with --json.
-    // We omit --json and parse the plain-text output instead.
-    const rgCountMode = !!input.count;
-    const args = rgCountMode
-        ? ["--line-number", "--color", "never"]
-        : ["--json", "--line-number", "--color", "never"];
-    pushIf(args, input.ignore_case, "-i");
-    pushIf(args, input.smart_case, "-S");
-    pushIf(args, input.fixed_strings, "-F");
-    pushIf(args, input.word_regexp, "-w");
-    pushIf(args, input.invert, "-v");
-    pushIf(args, input.files_only, "-l");
-    pushIf(args, input.count, "-c");
-    if (input.file_type)
-        args.push("-t", input.file_type);
-    if (input.glob)
-        args.push("-g", input.glob);
-    if (input.context != null)
-        args.push("-C", String(input.context));
-    if (input.max_count != null)
-        args.push("-m", String(input.max_count));
-    mergeExtraArgs(args, input.extra_args);
-    args.push("--", input.pattern);
-    args.push(input.path ?? ctx.workingDir);
-    try {
-        const { stdout } = await shellExec("rg", args, {
-            cwd: ctx.workingDir,
-            signal: ctx.abortSignal,
-        });
-        if (rgCountMode) {
-            const counts = parseRipgrepCount(stdout);
-            const total = counts.reduce((s, c) => s + c.count, 0);
-            return success(`Found ${total} matches across ${counts.length} files for "${input.pattern}"`, { counts, total });
-        }
-        const matches = parseRipgrepJson(stdout);
-        return success(`Found ${matches.length} matches for "${input.pattern}"`, { matches });
-    }
-    catch (err) {
-        const e = asExecError(err);
-        if (e.code === 1)
-            return success("No matches found", { matches: [] });
-        return fail(`rg failed: ${e.stderr || e.message}`);
-    }
-}
-function parseRipgrepJson(stdout) {
-    const matches = [];
-    for (const line of stdout.split("\n")) {
-        if (!line.trim())
-            continue;
-        try {
-            const obj = JSON.parse(line);
-            if (obj.type === "match") {
-                matches.push({
-                    file: obj.data.path.text,
-                    line: obj.data.line_number,
-                    text: obj.data.lines.text.trimEnd(),
-                    submatches: obj.data.submatches?.map((s) => s.match?.text) ?? [],
-                });
-            }
-        }
-        catch {
-            // Skip malformed lines
-        }
-    }
-    return matches;
-}
-/** Parse rg/ug plain-text count output: `file:count` per line.
- *  Filters out files with 0 matches (ug -c outputs 0-count lines, rg doesn't). */
-function parseRipgrepCount(stdout) {
-    const counts = [];
-    for (const line of stdout.split("\n")) {
-        if (!line.trim())
-            continue;
-        const lastColon = line.lastIndexOf(":");
-        if (lastColon === -1)
-            continue;
-        const file = line.slice(0, lastColon);
-        const count = parseInt(line.slice(lastColon + 1), 10);
-        if (!isNaN(count) && count > 0)
-            counts.push({ file, count });
-    }
-    return counts;
-}
-// ---------------------------------------------------------------------------
-// 2. ug — ugrep
-// ---------------------------------------------------------------------------
-export async function executeUg(input, ctx) {
-    if (ctx.abortSignal?.aborted)
-        return fail("Operation cancelled");
-    if (!(await hasBinary("ug")))
-        return fail("ugrep (ug) not installed. Install: brew install ugrep");
-    // --ignore-files: respect .gitignore / .ignore (parity with rg default behaviour).
-    // --ignore-binary: skip binary files (tar, images, etc.) — rg skips them by default.
-    // Without these flags ug searches dist/, node_modules/, .tar archives, etc.
-    const ugCountMode = !!input.count;
-    const args = ugCountMode
-        ? ["--line-number", "--color=never", "-r", "--ignore-files", "--ignore-binary"]
-        : ["--json", "--line-number", "--color=never", "-r", "--ignore-files", "--ignore-binary"];
-    pushIf(args, input.ignore_case, "-i");
-    pushIf(args, input.smart_case, "-j");
-    pushIf(args, input.fixed_strings, "-F");
-    pushIf(args, input.word_regexp, "-w");
-    pushIf(args, input.files_only, "-l");
-    pushIf(args, input.count, "-c");
-    pushIf(args, input.decompress, "-z");
-    if (input.file_type)
-        args.push("-t", input.file_type);
-    if (input.glob)
-        args.push("-g", input.glob);
-    if (input.context != null)
-        args.push("-C", String(input.context));
-    if (input.max_count != null)
-        args.push("-m", String(input.max_count));
-    if (input.neg_pattern)
-        args.push("-N", input.neg_pattern);
-    // Fuzzy matching
-    if (input.fuzzy === true) {
-        args.push("-Z");
-    }
-    else if (typeof input.fuzzy === "number") {
-        args.push(`-Z${input.fuzzy}`);
-    }
-    // Boolean query mode
-    if (input.bool)
-        args.push("-%%");
-    mergeExtraArgs(args, input.extra_args);
-    args.push("--", input.pattern);
-    args.push(input.path ?? ctx.workingDir);
-    try {
-        const { stdout } = await shellExec("ug", args, {
-            cwd: ctx.workingDir,
-            signal: ctx.abortSignal,
-        });
-        if (ugCountMode) {
-            const counts = parseRipgrepCount(stdout); // same file:count format
-            const total = counts.reduce((s, c) => s + c.count, 0);
-            return success(`Found ${total} matches across ${counts.length} files for "${input.pattern}"`, { counts, total });
-        }
-        const matches = parseUgrepJson(stdout);
-        return success(`Found ${matches.length} matches for "${input.pattern}"`, { matches });
-    }
-    catch (err) {
-        const e = asExecError(err);
-        if (e.code === 1)
-            return success("No matches found", { matches: [] });
-        return fail(`ug failed: ${e.stderr || e.message}`);
-    }
-}
-function parseUgrepJson(stdout) {
-    // ugrep --json outputs: [{ file, matches: [{ line, match }] }]
-    // This is a JSON array, NOT NDJSON like ripgrep
-    const results = [];
-    try {
-        const parsed = JSON.parse(stdout);
-        for (const fileGroup of parsed) {
-            for (const m of fileGroup.matches) {
-                results.push({
-                    file: fileGroup.file,
-                    line: m.line,
-                    text: m.match.trimEnd(),
-                    submatches: [],
-                });
-            }
-        }
-    }
-    catch {
-        // Fallback: try NDJSON parsing in case format varies
-        for (const line of stdout.split("\n")) {
-            if (!line.trim())
-                continue;
-            try {
-                const obj = JSON.parse(line);
-                if (obj.file && obj.matches) {
-                    for (const m of obj.matches) {
-                        results.push({
-                            file: obj.file,
-                            line: m.line,
-                            text: m.match?.trimEnd() ?? "",
-                            submatches: [],
-                        });
-                    }
-                }
-            }
-            catch {
-                // Skip
-            }
-        }
-    }
-    return results;
-}
-// ---------------------------------------------------------------------------
-// 3. probe
-// ---------------------------------------------------------------------------
-export async function executeProbe(input, ctx) {
-    if (ctx.abortSignal?.aborted)
-        return fail("Operation cancelled");
-    if (!(await hasBinary("probe")))
-        return fail("probe not installed. Install: npm install -g @probelabs/probe");
-    const cmd = input.command ?? "search";
-    const args = [cmd];
-    switch (cmd) {
-        case "search": {
-            if (!input.query)
-                return fail("query required for search");
-            pushIf(args, input.exact, "--exact");
-            pushIf(args, input.allow_tests, "--allow-tests");
-            if (input.max_tokens != null)
-                args.push("--max-tokens", String(input.max_tokens));
-            if (input.max_results != null)
-                args.push("--max-results", String(input.max_results));
-            if (input.session)
-                args.push("--session", input.session);
-            if (input.language)
-                args.push("--language", input.language);
-            if (input.reranker)
-                args.push("--reranker", input.reranker);
-            args.push("--format", "json");
-            mergeExtraArgs(args, input.extra_args);
-            args.push("--", input.query);
-            if (input.path)
-                args.push(input.path);
-            break;
-        }
-        case "extract": {
-            if (!input.files?.length)
-                return fail("files required for extract");
-            args.push("--format", "json");
-            mergeExtraArgs(args, input.extra_args);
-            args.push(...input.files);
-            break;
-        }
-        case "symbols": {
-            // Accept files via `files` array or fall back to `query` as a file path
-            const symbolFiles = input.files?.length ? input.files : input.query ? [input.query] : [];
-            if (!symbolFiles.length)
-                return fail("files required for symbols (pass via 'files' or 'query')");
-            args.push("--format", "json");
-            mergeExtraArgs(args, input.extra_args);
-            args.push(...symbolFiles);
-            break;
-        }
-        case "query": {
-            if (!input.query)
-                return fail("query (AST pattern) required for query command");
-            if (input.language)
-                args.push("--language", input.language);
-            if (input.max_results != null)
-                args.push("--max-results", String(input.max_results));
-            pushIf(args, input.allow_tests, "--allow-tests");
-            args.push("--format", "json");
-            mergeExtraArgs(args, input.extra_args);
-            args.push("--", input.query);
-            if (input.path)
-                args.push(input.path);
-            break;
-        }
-    }
-    try {
-        const { stdout } = await shellExec("probe", args, {
-            cwd: ctx.workingDir,
-            signal: ctx.abortSignal,
-            timeout: 60_000,
-        });
-        try {
-            const data = JSON.parse(stdout);
-            return success(`probe ${cmd} completed`, data);
-        }
-        catch {
-            // If not valid JSON, return raw output
-            return success(`probe ${cmd} completed`, { raw: stdout });
-        }
-    }
-    catch (err) {
-        const e = asExecError(err);
-        return fail(`probe ${cmd} failed: ${e.stderr || e.message}`);
-    }
-}
-// ---------------------------------------------------------------------------
-// 4. sg — ast-grep
-// ---------------------------------------------------------------------------
-export async function executeSg(input, ctx) {
-    if (ctx.abortSignal?.aborted)
-        return fail("Operation cancelled");
-    if (!(await hasBinary("sg")))
-        return fail("ast-grep (sg) not installed. Install: cargo install ast-grep --locked");
-    const cmd = input.command ?? "run";
-    const isMutation = !!(input.rewrite || input.update_all);
-    // Require confirmation for mutations
-    if (isMutation && !input.update_all && ctx.confirm) {
-        const approved = await ctx.confirm(`Rewrite code matching \`${input.pattern}\` to \`${input.rewrite}\` in ${input.language || "auto-detected"} files?`);
-        if (!approved)
-            return fail("Rewrite cancelled by user");
-    }
-    const args = [cmd];
-    if (cmd === "run") {
-        if (!input.pattern)
-            return fail("pattern required for sg run");
-        args.push("--pattern", input.pattern);
-        if (input.language)
-            args.push("--lang", input.language);
-        if (input.rewrite)
-            args.push("--rewrite", input.rewrite);
-        if (input.strictness)
-            args.push("--strictness", input.strictness);
-        pushIf(args, input.update_all, "-U");
-    }
-    else if (cmd === "scan") {
-        if (input.rule)
-            args.push("--rule", input.rule);
-        if (input.inline_rules)
-            args.push("--inline-rules", input.inline_rules);
-    }
-    // Shared flags
-    if (input.globs)
-        args.push("--globs", input.globs);
-    if (input.context != null)
-        args.push("-C", String(input.context));
-    // Always JSON for machine parsing, skip color
-    if (!isMutation) {
-        args.push("--json=compact");
-    }
-    args.push("--color", "never");
-    mergeExtraArgs(args, input.extra_args);
-    args.push(input.path ?? ctx.workingDir);
-    try {
-        const { stdout } = await shellExec("sg", args, {
-            cwd: ctx.workingDir,
-            signal: ctx.abortSignal,
-        });
-        if (isMutation) {
-            return success(`sg ${cmd}: rewrites applied`, { raw: stdout });
-        }
-        try {
-            const data = JSON.parse(stdout);
-            const count = Array.isArray(data) ? data.length : 0;
-            return success(`Found ${count} matches`, { matches: data });
-        }
-        catch {
-            return success(`sg ${cmd} completed`, { raw: stdout });
-        }
-    }
-    catch (err) {
-        // Exit code 1 = no matches for run
-        const e = asExecError(err);
-        if (e.code === 1 && cmd === "run")
-            return success("No matches found", { matches: [] });
-        return fail(`sg ${cmd} failed: ${e.stderr || e.message}`);
-    }
-}
-// ---------------------------------------------------------------------------
-// 5. cbm — codebase-memory-mcp
-// ---------------------------------------------------------------------------
-// Internal helper to call cbm CLI
-async function cbmCall(tool, params, ctx, timeout) {
-    // Remove undefined/null values from params
-    const clean = {};
-    for (const [k, v] of Object.entries(params)) {
-        if (v !== undefined && v !== null)
-            clean[k] = v;
-    }
-    const { stdout } = await shellExec("codebase-memory-mcp", ["cli", tool, JSON.stringify(clean)], {
-        cwd: ctx.workingDir,
-        signal: ctx.abortSignal,
-        timeout: timeout ?? 30_000,
-    });
-    // cbm cli returns MCP content format: { content: [{ type: "text", text: "..." }] }
-    // Filter log lines (level=info ...) and parse
-    const jsonLines = stdout.split("\n").filter((l) => l.trim() && !l.startsWith("level="));
-    const parsed = JSON.parse(jsonLines.join("\n"));
-    if (Array.isArray(parsed.content)) {
-        const textBlocks = parsed.content
-            .filter((c) => c.type === "text")
-            .map((c) => c.text);
-        const combined = textBlocks.join("\n");
-        try {
-            return JSON.parse(combined);
-        }
-        catch {
-            return { text: combined };
-        }
-    }
-    return parsed;
-}
-export async function executeCbm(input, ctx) {
-    if (ctx.abortSignal?.aborted)
-        return fail("Operation cancelled");
-    if (!(await hasBinary("codebase-memory-mcp")))
-        return fail("codebase-memory-mcp not installed. Install:\ncurl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup.sh | bash");
-    // Auto-detect project name: cbm slugifies repo_path by replacing / with -
-    // and stripping the leading separator: /Users/hole/aria → Users-hole-aria
-    const p = input.project ?? (input.path ?? ctx.workingDir).replace(/^\//, "").replace(/\//g, "-");
-    // Auto-index: if the action requires an indexed project and no project exists,
-    // transparently run a fast index first so queries don't silently return empty.
-    const queryActions = new Set([
-        "search",
-        "trace",
-        "impact",
-        "context",
-        "snippet",
-        "code_search",
-        "architecture",
-        "schema",
-        "cypher",
-    ]);
-    if (queryActions.has(input.action)) {
-        let needsIndex = false;
-        try {
-            const statusResult = (await cbmCall("index_status", { project: p }, ctx));
-            // If status indicates no project or empty graph, auto-index
-            if (statusResult?.status === "no_project" ||
-                statusResult?.node_count === 0 ||
-                statusResult?.error) {
-                needsIndex = true;
-            }
-        }
-        catch {
-            // index_status failed — likely no project
-            needsIndex = true;
-        }
-        if (needsIndex) {
-            try {
-                await cbmCall("index_repository", { repo_path: input.path ?? ctx.workingDir, mode: "full" }, ctx, 300_000);
-            }
-            catch {
-                // If auto-index fails, continue — let the actual action produce the error
-            }
-        }
-    }
-    switch (input.action) {
-        case "index":
-            return success("Indexed", await cbmCall("index_repository", { repo_path: input.path ?? ctx.workingDir, mode: input.mode ?? "full" }, ctx, 300_000));
-        case "search":
-            return success("Search results", await cbmCall("search_graph", {
-                project: p,
-                name_pattern: input.name,
-                label: input.label,
-                file_pattern: input.file,
-                limit: input.limit ?? 20,
-            }, ctx));
-        case "trace": {
-            if (!input.name)
-                return fail("name required for trace");
-            return success(`Call chain: ${input.name}`, await cbmCall("trace_call_path", {
-                project: p,
-                function_name: input.name,
-                direction: input.direction ?? "both",
-                depth: input.depth ?? 3,
-                edge_types: input.edge_types,
-            }, ctx));
-        }
-        case "impact":
-            return success("Impact analysis", await cbmCall("detect_changes", {
-                project: p,
-                scope: input.scope,
-                depth: input.depth ?? 2,
-                base_branch: input.base_branch ?? "main",
-            }, ctx));
-        case "context": {
-            if (!input.name)
-                return fail("name required for context");
-            const [sym, callers, callees] = await Promise.all([
-                cbmCall("search_graph", { project: p, name_pattern: `^${escapeRegex(input.name)}$`, limit: 1 }, ctx),
-                cbmCall("trace_call_path", { project: p, function_name: input.name, direction: "inbound", depth: 2 }, ctx),
-                cbmCall("trace_call_path", { project: p, function_name: input.name, direction: "outbound", depth: 2 }, ctx),
-            ]);
-            return success(`360° context: ${input.name}`, {
-                definition: sym.results?.[0],
-                callers,
-                callees,
-            });
-        }
-        case "snippet": {
-            if (!input.qualified_name)
-                return fail("qualified_name required for snippet");
-            return success("Code snippet", await cbmCall("get_code_snippet", {
-                project: p,
-                qualified_name: input.qualified_name,
-                include_neighbors: input.include_neighbors,
-            }, ctx));
-        }
-        case "code_search":
-            return success("Code search", await cbmCall("search_code", {
-                project: p,
-                pattern: input.code_pattern,
-                mode: input.code_mode ?? "compact",
-                regex: input.regex,
-                limit: input.limit ?? 10,
-                file_pattern: input.file,
-                context: input.context,
-            }, ctx));
-        case "architecture":
-            return success("Architecture", await cbmCall("get_architecture", { project: p }, ctx));
-        case "schema":
-            return success("Schema", await cbmCall("get_graph_schema", { project: p }, ctx));
-        case "cypher": {
-            if (!input.query)
-                return fail("query required for cypher");
-            return success("Cypher result", await cbmCall("query_graph", { project: p, query: input.query, max_rows: input.max_rows }, ctx));
-        }
-        case "list_projects":
-            return success("Projects", await cbmCall("list_projects", {}, ctx));
-        case "delete_project": {
-            if (!input.project)
-                return fail("project required for delete_project");
-            if (ctx.confirm) {
-                const ok = await ctx.confirm(`Delete project "${input.project}" from cbm index?`);
-                if (!ok)
-                    return fail("Cancelled");
-            }
-            return success("Deleted", await cbmCall("delete_project", { project: p }, ctx));
-        }
-        case "status":
-            return success("Status", await cbmCall("index_status", { project: p }, ctx));
-        default:
-            return fail(`Unknown cbm action: ${input.action}`);
-    }
-}
-let _lspClient;
-async function getLspClient() {
-    if (!_lspClient) {
-        // Use variable to prevent TypeScript from following the import in CJS build
-        const modulePath = "./lsp-client.js";
-        _lspClient = (await import(/* webpackIgnore: true */ modulePath));
-    }
-    return _lspClient;
-}
-export async function executeLsp(input, ctx) {
-    if (ctx.abortSignal?.aborted)
-        return fail("Operation cancelled");
-    if (!input.file)
-        return fail("file required");
-    const { getServerForFile, getOrCreateServer, LSP_SERVERS } = await getLspClient();
-    const serverName = getServerForFile(input.file);
-    if (!serverName) {
-        const ext = input.file.slice(input.file.lastIndexOf("."));
-        const supported = Object.entries(LSP_SERVERS)
-            .map(([name, cfg]) => `${name}: ${Object.keys(cfg.extensionToLanguage).join(", ")}`)
-            .join("\n  ");
-        return fail(`No language server for extension "${ext}". Supported:\n  ${supported}`);
-    }
-    // Rename requires confirmation
-    if (input.action === "rename" && ctx.confirm) {
-        const ok = await ctx.confirm(`Rename symbol at ${input.file}:${input.line}:${input.character} to "${input.new_name}"?`);
-        if (!ok)
-            return fail("Cancelled by user");
-    }
-    const server = getOrCreateServer(serverName, ctx.workingDir);
-    try {
-        await server.start();
-        switch (input.action) {
-            case "definition": {
-                if (input.line == null || input.character == null)
-                    return fail("line and character required for definition");
-                const result = await server.definition(input.file, input.line, input.character);
-                return success(`lsp definition`, result);
-            }
-            case "references": {
-                if (input.line == null || input.character == null)
-                    return fail("line and character required for references");
-                const result = await server.references(input.file, input.line, input.character);
-                return success(`lsp references`, result);
-            }
-            case "hover": {
-                if (input.line == null || input.character == null)
-                    return fail("line and character required for hover");
-                const result = await server.hover(input.file, input.line, input.character);
-                return success(`lsp hover`, result);
-            }
-            case "symbols": {
-                const result = await server.documentSymbols(input.file);
-                return success(`lsp symbols`, result);
-            }
-            case "rename": {
-                if (input.line == null || input.character == null || !input.new_name)
-                    return fail("line, character, and new_name required for rename");
-                const result = await server.rename(input.file, input.line, input.character, input.new_name);
-                return success(`lsp rename`, result);
-            }
-            default:
-                return fail(`Unknown lsp action: ${input.action}. Use: definition, references, hover, symbols, rename`);
-        }
-    }
-    catch (err) {
-        const e = asExecError(err);
-        return fail(`lsp ${input.action} failed: ${e.message}`);
-    }
-}
-// ---------------------------------------------------------------------------
-// 7. serena — HTTP project server (kept alongside native LSP for full Serena API)
-// ---------------------------------------------------------------------------
-const SERENA_PORT = 9750;
-const SERENA_BASE = `http://127.0.0.1:${SERENA_PORT}`;
-const SERENA_PROJECT = "aria";
-const SERENA_TOOL_MAP = {
-    find_symbol: "find_symbol",
-    find_references: "find_referencing_symbols",
-    overview: "get_symbols_overview",
-    replace_body: "replace_symbol_body",
-    insert_after: "insert_after_symbol",
-    insert_before: "insert_before_symbol",
-    rename: "rename_symbol",
-    search: "search_for_pattern",
-};
-// ---------------------------------------------------------------------------
-// Serena auto-start: spawn the HTTP project server on demand
-// ---------------------------------------------------------------------------
-let serenaStarting = null;
-async function isSerenaAlive() {
-    // Lightweight TCP probe — just check if something is listening on the port.
-    // A full HTTP request is too heavy during startup (Serena takes seconds to load projects).
-    return new Promise((resolve) => {
-        const sock = createConnection({ host: "127.0.0.1", port: SERENA_PORT }, () => {
-            sock.destroy();
-            resolve(true);
-        });
-        sock.setTimeout(2_000);
-        sock.on("error", () => resolve(false));
-        sock.on("timeout", () => {
-            sock.destroy();
-            resolve(false);
-        });
-    });
-}
-function findSerenaProjectRoot() {
-    // Walk up from cwd looking for .serena/project.yml
-    let dir = pathResolve(process.cwd());
-    while (dir !== dirname(dir)) {
-        if (existsSync(pathJoin(dir, ".serena", "project.yml")))
-            return dir;
-        dir = dirname(dir);
-    }
-    // Fallback: walk up from this file's directory
-    // (compiled JS lives in packages/tools/dist/executors/)
-    // __dirname is available since the build target is CJS
-    dir = typeof __dirname === "string" ? pathResolve(__dirname) : pathResolve(".");
-    while (dir !== dirname(dir)) {
-        if (existsSync(pathJoin(dir, ".serena", "project.yml")))
-            return dir;
-        dir = dirname(dir);
-    }
-    return process.cwd();
-}
-let cachedSerenaBin;
-function resolveSerenaBin() {
-    if (cachedSerenaBin !== undefined)
-        return cachedSerenaBin;
-    // Find the serena binary from uv's cache directory.
-    // We avoid `uvx --from git+... which serena` because it triggers a blocking
-    // git fetch that hangs inside a detached spawn context.
-    const cacheBase = pathJoin(process.env.HOME ?? "/tmp", ".cache", "uv", "archive-v0");
-    try {
-        const entries = readdirSync(cacheBase)
-            .map((d) => pathJoin(cacheBase, d, "bin", "serena"))
-            .filter((p) => existsSync(p))
-            .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
-        cachedSerenaBin = entries.length > 0 ? entries[0] : null;
-    }
-    catch {
-        cachedSerenaBin = null;
-    }
-    return cachedSerenaBin ?? null;
-}
-function spawnSerenaServer() {
-    const projectRoot = findSerenaProjectRoot();
-    const serenaBin = resolveSerenaBin();
-    if (!serenaBin)
-        return;
-    // Spawn the cached Python binary directly with stdio:'ignore' + detached.
-    // Using 'uvx --from git+...' does NOT work because uvx triggers a blocking
-    // git fetch that hangs/dies with closed file descriptors.
-    const child = cpSpawn(serenaBin, ["start-project-server", "--port", String(SERENA_PORT)], {
-        cwd: projectRoot,
-        detached: true,
-        stdio: "ignore",
-        env: { ...process.env },
-    });
-    child.unref();
-}
-async function ensureSerenaServer() {
-    if (await isSerenaAlive())
-        return true;
-    // Deduplicate concurrent start attempts
-    if (serenaStarting)
-        return serenaStarting;
-    serenaStarting = (async () => {
-        spawnSerenaServer();
-        // Poll for readiness (serena can take a few seconds to initialize)
-        const deadline = Date.now() + 30_000;
-        const interval = 500;
-        while (Date.now() < deadline) {
-            await new Promise((r) => setTimeout(r, interval));
-            if (await isSerenaAlive()) {
-                serenaStarting = null;
-                return true;
-            }
-        }
-        serenaStarting = null;
-        return false;
-    })();
-    return serenaStarting;
-}
-export async function executeSerena(input, ctx) {
-    if (ctx.abortSignal?.aborted)
-        return fail("Operation cancelled");
-    const toolName = SERENA_TOOL_MAP[input.action];
-    if (!toolName)
-        return fail(`Unknown serena action: ${input.action}`);
-    const isMutation = ["replace_body", "insert_after", "insert_before", "rename"].includes(input.action);
-    if (isMutation && ctx.confirm) {
-        const desc = input.action === "rename"
-            ? `Rename "${input.name_path}" to "${input.new_name}"?`
-            : `${input.action} on "${input.name_path}"?`;
-        const ok = await ctx.confirm(desc);
-        if (!ok)
-            return fail("Cancelled by user");
-    }
-    // Auto-start the Serena project server if not running
-    const alive = await ensureSerenaServer();
-    if (!alive) {
-        return fail("Failed to auto-start Serena project server after 30s. " +
-            "Check logs or start manually:\n" +
-            `uvx --from "git+https://github.com/oraios/serena" serena start-project-server --port ${SERENA_PORT}`);
-    }
-    const params = { ...input.extra_args };
-    if (input.name_path) {
-        if (input.action === "find_symbol") {
-            params.name_path_pattern = input.name_path;
-        }
-        else {
-            params.name_path = input.name_path;
-        }
-    }
-    if (input.relative_path)
-        params.relative_path = input.relative_path;
-    if (input.include_body != null)
-        params.include_body = input.include_body;
-    if (input.include_info != null)
-        params.include_info = input.include_info;
-    if (input.depth != null)
-        params.depth = input.depth;
-    if (input.body)
-        params.body = input.body;
-    if (input.new_name)
-        params.new_name = input.new_name;
-    if (input.pattern)
-        params.substring_pattern = input.pattern;
-    if (input.context_before != null)
-        params.context_lines_before = input.context_before;
-    if (input.context_after != null)
-        params.context_lines_after = input.context_after;
-    if (input.paths_include)
-        params.paths_include_glob = input.paths_include;
-    if (input.paths_exclude)
-        params.paths_exclude_glob = input.paths_exclude;
-    try {
-        const body = JSON.stringify({
-            project_name: SERENA_PROJECT,
-            tool_name: toolName,
-            tool_params_json: JSON.stringify(params),
-        });
-        const response = await fetch(`${SERENA_BASE}/query_project`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body,
-            signal: ctx.abortSignal,
-        });
-        if (!response.ok) {
-            const text = await response.text();
-            return fail(`serena ${input.action}: HTTP ${response.status} — ${text.slice(0, 200)}`);
-        }
-        const text = await response.text();
-        try {
-            return success(`serena ${input.action} completed`, JSON.parse(text));
-        }
-        catch {
-            return success(`serena ${input.action} completed`, { raw: text });
-        }
-    }
-    catch (err) {
-        const e = asExecError(err);
-        return fail(`serena ${input.action} failed: ${e.message}`);
-    }
-}
-// ---------------------------------------------------------------------------
-// 8. fff — native CLI (fff-cli binary, zero MCP)
-// ---------------------------------------------------------------------------
-export async function executeFff(input, ctx) {
-    if (ctx.abortSignal?.aborted)
-        return fail("Operation cancelled");
-    if (!(await hasBinary("fff-cli")))
-        return fail("fff-cli not installed. Build: cd vendor/fff-cli && cargo build --release && cp target/release/fff-cli ~/.local/bin/");
-    const args = [input.action];
-    // Query or patterns. Native fff-cli supports positional query terms; constraints are
-    // appended as additional terms for grep/find_files and patterns for multi_grep.
-    if (input.action === "multi_grep" && input.patterns?.length) {
-        args.push(...input.patterns);
-        if (input.constraints)
-            args.push(input.constraints);
-    }
-    else {
-        if (input.query)
-            args.push(input.query);
-        if (input.constraints)
-            args.push(input.constraints);
-    }
-    // Path
-    args.push("--path", input.path ?? ctx.workingDir);
-    try {
-        const { stdout } = await shellExec("fff-cli", args, {
-            cwd: ctx.workingDir,
-            signal: ctx.abortSignal,
-            timeout: 30_000,
-        });
-        return success(`fff ${input.action} completed`, JSON.parse(stdout));
-    }
-    catch (err) {
-        const e = asExecError(err);
-        return fail(`fff ${input.action} failed: ${e.stderr || e.message}`);
-    }
-}