xacli_core/application/

app.rs

use std::io::Write;

use super::parser::Parser;
use crate::{application::AppContext, Command, Context, ContextInfo, Error, Result};

pub struct App {
    pub info: AppInfo,
    pub root: Command,
}

#[derive(Debug, Clone, PartialEq)]
pub struct AppInfo {
    pub name: String,
    pub version: String,
    pub title: String,
    pub description: String,
}

impl App {
    /// Create a new application with name and version
    ///
    /// This is the recommended way to create an App. Use method chaining
    /// to configure the application before calling `run()`.
    pub fn new(name: impl Into<String>, version: impl Into<String>) -> Self {
        let name = name.into();
        let root_name = name.clone();
        Self {
            info: AppInfo {
                name,
                version: version.into(),
                title: String::new(),
                description: String::new(),
            },
            root: Command::new(root_name),
        }
    }

    pub fn command(mut self, cmd: Command) -> Self {
        self.root.subcommands.push(cmd);
        self
    }

    /// Set the run handler for the root command
    ///
    /// This allows the app to execute logic directly without requiring subcommands.
    /// Useful for simple CLIs or testing scenarios.
    ///
    /// # Example
    ///
    /// ```
    /// use xacli_core::App;
    ///
    /// let app = App::new("myapp", "1.0.0")
    ///     .run(Box::new(|ctx| {
    ///         println!("Hello from root!");
    ///         Ok(())
    ///     }));
    /// ```
    pub fn run(mut self, f: Box<crate::command::RunFn>) -> Self {
        self.root.hooks.run_fn = Some(f);
        self
    }

    /// Set the pre_run handler for the root command
    pub fn pre_run(mut self, f: Box<crate::command::RunFn>) -> Self {
        self.root.hooks.pre_run_fn = Some(f);
        self
    }

    /// Set the post_run handler for the root command
    pub fn post_run(mut self, f: Box<crate::command::RunFn>) -> Self {
        self.root.hooks.post_run_fn = Some(f);
        self
    }

    /// Add an argument to the root command
    ///
    /// This allows adding arguments that apply when no subcommand is specified.
    pub fn arg(mut self, arg: crate::Arg) -> Self {
        self.root.args.push(arg);
        self
    }

    pub fn parse(&self, args: Vec<String>) -> Result<ContextInfo> {
        let parsed = Parser::new(self, args).parse()?;

        // Find the command (if any)
        let cmd = self.find_command_by_path(parsed.commands());

        Ok(ContextInfo {
            app: self.info.clone(),
            command: cmd
                .map(|c| c.info.clone())
                .unwrap_or_else(|| crate::CommandInfo {
                    name: self.info.name.clone(),
                    aliases: Vec::new(),
                    title: String::new(),
                    description: String::new(),
                }),
            args: parsed,
        })
    }

    /// Run the application with command line arguments
    ///
    /// This will:
    /// 1. Parse command-line arguments from std::env::args
    /// 2. Handle --version flag (print version and exit)
    /// 3. Handle --help flag or no command (print help and exit)
    /// 4. Find and execute the matched command
    ///
    /// Returns Ok(()) on success, or an error if:
    /// - Argument parsing fails
    /// - Command not found
    /// - Command execution fails
    pub fn execute(&self) -> Result<()> {
        let args: Vec<String> = std::env::args().collect();

        let context_info = self.parse(args)?;

        // Create context
        let mut ctx = AppContext::new(context_info);

        self.execute_with_ctx(&mut ctx)
    }

