feat(cortex-cli): implement 10 open PRs

This commit implements the following 10 open PRs for cortex-cli:

1. PR #155 - Prompt for tab completion setup on first run
   - Added completion_setup module for first-run completion detection
   - On first interactive run, prompts user to enable tab completion
   - Automatically detects shell (bash, zsh, fish, PowerShell, elvish)
   - Creates marker file to avoid repeated prompts

2. PR #153 - Emit valid JSONL with full event data in streaming mode
   - Already implemented in previous work

3. PR #151 - Add man page generation command
   - Added clap_mangen dependency
   - Added 'man' command with optional output directory
   - Generates roff-format man pages

4. PR #137 - Use consistent provider name casing in models output
   - Already using lowercase provider names (no changes needed)

5. PR #134 - Check actual write permission for current user in debug file
   - Added is_writable_by_current_user() helper function
   - Uses actual file open test instead of permission bits

6. PR #133 - Detect actual binary location from PATH for uninstall dry-run
   - Added 'which' dependency for PATH lookup
   - Updated collect_binary_locations() to use PATH search first

7. PR #130 - Show searched paths in debug ripgrep output
   - Added searched_paths field to RipgrepDebugOutput
   - Added get_path_directories() helper function
   - Shows PATH directories when ripgrep is not found

8. PR #129 - Output valid JSON on errors when --json flag is set
   - Updated run_servers() to handle MdnsBrowser errors as JSON
   - Move discovery banner inside conditional for non-JSON mode

9. PR #126 - Add batch export for sessions
   - Added --all (-a) flag for batch export mode
   - Added --output-dir option for batch exports
   - Each session exported to separate JSON file

10. PR #124 - Display feature descriptions in features list
    - Updated list_features() to use actual feature registry
    - Added Description column to features list output

11. PR #122 - Add debug system command for system information
    - Added System subcommand to debug CLI
    - Gathers OS, hardware, environment, and Cortex info
    - Supports JSON output for scripts/automation

Author: factorydroid

Cargo.toml

@@ -242,6 +242,7 @@ toml_edit = "0.23"
 # CLI - Arguments
 clap = { version = "4", features = ["derive", "wrap_help", "env"] }
 clap_complete = "4"
+clap_mangen = "0.2"
 
 # CLI - TUI
 ratatui = { version = "0.29", features = ["scrolling-regions", "unstable-backend-writer", "unstable-rendered-line-info", "unstable-widget-ref"] }

cortex-cli/Cargo.toml

@@ -34,6 +34,7 @@ cortex-update = { workspace = true }
 
 clap = { workspace = true }
 clap_complete = { workspace = true }
+clap_mangen = { workspace = true }
 tokio = { workspace = true, features = ["full"] }
 anyhow = { workspace = true }
 tracing = { workspace = true }
@@ -61,3 +62,6 @@ scraper = "0.22"
 
 # For mDNS service discovery
 hostname = { workspace = true }
+
+# For finding binary location in PATH
+which = { workspace = true }

cortex-cli/src/completion_setup.rs

