@heysalad/cheri-cli 0.1.0 → 0.2.0

package/bin/cheri.js

@@ -7,11 +7,12 @@ import { registerStatusCommand } from "../src/commands/status.js";
 import { registerMemoryCommand } from "../src/commands/memory.js";
 import { registerConfigCommand } from "../src/commands/config.js";
 import { registerWorkspaceCommand } from "../src/commands/workspace.js";
+import { registerChatCommand } from "../src/commands/chat.js";
 
 program
   .name("cheri")
   .description("Cheri CLI - AI-powered cloud IDE by HeySalad")
-  .version("0.1.0");
+  .version("0.2.0");
 
 registerLoginCommand(program);
 registerInitCommand(program);
@@ -19,10 +20,12 @@ registerStatusCommand(program);
 registerMemoryCommand(program);
 registerConfigCommand(program);
 registerWorkspaceCommand(program);
+registerChatCommand(program);
 
-program.parse(process.argv);
-
-// Show help if no command provided
+// If no args, launch interactive REPL
 if (!process.argv.slice(2).length) {
-  program.outputHelp();
+  const { startRepl } = await import("../src/lib/repl.js");
+  await startRepl();
+} else {
+  program.parse(process.argv);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heysalad/cheri-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Cheri CLI - AI-powered cloud IDE by HeySalad. Like Claude Code, but for cloud workspaces.",
   "type": "module",
   "bin": {
@@ -38,9 +38,14 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "@google/generative-ai": "^0.24.1",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "inquirer": "^9.2.23",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
+    "openai": "^6.22.0",
     "ora": "^8.0.1"
   }
 }

package/src/commands/chat.js

@@ -0,0 +1,15 @@
+import { startRepl } from "../lib/repl.js";
+
+export function registerChatCommand(program) {
+  program
+    .command("chat")
+    .description("Start an interactive AI coding session")
+    .option("-p, --provider <provider>", "AI provider (anthropic, openai, deepseek, gemini)")
+    .option("-m, --model <model>", "Model to use (overrides provider default)")
+    .action(async (options) => {
+      await startRepl({
+        provider: options.provider,
+        model: options.model,
+      });
+    });
+}

package/src/lib/branding.js

@@ -0,0 +1,36 @@
+import chalk from "chalk";
+import { getConfigValue } from "./config-store.js";
+
+const CHERRY_ART = `
+      ${chalk.red("🍒🍒")}
+     ${chalk.red("🍒  🍒")}
+`;
+
+export function showStartupScreen(options = {}) {
+  const provider = options.provider || getConfigValue("ai.provider") || "anthropic";
+  const model = options.model || getConfigValue("ai.model") || getDefaultModel(provider);
+  const cwd = process.cwd();
+  const version = "0.2.0";
+
+  console.log(CHERRY_ART);
+  console.log(chalk.bold(`  cheri  v${version}`));
+  console.log(chalk.dim("  AI coding agent by HeySalad"));
+  console.log();
+  console.log(`  ${chalk.dim("Provider:")}  ${chalk.cyan(provider)}`);
+  console.log(`  ${chalk.dim("Model:")}     ${chalk.cyan(model)}`);
+  console.log(`  ${chalk.dim("Directory:")} ${chalk.cyan(cwd)}`);
+  console.log();
+  console.log(chalk.dim("  Type your request. /help for commands, Ctrl+C to exit."));
+  console.log(chalk.dim("  " + "─".repeat(48)));
+  console.log();
+}
+
+export function getDefaultModel(provider) {
+  const defaults = {
+    anthropic: "claude-sonnet-4-20250514",
+    openai: "gpt-4o",
+    deepseek: "deepseek-chat",
+    gemini: "gemini-2.0-flash",
+  };
+  return defaults[provider] || "unknown";
+}

package/src/lib/config-store.js

@@ -74,5 +74,15 @@ function getDefaultConfig() {
       theme: "dark",
       fontSize: 14,
     },
+    ai: {
+      provider: "anthropic",
+      model: "",
+      keys: {
+        anthropic: "",
+        openai: "",
+        deepseek: "",
+        gemini: "",
+      },
+    },
   };
 }

