refactor: implement modular command handler architecture with async traits

Author: g

.gitignore

@@ -2,3 +2,6 @@
 
 # Documentation files
 TODO.md
+
+# VS Code
+.vscode/

.vscode/settings.json

@@ -3,23 +3,39 @@
 ## Technology Stack
 - **Rust 2021 Edition**: Command-line tool for OBS Studio control
 - **obws**: OBS WebSocket client library
-- **clap**: Command-line argument parsing
-- **tokio**: Async runtime
+- **clap**: Command-line argument parsing with derive macros
+- **tokio**: Async runtime with multi-threaded scheduler
+- **thiserror**: Error handling with derive macros
+- **async-trait**: Async trait support for command handlers
 - The official obs-websocket spec https://raw.githubusercontent.com/obsproject/obs-websocket/master/docs/generated/protocol.md
 
-## Project Structure
-```
-src/
-├── main.rs          # Application entry point and WebSocket connection
-├── cli.rs           # CLI argument definitions and parsing
-└── handler.rs       # Command handling and OBS API calls
-```
+## Architecture Patterns
+
+### Command Handler Pattern
+- All OBS operations implement `CommandHandler` trait in `src/handlers/mod.rs`
+- Trait provides `execute()` and `description()` methods for consistent interface
+- Handlers are boxed and dispatched in `src/handler.rs`
+
+### Connection Management
+- Retry logic with configurable timeouts in `src/connection.rs`
+- Connection health checks before command execution in `src/handler.rs`
+- Support for both CLI args and `OBS_WEBSOCKET_URL` environment variable
+
+### Error Handling
+- Comprehensive error types in `src/error.rs` using thiserror
+- Result type alias for consistent error handling
+- Detailed error messages with actionable guidance
+
+### CLI Design
+- Custom URL parsing for `obws://hostname:port/password` format in `src/cli.rs`
+- Subcommand structure for logical grouping (scenes, recording, streaming, etc.)
+- Duration parsing for media controls in `src/cli.rs`
 
 ## Development Commands
 ```bash
 # Build and run
 cargo run                    # Build and run locally
-cargo build --release        # Release build
+cargo build --release        # Release build with optimizations
 
 # Code quality
 cargo fmt                    # Format code
@@ -28,55 +44,19 @@ cargo test                   # Run tests
 
 # Dependency management
 cargo update                 # Update dependencies
-cargo outdated               # Check for outdated dependencies
 cargo audit                  # Security audit
 cargo deny check             # License and dependency checks
 
-
 # Installation
 cargo install --path .       # Install locally
 ```
 
-## Key Components
-
-### CLI Structure (cli.rs)
-- Defines all OBS commands using clap subcommands
-- Handles WebSocket URL parsing and validation
-- Supports environment variable `OBS_WEBSOCKET_URL` for connection
-
-### Command Handler (handler.rs)
-- Implements all OBS operations via obws client
-- Handles scenes, recording, streaming, audio, filters, and more
-- Provides error handling and user feedback
-
-### Main Entry (main.rs)
-- Establishes WebSocket connection to OBS
-- Supports both CLI flag and environment variable configuration
-- Routes commands to handler
-
-## Common Patterns
-- Async/await for all WebSocket operations
-- Result-based error handling throughout
-- Subcommand structure for logical command grouping
-- Environment variable fallback for configuration
-
-## GitHub Workflows
-
-### Development Workflow (rust.yml)
-- **Triggers**: Push/PR to main/master branch
-- **Platforms**: Ubuntu, macOS, Windows
-- **Jobs**: Testing, code coverage, performance benchmarks
-
-### Security & Quality (security.yml)
-- **Triggers**: Push/PR to main/master + daily schedule
-- **Jobs**: Security audit, code quality, dependency analysis, secrets scan
-
-### Release Automation (release.yml)
-- **Triggers**: Git tags starting with `v*`
-- **Features**: Multi-platform builds, automatic changelog, GitHub releases
+## Release Configuration
+- Optimized release profile in `Cargo.toml` with size optimizations
+- LTO enabled, single codegen unit, panic=abort for smaller binaries
+- Strip symbols for reduced binary size
 
-### Branch Protection
-Configure `main`/`master` branch to require:
-- Rust workflow checks
-- Security workflow checks
-- Code quality validation
+## Security & Quality
+- License compliance via deny.toml
+- GitHub workflows for automated testing and security scanning
+- Branch protection requiring workflow checks

AGENTS.md

@@ -17,6 +17,7 @@ clap = { version = "4.5", features = ["derive"] }
 url = "2.5"
 time = "0.3.37"
 thiserror = "2.0"
+async-trait = "0.1"
 
 [profile.release]
 opt-level = "z"

Cargo.lock

@@ -4,7 +4,7 @@ use std::str::FromStr;
 use url::Url;
 
 /// OBS WebSocket connection configuration.
-/// 
+///
 /// This struct represents the connection parameters for connecting
 /// to an OBS WebSocket server, typically parsed from a URL string.
 #[derive(Clone, Debug)]
