@cdoing/core 0.1.0

package/src/tools/file-run.ts

@@ -0,0 +1,158 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { exec } from "child_process";
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import { safePath } from "../utils/path-safety";
+import type { SandboxManager } from "../sandbox";
+
+const IS_WINDOWS = os.platform() === "win32";
+const SHELL = IS_WINDOWS ? "powershell.exe" : process.env.SHELL || "/bin/sh";
+
+/** Map file extensions to the command that runs them */
+const RUNNERS: Record<string, string> = {
+  ".js": "node", ".mjs": "node", ".cjs": "node",
+  ".ts": "npx ts-node", ".tsx": "npx ts-node",
+  ".py": IS_WINDOWS ? "python" : "python3", ".rb": "ruby",
+  ".sh": "bash", ".bash": "bash", ".zsh": "zsh",
+  ".bat": "cmd /c", ".cmd": "cmd /c", ".ps1": "powershell -File",
+  ".go": "go run", ".swift": "swift", ".lua": "lua",
+  ".php": "php", ".pl": "perl",
+};
+
+export class FileRunTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "file_run",
+    description:
+      "Run a file. Auto-detects language from extension (node for .js, python3 for .py, etc). Use after writing a program to test it. Requires user permission. Subject to sandbox restrictions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file_path: { type: "string", description: "Path to the file to run" },
+        args: { type: "string", description: "Command-line arguments (optional)" },
+        timeout: { type: "number", description: "Timeout in ms. Default: 30000" },
+        env_vars: {
+          type: "object",
+          description: "Environment variables to set (e.g., {\"PORT\": \"3001\", \"NODE_ENV\": \"test\"})",
+          additionalProperties: { type: "string" },
+        },
+        debug: {
+          type: "boolean",
+          description: "Enable debug/verbose mode. Sets DEBUG=*, NODE_DEBUG=*, RUST_BACKTRACE=1, PYTHONTRACEBACK=1. Default: false",
+        },
+      },
+      required: ["file_path"],
+    },
+    requiresPermission: true,
+    permissionMessage: (input) => `Run file: ${input.file_path}`,
+  };
+
+  private workingDir: string;
+  private sandboxManager?: SandboxManager;
+
+  constructor(workingDir: string, sandboxManager?: SandboxManager) {
+    this.workingDir = workingDir;
+    this.sandboxManager = sandboxManager;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    let filePath: string;
+    try {
+      filePath = safePath(input.file_path as string, this.workingDir);
+    } catch (err) {
+      return { success: false, output: "", error: (err as Error).message };
+    }
+
+    const args = (input.args as string) || "";
+    const timeout = (input.timeout as number) || 30000;
+
+    // Sandbox read check
+    if (this.sandboxManager) {
+      const check = this.sandboxManager.checkFileRead(filePath);
+      if (!check.allowed) {
+        return { success: false, output: "", error: check.reason || "Sandbox: read access denied" };
+      }
+    }
+
+    if (!fs.existsSync(filePath))
+      return { success: false, output: "", error: `File not found: ${filePath}` };
+
+    const ext = path.extname(filePath).toLowerCase();
+    const runner = RUNNERS[ext];
+    if (!runner)
+      return { success: false, output: "", error: `Can't run ${ext} files. Supported: ${Object.keys(RUNNERS).join(", ")}` };
+
+    const command = `${runner} "${filePath}"${args ? ` ${args}` : ""}`;
+
+    // Build environment
+    const env = this.sandboxManager ? this.sandboxManager.getShellEnv() : { ...process.env };
+
+    // Merge user-provided env vars
+    const envVars = input.env_vars as Record<string, string> | undefined;
+    if (envVars && typeof envVars === "object") {
+      for (const [key, val] of Object.entries(envVars)) {
+        env[key] = String(val);
+      }
+    }
+
+    // Debug mode — set common debug env vars
+    if (input.debug) {
+      env.DEBUG = env.DEBUG || "*";
+      env.NODE_DEBUG = env.NODE_DEBUG || "*";
+      env.RUST_BACKTRACE = env.RUST_BACKTRACE || "1";
+      env.PYTHONTRACEBACK = env.PYTHONTRACEBACK || "1";
+      env.PYTHONFAULTHANDLER = env.PYTHONFAULTHANDLER || "1";
+    }
+
+    return new Promise((resolve) => {
+      const child = exec(command, { cwd: this.workingDir, timeout, maxBuffer: 10 * 1024 * 1024, env, shell: SHELL },
+        (error, stdout, stderr) => {
+          const outputParts: string[] = [];
+          if (stdout) outputParts.push(stdout.trimEnd());
+          if (stderr) {
+            // Filter out common non-error warnings
+            const filteredStderr = stderr.split("\n")
+              .filter((l) => !l.includes("DeprecationWarning") && !l.includes("ExperimentalWarning"))
+              .join("\n").trim();
+            if (filteredStderr) outputParts.push(`STDERR:\n${filteredStderr}`);
+          }
+          const output = outputParts.join("\n\n") || "(no output)";
+
+          if (error?.killed) {
+            // Timed out — but if we got output, it's likely a server/long-running process
+            // Treat as success with note, not as an error
+            if (output && output !== "(no output)") {
+              resolve({
+                success: true,
+                output: output + `\n\n[Process timed out after ${timeout / 1000}s — this is normal for servers and long-running processes. The output above was captured before timeout. Use shell_exec instead if you need to start a server in the background.]`,
+              });
+            } else {
+              resolve({ success: false, output, error: `Timed out after ${timeout}ms with no output` });
+            }
+            return;
+          }
+
+          if (error) {
+            resolve({ success: false, output, error: `Exit code: ${error.code}` });
+          } else {
+            resolve({ success: true, output });
+          }
+        });
+
+      // For server-like processes: if we get output early, don't wait for timeout
+      // Kill after 5s if stdout has content (server started successfully)
+      let earlyOutput = "";
+      child.stdout?.on("data", (chunk: string) => {
+        earlyOutput += chunk;
+        // If output contains typical server-started messages, kill early
+        if (/listening|started|running|ready|server/i.test(earlyOutput)) {
+          setTimeout(() => {
+            if (!child.killed) {
+              child.kill("SIGTERM");
+            }
+          }, 2000); // Give 2s for any additional startup output
+        }
+      });
+    });
+  }
+}

