metarepo-core 0.77.0

use anyhow::Result;
use clap::{Arg, ArgMatches, Command};
use std::collections::HashMap;

use crate::{BasePlugin, MetaPlugin, RuntimeConfig};

/// Type alias for command handlers
type CommandHandler = Box<dyn Fn(&ArgMatches, &RuntimeConfig) -> Result<()> + Send + Sync>;

/// Builder for creating plugins declaratively
pub struct PluginBuilder {
    name: String,
    version: String,
    description: String,
    help_description: Option<String>,
    author: String,
    experimental: bool,
    commands: Vec<CommandBuilder>,
    handlers: HashMap<String, CommandHandler>,
}

impl PluginBuilder {
    /// Create a new plugin builder
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            version: "0.1.0".to_string(),
            description: String::new(),
            help_description: None,
            author: String::new(),
            experimental: false,
            commands: Vec::new(),
            handlers: HashMap::new(),
        }
    }

    /// Set a long, man-page-style help description for the plugin's top-level
    /// command (`meta <plugin>`). Rendered as a `Description:` section on `--help`.
    pub fn help_description(mut self, text: impl Into<String>) -> Self {
        self.help_description = Some(text.into());
        self
    }

    /// Set plugin version
    pub fn version(mut self, version: impl Into<String>) -> Self {
        self.version = version.into();
        self
    }

    /// Set plugin description
    pub fn description(mut self, desc: impl Into<String>) -> Self {
        self.description = desc.into();
        self
    }

    /// Set plugin author
    pub fn author(mut self, author: impl Into<String>) -> Self {
        self.author = author.into();
        self
    }

    /// Mark plugin as experimental
    pub fn experimental(mut self, experimental: bool) -> Self {
        self.experimental = experimental;
        self
    }

    /// Add a command to the plugin
    pub fn command(mut self, builder: CommandBuilder) -> Self {
        self.commands.push(builder);
        self
    }

    /// Add a handler for a specific command
    pub fn handler<F>(mut self, command: impl Into<String>, handler: F) -> Self
    where
        F: Fn(&ArgMatches, &RuntimeConfig) -> Result<()> + Send + Sync + 'static,
    {
        self.handlers.insert(command.into(), Box::new(handler));
        self
    }

    /// Build the plugin
    pub fn build(self) -> BuiltPlugin {
        BuiltPlugin {
            name: self.name,
            version: self.version,
            description: self.description,
            help_description: self.help_description,
            author: self.author,
            experimental: self.experimental,
            commands: self.commands,
            handlers: self.handlers,
        }
    }
}

/// A plugin built from the builder
pub struct BuiltPlugin {
    name: String,
    version: String,
    description: String,
    help_description: Option<String>,
    author: String,
    experimental: bool,
    commands: Vec<CommandBuilder>,
    handlers: HashMap<String, CommandHandler>,
}

impl BuiltPlugin {
    /// Apply the plugin-level `helpDescription` (if any) to its top command.
    fn with_help_description(&self, cmd: Command) -> Command {
        match &self.help_description {
            Some(desc) => {
                let rendered: &'static str =
                    Box::leak(format_help_description(desc).into_boxed_str());
                cmd.after_long_help(rendered)
            }
            None => cmd,
        }
    }
}

impl MetaPlugin for BuiltPlugin {
    fn name(&self) -> &str {
        &self.name
    }

    fn register_commands(&self, app: Command) -> Command {
        if self.commands.is_empty() {
            return app;
        }

        let name: &'static str = Box::leak(self.name.clone().into_boxed_str());
        let desc: &'static str = Box::leak(self.description.clone().into_boxed_str());
        let vers: &'static str = Box::leak(self.version.clone().into_boxed_str());

        let mut plugin_cmd = Command::new(name).about(desc).version(vers);
        plugin_cmd = self.with_help_description(plugin_cmd);

        for cmd_builder in &self.commands {
            plugin_cmd = plugin_cmd.subcommand(cmd_builder.build());
        }

        app.subcommand(plugin_cmd)
    }

