@cdoing/core 0.1.0

package/src/tools/codebase-search.ts

@@ -0,0 +1,117 @@
+/**
+ * Codebase Search Tool — semantic + full-text search across the indexed codebase.
+ *
+ * Uses the indexing system (SQLite FTS5 + optional embeddings) for fast,
+ * ranked code retrieval. Falls back to runtime grep if index not available.
+ */
+
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import { CodebaseIndexer } from "../indexing";
+
+export class CodebaseSearchTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "codebase_search",
+    description:
+      `Search the entire codebase using natural language or keywords. Uses indexed full-text search (BM25) and optional semantic search (embeddings) for fast, ranked results.
+
+The codebase is automatically indexed on first use. Results include file paths, line numbers, and matching code snippets ranked by relevance.
+
+Use this for:
+- Finding where a concept is implemented ("authentication middleware")
+- Locating function/class definitions ("UserService class")
+- Understanding how something works ("how errors are handled")
+- Finding usage patterns ("all places that call sendEmail")`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Natural language query or keywords to search for",
+        },
+        directory: {
+          type: "string",
+          description: "Optional: limit search to a subdirectory (e.g. 'src/api')",
+        },
+        limit: {
+          type: "number",
+          description: "Max results to return. Default: 20.",
+        },
+      },
+      required: ["query"],
+    },
+    requiresPermission: false,
+  };
+
+  private indexer: CodebaseIndexer | null = null;
+  private workingDir: string;
+  private indexPromise: Promise<void> | null = null;
+
+  constructor(workingDir: string) {
+    this.workingDir = workingDir;
+  }
+
+  async execute(input: Record<string, unknown>): Promise<ToolResult> {
+    const query = input.query as string;
+    const directory = input.directory as string | undefined;
+    const limit = (input.limit as number) || 20;
+
+    if (!query.trim()) {
+      return { success: false, output: "", error: "Query cannot be empty" };
+    }
+
+    // Ensure index exists (lazy initialization)
+    try {
+      await this.ensureIndex();
+    } catch (err) {
+      return { success: false, output: "", error: `Indexing failed: ${(err as Error).message}` };
+    }
+
+    if (!this.indexer) {
+      return { success: false, output: "", error: "Indexer not available" };
+    }
+
+    // Search
+    const results = await this.indexer.search(query, limit, directory);
+
+    if (results.length === 0) {
+      return { success: true, output: `No results found for: "${query}"` };
+    }
+
+    // Format results
+    const formatted = results.map((r, i) => {
+      const header = `### ${i + 1}. ${r.path}:${r.startLine}-${r.endLine} (${r.source}, score: ${r.score.toFixed(3)})`;
+      const content = r.content.length > 500
+        ? r.content.substring(0, 500) + "\n... [truncated]"
+        : r.content;
+      return `${header}\n\`\`\`\n${content}\n\`\`\``;
+    });
+
+    const stats = this.indexer.getStats();
+    const header = `Found ${results.length} results for "${query}" (searched ${stats.totalChunks} chunks across ${stats.totalFiles} files)`;
+
+    return { success: true, output: `${header}\n\n${formatted.join("\n\n")}` };
+  }
+
+  private async ensureIndex(): Promise<void> {
+    if (this.indexer) return;
+
+    // Prevent concurrent indexing
+    if (this.indexPromise) {
+      await this.indexPromise;
+      return;
+    }
+
+    this.indexPromise = (async () => {
+      this.indexer = new CodebaseIndexer(this.workingDir);
+      const stats = this.indexer.getStats();
+
+      // If index is empty or stale (>1 hour), re-index
+      const oneHour = 60 * 60 * 1000;
+      if (stats.totalFiles === 0 || Date.now() - stats.lastIndexed > oneHour) {
+        await this.indexer.index();
+      }
+    })();
+
+    await this.indexPromise;
+  }
+}

package/src/tools/file-delete.ts