package/src/lib/providers/anthropic.js

@@ -0,0 +1,66 @@
+import { BaseProvider, SYSTEM_PROMPT } from "./base.js";
+
+export class AnthropicProvider extends BaseProvider {
+  constructor(apiKey, model = "claude-sonnet-4-20250514") {
+    super(apiKey, model);
+  }
+
+  async *chat(messages, tools) {
+    const { default: Anthropic } = await import("@anthropic-ai/sdk");
+    const client = new Anthropic({ apiKey: this.apiKey });
+
+    const anthropicTools = tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.parameters,
+    }));
+
+    const stream = await client.messages.stream({
+      model: this.model,
+      max_tokens: 8192,
+      system: SYSTEM_PROMPT,
+      messages,
+      tools: anthropicTools.length > 0 ? anthropicTools : undefined,
+    });
+
+    let currentToolId = null;
+    let currentToolName = null;
+    let toolInputJson = "";
+
+    for await (const event of stream) {
+      if (event.type === "content_block_start") {
+        if (event.content_block.type === "text") {
+          // text block starting
+        } else if (event.content_block.type === "tool_use") {
+          currentToolId = event.content_block.id;
+          currentToolName = event.content_block.name;
+          toolInputJson = "";
+          yield { type: "tool_use_start", id: currentToolId, name: currentToolName };
+        }
+      } else if (event.type === "content_block_delta") {
+        if (event.delta.type === "text_delta") {
+          yield { type: "text", content: event.delta.text };
+        } else if (event.delta.type === "input_json_delta") {
+          toolInputJson += event.delta.partial_json;
+          yield { type: "tool_input_delta", content: event.delta.partial_json };
+        }
+      } else if (event.type === "content_block_stop") {
+        if (currentToolId) {
+          let input = {};
+          try {
+            input = JSON.parse(toolInputJson);
+          } catch {}
+          yield { type: "tool_use_end", id: currentToolId, name: currentToolName, input };
+          currentToolId = null;
+          currentToolName = null;
+          toolInputJson = "";
+        }
+      } else if (event.type === "message_stop") {
+        // done
+      }
+    }
+
+    const finalMessage = await stream.finalMessage();
+    yield { type: "done", stopReason: finalMessage.stop_reason };
+  }
+}

package/src/lib/providers/base.js

@@ -0,0 +1,34 @@
+export const SYSTEM_PROMPT = `You are Cheri, an AI coding assistant by HeySalad. You help developers write, debug, and understand code.
+
+You have access to tools that let you read files, write files, edit files, run shell commands, search files, and list directories. Use them proactively to help the user.
+
+Guidelines:
+- Read files before modifying them to understand the existing code.
+- Use edit_file for targeted changes instead of rewriting entire files.
+- When running commands, explain what you're about to run and why.
+- Be concise but thorough. Show relevant code snippets in your responses.
+- If you're unsure about something, say so rather than guessing.
+- Format responses with markdown for readability.`;
+
+export class BaseProvider {
+  constructor(apiKey, model) {
+    this.apiKey = apiKey;
+    this.model = model;
+  }
+
+  /**
+   * Async generator that yields streaming events:
+   *   { type: "text", content: string }
+   *   { type: "tool_use_start", id: string, name: string }
+   *   { type: "tool_input_delta", content: string }
+   *   { type: "tool_use_end", id: string, name: string, input: object }
+   *   { type: "done", stopReason: string }
+   */
+  async *chat(messages, tools) {
+    throw new Error("chat() must be implemented by subclass");
+  }
+
+  getModel() {
+    return this.model;
+  }
+}

package/src/lib/providers/gemini.js

