Relevant source files

The following files were used as context for generating this wiki page: - [src-tauri/src/execute.rs](https://github.com/s00d/switchshuttle/blob/main/src-tauri/src/execute.rs) - [src-tauri/src/commands.rs](https://github.com/s00d/switchshuttle/blob/main/src-tauri/src/commands.rs) - [src-tauri/src/console.rs](https://github.com/s00d/switchshuttle/blob/main/src-tauri/src/console.rs) - [src/lib/security.ts](https://github.com/s00d/switchshuttle/blob/main/src/lib/security.ts) - [src/components/commands/CommandItem.vue](https://github.com/s00d/switchshuttle/blob/main/src/components/commands/CommandItem.vue) - [README.md](https://github.com/s00d/switchshuttle/blob/main/README.md)

# Command Execution Engine The Command Execution Engine is the core component of SwitchShuttle, responsible for processing, validating, and dispatching terminal commands across different operating systems. It acts as a bridge between the user interface and the underlying system shells, supporting various terminal applications like iTerm2, PowerShell, and GNOME Terminal. The engine handles three primary execution workflows: standard terminal execution (foreground), silent execution (background) via a ConsolePool, and scheduled execution using cron expressions. It ensures that commands are properly escaped for the target shell and validated against security policies before execution. ## Core Architecture and Data Flow The engine is structured to handle command requests from the frontend or CLI, apply dynamic variable substitutions, and route them to the appropriate execution handler based on the `background` flag or command type (e.g., Switch or Monitor commands). ### Execution Workflow The following diagram illustrates the path a command takes from the UI through validation and template processing to the final system execution. ```mermaid flowchart TD UI[User Trigger] --> Val[Security Validation] Val --> Input[Input Substitution] Input --> Mode{Execution Mode?} Mode -- Foreground --> Term[Terminal Dispatcher] Mode -- Background --> Pool[ConsolePool Execution] Term --> OS_Script[OS Specific Scripts/Args] Pool --> Silent[Silent System Command] OS_Script --> Shell[Target Terminal/Shell] ``` Sources: [src-tauri/src/execute.rs:430-490](), [src-tauri/src/commands.rs:141-210](), [src/lib/security.ts:114-130]() ### Terminal Configuration The engine maintains a registry of supported terminal applications for macOS, Windows, and Linux. Each terminal is defined by a `TerminalConfig` struct. | OS | Supported Terminals | Executable | | :--- | :--- | :--- | | **macOS** | iTerm, Terminal.app, Warp, Hyper, Alacritty, VSCode | `osascript` | | **Windows** | PowerShell, CMD, Windows Terminal, WSL, Hyper, Git Bash, Alacritty | `cmd`, `powershell`, or `wsl` | | **Linux** | GNOME Terminal, Konsole, XFCE4, Alacritty, WezTerm, Kitty | Native binaries | Sources: [src-tauri/src/execute.rs:13-140]() ## Command Processing Logic ### Dynamic Input Substitution Before a command is sent to the shell, the engine performs string replacement for dynamic inputs defined in the command configuration. The syntax `[variable_name]` is used in the command string and matched against values provided by the user. ```rust // Example of substitution logic in commands.rs if let Some(ref mut cmd) = cmd { for (key, value) in &inputs { *cmd = cmd.replace(&format!("[{}]", key), value); } } ``` Sources: [src-tauri/src/commands.rs:163-180](), [src/components/commands/CommandItem.vue:150-200]() ### OS-Specific Escaping To prevent shell injection and ensure compatibility, the engine includes a `process_command_placeholder` function that handles quoting differently for each platform. * **macOS**: Uses AppleScript (`osascript`) where double quotes are escaped as `\"`. * **Windows**: Escapes double quotes by doubling them (`""`) for compatibility with `cmd.exe`. * **Linux**: Standard shell escaping using `\"`. Sources: [src-tauri/src/execute.rs:400-428]() ## Execution Modes The engine supports multiple ways to present and run commands, primarily controlled by the `launch_in` and `background` parameters. ### Foreground Execution (Terminal) Foreground execution launches the actual terminal application. On macOS, this is achieved via AppleScript templates stored in the `scripts` directory (e.g., `iTerm2-Tab.scpt`). On Windows and Linux, it uses direct process spawning with specific arguments for new tabs or windows. | Mode | Description | | :--- | :--- | | `current` | Executes in the currently active terminal session. | | `new_tab` | Opens a new tab in the target terminal. | | `new_window` | Spawns a completely new terminal window. | Sources: [src-tauri/src/execute.rs:340-398](), [README.md:460-475]() ### Background Execution (Silent) Commands marked with `"background": true` or specific types like **Switch** and **Monitor** commands bypass the terminal UI entirely. They are executed using `ConsoleInstance::execute_command_silent`. ```mermaid sequenceDiagram participant E as Execution Engine participant C as ConsolePool participant S as System Shell E->>C: Request silent execution C->>S: std::process::Command::new(...) S-->>C: Output/Exit Status C-->>E: Result (Ok/Err) ``` Sources: [src-tauri/src/commands.rs:198-215](), [src-tauri/src/execute.rs:430-450]() ## Security and Validation The `SecurityManager` acts as a gatekeeper within the execution engine. It analyzes commands for dangerous patterns and ensures they conform to length restrictions before they reach the system shell. ### Validation Rules The engine checks for: 1. **Blocked Commands**: Patterns like `rm -rf /` or `format c:`. 2. **Suspicious Activity**: Usage of `sudo`, `curl` to unknown hosts, or destructive filesystem actions. 3. **Command Length**: Limits (default 1000 chars) to prevent buffer overflows or malicious payloads. 4. **Character Filtering**: Detects suspicious shell characters like `;`, `|`, and `&` in user inputs to prevent injection. Sources: [src/lib/security.ts:50-110](), [src/lib/security.ts:160-200]() ## Implementation Details ### Data Structures The core data structure for command definition is the `CommandConfig`. ```rust pub struct CommandConfig { pub id: Option, pub name: String, pub command: Option, pub commands: Option>, pub submenu: Option>, pub switch: Option, pub monitor: Option, pub background: Option, // ... other fields } ``` Sources: [src-tauri/src/commands.rs:130-140](), [src-tauri/src/execute.rs:430-440]() ### Execution Dispatcher The `execute_command` function in `execute.rs` is the primary entry point. It normalizes inputs, validates terminal support via `is_terminal_supported`, and iterates through the `commands` vector to execute them sequentially. Sources: [src-tauri/src/execute.rs:430-488]() ## Summary The Command Execution Engine provides a robust, cross-platform abstraction for running terminal operations. By combining OS-specific scripting (AppleScript for macOS) with direct process management (Windows/Linux) and a background execution pool, it allows for seamless management of both interactive development tools and silent system monitoring tasks. Integrated security validation ensures that these powerful capabilities remain safe for the end-user. Sources: [README.md:15-50](), [src-tauri/src/execute.rs:480-490]()