Merge pull request #471 from CortexLM/refactor/cortex-cli-production-quality

refactor(cortex-cli): add modular CLI structure and centralized utilities

Author: echobt

cortex-cli/src/cli/args.rs

@@ -0,0 +1,21 @@
+//! CLI argument parsing and command dispatch.
+//!
+//! This module provides the core CLI infrastructure:
+//! - Command-line argument definitions using clap
+//! - Version and help text formatting
+//! - Subcommand dispatch
+//!
+//! # Module Structure
+//!
+//! - `args` - Command-line argument structures
+//! - `styles` - ANSI styling for help output
+//! - `handlers` - Command execution handlers
+
+pub mod args;
+pub mod handlers;
+pub mod styles;
+
+// Re-export main types
+pub use args::{Cli, ColorMode, Commands, InteractiveArgs, LogLevel};
+pub use handlers::dispatch_command;
+pub use styles::{AFTER_HELP, BEFORE_HELP, get_styles};

cortex-cli/src/cli/handlers.rs

@@ -0,0 +1,81 @@
+//! CLI styling and formatting.
+//!
+//! Defines ANSI colors and formatting for the CLI help output.
+
+use clap::builder::styling::{AnsiColor, Effects, Styles};
+
+/// Cortex CLI styled help theme.
+///
+/// Uses a modern color scheme with cyan accents for a beautiful terminal experience.
+pub fn get_styles() -> Styles {
+    Styles::styled()
+        // Headers (USAGE, COMMANDS, OPTIONS) - Bold cyan
+        .header(AnsiColor::Cyan.on_default() | Effects::BOLD)
+        // Usage line - Green
+        .usage(AnsiColor::Green.on_default() | Effects::BOLD)
+        // Literals (command names, flag names) - Bold green
+        .literal(AnsiColor::Green.on_default() | Effects::BOLD)
+        // Placeholders (<VALUE>, [ARGS]) - Yellow
+        .placeholder(AnsiColor::Yellow.on_default())
+        // Errors - Bold red
+        .error(AnsiColor::Red.on_default() | Effects::BOLD)
+        // Valid values - Cyan
+        .valid(AnsiColor::Cyan.on_default())
+        // Invalid values - Yellow
+        .invalid(AnsiColor::Yellow.on_default())
+}
+
+/// After-help section with environment variables documentation.
+pub const AFTER_HELP: &str = color_print::cstr!(
+    r#"
+<cyan,bold>ENVIRONMENT VARIABLES:</>
+    <green,bold>CORTEX_HOME</>          Override config directory (default: ~/.config/cortex)
+    <green,bold>CORTEX_API_KEY</>       API key (alternative to --with-api-key)
+    <green,bold>CORTEX_MODEL</>         Default model (alternative to --model)
+    <green,bold>CORTEX_LOG_LEVEL</>     Log verbosity (error, warn, info, debug, trace)
+    <green,bold>NO_COLOR</>             Disable colored output (set to '1' or 'true')
+    <green,bold>VISUAL</>               Editor for /edit command (fallback: EDITOR)
+    <green,bold>EDITOR</>               Fallback editor if VISUAL is not set
+
+<cyan,bold>PATHS:</>
+    <green,bold>Config file</>   ~/.config/cortex/config.toml
+    <green,bold>Sessions</>      ~/.local/share/cortex/sessions/
+    <green,bold>Logs</>          ~/.cache/cortex/logs/
+    <green,bold>Agents</>        ~/.cortex/agents/ (personal), .cortex/agents/ (project)
+
+<cyan,bold>QUICK START:</>
+    <yellow>cortex</>                         Start interactive TUI
+    <yellow>cortex</> <dim>"fix the bug"</>          Start TUI with initial prompt
+    <yellow>cortex run</> <dim>"explain this"</>     Non-interactive single request
+    <yellow>cortex exec</> <dim>"run tests"</>       Headless execution for CI/CD
+    <yellow>cortex resume --last</>           Continue most recent session
+
+<cyan,bold>LEARN MORE:</>
+    Documentation:   <blue,underline>https://docs.cortex.foundation</>
+    Report issues:   <blue,underline>https://github.com/CortexLM/cortex-cli/issues</>
+"#
+);
+
+/// Before-help section with ASCII art banner.
+pub const BEFORE_HELP: &str = color_print::cstr!(
+    r#"
+<cyan,bold>   ██████╗ ██████╗ ██████╗ ████████╗███████╗██╗  ██╗</>
+<cyan,bold>  ██╔════╝██╔═══██╗██╔══██╗╚══██╔══╝██╔════╝╚██╗██╔╝</>
+<cyan,bold>  ██║     ██║   ██║██████╔╝   ██║   █████╗   ╚███╔╝ </>
+<cyan,bold>  ██║     ██║   ██║██╔══██╗   ██║   ██╔══╝   ██╔██╗ </>
+<cyan,bold>  ╚██████╗╚██████╔╝██║  ██║   ██║   ███████╗██╔╝ ██╗</>
+<cyan,bold>   ╚═════╝ ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝</>
+<dim>                 AI-Powered Coding Agent</>
+"#
+);
+
+/// Command category display names for styled help output.
+pub mod categories {
+    pub const EXECUTION: &str = "Execution Modes";
+    pub const SESSION: &str = "Session Management";
+    pub const AUTH: &str = "Authentication";
+    pub const EXTENSION: &str = "Extensibility";
+    pub const CONFIG: &str = "Configuration";
+    pub const UTILITIES: &str = "Utilities";
+    pub const ADVANCED: &str = "Advanced";
+}

cortex-cli/src/cli/mod.rs

@@ -23,14 +23,18 @@
 //!
 //! The crate is organized into the following structure:
 //!
-//! - `utils/` - Shared utilities (validation, paths, clipboard, terminal)
+//! - `cli/` - CLI argument parsing and command dispatch
+//! - `utils/` - Shared utilities (validation, paths, clipboard, terminal, model, etc.)
 //! - 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 CLI module for command-line parsing
+pub mod cli;
+
 // Re-export the utilities module for shared functionality
 pub mod utils;