    fn handle_command(&self, matches: &ArgMatches, config: &RuntimeConfig) -> Result<()> {
        // Find which subcommand was called
        if let Some((cmd_name, sub_matches)) = matches.subcommand() {
            // Look for a handler
            if let Some(handler) = self.handlers.get(cmd_name) {
                return handler(sub_matches, config);
            }

            // If no handler, show help
            println!("No handler registered for command: {}", cmd_name);
        }

        // Show help if no subcommand
        let mut help_cmd = self.build_help_command();
        help_cmd.print_help()?;
        Ok(())
    }

    fn is_experimental(&self) -> bool {
        self.experimental
    }
}

impl BuiltPlugin {
    fn build_help_command(&self) -> Command {
        let name: &'static str = Box::leak(self.name.clone().into_boxed_str());
        let desc: &'static str = Box::leak(self.description.clone().into_boxed_str());
        let vers: &'static str = Box::leak(self.version.clone().into_boxed_str());

        let mut plugin_cmd = Command::new(name).about(desc).version(vers);
        plugin_cmd = self.with_help_description(plugin_cmd);

        for cmd_builder in &self.commands {
            plugin_cmd = plugin_cmd.subcommand(cmd_builder.build());
        }

        with_standard_help(plugin_cmd)
    }
}

impl BasePlugin for BuiltPlugin {
    fn version(&self) -> Option<&str> {
        Some(&self.version)
    }

    fn description(&self) -> Option<&str> {
        Some(&self.description)
    }

    fn author(&self) -> Option<&str> {
        Some(&self.author)
    }
}

/// Builder for individual commands
pub struct CommandBuilder {
    name: String,
    about: String,
    long_about: Option<String>,
    help_description: Option<String>,
    aliases: Vec<String>,
    args: Vec<ArgBuilder>,
    subcommands: Vec<CommandBuilder>,
    allow_external_subcommands: bool,
}

impl CommandBuilder {
    /// Create a new command builder
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            about: String::new(),
            long_about: None,
            help_description: None,
            aliases: Vec::new(),
            args: Vec::new(),
            subcommands: Vec::new(),
            allow_external_subcommands: false,
        }
    }

    /// Set a long, man-page-style help description for this command. Rendered as a
    /// `Description:` section below Options/Commands on `--help` (not `-h`).
    pub fn help_description(mut self, text: impl Into<String>) -> Self {
        self.help_description = Some(text.into());
        self
    }

    /// Set command description
    pub fn about(mut self, about: impl Into<String>) -> Self {
        self.about = about.into();
        self
    }

    /// Set long command description
    pub fn long_about(mut self, long_about: impl Into<String>) -> Self {
        self.long_about = Some(long_about.into());
        self
    }

    /// Add command alias
    pub fn alias(mut self, alias: impl Into<String>) -> Self {
        self.aliases.push(alias.into());
        self
    }

    /// Add command aliases
    pub fn aliases(mut self, aliases: Vec<String>) -> Self {
        self.aliases.extend(aliases);
        self
    }

    /// Add an argument
    pub fn arg(mut self, arg: ArgBuilder) -> Self {
        self.args.push(arg);
        self
    }

    /// Add a subcommand
    pub fn subcommand(mut self, cmd: CommandBuilder) -> Self {
        self.subcommands.push(cmd);
        self
    }

    /// Allow external subcommands (for commands like exec that need to pass through arbitrary commands)
    pub fn allow_external_subcommands(mut self, allow: bool) -> Self {
        self.allow_external_subcommands = allow;
        self
    }

    /// Add standard help formatting options (--output-format, --ai)
    /// Use this for commands that support structured help output
    /// NOTE: This method is now deprecated and does nothing. It's kept for backward compatibility.
    pub fn with_help_formatting(self) -> Self {
        // No longer adds any arguments
        self
    }

    /// Build the clap Command
    fn build(&self) -> Command {
        let name: &'static str = Box::leak(self.name.clone().into_boxed_str());
        let about: &'static str = Box::leak(self.about.clone().into_boxed_str());

        let mut cmd = Command::new(name)
            .about(about)
            .version(env!("CARGO_PKG_VERSION"));

        if let Some(ref long_about) = self.long_about {
            let long_about_str: &'static str = Box::leak(long_about.clone().into_boxed_str());
            cmd = cmd.long_about(long_about_str);
        }

        if let Some(ref desc) = self.help_description {
            let rendered: &'static str = Box::leak(format_help_description(desc).into_boxed_str());
            cmd = cmd.after_long_help(rendered);
        }

        if !self.aliases.is_empty() {
            let aliases: Vec<&'static str> = self
                .aliases
                .iter()
                .map(|s| Box::leak(s.clone().into_boxed_str()) as &'static str)
                .collect();
            cmd = cmd.visible_aliases(aliases);
        }

        for arg_builder in &self.args {
            cmd = cmd.arg(arg_builder.build());
        }

        for subcmd_builder in &self.subcommands {
            cmd = cmd.subcommand(subcmd_builder.build());
        }

        if self.allow_external_subcommands {
            // A command that forwards arbitrary external subcommands (e.g. `exec`)
            // must not let clap's built-in `help` subcommand swallow a real
            // command named `help` — keep it disabled here.
            cmd = cmd
                .allow_external_subcommands(true)
                .disable_help_subcommand(true);
        }

        cmd
    }
}

