Add documentation for the execute_command tool and its functionality

Author: hannesrudolph

docs/features/tools/execute-command.md

@@ -0,0 +1,153 @@
+# execute_command
+
+The `execute_command` tool runs CLI commands on the user's system. It allows Roo to perform system operations, install dependencies, build projects, start servers, and execute other terminal-based tasks needed to accomplish user objectives.
+
+## Parameters
+
+The tool accepts these parameters:
+
+- `command` (required): The CLI command to execute. Must be valid for the user's operating system.
+- `cwd` (optional): The working directory to execute the command in. If not provided, the current working directory is used.
+
+## What It Does
+
+This tool executes terminal commands directly on the user's system, enabling a wide range of operations from file manipulations to running development servers. Commands run in managed terminal instances with real-time output capture, integrated with VS Code's terminal system for optimal performance and security.
+
+## When is it used?
+
+- When installing project dependencies (npm install, pip install, etc.)
+- When building or compiling code (make, npm run build, etc.)
+- When starting development servers or running applications
+- When initializing new projects (git init, npm init, etc.)
+- When performing file operations beyond what other tools provide
+- When running tests or linting operations
+- When needing to execute specialized commands for specific technologies
+
+## Key Features
+
+- Integrates with VS Code shell API for reliable terminal execution
+- Reuses terminal instances when possible through a registry system
+- Captures command output line by line with real-time feedback
+- Supports long-running commands that continue in the background
+- Allows specification of custom working directories
+- Maintains terminal history and state across command executions
+- Handles complex command chains appropriate for the user's shell
+- Provides detailed command completion status and exit code interpretation
+- Supports interactive terminal applications with user feedback loop
+- Shows terminals during execution for transparency
+- Validates commands for security using shell-quote parsing
+- Blocks potentially dangerous subshell execution patterns
+- Integrates with RooIgnore system for file access control
+- Handles terminal escape sequences for clean output
+
+## Limitations
+
+- Command access may be restricted by RooIgnore rules and security validations
+- Commands with elevated permission requirements may need user configuration
+- Behavior may vary across operating systems for certain commands
+- Very long-running commands may require specific handling
+- File paths should be properly escaped according to the OS shell rules
+- Not all terminal features may work with remote development scenarios
+
+## How It Works
+
+When the `execute_command` tool is invoked, it follows this process:
+
+1. **Command Validation and Security Checks**:
+   - Parses the command using shell-quote to identify components
+   - Validates against security restrictions (subshell usage, restricted files)
+   - Checks against RooIgnore rules for file access permissions
+   - Ensures the command meets system security requirements
+
+2. **Terminal Management**:
+   - Gets or creates a terminal through TerminalRegistry
+   - Sets up the working directory context
+   - Prepares event listeners for output capture
+   - Shows the terminal for user visibility
+
+3. **Command Execution and Monitoring**:
+   - Executes via VS Code's shellIntegration API
+   - Captures output with escape sequence processing
+   - Throttles output handling (100ms intervals)
+   - Monitors for command completion or errors
+   - Detects "hot" processes like compilers for special handling
+
+4. **Result Processing**:
+   - Strips ANSI/VS Code escape sequences for clean output
+   - Interprets exit codes with detailed signal information
+   - Updates working directory tracking if changed by command
+   - Provides command status with appropriate context
+
+## Terminal Implementation Details
+
+The tool uses a sophisticated terminal management system:
+
+1. **First Priority: Terminal Reuse**
+   - The TerminalRegistry tries to reuse existing terminals when possible
+   - This reduces proliferation of terminal instances and improves performance
+   - Terminal state (working directory, history) is preserved across commands
+
+2. **Second Priority: Security Validation**
+   - Commands are parsed using shell-quote for component analysis
+   - Dangerous patterns like `$(...)` and backticks are blocked
+   - Commands are checked against RooIgnore rules for file access control
+   - A prefix-based allowlist system validates command patterns
+
+3. **Performance Optimizations**
+   - Output is processed in 100ms throttled intervals to prevent UI overload
+   - Zero-copy buffer management uses index-based tracking for efficiency
+   - Special handling for compilation and "hot" processes
+   - Platform-specific optimizations for Windows PowerShell
+
+4. **Error and Signal Handling**
+   - Exit codes are mapped to detailed signal information (SIGTERM, SIGKILL, etc.)
+   - Core dump detection for critical failures
+   - Working directory changes are tracked and handled automatically
+   - Clean recovery from terminal disconnection scenarios
+
+## Examples When Used
+
+- When setting up a new project, Roo runs initialization commands like `npm init -y` followed by installing dependencies.
+- When building a web application, Roo executes build commands like `npm run build` to compile assets.
+- When deploying code, Roo runs git commands to commit and push changes to a repository.
+- When troubleshooting, Roo executes diagnostic commands to gather system information.
+- When starting a development server, Roo launches the appropriate server command (e.g., `npm start`).
+- When running tests, Roo executes the test runner command for the project's testing framework.
+
+## Usage Examples
+
+Running a simple command in the current directory:
+```
+<execute_command>
+<command>npm run dev</command>
+</execute_command>
+```
+
+Installing dependencies for a project:
+```
+<execute_command>
+<command>npm install express mongodb mongoose dotenv</command>
+</execute_command>
+```
+
+Running multiple commands in sequence:
+```
+<execute_command>
+<command>mkdir -p src/components && touch src/components/App.js</command>
+</execute_command>
+```
+
+Executing a command in a specific directory:
+```
+<execute_command>
+<command>git status</command>
+<cwd>./my-project</cwd>
+</execute_command>
+```
+
+Building and then starting a project:
+```
+<execute_command>
+<command>npm run build && npm start</command>
+</execute_command>
+```