package/src/tools/file-write.ts

@@ -0,0 +1,104 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import { safePath } from "../utils/path-safety";
+import { hasPlaceholders, expandPlaceholders } from "../utils/lazy-apply";
+import type { SandboxManager } from "../sandbox";
+
+export class FileWriteTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "file_write",
+    description:
+      `Create a new file or completely overwrite an existing file. Creates parent directories if needed. Requires user permission.
+
+Use this tool ONLY for:
+- Creating new files that don't exist yet
+- Complete file rewrites where the entire content changes
+
+Do NOT use this for partial edits — use file_edit or multi_edit instead, which preserve unchanged code and provide diffs.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        file_path: {
+          type: "string",
+          description: "Path to the file to write",
+        },
+        content: {
+          type: "string",
+          description: "Content to write to the file",
+        },
+      },
+      required: ["file_path", "content"],
+    },
+    requiresPermission: true,
+    permissionMessage: (input) => `Write to file: ${input.file_path}`,
+  };
+
+  private workingDir: string;
+  private sandboxManager?: SandboxManager;
+
+  constructor(workingDir: string, sandboxManager?: SandboxManager) {
+    this.workingDir = workingDir;
+    this.sandboxManager = sandboxManager;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    let filePath: string;
+    try {
+      filePath = safePath(input.file_path as string, this.workingDir);
+    } catch (err) {
+      return { success: false, output: "", error: (err as Error).message };
+    }
+
+    // Sandbox write check
+    if (this.sandboxManager) {
+      const check = this.sandboxManager.checkFileWrite(filePath);
+      if (!check.allowed) {
+        return { success: false, output: "", error: check.reason || "Sandbox: write access denied" };
+      }
+    }
+
+    let content = input.content as string;
+
+    try {
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+      const existed = fs.existsSync(filePath);
+      const oldContent = existed ? fs.readFileSync(filePath, "utf-8") : "";
+
+      // Lazy apply: if content has placeholders and file exists, expand them
+      if (existed && hasPlaceholders(content)) {
+        const { content: expanded, placeholdersExpanded } = expandPlaceholders(oldContent, content);
+        if (placeholdersExpanded > 0) {
+          content = expanded;
+        }
+      }
+
+      fs.writeFileSync(filePath, content, "utf-8");
+      const lines = content.split("\n").length;
+
+      // Generate diff for the extension to render
+      let diff = "";
+      if (existed && oldContent !== content) {
+        const oldLines = oldContent.split("\n");
+        const newLines = content.split("\n");
+        diff = `--- a/${input.file_path}\n+++ b/${input.file_path}\n@@ -1,${oldLines.length} +1,${newLines.length} @@\n`;
+        for (const line of oldLines) diff += `- ${line}\n`;
+        for (const line of newLines) diff += `+ ${line}\n`;
+      } else if (!existed) {
+        const newLines = content.split("\n");
+        diff = `--- /dev/null\n+++ b/${input.file_path}\n@@ -0,0 +1,${newLines.length} @@\n`;
+        for (const line of newLines) diff += `+ ${line}\n`;
+      }
+
+      const summary = `${existed ? "Updated" : "Created"} file: ${filePath} (${lines} lines)`;
+      return {
+        success: true,
+        output: diff ? `${summary}\n\n${diff}` : summary,
+      };
+    } catch (err) {
+      return { success: false, output: "", error: `Failed to write: ${err}` };
+    }
+  }
+}

package/src/tools/glob-search.ts

@@ -0,0 +1,80 @@
+import { glob } from "glob";
+import * as path from "path";
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import { loadIgnorePatterns } from "../utils/gitignore";
+
+export class GlobSearchTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "glob_search",
+    description:
+      "Search for files matching a glob pattern. Returns matching file paths sorted by modification time. Use patterns like '**/*.ts', 'src/**/*.js', '*.json'. Respects .gitignore. The search always starts from the project working directory — do NOT pass directory unless you specifically need a subdirectory (e.g. 'src/components'). Never pass '/' or an absolute path.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pattern: {
+          type: "string",
+          description: "Glob pattern to match files (e.g., '**/*.ts', 'src/**/*.js')",
+        },
+        directory: {
+          type: "string",
+          description: "Optional subdirectory to narrow the search (e.g. 'src/components'). Omit to search the entire project. Never use '/' or absolute paths.",
+        },
+      },
+      required: ["pattern"],
+    },
+    requiresPermission: false,
+  };
+
+  private workingDir: string;
+
+  constructor(workingDir: string) {
+    this.workingDir = workingDir;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    const pattern = input.pattern as string;
+    const rawDir = (input.directory as string | undefined) || "";
+    // Clamp to workingDir: reject "/" or paths outside the project
+    let searchDir: string;
+    if (!rawDir || rawDir === "/") {
+      searchDir = this.workingDir;
+    } else {
+      const resolved = path.isAbsolute(rawDir)
+        ? rawDir
+        : path.resolve(this.workingDir, rawDir);
+      // Don't allow searching outside the working directory
+      searchDir = resolved.startsWith(this.workingDir) ? resolved : this.workingDir;
+    }
+
+    try {
+      const ignorePatterns = loadIgnorePatterns(this.workingDir);
+      const files = await glob(pattern, {
+        cwd: searchDir,
+        nodir: true,
+        ignore: ignorePatterns,
+      });
+
+      if (files.length === 0) {
+        return { success: true, output: "No files found matching the pattern." };
+      }
+
+      const result = files
+        .slice(0, 100)
+        .map((f) => path.join(searchDir, f))
+        .join("\n");
+
+      const summary =
+        files.length > 100
+          ? `\n\n... and ${files.length - 100} more files (showing first 100)`
+          : "";
+
+      return {
+        success: true,
+        output: `Found ${files.length} file(s):\n${result}${summary}`,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { success: false, output: "", error: `Glob search failed: ${message}` };
+    }
+  }
+}

package/src/tools/grep-search.ts

@@ -0,0 +1,120 @@
+import * as fs from "fs";
+import * as path from "path";
+import { glob } from "glob";
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import { loadIgnorePatterns } from "../utils/gitignore";
+
+interface GrepMatch {
+  file: string;
+  line: number;
+  content: string;
+}
+
+export class GrepSearchTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "grep_search",
+    description:
+      "Search file contents using a regex pattern. Returns matching lines with file paths and line numbers. Use this to find code patterns, function definitions, variable usages, etc. Respects .gitignore.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pattern: {
+          type: "string",
+          description: "Regex pattern to search for in file contents",
+        },
+        directory: {
+          type: "string",
+          description: "Directory to search in. Defaults to working directory.",
+        },
+        file_pattern: {
+          type: "string",
+          description: "Glob pattern to filter files (e.g., '*.ts', '*.py'). Optional.",
+        },
+        case_insensitive: {
+          type: "boolean",
+          description: "Case insensitive search. Default: false.",
+        },
+      },
+      required: ["pattern"],
+    },
+    requiresPermission: false,
+  };
+
+  private workingDir: string;
+
+  constructor(workingDir: string) {
+    this.workingDir = workingDir;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    const pattern = input.pattern as string;
+    const directory = (input.directory as string) || this.workingDir;
+    const filePattern = (input.file_pattern as string) || "**/*";
+    const caseInsensitive = (input.case_insensitive as boolean) || false;
+
+    const searchDir = path.isAbsolute(directory)
+      ? directory
+      : path.resolve(this.workingDir, directory);
+
+    try {
+      const regex = new RegExp(pattern, caseInsensitive ? "gi" : "g");
+      const ignorePatterns = loadIgnorePatterns(this.workingDir);
+      const files = await glob(filePattern, {
+        cwd: searchDir,
+        nodir: true,
+        ignore: ignorePatterns,
+      });
+
+      const matches: GrepMatch[] = [];
+      const maxMatches = 200;
+
+      for (const file of files) {
+        if (matches.length >= maxMatches) break;
+
+        const fullPath = path.join(searchDir, file);
+        try {
+          const stat = fs.statSync(fullPath);
+          if (stat.size > 1024 * 1024) continue; // skip files > 1MB
+
+          const content = fs.readFileSync(fullPath, "utf-8");
+          const lines = content.split("\n");
+
+          for (let i = 0; i < lines.length; i++) {
+            if (matches.length >= maxMatches) break;
+            if (regex.test(lines[i])) {
+              matches.push({
+                file: fullPath,
+                line: i + 1,
+                content: lines[i].trim(),
+              });
+            }
+            regex.lastIndex = 0;
+          }
+        } catch {
+          // skip unreadable files
+        }
+      }
+
+      if (matches.length === 0) {
+        return { success: true, output: "No matches found." };
+      }
+
+      const result = matches
+        .map((m) => `${m.file}:${m.line}: ${m.content}`)
+        .join("\n");
+
+      const summary =
+        matches.length >= maxMatches
+          ? `\n\n... results truncated at ${maxMatches} matches`
+          : "";
+
+      return {
+        success: true,
+        output: `Found ${matches.length} match(es):\n${result}${summary}`,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { success: false, output: "", error: `Grep search failed: ${message}` };
+    }
+  }
+}

package/src/tools/list-dir.ts

@@ -0,0 +1,172 @@
+/**
+ * List Directory Tool — list directory contents with optional recursion.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import { safePath } from "../utils/path-safety";
+import { loadIgnorePatterns } from "../utils/gitignore";
+import type { SandboxManager } from "../sandbox";
+
+const DEFAULT_MAX_ENTRIES = 500;
+
+export class ListDirTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "list_dir",
+    description:
+      `List directory contents. Shows files and subdirectories with type indicators. Respects .gitignore patterns.
+
+Use this to understand directory structure before reading or editing files. Supports optional recursive listing with depth control.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        directory: {
+          type: "string",
+          description: "Directory path to list. Defaults to working directory.",
+        },
+        recursive: {
+          type: "boolean",
+          description: "List recursively. Default: false.",
+        },
+        max_depth: {
+          type: "number",
+          description: "Maximum depth for recursive listing. Default: 3.",
+        },
+      },
+      required: [],
+    },
+    requiresPermission: false,
+  };
+
+  private workingDir: string;
+  private sandboxManager?: SandboxManager;
+
+  constructor(workingDir: string, sandboxManager?: SandboxManager) {
+    this.workingDir = workingDir;
+    this.sandboxManager = sandboxManager;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    const dirInput = (input.directory as string) || ".";
+    const recursive = (input.recursive as boolean) || false;
+    const maxDepth = (input.max_depth as number) || 3;
+
+    let dirPath: string;
+    try {
+      dirPath = safePath(dirInput, this.workingDir);
+    } catch (err) {
+      return { success: false, output: "", error: (err as Error).message };
+    }
+
+    // Sandbox read check
+    if (this.sandboxManager) {
+      const check = this.sandboxManager.checkFileRead(dirPath);
+      if (!check.allowed) {
+        return { success: false, output: "", error: check.reason || "Sandbox: read access denied" };
+      }
+    }
+
+    if (!fs.existsSync(dirPath)) {
+      return { success: false, output: "", error: `Directory not found: ${dirPath}` };
+    }
+
+    if (!fs.statSync(dirPath).isDirectory()) {
+      return { success: false, output: "", error: `Not a directory: ${dirPath}` };
+    }
+
+    const ignorePatterns = loadIgnorePatterns(this.workingDir);
+    const entries: string[] = [];
+
+    try {
+      this.listEntries(dirPath, "", recursive ? maxDepth : 0, 0, entries, ignorePatterns);
+    } catch (err) {
+      return { success: false, output: "", error: `Failed to list: ${(err as Error).message}` };
+    }
+
+    if (entries.length === 0) {
+      return { success: true, output: `${dirPath}: (empty directory)` };
+    }
+
+    const truncated = entries.length > DEFAULT_MAX_ENTRIES;
+    const shown = truncated ? entries.slice(0, DEFAULT_MAX_ENTRIES) : entries;
+    const suffix = truncated ? `\n\n... and ${entries.length - DEFAULT_MAX_ENTRIES} more entries (truncated)` : "";
+
+    return {
+      success: true,
+      output: `${dirPath}:\n${shown.join("\n")}${suffix}`,
+    };
+  }
+
+  private listEntries(
+    basePath: string,
+    prefix: string,
+    maxDepth: number,
+    currentDepth: number,
+    result: string[],
+    ignorePatterns: string[],
+  ): void {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(basePath, { withFileTypes: true });
+    } catch {
+      return; // Permission denied
+    }
+
+    // Sort: directories first, then alphabetical
+    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 entries) {
+      if (result.length >= DEFAULT_MAX_ENTRIES * 2) return;
+
+      const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+      // Skip ignored patterns
+      if (this.shouldIgnore(entry.name, relativePath, ignorePatterns)) continue;
+
+      const indent = "  ".repeat(currentDepth);
+      if (entry.isDirectory()) {
+        result.push(`${indent}${entry.name}/`);
+        if (currentDepth < maxDepth) {
+          this.listEntries(
+            path.join(basePath, entry.name),
+            relativePath,
+            maxDepth,
+            currentDepth + 1,
+            result,
+            ignorePatterns,
+          );
+        }
+      } else {
+        const size = this.getFileSize(path.join(basePath, entry.name));
+        result.push(`${indent}${entry.name}${size ? `  (${size})` : ""}`);
+      }
+    }
+  }
+
+  private shouldIgnore(name: string, relativePath: string, patterns: string[]): boolean {
+    // Always ignore these
+    if (name === ".git" || name === "node_modules" || name === ".DS_Store") return true;
+    // Check gitignore patterns (simple prefix/suffix matching)
+    for (const p of patterns) {
+      if (p === name || relativePath.startsWith(p) || relativePath.endsWith(p)) return true;
+    }
+    return false;
+  }
+
+  private getFileSize(filePath: string): string {
+    try {
+      const stat = fs.statSync(filePath);
+      const bytes = stat.size;
+      if (bytes < 1024) return `${bytes}B`;
+      if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)}KB`;
+      return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    } catch {
+      return "";
+    }
+  }
+}