debug_cmd.rs

//! Debug commands for Cortex CLI.
//!
//! Provides diagnostic and debugging functionality:
//! - Configuration inspection
//! - File metadata and MIME detection
//! - LSP server status
//! - Ripgrep availability
//! - Skill validation
//! - Snapshot inspection
//! - Path inspection
//! - System information (OS, arch, shell, etc.)
//! - Wait for conditions

use anyhow::{Context, Result, bail};
use clap::Parser;
use cortex_engine::create_default_client;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::path::PathBuf;
use std::time::Duration;

use cortex_engine::list_sessions;
use cortex_engine::rollout::get_rollout_path;
use cortex_protocol::ConversationId;

/// Debug CLI for Cortex.
#[derive(Debug, Parser)]
pub struct DebugCli {
    #[command(subcommand)]
    pub subcommand: Option<DebugSubcommand>,
}

/// Debug subcommands.
#[derive(Debug, clap::Subcommand)]
pub enum DebugSubcommand {
    /// Show resolved configuration and config file locations.
    Config(ConfigArgs),

    /// Show file metadata, MIME type, and encoding.
    File(FileArgs),

    /// List and test LSP servers.
    Lsp(LspArgs),

    /// Check ripgrep availability and test search.
    Ripgrep(RipgrepArgs),

    /// Parse and validate a skill file.
    Skill(SkillArgs),

    /// Show snapshot status and diffs.
    Snapshot(SnapshotArgs),

    /// Show all Cortex paths.
    Paths(PathsArgs),

    /// Show system information (OS, architecture, shell, etc.) for bug reports.
    System(SystemArgs),

    /// Wait for a condition (useful for scripts).
    Wait(WaitArgs),
}

// =============================================================================
// Config subcommand
// =============================================================================

/// Arguments for config subcommand.
#[derive(Debug, Parser)]
pub struct ConfigArgs {
    /// Output as JSON.
    #[arg(long)]
    pub json: bool,

    /// Show environment variables related to Cortex.
    #[arg(long)]
    pub env: bool,

    /// Show diff between local project config and global config.
    #[arg(long)]
    pub diff: bool,
}

/// Config debug output.
#[derive(Debug, Serialize)]
struct ConfigDebugOutput {
    resolved: ResolvedConfig,
    locations: ConfigLocations,
    #[serde(skip_serializing_if = "Option::is_none")]
    environment: Option<HashMap<String, String>>,
}

/// Resolved configuration values.
#[derive(Debug, Serialize)]
struct ResolvedConfig {
    model: String,
    provider: String,
    cwd: PathBuf,
    cortex_home: PathBuf,
}

/// Config file locations.
#[derive(Debug, Serialize)]
struct ConfigLocations {
    global_config: PathBuf,
    global_config_exists: bool,
    local_config: Option<PathBuf>,
    local_config_exists: bool,
}

async fn run_config(args: ConfigArgs) -> Result<()> {
    let config = cortex_engine::Config::default();

    let global_config = config.cortex_home.join("config.toml");
    let local_config = std::env::current_dir()
        .ok()
        .map(|d| d.join(".cortex/config.toml"));

    let resolved = ResolvedConfig {
        model: config.model.clone(),
        provider: config.model_provider_id.clone(),
        cwd: config.cwd.clone(),
        cortex_home: config.cortex_home.clone(),
    };

    let locations = ConfigLocations {
        global_config_exists: global_config.exists(),
        global_config,
        local_config_exists: local_config.as_ref().is_some_and(|p| p.exists()),
        local_config,
    };

    let environment = if args.env {
        let mut env_vars = HashMap::new();
        // Cortex environment variables
        let cortex_vars = [
            "CORTEX_HOME",
            "CORTEX_MODEL",
            "CORTEX_PROVIDER",
            "CORTEX_API_KEY",
            "CORTEX_DEBUG",
            "CORTEX_LOG_LEVEL",
            "CORTEX_AUTH_TOKEN",
            "CORTEX_API_URL",
            // Standard environment variables
            "EDITOR",
            "VISUAL",
            "SHELL",
        ];
        for var in cortex_vars {
            if let Ok(val) = std::env::var(var) {
                // Mask sensitive values (API keys, secrets, tokens, passwords, credentials)
                let display_val = if is_sensitive_var_name(var) {
                    redact_sensitive_value(&val)
                } else {
                    val
                };
                env_vars.insert(var.to_string(), display_val);
            }
        }
        Some(env_vars)
    } else {
        None
    };

    let output = ConfigDebugOutput {
        resolved,
        locations,
        environment,
    };

    if args.json {
        println!("{}", serde_json::to_string_pretty(&output)?);
    } else {
        println!("Resolved Configuration");
        println!("{}", "=".repeat(50));
        println!("  Model:       {}", output.resolved.model);
        // Clarify that 'cortex' provider means requests go through Cortex backend
        let provider_desc = if output.resolved.provider == "cortex" {
            "cortex (routes to model's underlying provider)"
        } else {
            &output.resolved.provider
        };
        println!("  Provider:    {}", provider_desc);
        println!("  CWD:         {}", output.resolved.cwd.display());
        println!("  Cortex Home: {}", output.resolved.cortex_home.display());
        println!();

        println!("Config File Locations");
        println!("{}", "-".repeat(40));
        println!(
            "  Global: {} {}",
            output.locations.global_config.display(),
            if output.locations.global_config_exists {
                "(exists)"
            } else {
                "(not found)"
            }
        );
        if let Some(ref local) = output.locations.local_config {
            println!(
                "  Local:  {} {}",
                local.display(),
                if output.locations.local_config_exists {
                    "(exists)"
                } else {
                    "(not found)"
                }
            );
        }

        if let Some(ref env) = output.environment {
            println!();
            println!("Environment Variables");
            println!("{}", "-".repeat(40));
            if env.is_empty() {
                println!("  (no Cortex-related environment variables set)");
            } else {
                for (key, val) in env {
                    println!("  {key}={val}");
                }
            }
        }

        // Show hints about available options
        println!();
        println!("Tip: Use --json for machine-readable output, --env for environment variables.");
    }

    // Handle --diff flag: compare local and global configs
    if args.diff {
        println!();
        println!("Config Diff (Global vs Local)");
        println!("{}", "=".repeat(50));

        let global_path = config.cortex_home.join("config.toml");
        let local_path = std::env::current_dir()
            .ok()
            .map(|d| d.join(".cortex/config.toml"));

        let global_content = if global_path.exists() {
            std::fs::read_to_string(&global_path).ok()
        } else {
            None
        };

        let local_content = local_path.as_ref().and_then(|p| {
            if p.exists() {
                std::fs::read_to_string(p).ok()
            } else {
                None
            }
        });

        match (global_content.as_ref(), local_content.as_ref()) {
            (None, None) => {
                println!("  No config files found.");
            }
            (Some(global), None) => {
                println!("  Only global config exists.");
                if args.json {
                    let diff_output = serde_json::json!({
                        "global_only": true,
                        "local_only": false,
                        "differences": [],
                    });
                    println!("{}", serde_json::to_string_pretty(&diff_output)?);
                }
            }
            (None, Some(local)) => {
                println!("  Only local config exists.");
                if args.json {
                    let diff_output = serde_json::json!({
                        "global_only": false,
                        "local_only": true,
                        "differences": [],
                    });
                    println!("{}", serde_json::to_string_pretty(&diff_output)?);
                }
            }
            (Some(global), Some(local)) => {
                if global == local {
                    println!("  Configs are identical.");
                } else {
                    let diff = compute_config_diff(global, local);
                    if args.json {
                        println!("{}", serde_json::to_string_pretty(&diff)?);
                    } else {
                        println!();
                        if !diff.only_in_global.is_empty() {
                            println!("Lines only in global config:");
                            for line in &diff.only_in_global {
                                println!("  - {}", line);
                            }
                            println!();
                        }
                        if !diff.only_in_local.is_empty() {
                            println!("Lines only in local config:");
                            for line in &diff.only_in_local {
                                println!("  + {}", line);
                            }
                            println!();
                        }
                        if !diff.unified_diff.is_empty() {
                            println!("Unified diff:");
                            println!("{}", diff.unified_diff);
                        }
                    }
                }
            }
        }
    }

    Ok(())
}

/// Result of comparing two config files.
#[derive(Debug, Serialize)]
struct ConfigDiff {
    only_in_global: Vec<String>,
    only_in_local: Vec<String>,
    unified_diff: String,
}

/// Compute diff between two config file contents.
fn compute_config_diff(global: &str, local: &str) -> ConfigDiff {
    use std::collections::HashSet;

    let global_lines: HashSet<&str> = global.lines().filter(|l| !l.trim().is_empty()).collect();
    let local_lines: HashSet<&str> = local.lines().filter(|l| !l.trim().is_empty()).collect();

    let only_in_global: Vec<String> = global_lines
        .difference(&local_lines)
        .map(|s| s.to_string())
        .collect();
    let only_in_local: Vec<String> = local_lines
        .difference(&global_lines)
        .map(|s| s.to_string())
        .collect();

    // Generate a simple unified diff
    let unified_diff = generate_unified_diff(global, local);

    ConfigDiff {
        only_in_global,
        only_in_local,
        unified_diff,
    }
}

