kafox-cli 0.3.0 → 0.7.0

package/src/tools.js

@@ -0,0 +1,371 @@
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+// Limites para nao estourar o contexto nem travar a TUI.
+const MAX_READ_CHARS = 40_000;
+const MAX_READ_LINES = 400;
+const MAX_WRITE_CHARS = 120_000;
+const MAX_LIST_ENTRIES = 300;
+const MAX_OUTPUT_CHARS = 12_000;
+const COMMAND_TIMEOUT_MS = 60_000;
+
+const TOOL_SPECS = [
+  {
+    type: "function",
+    function: {
+      name: "read_file",
+      description:
+        "Le um arquivo de texto do diretorio de trabalho. Use offset/limit para trechos grandes.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Caminho relativo ao diretorio de trabalho" },
+          offset: { type: "integer", description: "Linha inicial (1-based)" },
+          limit: { type: "integer", description: "Quantidade de linhas (max 400)" },
+        },
+        required: ["path"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "list_dir",
+      description: "Lista arquivos e pastas de um diretorio do projeto.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Diretorio relativo (padrao: raiz do projeto)" },
+        },
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "write_file",
+      description:
+        "Cria um arquivo novo ou reescreve um arquivo inteiro no diretorio de trabalho. Cria as pastas necessarias.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Caminho relativo ao diretorio de trabalho" },
+          content: { type: "string", description: "Conteudo completo do arquivo" },
+        },
+        required: ["path", "content"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "edit_file",
+      description:
+        "Troca um trecho exato de um arquivo existente por outro. Prefira esta ferramenta a reescrever o arquivo inteiro.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Caminho relativo ao diretorio de trabalho" },
+          old_string: { type: "string", description: "Trecho atual, exatamente como esta no arquivo" },
+          new_string: { type: "string", description: "Trecho que substitui o anterior" },
+          replace_all: {
+            type: "boolean",
+            description: "Troca todas as ocorrencias (padrao: so quando for unica)",
+          },
+        },
+        required: ["path", "old_string", "new_string"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "run_command",
+      description:
+        "Executa um comando de shell no diretorio de trabalho e devolve stdout, stderr e o codigo de saida.",
+      parameters: {
+        type: "object",
+        properties: {
+          command: { type: "string", description: "Comando a executar" },
+          timeout_ms: { type: "integer", description: "Timeout em ms (padrao 60000, max 120000)" },
+        },
+        required: ["command"],
+      },
+    },
+  },
+];
+
+const LOCAL_TOOL_NAMES = new Set(TOOL_SPECS.map((tool) => tool.function.name));
+const TOOL_NAMES = LOCAL_TOOL_NAMES;
+// Ferramentas que mudam o disco ou executam codigo pedem aprovacao.
+const APPROVAL_REQUIRED = new Set(["write_file", "edit_file", "run_command"]);
+
+const TOOL_META = {
+  // A ferramenta de subagente e montada no agent.js (nao vai para TOOL_SPECS
+  // porque só aparece enquanto a profundidade permite), mas o card da TUI
+  // precisa do mesmo rótulo das outras.
+  spawn_subagent: { kind: "agent", label: "Subagente" },
+  read_file: { kind: "read", label: "Read" },
+  list_dir: { kind: "list", label: "List" },
+  write_file: { kind: "write", label: "Write" },
+  edit_file: { kind: "edit", label: "Edit" },
+  run_command: { kind: "bash", label: "Bash" },
+};
+
+function toolMeta(name, hub) {
+  if (TOOL_META[name]) return { ...TOOL_META[name], mcp: null };
+  const entry = hub?.describe?.(name);
+  if (entry) return { kind: "mcp", label: "MCP", server: entry.server, tool: entry.tool };
+  return { kind: "tool", label: name || "tool" };
+}
+
+function resolveInside(cwd, target) {
+  const root = path.resolve(cwd);
+  const full = path.resolve(root, target || ".");
+  if (full !== root && !full.startsWith(root + path.sep)) {
+    throw new Error(`caminho fora do diretorio de trabalho: ${target}`);
+  }
+  return full;
+}
+
+function relative(cwd, full) {
+  const rel = path.relative(path.resolve(cwd), full);
+  return rel === "" ? "." : rel;
+}
+
+function truncate(text, max) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n... (cortado, ${text.length - max} caracteres a mais)`;
+}
+
+function readTextFile(cwd, target) {
+  const full = resolveInside(cwd, target);
+  if (!fs.existsSync(full)) throw new Error(`arquivo nao encontrado: ${target}`);
+  if (fs.statSync(full).isDirectory()) throw new Error(`${target} e um diretorio`);
+  return { full, content: fs.readFileSync(full, "utf8") };
+}
+
+function readFile(cwd, args) {
+  const { full, content: raw } = readTextFile(cwd, args.path);
+
+  const offset = Math.max(1, Number(args.offset) || 1);
+  const limit = Math.min(MAX_READ_LINES, Math.max(1, Number(args.limit) || MAX_READ_LINES));
+  const lines = raw.split("\n");
+  const slice = lines.slice(offset - 1, offset - 1 + limit);
+  const header =
+    offset > 1 || slice.length < lines.length
+      ? `# ${relative(cwd, full)} linhas ${offset}-${offset + slice.length - 1} de ${lines.length}\n`
+      : "";
+  return truncate(header + slice.join("\n"), MAX_READ_CHARS);
+}
+
+function writeFile(cwd, args) {
+  const full = resolveInside(cwd, args.path);
+  const content = String(args.content ?? "");
+  if (content.length > MAX_WRITE_CHARS) {
+    throw new Error(`conteudo grande demais (${content.length} chars, max ${MAX_WRITE_CHARS})`);
+  }
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, content, "utf8");
+  return `ok: ${relative(cwd, full)} (${content.length} caracteres escritos)`;
+}
+
+/** Aplica a troca de trecho; separado da escrita para permitir o preview. */
+function applyEdit(cwd, args) {
+  const oldString = String(args.old_string ?? "");
+  const newString = String(args.new_string ?? "");
+  if (!oldString) throw new Error("old_string vazio: diga qual trecho deve sair");
+
+  const { full, content } = readTextFile(cwd, args.path);
+  const occurrences = content.split(oldString).length - 1;
+  if (!occurrences) throw new Error(`trecho nao encontrado em ${args.path}`);
+  if (occurrences > 1 && !args.replace_all) {
+    throw new Error(
+      `o trecho aparece ${occurrences} vezes em ${args.path}: inclua mais contexto ou use replace_all`
+    );
+  }
+
+  const after = args.replace_all
+    ? content.split(oldString).join(newString)
+    : content.replace(oldString, newString);
+  if (after.length > MAX_WRITE_CHARS) {
+    throw new Error(`resultado grande demais (${after.length} chars, max ${MAX_WRITE_CHARS})`);
+  }
+  return { full, before: content, after, occurrences };
+}
+
+function editFile(cwd, args) {
+  const { full, after, occurrences } = applyEdit(cwd, args);
+  fs.writeFileSync(full, after, "utf8");
+  return `ok: ${relative(cwd, full)} editado (${occurrences} trecho${occurrences > 1 ? "s" : ""})`;
+}
+
+function listDir(cwd, args) {
+  const full = resolveInside(cwd, args.path);
+  if (!fs.existsSync(full)) throw new Error(`diretorio nao encontrado: ${args.path || "."}`);
+  const entries = fs.readdirSync(full, { withFileTypes: true });
+  const rows = entries
+    .sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name))
+    .slice(0, MAX_LIST_ENTRIES)
+    .map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name));
+  const extra = entries.length > rows.length ? `\n... (+${entries.length - rows.length})` : "";
+  return `${relative(cwd, full)}\n${rows.join("\n")}${extra}`;
+}
+
+function runCommand(cwd, args) {
+  const command = String(args.command || "").trim();
+  if (!command) throw new Error("comando vazio");
+  const timeout = Math.min(120_000, Math.max(1_000, Number(args.timeout_ms) || COMMAND_TIMEOUT_MS));
+
+  const result = spawnSync(command, {
+    shell: true,
+    cwd: path.resolve(cwd),
+    timeout,
+    encoding: "utf8",
+    maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, KAFOX_CLI: "1" },
+  });
+
+  const stdout = truncate(result.stdout || "", MAX_OUTPUT_CHARS);
+  const stderr = truncate(result.stderr || "", MAX_OUTPUT_CHARS);
+  const parts = [`exit: ${result.status == null ? "?" : result.status}`];
+  if (result.error?.code === "ETIMEDOUT") parts.push(`timeout: ${timeout}ms`);
+  if (stdout.trim()) parts.push(`stdout:\n${stdout.trimEnd()}`);
+  if (stderr.trim()) parts.push(`stderr:\n${stderr.trimEnd()}`);
+  return parts.join("\n");
+}
+
+async function executeTool(name, args = {}, context = {}) {
+  const cwd = context.cwd || process.cwd();
+  if (!LOCAL_TOOL_NAMES.has(name)) {
+    if (context.mcp?.has?.(name)) return context.mcp.call(name, args);
+    throw new Error(`ferramenta desconhecida: ${name}`);
+  }
+  switch (name) {
+    case "read_file":
+      return readFile(cwd, args);
+    case "write_file":
+      return writeFile(cwd, args);
+    case "edit_file":
+      return editFile(cwd, args);
+    case "list_dir":
+      return listDir(cwd, args);
+    case "run_command":
+      return runCommand(cwd, args);
+    default:
+      throw new Error(`ferramenta desconhecida: ${name}`);
+  }
+}
+
+/**
+ * O que a ferramenta vai mudar no arquivo, sem escrever nada.
+ * Usado no modal de aprovacao e no diff mostrado na conversa.
+ */
+function previewToolChange(name, args = {}, context = {}) {
+  const cwd = context.cwd || process.cwd();
+  if (name === "write_file") {
+    const full = resolveInside(cwd, args.path);
+    const exists = fs.existsSync(full) && !fs.statSync(full).isDirectory();
+    return {
+      kind: exists ? "update" : "create",
+      path: relative(cwd, full),
+      before: exists ? fs.readFileSync(full, "utf8") : null,
+      after: String(args.content ?? ""),
+    };
+  }
+  if (name === "edit_file") {
+    try {
+      const { full, before, after, occurrences } = applyEdit(cwd, args);
+      return { kind: "edit", path: relative(cwd, full), before, after, occurrences };
+    } catch (error) {
+      return {
+        kind: "edit",
+        path: String(args.path || ""),
+        before: null,
+        after: null,
+        error: error.message,
+      };
+    }
+  }
+  if (name === "run_command") {
+    return { kind: "command", command: String(args.command || "") };
+  }
+  return null;
+}
+
+/** Resumo curto da chamada para mostrar na conversa. */
+function describeToolCall(name, args = {}) {
+  if (name === "spawn_subagent") {
+    const tasks = Array.isArray(args.tasks) ? args.tasks : args.objective ? [args] : [];
+    if (!tasks.length) return "(sem objetivo)";
+    if (tasks.length === 1) return String(tasks[0].objective || "(objetivo)").slice(0, 120);
+    return `${tasks.length} subagentes: ${tasks
+      .map((task) => String(task.objective || "").slice(0, 40))
+      .join(" | ")}`;
+  }
+  if (name === "read_file") return args.path || "(arquivo)";
+  if (name === "write_file") return `${args.path || "(arquivo)"} (${String(args.content || "").length} chars)`;
+  if (name === "edit_file") return `${args.path || "(arquivo)"}`;
+  if (name === "list_dir") return args.path || ".";
+  if (name === "run_command") return args.command || "(comando)";
+  return "";
+}
+
+/**
+ * Separa a saida de run_command no que a TUI precisa mostrar:
+ * codigo de saida, se deu timeout, stdout e stderr.
+ */
+function parseCommandOutput(output) {
+  const result = { exit: null, timedOut: false, stdout: [], stderr: [] };
+  let bucket = null;
+
+  for (const raw of String(output ?? "").split("\n")) {
+    const line = raw.replace(/\s+$/, "");
+    const exit = line.match(/^exit:\s*(.+)$/);
+    if (exit) {
+      result.exit = exit[1].trim() === "?" ? null : Number(exit[1]);
+      continue;
+    }
+    if (/^timeout:\s*\d+ms$/.test(line)) {
+      result.timedOut = true;
+      continue;
+    }
+    if (line === "stdout:") {
+      bucket = "stdout";
+      continue;
+    }
+    if (line === "stderr:") {
+      bucket = "stderr";
+      continue;
+    }
+    if (bucket) result[bucket].push(line);
+  }
+
+  return result;
+}
+
+/** Uma linha de resumo do resultado (primeira linha util da saida). */
+function summarizeOutput(output) {
+  const first = String(output || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)[0];
+  return first ? first.slice(0, 200) : "(sem saida)";
+}
+
+module.exports = {
+  TOOL_SPECS,
+  TOOL_NAMES,
+  LOCAL_TOOL_NAMES,
+  APPROVAL_REQUIRED,
+  TOOL_META,
+  toolMeta,
+  executeTool,
+  previewToolChange,
+  describeToolCall,
+  summarizeOutput,
+  parseCommandOutput,
+  resolveInside,
+  MAX_WRITE_CHARS,
+};