mi6_cli/

help.rs

use clap::CommandFactory;
use std::io::{IsTerminal, Write};

/// Get ANSI escape codes, respecting TTY and NO_COLOR.
fn ansi_codes() -> (&'static str, &'static str, &'static str, &'static str) {
    // Disable colors if not a TTY or NO_COLOR is set
    if !std::io::stdout().is_terminal() || std::env::var_os("NO_COLOR").is_some() {
        return ("", "", "", "");
    }
    ("\x1b[0m", "\x1b[1m", "\x1b[32m", "\x1b[37m")
}

/// Capitalize the first letter of a string.
fn capitalize(s: &str) -> String {
    let mut chars = s.chars();
    match chars.next() {
        None => String::new(),
        Some(c) => c.to_uppercase().collect::<String>() + chars.as_str(),
    }
}

/// Print styled help for a command path (e.g., `["ingest"]` or `["ingest", "transcript"]`).
pub fn print_command_help(path: &[&str]) -> bool {
    let app = crate::Cli::command();

    // Navigate to the command at the given path
    let mut current_cmd = &app;
    for name in path {
        let Some(cmd) = current_cmd
            .get_subcommands()
            .find(|c| c.get_name() == *name)
        else {
            return false;
        };
        current_cmd = cmd;
    }

    let mut stdout = std::io::stdout();
    let (reset, bold, green, white) = ansi_codes();

    // Build the full command string (e.g., "mi6 ingest transcript")
    let full_cmd = format!("mi6 {}", path.join(" "));

    // Usage line
    let _ = writeln!(
        stdout,
        "{bold}{green}usage:{reset} {bold}{white}{full_cmd} [options]{reset}"
    );
    let _ = writeln!(stdout);

    // Description
    if let Some(about) = current_cmd.get_about() {
        let _ = writeln!(stdout, "{}", about);
        let _ = writeln!(stdout);
    }

    // Check if this command has subcommands
    let subcommands: Vec<_> = current_cmd
        .get_subcommands()
        .filter(|c| !c.is_hide_set())
        .collect();
    let has_subcommands = !subcommands.is_empty();

    if has_subcommands {
        // Use the last path component for the header (e.g., "Ingest Commands")
        let cmd_name = capitalize(path.last().unwrap_or(&""));
        let _ = writeln!(stdout, "{bold}{green}{cmd_name} Commands{reset}");
        for sub in &subcommands {
            let name = sub.get_name();
            let desc = sub.get_about().map(|s| s.to_string()).unwrap_or_default();
            let _ = writeln!(stdout, "    {bold}{white}{name:<20}{reset} {desc}");
        }
        let _ = writeln!(stdout);
    }

    // Arguments (positional)
    let positionals: Vec<_> = current_cmd.get_positionals().collect();
    let has_positionals = !positionals.is_empty();
    if has_positionals {
        // Build argument strings and calculate max width for alignment
        let arg_entries: Vec<(String, String)> = positionals
            .iter()
            .map(|arg| {
                let name = arg.get_id().as_str();
                let arg_str = format!("<{name}>");
                let help = arg.get_help().map(|s| s.to_string()).unwrap_or_default();
                (arg_str, help)
            })
            .collect();

        let max_width = arg_entries.iter().map(|(s, _)| s.len()).max().unwrap_or(0);

        let _ = writeln!(stdout, "{bold}{green}Arguments{reset}");
        for (arg_str, help) in arg_entries {
            let _ = writeln!(
                stdout,
                "    {bold}{white}{arg_str:<max_width$}{reset}  {help}"
            );
        }
    }

    // Options
    let options: Vec<_> = current_cmd
        .get_opts()
        .filter(|a| !a.is_hide_set() && !a.is_positional())
        .collect();
    let has_options = !options.is_empty();

    // Add separator after Arguments if more content follows
    if has_positionals && (has_options || has_subcommands) {
        let _ = writeln!(stdout);
    }

    if has_options {
        // Build option strings and calculate max width for alignment
        let option_entries: Vec<(String, String)> = options
            .iter()
            .map(|opt| {
                let short = opt
                    .get_short()
                    .map(|c| format!("-{c}, "))
                    .unwrap_or_default();
                let long = opt
                    .get_long()
                    .map_or_else(|| opt.get_id().to_string(), |l| l.to_string());
                let aliases: Vec<&str> = opt.get_visible_aliases().unwrap_or_default();
                let long_with_aliases = if aliases.is_empty() {
                    format!("--{long}")
                } else {
                    let alias_str = aliases
                        .iter()
                        .map(|a| format!("--{a}"))
                        .collect::<Vec<_>>()
                        .join(", ");
                    format!("--{long}, {alias_str}")
                };
                let opt_str = format!("{short}{long_with_aliases}");
                let help = opt.get_help().map(|s| s.to_string()).unwrap_or_default();
                (opt_str, help)
            })
            .collect();

        let max_width = option_entries
            .iter()
            .map(|(s, _)| s.len())
            .max()
            .unwrap_or(0);

        let _ = writeln!(stdout, "{bold}{green}Options{reset}");
        for (opt_str, help) in option_entries {
            let _ = writeln!(
                stdout,
                "    {bold}{white}{opt_str:<max_width$}{reset}  {help}"
            );
        }
        // Only add blank line if footer follows
        if has_subcommands {
            let _ = writeln!(stdout);
        }
    }

    // Footer for commands with subcommands
    if has_subcommands {
        let _ = writeln!(
            stdout,
            "See arguments for each command with {bold}{white}{full_cmd} <command> -h{reset}"
        );
    }

    true
}

