xibecode 0.3.5 → 0.3.8

package/dist/core/tools.js

@@ -13,6 +13,51 @@ import { BrowserManager } from '../tools/browser.js';
 import * as os from 'os';
 import { SkillManager } from './skills.js';
 const execAsync = promisify(exec);
+/**
+ * Main tool executor for XibeCode agent
+ *
+ * Provides 95+ tools across 8 categories for autonomous coding operations:
+ * - File Operations: read, write, edit, delete files
+ * - Git Operations: status, diff, commit, reset
+ * - Shell Commands: run commands, interactive shell
+ * - Web Operations: search, fetch URLs, HTTP requests
+ * - Context Operations: code search, file finding, context discovery
+ * - Test Operations: run tests, get results
+ * - Memory Operations: update neural memory
+ * - Browser Operations: web automation with Playwright
+ *
+ * Features:
+ * - Mode-based tool permissions
+ * - Safety checking for dangerous operations
+ * - Plugin support for custom tools
+ * - MCP integration for external tools
+ * - Dry-run mode for safe previews
+ * - Backup system for file operations
+ *
+ * @example
+ * ```typescript
+ * const executor = new CodingToolExecutor('/project', {
+ *   dryRun: false,
+ *   pluginManager,
+ *   memory
+ * });
+ *
+ * executor.setMode('agent');
+ *
+ * // Read a file
+ * const result = await executor.execute('read_file', { path: 'src/app.ts' });
+ *
+ * // Edit a file
+ * await executor.execute('edit_file', {
+ *   path: 'src/app.ts',
+ *   search: 'old code',
+ *   replace: 'new code'
+ * });
+ * ```
+ *
+ * @category Tool Execution
+ * @since 0.1.0
+ */
 export class CodingToolExecutor {
     workingDir;
     contextManager;
@@ -28,6 +73,37 @@ export class CodingToolExecutor {
     platform;
     dryRun;
     testCommandOverride;
+    /**
+     * Creates a new CodingToolExecutor instance
+     *
+     * Initializes all tool subsystems including file operations, git utilities,
+     * test runner, safety checker, plugin manager, and optional MCP integration.
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const executor = new CodingToolExecutor('/project');
+     *
+     * // With options
+     * const executor = new CodingToolExecutor('/project', {
+     *   dryRun: true,
+     *   pluginManager: new PluginManager(),
+     *   memory: new NeuralMemory('./.xibecode/memory.json')
+     * });
+     * ```
+     *
+     * @param workingDir - Working directory for file operations (default: process.cwd())
+     * @param options - Configuration options
+     * @param options.dryRun - Enable dry-run mode (preview changes without executing)
+     * @param options.testCommandOverride - Override test command detection
+     * @param options.pluginManager - Plugin manager instance for custom tools
+     * @param options.mcpClientManager - MCP client manager for external tool integration
+     * @param options.memory - Neural memory instance for persistent learning
+     * @param options.skillManager - Skill manager for loading custom workflows
+     *
+     * @category Constructor
+     * @since 0.1.0
+     */
     constructor(workingDir = process.cwd(), options) {
         this.workingDir = workingDir;
         this.contextManager = new ContextManager(workingDir);
@@ -46,6 +122,26 @@ export class CodingToolExecutor {
         this.testCommandOverride = options?.testCommandOverride;
     }
     currentMode = 'agent';
+    /**
+     * Set the current agent mode
+     *
+     * Changes the tool executor's operating mode, which affects:
+     * - Tool permissions (what tools are available)
+     * - Dry-run default (some modes preview changes by default)
+     * - Risk tolerance for operations
+     *
+     * @example
+     * ```typescript
+     * executor.setMode('plan');      // Read-only mode
+     * executor.setMode('agent');     // Full capabilities
+     * executor.setMode('security');  // Security-focused mode
+     * ```
+     *
+     * @param mode - Agent mode to switch to
+     *
+     * @category Mode Management
+     * @since 0.1.0
+     */
     setMode(mode) {
         this.currentMode = mode;
         const config = MODE_CONFIG[mode];
@@ -53,6 +149,11 @@ export class CodingToolExecutor {
     }
     /**
      * Safely parse tool input - handles string JSON, null, undefined
+     *
+     * @param input - Raw tool input (string, object, null, or undefined)
+     * @returns Parsed input as object
+     *
+     * @internal
      */
     parseInput(input) {
         if (!input)
@@ -69,6 +170,49 @@ export class CodingToolExecutor {
             return input;
         return {};
     }
+    /**
+     * Execute a tool with given input
+     *
+     * Main tool execution pipeline that:
+     * 1. Checks tool permissions for current mode
+     * 2. Routes MCP tools to external servers
+     * 3. Routes plugin tools to plugin manager
+     * 4. Performs safety assessment for risky operations
+     * 5. Executes the tool implementation
+     * 6. Returns structured result
+     *
+     * @example
+     * ```typescript
+     * // Read a file
+     * const result = await executor.execute('read_file', {
+     *   path: 'src/app.ts'
+     * });
+     *
+     * if (result.success) {
+     *   console.log(result.content);
+     * }
+     *
+     * // Edit a file
+     * await executor.execute('edit_file', {
+     *   path: 'src/app.ts',
+     *   search: 'const old = 1;',
+     *   replace: 'const new = 2;'
+     * });
+     *
+     * // Run a command
+     * await executor.execute('run_command', {
+     *   command: 'npm test'
+     * });
+     * ```
+     *
+     * @param toolName - Name of the tool to execute (e.g., 'read_file', 'edit_file')
+     * @param input - Tool input parameters (varies by tool)
+     * @returns Tool execution result with success/error status
+     *
+     * @see {@link getTools} for list of available tools
+     * @category Tool Execution
+     * @since 0.1.0
+     */
     async execute(toolName, input) {
         // Check tool permissions first
         const permission = isToolAllowed(this.currentMode, toolName);
@@ -327,6 +471,44 @@ export class CodingToolExecutor {
                     return { error: true, success: false, message: 'Missing url' };
                 return this.browserManager.getConsoleLogs(p.url);
             }
+            case 'run_visual_test': {
+                if (!p.url || typeof p.url !== 'string')
+                    return { error: true, success: false, message: 'Missing url' };
+                if (!p.baseline_path || typeof p.baseline_path !== 'string')
+                    return { error: true, success: false, message: 'Missing baseline_path' };
+                const outputDir = p.output_dir || '.playwright-baselines';
+                return this.browserManager.runVisualTest(p.url, this.resolvePath(p.baseline_path), this.resolvePath(outputDir));
+            }
+            case 'check_accessibility': {
+                if (!p.url || typeof p.url !== 'string')
+                    return { error: true, success: false, message: 'Missing url' };
+                return this.browserManager.checkAccessibility(p.url);
+            }
+            case 'measure_performance': {
+                if (!p.url || typeof p.url !== 'string')
+                    return { error: true, success: false, message: 'Missing url' };
+                return this.browserManager.measurePerformance(p.url);
+            }
+            case 'test_responsive': {
+                if (!p.url || typeof p.url !== 'string')
+                    return { error: true, success: false, message: 'Missing url' };
+                const outputDir = p.output_dir || '.responsive-screenshots';
+                return this.browserManager.testResponsive(p.url, this.resolvePath(outputDir), p.viewports);
+            }
+            case 'capture_network': {
+                if (!p.url || typeof p.url !== 'string')
+                    return { error: true, success: false, message: 'Missing url' };
+                return this.browserManager.captureNetworkRequests(p.url);
+            }
+            case 'run_playwright_test': {
+                if (!p.test_path || typeof p.test_path !== 'string')
+                    return { error: true, success: false, message: 'Missing test_path' };
+                return this.browserManager.runPlaywrightTest(this.resolvePath(p.test_path), {
+                    headed: p.headed,
+                    browser: p.browser,
+                    timeout: p.timeout,
+                });
+            }
             case 'search_skills_sh': {
                 if (!p.query || typeof p.query !== 'string') {
                     return { error: true, success: false, message: 'Missing required parameter: query (string)' };
@@ -340,9 +522,43 @@ export class CodingToolExecutor {
                 return this.installSkillFromSkillsSh(p.skill_id);
             }
             default:
-                return { error: true, success: false, message: `Unknown tool: ${toolName}. Available tools: read_file, read_multiple_files, write_file, edit_file, edit_lines, insert_at_line, verified_edit, list_directory, search_files, run_command, create_directory, delete_file, move_file, get_context, revert_file, run_tests, get_test_status, get_git_status, get_git_diff_summary, get_git_changed_files, create_git_checkpoint, revert_to_git_checkpoint, git_show_diff, get_mcp_status, grep_code, web_search, fetch_url, remember_lesson, take_screenshot, get_console_logs, search_skills_sh, install_skill_from_skills_sh` };
+                return { error: true, success: false, message: `Unknown tool: ${toolName}. Available tools: read_file, read_multiple_files, write_file, edit_file, edit_lines, insert_at_line, verified_edit, list_directory, search_files, run_command, create_directory, delete_file, move_file, get_context, revert_file, run_tests, get_test_status, get_git_status, get_git_diff_summary, get_git_changed_files, create_git_checkpoint, revert_to_git_checkpoint, git_show_diff, get_mcp_status, grep_code, web_search, fetch_url, remember_lesson, take_screenshot, get_console_logs, run_visual_test, check_accessibility, measure_performance, test_responsive, capture_network, run_playwright_test, search_skills_sh, install_skill_from_skills_sh` };
         }
     }
+    /**
+     * Get all available tools for the agent
+     *
+     * Returns an array of tool definitions including core tools, plugin tools,
+     * and MCP tools. Each tool includes:
+     * - name: Tool identifier
+     * - description: What the tool does (for Claude AI)
+     * - input_schema: JSON Schema for input validation
+     *
+     * Tools are grouped by category:
+     * - File Operations: read_file, write_file, edit_file, etc.
+     * - Git Operations: get_git_status, git_commit, etc.
+     * - Shell Commands: run_command, interactive_shell
+     * - Web Operations: web_search, fetch_url, http_request
+     * - Context Operations: grep_code, search_files, get_context
+     * - Test Operations: run_tests, get_test_status
+     * - Memory Operations: update_memory
+     * - Browser Operations: open_browser, browser_click, etc.
+     *
+     * @example
+     * ```typescript
+     * const tools = executor.getTools();
+     * console.log(`${tools.length} tools available`);
+     *
+     * // Find a specific tool
+     * const readFile = tools.find(t => t.name === 'read_file');
+     * console.log(readFile.description);
+     * ```
+     *
+     * @returns Array of tool definitions with schemas
+     *
+     * @category Tool Management
+     * @since 0.1.0
+     */
     getTools() {
         const coreTools = [
             {
@@ -852,6 +1068,90 @@ export class CodingToolExecutor {
                     required: ['url']
                 }
             },
+            {
+                name: 'run_visual_test',
+                description: 'Run visual regression testing by comparing screenshots. Creates baseline on first run, then compares subsequent screenshots against it. Perfect for catching unintended UI changes.',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        url: { type: 'string', description: 'URL to test (e.g., http://localhost:3000)' },
+                        baseline_path: { type: 'string', description: 'Path to baseline screenshot file (e.g., baselines/homepage.png)' },
+                        output_dir: { type: 'string', description: 'Directory for test output (default: .playwright-baselines)' }
+                    },
+                    required: ['url', 'baseline_path']
+                }
+            },
+            {
+                name: 'check_accessibility',
+                description: 'Run accessibility audit on a webpage. Checks for missing alt text, form labels, heading hierarchy, color contrast, and other WCAG issues. Returns errors, warnings, and notices.',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        url: { type: 'string', description: 'URL to audit (e.g., http://localhost:3000)' }
+                    },
+                    required: ['url']
+                }
+            },
+            {
+                name: 'measure_performance',
+                description: 'Measure Core Web Vitals and performance metrics: First Contentful Paint (FCP), Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), Time to Interactive (TTI), and DOM Content Loaded. Essential for UX and SEO.',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        url: { type: 'string', description: 'URL to measure (e.g., http://localhost:3000)' }
+                    },
+                    required: ['url']
+                }
+            },
+            {
+                name: 'test_responsive',
+                description: 'Test a page across multiple viewport sizes (mobile, tablet, desktop). Takes screenshots at each breakpoint and reports any JavaScript errors. Perfect for responsive design testing.',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        url: { type: 'string', description: 'URL to test (e.g., http://localhost:3000)' },
+                        output_dir: { type: 'string', description: 'Directory for screenshots (default: .responsive-screenshots)' },
+                        viewports: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    name: { type: 'string' },
+                                    width: { type: 'number' },
+                                    height: { type: 'number' }
+                                }
+                            },
+                            description: 'Custom viewports. Default: mobile (375x667), tablet (768x1024), desktop (1280x800), desktop-large (1920x1080)'
+                        }
+                    },
+                    required: ['url']
+                }
+            },
+            {
+                name: 'capture_network',
+                description: 'Capture all network requests made during page load. Shows URLs, methods, status codes, resource types, and timing. Useful for debugging API calls, detecting failed requests, and performance analysis.',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        url: { type: 'string', description: 'URL to load and monitor (e.g., http://localhost:3000)' }
+                    },
+                    required: ['url']
+                }
+            },
+            {
+                name: 'run_playwright_test',
+                description: 'Execute a Playwright test file. Runs the test and returns pass/fail results with output. Great for running E2E tests, integration tests, and component tests.',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        test_path: { type: 'string', description: 'Path to the Playwright test file (e.g., tests/homepage.spec.ts)' },
+                        headed: { type: 'boolean', description: 'Run with visible browser window (default: false)' },
+                        browser: { type: 'string', enum: ['chromium', 'firefox', 'webkit'], description: 'Browser to use (default: chromium)' },
+                        timeout: { type: 'number', description: 'Test timeout in milliseconds (default: 120000)' }
+                    },
+                    required: ['test_path']
+                }
+            },
             {
                 name: 'fetch_url',
                 description: 'Fetch and read content from any URL. HTML is automatically stripped to plain text. Use this to read documentation pages, API references, blog posts, or any web content. Supports HTML, JSON, and plain text.',
@@ -933,9 +1233,50 @@ export class CodingToolExecutor {
         const pluginTools = this.pluginManager.getPluginTools();
         return [...coreTools, ...mcpTools, ...pluginTools];
     }
+    /**
+     * Resolve relative file path to absolute path
+     *
+     * @param filePath - Relative or absolute file path
+     * @returns Absolute path resolved against working directory
+     *
+     * @internal
+     */
     resolvePath(filePath) {
         return path.resolve(this.workingDir, filePath);
     }
+    /**
+     * Read file contents
+     *
+     * Reads a file from the filesystem. Supports partial reading by line range
+     * to avoid token limits for large files. Always returns UTF-8 encoded text.
+     *
+     * @example
+     * ```typescript
+     * // Read entire file
+     * const result = await executor.execute('read_file', {
+     *   path: 'src/app.ts'
+     * });
+     *
+     * // Read specific line range
+     * const partial = await executor.execute('read_file', {
+     *   path: 'src/large-file.ts',
+     *   start_line: 100,
+     *   end_line: 200
+     * });
+     * ```
+     *
+     * @param filePath - Path to file (relative to working directory)
+     * @param startLine - Optional start line for partial read (1-indexed)
+     * @param endLine - Optional end line for partial read (inclusive)
+     * @returns Object with path, content, and line info
+     *
+     * @throws {FileNotFoundError} If file doesn't exist
+     * @throws {PermissionError} If file is not readable
+     *
+     * @category File Operations
+     * @mode All modes
+     * @since 0.1.0
+     */
     async readFile(filePath, startLine, endLine) {
         const fullPath = this.resolvePath(filePath);
         try {
@@ -977,6 +1318,33 @@ export class CodingToolExecutor {
                 .map((r, i) => ({ path: paths[i], error: r.reason.message })),
         };
     }
+    /**
+     * Write content to file
+     *
+     * Creates or overwrites a file with the given content. Automatically creates
+     * parent directories if they don't exist. Creates a backup before overwriting
+     * existing files.
+     *
+     * In dry-run mode, shows what would be written without making changes.
+     *
+     * @example
+     * ```typescript
+     * await executor.execute('write_file', {
+     *   path: 'src/new-file.ts',
+     *   content: 'export const hello = "world";'
+     * });
+     * ```
+     *
+     * @param filePath - Path to file (relative to working directory)
+     * @param content - File content to write
+     * @returns Object with success status, path, and file info
+     *
+     * @throws {PermissionError} If directory is not writable
+     *
+     * @category File Operations
+     * @mode Write modes (agent, engineer, architect)
+     * @since 0.1.0
+     */
     async writeFile(filePath, content) {
         const fullPath = this.resolvePath(filePath);
         if (this.dryRun) {
@@ -1005,6 +1373,47 @@ export class CodingToolExecutor {
             return { error: true, success: false, message: `Failed to write ${filePath}: ${error.message}` };
         }
     }
+    /**
+     * Edit file using search and replace
+     *
+     * Performs intelligent search-and-replace editing using the FileEditor's
+     * smart edit strategy. Searches for exact string matches and replaces them.
+     * Automatically handles multi-line strings and special characters.
+     *
+     * Creates a backup before editing. In dry-run mode, shows what would be
+     * changed without modifying the file.
+     *
+     * @example
+     * ```typescript
+     * // Replace first occurrence
+     * await executor.execute('edit_file', {
+     *   path: 'src/app.ts',
+     *   search: 'const oldValue = 1;',
+     *   replace: 'const newValue = 2;'
+     * });
+     *
+     * // Replace all occurrences
+     * await executor.execute('edit_file', {
+     *   path: 'src/app.ts',
+     *   search: 'oldName',
+     *   replace: 'newName',
+     *   all: true
+     * });
+     * ```
+     *
+     * @param filePath - Path to file (relative to working directory)
+     * @param search - Exact string to search for (can be multi-line)
+     * @param replace - Replacement string
+     * @param all - Replace all occurrences (default: false, replaces first only)
+     * @returns Object with success status, changes made, and diff
+     *
+     * @throws {FileNotFoundError} If file doesn't exist
+     * @throws {SearchNotFoundError} If search string not found
+     *
+     * @category File Operations
+     * @mode Write modes (agent, engineer, architect)
+     * @since 0.1.0
+     */
     async editFile(filePath, search, replace, all) {
         if (this.dryRun) {
             return {
@@ -1097,6 +1506,56 @@ export class CodingToolExecutor {
             return { error: true, success: false, message: `Failed to search files: ${error.message}` };
         }
     }
+    /**
+     * Execute a shell command
+     *
+     * Runs a command in a shell (bash on Unix, PowerShell on Windows).
+     * Captures stdout and stderr. Supports stdin input for interactive commands.
+     * Automatically times out after 120 seconds (configurable).
+     *
+     * Safety checks are performed before execution to block dangerous commands
+     * like `rm -rf /`, malicious scripts, and other high-risk operations.
+     *
+     * @example
+     * ```typescript
+     * // Run a simple command
+     * const result = await executor.execute('run_command', {
+     *   command: 'npm test'
+     * });
+     *
+     * // Run with specific working directory
+     * await executor.execute('run_command', {
+     *   command: 'ls -la',
+     *   cwd: './src'
+     * });
+     *
+     * // Run with stdin input
+     * await executor.execute('run_command', {
+     *   command: 'cat > output.txt',
+     *   input: 'Hello World'
+     * });
+     *
+     * // Run with custom timeout
+     * await executor.execute('run_command', {
+     *   command: 'npm install',
+     *   timeout: 300  // 5 minutes
+     * });
+     * ```
+     *
+     * @param command - Shell command to execute
+     * @param cwd - Working directory (default: executor's working directory)
+     * @param input - Optional stdin input for interactive commands
+     * @param timeout - Timeout in seconds (default: 120)
+     * @returns Object with stdout, stderr, exit code, and execution time
+     *
+     * @throws {SafetyError} If command is blocked by safety checker
+     * @throws {TimeoutError} If command exceeds timeout
+     *
+     * @category Shell Commands
+     * @mode Command modes (agent, engineer, debugger, tester)
+     * @risk-level High
+     * @since 0.1.0
+     */
     async runCommand(command, cwd, input, timeout) {
         const workDir = cwd ? this.resolvePath(cwd) : this.workingDir;
         const timeoutMs = (timeout || 120) * 1000;