@@ -0,0 +1,312 @@
+//! First-run shell completion setup module.
+//!
+//! This module handles prompting users to install shell completions on first run.
+//! It detects the user's shell, offers to install completions, and tracks whether
+//! the prompt has been shown to avoid repeated prompts.
+
+use std::fs;
+use std::io::{self, IsTerminal, Write};
+use std::path::PathBuf;
+
+use clap_complete::Shell;
+
+/// Marker file name to track if completion setup has been offered.
+const COMPLETION_OFFERED_MARKER: &str = ".completion_offered";
+
+/// Check if this is an interactive terminal.
+fn is_interactive_terminal() -> bool {
+    io::stdin().is_terminal() && io::stdout().is_terminal()
+}
+
+/// Get the cortex home directory.
+fn get_cortex_home() -> Option<PathBuf> {
+    // Check CORTEX_HOME or CORTEX_CONFIG_DIR environment variables
+    if let Ok(val) = std::env::var("CORTEX_CONFIG_DIR") {
+        if !val.is_empty() {
+            return Some(PathBuf::from(val));
+        }
+    }
+    if let Ok(val) = std::env::var("CORTEX_HOME") {
+        if !val.is_empty() {
+            return Some(PathBuf::from(val));
+        }
+    }
+
+    // Default to ~/.cortex
+    dirs::home_dir().map(|h| h.join(".cortex"))
+}
+
+/// Check if completion setup has already been offered.
+fn completion_already_offered(cortex_home: &PathBuf) -> bool {
+    cortex_home.join(COMPLETION_OFFERED_MARKER).exists()
+}
+
+/// Mark that completion setup has been offered.
+fn mark_completion_offered(cortex_home: &PathBuf) -> io::Result<()> {
+    // Ensure the directory exists
+    fs::create_dir_all(cortex_home)?;
+
+    // Create the marker file
+    let marker_path = cortex_home.join(COMPLETION_OFFERED_MARKER);
+    fs::write(&marker_path, "completion setup offered\n")?;
+    Ok(())
+}
+
+/// Detect the user's shell from the SHELL environment variable.
+fn detect_shell() -> Option<Shell> {
+    let shell_path = std::env::var("SHELL").ok()?;
+    let shell_name = std::path::Path::new(&shell_path)
+        .file_name()?
+        .to_str()?
+        .to_lowercase();
+
+    match shell_name.as_str() {
+        "bash" => Some(Shell::Bash),
+        "zsh" => Some(Shell::Zsh),
+        "fish" => Some(Shell::Fish),
+        "powershell" | "pwsh" => Some(Shell::PowerShell),
+        "elvish" => Some(Shell::Elvish),
+        _ => None,
+    }
+}
+
+/// Get the completion installation path for a given shell.
+fn get_completion_install_path(shell: Shell) -> Option<PathBuf> {
+    let home = dirs::home_dir()?;
+
+    match shell {
+        Shell::Bash => {
+            // Try bash-completion directory first, then fall back to .bashrc
+            let bash_completion = home.join(".local/share/bash-completion/completions");
+            if bash_completion.parent().map_or(false, |p| p.exists()) {
+                Some(bash_completion.join("cortex"))
+            } else {
+                Some(home.join(".bashrc"))
+            }
+        }
+        Shell::Zsh => {
+            // Check for common zsh completion directories
+            let zsh_completions = home.join(".zsh/completions");
+            if zsh_completions.exists() {
+                Some(zsh_completions.join("_cortex"))
+            } else {
+                Some(home.join(".zshrc"))
+            }
+        }
+        Shell::Fish => Some(home.join(".config/fish/completions/cortex.fish")),
+        Shell::PowerShell => {
+            // PowerShell profile location varies by platform
+            #[cfg(windows)]
+            {
+                Some(home.join("Documents/PowerShell/Microsoft.PowerShell_profile.ps1"))
+            }
+            #[cfg(not(windows))]
+            {
+                Some(home.join(".config/powershell/Microsoft.PowerShell_profile.ps1"))
+            }
+        }
+        Shell::Elvish => Some(home.join(".elvish/lib/cortex.elv")),
+        _ => None,
+    }
+}
+
+/// Get the shell name in lowercase for command output.
+fn shell_name(shell: Shell) -> &'static str {
+    match shell {
+        Shell::Bash => "bash",
+        Shell::Zsh => "zsh",
+        Shell::Fish => "fish",
+        Shell::PowerShell => "powershell",
+        Shell::Elvish => "elvish",
+        _ => "bash",
+    }
+}
+
+/// Install completions for the given shell.
+///
+/// For most shells, we add an eval command to the shell configuration file
+/// that dynamically loads completions. This approach is more robust as it
+/// doesn't require updating the completion script when the CLI changes.
+fn install_completions(shell: Shell) -> io::Result<()> {
+    let install_path = get_completion_install_path(shell).ok_or_else(|| {
+        io::Error::new(
+            io::ErrorKind::NotFound,
+            "Could not determine completion installation path",
+        )
+    })?;
+
+    // Create parent directory if needed
+    if let Some(parent) = install_path.parent() {
+        fs::create_dir_all(parent)?;
+    }
+
+    let shell_cmd = shell_name(shell);
+
+    match shell {
+        Shell::Bash => {
+            // Append eval command to .bashrc
+            let mut file = fs::OpenOptions::new()
+                .create(true)
+                .append(true)
+                .open(&install_path)?;
+
+            writeln!(file)?;
+            writeln!(file, "# Cortex CLI completions")?;
+            writeln!(file, "eval \"$(cortex completion {})\"\n", shell_cmd)?;
+        }
+        Shell::Zsh => {
+            // Append eval command to .zshrc
+            let mut file = fs::OpenOptions::new()
+                .create(true)
+                .append(true)
+                .open(&install_path)?;
+
+            writeln!(file)?;
+            writeln!(file, "# Cortex CLI completions")?;
+            writeln!(file, "eval \"$(cortex completion {})\"\n", shell_cmd)?;
+        }
+        Shell::Fish => {
+            // Fish needs the script written to the completions directory
+            // Generate it by running the command
+            let output = std::process::Command::new("cortex")
+                .args(["completion", shell_cmd])
+                .output()?;
+
+            if output.status.success() {
+                fs::write(&install_path, output.stdout)?;
+            } else {
+                return Err(io::Error::new(
+                    io::ErrorKind::Other,
+                    "Failed to generate fish completions",
+                ));
+            }
+        }
+        Shell::PowerShell => {
+            // Append to PowerShell profile
+            let mut file = fs::OpenOptions::new()
+                .create(true)
+                .append(true)
+                .open(&install_path)?;
+
+            writeln!(file)?;
+            writeln!(file, "# Cortex CLI completions")?;
+            writeln!(
+                file,
+                "cortex completion powershell | Out-String | Invoke-Expression\n"
+            )?;
+        }
+        Shell::Elvish => {
+            // Generate script by running the command
+            let output = std::process::Command::new("cortex")
+                .args(["completion", shell_cmd])
+                .output()?;
+
+            if output.status.success() {
+                fs::write(&install_path, output.stdout)?;
+            } else {
+                return Err(io::Error::new(
+                    io::ErrorKind::Other,
+                    "Failed to generate elvish completions",
+                ));
+            }
+        }
+        _ => {
+            return Err(io::Error::new(
+                io::ErrorKind::Unsupported,
+                "Unsupported shell for automatic installation",
+            ));
+        }
+    }
+
+    Ok(())
+}
+
+/// Prompt the user to install shell completions on first run.
+///
+/// This function checks if:
+/// 1. We're running in an interactive terminal
+/// 2. Completion setup hasn't been offered before
+/// 3. We can detect the user's shell
+///
+/// If all conditions are met, it prompts the user and optionally installs completions.
+pub fn maybe_prompt_completion_setup() {
+    // Only prompt in interactive terminals
+    if !is_interactive_terminal() {
+        return;
+    }
+
+    // Get cortex home directory
+    let cortex_home = match get_cortex_home() {
+        Some(home) => home,
+        None => return,
+    };
+
+    // Check if we've already offered completion setup
+    if completion_already_offered(&cortex_home) {
+        return;
+    }
+
+    // Detect the user's shell
+    let shell = match detect_shell() {
+        Some(s) => s,
+        None => {
+            // Mark as offered so we don't keep trying with unknown shells
+            let _ = mark_completion_offered(&cortex_home);
+            return;
+        }
+    };
+
+    let shell_str = shell_name(shell);
+
+    // Show the prompt
+    println!();
+    println!("Welcome to Cortex CLI!");
+    println!();
+    println!(
+        "Would you like to enable tab completion for your shell ({shell_str})?",
+    );
+    println!("This will allow you to press TAB to complete commands and options.");
+    println!();
+    print!("Enable tab completion? [y/N] ");
+    let _ = io::stdout().flush();
+
+    // Read user input
+    let mut input = String::new();
+    if io::stdin().read_line(&mut input).is_err() {
+        let _ = mark_completion_offered(&cortex_home);
+        return;
+    }
+
+    let response = input.trim().to_lowercase();
+    if response == "y" || response == "yes" {
+        match install_completions(shell) {
+            Ok(()) => {
+                println!();
+                println!("Tab completion has been enabled!");
+                println!(
+                    "Please restart your shell or run 'source ~/.{}rc' to activate.",
+                    shell_str
+                );
+                println!();
+            }
+            Err(e) => {
+                println!();
+                println!("Could not automatically install completions: {e}");
+                println!();
+                println!("You can manually enable completions by running:");
+                println!("  cortex completion {shell_str}");
+                println!();
+                println!("Then add the output to your shell configuration file.");
+                println!();
+            }
+        }
+    } else {
+        println!();
+        println!("No problem! You can enable tab completion later by running:");
+        println!("  cortex completion {shell_str}");
+        println!();
+    }
+
+    // Mark as offered regardless of the user's choice
+    let _ = mark_completion_offered(&cortex_home);
+}