/// Builder for arguments
pub struct ArgBuilder {
    name: String,
    short: Option<char>,
    long: Option<String>,
    help: Option<String>,
    required: bool,
    takes_value: bool,
    default_value: Option<String>,
    possible_values: Vec<String>,
}

impl ArgBuilder {
    /// Create a new argument builder
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            short: None,
            long: None,
            help: None,
            required: false,
            takes_value: false,
            default_value: None,
            possible_values: Vec::new(),
        }
    }

    /// Set short flag
    pub fn short(mut self, short: char) -> Self {
        self.short = Some(short);
        self
    }

    /// Set long flag
    pub fn long(mut self, long: impl Into<String>) -> Self {
        self.long = Some(long.into());
        self
    }

    /// Set help text
    pub fn help(mut self, help: impl Into<String>) -> Self {
        self.help = Some(help.into());
        self
    }

    /// Mark as required
    pub fn required(mut self, required: bool) -> Self {
        self.required = required;
        self
    }

    /// Set whether argument takes a value
    pub fn takes_value(mut self, takes: bool) -> Self {
        self.takes_value = takes;
        self
    }

    /// Set default value
    pub fn default_value(mut self, value: impl Into<String>) -> Self {
        self.default_value = Some(value.into());
        self
    }

    /// Add possible value
    pub fn possible_value(mut self, value: impl Into<String>) -> Self {
        self.possible_values.push(value.into());
        self
    }

    /// Build the clap Arg
    fn build(&self) -> Arg {
        let name: &'static str = Box::leak(self.name.clone().into_boxed_str());
        let mut arg = Arg::new(name);

        if let Some(short) = self.short {
            arg = arg.short(short);
        }

        if let Some(ref long) = self.long {
            let long_str: &'static str = Box::leak(long.clone().into_boxed_str());
            arg = arg.long(long_str);
        }

        if let Some(ref help) = self.help {
            let help_str: &'static str = Box::leak(help.clone().into_boxed_str());
            arg = arg.help(help_str);
        }

        if self.required {
            arg = arg.required(true);
        }

        if self.takes_value {
            arg = arg.action(clap::ArgAction::Set);
        } else {
            arg = arg.action(clap::ArgAction::SetTrue);
        }

        if let Some(ref default) = self.default_value {
            let default_str: &'static str = Box::leak(default.clone().into_boxed_str());
            arg = arg.default_value(default_str);
        }

        if !self.possible_values.is_empty() {
            let values: Vec<&'static str> = self
                .possible_values
                .iter()
                .map(|s| Box::leak(s.clone().into_boxed_str()) as &'static str)
                .collect();
            arg = arg.value_parser(values);
        }

        arg
    }
}

