specvector 0.0.1 → 0.1.2

package/src/agent/tools/grep.ts

@@ -0,0 +1,149 @@
+/**
+ * Grep Search Tool - Search codebase for patterns.
+ * 
+ * Uses execFile with array arguments to prevent command injection.
+ */
+
+import { execFile } from "child_process";
+import { promisify } from "util";
+import type { Tool, ToolResult } from "../types";
+import { ok, err } from "../../types/result";
+
+const execFileAsync = promisify(execFile);
+
+/** Maximum number of results to return */
+const DEFAULT_MAX_RESULTS = 50;
+
+/** Timeout for grep command in ms */
+const GREP_TIMEOUT_MS = 30_000;
+
+/** Configuration for grep tool */
+export interface GrepConfig {
+  /** Working directory for search */
+  workingDir: string;
+  /** Maximum results to return (default: 50) */
+  maxResults?: number;
+  /** Timeout in ms (default: 30s) */
+  timeoutMs?: number;
+}
+
+/**
+ * Create the grep tool.
+ */
+export function createGrepTool(config: GrepConfig): Tool {
+  const maxResults = config.maxResults ?? DEFAULT_MAX_RESULTS;
+  const timeoutMs = config.timeoutMs ?? GREP_TIMEOUT_MS;
+
+  return {
+    name: "grep",
+    description: "Search for a pattern in files. Returns matching lines with file paths and line numbers. Use this to find usages of functions, imports, or specific code patterns.",
+    parameters: {
+      type: "object",
+      properties: {
+        pattern: {
+          type: "string",
+          description: "Search pattern (supports regex)",
+        },
+        include: {
+          type: "string",
+          description: "File glob pattern to include (e.g., '*.ts', '*.py'). Optional.",
+        },
+      },
+      required: ["pattern"],
+    },
+
+    execute: async (args): Promise<ToolResult> => {
+      const pattern = args.pattern;
+      const include = args.include;
+
+      // Validate pattern
+      if (typeof pattern !== "string" || !pattern.trim()) {
+        return err({
+          code: "INVALID_PATTERN",
+          message: "Pattern must be a non-empty string",
+        });
+      }
+
+      try {
+        // Build grep arguments as array (prevents command injection)
+        const grepArgs: string[] = [
+          "-r",        // Recursive
+          "-n",        // Line numbers
+          "-I",        // Ignore binary files
+          "--color=never",
+        ];
+        
+        if (include && typeof include === "string") {
+          // Validate include pattern (only allow safe glob characters)
+          if (!/^[\w.*?\[\]/-]+$/.test(include)) {
+            return err({
+              code: "INVALID_INCLUDE",
+              message: "Include pattern contains invalid characters",
+            });
+          }
+          grepArgs.push(`--include=${include}`);
+        }
+        
+        // Pattern and search path
+        grepArgs.push(pattern, ".");
+
+        const { stdout, stderr } = await execFileAsync("grep", grepArgs, {
+          cwd: config.workingDir,
+          maxBuffer: 1024 * 1024, // 1MB
+          timeout: timeoutMs,
+        });
+
+        if (stderr && !stdout) {
+          return err({
+            code: "GREP_ERROR",
+            message: stderr.trim(),
+          });
+        }
+
+        // Parse and limit results
+        const lines = stdout.trim().split("\n").filter(Boolean);
+        const limitedLines = lines.slice(0, maxResults);
+
+        if (lines.length === 0) {
+          return ok("No matches found.");
+        }
+
+        let result = limitedLines.join("\n");
+        if (lines.length > maxResults) {
+          result += `\n\n... and ${lines.length - maxResults} more matches (limited to ${maxResults})`;
+        }
+
+        return ok(result);
+      } catch (error) {
+        // grep returns exit code 1 when no matches found
+        if (isExecError(error) && error.code === 1 && !error.stderr) {
+          return ok("No matches found.");
+        }
+
+        // Handle timeout
+        if (isExecError(error) && error.killed) {
+          return err({
+            code: "TIMEOUT",
+            message: `Search timed out after ${timeoutMs}ms`,
+          });
+        }
+
+        return err({
+          code: "GREP_ERROR",
+          message: `Search failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        });
+      }
+    },
+  };
+}
+
+/**
+ * Type guard for exec errors.
+ */
+function isExecError(error: unknown): error is { code: number; stderr: string; killed?: boolean } {
+  return (
+    error !== null &&
+    typeof error === "object" &&
+    "code" in error
+  );
+}

package/src/agent/tools/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Agent Tools - Barrel export for all tools.
+ */
+
+export { createReadFileTool, type ReadFileConfig } from "./read-file";
+export { createGrepTool, type GrepConfig } from "./grep";
+export { createListDirTool, type ListDirConfig } from "./list-dir";
+export { createOutlineTool, type OutlineConfig } from "./outline";
+export { createFindSymbolTool, type FindSymbolConfig } from "./find-symbol";

package/src/agent/tools/list-dir.ts

@@ -0,0 +1,191 @@
+/**
+ * List Directory Tool - List files in a directory.
+ * 
+ * Security: Uses path.relative() check for path traversal.
+ */
+
+import { readdir, stat } from "fs/promises";
+import { resolve, isAbsolute, relative } from "path";
+import type { Tool, ToolResult } from "../types";
+import { ok, err } from "../../types/result";
+
+/** Maximum depth for recursive listing */
+const DEFAULT_MAX_DEPTH = 3;
+
+/** Maximum files to return */
+const DEFAULT_MAX_FILES = 100;
+
+/** Configuration for list directory tool */
+export interface ListDirConfig {
+  /** Working directory for relative paths */
+  workingDir: string;
+  /** Maximum depth for recursive listing (default: 3) */
+  maxDepth?: number;
+  /** Maximum files to return (default: 100) */
+  maxFiles?: number;
+}
+
+interface FileInfo {
+  path: string;
+  type: "file" | "directory";
+}
+
+/**
+ * Create the list_dir tool.
+ */
+export function createListDirTool(config: ListDirConfig): Tool {
+  const maxDepth = config.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const maxFiles = config.maxFiles ?? DEFAULT_MAX_FILES;
+  // Normalize working directory path
+  const normalizedWorkingDir = resolve(config.workingDir);
+
+  return {
+    name: "list_dir",
+    description: "List files and directories. Use this to explore the project structure and find relevant files.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Directory path (relative to working directory or absolute). Use '.' for current directory.",
+        },
+        recursive: {
+          type: "boolean",
+          description: "If true, list files recursively (up to max depth). Default: false.",
+        },
+      },
+      required: ["path"],
+    },
+
+    execute: async (args): Promise<ToolResult> => {
+      const pathArg = args.path;
+      const recursive = args.recursive === true;
+
+      // Validate path argument
+      if (typeof pathArg !== "string") {
+        return err({
+          code: "INVALID_PATH",
+          message: "Path must be a string",
+        });
+      }
+
+      // Handle empty path or "."
+      const targetPath = pathArg.trim() || ".";
+
+      // Resolve path
+      const dirPath = isAbsolute(targetPath)
+        ? resolve(targetPath)
+        : resolve(normalizedWorkingDir, targetPath);
+
+      // Security: Check path traversal using relative path
+      const relativePath = relative(normalizedWorkingDir, dirPath);
+      if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
+        return err({
+          code: "PATH_TRAVERSAL",
+          message: `Path must be within working directory`,
+        });
+      }
+
+      try {
+        const stats = await stat(dirPath);
+
+        if (!stats.isDirectory()) {
+          return err({
+            code: "NOT_A_DIRECTORY",
+            message: `Path is not a directory: ${pathArg}`,
+          });
+        }
+
+        const files: FileInfo[] = [];
+        await listDirectory(dirPath, normalizedWorkingDir, files, 0, recursive ? maxDepth : 0, maxFiles);
+
+        if (files.length === 0) {
+          return ok("Directory is empty.");
+        }
+
+        // Format output
+        const output = files
+          .map((f) => `${f.type === "directory" ? "📁" : "📄"} ${f.path}`)
+          .join("\n");
+
+        const result = files.length >= maxFiles
+          ? `${output}\n\n... limited to ${maxFiles} items`
+          : output;
+
+        return ok(result);
+      } catch (error) {
+        if (isNodeError(error)) {
+          if (error.code === "ENOENT") {
+            return err({
+              code: "NOT_FOUND",
+              message: `Directory not found: ${pathArg}`,
+            });
+          }
+          if (error.code === "EACCES") {
+            return err({
+              code: "PERMISSION_DENIED",
+              message: `Permission denied: ${pathArg}`,
+            });
+          }
+        }
+
+        return err({
+          code: "LIST_ERROR",
+          message: `Failed to list directory: ${error instanceof Error ? error.message : "Unknown error"}`,
+        });
+      }
+    },
+  };
+}
+
+/**
+ * Recursively list directory contents.
+ */
+async function listDirectory(
+  dirPath: string,
+  workingDir: string,
+  files: FileInfo[],
+  depth: number,
+  maxDepth: number,
+  maxFiles: number
+): Promise<void> {
+  if (files.length >= maxFiles) return;
+
+  const entries = await readdir(dirPath, { withFileTypes: true });
+
+  // Sort: directories first, then files, both alphabetically
+  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 (files.length >= maxFiles) break;
+
+    // Skip hidden files and common non-essential directories
+    if (entry.name.startsWith(".") || entry.name === "node_modules") {
+      continue;
+    }
+
+    const fullPath = resolve(dirPath, entry.name);
+    const relativePath = relative(workingDir, fullPath);
+
+    files.push({
+      path: relativePath,
+      type: entry.isDirectory() ? "directory" : "file",
+    });
+
+    // Recurse into directories
+    if (entry.isDirectory() && depth < maxDepth) {
+      await listDirectory(fullPath, workingDir, files, depth + 1, maxDepth, maxFiles);
+    }
+  }
+}
+
+/**
+ * Type guard for Node.js errors with codes.
+ */
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}

package/src/agent/tools/outline.ts

@@ -0,0 +1,259 @@
+/**
+ * File Outline Tool - Get structure of a file (functions, classes).
+ * 
+ * Uses simple regex-based parsing for TypeScript/JavaScript files.
+ * This is fast and works without a full AST parser.
+ */
+
+import { readFile, stat } from "fs/promises";
+import { resolve, isAbsolute, relative, extname } from "path";
+import type { Tool, ToolResult } from "../types";
+import { ok, err } from "../../types/result";
+
+/** Maximum file size for outline (200KB) */
+const MAX_FILE_SIZE = 200 * 1024;
+
+/** Configuration for outline tool */
+export interface OutlineConfig {
+  /** Working directory for relative paths */
+  workingDir: string;
+}
+
+interface OutlineItem {
+  type: "function" | "class" | "method" | "interface" | "type" | "const" | "export";
+  name: string;
+  line: number;
+  signature?: string;
+}
+
+/**
+ * Create the get_outline tool.
+ */
+export function createOutlineTool(config: OutlineConfig): Tool {
+  const normalizedWorkingDir = resolve(config.workingDir);
+
+  return {
+    name: "get_outline",
+    description: "Get the structure of a source file - functions, classes, interfaces. Use this to understand what's in a file without reading all the code.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Path to the file to analyze",
+        },
+      },
+      required: ["path"],
+    },
+
+    execute: async (args): Promise<ToolResult> => {
+      const pathArg = args.path;
+
+      if (typeof pathArg !== "string" || !pathArg.trim()) {
+        return err({
+          code: "INVALID_PATH",
+          message: "Path must be a non-empty string",
+        });
+      }
+
+      // Resolve and validate path
+      const filePath = isAbsolute(pathArg)
+        ? resolve(pathArg)
+        : resolve(normalizedWorkingDir, pathArg);
+
+      const relativePath = relative(normalizedWorkingDir, filePath);
+      if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
+        return err({
+          code: "PATH_TRAVERSAL",
+          message: "Path must be within working directory",
+        });
+      }
+
+      try {
+        const stats = await stat(filePath);
+        
+        if (!stats.isFile()) {
+          return err({
+            code: "NOT_A_FILE",
+            message: `Path is not a file: ${pathArg}`,
+          });
+        }
+
+        if (stats.size > MAX_FILE_SIZE) {
+          return err({
+            code: "FILE_TOO_LARGE",
+            message: `File too large for outline (max 200KB)`,
+          });
+        }
+
+        const content = await readFile(filePath, "utf-8");
+        const ext = extname(filePath).toLowerCase();
+        
+        // Only support common code files
+        const supportedExts = [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"];
+        if (!supportedExts.includes(ext)) {
+          return ok(`Outline not supported for ${ext} files. Use read_file instead.`);
+        }
+
+        const items = parseOutline(content, ext);
+        
+        if (items.length === 0) {
+          return ok("No functions, classes, or interfaces found in this file.");
+        }
+
+        // Format output
+        const output = items
+          .map(item => {
+            const typeIcon = getTypeIcon(item.type);
+            const sig = item.signature ? `: ${item.signature}` : "";
+            return `${item.line.toString().padStart(4)} │ ${typeIcon} ${item.name}${sig}`;
+          })
+          .join("\n");
+
+        return ok(`File: ${pathArg}\n${"─".repeat(50)}\n${output}`);
+      } catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+          return err({
+            code: "NOT_FOUND",
+            message: `File not found: ${pathArg}`,
+          });
+        }
+        if (isNodeError(error) && error.code === "EISDIR") {
+          return err({
+            code: "NOT_A_FILE",
+            message: `Path is a directory, not a file: ${pathArg}`,
+          });
+        }
+        return err({
+          code: "OUTLINE_ERROR",
+          message: `Failed to get outline: ${error instanceof Error ? error.message : "Unknown"}`,
+        });
+      }
+    },
+  };
+}
+
+/**
+ * Parse file content to extract outline items.
+ */
+function parseOutline(content: string, ext: string): OutlineItem[] {
+  const items: OutlineItem[] = [];
+  const lines = content.split("\n");
+
+  // Extension-specific patterns
+  const patterns = getPatterns(ext);
+
+  // Max line length to prevent ReDoS attacks
+  const MAX_LINE_LENGTH = 500;
+
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    const lineNum = i + 1;
+
+    // Skip long lines to prevent ReDoS (catastrophic backtracking)
+    if (!rawLine || rawLine.length > MAX_LINE_LENGTH) continue;
+    
+    // Skip comment lines to avoid false positives
+    const trimmed = rawLine.trim();
+    if (trimmed.startsWith("//") || trimmed.startsWith("/*") || trimmed.startsWith("*") || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    for (const { regex, type, nameGroup, sigGroup } of patterns) {
+      const match = rawLine.match(regex);
+      if (match && match[nameGroup]) {
+        items.push({
+          type,
+          name: match[nameGroup],
+          line: lineNum,
+          signature: sigGroup && match[sigGroup] ? match[sigGroup].trim() : undefined,
+        });
+        break;
+      }
+    }
+  }
+
+  return items;
+}
+
+interface Pattern {
+  regex: RegExp;
+  type: OutlineItem["type"];
+  nameGroup: number;
+  sigGroup?: number;
+}
+
+function getPatterns(ext: string): Pattern[] {
+  if ([".ts", ".tsx", ".js", ".jsx"].includes(ext)) {
+    return [
+      // export function name(...)
+      { regex: /^export\s+(?:async\s+)?function\s+(\w+)\s*(\([^)]*\))?/, type: "function", nameGroup: 1, sigGroup: 2 },
+      // function name(...)
+      { regex: /^(?:async\s+)?function\s+(\w+)\s*(\([^)]*\))?/, type: "function", nameGroup: 1, sigGroup: 2 },
+      // const name = async (...) =>
+      { regex: /^(?:export\s+)?const\s+(\w+)\s*=\s*(?:async\s+)?\([^)]*\)\s*(?::\s*\w+)?\s*=>/, type: "function", nameGroup: 1 },
+      // export class Name
+      { regex: /^export\s+(?:abstract\s+)?class\s+(\w+)/, type: "class", nameGroup: 1 },
+      // class Name
+      { regex: /^(?:abstract\s+)?class\s+(\w+)/, type: "class", nameGroup: 1 },
+      // export interface Name
+      { regex: /^export\s+interface\s+(\w+)/, type: "interface", nameGroup: 1 },
+      // interface Name
+      { regex: /^interface\s+(\w+)/, type: "interface", nameGroup: 1 },
+      // export type Name
+      { regex: /^export\s+type\s+(\w+)/, type: "type", nameGroup: 1 },
+      // type Name
+      { regex: /^type\s+(\w+)/, type: "type", nameGroup: 1 },
+      // method in class/object: name(...) { or async name(...)
+      { regex: /^\s+(?:async\s+)?(\w+)\s*\([^)]*\)\s*(?::\s*\S+)?\s*\{/, type: "method", nameGroup: 1 },
+    ];
+  }
+  
+  if (ext === ".py") {
+    return [
+      { regex: /^def\s+(\w+)\s*\(([^)]*)\)/, type: "function", nameGroup: 1, sigGroup: 2 },
+      { regex: /^async\s+def\s+(\w+)\s*\(([^)]*)\)/, type: "function", nameGroup: 1, sigGroup: 2 },
+      { regex: /^class\s+(\w+)/, type: "class", nameGroup: 1 },
+      { regex: /^\s{4}def\s+(\w+)\s*\(([^)]*)\)/, type: "method", nameGroup: 1, sigGroup: 2 },
+    ];
+  }
+
+  if (ext === ".go") {
+    return [
+      { regex: /^func\s+(\w+)\s*\(([^)]*)\)/, type: "function", nameGroup: 1, sigGroup: 2 },
+      { regex: /^func\s+\(\w+\s+\*?\w+\)\s+(\w+)\s*\(([^)]*)\)/, type: "method", nameGroup: 1, sigGroup: 2 },
+      { regex: /^type\s+(\w+)\s+struct/, type: "class", nameGroup: 1 },
+      { regex: /^type\s+(\w+)\s+interface/, type: "interface", nameGroup: 1 },
+    ];
+  }
+
+  if (ext === ".rs") {
+    return [
+      { regex: /^pub\s+fn\s+(\w+)\s*\(([^)]*)\)/, type: "function", nameGroup: 1, sigGroup: 2 },
+      { regex: /^fn\s+(\w+)\s*\(([^)]*)\)/, type: "function", nameGroup: 1, sigGroup: 2 },
+      { regex: /^pub\s+struct\s+(\w+)/, type: "class", nameGroup: 1 },
+      { regex: /^struct\s+(\w+)/, type: "class", nameGroup: 1 },
+      { regex: /^pub\s+trait\s+(\w+)/, type: "interface", nameGroup: 1 },
+      { regex: /^trait\s+(\w+)/, type: "interface", nameGroup: 1 },
+    ];
+  }
+
+  return [];
+}
+
+function getTypeIcon(type: OutlineItem["type"]): string {
+  switch (type) {
+    case "function": return "ƒ";
+    case "class": return "◆";
+    case "method": return "○";
+    case "interface": return "◇";
+    case "type": return "τ";
+    case "const": return "●";
+    case "export": return "→";
+    default: return "•";
+  }
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}