@@ -114,42 +114,42 @@ pub enum SceneCollection {
 }
 
 /// Command-line interface for obs-cmd.
-/// 
+///
 /// This struct defines the main CLI interface using clap for parsing.
 /// It supports connecting to OBS WebSocket and executing various commands.
-/// 
+///
 /// # Examples
-/// 
+///
 /// ```bash
 /// # Get OBS version info
 /// obs-cmd info
-/// 
+///
 /// # Start recording
 /// obs-cmd recording start
-/// 
+///
 /// # Switch to a scene
 /// obs-cmd scene switch "Main Scene"
-/// 
+///
 /// # Connect to custom OBS WebSocket
 /// obs-cmd --websocket obsws://192.168.1.100:4455/password info
 /// ```
 #[derive(Parser)]
 #[clap(author, version, about, long_about = None)]
 pub struct Cli {
     /// OBS WebSocket connection URL.
-    /// 
+    ///
     /// If not provided, defaults to `obsws://localhost:4455/secret`.
     /// Can also be set via OBS_WEBSOCKET_URL environment variable.
     #[clap(short, long)]
     pub websocket: Option<ObsWebsocket>,
-    
+
     /// The command to execute on OBS.
     #[clap(subcommand)]
     pub command: Commands,
 }
 
 /// Available commands for controlling OBS.
-/// 
+///
 /// This enum represents all possible operations that can be performed
 /// on OBS Studio via the WebSocket interface.
 #[derive(Subcommand)]
@@ -257,23 +257,23 @@ pub enum MediaInput {
 }
 
 /// Parses duration strings in [hh:]mm:ss format.
-/// 
+///
 /// This function converts human-readable time strings into Duration objects.
 /// Supports both minute:second and hour:minute:second formats.
-/// 
+///
 /// # Examples
-/// 
+///
 /// * "0:00" -> 0 seconds
 /// * "01:00" -> 1 minute  
 /// * "1:00:00" -> 1 hour
 /// * "1:30:45" -> 1 hour, 30 minutes, 45 seconds
-/// 
+///
 /// # Arguments
-/// 
+///
 /// * `s` - The duration string to parse
-/// 
+///
 /// # Returns
-/// 
+///
 /// Returns a `time::Duration` on success, or an error string if format is invalid
 fn parse_duration(s: &str) -> Result<time::Duration, String> {
     let parts = s

Cargo.toml

@@ -1,10 +1,12 @@
+#![allow(clippy::redundant_closure)]
+
 use crate::error::{ObsCmdError, Result};
 use obws::Client;
 use std::time::Duration;
 use tokio::time::timeout;
 
 /// Configuration for OBS WebSocket connection attempts.
-/// 
+///
 /// This struct defines how connection attempts should be handled,
 /// including timeouts, retry limits, and delays between attempts.
 pub struct ConnectionConfig {
@@ -30,25 +32,25 @@ impl Default for ConnectionConfig {
 }
 
 /// Establishes a WebSocket connection to OBS with retry logic.
-/// 
+///
 /// This function attempts to connect to an OBS WebSocket server with the
 /// provided configuration. It will retry connection attempts according to
 /// the specified config and provide detailed error feedback.
-/// 
+///
 /// # Arguments
-/// 
+///
 /// * `hostname` - The OBS WebSocket server hostname or IP address
 /// * `port` - The port number where OBS WebSocket is listening
 /// * `password` - Optional password for OBS WebSocket authentication
 /// * `config` - Connection configuration including timeouts and retry settings
-/// 
+///
 /// # Returns
-/// 
+///
 /// Returns a connected `Client` instance on success, or an error if all
 /// connection attempts fail.
-/// 
+///
 /// # Examples
-/// 
+///
 /// ```rust
 /// let config = ConnectionConfig::default();
 /// let client = connect_with_retry(
@@ -100,31 +102,31 @@ pub async fn connect_with_retry(
         }
     }
 
-    Err(last_error.unwrap_or_else(|| {
-        ObsCmdError::AllConnectionAttemptsFailed {
+    Err(
+        last_error.unwrap_or_else(|| ObsCmdError::AllConnectionAttemptsFailed {
             attempts: config.max_retries,
-        }
-    }))
+        }),
+    )
 }
 
 /// Checks the health of an existing OBS WebSocket connection.
-/// 
+///
 /// This function verifies that the connection to OBS is still active
 /// and responsive by attempting to retrieve the OBS version.
-/// 
+///
 /// # Arguments
-/// 
+///
 /// * `client` - The OBS WebSocket client to check
-/// 
+///
 /// # Returns
-/// 
+///
 /// Returns `Ok(())` if the connection is healthy, or an error if the
 /// connection is unresponsive or broken.
 pub async fn check_connection_health(client: &Client) -> Result<()> {
     timeout(Duration::from_secs(5), client.general().version())
         .await
         .map_err(|_| ObsCmdError::ConnectionTimeout { timeout: 5 })?
-        .map_err(ObsCmdError::ConnectionError)?;
+        .map_err(|e| ObsCmdError::ConnectionError(e))?;
 
     Ok(())
 }