/// Apply the standard meta help layout to a command and all of its
/// subcommands, recursively.
///
/// clap's default help renders the Commands section *before* Options, but the
/// top-level `meta` command shows Options first and Commands last. This helper
/// makes every subcommand match that ordering: Usage, Arguments (if any),
/// Options, then Commands (if any). Empty sections are omitted so leaf commands
/// don't print a stray "Commands:" header.
pub fn with_standard_help(cmd: Command) -> Command {
    // Recurse into children first so the whole tree is consistent, and order
    // every Commands section shortest-name-first (ties alphabetical) by setting
    // each subcommand's display order to its name length. clap sorts by display
    // order ascending, breaking ties alphabetically.
    let cmd = cmd.mut_subcommands(|sub| {
        let order = sub.get_name().chars().count();
        with_standard_help(sub).display_order(order)
    });

    let mut template = String::from("{about-with-newline}\n{usage-heading} {usage}\n");
    if cmd.get_positionals().next().is_some() {
        template.push_str("\n\x1b[1;96mArguments:\x1b[0m\n{positionals}\n");
    }
    template.push_str("\n\x1b[1;96mOptions:\x1b[0m\n{options}\n");
    if cmd.has_subcommands() {
        template.push_str("\n\x1b[1;96mCommands:\x1b[0m\n{subcommands}");
    }
    template.push_str("{after-help}");

    cmd.help_template(template)
}

/// Render a plugin/command `helpDescription` into the man-page-style section that
/// clap drops at the `{after-help}` slot of [`with_standard_help`] on `--help`.
///
/// The header is styled to match the other section headers (bold bright cyan) and
/// each body line is indented two spaces, so a multi-paragraph description reads
/// like the DESCRIPTION block of a man page.
pub fn format_help_description(body: &str) -> String {
    let mut out = String::from("\n\x1b[1;96mDescription:\x1b[0m\n");
    for line in body.lines() {
        if line.is_empty() {
            out.push('\n');
        } else {
            out.push_str("  ");
            out.push_str(line);
            out.push('\n');
        }
    }
    out
}

/// Convenience function to create a new plugin builder
pub fn plugin(name: impl Into<String>) -> PluginBuilder {
    PluginBuilder::new(name)
}

/// Convenience function to create a new command builder
pub fn command(name: impl Into<String>) -> CommandBuilder {
    CommandBuilder::new(name)
}