@@ -0,0 +1,89 @@
+import { BaseProvider, SYSTEM_PROMPT } from "./base.js";
+
+export class GeminiProvider extends BaseProvider {
+  constructor(apiKey, model = "gemini-2.0-flash") {
+    super(apiKey, model);
+  }
+
+  async *chat(messages, tools) {
+    const { GoogleGenerativeAI } = await import("@google/generative-ai");
+    const genAI = new GoogleGenerativeAI(this.apiKey);
+
+    const geminiTools = tools.length > 0 ? [{
+      functionDeclarations: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      })),
+    }] : undefined;
+
+    const genModel = genAI.getGenerativeModel({
+      model: this.model,
+      systemInstruction: SYSTEM_PROMPT,
+      tools: geminiTools,
+    });
+
+    // Convert messages to Gemini format
+    const history = [];
+    for (const msg of messages.slice(0, -1)) {
+      const role = msg.role === "assistant" ? "model" : "user";
+      if (typeof msg.content === "string") {
+        history.push({ role, parts: [{ text: msg.content }] });
+      } else if (Array.isArray(msg.content)) {
+        const parts = [];
+        for (const block of msg.content) {
+          if (block.type === "text") {
+            parts.push({ text: block.text });
+          } else if (block.type === "tool_use") {
+            parts.push({ functionCall: { name: block.name, args: block.input } });
+          } else if (block.type === "tool_result") {
+            const resultText = typeof block.content === "string" ? block.content : JSON.stringify(block.content);
+            parts.push({ functionResponse: { name: block.name || "tool", response: { result: resultText } } });
+          }
+        }
+        if (parts.length > 0) history.push({ role, parts });
+      }
+    }
+
+    const chat = genModel.startChat({ history });
+
+    // Get the last message content
+    const lastMsg = messages[messages.length - 1];
+    const lastContent = typeof lastMsg.content === "string"
+      ? lastMsg.content
+      : lastMsg.content.map((b) => {
+          if (b.type === "text") return b.text;
+          if (b.type === "tool_result") {
+            return typeof b.content === "string" ? b.content : JSON.stringify(b.content);
+          }
+          return "";
+        }).join("\n");
+
+    const result = await chat.sendMessageStream(lastContent);
+
+    let hasToolCalls = false;
+
+    for await (const chunk of result.stream) {
+      const text = chunk.text();
+      if (text) {
+        yield { type: "text", content: text };
+      }
+
+      // Check for function calls
+      const candidates = chunk.candidates || [];
+      for (const candidate of candidates) {
+        for (const part of candidate.content?.parts || []) {
+          if (part.functionCall) {
+            hasToolCalls = true;
+            const id = `gemini_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+            yield { type: "tool_use_start", id, name: part.functionCall.name };
+            yield { type: "tool_input_delta", content: JSON.stringify(part.functionCall.args) };
+            yield { type: "tool_use_end", id, name: part.functionCall.name, input: part.functionCall.args || {} };
+          }
+        }
+      }
+    }
+
+    yield { type: "done", stopReason: hasToolCalls ? "tool_use" : "end_turn" };
+  }
+}

package/src/lib/providers/index.js

@@ -0,0 +1,47 @@
+import { getConfigValue } from "../config-store.js";
+import { getDefaultModel } from "../branding.js";
+
+export async function createProvider(options = {}) {
+  const provider = options.provider || getConfigValue("ai.provider") || "anthropic";
+  const model = options.model || getConfigValue("ai.model") || getDefaultModel(provider);
+
+  // Resolve API key: env var takes priority, then config
+  const envKeys = {
+    anthropic: "ANTHROPIC_API_KEY",
+    openai: "OPENAI_API_KEY",
+    deepseek: "DEEPSEEK_API_KEY",
+    gemini: "GEMINI_API_KEY",
+  };
+
+  const apiKey = process.env[envKeys[provider]] || getConfigValue(`ai.keys.${provider}`);
+
+  if (!apiKey) {
+    throw new Error(
+      `No API key found for ${provider}. Set it with:\n` +
+      `  cheri config set ai.keys.${provider} <your-key>\n` +
+      `Or set the ${envKeys[provider]} environment variable.`
+    );
+  }
+
+  // Lazy import only the selected provider
+  switch (provider) {
+    case "anthropic": {
+      const { AnthropicProvider } = await import("./anthropic.js");
+      return new AnthropicProvider(apiKey, model);
+    }
+    case "openai": {
+      const { OpenAIProvider } = await import("./openai.js");
+      return new OpenAIProvider(apiKey, model);
+    }
+    case "deepseek": {
+      const { DeepSeekProvider } = await import("./openai.js");
+      return new DeepSeekProvider(apiKey, model);
+    }
+    case "gemini": {
+      const { GeminiProvider } = await import("./gemini.js");
+      return new GeminiProvider(apiKey, model);
+    }
+    default:
+      throw new Error(`Unknown provider: ${provider}. Supported: anthropic, openai, deepseek, gemini`);
+  }
+}

package/src/lib/providers/openai.js

@@ -0,0 +1,105 @@
+import { BaseProvider, SYSTEM_PROMPT } from "./base.js";
+
+export class OpenAIProvider extends BaseProvider {
+  constructor(apiKey, model = "gpt-4o", baseURL = undefined) {
+    super(apiKey, model);
+    this.baseURL = baseURL;
+  }
+
+  async *chat(messages, tools) {
+    const { default: OpenAI } = await import("openai");
+    const clientOpts = { apiKey: this.apiKey };
+    if (this.baseURL) clientOpts.baseURL = this.baseURL;
+    const client = new OpenAI(clientOpts);
+
+    // Convert from Anthropic message format to OpenAI format
+    const openaiMessages = [{ role: "system", content: SYSTEM_PROMPT }];
+    for (const msg of messages) {
+      if (typeof msg.content === "string") {
+        openaiMessages.push({ role: msg.role, content: msg.content });
+      } else if (Array.isArray(msg.content)) {
+        // Handle tool results and multi-part content
+        for (const block of msg.content) {
+          if (block.type === "tool_result") {
+            openaiMessages.push({
+              role: "tool",
+              tool_call_id: block.tool_use_id,
+              content: typeof block.content === "string" ? block.content : JSON.stringify(block.content),
+            });
+          } else if (block.type === "text") {
+            openaiMessages.push({ role: msg.role, content: block.text });
+          } else if (block.type === "tool_use") {
+            // Assistant message with tool call
+            openaiMessages.push({
+              role: "assistant",
+              content: null,
+              tool_calls: [{
+                id: block.id,
+                type: "function",
+                function: { name: block.name, arguments: JSON.stringify(block.input) },
+              }],
+            });
+          }
+        }
+      }
+    }
+
+    const openaiTools = tools.map((t) => ({
+      type: "function",
+      function: { name: t.name, description: t.description, parameters: t.parameters },
+    }));
+
+    const stream = await client.chat.completions.create({
+      model: this.model,
+      messages: openaiMessages,
+      tools: openaiTools.length > 0 ? openaiTools : undefined,
+      stream: true,
+    });
+
+    const toolCalls = {};
+
+    for await (const chunk of stream) {
+      const delta = chunk.choices?.[0]?.delta;
+      const finishReason = chunk.choices?.[0]?.finish_reason;
+
+      if (delta?.content) {
+        yield { type: "text", content: delta.content };
+      }
+
+      if (delta?.tool_calls) {
+        for (const tc of delta.tool_calls) {
+          const idx = tc.index;
+          if (!toolCalls[idx]) {
+            toolCalls[idx] = { id: tc.id || "", name: "", arguments: "" };
+          }
+          if (tc.id) toolCalls[idx].id = tc.id;
+          if (tc.function?.name) {
+            toolCalls[idx].name = tc.function.name;
+            yield { type: "tool_use_start", id: toolCalls[idx].id, name: tc.function.name };
+          }
+          if (tc.function?.arguments) {
+            toolCalls[idx].arguments += tc.function.arguments;
+            yield { type: "tool_input_delta", content: tc.function.arguments };
+          }
+        }
+      }
+
+      if (finishReason) {
+        // Emit tool_use_end for any accumulated tool calls
+        for (const idx of Object.keys(toolCalls)) {
+          const tc = toolCalls[idx];
+          let input = {};
+          try { input = JSON.parse(tc.arguments); } catch {}
+          yield { type: "tool_use_end", id: tc.id, name: tc.name, input };
+        }
+        yield { type: "done", stopReason: finishReason === "tool_calls" ? "tool_use" : finishReason };
+      }
+    }
+  }
+}
+
+export class DeepSeekProvider extends OpenAIProvider {
+  constructor(apiKey, model = "deepseek-chat") {
+    super(apiKey, model, "https://api.deepseek.com");
+  }
+}

package/src/lib/renderer.js

@@ -0,0 +1,44 @@
+import chalk from "chalk";
+
+let markedRender = null;
+
+async function getMarked() {
+  if (markedRender) return markedRender;
+  const { marked } = await import("marked");
+  const { default: TerminalRenderer } = await import("marked-terminal");
+  marked.setOptions({
+    renderer: new TerminalRenderer({
+      reflowText: true,
+      width: Math.min(process.stdout.columns || 80, 100),
+      tab: 2,
+    }),
+  });
+  markedRender = marked;
+  return markedRender;
+}
+
+export async function renderMarkdown(text) {
+  try {
+    const marked = await getMarked();
+    return marked.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+export function renderToolUse(name, input) {
+  const shortInput = Object.entries(input || {})
+    .map(([k, v]) => {
+      const val = typeof v === "string" ? (v.length > 60 ? v.slice(0, 57) + "..." : v) : JSON.stringify(v);
+      return `${chalk.dim(k)}=${val}`;
+    })
+    .join(", ");
+  return `${chalk.magenta("🔧")} ${chalk.bold(name)}(${shortInput})`;
+}
+
+export function renderToolResult(name, result) {
+  if (result.error) {
+    return chalk.red(`❌ ${name}: ${result.error}`);
+  }
+  return chalk.green(`✅ ${name} completed`);
+}

package/src/lib/repl.js

@@ -0,0 +1,225 @@
+import readline from "readline";
+import chalk from "chalk";
+import ora from "ora";
+import { createProvider } from "./providers/index.js";
+import { getToolDefinitions, executeTool, requiresConfirmation } from "./tools/index.js";
+import { showStartupScreen } from "./branding.js";
+import { renderMarkdown, renderToolUse, renderToolResult } from "./renderer.js";
+
+export async function startRepl(options = {}) {
+  showStartupScreen(options);
+
+  let provider;
+  try {
+    provider = await createProvider(options);
+  } catch (err) {
+    console.error(chalk.red(`\n${err.message}`));
+    process.exit(1);
+  }
+
+  const messages = [];
+  const tools = getToolDefinitions();
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: "🍒 > ",
+  });
+
+  rl.prompt();
+
+  rl.on("line", async (line) => {
+    const input = line.trim();
+    if (!input) {
+      rl.prompt();
+      return;
+    }
+
+    // Slash commands
+    if (input.startsWith("/")) {
+      await handleSlashCommand(input, messages, provider, options, rl);
+      rl.prompt();
+      return;
+    }
+
+    // Add user message
+    messages.push({ role: "user", content: input });
+
+    // Run agent loop
+    await agentLoop(provider, messages, tools, rl);
+    rl.prompt();
+  });
+
+  rl.on("close", () => {
+    console.log(chalk.dim("\nGoodbye! 🍒"));
+    process.exit(0);
+  });
+}
+
+async function agentLoop(provider, messages, tools, rl) {
+  let continueLoop = true;
+
+  while (continueLoop) {
+    continueLoop = false;
+    const spinner = ora({ text: "Thinking...", color: "yellow" }).start();
+
+    let fullText = "";
+    const toolCalls = [];
+    let streamingStarted = false;
+
+    try {
+      for await (const event of provider.chat(messages, tools)) {
+        switch (event.type) {
+          case "text":
+            if (!streamingStarted) {
+              spinner.stop();
+              streamingStarted = true;
+            }
+            process.stdout.write(event.content);
+            fullText += event.content;
+            break;
+
+          case "tool_use_start":
+            if (!streamingStarted) {
+              spinner.stop();
+              streamingStarted = true;
+            }
+            toolCalls.push({ id: event.id, name: event.name, inputJson: "", input: {} });
+            break;
+
+          case "tool_input_delta":
+            if (toolCalls.length > 0) {
+              toolCalls[toolCalls.length - 1].inputJson += event.content;
+            }
+            break;
+
+          case "tool_use_end":
+            if (toolCalls.length > 0) {
+              const tc = toolCalls[toolCalls.length - 1];
+              tc.input = event.input;
+            }
+            break;
+
+          case "done":
+            spinner.stop();
+            if (event.stopReason === "tool_use" || toolCalls.length > 0) {
+              continueLoop = true;
+            }
+            break;
+        }
+      }
+    } catch (err) {
+      spinner.stop();
+      console.error(chalk.red(`\n❌ API Error: ${err.message}`));
+      // Remove the last user message on error so conversation stays valid
+      if (messages.length > 0 && messages[messages.length - 1].role === "user") {
+        messages.pop();
+      }
+      return;
+    }
+
+    // End text output with newline if we streamed any text
+    if (fullText) {
+      process.stdout.write("\n");
+    }
+
+    // Build assistant message content
+    const assistantContent = [];
+    if (fullText) {
+      assistantContent.push({ type: "text", text: fullText });
+    }
+    for (const tc of toolCalls) {
+      assistantContent.push({ type: "tool_use", id: tc.id, name: tc.name, input: tc.input });
+    }
+    if (assistantContent.length > 0) {
+      messages.push({ role: "assistant", content: assistantContent });
+    }
+
+    // Execute tool calls if any
+    if (toolCalls.length > 0) {
+      const toolResults = [];
+
+      for (const tc of toolCalls) {
+        console.log(renderToolUse(tc.name, tc.input));
+
+        // Confirmation for dangerous commands
+        if (requiresConfirmation(tc.name)) {
+          const confirmed = await askConfirmation(rl, `Run command: ${chalk.bold(tc.input.command || "")}`);
+          if (!confirmed) {
+            toolResults.push({
+              type: "tool_result",
+              tool_use_id: tc.id,
+              content: "User denied execution of this command.",
+            });
+            console.log(chalk.yellow("⏭️  Skipped"));
+            continue;
+          }
+          const cmdSpinner = ora({ text: `Running: ${tc.input.command}`, color: "red" }).start();
+          const result = await executeTool(tc.name, tc.input);
+          cmdSpinner.stop();
+          console.log(renderToolResult(tc.name, result));
+          toolResults.push({
+            type: "tool_result",
+            tool_use_id: tc.id,
+            content: JSON.stringify(result),
+          });
+        } else {
+          const toolSpinner = ora({ text: `${tc.name}...`, color: "magenta" }).start();
+          const result = await executeTool(tc.name, tc.input);
+          toolSpinner.stop();
+          console.log(renderToolResult(tc.name, result));
+          toolResults.push({
+            type: "tool_result",
+            tool_use_id: tc.id,
+            content: JSON.stringify(result),
+          });
+        }
+      }
+
+      messages.push({ role: "user", content: toolResults });
+    }
+  }
+}
+
+function askConfirmation(rl, message) {
+  return new Promise((resolve) => {
+    rl.question(`${chalk.yellow("⚡")} ${message} ${chalk.dim("[Y/n]")} `, (answer) => {
+      const a = answer.trim().toLowerCase();
+      resolve(a === "" || a === "y" || a === "yes");
+    });
+  });
+}
+
+async function handleSlashCommand(input, messages, provider, options, rl) {
+  const [cmd, ...args] = input.split(/\s+/);
+
+  switch (cmd) {
+    case "/help":
+      console.log(`
+${chalk.bold("Cheri REPL Commands:")}
+  ${chalk.cyan("/help")}    Show this help
+  ${chalk.cyan("/clear")}   Clear conversation history
+  ${chalk.cyan("/model")}   Show current model info
+  ${chalk.cyan("/exit")}    Exit the REPL
+`);
+      break;
+
+    case "/clear":
+      messages.length = 0;
+      console.log(chalk.dim("Conversation cleared."));
+      break;
+
+    case "/model":
+      console.log(`  Provider: ${chalk.cyan(options.provider || "anthropic")}`);
+      console.log(`  Model:    ${chalk.cyan(provider.getModel())}`);
+      break;
+
+    case "/exit":
+      console.log(chalk.dim("Goodbye! 🍒"));
+      process.exit(0);
+      break;
+
+    default:
+      console.log(chalk.yellow(`Unknown command: ${cmd}. Type /help for available commands.`));
+  }
+}

package/src/lib/tools/command-tools.js

@@ -0,0 +1,34 @@
+import { execSync } from "child_process";
+
+export const runCommand = {
+  name: "run_command",
+  description: "Execute a shell command and return its output. Requires user confirmation before execution.",
+  parameters: {
+    type: "object",
+    properties: {
+      command: { type: "string", description: "The shell command to execute" },
+      cwd: { type: "string", description: "Working directory (optional, defaults to current directory)" },
+    },
+    required: ["command"],
+  },
+  requiresConfirmation: true,
+  handler: async ({ command, cwd }) => {
+    try {
+      const output = execSync(command, {
+        cwd: cwd || process.cwd(),
+        encoding: "utf-8",
+        timeout: 120_000,
+        maxBuffer: 1024 * 1024 * 10,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      return { command, exitCode: 0, stdout: output, stderr: "" };
+    } catch (err) {
+      return {
+        command,
+        exitCode: err.status ?? 1,
+        stdout: err.stdout || "",
+        stderr: err.stderr || err.message,
+      };
+    }
+  },
+};

package/src/lib/tools/file-tools.js

@@ -0,0 +1,73 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { dirname } from "path";
+import { resolve } from "path";
+
+export const readFile = {
+  name: "read_file",
+  description: "Read the contents of a file at the given path. Returns the file contents as a string.",
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Absolute or relative file path to read" },
+    },
+    required: ["path"],
+  },
+  handler: async ({ path }) => {
+    const resolved = resolve(path);
+    if (!existsSync(resolved)) {
+      return { error: `File not found: ${resolved}` };
+    }
+    const content = readFileSync(resolved, "utf-8");
+    return { path: resolved, content, lines: content.split("\n").length };
+  },
+};
+
+export const writeFile = {
+  name: "write_file",
+  description: "Create or overwrite a file with the given content. Creates parent directories if needed.",
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Absolute or relative file path to write" },
+      content: { type: "string", description: "The content to write to the file" },
+    },
+    required: ["path", "content"],
+  },
+  handler: async ({ path, content }) => {
+    const resolved = resolve(path);
+    const dir = dirname(resolved);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(resolved, content, "utf-8");
+    return { path: resolved, bytesWritten: Buffer.byteLength(content, "utf-8") };
+  },
+};
+
+export const editFile = {
+  name: "edit_file",
+  description: "Edit a file by replacing an exact string match with new content. The old_string must match exactly (including whitespace and indentation).",
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Absolute or relative file path to edit" },
+      old_string: { type: "string", description: "The exact string to find and replace" },
+      new_string: { type: "string", description: "The replacement string" },
+    },
+    required: ["path", "old_string", "new_string"],
+  },
+  handler: async ({ path, old_string, new_string }) => {
+    const resolved = resolve(path);
+    if (!existsSync(resolved)) {
+      return { error: `File not found: ${resolved}` };
+    }
+    const content = readFileSync(resolved, "utf-8");
+    if (!content.includes(old_string)) {
+      return { error: "old_string not found in file. Make sure it matches exactly, including whitespace." };
+    }
+    const count = content.split(old_string).length - 1;
+    const newContent = content.replace(old_string, new_string);
+    writeFileSync(resolved, newContent, "utf-8");
+    return { path: resolved, replacements: 1, totalOccurrences: count };
+  },
+};

package/src/lib/tools/index.js

@@ -0,0 +1,32 @@
+import { readFile, writeFile, editFile } from "./file-tools.js";
+import { runCommand } from "./command-tools.js";
+import { searchFiles, searchContent, listDirectory } from "./search-tools.js";
+
+const tools = [readFile, writeFile, editFile, runCommand, searchFiles, searchContent, listDirectory];
+
+const toolMap = new Map(tools.map((t) => [t.name, t]));
+
+export function getToolDefinitions() {
+  return tools.map(({ name, description, parameters }) => ({ name, description, parameters }));
+}
+
+export function getTool(name) {
+  return toolMap.get(name);
+}
+
+export async function executeTool(name, input) {
+  const tool = toolMap.get(name);
+  if (!tool) {
+    return { error: `Unknown tool: ${name}` };
+  }
+  try {
+    return await tool.handler(input);
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+export function requiresConfirmation(name) {
+  const tool = toolMap.get(name);
+  return tool?.requiresConfirmation === true;
+}

package/src/lib/tools/search-tools.js

@@ -0,0 +1,95 @@
+import { readdirSync, statSync, existsSync } from "fs";
+import { resolve, join, relative } from "path";
+import { execSync } from "child_process";
+
+export const searchFiles = {
+  name: "search_files",
+  description: "Search for files matching a glob/name pattern. Returns matching file paths.",
+  parameters: {
+    type: "object",
+    properties: {
+      pattern: { type: "string", description: "File name pattern to search for (e.g., '*.js', 'config*', 'test')" },
+      path: { type: "string", description: "Directory to search in (defaults to current directory)" },
+    },
+    required: ["pattern"],
+  },
+  handler: async ({ pattern, path }) => {
+    const dir = resolve(path || ".");
+    try {
+      const result = execSync(`find ${JSON.stringify(dir)} -name ${JSON.stringify(pattern)} -not -path '*/node_modules/*' -not -path '*/.git/*' 2>/dev/null | head -50`, {
+        encoding: "utf-8",
+        timeout: 10_000,
+      });
+      const files = result.trim().split("\n").filter(Boolean);
+      return { pattern, searchPath: dir, matches: files, count: files.length };
+    } catch {
+      return { pattern, searchPath: dir, matches: [], count: 0 };
+    }
+  },
+};
+
+export const searchContent = {
+  name: "search_content",
+  description: "Search for a text pattern inside files (like grep). Returns matching lines with file paths and line numbers.",
+  parameters: {
+    type: "object",
+    properties: {
+      pattern: { type: "string", description: "Text or regex pattern to search for" },
+      path: { type: "string", description: "Directory to search in (defaults to current directory)" },
+      include: { type: "string", description: "File glob to filter (e.g., '*.js')" },
+    },
+    required: ["pattern"],
+  },
+  handler: async ({ pattern, path, include }) => {
+    const dir = resolve(path || ".");
+    try {
+      let cmd = `grep -rn --include='${include || "*"}' ${JSON.stringify(pattern)} ${JSON.stringify(dir)} 2>/dev/null | head -50`;
+      const result = execSync(cmd, { encoding: "utf-8", timeout: 10_000 });
+      const lines = result.trim().split("\n").filter(Boolean);
+      const matches = lines.map((line) => {
+        const match = line.match(/^(.+?):(\d+):(.*)$/);
+        if (match) return { file: match[1], line: parseInt(match[2]), content: match[3].trim() };
+        return { raw: line };
+      });
+      return { pattern, searchPath: dir, matches, count: matches.length };
+    } catch {
+      return { pattern, searchPath: dir, matches: [], count: 0 };
+    }
+  },
+};
+
+export const listDirectory = {
+  name: "list_directory",
+  description: "List files and directories at the given path. Shows names, types, and sizes.",
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Directory path to list (defaults to current directory)" },
+    },
+    required: [],
+  },
+  handler: async ({ path }) => {
+    const dir = resolve(path || ".");
+    if (!existsSync(dir)) {
+      return { error: `Directory not found: ${dir}` };
+    }
+    try {
+      const entries = readdirSync(dir).map((name) => {
+        try {
+          const fullPath = join(dir, name);
+          const stat = statSync(fullPath);
+          return {
+            name,
+            type: stat.isDirectory() ? "directory" : "file",
+            size: stat.isDirectory() ? undefined : stat.size,
+          };
+        } catch {
+          return { name, type: "unknown" };
+        }
+      });
+      return { path: dir, entries, count: entries.length };
+    } catch (err) {
+      return { error: err.message };
+    }
+  },
+};