/// Generate a simple unified diff output.
fn generate_unified_diff(old_content: &str, new_content: &str) -> String {
    let old_lines: Vec<&str> = old_content.lines().collect();
    let new_lines: Vec<&str> = new_content.lines().collect();

    let mut diff_output = String::new();
    diff_output.push_str("--- global/config.toml\n");
    diff_output.push_str("+++ local/config.toml\n");

    // Simple line-by-line comparison (not a proper LCS diff, but useful for config files)
    let max_lines = old_lines.len().max(new_lines.len());
    let mut has_changes = false;

    for i in 0..max_lines {
        let old_line = old_lines.get(i).copied();
        let new_line = new_lines.get(i).copied();

        match (old_line, new_line) {
            (Some(o), Some(n)) if o == n => {
                // Lines are the same, show context
                diff_output.push_str(&format!(" {}\n", o));
            }
            (Some(o), Some(n)) => {
                // Lines differ
                has_changes = true;
                diff_output.push_str(&format!("-{}\n", o));
                diff_output.push_str(&format!("+{}\n", n));
            }
            (Some(o), None) => {
                // Line only in old
                has_changes = true;
                diff_output.push_str(&format!("-{}\n", o));
            }
            (None, Some(n)) => {
                // Line only in new
                has_changes = true;
                diff_output.push_str(&format!("+{}\n", n));
            }
            (None, None) => break,
        }
    }

    if !has_changes {
        String::new()
    } else {
        diff_output
    }
}

// =============================================================================
// File subcommand
// =============================================================================

/// Arguments for file subcommand.
#[derive(Debug, Parser)]
pub struct FileArgs {
    /// Path to the file to inspect.
    pub path: PathBuf,

    /// Output as JSON.
    #[arg(long)]
    pub json: bool,
}

/// File debug output.
#[derive(Debug, Serialize)]
struct FileDebugOutput {
    path: PathBuf,
    exists: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    metadata: Option<FileMetadata>,
    #[serde(skip_serializing_if = "Option::is_none")]
    mime_type: Option<String>,
    encoding: Option<String>,
    is_binary: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    error: Option<String>,
    /// Warning when the file appears to be actively modified
    #[serde(skip_serializing_if = "Option::is_none")]
    active_modification_warning: Option<String>,
}

/// File metadata.
#[derive(Debug, Serialize)]
struct FileMetadata {
    size: u64,
    /// For virtual filesystems (procfs, sysfs), stat() returns 0 but reading
    /// the file may return actual content. This field stores the actual
    /// content size when available.
    #[serde(skip_serializing_if = "Option::is_none")]
    actual_size: Option<u64>,
    /// Whether the file is on a virtual filesystem (procfs, sysfs, etc.)
    #[serde(skip_serializing_if = "Option::is_none")]
    is_virtual_fs: Option<bool>,
    is_file: bool,
    is_dir: bool,
    is_symlink: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    file_type: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    symlink_target: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    modified: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    created: Option<String>,
    readonly: bool,
}

async fn run_file(args: FileArgs) -> Result<()> {
    let path = if args.path.is_absolute() {
        args.path.clone()
    } else {
        std::env::current_dir()?.join(&args.path)
    };

    let exists = path.exists();

    // Detect special file types using stat() BEFORE attempting any reads
    // This prevents blocking on FIFOs, sockets, and other special files
    let special_file_type = if exists {
        detect_special_file_type(&path)
    } else {
        None
    };

    let (metadata, error) = if exists {
        match std::fs::metadata(&path) {
            Ok(meta) => {
                let modified = meta
                    .modified()
                    .ok()
                    .map(|t| chrono::DateTime::<chrono::Utc>::from(t).to_rfc3339());
                let created = meta
                    .created()
                    .ok()
                    .map(|t| chrono::DateTime::<chrono::Utc>::from(t).to_rfc3339());

                // Get symlink target if applicable
                let symlink_target = if meta.file_type().is_symlink() {
                    std::fs::read_link(&path)
                        .ok()
                        .map(|p| p.to_string_lossy().to_string())
                } else {
                    None
                };

                // Check if the current user can actually write to the file
                // This is more accurate than just checking permission bits
                // Skip this check for special files (FIFOs, etc.) to avoid blocking
                let readonly = if special_file_type.is_some() {
                    false // Don't check writability for special files
                } else {
                    !is_writable_by_current_user(&path)
                };

                // Check if this is a virtual filesystem (procfs, sysfs, etc.)
                // These report size=0 in stat() but may have actual content
                let is_virtual_fs = is_virtual_filesystem(&path);
                let stat_size = meta.len();

                // For virtual filesystem files that report 0 size, try to read actual content size
                let actual_size = if is_virtual_fs && stat_size == 0 && meta.is_file() {
                    // Try to read the file to get actual content size
                    // Limit read to 1MB to avoid hanging on infinite streams
                    match std::fs::read(&path) {
                        Ok(content) if !content.is_empty() => Some(content.len() as u64),
                        _ => None,
                    }
                } else {
                    None
                };

                (
                    Some(FileMetadata {
                        size: stat_size,
                        actual_size,
                        is_virtual_fs: if is_virtual_fs { Some(true) } else { None },
                        is_file: meta.is_file(),
                        is_dir: meta.is_dir(),
                        is_symlink: meta.file_type().is_symlink(),
                        file_type: special_file_type.clone(),
                        symlink_target,
                        modified,
                        created,
                        readonly,
                    }),
                    None,
                )
            }
            Err(e) => (None, Some(e.to_string())),
        }
    } else {
        (None, Some("File does not exist".to_string()))
    };

    // Detect MIME type from extension - skip for special files
    let mime_type = if exists && path.is_file() && special_file_type.is_none() {
        path.extension()
            .and_then(|ext| ext.to_str())
            .map(|ext| guess_mime_type(ext))
    } else {
        None
    };

    // Detect encoding and binary status - SKIP for special files to avoid blocking
    let (encoding, is_binary) = if exists && path.is_file() && special_file_type.is_none() {
        detect_encoding_and_binary(&path)
    } else {
        (None, None)
    };

    // Check if the file appears to be actively modified by comparing
    // metadata from two reads with a small delay
    let active_modification_warning = if exists && path.is_file() {
        // Get initial size
        let initial_size = std::fs::metadata(&path).ok().map(|m| m.len());
        // Brief delay to detect active writes
        std::thread::sleep(std::time::Duration::from_millis(50));
        // Get size again
        let final_size = std::fs::metadata(&path).ok().map(|m| m.len());

        match (initial_size, final_size) {
            (Some(s1), Some(s2)) if s1 != s2 => Some(format!(
                "File appears to be actively modified (size changed from {} to {} bytes during read). \
                     Content may be inconsistent.",
                s1, s2
            )),
            _ => None,
        }
    } else {
        None
    };

    let output = FileDebugOutput {
        path,
        exists,
        metadata,
        mime_type,
        encoding,
        is_binary,
        error,
        active_modification_warning,
    };

    if args.json {
        println!("{}", serde_json::to_string_pretty(&output)?);
    } else {
        println!("File Debug Info");
        println!("{}", "=".repeat(50));
        println!("  Path:   {}", output.path.display());
        println!("  Exists: {}", output.exists);

        if let Some(ref meta) = output.metadata {
            println!();
            println!("Metadata");
            println!("{}", "-".repeat(40));
            // Handle virtual filesystem files that report 0 size (#2829)
            if meta.is_virtual_fs.unwrap_or(false) {
                if let Some(actual) = meta.actual_size {
                    println!(
                        "  Size:     {} (stat reports 0, virtual filesystem)",
                        format_size(actual)
                    );
                } else {
                    println!("  Size:     unknown (virtual filesystem)");
                }
            } else {
                println!("  Size:     {}", format_size(meta.size));
            }

            // Display file type, including special types like FIFO, socket, etc.
            let type_str = if let Some(ref special_type) = meta.file_type {
                special_type.as_str()
            } else if meta.is_file {
                "file"
            } else if meta.is_dir {
                "directory"
            } else if meta.is_symlink {
                "symlink"
            } else {
                "unknown"
            };
            println!("  Type:     {}", type_str);

            if meta.is_virtual_fs.unwrap_or(false) {
                println!("  Virtual:  yes (procfs/sysfs/etc)");
            }
            println!("  Readonly: {}", meta.readonly);
            if let Some(ref modified) = meta.modified {
                println!("  Modified: {}", modified);
            }
            if let Some(ref created) = meta.created {
                println!("  Created:  {}", created);
            }
        }

        if let Some(ref mime) = output.mime_type {
            println!();
            println!("Content Detection");
            println!("{}", "-".repeat(40));
            println!("  MIME Type: {}", mime);
        }

        if let Some(ref enc) = output.encoding {
            println!("  Encoding:  {}", enc);
        }

        if let Some(binary) = output.is_binary {
            println!("  Binary:    {}", binary);
        }

        if let Some(ref err) = output.error {
            println!();
            println!("Error: {}", err);
        }

        if let Some(ref warning) = output.active_modification_warning {
            println!();
            println!("Warning: {}", warning);
        }
    }

    Ok(())
}

