zero-ai-cli 1.0.0

package/packages/core/src/tools/builtin.ts

@@ -0,0 +1,568 @@
+/**
+ * ZERO Built-in Tools
+ * Core tool implementations combining best patterns from all 9 projects
+ *
+ * Sources:
+ * - File operations: aider (diff editing) + cline (precise edits) + kilocode
+ * - Shell execution: gemini-cli (sandboxed) + crush (session management)
+ * - Search: opencode (ripgrep integration) + kilocode (indexing)
+ * - Git: cline (comprehensive git support) + aider
+ * - Memory: kilocode (kilo-memory) + goose (memory MCP)
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { execSync, spawn } from "node:child_process";
+import type { ToolDefinition, ToolContext, ToolResult } from "../types.js";
+
+// ============================================================================
+// File Operations
+// ============================================================================
+
+export const readFileTool: ToolDefinition = {
+  name: "read_file",
+  description: "Read the contents of a file. Supports text files. Returns the file content as text with line numbers.",
+  parameters: {
+    path: { type: "string", description: "Path to the file to read (relative to working directory)", required: true },
+    startLine: { type: "number", description: "Start reading from this line (1-indexed)", required: false },
+    endLine: { type: "number", description: "Stop reading at this line (inclusive)", required: false },
+  },
+  category: "file",
+  requiresApproval: false,
+  handler: async (args, context) => {
+    const filePath = path.resolve(context.workingDirectory, args.path as string);
+    try {
+      const content = await fs.readFile(filePath, "utf-8");
+      const lines = content.split("\n");
+
+      const startLine = (args.startLine as number) || 1;
+      const endLine = (args.endLine as number) || lines.length;
+
+      const selectedLines = lines.slice(startLine - 1, endLine);
+      const numbered = selectedLines
+        .map((line, i) => `${String(startLine + i).padStart(5)} | ${line}`)
+        .join("\n");
+
+      return {
+        success: true,
+        output: `File: ${args.path}\nLines: ${startLine}-${endLine} of ${lines.length}\n\n${numbered}`,
+        data: { path: args.path, lines: lines.length, content },
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: `Failed to read file: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};
+
+export const writeFileTool: ToolDefinition = {
+  name: "write_file",
+  description: "Write content to a file. Creates the file if it doesn't exist, or overwrites if it does. Parent directories are created automatically.",
+  parameters: {
+    path: { type: "string", description: "Path to the file to write (relative to working directory)", required: true },
+    content: { type: "string", description: "The content to write to the file", required: true },
+  },
+  category: "file",
+  requiresApproval: true,
+  handler: async (args, context) => {
+    const filePath = path.resolve(context.workingDirectory, args.path as string);
+    try {
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.writeFile(filePath, args.content as string, "utf-8");
+      const lineCount = (args.content as string).split("\n").length;
+      return {
+        success: true,
+        output: `Successfully wrote ${lineCount} lines to ${args.path}`,
+        data: { path: args.path, lines: lineCount },
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: `Failed to write file: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};
+
+export const editFileTool: ToolDefinition = {
+  name: "edit_file",
+  description: `Edit a file by finding and replacing text. Uses exact string matching.
+Provide the exact old text to find and the new text to replace it with.
+Only the first occurrence is replaced. Use sufficient context in oldText to ensure uniqueness.`,
+  parameters: {
+    path: { type: "string", description: "Path to the file to edit (relative to working directory)", required: true },
+    oldText: { type: "string", description: "The exact text to find and replace", required: true },
+    newText: { type: "string", description: "The new text to replace with", required: true },
+  },
+  category: "file",
+  requiresApproval: true,
+  handler: async (args, context) => {
+    const filePath = path.resolve(context.workingDirectory, args.path as string);
+    try {
+      const content = await fs.readFile(filePath, "utf-8");
+      const oldText = args.oldText as string;
+      const newText = args.newText as string;
+
+      // Count occurrences
+      const count = content.split(oldText).length - 1;
+
+      if (count === 0) {
+        return {
+          success: false,
+          output: "",
+          error: `Text not found in file. Make sure the oldText matches exactly.`,
+        };
+      }
+
+      if (count > 1) {
+        return {
+          success: false,
+          output: "",
+          error: `Text found ${count} times. Provide more context in oldText to ensure uniqueness.`,
+        };
+      }
+
+      const newContent = content.replace(oldText, newText);
+      await fs.writeFile(filePath, newContent, "utf-8");
+
+      return {
+        success: true,
+        output: `Successfully edited ${args.path}`,
+        data: { path: args.path, occurrences: 1 },
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: `Failed to edit file: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};
+
+export const listDirectoryTool: ToolDefinition = {
+  name: "list_directory",
+  description: "List files and directories in a path. Shows file sizes and types. Respects .gitignore patterns.",
+  parameters: {
+    path: { type: "string", description: "Path to list (relative to working directory). Defaults to root.", required: false },
+    recursive: { type: "boolean", description: "List recursively", required: false, default: false },
+    maxDepth: { type: "number", description: "Maximum depth for recursive listing", required: false, default: 3 },
+  },
+  category: "file",
+  requiresApproval: false,
+  handler: async (args, context) => {
+    const dirPath = path.resolve(context.workingDirectory, (args.path as string) || ".");
+    const recursive = (args.recursive as boolean) || false;
+    const maxDepth = (args.maxDepth as number) || 3;
+
+    try {
+      const results: string[] = [];
+
+      async function listDir(dir: string, prefix: string, depth: number): Promise<void> {
+        if (depth > maxDepth) return;
+
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        const sorted = entries.sort((a, b) => {
+          if (a.isDirectory() && !b.isDirectory()) return -1;
+          if (!a.isDirectory() && b.isDirectory()) return 1;
+          return a.name.localeCompare(b.name);
+        });
+
+        for (const entry of sorted) {
+          if (entry.name.startsWith(".") && entry.name !== ".env") continue;
+          if (entry.name === "node_modules" || entry.name === "__pycache__") continue;
+
+          const icon = entry.isDirectory() ? "📁" : "📄";
+          results.push(`${prefix}${icon} ${entry.name}`);
+
+          if (entry.isDirectory() && recursive) {
+            await listDir(path.join(dir, entry.name), prefix + "  ", depth + 1);
+          }
+        }
+      }
+
+      await listDir(dirPath, "", 0);
+
+      return {
+        success: true,
+        output: results.join("\n") || "(empty directory)",
+        data: { path: args.path || ".", count: results.length },
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: `Failed to list directory: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};
+
+// ============================================================================
+// Search Operations
+// ============================================================================
+
+export const searchFilesTool: ToolDefinition = {
+  name: "search_files",
+  description: "Search for files by name pattern using glob syntax. Fast and efficient for finding specific files.",
+  parameters: {
+    pattern: { type: "string", description: "Glob pattern to match (e.g., '*.ts', 'test/**/*.spec.js')", required: true },
+    path: { type: "string", description: "Directory to search in (relative to working directory)", required: false },
+  },
+  category: "search",
+  requiresApproval: false,
+  handler: async (args, context) => {
+    const searchDir = path.resolve(context.workingDirectory, (args.path as string) || ".");
+    const pattern = args.pattern as string;
+
+    try {
+      // Use find command for portability
+      const findCmd = `find "${searchDir}" -name "${pattern.replace(/\*/g, "*")}" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -50`;
+      const output = execSync(findCmd, { encoding: "utf-8", timeout: 10000 }).trim();
+
+      const files = output.split("\n").filter(Boolean).map((f) =>
+        path.relative(context.workingDirectory, f)
+      );
+
+      return {
+        success: true,
+        output: files.length > 0
+          ? `Found ${files.length} files:\n${files.join("\n")}`
+          : "No files found matching pattern",
+        data: { files, count: files.length },
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: `Search failed: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};
+
+export const searchCodeTool: ToolDefinition = {
+  name: "search_code",
+  description: "Search for text/code patterns across all files. Uses grep/ripgrep for fast searching. Shows matching lines with context.",
+  parameters: {
+    query: { type: "string", description: "Text or regex pattern to search for", required: true },
+    path: { type: "string", description: "Directory to search in (relative to working directory)", required: false },
+    filePattern: { type: "string", description: "File extension filter (e.g., '*.ts', '*.py')", required: false },
+    caseSensitive: { type: "boolean", description: "Case sensitive search", required: false, default: true },
+  },
+  category: "search",
+  requiresApproval: false,
+  handler: async (args, context) => {
+    const searchDir = path.resolve(context.workingDirectory, (args.path as string) || ".");
+    const query = args.query as string;
+    const filePattern = args.filePattern as string;
+    const caseSensitive = args.caseSensitive !== false;
+
+    try {
+      // Try ripgrep first, fall back to grep
+      let cmd: string;
+      const ignoreFlags = "--exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build";
+      const includeFlag = filePattern ? `--include='${filePattern}'` : "";
+      const caseFlag = caseSensitive ? "" : "-i";
+
+      cmd = `grep -rn ${caseFlag} ${ignoreFlags} ${includeFlag} -- "${query.replace(/"/g, '\\"')}" "${searchDir}" | head -50`;
+
+      const output = execSync(cmd, { encoding: "utf-8", timeout: 15000, maxBuffer: 1024 * 1024 }).trim();
+
+      if (!output) {
+        return { success: true, output: "No matches found.", data: { matches: [], count: 0 } };
+      }
+
+      const matches = output.split("\n").map((line) => {
+        const parts = line.split(":");
+        return {
+          file: path.relative(context.workingDirectory, parts[0] || ""),
+          line: parseInt(parts[1] || "0"),
+          content: parts.slice(2).join(":").trim(),
+        };
+      });
+
+      return {
+        success: true,
+        output: `Found ${matches.length} matches:\n\n${output}`,
+        data: { matches, count: matches.length },
+      };
+    } catch (error) {
+      // grep returns non-zero when no matches
+      if ((error as any)?.status === 1) {
+        return { success: true, output: "No matches found.", data: { matches: [], count: 0 } };
+      }
+      return {
+        success: false,
+        output: "",
+        error: `Code search failed: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};
+
+// ============================================================================
+// Shell Execution
+// ============================================================================
+
+export const executeShellTool: ToolDefinition = {
+  name: "execute_shell",
+  description: `Execute a shell command in the working directory. Use for running tests, installing packages, building projects, etc.
+Commands are executed with a timeout. Output is truncated if too long.
+WARNING: Commands that modify the filesystem or install packages require user approval.`,
+  parameters: {
+    command: { type: "string", description: "Shell command to execute", required: true },
+    timeout: { type: "number", description: "Timeout in seconds (default: 30, max: 120)", required: false, default: 30 },
+  },
+  category: "shell",
+  requiresApproval: true,
+  handler: async (args, context) => {
+    const command = args.command as string;
+    const timeout = Math.min(((args.timeout as number) || 30) * 1000, 120000);
+
+    try {
+      const output = execSync(command, {
+        cwd: context.workingDirectory,
+        encoding: "utf-8",
+        timeout,
+        maxBuffer: 5 * 1024 * 1024,
+        shell: "/bin/bash",
+        env: { ...process.env, ZERO_SESSION_ID: context.sessionId },
+      });
+
+      // Truncate if too long
+      const maxOutput = 10000;
+      const truncated = output.length > maxOutput
+        ? output.slice(0, maxOutput) + `\n\n... [truncated ${output.length - maxOutput} characters]`
+        : output;
+
+      return {
+        success: true,
+        output: truncated || "(command completed with no output)",
+        data: { exitCode: 0 },
+      };
+    } catch (error: any) {
+      const output = (error.stdout || "") + (error.stderr || "");
+      const truncated = output.length > 10000
+        ? output.slice(0, 10000) + "\n\n... [truncated]"
+        : output;
+
+      return {
+        success: false,
+        output: truncated,
+        error: `Command failed with exit code ${error.status || "unknown"}`,
+        data: { exitCode: error.status },
+      };
+    }
+  },
+};
+
+// ============================================================================
+// Git Operations
+// ============================================================================
+
+export const gitStatusTool: ToolDefinition = {
+  name: "git_status",
+  description: "Get the current git status showing modified, added, deleted, and untracked files.",
+  parameters: {
+    path: { type: "string", description: "Repository path (relative to working directory)", required: false },
+  },
+  category: "git",
+  requiresApproval: false,
+  handler: async (args, context) => {
+    const repoPath = path.resolve(context.workingDirectory, (args.path as string) || ".");
+    try {
+      const status = execSync("git status --porcelain=v2 --branch", {
+        cwd: repoPath,
+        encoding: "utf-8",
+        timeout: 10000,
+      });
+
+      const log = execSync("git log --oneline -5", {
+        cwd: repoPath,
+        encoding: "utf-8",
+        timeout: 10000,
+      }).trim();
+
+      return {
+        success: true,
+        output: `Git Status:\n${status}\n\nRecent Commits:\n${log}`,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: `Git status failed: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};
+
+export const gitDiffTool: ToolDefinition = {
+  name: "git_diff",
+  description: "Show git diff of changes. Can show staged, unstaged, or changes compared to a specific commit/branch.",
+  parameters: {
+    path: { type: "string", description: "File or directory to diff", required: false },
+    staged: { type: "boolean", description: "Show staged changes", required: false, default: false },
+    ref: { type: "string", description: "Compare against this ref (commit, branch, tag)", required: false },
+  },
+  category: "git",
+  requiresApproval: false,
+  handler: async (args, context) => {
+    const repoPath = context.workingDirectory;
+    const filePath = args.path as string;
+    const staged = args.staged as boolean;
+    const ref = args.ref as string;
+
+    try {
+      let cmd = "git diff";
+      if (staged) cmd += " --cached";
+      if (ref) cmd += ` ${ref}`;
+      if (filePath) cmd += ` -- ${filePath}`;
+
+      const output = execSync(cmd, {
+        cwd: repoPath,
+        encoding: "utf-8",
+        timeout: 15000,
+        maxBuffer: 5 * 1024 * 1024,
+      });
+
+      return {
+        success: true,
+        output: output || "No changes detected.",
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: `Git diff failed: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};
+
+export const gitCommitTool: ToolDefinition = {
+  name: "git_commit",
+  description: "Stage all changes and create a git commit with the provided message.",
+  parameters: {
+    message: { type: "string", description: "Commit message", required: true },
+    files: { type: "array", description: "Specific files to stage (if empty, stages all)", required: false },
+  },
+  category: "git",
+  requiresApproval: true,
+  handler: async (args, context) => {
+    const message = args.message as string;
+    const files = args.files as string[] | undefined;
+
+    try {
+      if (files && files.length > 0) {
+        for (const file of files) {
+          execSync(`git add "${file}"`, { cwd: context.workingDirectory, timeout: 10000 });
+        }
+      } else {
+        execSync("git add -A", { cwd: context.workingDirectory, timeout: 10000 });
+      }
+
+      const output = execSync(`git commit -m "${message.replace(/"/g, '\\"')}"`, {
+        cwd: context.workingDirectory,
+        encoding: "utf-8",
+        timeout: 10000,
+      });
+
+      return {
+        success: true,
+        output: output.trim(),
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: `Git commit failed: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};
+
+// ============================================================================
+// Web Operations
+// ============================================================================
+
+export const webFetchTool: ToolDefinition = {
+  name: "web_fetch",
+  description: "Fetch content from a URL. Returns the text content of the page.",
+  parameters: {
+    url: { type: "string", description: "URL to fetch", required: true },
+  },
+  category: "web",
+  requiresApproval: true,
+  handler: async (args) => {
+    const url = args.url as string;
+    try {
+      const response = await fetch(url, {
+        headers: { "User-Agent": "ZERO/1.0" },
+        signal: AbortSignal.timeout(30000),
+      });
+
+      if (!response.ok) {
+        return { success: false, output: "", error: `HTTP ${response.status}: ${response.statusText}` };
+      }
+
+      const text = await response.text();
+      const truncated = text.length > 50000 ? text.slice(0, 50000) + "\n... [truncated]" : text;
+
+      return {
+        success: true,
+        output: truncated,
+        data: { url, contentType: response.headers.get("content-type"), status: response.status },
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: "",
+        error: `Fetch failed: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};
+
+export const webSearchTool: ToolDefinition = {
+  name: "web_search",
+  description: "Search the web for information. Returns relevant results with titles, URLs, and snippets.",
+  parameters: {
+    query: { type: "string", description: "Search query", required: true },
+  },
+  category: "web",
+  requiresApproval: false,
+  handler: async (args) => {
+    // Placeholder - would integrate with a search API
+    return {
+      success: true,
+      output: `Web search for: "${args.query}"\n(Configure a search API key in ZERO config to enable web search)`,
+    };
+  },
+};
+
+// ============================================================================
+// Export all tools
+// ============================================================================
+
+export function getAllBuiltinTools(): ToolDefinition[] {
+  return [
+    readFileTool,
+    writeFileTool,
+    editFileTool,
+    listDirectoryTool,
+    searchFilesTool,
+    searchCodeTool,
+    executeShellTool,
+    gitStatusTool,
+    gitDiffTool,
+    gitCommitTool,
+    webFetchTool,
+    webSearchTool,
+  ];
+}