refactor(cortex-cli): centralize utilities into modular structure (#465)

This refactoring introduces a new utils module hierarchy that centralizes
shared functionality across the CLI commands:

- utils/mod.rs: Module exports and organization
- utils/clipboard.rs: Cross-platform clipboard read/write operations
- utils/paths.rs: Path manipulation, validation, and security checks
- utils/session.rs: Unified session ID resolution (UUID and short IDs)
- utils/terminal.rs: Terminal color detection, formatting, ANSI codes
- utils/validation.rs: URL, server name, env var, and model validation

Benefits:
- DRY: Eliminates duplicated validation logic across mcp_cmd, run_cmd, etc.
- Type safety: SessionIdError enum for better error handling
- Security: Centralized path traversal and URL validation
- Modularity: Clean separation of concerns for easier maintenance

This is the first phase of the cortex-cli refactoring effort. Future
work will update existing commands to use these shared utilities.

Co-authored-by: Droid Agent <droid@factory.ai>

Author: echobt

Cargo.lock

@@ -63,6 +63,9 @@ serde = { workspace = true }
 ctor = "0.5"
 base64 = { workspace = true }
 
+# For error types in utilities
+thiserror = { workspace = true }
+
 # For upgrade command (HTTP requests) and scrape command (cookie support)
 reqwest = { workspace = true, features = ["json", "cookies"] }
 

cortex-cli/Cargo.toml

@@ -18,10 +18,22 @@
 //! - WSL path handling
 //! - Terminal cleanup for graceful shutdown
 //! - SIGTERM handling for graceful process termination
+//!
+//! # Module Organization
+//!
+//! The crate is organized into the following structure:
+//!
+//! - `utils/` - Shared utilities (validation, paths, clipboard, terminal)
+//! - Command modules - Individual CLI commands (`*_cmd.rs`)
+//! - `styled_output` - Themed terminal output formatting
+//! - `login` - Authentication management
 
 use std::panic;
 use std::sync::atomic::{AtomicBool, AtomicI32, Ordering};
 
+// Re-export the utilities module for shared functionality
+pub mod utils;
+
 static CLEANUP_REGISTERED: AtomicBool = AtomicBool::new(false);
 static PANIC_HOOK_INSTALLED: AtomicBool = AtomicBool::new(false);
 

cortex-cli/src/lib.rs

@@ -0,0 +1,153 @@
+//! Clipboard operations for the Cortex CLI.
+//!
+//! Provides cross-platform clipboard read/write functionality.
+
+use anyhow::{Context, Result, bail};
+use std::io::Write;
+use std::process::{Command, Stdio};
+
+/// Copy text to the system clipboard.
+///
+/// Uses platform-specific commands:
+/// - macOS: `pbcopy`
+/// - Linux: `xclip` or `xsel` (with X11 fallback)
+/// - Windows: `clip.exe`
+///
+/// # Arguments
+/// * `text` - The text to copy to clipboard
+///
+/// # Returns
+/// `Ok(())` on success, or an error if clipboard access failed.
+///
+/// # Example
+/// ```ignore
+/// copy_to_clipboard("Hello, world!")?;
+/// ```
+pub fn copy_to_clipboard(text: &str) -> Result<()> {
+    #[cfg(target_os = "macos")]
+    {
+        let mut child = Command::new("pbcopy")
+            .stdin(Stdio::piped())
+            .spawn()
+            .context("Failed to spawn pbcopy")?;
+
+        if let Some(ref mut stdin) = child.stdin {
+            stdin.write_all(text.as_bytes())?;
+        }
+        child.wait()?;
+        Ok(())
+    }
+
+    #[cfg(target_os = "linux")]
+    {
+        // Try xclip first, then xsel as fallback
+        let result = Command::new("xclip")
+            .args(["-selection", "clipboard"])
+            .stdin(Stdio::piped())
+            .spawn();
+
+        let mut child = match result {
+            Ok(c) => c,
+            Err(_) => Command::new("xsel")
+                .args(["--clipboard", "--input"])
+                .stdin(Stdio::piped())
+                .spawn()
+                .context("Failed to spawn clipboard command (tried xclip and xsel)")?,
+        };
+
+        if let Some(ref mut stdin) = child.stdin {
+            stdin.write_all(text.as_bytes())?;
+        }
+        child.wait()?;
+        Ok(())
+    }
+
+    #[cfg(target_os = "windows")]
+    {
+        let mut child = Command::new("clip")
+            .stdin(Stdio::piped())
+            .spawn()
+            .context("Failed to spawn clip.exe")?;
+
+        if let Some(ref mut stdin) = child.stdin {
+            stdin.write_all(text.as_bytes())?;
+        }
+        child.wait()?;
+        Ok(())
+    }
+
+    #[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
+    {
+        bail!("Clipboard not supported on this platform")
+    }
+}
+
+/// Read text from the system clipboard.
+///
+/// Uses platform-specific commands:
+/// - macOS: `pbpaste`
+/// - Linux: `xclip` or `xsel` (with X11 fallback)
+/// - Windows: `Get-Clipboard` via PowerShell
+///
+/// # Returns
+/// The clipboard content as a string, or an error if clipboard access failed.
+///
+/// # Example
+/// ```ignore
+/// let content = read_clipboard()?;
+/// println!("Clipboard: {}", content);
+/// ```
+pub fn read_clipboard() -> Result<String> {
+    #[cfg(target_os = "macos")]
+    {
+        let output = Command::new("pbpaste").output()?;
+        if output.status.success() {
+            Ok(String::from_utf8_lossy(&output.stdout).to_string())
+        } else {
+            bail!("Failed to read clipboard")
+        }
+    }
+
+    #[cfg(target_os = "linux")]
+    {
+        // Try xclip first, then xsel
+        let output = Command::new("xclip")
+            .args(["-selection", "clipboard", "-o"])
+            .output()
+            .or_else(|_| {
+                Command::new("xsel")
+                    .args(["--clipboard", "--output"])
+                    .output()
+            })?;
+
+        if output.status.success() {
+            Ok(String::from_utf8_lossy(&output.stdout).to_string())
+        } else {
+            bail!("Failed to read clipboard (tried xclip and xsel)")
+        }
+    }
+
+    #[cfg(target_os = "windows")]
+    {
+        let output = Command::new("powershell")
+            .args(["-Command", "Get-Clipboard"])
+            .output()?;
+
+        if output.status.success() {
+            Ok(String::from_utf8_lossy(&output.stdout).to_string())
+        } else {
+            bail!("Failed to read clipboard")
+        }
+    }
+
+    #[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
+    {
+        bail!("Clipboard not supported on this platform")
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    // Clipboard tests are difficult to run in CI environments
+    // as they require a display server or clipboard service
+}

cortex-cli/src/utils/clipboard.rs

@@ -0,0 +1,24 @@
+//! Shared utilities for the Cortex CLI.
+//!
+//! This module centralizes common functionality used across multiple CLI commands:
+//! - Session ID resolution and validation
+//! - URL validation and sanitization  
+//! - File validation and security checks
+//! - Clipboard operations
+//! - Path validation utilities
+//! - Terminal color detection
+
+pub mod clipboard;
+pub mod paths;
+pub mod session;
+pub mod terminal;
+pub mod validation;
+
+pub use clipboard::{copy_to_clipboard, read_clipboard};
+pub use paths::{expand_tilde, get_cortex_home, validate_path_safety};
+pub use session::{SessionIdError, resolve_session_id};
+pub use terminal::{TermColor, is_terminal_output, should_use_colors};
+pub use validation::{
+    validate_env_var_name, validate_env_var_value, validate_model_name, validate_server_name,
+    validate_url, validate_url_allowing_local,
+};