/// Guess MIME type from file extension.
fn guess_mime_type(ext: &str) -> String {
    match ext.to_lowercase().as_str() {
        // Text
        "txt" => "text/plain",
        "md" | "markdown" => "text/markdown",
        "html" | "htm" => "text/html",
        "css" => "text/css",
        "csv" => "text/csv",
        "xml" => "text/xml",
        // Code
        "rs" => "text/x-rust",
        "js" => "text/javascript",
        "ts" => "text/typescript",
        "jsx" => "text/jsx",
        "tsx" => "text/tsx",
        "py" => "text/x-python",
        "rb" => "text/x-ruby",
        "go" => "text/x-go",
        "java" => "text/x-java",
        "c" | "h" => "text/x-c",
        "cpp" | "hpp" | "cc" => "text/x-c++",
        "cs" => "text/x-csharp",
        "swift" => "text/x-swift",
        "kt" => "text/x-kotlin",
        "sh" | "bash" => "text/x-shellscript",
        "ps1" => "text/x-powershell",
        "sql" => "text/x-sql",
        // Config
        "json" => "application/json",
        "yaml" | "yml" => "text/yaml",
        "toml" => "text/toml",
        "ini" | "cfg" => "text/plain",
        // Images
        "png" => "image/png",
        "jpg" | "jpeg" => "image/jpeg",
        "gif" => "image/gif",
        "svg" => "image/svg+xml",
        "webp" => "image/webp",
        "ico" => "image/x-icon",
        // Documents
        "pdf" => "application/pdf",
        "doc" => "application/msword",
        "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        // Archives
        "zip" => "application/zip",
        "tar" => "application/x-tar",
        "gz" => "application/gzip",
        // Executables
        "exe" => "application/x-msdownload",
        "dll" => "application/x-msdownload",
        "so" => "application/x-sharedlib",
        "dylib" => "application/x-mach-binary",
        // Default
        _ => "application/octet-stream",
    }
    .to_string()
}

/// Check if the current user can write to the file.
///
/// This function attempts to open the file for writing to determine
/// if the current user has write access. This is more accurate than
/// checking permission bits, as it accounts for ownership, group
/// membership, and ACLs.
fn is_writable_by_current_user(path: &std::path::Path) -> bool {
    std::fs::OpenOptions::new().write(true).open(path).is_ok()
}

/// Detect special file types (FIFO, socket, block device, char device).
/// Uses stat() to determine the file type WITHOUT opening/reading the file,
/// which would block indefinitely for FIFOs and sockets.
fn detect_special_file_type(path: &std::path::Path) -> Option<String> {
    #[cfg(unix)]
    {
        use std::os::unix::fs::FileTypeExt;
        if let Ok(meta) = std::fs::metadata(path) {
            let file_type = meta.file_type();
            if file_type.is_fifo() {
                return Some("fifo".to_string());
            }
            if file_type.is_socket() {
                return Some("socket".to_string());
            }
            if file_type.is_block_device() {
                return Some("block_device".to_string());
            }
            if file_type.is_char_device() {
                return Some("char_device".to_string());
            }
        }
        None
    }

    #[cfg(not(unix))]
    {
        // On non-Unix systems, special file types are not common
        let _ = path;
        None
    }
}

/// Check if the path is on a virtual filesystem like procfs or sysfs.
/// These filesystems report size=0 in stat() for files that have actual content. (#2829)
#[cfg(target_os = "linux")]
fn is_virtual_filesystem(path: &std::path::Path) -> bool {
    let path_str = path.to_string_lossy();
    path_str.starts_with("/proc/")
        || path_str.starts_with("/sys/")
        || path_str.starts_with("/dev/")
        || path_str == "/proc"
        || path_str == "/sys"
        || path_str == "/dev"
}

/// Check if the path is on a virtual filesystem like procfs or sysfs.
/// On non-Linux systems, return false as these filesystems are Linux-specific.
#[cfg(not(target_os = "linux"))]
fn is_virtual_filesystem(_path: &std::path::Path) -> bool {
    false
}

/// Detect encoding and binary status.
fn detect_encoding_and_binary(path: &PathBuf) -> (Option<String>, Option<bool>) {
    // Read first 8KB to check for binary content
    let Ok(file) = std::fs::File::open(path) else {
        return (None, None);
    };

    use std::io::Read;
    let mut reader = std::io::BufReader::new(file);
    let mut buffer = [0u8; 8192];
    let Ok(bytes_read) = reader.read(&mut buffer) else {
        return (None, None);
    };

    let sample = &buffer[..bytes_read];

    // Check for null bytes (common in binary files)
    let has_null = sample.contains(&0);

    // Check for UTF-8 BOM
    let has_utf8_bom = sample.starts_with(&[0xEF, 0xBB, 0xBF]);

    // Check for UTF-16 BOM
    let has_utf16_le_bom = sample.starts_with(&[0xFF, 0xFE]);
    let has_utf16_be_bom = sample.starts_with(&[0xFE, 0xFF]);

    let encoding = if has_utf8_bom {
        Some("UTF-8 (with BOM)".to_string())
    } else if has_utf16_le_bom {
        Some("UTF-16 LE".to_string())
    } else if has_utf16_be_bom {
        Some("UTF-16 BE".to_string())
    } else if !has_null && std::str::from_utf8(sample).is_ok() {
        Some("UTF-8".to_string())
    } else if has_null {
        Some("Binary".to_string())
    } else {
        Some("Unknown".to_string())
    };

    let is_binary = Some(has_null);

    (encoding, is_binary)
}

/// Format file size in human-readable format.
fn format_size(bytes: u64) -> String {
    const KB: u64 = 1024;
    const MB: u64 = KB * 1024;
    const GB: u64 = MB * 1024;

    if bytes >= GB {
        format!("{:.2} GB", bytes as f64 / GB as f64)
    } else if bytes >= MB {
        format!("{:.2} MB", bytes as f64 / MB as f64)
    } else if bytes >= KB {
        format!("{:.2} KB", bytes as f64 / KB as f64)
    } else {
        format!("{} B", bytes)
    }
}

// =============================================================================
// LSP subcommand
// =============================================================================

/// Arguments for lsp subcommand.
#[derive(Debug, Parser)]
pub struct LspArgs {
    /// Test a specific LSP server.
    #[arg(long)]
    pub server: Option<String>,

    /// Filter by programming language (e.g., python, rust, go).
    #[arg(long, short = 'l')]
    pub language: Option<String>,

    /// Test LSP connection for a specific file.
    #[arg(long)]
    pub file: Option<PathBuf>,

    /// Output as JSON.
    #[arg(long)]
    pub json: bool,
}

/// LSP server info.
#[derive(Debug, Serialize)]
struct LspServerInfo {
    name: String,
    language: String,
    command: String,
    installed: bool,
    version: Option<String>,
    path: Option<PathBuf>,
}

/// LSP debug output.
#[derive(Debug, Serialize)]
struct LspDebugOutput {
    servers: Vec<LspServerInfo>,
    #[serde(skip_serializing_if = "Option::is_none")]
    connection_test: Option<LspConnectionTest>,
}

/// LSP connection test result.
#[derive(Debug, Serialize)]
struct LspConnectionTest {
    server: String,
    success: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    latency_ms: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    error: Option<String>,
}

async fn run_lsp(args: LspArgs) -> Result<()> {
    // Known LSP servers
    let known_servers = vec![
        ("rust-analyzer", "Rust", "rust-analyzer"),
        (
            "typescript-language-server",
            "TypeScript/JavaScript",
            "typescript-language-server",
        ),
        ("pyright", "Python", "pyright-langserver"),
        ("pylsp", "Python", "pylsp"),
        ("gopls", "Go", "gopls"),
        ("clangd", "C/C++", "clangd"),
        ("lua-language-server", "Lua", "lua-language-server"),
        ("marksman", "Markdown", "marksman"),
        ("yaml-language-server", "YAML", "yaml-language-server"),
        (
            "vscode-json-language-server",
            "JSON",
            "vscode-json-language-server",
        ),
        ("bash-language-server", "Bash", "bash-language-server"),
        ("taplo", "TOML", "taplo"),
        ("zls", "Zig", "zls"),
    ];

    let mut servers = Vec::new();

    for (name, language, command) in known_servers {
        let (installed, path, version) = check_command_installed(command).await;
        servers.push(LspServerInfo {
            name: name.to_string(),
            language: language.to_string(),
            command: command.to_string(),
            installed,
            version,
            path,
        });
    }

    // Filter if specific server requested
    if let Some(ref server_name) = args.server {
        servers.retain(|s| s.name.to_lowercase().contains(&server_name.to_lowercase()));
    }

    // Filter by language if specified
    if let Some(ref lang) = args.language {
        servers.retain(|s| s.language.to_lowercase().contains(&lang.to_lowercase()));
    }

    // Connection test placeholder (actual implementation would require LSP client)
    let connection_test = if args.server.is_some() || args.file.is_some() {
        let server = args.server.as_deref().unwrap_or("auto-detect");
        Some(LspConnectionTest {
            server: server.to_string(),
            success: false,
            latency_ms: None,
            error: Some("LSP connection testing not yet implemented".to_string()),
        })
    } else {
        None
    };

    let output = LspDebugOutput {
        servers,
        connection_test,
    };

    if args.json {
        println!("{}", serde_json::to_string_pretty(&output)?);
    } else {
        println!("LSP Servers");
        println!("{}", "=".repeat(60));
        println!("{:<30} {:<15} {:<10}", "Server", "Language", "Status");
        println!("{}", "-".repeat(60));

        for server in &output.servers {
            let status = if server.installed {
                "installed"
            } else {
                "not found"
            };
            println!("{:<30} {:<15} {:<10}", server.name, server.language, status);
            if let Some(ref path) = server.path {
                println!("    Path: {}", path.display());
            }
            if let Some(ref version) = server.version {
                println!("    Version: {}", version);
            }
        }

        if let Some(ref test) = output.connection_test {
            println!();
            println!("Connection Test: {}", test.server);
            println!("{}", "-".repeat(40));
            println!("  Success: {}", test.success);
            if let Some(latency) = test.latency_ms {
                println!("  Latency: {}ms", latency);
            }
            if let Some(ref error) = test.error {
                println!("  Error: {}", error);
            }
        }
    }

    Ok(())
}

