@aria-cli/tools 1.0.2 → 1.0.3

package/src/executors/code-intelligence.ts

@@ -0,0 +1,1179 @@
+/**
+ * @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 type { ToolContext, ToolResult } from "../types.js";
+import { success, fail } from "./utils.js";
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+const binaryCache = new Map<string, boolean>();
+
+async function hasBinary(name: string): Promise<boolean> {
+  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: string,
+  args: string[],
+  opts: { cwd?: string; timeout?: number; signal?: AbortSignal },
+): Promise<{ stdout: string; stderr: string }> {
+  return execFileAsync(cmd, args, {
+    cwd: opts.cwd,
+    timeout: opts.timeout ?? 30_000,
+    signal: opts.signal,
+    maxBuffer: 10 * 1024 * 1024, // 10MB
+  });
+}
+
+function pushIf(args: string[], condition: unknown, ...flags: string[]): void {
+  if (condition) args.push(...flags);
+}
+
+function mergeExtraArgs(args: string[], extra?: string[]): void {
+  if (extra?.length) args.push(...extra);
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+interface ExecError {
+  code?: number;
+  stderr?: string;
+  message?: string;
+}
+
+function asExecError(err: unknown): ExecError {
+  if (err && typeof err === "object") return err as ExecError;
+  return { message: String(err) };
+}
+
+// ---------------------------------------------------------------------------
+// Input types
+// ---------------------------------------------------------------------------
+
+export interface RgInput {
+  pattern: string;
+  path?: string;
+  ignore_case?: boolean;
+  smart_case?: boolean;
+  fixed_strings?: boolean;
+  word_regexp?: boolean;
+  file_type?: string;
+  glob?: string;
+  context?: number;
+  max_count?: number;
+  invert?: boolean;
+  files_only?: boolean;
+  count?: boolean;
+  extra_args?: string[];
+}
+
+export interface UgInput {
+  pattern: string;
+  path?: string;
+  ignore_case?: boolean;
+  smart_case?: boolean;
+  fixed_strings?: boolean;
+  word_regexp?: boolean;
+  file_type?: string;
+  glob?: string;
+  context?: number;
+  max_count?: number;
+  fuzzy?: boolean | number;
+  bool?: boolean;
+  neg_pattern?: string;
+  files_only?: boolean;
+  count?: boolean;
+  decompress?: boolean;
+  extra_args?: string[];
+}
+
+export interface ProbeInput {
+  command?: "search" | "extract" | "symbols" | "query";
+  query?: string;
+  path?: string;
+  exact?: boolean;
+  max_tokens?: number;
+  max_results?: number;
+  session?: string;
+  language?: string;
+  reranker?: string;
+  allow_tests?: boolean;
+  files?: string[];
+  extra_args?: string[];
+}
+
+export interface SgInput {
+  command?: "run" | "scan";
+  pattern?: string;
+  language?: string;
+  rewrite?: string;
+  strictness?: "cst" | "smart" | "ast" | "relaxed" | "signature";
+  globs?: string;
+  rule?: string;
+  inline_rules?: string;
+  path?: string;
+  update_all?: boolean;
+  context?: number;
+  extra_args?: string[];
+}
+
+export interface CbmInput {
+  action:
+    | "index"
+    | "search"
+    | "trace"
+    | "impact"
+    | "context"
+    | "snippet"
+    | "code_search"
+    | "architecture"
+    | "schema"
+    | "cypher"
+    | "list_projects"
+    | "delete_project"
+    | "status";
+  path?: string;
+  mode?: "full" | "fast";
+  name?: string;
+  label?: string;
+  file?: string;
+  direction?: "inbound" | "outbound" | "both";
+  depth?: number;
+  edge_types?: string[];
+  scope?: string;
+  base_branch?: string;
+  qualified_name?: string;
+  include_neighbors?: boolean;
+  code_pattern?: string;
+  regex?: boolean;
+  code_mode?: "compact" | "full" | "files";
+  query?: string;
+  max_rows?: number;
+  project?: string;
+  limit?: number;
+  context?: number;
+}
+
+export interface LspInput {
+  action: "definition" | "references" | "hover" | "symbols" | "rename";
+  file: string;
+  line?: number;
+  character?: number;
+  new_name?: string;
+}
+
+export interface SerenaInput {
+  action:
+    | "find_symbol"
+    | "find_references"
+    | "overview"
+    | "replace_body"
+    | "insert_after"
+    | "insert_before"
+    | "rename"
+    | "search";
+  name_path?: string;
+  relative_path?: string;
+  include_body?: boolean;
+  include_info?: boolean;
+  depth?: number;
+  body?: string;
+  new_name?: string;
+  pattern?: string;
+  context_before?: number;
+  context_after?: number;
+  paths_include?: string;
+  paths_exclude?: string;
+  extra_args?: Record<string, unknown>;
+}
+
+export interface FffInput {
+  action: "grep" | "find_files" | "multi_grep";
+  query?: string;
+  patterns?: string[];
+  constraints?: string;
+  path?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Output types
+// ---------------------------------------------------------------------------
+
+export interface RgMatch {
+  file: string;
+  line: number;
+  text: string;
+  submatches: string[];
+}
+
+// ---------------------------------------------------------------------------
+// 1. rg — ripgrep
+// ---------------------------------------------------------------------------
+
+export async function executeRg(input: RgInput, ctx: ToolContext): Promise<ToolResult> {
+  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: unknown) {
+    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: string): RgMatch[] {
+  const matches: RgMatch[] = [];
+  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: Record<string, unknown>) => (s.match as Record<string, unknown>)?.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: string): Array<{ file: string; count: number }> {
+  const counts: Array<{ file: string; count: number }> = [];
+  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: UgInput, ctx: ToolContext): Promise<ToolResult> {
+  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: unknown) {
+    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: string): RgMatch[] {
+  // ugrep --json outputs: [{ file, matches: [{ line, match }] }]
+  // This is a JSON array, NOT NDJSON like ripgrep
+  const results: RgMatch[] = [];
+  try {
+    const parsed = JSON.parse(stdout) as Array<{
+      file: string;
+      matches: Array<{ line: number; match: string }>;
+    }>;
+    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: ProbeInput, ctx: ToolContext): Promise<ToolResult> {
+  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: string[] = [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: unknown) {
+    const e = asExecError(err);
+    return fail(`probe ${cmd} failed: ${e.stderr || e.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 4. sg — ast-grep
+// ---------------------------------------------------------------------------
+
+export async function executeSg(input: SgInput, ctx: ToolContext): Promise<ToolResult> {
+  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: string[] = [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: unknown) {
+    // 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: string,
+  params: Record<string, unknown>,
+  ctx: ToolContext,
+  timeout?: number,
+): Promise<unknown> {
+  // Remove undefined/null values from params
+  const clean: Record<string, unknown> = {};
+  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")) as Record<string, unknown>;
+  if (Array.isArray(parsed.content)) {
+    const textBlocks = (parsed.content as Array<{ type: string; text: string }>)
+      .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: CbmInput, ctx: ToolContext): Promise<ToolResult> {
+  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)) as Record<
+        string,
+        unknown
+      >;
+      // 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, // 5 min timeout for indexing
+        ),
+      );
+
+    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 as Record<string, unknown[]>).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}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 6. lsp — native LSP client (direct JSON-RPC to language servers, no Serena, no MCP, no HTTP)
+// ---------------------------------------------------------------------------
+
+// Dynamic import for ESM-only lsp-client (allows CJS build to succeed)
+// Type is loose to avoid pulling lsp-client.ts into CJS build graph
+interface LspClientModule {
+  getServerForFile: (file: string) => string | undefined;
+  getOrCreateServer: (
+    serverName: string,
+    rootPath: string,
+  ) => {
+    start: () => Promise<void>;
+    definition: (file: string, line: number, char: number) => Promise<unknown>;
+    references: (file: string, line: number, char: number) => Promise<unknown>;
+    hover: (file: string, line: number, char: number) => Promise<unknown>;
+    documentSymbols: (file: string) => Promise<unknown>;
+    rename: (file: string, line: number, char: number, newName: string) => Promise<unknown>;
+  };
+  LSP_SERVERS: Record<string, { extensionToLanguage: Record<string, string> }>;
+}
+let _lspClient: LspClientModule | undefined;
+async function getLspClient(): Promise<LspClientModule> {
+  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)) as LspClientModule;
+  }
+  return _lspClient;
+}
+
+export async function executeLsp(input: LspInput, ctx: ToolContext): Promise<ToolResult> {
+  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: unknown) {
+    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: Record<string, string> = {
+  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: Promise<boolean> | null = null;
+
+async function isSerenaAlive(): Promise<boolean> {
+  // 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<boolean>((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(): string {
+  // 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: string | null | undefined;
+
+function resolveSerenaBin(): string | null {
+  if (cachedSerenaBin !== undefined) return cachedSerenaBin as string | null;
+
+  // 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: string) => pathJoin(cacheBase, d, "bin", "serena"))
+      .filter((p: string) => existsSync(p))
+      .sort((a: string, b: string) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    cachedSerenaBin = entries.length > 0 ? entries[0] : null;
+  } catch {
+    cachedSerenaBin = null;
+  }
+
+  return cachedSerenaBin ?? null;
+}
+
+function spawnSerenaServer(): void {
+  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(): Promise<boolean> {
+  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: SerenaInput, ctx: ToolContext): Promise<ToolResult> {
+  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: Record<string, unknown> = { ...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: unknown) {
+    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: FffInput, ctx: ToolContext): Promise<ToolResult> {
+  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: string[] = [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: unknown) {
+    const e = asExecError(err);
+    return fail(`fff ${input.action} failed: ${e.stderr || e.message}`);
+  }
+}