    /// Run the application with a pre-configured context
    ///
    /// This is useful for testing where you want to use a MockContext
    /// to capture output and inject input events.
    ///
    /// The context should already contain the parsed arguments.
    pub fn execute_with_ctx(&self, ctx: &mut dyn Context) -> Result<()> {
        // Extract values we need from ctx to avoid borrow conflicts
        let is_version = ctx.info().args.is_version();
        let is_help = ctx.info().args.is_help();
        let commands = ctx.info().args.commands().to_vec();

        let mut stdout = ctx.stdout();

        // Handle --version
        if is_version {
            self.write_version(&mut stdout)?;
            return Ok(());
        }

        // Handle --help
        if is_help {
            self.write_help_for_path(&mut stdout, &commands)?;
            return Ok(());
        }

        // If only app name (no subcommands) and root has a run handler, execute it
        if commands.len() == 1 {
            if self.root.hooks.run_fn.is_some() {
                // Drop stdout to release the borrow before executing
                drop(stdout);
                return self.root.execute(ctx);
            } else {
                // No root handler and no subcommands specified - show help
                self.write_help_for_path(&mut stdout, &commands)?;
                return Ok(());
            }
        }

        // Drop stdout before finding and executing command
        drop(stdout);

        // Find the command
        let cmd = self.find_command_by_path(&commands).ok_or_else(|| {
            let available = self.available_commands().join(", ");
            Error::CommandNotFound(format!(
                "'{}'. Available commands: {}",
                commands.last().unwrap_or(&String::new()),
                available
            ))
        })?;

        cmd.execute(ctx)
    }

    /// Find a command by its path
    ///
    /// The path is a slice of command names, starting from the app name.
    /// For example, ["app", "get", "pod"] would find the "pod" subcommand
    /// of the "get" command.
    ///
    /// Returns None if:
    /// - The path is empty
    /// - The first element doesn't match the app name
    /// - Any command in the path is not found
    pub fn find_command_by_path(&self, path: &[String]) -> Option<&Command> {
        // Path must have at least app name + one command
        if path.len() < 2 {
            return None;
        }

        // First element must match app name
        if path[0] != self.info.name {
            return None;
        }

        // Find the first command in root.subcommands
        let mut current_cmd = self
            .root
            .subcommands
            .iter()
            .find(|cmd| cmd.info.name == path[1] || cmd.info.aliases.contains(&path[1]))?;

        // Navigate through subcommands for remaining path elements
        for name in path.iter().skip(2) {
            current_cmd = current_cmd
                .subcommands
                .iter()
                .find(|cmd| cmd.info.name == *name || cmd.info.aliases.contains(name))?;
        }

        Some(current_cmd)
    }

    /// Get all top-level command names for error messages
    pub fn available_commands(&self) -> Vec<&str> {
        self.root
            .subcommands
            .iter()
            .map(|c| c.info.name.as_str())
            .collect()
    }

    /// Check the application configuration for errors
    ///
    /// This verifies that:
    /// - All leaf commands (commands without subcommands) have a run_fn set
    ///
    /// Returns Ok(()) if all checks pass, or Error with details of what's wrong.
    pub fn check(&self) -> Result<()> {
        let mut errors: Vec<String> = Vec::new();

        for cmd in &self.root.subcommands {
            check_command(cmd, &mut errors, vec![self.info.name.clone()]);
        }

        if errors.is_empty() {
            Ok(())
        } else {
            Err(Error::custom(format!(
                "Application configuration errors:\n{}",
                errors.join("\n")
            )))
        }
    }

    /// Print version information to stdout
    pub fn print_version(&self) {
        println!("{} {}", self.info.name, self.info.version);
    }

    /// Write version information to a writer
    pub fn write_version(&self, w: &mut dyn Write) -> Result<()> {
        writeln!(w, "{} {}", self.info.name, self.info.version)?;
        Ok(())
    }

    /// Print help information for the application
    pub fn print_help(&self) {
        self.print_help_for_path(std::slice::from_ref(&self.info.name));
    }

    /// Print help information for a specific command path
    pub fn print_help_for_path(&self, path: &[String]) {
        // Use stdout as default writer
        let _ = self.write_help_for_path(&mut std::io::stdout(), path);
    }

    /// Write help information for a specific command path to a writer
    pub fn write_help_for_path(&self, w: &mut dyn Write, path: &[String]) -> Result<()> {
        if path.is_empty() {
            return Ok(());
        }

        // If only app name in path, print app-level help
        if path.len() == 1 {
            self.write_app_help(w)?;
            return Ok(());
        }

        // Find the command and print its help
        if let Some(cmd) = self.find_command_by_path(path) {
            self.write_command_help(w, cmd, path)?;
        } else {
            // Fallback to app help if command not found
            self.write_app_help(w)?;
        }
        Ok(())
    }