/// Check if a command is installed and get its path/version.
async fn check_command_installed(command: &str) -> (bool, Option<PathBuf>, Option<String>) {
    #[cfg(windows)]
    let which_cmd = "where";
    #[cfg(not(windows))]
    let which_cmd = "which";

    let output = tokio::process::Command::new(which_cmd)
        .arg(command)
        .output()
        .await;

    match output {
        Ok(out) if out.status.success() => {
            let path_str = String::from_utf8_lossy(&out.stdout);
            let path = path_str.lines().next().map(|s| PathBuf::from(s.trim()));

            // Try to get version
            let version = tokio::process::Command::new(command)
                .arg("--version")
                .output()
                .await
                .ok()
                .and_then(|v| {
                    if v.status.success() {
                        let ver = String::from_utf8_lossy(&v.stdout);
                        ver.lines().next().map(|s| s.trim().to_string())
                    } else {
                        None
                    }
                });

            (true, path, version)
        }
        _ => (false, None, None),
    }
}

// =============================================================================
// Ripgrep subcommand
// =============================================================================

/// Arguments for ripgrep subcommand.
#[derive(Debug, Parser)]
pub struct RipgrepArgs {
    /// Test search with a pattern.
    #[arg(long)]
    pub test: Option<String>,

    /// Directory to search in for test.
    #[arg(long)]
    pub dir: Option<PathBuf>,

    /// Offer to install ripgrep if not found.
    #[arg(long)]
    pub install: bool,

    /// Output as JSON.
    #[arg(long)]
    pub json: bool,
}

/// Ripgrep debug output.
#[derive(Debug, Serialize)]
struct RipgrepDebugOutput {
    available: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    version: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    path: Option<PathBuf>,
    #[serde(skip_serializing_if = "Option::is_none")]
    searched_paths: Option<Vec<PathBuf>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    test_result: Option<RipgrepTestResult>,
}

/// Ripgrep test result.
#[derive(Debug, Serialize)]
struct RipgrepTestResult {
    pattern: String,
    directory: PathBuf,
    matches_found: usize,
    duration_ms: u64,
    #[serde(skip_serializing_if = "Option::is_none")]
    error: Option<String>,
}

/// Get the directories in the PATH environment variable.
fn get_path_directories() -> Vec<PathBuf> {
    std::env::var_os("PATH")
        .map(|path| std::env::split_paths(&path).collect())
        .unwrap_or_default()
}

/// Attempt to install ripgrep using the system package manager.
async fn install_ripgrep() -> Result<()> {
    #[cfg(target_os = "macos")]
    {
        // Try Homebrew first
        let output = tokio::process::Command::new("brew")
            .args(["install", "ripgrep"])
            .status()
            .await;

        match output {
            Ok(status) if status.success() => {
                println!("ripgrep installed successfully via Homebrew!");
                return Ok(());
            }
            _ => {
                bail!("Failed to install via Homebrew. Is Homebrew installed?");
            }
        }
    }

    #[cfg(target_os = "linux")]
    {
        // Try apt first (Debian/Ubuntu)
        if tokio::process::Command::new("which")
            .arg("apt")
            .output()
            .await
            .map(|o| o.status.success())
            .unwrap_or(false)
        {
            let output = tokio::process::Command::new("sudo")
                .args(["apt", "install", "-y", "ripgrep"])
                .status()
                .await;

            match output {
                Ok(status) if status.success() => {
                    println!("ripgrep installed successfully via apt!");
                    return Ok(());
                }
                _ => {}
            }
        }

        // Try dnf (Fedora/RHEL)
        if tokio::process::Command::new("which")
            .arg("dnf")
            .output()
            .await
            .map(|o| o.status.success())
            .unwrap_or(false)
        {
            let output = tokio::process::Command::new("sudo")
                .args(["dnf", "install", "-y", "ripgrep"])
                .status()
                .await;

            match output {
                Ok(status) if status.success() => {
                    println!("ripgrep installed successfully via dnf!");
                    return Ok(());
                }
                _ => {}
            }
        }

        // Try pacman (Arch)
        if tokio::process::Command::new("which")
            .arg("pacman")
            .output()
            .await
            .map(|o| o.status.success())
            .unwrap_or(false)
        {
            let output = tokio::process::Command::new("sudo")
                .args(["pacman", "-S", "--noconfirm", "ripgrep"])
                .status()
                .await;

            match output {
                Ok(status) if status.success() => {
                    println!("ripgrep installed successfully via pacman!");
                    return Ok(());
                }
                _ => {}
            }
        }

        bail!("Could not detect a supported package manager (apt, dnf, pacman)");
    }

    #[cfg(target_os = "windows")]
    {
        // Try winget
        let output = tokio::process::Command::new("winget")
            .args(["install", "-e", "--id", "BurntSushi.ripgrep.MSVC"])
            .status()
            .await;

        match output {
            Ok(status) if status.success() => {
                println!("ripgrep installed successfully via winget!");
                return Ok(());
            }
            _ => {
                bail!("Failed to install via winget. Is winget available?");
            }
        }
    }

    #[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
    {
        bail!("Automatic installation not supported on this platform");
    }
}