/// Convenience function to create a new argument builder
pub fn arg(name: impl Into<String>) -> ArgBuilder {
    ArgBuilder::new(name)
}

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

    #[test]
    fn test_plugin_builder_basic() {
        let plugin = plugin("test-plugin")
            .version("1.0.0")
            .description("Test plugin")
            .author("Test Author")
            .experimental(true)
            .build();

        assert_eq!(plugin.name(), "test-plugin");
        assert_eq!(plugin.version(), Some("1.0.0"));
        assert_eq!(plugin.description(), Some("Test plugin"));
        assert_eq!(plugin.author(), Some("Test Author"));
        assert!(plugin.is_experimental());
    }

    #[test]
    fn test_plugin_builder_with_commands() {
        let test_handler =
            |_matches: &ArgMatches, _config: &RuntimeConfig| -> Result<()> { Ok(()) };

        let plugin = plugin("test-plugin")
            .command(
                command("test-cmd").about("Test command").arg(
                    arg("input")
                        .short('i')
                        .long("input")
                        .help("Input file")
                        .takes_value(true),
                ),
            )
            .handler("test-cmd", test_handler)
            .build();

        let app = Command::new("test");
        let app_with_plugin = plugin.register_commands(app);

        // Check that the plugin command was added
        let plugin_cmd = app_with_plugin.find_subcommand("test-plugin");
        assert!(plugin_cmd.is_some());

        let plugin_cmd = plugin_cmd.unwrap();
        let test_cmd = plugin_cmd.find_subcommand("test-cmd");
        assert!(test_cmd.is_some());
    }

    #[test]
    fn test_command_builder() {
        let cmd = command("test")
            .about("Test command")
            .long_about("This is a longer description")
            .aliases(vec!["t".to_string(), "tst".to_string()])
            .arg(
                arg("verbose")
                    .short('v')
                    .long("verbose")
                    .help("Enable verbose output"),
            )
            .build();

        assert_eq!(cmd.get_name(), "test");
        assert_eq!(
            cmd.get_about().map(|s| s.to_string()),
            Some("Test command".to_string())
        );
        assert_eq!(
            cmd.get_long_about().map(|s| s.to_string()),
            Some("This is a longer description".to_string())
        );

        // Check aliases
        let aliases: Vec<&str> = cmd.get_visible_aliases().collect();
        assert!(aliases.contains(&"t"));
        assert!(aliases.contains(&"tst"));

        // Check arguments
        let verbose_arg = cmd.get_arguments().find(|a| a.get_id() == "verbose");
        assert!(verbose_arg.is_some());
    }

    #[test]
    fn test_arg_builder_flag() {
        let arg = arg("verbose")
            .short('v')
            .long("verbose")
            .help("Enable verbose output")
            .build();

        assert_eq!(arg.get_id().to_string(), "verbose");
        assert_eq!(arg.get_short(), Some('v'));
        assert_eq!(arg.get_long(), Some("verbose"));
        assert_eq!(
            arg.get_help().map(|s| s.to_string()),
            Some("Enable verbose output".to_string())
        );
    }

    #[test]
    fn test_arg_builder_with_value() {
        let arg = arg("input")
            .long("input")
            .help("Input file")
            .required(true)
            .takes_value(true)
            .default_value("default.txt")
            .build();

        assert_eq!(arg.get_id().to_string(), "input");
        assert_eq!(arg.get_long(), Some("input"));
        assert!(arg.is_required_set());
        assert_eq!(arg.get_default_values(), &["default.txt"]);
    }

    #[test]
    fn test_arg_builder_with_possible_values() {
        let arg = arg("format")
            .long("format")
            .help("Output format")
            .takes_value(true)
            .possible_value("json")
            .possible_value("yaml")
            .possible_value("text")
            .build();

        assert_eq!(arg.get_id().to_string(), "format");
        // Note: Testing possible values would require checking the value parser
        // which is not directly accessible from the Arg struct
    }

    #[test]
    fn test_command_builder_with_subcommands() {
        let cmd = command("parent")
            .about("Parent command")
            .subcommand(command("child1").about("First child"))
            .subcommand(
                command("child2")
                    .about("Second child")
                    .arg(arg("option").long("option").takes_value(true)),
            )
            .build();

        assert_eq!(cmd.get_name(), "parent");

        let child1 = cmd.find_subcommand("child1");
        assert!(child1.is_some());
        assert_eq!(
            child1.unwrap().get_about().map(|s| s.to_string()),
            Some("First child".to_string())
        );

        let child2 = cmd.find_subcommand("child2");
        assert!(child2.is_some());
        let child2 = child2.unwrap();
        assert_eq!(
            child2.get_about().map(|s| s.to_string()),
            Some("Second child".to_string())
        );

        let option_arg = child2.get_arguments().find(|a| a.get_id() == "option");
        assert!(option_arg.is_some());
    }

    #[test]
    fn test_command_builder_external_subcommands() {
        let cmd = command("exec")
            .about("Execute commands")
            .allow_external_subcommands(true)
            .build();

        assert_eq!(cmd.get_name(), "exec");
        assert!(cmd.is_allow_external_subcommands_set());
    }

    #[test]
    fn test_plugin_handler_execution() {
        use std::sync::atomic::{AtomicBool, Ordering};
        use std::sync::Arc;

        let executed = Arc::new(AtomicBool::new(false));
        let executed_clone = executed.clone();

        let test_handler = move |_matches: &ArgMatches, _config: &RuntimeConfig| -> Result<()> {
            executed_clone.store(true, Ordering::SeqCst);
            Ok(())
        };

        let plugin = plugin("test-plugin")
            .command(command("test-cmd").about("Test command"))
            .handler("test-cmd", test_handler)
            .build();

        // Create mock matches for the plugin and its test-cmd subcommand
        // The plugin expects matches to have the subcommand structure
        let app = Command::new("test-plugin").subcommand(Command::new("test-cmd"));
        let matches = app
            .clone()
            .get_matches_from(vec!["test-plugin", "test-cmd"]);

        // Create a dummy runtime config
        let config = RuntimeConfig {
            meta_config: crate::MetaConfig::default(),
            working_dir: std::path::PathBuf::from("."),
            meta_file_path: None,
            experimental: false,
            non_interactive: None,
            scope_workspace: false,
            settings_catalog: Vec::new(),
        };

        // Handle the command - the plugin will look for subcommands in the matches
        plugin.handle_command(&matches, &config).unwrap();

        // Check that the handler was executed
        assert!(executed.load(Ordering::SeqCst));
    }
}