    /// Write app-level help to a writer
    fn write_app_help(&self, w: &mut dyn Write) -> Result<()> {
        // Title/description
        if !self.info.title.is_empty() {
            writeln!(w, "{}", self.info.title)?;
        } else {
            writeln!(w, "{} {}", self.info.name, self.info.version)?;
        }

        if !self.info.description.is_empty() {
            writeln!(w)?;
            writeln!(w, "{}", self.info.description)?;
        }

        // Usage
        writeln!(w)?;
        writeln!(w, "Usage: {} <command> [options]", self.info.name)?;

        // Commands
        if !self.root.subcommands.is_empty() {
            writeln!(w)?;
            writeln!(w, "Commands:")?;
            for cmd in &self.root.subcommands {
                let desc = if !cmd.info.title.is_empty() {
                    &cmd.info.title
                } else {
                    &cmd.info.description
                };
                writeln!(w, "  {:20} {}", cmd.info.name, desc)?;
            }
        }

        // Global options hint
        writeln!(w)?;
        writeln!(w, "Options:")?;
        writeln!(w, "  {:20} Show help information", "-h, --help")?;
        writeln!(w, "  {:20} Show version information", "-V, --version")?;
        Ok(())
    }

    /// Write command-level help to a writer
    fn write_command_help(&self, w: &mut dyn Write, cmd: &Command, path: &[String]) -> Result<()> {
        // Title/description
        if !cmd.info.title.is_empty() {
            writeln!(w, "{}", cmd.info.title)?;
        } else {
            writeln!(w, "{}", path.join(" "))?;
        }

        if !cmd.info.description.is_empty() {
            writeln!(w)?;
            writeln!(w, "{}", cmd.info.description)?;
        }

        // Usage
        writeln!(w)?;
        let usage_path = path.join(" ");
        if cmd.subcommands.is_empty() {
            writeln!(w, "Usage: {} [options] [arguments]", usage_path)?;
        } else {
            writeln!(w, "Usage: {} <command> [options]", usage_path)?;
        }

        // Subcommands
        if !cmd.subcommands.is_empty() {
            writeln!(w)?;
            writeln!(w, "Commands:")?;
            for subcmd in &cmd.subcommands {
                let desc = if !subcmd.info.title.is_empty() {
                    &subcmd.info.title
                } else {
                    &subcmd.info.description
                };
                writeln!(w, "  {:20} {}", subcmd.info.name, desc)?;
            }
        }

        // Arguments and options
        let positional: Vec<_> = cmd
            .args
            .iter()
            .filter(|a| matches!(a.info.kind, crate::ArgKind::Positional))
            .collect();
        let options: Vec<_> = cmd
            .args
            .iter()
            .filter(|a| !matches!(a.info.kind, crate::ArgKind::Positional))
            .collect();

        if !positional.is_empty() {
            writeln!(w)?;
            writeln!(w, "Arguments:")?;
            for arg in positional {
                let required_marker = if arg.info.schema.required {
                    " (required)"
                } else {
                    ""
                };
                writeln!(
                    w,
                    "  {:20} {}{}",
                    arg.info.name, arg.info.description, required_marker
                )?;
            }
        }

        if !options.is_empty() {
            writeln!(w)?;
            writeln!(w, "Options:")?;
            for arg in options {
                let (short, long) = match &arg.info.kind {
                    crate::ArgKind::Flag { short, long, .. }
                    | crate::ArgKind::Option { short, long, .. } => {
                        let short_str = short.map(|c| format!("-{}, ", c)).unwrap_or_default();
                        let long_str = format!("--{}", long);
                        (short_str, long_str)
                    }
                    crate::ArgKind::Positional => (String::new(), String::new()),
                };
                let flag_str = format!("{}{}", short, long);
                writeln!(w, "  {:20} {}", flag_str, arg.info.description)?;
            }
        }

        // Global options hint
        writeln!(w)?;
        writeln!(w, "  {:20} Show help information", "-h, --help")?;
        Ok(())
    }
}

/// Recursively check a command and its subcommands
fn check_command(cmd: &Command, errors: &mut Vec<String>, mut path: Vec<String>) {
    path.push(cmd.info.name.clone());
    let path_str = path.join(" ");

    if cmd.is_leaf() && cmd.hooks.run_fn.is_none() {
        errors.push(format!("Leaf command '{}' has no run function", path_str));
    }

    for subcmd in &cmd.subcommands {
        check_command(subcmd, errors, path.clone());
    }
}