async fn run_ripgrep(args: RipgrepArgs) -> Result<()> {
    let (available, path, version) = check_command_installed("rg").await;

    // When ripgrep is not found, include the searched paths for debugging
    let searched_paths = if !available {
        Some(get_path_directories())
    } else {
        None
    };

    let test_result = if let Some(pattern) = args.test {
        let dir = args
            .dir
            .unwrap_or_else(|| std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")));

        if available {
            let start = std::time::Instant::now();
            let output = tokio::process::Command::new("rg")
                .args(["--count", "--no-heading", &pattern])
                .current_dir(&dir)
                .output()
                .await;

            let duration_ms = start.elapsed().as_millis() as u64;

            match output {
                Ok(out) => {
                    let stdout = String::from_utf8_lossy(&out.stdout);
                    let matches: usize = stdout
                        .lines()
                        .filter_map(|line| {
                            line.rsplit(':')
                                .next()
                                .and_then(|n| n.parse::<usize>().ok())
                        })
                        .sum();

                    Some(RipgrepTestResult {
                        pattern,
                        directory: dir,
                        matches_found: matches,
                        duration_ms,
                        error: None,
                    })
                }
                Err(e) => Some(RipgrepTestResult {
                    pattern,
                    directory: dir,
                    matches_found: 0,
                    duration_ms,
                    error: Some(e.to_string()),
                }),
            }
        } else {
            Some(RipgrepTestResult {
                pattern,
                directory: dir,
                matches_found: 0,
                duration_ms: 0,
                error: Some("ripgrep not installed".to_string()),
            })
        }
    } else {
        None
    };

    let output = RipgrepDebugOutput {
        available,
        version,
        path,
        searched_paths,
        test_result,
    };

    if args.json {
        println!("{}", serde_json::to_string_pretty(&output)?);
    } else {
        println!("Ripgrep Status");
        println!("{}", "=".repeat(50));
        println!(
            "  Available: {}",
            if output.available { "yes" } else { "no" }
        );
        if let Some(ref path) = output.path {
            println!("  Path:      {}", path.display());
        }
        if let Some(ref version) = output.version {
            println!("  Version:   {}", version);
        }

        if let Some(ref test) = output.test_result {
            println!();
            println!("Search Test");
            println!("{}", "-".repeat(40));
            println!("  Pattern:   {}", test.pattern);
            println!("  Directory: {}", test.directory.display());
            println!("  Matches:   {}", test.matches_found);
            println!("  Duration:  {}ms", test.duration_ms);
            if let Some(ref error) = test.error {
                println!("  Error:     {}", error);
            }
        }

        if !output.available {
            println!();
            if let Some(ref paths) = output.searched_paths {
                println!("Searched Paths");
                println!("{}", "-".repeat(40));
                if paths.is_empty() {
                    println!("  (PATH environment variable is empty or not set)");
                } else {
                    for p in paths {
                        println!("  {}", p.display());
                    }
                }
            }
            println!();
            println!("To install ripgrep:");
            println!("  macOS:   brew install ripgrep");
            println!("  Linux:   apt install ripgrep / dnf install ripgrep");
            println!("  Windows: winget install BurntSushi.ripgrep.MSVC");

            // Offer to install if --install flag was provided
            if args.install {
                println!();
                println!("Attempting to install ripgrep...");
                if let Err(e) = install_ripgrep().await {
                    eprintln!("Failed to install ripgrep: {e}");
                    eprintln!("Please install manually using the commands above.");
                }
            }
        }
    }

    Ok(())
}

// =============================================================================
// Skill subcommand
// =============================================================================

/// Arguments for skill subcommand.
#[derive(Debug, Parser)]
pub struct SkillArgs {
    /// Name or path of the skill to validate.
    pub name: String,

    /// Output as JSON.
    #[arg(long)]
    pub json: bool,
}

/// Skill debug output.
#[derive(Debug, Serialize)]
struct SkillDebugOutput {
    name: String,
    path: Option<PathBuf>,
    found: bool,
    valid: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    definition: Option<SkillDefinition>,
    errors: Vec<String>,
    warnings: Vec<String>,
}

/// Skill definition (simplified).
#[derive(Debug, Serialize, Deserialize)]
struct SkillDefinition {
    #[serde(default)]
    name: String,
    #[serde(default)]
    description: String,
    #[serde(default)]
    version: Option<String>,
    #[serde(default)]
    author: Option<String>,
    #[serde(default)]
    commands: Vec<SkillCommand>,
}

/// Skill command definition.
#[derive(Debug, Serialize, Deserialize)]
struct SkillCommand {
    name: String,
    #[serde(default)]
    description: Option<String>,
    #[serde(default)]
    command: Option<String>,
}

async fn run_skill(args: SkillArgs) -> Result<()> {
    let cortex_home = get_cortex_home();
    let skills_dir = cortex_home.join("skills");

    // Try to find the skill
    let skill_path = if PathBuf::from(&args.name).exists() {
        Some(PathBuf::from(&args.name))
    } else if skills_dir.join(&args.name).exists() {
        Some(skills_dir.join(&args.name))
    } else if skills_dir.join(format!("{}.yaml", &args.name)).exists() {
        Some(skills_dir.join(format!("{}.yaml", &args.name)))
    } else if skills_dir.join(format!("{}.yml", &args.name)).exists() {
        Some(skills_dir.join(format!("{}.yml", &args.name)))
    } else if skills_dir.join(format!("{}.toml", &args.name)).exists() {
        Some(skills_dir.join(format!("{}.toml", &args.name)))
    } else {
        None
    };

    let mut errors = Vec::new();
    let mut warnings = Vec::new();
    let mut definition = None;
    let mut valid = false;

    if let Some(ref path) = skill_path {
        if path.exists() {
            // Check if path is a directory - provide helpful error message
            if path.is_dir() {
                errors.push(format!(
                    "Path '{}' is a directory, not a file. Please provide a path to a skill file (e.g., skill.yaml or skill.toml).",
                    path.display()
                ));
            } else {
                match std::fs::read_to_string(path) {
                    Ok(content) => {
                        // Try YAML first, then TOML
                        let ext = path.extension().and_then(|e| e.to_str()).unwrap_or("");
                        let parse_result: Result<SkillDefinition, String> = match ext {
                            "yaml" | "yml" => {
                                serde_yaml::from_str(&content).map_err(|e| e.to_string())
                            }
                            "toml" => toml::from_str(&content).map_err(|e| e.to_string()),
                            _ => {
                                // Try YAML first, then TOML
                                serde_yaml::from_str(&content)
                                    .map_err(|e| e.to_string())
                                    .or_else(|_| {
                                        toml::from_str(&content).map_err(|e| e.to_string())
                                    })
                            }
                        };

                        match parse_result {
                            Ok(def) => {
                                // Validate the definition
                                if def.name.is_empty() {
                                    warnings.push("Skill name is empty".to_string());
                                }
                                if def.description.is_empty() {
                                    warnings.push("Skill description is empty".to_string());
                                }
                                if def.commands.is_empty() {
                                    warnings.push("Skill has no commands".to_string());
                                }
                                for cmd in &def.commands {
                                    if cmd.command.is_none() {
                                        warnings.push(format!(
                                            "Command '{}' has no command defined",
                                            cmd.name
                                        ));
                                    }
                                }
                                valid = errors.is_empty();
                                definition = Some(def);
                            }
                            Err(e) => {
                                errors.push(format!("Parse error: {}", e));
                            }
                        }
                    }
                    Err(e) => {
                        errors.push(format!("Read error: {}", e));
                    }
                }
            }
        }
    }

    let output = SkillDebugOutput {
        name: args.name.clone(),
        path: skill_path.clone(),
        found: skill_path.is_some(),
        valid,
        definition,
        errors,
        warnings,
    };

    if args.json {
        println!("{}", serde_json::to_string_pretty(&output)?);
    } else {
        println!("Skill Debug: {}", output.name);
        println!("{}", "=".repeat(50));
        println!("  Found: {}", output.found);
        if let Some(ref path) = output.path {
            println!("  Path:  {}", path.display());
        }
        println!("  Valid: {}", output.valid);

        if let Some(ref def) = output.definition {
            println!();
            println!("Definition");
            println!("{}", "-".repeat(40));
            println!("  Name:        {}", def.name);
            println!("  Description: {}", def.description);
            if let Some(ref version) = def.version {
                println!("  Version:     {}", version);
            }
            if let Some(ref author) = def.author {
                println!("  Author:      {}", author);
            }
            println!("  Commands:    {}", def.commands.len());
            for cmd in &def.commands {
                println!("    - {}", cmd.name);
            }
        }

        if !output.errors.is_empty() {
            println!();
            println!("Errors");
            println!("{}", "-".repeat(40));
            for error in &output.errors {
                println!("  \u{2717} {}", error);
            }
        }

        if !output.warnings.is_empty() {
            println!();
            println!("Warnings");
            println!("{}", "-".repeat(40));
            for warning in &output.warnings {
                println!("  \u{26A0} {}", warning);
            }
        }
    }

    Ok(())
}

// =============================================================================
// Snapshot subcommand
// =============================================================================

/// Arguments for snapshot subcommand.
#[derive(Debug, Parser)]
pub struct SnapshotArgs {
    /// Session ID to inspect snapshots for.
    #[arg(long)]
    pub session: Option<String>,

    /// Show diff between snapshots.
    #[arg(long)]
    pub diff: bool,

    /// Output as JSON.
    #[arg(long)]
    pub json: bool,
}

/// Snapshot debug output.
#[derive(Debug, Serialize)]
struct SnapshotDebugOutput {
    snapshots_dir: PathBuf,
    snapshots_dir_exists: bool,
    snapshot_count: usize,
    #[serde(skip_serializing_if = "Option::is_none")]
    session_snapshots: Option<Vec<SnapshotInfo>>,
    total_size_bytes: u64,
}

/// Snapshot info.
#[derive(Debug, Serialize)]
struct SnapshotInfo {
    id: String,
    timestamp: String,
    size_bytes: u64,
}

async fn run_snapshot(args: SnapshotArgs) -> Result<()> {
    let cortex_home = get_cortex_home();
    let snapshots_dir = cortex_home.join("snapshots");

    let snapshots_dir_exists = snapshots_dir.exists();
    let mut snapshot_count = 0;
    let mut total_size_bytes = 0u64;
    let mut session_snapshots = None;

    if snapshots_dir_exists {
        // Count all snapshots
        if let Ok(entries) = std::fs::read_dir(&snapshots_dir) {
            for entry in entries.flatten() {
                if entry.path().is_file() {
                    snapshot_count += 1;
                    if let Ok(meta) = entry.metadata() {
                        total_size_bytes += meta.len();
                    }
                }
            }
        }

        // Get session-specific snapshots
        if let Some(ref session_id) = args.session {
            // Validate session ID and check if session exists
            let conversation_id: ConversationId = match session_id.parse() {
                Ok(id) => id,
                Err(_) => {
                    // If parsing failed, check if it's a short ID (8 chars)
                    if session_id.len() == 8 {
                        // Try to find a session with matching prefix
                        let sessions = list_sessions(&cortex_home)?;
                        let matching: Vec<_> = sessions
                            .iter()
                            .filter(|s| s.id.starts_with(session_id))
                            .collect();

                        match matching.len() {
                            0 => bail!("No session found with ID prefix: {session_id}"),
                            1 => matching[0].id.parse().map_err(|_| {
                                anyhow::anyhow!("Internal error: invalid session ID format")
                            })?,
                            _ => bail!(
                                "Ambiguous session ID prefix '{}' matches {} sessions. Please provide more characters.",
                                session_id,
                                matching.len()
                            ),
                        }
                    } else {
                        bail!(
                            "Invalid session ID: {session_id}. Expected full UUID or 8-character prefix."
                        );
                    }
                }
            };

            // Check if session rollout file exists
            let rollout_path = get_rollout_path(&cortex_home, &conversation_id);
            if !rollout_path.exists() {
                bail!("Session not found: {session_id}");
            }

            // Session exists, now search for its snapshots
            let mut snapshots = Vec::new();
            let conversation_id_str = conversation_id.to_string();
            if let Ok(entries) = std::fs::read_dir(&snapshots_dir) {
                for entry in entries.flatten() {
                    let filename = entry.file_name().to_string_lossy().to_string();
                    // Match against the validated full conversation ID
                    if filename.contains(&conversation_id_str) {
                        if let Ok(meta) = entry.metadata() {
                            let modified = meta
                                .modified()
                                .ok()
                                .map(|t| chrono::DateTime::<chrono::Utc>::from(t).to_rfc3339())
                                .unwrap_or_else(|| "unknown".to_string());

                            snapshots.push(SnapshotInfo {
                                id: filename,
                                timestamp: modified,
                                size_bytes: meta.len(),
                            });
                        }
                    }
                }
            }
            snapshots.sort_by(|a, b| b.timestamp.cmp(&a.timestamp));
            session_snapshots = Some(snapshots);
        }
    }

    let output = SnapshotDebugOutput {
        snapshots_dir: snapshots_dir.clone(),
        snapshots_dir_exists,
        snapshot_count,
        session_snapshots,
        total_size_bytes,
    };

    if args.json {
        println!("{}", serde_json::to_string_pretty(&output)?);
    } else {
        println!("Snapshot Status");
        println!("{}", "=".repeat(50));
        println!("  Directory: {}", output.snapshots_dir.display());
        println!(
            "  Exists:    {}",
            if output.snapshots_dir_exists {
                "yes"
            } else {
                "no"
            }
        );
        println!("  Count:     {}", output.snapshot_count);
        println!("  Total Size: {}", format_size(output.total_size_bytes));

        // Provide guidance when snapshots directory doesn't exist
        if !output.snapshots_dir_exists {
            println!();
            println!("Note: Snapshots are created automatically during sessions when the agent");
            println!(
                "      makes changes to your workspace. Start a new session to create snapshots."
            );
        }

        if let Some(ref snapshots) = output.session_snapshots {
            println!();
            println!("Session Snapshots");
            println!("{}", "-".repeat(40));
            if snapshots.is_empty() {
                println!("  (no snapshots found for session)");
            } else {
                for snap in snapshots {
                    println!(
                        "  {} ({}) - {}",
                        snap.id,
                        format_size(snap.size_bytes),
                        snap.timestamp
                    );
                }
            }
        }

        if args.diff {
            println!();
            println!("Diff");
            println!("{}", "-".repeat(40));
            println!("  (snapshot diff not yet implemented)");
        }
    }

    Ok(())
}

// =============================================================================
// Paths subcommand
// =============================================================================

/// Arguments for paths subcommand.
#[derive(Debug, Parser)]
pub struct PathsArgs {
    /// Output as JSON.
    #[arg(long)]
    pub json: bool,

    /// Check if write locations are accessible (useful for Docker read-only containers).
    #[arg(long)]
    pub check_writable: bool,
}

/// Paths debug output.
#[derive(Debug, Serialize)]
struct PathsDebugOutput {
    cortex_home: PathInfo,
    config_dir: PathInfo,
    data_dir: PathInfo,
    cache_dir: PathInfo,
    sessions_dir: PathInfo,
    plugins_dir: PathInfo,
    skills_dir: PathInfo,
    agents_dir: PathInfo,
    mcp_dir: PathInfo,
    logs_dir: PathInfo,
    snapshots_dir: PathInfo,
    temp_dir: PathInfo,
}

/// Path info.
#[derive(Debug, Serialize)]
struct PathInfo {
    path: PathBuf,
    exists: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    size_bytes: Option<u64>,
}

impl PathInfo {
    fn new(path: PathBuf) -> Self {
        let exists = path.exists();
        let size_bytes = if exists && path.is_dir() {
            dir_size(&path).ok()
        } else if exists {
            std::fs::metadata(&path).ok().map(|m| m.len())
        } else {
            None
        };
        Self {
            path,
            exists,
            size_bytes,
        }
    }
}

/// Calculate directory size.
fn dir_size(path: &PathBuf) -> Result<u64> {
    let mut total = 0;
    if path.is_dir() {
        for entry in std::fs::read_dir(path)? {
            let entry = entry?;
            let meta = entry.metadata()?;
            if meta.is_dir() {
                total += dir_size(&entry.path())?;
            } else {
                total += meta.len();
            }
        }
    }
    Ok(total)
}

async fn run_paths(args: PathsArgs) -> Result<()> {
    let cortex_home = get_cortex_home();

    // Handle --check-writable flag for Docker read-only container validation
    if args.check_writable {
        if let Some(warning) = cortex_engine::file_utils::check_write_permissions(&cortex_home) {
            if args.json {
                let statuses = cortex_engine::file_utils::validate_write_locations(&cortex_home);
                let output: Vec<_> = statuses
                    .iter()
                    .map(|s| {
                        serde_json::json!({
                            "path": s.path,
                            "description": s.description,
                            "is_writable": s.is_writable,
                            "error": s.error,
                        })
                    })
                    .collect();
                println!("{}", serde_json::to_string_pretty(&output)?);
            } else {
                eprintln!("{warning}");
            }
            std::process::exit(1);
        } else {
            if args.json {
                let statuses = cortex_engine::file_utils::validate_write_locations(&cortex_home);
                let output: Vec<_> = statuses
                    .iter()
                    .map(|s| {
                        serde_json::json!({
                            "path": s.path,
                            "description": s.description,
                            "is_writable": s.is_writable,
                            "error": s.error,
                        })
                    })
                    .collect();
                println!("{}", serde_json::to_string_pretty(&output)?);
            } else {
                println!("✓ All write locations are accessible.");
            }
            return Ok(());
        }
    }

    let output = PathsDebugOutput {
        cortex_home: PathInfo::new(cortex_home.clone()),
        config_dir: PathInfo::new(cortex_home.clone()),
        data_dir: PathInfo::new(cortex_home.clone()),
        cache_dir: PathInfo::new(cortex_home.join("cache")),
        sessions_dir: PathInfo::new(cortex_home.join("sessions")),
        plugins_dir: PathInfo::new(cortex_home.join("plugins")),
        skills_dir: PathInfo::new(cortex_home.join("skills")),
        agents_dir: PathInfo::new(cortex_home.join("agents")),
        mcp_dir: PathInfo::new(cortex_home.join("mcp")),
        logs_dir: PathInfo::new(cortex_home.join("logs")),
        snapshots_dir: PathInfo::new(cortex_home.join("snapshots")),
        temp_dir: PathInfo::new(std::env::temp_dir().join("Cortex")),
    };

    if args.json {
        println!("{}", serde_json::to_string_pretty(&output)?);
    } else {
        println!("Cortex Paths");
        println!("{}", "=".repeat(70));
        println!("{:<20} {:<40} {:>8}", "Directory", "Path", "Status");
        println!("{}", "-".repeat(70));

        let paths = [
            ("Cortex Home", &output.cortex_home),
            ("Config", &output.config_dir),
            ("Data", &output.data_dir),
            ("Cache", &output.cache_dir),
            ("Sessions", &output.sessions_dir),
            ("Plugins", &output.plugins_dir),
            ("Skills", &output.skills_dir),
            ("Agents", &output.agents_dir),
            ("MCP", &output.mcp_dir),
            ("Logs", &output.logs_dir),
            ("Snapshots", &output.snapshots_dir),
            ("Temp", &output.temp_dir),
        ];

        for (name, info) in paths {
            let status = if info.exists { "exists" } else { "missing" };
            let path_display = info.path.display().to_string();
            let path_truncated = if path_display.len() > 38 {
                format!("...{}", &path_display[path_display.len() - 35..])
            } else {
                path_display
            };
            println!("{:<20} {:<40} {:>8}", name, path_truncated, status);
            if let Some(size) = info.size_bytes {
                if size > 0 {
                    println!("{:>62}", format!("({} )", format_size(size)));
                }
            }
        }
    }

    Ok(())
}

// =============================================================================
// Wait subcommand
// =============================================================================

/// Arguments for wait subcommand.
#[derive(Debug, Parser)]
pub struct WaitArgs {
    /// Wait for LSP to be ready.
    #[arg(long)]
    pub lsp_ready: bool,

    /// Wait for server to be ready.
    #[arg(long)]
    pub server_ready: bool,

    /// Server URL to check (default: http://127.0.0.1:3000).
    #[arg(long, default_value = "http://127.0.0.1:3000")]
    pub server_url: String,

    /// Wait for a TCP port to be available.
    #[arg(long)]
    pub port: Option<u16>,

    /// Host to check when using --port (default: 127.0.0.1).
    #[arg(long, default_value = "127.0.0.1")]
    pub host: String,

    /// Timeout in seconds.
    #[arg(long, default_value = "30")]
    pub timeout: u64,

    /// Check interval in milliseconds.
    #[arg(long, default_value = "500")]
    pub interval: u64,

    /// Output as JSON.
    #[arg(long)]
    pub json: bool,
}

/// Wait result output.
#[derive(Debug, Serialize)]
struct WaitResult {
    condition: String,
    success: bool,
    waited_ms: u64,
    #[serde(skip_serializing_if = "Option::is_none")]
    error: Option<String>,
}

async fn run_wait(args: WaitArgs) -> Result<()> {
    let start = std::time::Instant::now();
    let timeout = Duration::from_secs(args.timeout);

    // Validate interval: minimum 100ms to prevent high CPU usage
    // Treat 0 as default (500ms)
    let interval_ms = if args.interval == 0 {
        500
    } else if args.interval < 100 {
        100
    } else {
        args.interval
    };
    let interval = Duration::from_millis(interval_ms);

    let (condition, success, error) = if args.lsp_ready {
        // Wait for LSP - check if rust-analyzer or similar is available
        let condition = "lsp_ready".to_string();
        let mut success = false;
        let mut error = None;

        while start.elapsed() < timeout {
            let (available, _, _) = check_command_installed("rust-analyzer").await;
            if available {
                success = true;
                break;
            }
            tokio::time::sleep(interval).await;
        }

        if !success {
            error = Some("Timeout waiting for LSP".to_string());
        }

        (condition, success, error)
    } else if args.server_ready {
        // Wait for HTTP server
        let condition = format!("server_ready ({})", args.server_url);
        let mut success = false;
        let mut error = None;

        let client = create_default_client()?;

        while start.elapsed() < timeout {
            match client.get(&args.server_url).send().await {
                Ok(response)
                    if response.status().is_success() || response.status().is_client_error() =>
                {
                    // Server is responding (even 4xx means it's up)
                    success = true;
                    break;
                }
                _ => {
                    tokio::time::sleep(interval).await;
                }
            }
        }

        if !success {
            error = Some(format!("Timeout waiting for server at {}", args.server_url));
        }

        (condition, success, error)
    } else if let Some(port) = args.port {
        // Wait for TCP port to be available
        let condition = format!("port_ready ({}:{})", args.host, port);
        let mut success = false;
        let mut error = None;

        let addr = format!("{}:{}", args.host, port);

        while start.elapsed() < timeout {
            match tokio::net::TcpStream::connect(&addr).await {
                Ok(_) => {
                    // Port is open and accepting connections
                    success = true;
                    break;
                }
                Err(_) => {
                    tokio::time::sleep(interval).await;
                }
            }
        }

        if !success {
            error = Some(format!(
                "Timeout waiting for port {} on {}",
                port, args.host
            ));
        }

        (condition, success, error)
    } else {
        bail!("No condition specified. Use --lsp-ready, --server-ready, or --port");
    };

    let waited_ms = start.elapsed().as_millis() as u64;

    let result = WaitResult {
        condition,
        success,
        waited_ms,
        error,
    };

    if args.json {
        println!("{}", serde_json::to_string_pretty(&result)?);
    } else {
        println!("Wait Result");
        println!("{}", "=".repeat(40));
        println!("  Condition: {}", result.condition);
        println!(
            "  Success:   {} ({})",
            result.success,
            if result.success {
                format!("{} is ready", result.condition)
            } else {
                "condition not met".to_string()
            }
        );
        // Display waited time in seconds (consistent with --timeout which is in seconds)
        println!("  Waited:    {:.2}s", result.waited_ms as f64 / 1000.0);
        if let Some(ref err) = result.error {
            println!("  Error:     {}", err);
        }
    }

    if !result.success {
        std::process::exit(1);
    }

    Ok(())
}

// =============================================================================
// System subcommand
// =============================================================================

/// Arguments for system subcommand.
#[derive(Debug, Parser)]
pub struct SystemArgs {
    /// Output as JSON.
    #[arg(long)]
    pub json: bool,
}

/// System debug output.
#[derive(Debug, Serialize)]
struct SystemDebugOutput {
    os: OsInfo,
    hardware: HardwareInfo,
    environment: EnvironmentInfo,
    cortex: CortexInfo,
}

/// Operating system information.
#[derive(Debug, Serialize)]
struct OsInfo {
    name: String,
    version: Option<String>,
    family: String,
}

/// Hardware information.
#[derive(Debug, Serialize)]
struct HardwareInfo {
    arch: String,
    cpu_cores: Option<usize>,
    /// Total memory in bytes (considers container limits on Linux)
    #[serde(skip_serializing_if = "Option::is_none")]
    total_memory_bytes: Option<u64>,
    /// Human-readable memory string
    #[serde(skip_serializing_if = "Option::is_none")]
    total_memory: Option<String>,
    /// Whether running in a container with memory limits
    #[serde(skip_serializing_if = "Option::is_none")]
    container_memory_limit: Option<bool>,
}

/// Environment information.
#[derive(Debug, Serialize)]
struct EnvironmentInfo {
    shell: Option<String>,
    home_dir: Option<PathBuf>,
    current_dir: Option<PathBuf>,
    user: Option<String>,
    /// User ID (Unix only) - useful for container environments
    #[serde(skip_serializing_if = "Option::is_none")]
    uid: Option<u32>,
    term: Option<String>,
}

/// Cortex-specific information.
#[derive(Debug, Serialize)]
struct CortexInfo {
    version: String,
    cortex_home: PathBuf,
    rust_version: Option<String>,
}

async fn run_system(args: SystemArgs) -> Result<()> {
    // Gather OS information
    let os_name = std::env::consts::OS.to_string();
    let os_family = std::env::consts::FAMILY.to_string();

    // Try to get OS version
    let os_version = get_os_version().await;

    let os = OsInfo {
        name: os_name,
        version: os_version,
        family: os_family,
    };

    // Gather hardware information
    let arch = std::env::consts::ARCH.to_string();
    let cpu_cores = std::thread::available_parallelism().map(|p| p.get()).ok();

    // Get memory info, considering container limits
    let (total_memory_bytes, container_memory_limit) = get_available_memory();
    let total_memory = total_memory_bytes.map(format_size);

    let hardware = HardwareInfo {
        arch,
        cpu_cores,
        total_memory_bytes,
        total_memory,
        container_memory_limit,
    };

    // Gather environment information
    let shell = std::env::var("SHELL")
        .ok()
        .or_else(|| std::env::var("COMSPEC").ok());
    let home_dir = dirs::home_dir();
    let current_dir = std::env::current_dir().ok();

    // Get username - fallback to UID string if not found (container environments)
    let (user, uid) = get_user_info();
    let term = std::env::var("TERM").ok();

    let environment = EnvironmentInfo {
        shell,
        home_dir,
        current_dir,
        user,
        uid,
        term,
    };

    // Gather Cortex-specific information
    let version = env!("CARGO_PKG_VERSION").to_string();
    let cortex_home = get_cortex_home_or_default();
    let rust_version = get_rust_version().await;

    let cortex = CortexInfo {
        version,
        cortex_home,
        rust_version,
    };

    let output = SystemDebugOutput {
        os,
        hardware,
        environment,
        cortex,
    };

    if args.json {
        println!("{}", serde_json::to_string_pretty(&output)?);
    } else {
        println!("System Information");
        println!("{}", "=".repeat(50));

        println!();
        println!("Operating System");
        println!("{}", "-".repeat(40));
        println!("  Name:    {}", output.os.name);
        if let Some(ref version) = output.os.version {
            println!("  Version: {}", version);
        }
        println!("  Family:  {}", output.os.family);

        println!();
        println!("Hardware");
        println!("{}", "-".repeat(40));
        println!("  Architecture: {}", output.hardware.arch);
        if let Some(cores) = output.hardware.cpu_cores {
            println!("  CPU Cores:    {}", cores);
        }
        if let Some(ref mem) = output.hardware.total_memory {
            let mem_note = if output.hardware.container_memory_limit == Some(true) {
                " (container limit)"
            } else {
                ""
            };
            println!("  RAM:          {}{}", mem, mem_note);
        }

        println!();
        println!("Environment");
        println!("{}", "-".repeat(40));
        if let Some(ref shell) = output.environment.shell {
            println!("  Shell:       {}", shell);
        }
        if let Some(ref home) = output.environment.home_dir {
            println!("  Home Dir:    {}", home.display());
        }
        if let Some(ref cwd) = output.environment.current_dir {
            println!("  Current Dir: {}", cwd.display());
        }
        if let Some(ref user) = output.environment.user {
            println!("  User:        {}", user);
        }
        if let Some(uid) = output.environment.uid {
            println!("  UID:         {}", uid);
        }
        if let Some(ref term) = output.environment.term {
            println!("  Terminal:    {}", term);
        }

        println!();
        println!("Cortex");
        println!("{}", "-".repeat(40));
        println!("  Version:     {}", output.cortex.version);
        println!("  Cortex Home: {}", output.cortex.cortex_home.display());
        if let Some(ref rust_ver) = output.cortex.rust_version {
            println!("  Rust:        {}", rust_ver);
        }
    }

    Ok(())
}

/// Get OS version using platform-specific commands.
async fn get_os_version() -> Option<String> {
    #[cfg(target_os = "windows")]
    {
        // Try to get Windows version
        let output = tokio::process::Command::new("cmd")
            .args(["/c", "ver"])
            .output()
            .await
            .ok()?;
        if output.status.success() {
            let ver = String::from_utf8_lossy(&output.stdout);
            return Some(ver.trim().to_string());
        }
        None
    }

    #[cfg(target_os = "macos")]
    {
        // Try to get macOS version
        let output = tokio::process::Command::new("sw_vers")
            .arg("-productVersion")
            .output()
            .await
            .ok()?;
        if output.status.success() {
            let ver = String::from_utf8_lossy(&output.stdout);
            return Some(ver.trim().to_string());
        }
        None
    }

    #[cfg(target_os = "linux")]
    {
        // Try to read /etc/os-release
        if let Ok(content) = std::fs::read_to_string("/etc/os-release") {
            for line in content.lines() {
                if line.starts_with("PRETTY_NAME=") {
                    let name = line
                        .trim_start_matches("PRETTY_NAME=")
                        .trim_matches('"')
                        .to_string();
                    return Some(name);
                }
            }
        }
        // Fallback to uname
        let output = tokio::process::Command::new("uname")
            .arg("-r")
            .output()
            .await
            .ok()?;
        if output.status.success() {
            let ver = String::from_utf8_lossy(&output.stdout);
            return Some(ver.trim().to_string());
        }
        None
    }

    #[cfg(not(any(target_os = "windows", target_os = "macos", target_os = "linux")))]
    {
        None
    }
}

/// Get Rust version if rustc is available.
async fn get_rust_version() -> Option<String> {
    let output = tokio::process::Command::new("rustc")
        .arg("--version")
        .output()
        .await
        .ok()?;
    if output.status.success() {
        let ver = String::from_utf8_lossy(&output.stdout);
        return Some(ver.trim().to_string());
    }
    None
}

/// Get user information, handling container environments where UID may not be in /etc/passwd.
///
/// Returns (username, uid) where username falls back to "uid:<number>" if not found.
fn get_user_info() -> (Option<String>, Option<u32>) {
    // Try to get username from environment first
    let env_user = std::env::var("USER")
        .ok()
        .or_else(|| std::env::var("USERNAME").ok());

    #[cfg(unix)]
    {
        let uid = unsafe { libc::getuid() };

        // If we got a username from env, use it
        if let Some(user) = env_user {
            return (Some(user), Some(uid));
        }

        // Fallback: use UID string (common in containers with arbitrary UIDs)
        (Some(format!("uid:{}", uid)), Some(uid))
    }

    #[cfg(not(unix))]
    {
        (env_user, None)
    }
}

/// Get available memory, considering container cgroup limits on Linux.
///
/// Returns (memory_bytes, is_container_limited).
fn get_available_memory() -> (Option<u64>, Option<bool>) {
    #[cfg(target_os = "linux")]
    {
        // Try cgroup v2 first (unified hierarchy)
        if let Ok(limit) = std::fs::read_to_string("/sys/fs/cgroup/memory.max") {
            let limit = limit.trim();
            if limit != "max" {
                if let Ok(bytes) = limit.parse::<u64>() {
                    return (Some(bytes), Some(true));
                }
            }
        }

        // Try cgroup v1
        if let Ok(limit) = std::fs::read_to_string("/sys/fs/cgroup/memory/memory.limit_in_bytes") {
            let limit = limit.trim();
            // Check if it's not the max value (which means unlimited)
            if let Ok(bytes) = limit.parse::<u64>() {
                // 9223372036854771712 is typically "unlimited" in cgroup v1
                if bytes < 9223372036854771712 {
                    return (Some(bytes), Some(true));
                }
            }
        }

        // Fall back to /proc/meminfo for host memory
        if let Ok(meminfo) = std::fs::read_to_string("/proc/meminfo") {
            for line in meminfo.lines() {
                if line.starts_with("MemTotal:") {
                    let parts: Vec<&str> = line.split_whitespace().collect();
                    if parts.len() >= 2 {
                        if let Ok(kb) = parts[1].parse::<u64>() {
                            return (Some(kb * 1024), Some(false));
                        }
                    }
                }
            }
        }

        (None, None)
    }

    #[cfg(target_os = "macos")]
    {
        // Use sysctl on macOS
        let output = std::process::Command::new("sysctl")
            .args(["-n", "hw.memsize"])
            .output()
            .ok();

        if let Some(output) = output {
            if output.status.success() {
                let mem_str = String::from_utf8_lossy(&output.stdout);
                if let Ok(bytes) = mem_str.trim().parse::<u64>() {
                    return (Some(bytes), Some(false));
                }
            }
        }

        (None, None)
    }

    #[cfg(target_os = "windows")]
    {
        // On Windows, we could use GlobalMemoryStatusEx but it requires windows-sys crate
        // For now, return None
        (None, None)
    }

    #[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
    {
        (None, None)
    }
}

/// Get the cortex home directory (alternative function name for clarity).
fn get_cortex_home_or_default() -> PathBuf {
    dirs::home_dir()
        .map(|h| h.join(".cortex"))
        .unwrap_or_else(|| PathBuf::from(".cortex"))
}

// =============================================================================
// Main entry point
// =============================================================================

/// Get the cortex home directory.
fn get_cortex_home() -> PathBuf {
    dirs::home_dir()
        .map(|h| h.join(".cortex"))
        .unwrap_or_else(|| PathBuf::from(".cortex"))
}

impl DebugCli {
    /// Run the debug command.
    pub async fn run(self) -> Result<()> {
        match self.subcommand {
            Some(DebugSubcommand::Config(args)) => run_config(args).await,
            Some(DebugSubcommand::File(args)) => run_file(args).await,
            Some(DebugSubcommand::Lsp(args)) => run_lsp(args).await,
            Some(DebugSubcommand::Ripgrep(args)) => run_ripgrep(args).await,
            Some(DebugSubcommand::Skill(args)) => run_skill(args).await,
            Some(DebugSubcommand::Snapshot(args)) => run_snapshot(args).await,
            Some(DebugSubcommand::Paths(args)) => run_paths(args).await,
            Some(DebugSubcommand::System(args)) => run_system(args).await,
            Some(DebugSubcommand::Wait(args)) => run_wait(args).await,
            None => {
                // Show help when no subcommand is provided
                println!("Cortex Debug Commands");
                println!("{}", "=".repeat(50));
                println!();
                println!("Available subcommands:");
                println!("  config    Show resolved configuration and config file locations");
                println!("  file      Show file metadata, MIME type, and encoding");
                println!("  lsp       List and test LSP servers");
                println!("  ripgrep   Check ripgrep availability and test search");
                println!("  skill     Parse and validate a skill file");
                println!("  snapshot  Show snapshot status and diffs");
                println!("  paths     Show all Cortex paths");
                println!("  system    Show system information for bug reports");
                println!("  wait      Wait for a condition (useful for scripts)");
                println!();
                println!("Run 'cortex debug <subcommand> --help' for more information.");
                Ok(())
            }
        }
    }
}

/// Patterns that indicate a variable contains sensitive data.
const SENSITIVE_PATTERNS: &[&str] = &[
    "API_KEY",
    "SECRET",
    "TOKEN",
    "PASSWORD",
    "CREDENTIAL",
    "PRIVATE",
    "AUTH",
    "ACCESS_KEY",
    "BEARER",
    "SESSION",
];

/// Check if an environment variable name indicates sensitive data.
fn is_sensitive_var_name(name: &str) -> bool {
    let name_upper = name.to_uppercase();
    SENSITIVE_PATTERNS
        .iter()
        .any(|pattern| name_upper.contains(pattern))
}

/// Redact a sensitive value, showing only first and last few characters.
fn redact_sensitive_value(value: &str) -> String {
    if value.is_empty() {
        return "[EMPTY]".to_string();
    }
    if value.len() <= 8 {
        return "[REDACTED]".to_string();
    }
    // Show first 4 and last 4 characters
    format!("{}...{}", &value[..4], &value[value.len() - 4..])
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_guess_mime_type() {
        assert_eq!(guess_mime_type("rs"), "text/x-rust");
        assert_eq!(guess_mime_type("json"), "application/json");
        assert_eq!(guess_mime_type("png"), "image/png");
        assert_eq!(guess_mime_type("unknown"), "application/octet-stream");
    }

    #[test]
    fn test_format_size() {
        assert_eq!(format_size(500), "500 B");
        assert_eq!(format_size(1024), "1.00 KB");
        assert_eq!(format_size(1048576), "1.00 MB");
        assert_eq!(format_size(1073741824), "1.00 GB");
    }

    #[test]
    fn test_is_sensitive_var_name() {
        // Should match sensitive patterns
        assert!(is_sensitive_var_name("OPENAI_API_KEY"));
        assert!(is_sensitive_var_name("DATABASE_PASSWORD"));
        assert!(is_sensitive_var_name("AWS_SECRET_ACCESS_KEY"));
        assert!(is_sensitive_var_name("AUTH_TOKEN"));
        assert!(is_sensitive_var_name("GITHUB_TOKEN"));
        assert!(is_sensitive_var_name("PRIVATE_KEY"));
        assert!(is_sensitive_var_name("CREDENTIAL_FILE"));
        assert!(is_sensitive_var_name("BEARER_TOKEN"));

        // Should not match non-sensitive patterns
        assert!(!is_sensitive_var_name("PATH"));
        assert!(!is_sensitive_var_name("HOME"));
        assert!(!is_sensitive_var_name("USER"));
        assert!(!is_sensitive_var_name("EDITOR"));
        assert!(!is_sensitive_var_name("SHELL"));
    }

    #[test]
    fn test_redact_sensitive_value() {
        // Empty value
        assert_eq!(redact_sensitive_value(""), "[EMPTY]");

        // Short value (8 or fewer chars)
        assert_eq!(redact_sensitive_value("short"), "[REDACTED]");
        assert_eq!(redact_sensitive_value("12345678"), "[REDACTED]");

        // Longer value shows first/last 4 chars
        assert_eq!(redact_sensitive_value("sk-abc123xyz789"), "sk-a...9789");
        assert_eq!(redact_sensitive_value("supersecretpassword"), "supe...word");
    }
}