@@ -0,0 +1,155 @@
+/**
+ * File Delete Tool — permission-controlled file/directory deletion.
+ *
+ * Unlike raw `rm` via shell_exec, this tool:
+ *   - Goes through the permission system (Delete category — can be allow/deny/ask via settings)
+ *   - Checks sandbox write rules before deletion
+ *   - Reports what will be deleted (file count for directories)
+ *   - Requires explicit recursive flag for directories
+ *   - Requires force flag for large directories (>50 items)
+ *
+ * Users can control deletion via settings rules:
+ *   - Delete         → allow/deny all file deletions
+ *   - Delete(path)   → allow/deny deletion of specific paths
+ *   - Delete(*.log)  → allow/deny deletion by pattern
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import { safePath } from "../utils/path-safety";
+import type { SandboxManager } from "../sandbox";
+
+const MAX_DIR_FILES = 50;
+
+export class FileDeleteTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "file_delete",
+    description:
+      `Delete a file or directory. You can also use shell_exec with rm/del for simple deletions if preferred.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        file_path: {
+          type: "string",
+          description: "Path to the file or directory to delete",
+        },
+        recursive: {
+          type: "boolean",
+          description: "Required for directory deletion. Deletes all contents. Default: false.",
+        },
+        force: {
+          type: "boolean",
+          description: "Required for directories with more than 50 items. Default: false.",
+        },
+      },
+      required: ["file_path"],
+    },
+    requiresPermission: true,
+    permissionMessage: (input) => {
+      const recursive = input.recursive ? " (recursive)" : "";
+      return `Delete${recursive}: ${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 recursive = (input.recursive as boolean) || false;
+    const force = (input.force as boolean) || false;
+
+    // Sandbox write check (deletion requires write access to parent)
+    if (this.sandboxManager) {
+      const check = this.sandboxManager.checkFileWrite(filePath);
+      if (!check.allowed) {
+        return { success: false, output: "", error: check.reason || "Sandbox: delete access denied" };
+      }
+    }
+
+    // Existence check
+    if (!fs.existsSync(filePath)) {
+      return { success: false, output: "", error: `Path not found: ${filePath}` };
+    }
+
+    const stat = fs.statSync(filePath);
+
+    // ── File deletion ─────────────────────────────────────────────────────────
+    if (stat.isFile() || stat.isSymbolicLink()) {
+      try {
+        fs.unlinkSync(filePath);
+        return { success: true, output: `Deleted file: ${filePath}` };
+      } catch (err) {
+        return { success: false, output: "", error: `Failed to delete: ${(err as Error).message}` };
+      }
+    }
+
+    // ── Directory deletion ────────────────────────────────────────────────────
+    if (!stat.isDirectory()) {
+      return { success: false, output: "", error: `Unsupported file type at: ${filePath}` };
+    }
+
+    if (!recursive) {
+      // Show what's inside so the user can make an informed decision
+      const entries = fs.readdirSync(filePath);
+      const preview = entries.slice(0, 10).join(", ");
+      const more = entries.length > 10 ? ` ... and ${entries.length - 10} more` : "";
+      return {
+        success: false,
+        output: "",
+        error: `"${filePath}" is a directory with ${entries.length} items (${preview}${more}). Set recursive=true to delete it and all its contents.`,
+      };
+    }
+
+    // Count files before deleting
+    const fileCount = this.countItems(filePath);
+
+    if (fileCount > MAX_DIR_FILES && !force) {
+      return {
+        success: false,
+        output: "",
+        error: `Directory contains ${fileCount} items. Set force=true to confirm bulk deletion of "${filePath}".`,
+      };
+    }
+
+    try {
+      fs.rmSync(filePath, { recursive: true, force: true });
+      return {
+        success: true,
+        output: `Deleted directory: ${filePath} (${fileCount} items removed)`,
+      };
+    } catch (err) {
+      return { success: false, output: "", error: `Failed to delete directory: ${(err as Error).message}` };
+    }
+  }
+
+  private countItems(dirPath: string, limit = 10000): number {
+    let count = 0;
+    try {
+      const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+      for (const entry of entries) {
+        count++;
+        if (count >= limit) return count;
+        if (entry.isDirectory()) {
+          count += this.countItems(path.join(dirPath, entry.name), limit - count);
+          if (count >= limit) return count;
+        }
+      }
+    } catch {
+      // Permission denied — count what we can
+    }
+    return count;
+  }
+}

package/src/tools/file-edit.ts

@@ -0,0 +1,115 @@
+import * as fs from "fs";
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import { safePath } from "../utils/path-safety";
+import { executeFindAndReplace, isUnifiedDiff, applyUnifiedDiff } from "../utils/search-match";
+import { hasPlaceholders, expandPlaceholders } from "../utils/lazy-apply";
+import type { SandboxManager } from "../sandbox";
+
+export class FileEditTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "file_edit",
+    description:
+      `Performs string replacement in a file using multi-strategy matching (exact → trimmed → case-insensitive → whitespace-ignored). Also supports unified diff patches. Requires user permission. Access controlled by sandbox/permission rules.
+
+IMPORTANT:
+- Always read the file first before editing to see its current contents.
+- old_string should match the file content — the system tolerates minor whitespace/case differences.
+- old_string and new_string MUST be different.
+- When not using replace_all, old_string must be unique in the file. Add more surrounding context if ambiguous.
+- Use replace_all for renaming variables or strings across the file.
+- You can pass a unified diff (with @@ hunk headers) as old_string and leave new_string empty to apply the diff patch directly.
+- This tool CANNOT be called in parallel with itself on the SAME file.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        file_path: { type: "string", description: "Path to the file to edit" },
+        old_string: { type: "string", description: "The text to replace — must match file content (exact match preferred, but tolerates whitespace/case differences)" },
+        new_string: { type: "string", description: "The replacement text (MUST be different from old_string)" },
+        replace_all: { type: "boolean", description: "Replace all occurrences (default: false)" },
+      },
+      required: ["file_path", "old_string", "new_string"],
+    },
+    requiresPermission: true,
+    permissionMessage: (input) => `Edit 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" };
+      }
+    }
+
+    const oldStr = input.old_string as string;
+    const newStr = input.new_string as string;
+    const replaceAll = (input.replace_all as boolean) || false;
+
+    if (!fs.existsSync(filePath))
+      return { success: false, output: "", error: `File not found: ${filePath}` };
+
+    const content = fs.readFileSync(filePath, "utf-8");
+
+    try {
+      // Unified diff mode: detect @@ hunk headers in old_string
+      if (isUnifiedDiff(oldStr)) {
+        const result = applyUnifiedDiff(content, oldStr);
+        fs.writeFileSync(filePath, result, "utf-8");
+        return { success: true, output: `Applied unified diff patch to ${filePath}\n\n${oldStr}` };
+      }
+
+      // Lazy apply: expand placeholder markers in new_string before replacing
+      let expandedNewStr = newStr;
+      let lazyNote = "";
+      if (hasPlaceholders(newStr)) {
+        const { content: expanded, placeholdersExpanded, strategy: lazyStrategy } = expandPlaceholders(content, newStr);
+        if (placeholdersExpanded > 0) {
+          expandedNewStr = expanded;
+          lazyNote = ` (lazy apply: ${placeholdersExpanded} placeholder(s) expanded via ${lazyStrategy})`;
+        }
+      }
+
+      const { result, count, strategy } = executeFindAndReplace(content, oldStr, expandedNewStr, replaceAll);
+      fs.writeFileSync(filePath, result, "utf-8");
+
+      const diff = generateDiff(filePath, oldStr, expandedNewStr, count);
+      const strategyNote = strategy !== "exact" ? ` (matched via ${strategy} strategy)` : "";
+      return { success: true, output: `Edited ${filePath}: replaced ${count} occurrence(s)${strategyNote}${lazyNote}\n\n${diff}` };
+    } catch (err) {
+      return { success: false, output: "", error: (err as Error).message };
+    }
+  }
+}
+
+/** Generate a unified-style diff showing what changed */
+function generateDiff(filePath: string, oldStr: string, newStr: string, count: number): string {
+  const oldLines = oldStr.split("\n");
+  const newLines = newStr.split("\n");
+
+  const parts: string[] = [
+    `--- a/${filePath}`,
+    `+++ b/${filePath}`,
+    `@@ -1,${oldLines.length} +1,${newLines.length} @@ (${count} replacement${count > 1 ? "s" : ""})`,
+  ];
+
+  for (const line of oldLines) parts.push(`- ${line}`);
+  for (const line of newLines) parts.push(`+ ${line}`);
+
+  return parts.join("\n");
+}