/// Print styled help for a subcommand (single level).
pub fn print_subcommand_help(subcommand: &str) -> bool {
    print_command_help(&[subcommand])
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum CommandCategory {
    Inputs,
    Outputs,
    Meta,
}

impl CommandCategory {
    pub fn name(&self) -> &str {
        match self {
            CommandCategory::Inputs => "Input Commands",
            CommandCategory::Outputs => "Output Commands",
            CommandCategory::Meta => "Meta Commands",
        }
    }
}

/// Map command names to their categories.
///
/// NOTE: When adding a new command to the CLI, update this function to assign
/// it to the appropriate category. Unknown commands default to Meta.
fn get_command_category(name: &str) -> CommandCategory {
    match name {
        // Inputs - commands that ingest data
        "ingest" => CommandCategory::Inputs,

        // Outputs - commands that display/output data
        "session" | "tui" | "watch" => CommandCategory::Outputs,

        // Meta - commands for setup/management
        "enable" | "disable" | "status" => CommandCategory::Meta,

        // Default fallback for unknown commands
        _ => CommandCategory::Meta,
    }
}

/// Print custom help matching jtool's style.
pub fn print_help() {
    let mut stdout = std::io::stdout();
    let (reset, bold, green, white) = ansi_codes();

    let _ = writeln!(
        stdout,
        "{bold}{green}usage:{reset} {bold}{white}mi6 <command> [<args>]{reset}"
    );
    let _ = writeln!(stdout);
    let _ = writeln!(
        stdout,
        "Tool for monitoring and managing agentic coding sessions"
    );
    let _ = writeln!(stdout);

    // Dynamically get all commands from the Commands enum using clap
    let app = crate::Cli::command();
    let mut commands_by_category: std::collections::HashMap<
        CommandCategory,
        Vec<(String, String)>,
    > = std::collections::HashMap::new();

    for subcommand in app.get_subcommands() {
        // Skip hidden commands
        if subcommand.is_hide_set() {
            continue;
        }

        // Skip the help command (clap adds it automatically)
        let name = subcommand.get_name();
        if name == "help" {
            continue;
        }

        let name = name.to_string();
        let description = subcommand
            .get_about()
            .map(|s| s.to_string())
            .unwrap_or_default();
        let category = get_command_category(&name);

        commands_by_category
            .entry(category)
            .or_default()
            .push((name, description));
    }

    // Display commands grouped by category in a specific order
    let categories = [
        CommandCategory::Inputs,
        CommandCategory::Outputs,
        CommandCategory::Meta,
    ];

    let mut first = true;
    for category in &categories {
        if let Some(mut commands) = commands_by_category.remove(category) {
            // Sort commands alphabetically within each category
            commands.sort_by(|a, b| a.0.cmp(&b.0));

            // Print blank line between categories (not before first)
            if !first {
                let _ = writeln!(stdout);
            }
            first = false;

            let _ = writeln!(stdout, "{bold}{green}{}{reset}", category.name());

            for (name, description) in commands {
                let _ = writeln!(stdout, "    {bold}{white}{name:<20}{reset} {description}");
            }
        }
    }

    let _ = writeln!(stdout);
    let _ = writeln!(
        stdout,
        "See arguments for each command with {bold}{white}mi6 <command> -h{reset}"
    );
}