package/src/tools/file-read.ts

@@ -0,0 +1,195 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { BaseTool, ToolDefinition, ToolResult } from "./types";
+import { safePath } from "../utils/path-safety";
+import type { SandboxManager } from "../sandbox";
+
+/** Binary/image extensions we can describe but not read as text */
+const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".svg", ".ico"]);
+const PDF_EXTENSION = ".pdf";
+
+export class FileReadTool implements BaseTool {
+  definition: ToolDefinition = {
+    name: "file_read",
+    description:
+      "Read the contents of a file. Returns content with line numbers. Supports text files, images (returns metadata), and PDFs (extracts text). Always read before editing. Access is governed by the permission system — certain paths may be denied by sandbox or permission rules.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file_path: {
+          type: "string",
+          description: "Path to the file to read",
+        },
+        offset: {
+          type: "number",
+          description: "Line number to start from (1-based). Optional.",
+        },
+        limit: {
+          type: "number",
+          description: "Max lines to read. Default: 2000.",
+        },
+      },
+      required: ["file_path"],
+    },
+    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> {
+    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 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}` };
+    if (fs.statSync(filePath).isDirectory())
+      return { success: false, output: "", error: `Path is a directory: ${filePath}` };
+
+    const ext = path.extname(filePath).toLowerCase();
+
+    // Handle image files
+    if (IMAGE_EXTENSIONS.has(ext)) {
+      return this.readImage(filePath, ext);
+    }
+
+    // Handle PDF files
+    if (ext === PDF_EXTENSION) {
+      return this.readPdf(filePath);
+    }
+
+    // Regular text file
+    const offset = (input.offset as number) || 1;
+    const limit = (input.limit as number) || 2000;
+
+    try {
+      const content = fs.readFileSync(filePath, "utf-8");
+      const lines = content.split("\n");
+      const selected = lines.slice(offset - 1, offset - 1 + limit);
+      const numbered = selected
+        .map((line, i) => `${String(offset + i).padStart(5)}  ${line}`)
+        .join("\n");
+
+      const totalLines = lines.length;
+      const showing = selected.length;
+      const info = totalLines > showing
+        ? `\n\n[Showing lines ${offset}-${offset + showing - 1} of ${totalLines}]`
+        : "";
+
+      return { success: true, output: (numbered || "(empty file)") + info };
+    } catch {
+      // Might be a binary file
+      const stat = fs.statSync(filePath);
+      return {
+        success: true,
+        output: `Binary file: ${filePath} (${formatBytes(stat.size)})`,
+      };
+    }
+  }
+
+  private readImage(filePath: string, ext: string): ToolResult {
+    const stat = fs.statSync(filePath);
+    const info = [
+      `Image file: ${filePath}`,
+      `Format: ${ext.substring(1).toUpperCase()}`,
+      `Size: ${formatBytes(stat.size)}`,
+    ];
+
+    // For SVG, we can actually read the content
+    if (ext === ".svg") {
+      try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        info.push(`\nSVG Content:\n${content.substring(0, 5000)}`);
+        if (content.length > 5000) info.push(`\n... [truncated at 5000 chars]`);
+      } catch {
+        // skip
+      }
+    }
+
+    return { success: true, output: info.join("\n") };
+  }
+
+  private readPdf(filePath: string): ToolResult {
+    const stat = fs.statSync(filePath);
+
+    // Basic PDF text extraction — reads raw text strings from PDF
+    try {
+      const buffer = fs.readFileSync(filePath);
+      const text = extractPdfText(buffer);
+
+      if (text.trim()) {
+        const truncated = text.length > 10000
+          ? text.substring(0, 10000) + "\n\n... [truncated at 10000 chars]"
+          : text;
+        return {
+          success: true,
+          output: `PDF: ${filePath} (${formatBytes(stat.size)})\n\n${truncated}`,
+        };
+      }
+
+      return {
+        success: true,
+        output: `PDF: ${filePath} (${formatBytes(stat.size)})\n(Could not extract text — may be image-based or encrypted)`,
+      };
+    } catch {
+      return {
+        success: true,
+        output: `PDF: ${filePath} (${formatBytes(stat.size)})\n(Unable to read PDF content)`,
+      };
+    }
+  }
+}
+
+/** Very basic PDF text extraction — finds text between parentheses in PDF stream */
+function extractPdfText(buffer: Buffer): string {
+  const content = buffer.toString("latin1");
+  const textParts: string[] = [];
+
+  // Extract text from Tj and TJ operators (basic PDF text rendering)
+  const tjRegex = /\(([^)]*)\)\s*Tj/g;
+  let match;
+  while ((match = tjRegex.exec(content)) !== null) {
+    const decoded = match[1]
+      .replace(/\\n/g, "\n")
+      .replace(/\\r/g, "\r")
+      .replace(/\\t/g, "\t")
+      .replace(/\\\\/g, "\\")
+      .replace(/\\([()])/g, "$1");
+    textParts.push(decoded);
+  }
+
+  // Also try TJ arrays
+  const tjArrayRegex = /\[((?:\([^)]*\)|[^\]])*)\]\s*TJ/gi;
+  while ((match = tjArrayRegex.exec(content)) !== null) {
+    const innerRegex = /\(([^)]*)\)/g;
+    let inner;
+    while ((inner = innerRegex.exec(match[1])) !== null) {
+      textParts.push(inner[1]);
+    }
+  }
+
+  return textParts.join(" ").replace(/\s+/g, " ").trim();
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}