cli_engine/

cli.rs

use std::{
    collections::{BTreeMap, BTreeSet},
    future::Future,
    io::Write,
    path::{Path, PathBuf},
    process::ExitCode,
    sync::{Arc, Mutex},
    time::Duration,
};

mod builtins;
mod help;
mod tree_render;

use clap::{ArgMatches, Command};

use crate::{
    ActivityEmitter, Auditor, AuthProvider, Authorizer, CliCoreError, CommandMeta, CommandSpec,
    GroupSpec, GuideEntry, Middleware, MiddlewareRequest, Result, RuntimeCommandSpec,
    RuntimeGroupSpec,
    auth::commands::auth_command_group,
    command::{
        CommandContext, StreamSender, command_args_from_matches, command_path_from_matches,
        leaf_matches,
    },
    error::exit_code_for_error,
    flags::{
        GlobalFlags, default_output_format, derive_bool_flags, derive_value_flags,
        extract_command_path, extract_output_format, extract_search_query,
        global_flags_from_matches, has_true_schema_flag, register_global_flags,
    },
    guide::guide_content,
    module::{Module, ModuleContext},
    output::{
        HumanViewDef, NextAction, SchemaRegistry, format_help_section,
        global_human_view_registry_snapshot, global_schema_registry_snapshot,
    },
    search::{SearchDocument, SearchIndex},
};

use builtins::{guide_args, guide_command, help_args, help_command};
use help::{GROUP_HELP_TEMPLATE, ROOT_HELP_TEMPLATE};
pub use help::{ModuleHelpEntry, build_root_long, render_next_actions_human};

/// Build metadata shown by the root `--version` flag.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct BuildInfo {
    /// Semantic version or other release label.
    pub version: String,
    /// Optional source control commit identifier.
    pub commit: Option<String>,
    /// Optional build date string.
    pub date: Option<String>,
}

impl BuildInfo {
    /// Creates build metadata with only a version string.
    #[must_use]
    pub fn new(version: impl Into<String>) -> Self {
        Self {
            version: version.into(),
            commit: None,
            date: None,
        }
    }

    /// Adds a commit identifier to the version string shown by `--version`.
    #[must_use]
    pub fn with_commit(mut self, commit: impl Into<String>) -> Self {
        self.commit = Some(commit.into());
        self
    }

    /// Adds a build date to the version string shown by `--version`.
    #[must_use]
    pub fn with_date(mut self, date: impl Into<String>) -> Self {
        self.date = Some(date.into());
        self
    }

    /// Returns the rendered version string used by the root `--version` flag.
    #[must_use]
    pub fn version_string(&self) -> String {
        let commit = self.commit.as_deref().unwrap_or_default();
        let date = self.date.as_deref().unwrap_or_default();

        if commit.is_empty() && date.is_empty() {
            self.version.clone()
        } else {
            format!("{} (commit {commit}, built {date})", self.version)
        }
    }
}

/// Late dependency initializer run once before real command execution.
pub type InitDeps = Arc<dyn Fn(&mut Middleware) -> Result<()> + Send + Sync>;
/// Hook used to add application-specific global flags to the root `clap` command.
pub type RegisterFlags = Arc<dyn Fn(Command) -> Command + Send + Sync>;
/// Hook used to copy parsed application-specific flags into middleware.
pub type ApplyFlags = Arc<dyn Fn(&ArgMatches, &mut Middleware) -> Result<()> + Send + Sync>;
/// Hook run immediately before executable commands and built-ins.
pub type PreRun =
    Arc<dyn Fn(&mut Middleware, &str, &crate::middleware::ValueMap) -> Result<()> + Send + Sync>;
/// Hook used to adjust command metadata globally before middleware executes.
pub type ResolveMeta = Arc<dyn Fn(&str, CommandMeta) -> CommandMeta + Send + Sync>;
/// Hook called after a CLI run completes.
pub type OnShutdown = Arc<dyn Fn() + Send + Sync>;
/// Hook that contributes extra root-scope `--search` documents.
pub type ExtraSearchDocs = Arc<dyn Fn() -> Vec<SearchDocument> + Send + Sync>;
/// Hook that supplies the suggested next actions shown when the CLI is invoked
/// with no subcommand (bare root). The same actions drive a human "Next actions"
/// section and the JSON discovery envelope.
pub type RootNextActions = Arc<dyn Fn() -> Vec<NextAction> + Send + Sync>;

/// Default name for the admin help category, under which the engine files the
/// built-in `auth` command when a consumer does not override it via
/// [`CliConfig::with_admin_category`].
const DEFAULT_ADMIN_CATEGORY: &str = "Admin";

/// Maximum number of chained `argv0` dispatch hand-offs before the engine
/// refuses to recurse further. Real multi-call nesting is zero or one level;
/// this bounds a pathologically long explicit `argv0 … argv0 …` chain so it
/// errors cleanly instead of overflowing the stack.
const MAX_ARGV0_DEPTH: usize = 16;

/// How the engine behaves when invoked under a registered alternative `argv[0]`
/// name (busybox/git-style multi-call dispatch).
///
/// A route is selected when the binary's `argv[0]` basename — or the name given
/// to the hidden `argv0` command — matches a key registered via
/// [`CliConfig::with_argv0_alias`] or [`CliConfig::with_argv0_personality`]. An
/// `argv[0]` that matches no route falls through to the default CLI, so existing
/// applications that register no routes are unaffected.
///
/// Non-exhaustive: more route kinds may be added in future releases. Register
/// routes through the [`CliConfig`] builders rather than matching on variants.
#[derive(Clone)]
#[non_exhaustive]
pub enum Argv0Route {
    /// Rewrite the invocation into these canonical subcommand tokens and run it
    /// through the normal command tree, with the real argument tail appended.
    ///
    /// For example, an `Alias(vec!["project".into(), "list".into()])` registered
    /// under `pl` makes `pl --team x` behave exactly like `project list --team x`.
    Alias(Vec<String>),
    /// Run an entirely separate CLI application built from the returned
    /// [`CliConfig`] (its own root name, commands, flags, and auth). The
    /// configuration is built lazily, only when the route is actually dispatched,
    /// so registering a personality costs nothing for invocations that never hit it.
    Personality(Arc<dyn Fn() -> CliConfig + Send + Sync>),
}

impl std::fmt::Debug for Argv0Route {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Alias(tokens) => formatter.debug_tuple("Alias").field(tokens).finish(),
            Self::Personality(_) => formatter.write_str("Personality(..)"),
        }
    }
}

/// On-disk mechanism used by [`Cli::create_link`] to materialize an alternative
/// `argv[0]` name so the binary can be invoked under it.
///
/// Installers pick the mechanism that suits the platform and environment;
/// self-healing code can re-run [`Cli::create_link`] to restore a deleted link.
///
/// Non-exhaustive: more link mechanisms may be added in future releases.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum Argv0LinkMethod {
    /// A symbolic link to the target executable (`<name>` on Unix, `<name>.exe`
    /// on Windows). On Windows this may require Developer Mode or elevation.
    SoftLink,
    /// A hard link to the target executable (`<name>` on Unix, `<name>.exe` on
    /// Windows). The link must live on the same volume as the target.
    HardLink,
    /// A small shim script that forwards to the target via the `argv0` command:
    /// a `<name>.cmd` batch file on Windows, or an executable `<name>` shell
    /// script on Unix. Useful when links are unavailable or inconvenient.
    Script,
}

/// Declarative configuration for a CLI application.
///
/// Use [`CliConfig::new`] for the common path and chain `with_*` methods for
/// modules, auth providers, guides, views, and lifecycle hooks. Direct struct
/// literals remain available for advanced setup and tests.
#[derive(Clone, Default)]
pub struct CliConfig {
    /// Root command name shown in usage output.
    pub name: String,
    /// One-line root command description.
    pub short: String,
    /// Optional longer root command description. Defaults to `short`.
    pub long: Option<String>,
    /// Version/build metadata for `--version`.
    pub build: BuildInfo,
    /// Application id stored in middleware and output metadata.
    pub app_id: String,
    /// Fallback auth provider when a command does not select one explicitly.
    pub default_auth_provider: Option<String>,
    /// Domain modules mounted under the root command.
    pub modules: Vec<Module>,
    /// Additional top-level runtime commands.
    pub commands: Vec<RuntimeCommandSpec>,
    /// Global guide entries mounted under `guide`.
    pub guides: Vec<GuideEntry>,
    /// Global human output views.
    pub views: Vec<HumanViewDef>,
    /// Providers registered before command execution starts.
    pub auth_providers: Vec<Arc<dyn AuthProvider>>,
    /// Optional authorization gatekeeper injected into middleware.
    pub authz: Option<Arc<dyn Authorizer>>,
    /// Optional audit recorder injected into middleware.
    pub auditor: Option<Arc<dyn Auditor>>,
    /// Optional activity event sink injected into middleware.
    pub activity: Option<Arc<dyn ActivityEmitter>>,
    /// Optional late initializer for runtime dependencies.
    pub init_deps: Option<InitDeps>,
    /// Optional hook for adding application-specific global flags.
    pub register_flags: Option<RegisterFlags>,
    /// Optional hook for applying parsed application-specific flags.
    pub apply_flags: Option<ApplyFlags>,
    /// Optional hook run before executable commands and built-ins.
    pub pre_run: Option<PreRun>,
    /// Optional hook for global command metadata adjustments.
    pub meta_resolver: Option<ResolveMeta>,
    /// Optional hook called after each run.
    pub on_shutdown: Option<OnShutdown>,
    /// Optional root-scope search document provider.
    pub extra_search_docs: Option<ExtraSearchDocs>,
    /// Optional provider for the bare-root suggested next actions.
    pub root_next_actions: Option<RootNextActions>,
    /// Name of the admin help category. The engine files its built-in `auth`
    /// command under this heading; apps should use the same name for their own
    /// admin modules (e.g. godaddy's `env`). When unset, defaults to `"Admin"`;
    /// set it to match a consumer's own taxonomy (e.g. gdx's "Administration").
    pub admin_category: Option<String>,
    /// Alternative `argv[0]` names this binary may be invoked as, mapped to the
    /// behavior the engine should take (busybox/git-style multi-call dispatch).
    ///
    /// Keyed by the bare alternative name (no path, no extension). Empty by
    /// default, in which case argv0 dispatch is inert and behavior is identical
    /// to a binary that never opted in. Populate via [`CliConfig::with_argv0_alias`]
    /// and [`CliConfig::with_argv0_personality`].
    pub argv0_routes: BTreeMap<String, Argv0Route>,
}

impl CliConfig {
    /// Creates the minimum useful CLI configuration.
    #[must_use]
    pub fn new(
        name: impl Into<String>,
        short: impl Into<String>,
        app_id: impl Into<String>,
    ) -> Self {
        Self {
            name: name.into(),
            short: short.into(),
            app_id: app_id.into(),
            ..Self::default()
        }
    }

    /// Sets root long help text.
    #[must_use]
    pub fn with_long(mut self, long: impl Into<String>) -> Self {
        self.long = Some(long.into());
        self
    }

    /// Sets build metadata used by `--version`.
    #[must_use]
    pub fn with_build(mut self, build: BuildInfo) -> Self {
        self.build = build;
        self
    }

    /// Sets the fallback auth provider for commands that do not name one.
    #[must_use]
    pub fn with_default_auth_provider(mut self, provider: impl Into<String>) -> Self {
        self.default_auth_provider = Some(provider.into());
        self
    }

    /// Adds one domain module.
    #[must_use]
    pub fn with_module(mut self, module: Module) -> Self {
        self.modules.push(module);
        self
    }

    /// Adds several domain modules.
    #[must_use]
    pub fn with_modules(mut self, modules: impl IntoIterator<Item = Module>) -> Self {
        self.modules.extend(modules);
        self
    }

    /// Adds a top-level runtime command outside a module.
    #[must_use]
    pub fn with_command(mut self, command: RuntimeCommandSpec) -> Self {
        self.commands.push(command);
        self
    }

    /// Adds one global guide.
    #[must_use]
    pub fn with_guide(mut self, guide: GuideEntry) -> Self {
        self.guides.push(guide);
        self
    }

    /// Adds several global guides.
    #[must_use]
    pub fn with_guides(mut self, guides: impl IntoIterator<Item = GuideEntry>) -> Self {
        self.guides.extend(guides);
        self
    }

    /// Adds one global human view.
    #[must_use]
    pub fn with_view(mut self, view: HumanViewDef) -> Self {
        self.views.push(view);
        self
    }

    /// Registers one auth provider.
    #[must_use]
    pub fn with_auth_provider(mut self, provider: Arc<dyn AuthProvider>) -> Self {
        self.auth_providers.push(provider);
        self
    }

    /// Sets the authorization gatekeeper.
    #[must_use]
    pub fn with_authz(mut self, authz: Arc<dyn Authorizer>) -> Self {
        self.authz = Some(authz);
        self
    }

    /// Sets the audit recorder.
    #[must_use]
    pub fn with_auditor(mut self, auditor: Arc<dyn Auditor>) -> Self {
        self.auditor = Some(auditor);
        self
    }

    /// Sets the activity event sink.
    #[must_use]
    pub fn with_activity(mut self, activity: Arc<dyn ActivityEmitter>) -> Self {
        self.activity = Some(activity);
        self
    }

    /// Sets the late dependency initializer.
    #[must_use]
    pub fn with_init_deps(mut self, init_deps: InitDeps) -> Self {
        self.init_deps = Some(init_deps);
        self
    }

    /// Sets the application-specific global flag registration hook.
    #[must_use]
    pub fn with_register_flags(mut self, register_flags: RegisterFlags) -> Self {
        self.register_flags = Some(register_flags);
        self
    }

    /// Sets the application-specific parsed flag application hook.
    #[must_use]
    pub fn with_apply_flags(mut self, apply_flags: ApplyFlags) -> Self {
        self.apply_flags = Some(apply_flags);
        self
    }

    /// Sets the pre-run hook.
    #[must_use]
    pub fn with_pre_run(mut self, pre_run: PreRun) -> Self {
        self.pre_run = Some(pre_run);
        self
    }

    /// Sets the command metadata resolver hook.
    #[must_use]
    pub fn with_meta_resolver(mut self, meta_resolver: ResolveMeta) -> Self {
        self.meta_resolver = Some(meta_resolver);
        self
    }

    /// Sets the shutdown hook.
    #[must_use]
    pub fn with_on_shutdown(mut self, on_shutdown: OnShutdown) -> Self {
        self.on_shutdown = Some(on_shutdown);
        self
    }

    /// Sets the provider for additional root-scope search documents.
    #[must_use]
    pub fn with_extra_search_docs(mut self, extra_search_docs: ExtraSearchDocs) -> Self {
        self.extra_search_docs = Some(extra_search_docs);
        self
    }

    /// Sets the provider for the bare-root suggested next actions.
    #[must_use]
    pub fn with_root_next_actions(mut self, root_next_actions: RootNextActions) -> Self {
        self.root_next_actions = Some(root_next_actions);
        self
    }

    /// Sets the name of the admin help category. The engine files the built-in
    /// `auth` command there; apps should use the same name for their own admin
    /// modules (e.g. godaddy's `env`). Optional: defaults to `"Admin"`.
    #[must_use]
    pub fn with_admin_category(mut self, category: impl Into<String>) -> Self {
        self.admin_category = Some(category.into());
        self
    }

    /// Registers an alternative `argv[0]` name that acts as a shortcut to a
    /// command path on this same CLI.
    ///
    /// When the binary is invoked under `name` (via symlink, hardlink, copy, or
    /// the hidden `argv0` command), the engine behaves as if the user had typed
    /// `command_path` followed by the real argument tail, routed through the
    /// normal command tree. For example:
    ///
    /// ```
    /// use cli_engine::CliConfig;
    ///
    /// // Invoking the binary as `pl --team platform` runs `project list --team platform`.
    /// let config = CliConfig::new("my-cli", "Team CLI", "my-cli")
    ///     .with_argv0_alias("pl", ["project", "list"]);
    /// ```
    ///
    /// `name` must be a simple token: non-empty and composed only of ASCII
    /// letters, digits, `-`, or `_` (no dots, spaces, path separators, or shell
    /// metacharacters), and it must differ from the CLI's own name. These are
    /// debug-asserted. The restriction keeps the name usable as a link/shim
    /// filename and an `argv[0]` basename (which is matched with its extension
    /// stripped, so a dot would break matching).
    #[must_use]
    pub fn with_argv0_alias(
        mut self,
        name: impl Into<String>,
        command_path: impl IntoIterator<Item = impl Into<String>>,
    ) -> Self {
        let name = name.into();
        debug_assert!(
            is_valid_argv0_name(&name),
            "argv0 route name {name:?} must be non-empty and contain only ASCII letters, digits, '-', or '_'"
        );
        debug_assert!(
            name != self.name,
            "argv0 route name {name:?} must differ from the CLI's own name {:?}",
            self.name
        );
        let tokens = command_path.into_iter().map(Into::into).collect();
        self.argv0_routes.insert(name, Argv0Route::Alias(tokens));
        self
    }

    /// Registers an alternative `argv[0]` name that runs an entirely separate CLI
    /// application.
    ///
    /// When the binary is invoked under `name`, the engine builds a fresh
    /// [`CliConfig`] from `build` and runs that application instead — its own root
    /// name, commands, flags, and auth. The closure runs lazily, only when the
    /// route is dispatched, so unused personalities cost nothing. The personality
    /// presents the name from its own [`CliConfig`] in help and usage output.
    ///
    /// ```
    /// use cli_engine::CliConfig;
    ///
    /// let config = CliConfig::new("my-cli", "Team CLI", "my-cli")
    ///     .with_argv0_personality("legacy-tool", || {
    ///         CliConfig::new("legacy-tool", "Legacy compatibility shim", "legacy-tool")
    ///     });
    /// ```
    ///
    /// `name` follows the same contract as [`CliConfig::with_argv0_alias`]: a
    /// simple `[A-Za-z0-9_-]` token, differing from the CLI's own name
    /// (debug-asserted).
    #[must_use]
    pub fn with_argv0_personality(
        mut self,
        name: impl Into<String>,
        build: impl Fn() -> CliConfig + Send + Sync + 'static,
    ) -> Self {
        let name = name.into();
        debug_assert!(
            is_valid_argv0_name(&name),
            "argv0 route name {name:?} must be non-empty and contain only ASCII letters, digits, '-', or '_'"
        );
        debug_assert!(
            name != self.name,
            "argv0 route name {name:?} must differ from the CLI's own name {:?}",
            self.name
        );
        self.argv0_routes
            .insert(name, Argv0Route::Personality(Arc::new(build)));
        self
    }
}

impl std::fmt::Debug for CliConfig {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("CliConfig")
            .field("name", &self.name)
            .field("short", &self.short)
            .field("long", &self.long)
            .field("build", &self.build)
            .field("app_id", &self.app_id)
            .field("default_auth_provider", &self.default_auth_provider)
            .field("modules", &self.modules)
            .field("commands", &self.commands)
            .field("guides", &self.guides)
            .field("views", &self.views)
            .field("auth_providers_len", &self.auth_providers.len())
            .field("has_authz", &self.authz.is_some())
            .field("has_auditor", &self.auditor.is_some())
            .field("has_activity", &self.activity.is_some())
            .field("has_init_deps", &self.init_deps.is_some())
            .field("has_register_flags", &self.register_flags.is_some())
            .field("has_apply_flags", &self.apply_flags.is_some())
            .field("has_pre_run", &self.pre_run.is_some())
            .field("has_meta_resolver", &self.meta_resolver.is_some())
            .field("has_on_shutdown", &self.on_shutdown.is_some())
            .field("has_extra_search_docs", &self.extra_search_docs.is_some())
            .field("has_root_next_actions", &self.root_next_actions.is_some())
            .field("admin_category", &self.admin_category)
            .field(
                "argv0_routes",
                &self.argv0_routes.keys().collect::<Vec<_>>(),
            )
            .finish()
    }
}

/// Captured result of running a CLI in tests or embedding contexts.
#[derive(Clone, Debug, PartialEq)]
pub struct CliRunOutput {
    /// Process-style exit code.
    pub exit_code: i32,
    /// Rendered stdout or stderr payload.
    pub rendered: String,
}

impl From<crate::middleware::MiddlewareOutput> for CliRunOutput {
    fn from(o: crate::middleware::MiddlewareOutput) -> Self {
        Self {
            exit_code: o.exit_code,
            rendered: o.rendered,
        }
    }
}

/// Configured CLI application.
///
/// A `Cli` owns the `clap` command tree, middleware, registered runtime
/// commands, guides, schemas, and built-ins. Consumer binaries normally create
/// one `Cli` and call [`Cli::execute`].
#[derive(Clone)]
pub struct Cli {
    config: CliConfig,
    middleware: Middleware,
    root: Command,
    commands: BTreeMap<String, RuntimeCommandSpec>,
    module_entries: Vec<ModuleHelpEntry>,
    guide_entries: Vec<GuideEntry>,
    init_deps: Option<InitDeps>,
    apply_flags: Option<ApplyFlags>,
    pre_run: Option<PreRun>,
    meta_resolver: Option<ResolveMeta>,
    on_shutdown: Option<OnShutdown>,
    extra_search_docs: Option<ExtraSearchDocs>,
    root_next_actions: Option<RootNextActions>,
    init_state: Arc<Mutex<Option<std::result::Result<Middleware, InitFailure>>>>,
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct InitFailure {
    message: String,
    code: String,
    system: String,
    request_id: String,
    exit_code: i32,
}

impl InitFailure {
    fn capture(err: &CliCoreError) -> Self {
        let envelope = crate::output::build_error_envelope(err, "");
        let (code, system, request_id) = envelope.error.map_or_else(
            || ("ERROR".to_owned(), String::new(), String::new()),
            |error| (error.code, error.system, error.request_id),
        );
        Self {
            message: err.to_string(),
            code,
            system,
            request_id,
            exit_code: exit_code_for_error(err),
        }
    }

    fn into_error(self) -> CliCoreError {
        CliCoreError::with_exit_code(
            self.exit_code,
            CliCoreError::SystemMessage {
                message: self.message,
                system: self.system,
                code: self.code,
                request_id: self.request_id,
            },
        )
    }
}

impl std::fmt::Debug for Cli {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("Cli")
            .field("config", &self.config)
            .field("middleware", &self.middleware)
            .field("root", &self.root)
            .field("commands", &self.commands)
            .field("module_entries", &self.module_entries)
            .field("guide_entries", &self.guide_entries)
            .field("has_init_deps", &self.init_deps.is_some())
            .field("has_apply_flags", &self.apply_flags.is_some())
            .field("has_pre_run", &self.pre_run.is_some())
            .field("has_meta_resolver", &self.meta_resolver.is_some())
            .field("has_on_shutdown", &self.on_shutdown.is_some())
            .field("has_extra_search_docs", &self.extra_search_docs.is_some())
            .field("has_root_next_actions", &self.root_next_actions.is_some())
            .finish()
    }
}

impl Cli {
    /// Builds a CLI application from declarative configuration.
    #[must_use]
    pub fn new(config: CliConfig) -> Self {
        let auth_providers = config.auth_providers.clone();
        let guides = config.guides.clone();
        let views = config.views.clone();
        let modules = config.modules.clone();
        let commands = config.commands.clone();
        let init_deps = config.init_deps.clone();
        let apply_flags = config.apply_flags.clone();
        let pre_run = config.pre_run.clone();
        let meta_resolver = config.meta_resolver.clone();
        let on_shutdown = config.on_shutdown.clone();
        let extra_search_docs = config.extra_search_docs.clone();
        let root_next_actions = config.root_next_actions.clone();
        let mut root = Command::new(config.name.clone())
            .about(config.short.clone())
            .disable_help_subcommand(true)
            .version(config.build.version_string());
        if let Some(long) = &config.long
            && !long.is_empty()
        {
            root = root.long_about(long.clone());
        }
        root = register_global_flags(root)
            .subcommand(help_command())
            .subcommand(guide_command())
            .subcommand(Command::new("tree").about("Display full command tree"));
        if let Some(register_flags) = &config.register_flags {
            root = register_flags(root);
        }
        let intro = config
            .long
            .as_deref()
            .filter(|long| !long.is_empty())
            .unwrap_or(config.short.as_str());
        root = root
            .long_about(build_root_long(intro, &[], false))
            .help_template(ROOT_HELP_TEMPLATE);

        let mut middleware = Middleware::new();
        middleware.app_id = config.app_id.clone();
        middleware.default_auth_provider = config.default_auth_provider.clone().unwrap_or_default();
        middleware.authz = config.authz.clone();
        middleware.auditor = config.auditor.clone();
        middleware.activity = config.activity.clone();
        middleware
            .schema_registry
            .merge(&global_schema_registry_snapshot());
        middleware
            .human_views
            .merge(&global_human_view_registry_snapshot());

        let mut cli = Self {
            config,
            middleware,
            root,
            commands: BTreeMap::new(),
            module_entries: Vec::new(),
            guide_entries: Vec::new(),
            init_deps,
            apply_flags,
            pre_run,
            meta_resolver,
            on_shutdown,
            extra_search_docs,
            root_next_actions,
            init_state: Arc::new(Mutex::new(None)),
        };
        for provider in auth_providers {
            cli.register_auth_provider(provider);
        }
        if cli.middleware.default_auth_provider.is_empty()
            && let Some(provider) = cli.middleware.auth.registered_names().first()
        {
            cli.middleware.default_auth_provider = provider.clone();
        }
        if !cli.middleware.default_auth_provider.is_empty() {
            cli.ensure_auth_command();
        }
        for view in views {
            cli.middleware.human_views.register(view);
        }
        cli.add_guides(guides);
        for module in modules {
            cli.add_module(module);
        }
        for command in commands {
            cli.add_command(command);
        }
        cli
    }

    /// Lists the auto-registered `auth` command under the admin help category so
    /// it is never uncategorized once clap's auto subcommand list is suppressed.
    /// Defaults to [`DEFAULT_ADMIN_CATEGORY`]; `admin_category` overrides it to
    /// align with a consumer's own taxonomy.
    fn register_auth_help_entry(&mut self) {
        let category = self
            .config
            .admin_category
            .clone()
            .unwrap_or_else(|| DEFAULT_ADMIN_CATEGORY.to_owned());
        let already_listed = self.module_entries.iter().any(|entry| entry.name == "auth");
        let short = self
            .root
            .find_subcommand("auth")
            .filter(|auth| !auth.is_hide_set())
            .map(|auth| {
                auth.get_about()
                    .map(ToString::to_string)
                    .unwrap_or_default()
            });
        if !already_listed && let Some(short) = short {
            self.module_entries.push(ModuleHelpEntry {
                category,
                name: "auth".to_owned(),
                short,
            });
        }
        self.refresh_root_long();
    }

    /// Returns the shared middleware template.
    #[must_use]
    pub fn middleware(&self) -> &Middleware {
        &self.middleware
    }

    /// Returns mutable middleware for advanced application setup.
    pub fn middleware_mut(&mut self) -> &mut Middleware {
        &mut self.middleware
    }

    /// Executes the CLI with process arguments and process stdout/stderr.
    pub async fn execute(&self) -> ExitCode {
        let mut stdout = std::io::stdout().lock();
        let mut stderr = std::io::stderr().lock();
        match self
            .execute_from(std::env::args_os(), &mut stdout, &mut stderr)
            .await
        {
            Ok(code) => code,
            Err(err) => {
                drop(writeln!(stderr, "{err}"));
                ExitCode::from(1)
            }
        }
    }

    /// Executes the CLI with caller-provided args and output writers.
    pub async fn execute_from<I, S, O, E>(
        &self,
        args: I,
        stdout: &mut O,
        stderr: &mut E,
    ) -> std::io::Result<ExitCode>
    where
        I: IntoIterator<Item = S>,
        S: Into<std::ffi::OsString> + Clone,
        O: Write,
        E: Write,
    {
        self.execute_from_until_signal(args, stdout, stderr, shutdown_signal())
            .await
    }

    /// Executes the CLI until either command completion or a shutdown signal future resolves.
    pub async fn execute_from_until_signal<I, S, O, E, Shutdown>(
        &self,
        args: I,
        stdout: &mut O,
        stderr: &mut E,
        shutdown: Shutdown,
    ) -> std::io::Result<ExitCode>
    where
        I: IntoIterator<Item = S>,
        S: Into<std::ffi::OsString> + Clone,
        O: Write,
        E: Write,
        Shutdown: Future<Output = ()>,
    {
        let output = run_until_signal(self.run(args), shutdown).await;
        if output.exit_code == 130
            && output.rendered == "command interrupted\n"
            && let Some(on_shutdown) = &self.on_shutdown
        {
            on_shutdown();
        }
        if output.exit_code == 0 {
            stdout.write_all(output.rendered.as_bytes())?;
        } else {
            stderr.write_all(output.rendered.as_bytes())?;
        }
        Ok(process_exit_code(output.exit_code))
    }

    /// Registers an auth provider after construction.
    pub fn register_auth_provider(&mut self, provider: Arc<dyn AuthProvider>) -> &mut Self {
        self.middleware.auth.register(provider);
        self.ensure_auth_command();
        self.refresh_root_long();
        self
    }

    /// Returns the built `clap` root command.
    #[must_use]
    pub fn root_command(&self) -> &Command {
        &self.root
    }

    /// Adds one runtime module group after construction.
    pub fn add_module_group(
        &mut self,
        category: impl Into<String>,
        group: RuntimeGroupSpec,
    ) -> &mut Self {
        let category = category.into();
        if !group.group.hidden {
            self.module_entries.push(ModuleHelpEntry {
                category,
                name: group.group.name.clone(),
                short: group.group.short.clone(),
            });
        }

        let mut prefix = Vec::new();
        register_runtime_group_schemas(&group, &mut prefix, &mut self.middleware.schema_registry);
        let mut prefix = Vec::new();
        group.register_commands(&mut prefix, &mut self.commands);
        let mut prefix = Vec::new();
        let clap_group = runtime_group_clap_command_with_schema_help(
            &group,
            &mut prefix,
            &self.middleware.schema_registry,
        );
        self.root = self.root.clone().subcommand(clap_group);
        self.refresh_root_long();
        self
    }

    /// Adds one module after construction.
    pub fn add_module(&mut self, module: Module) -> &mut Self {
        for view in module.views.clone() {
            self.middleware.human_views.register(view);
        }
        self.add_guides(module.guides.clone());
        let mut context = ModuleContext::new(&mut self.middleware);
        let group = (module.register)(&mut context);
        let (guides, views) = context.into_parts();
        for view in views {
            self.middleware.human_views.register(view);
        }
        self.add_guides(guides);
        self.add_module_group(module.category, group)
    }

    /// Adds one top-level runtime command after construction.
    pub fn add_command(&mut self, command: RuntimeCommandSpec) -> &mut Self {
        let name = command.spec.name.clone();
        register_command_schema(&command.spec, &name, &mut self.middleware.schema_registry);
        self.commands.insert(name, command.clone());
        self.root = self
            .root
            .clone()
            .subcommand(command_clap_command_with_schema_help(
                &command.spec,
                &command.spec.name,
                &self.middleware.schema_registry,
            ));
        self
    }

    /// Controls whether the built-in `guide` command is advertised.
    pub fn set_has_guide(&mut self, has_guide: bool) -> &mut Self {
        if has_guide && self.guide_entries.is_empty() && !has_subcommand(&self.root, "guide") {
            self.root = self.root.clone().subcommand(guide_command());
        }
        self.refresh_root_long();
        self
    }

    /// Adds guide entries after construction.
    pub fn add_guides(&mut self, entries: impl IntoIterator<Item = GuideEntry>) -> &mut Self {
        let mut seen = self
            .guide_entries
            .iter()
            .map(|entry| entry.name.clone())
            .collect::<BTreeSet<_>>();
        for entry in entries {
            if seen.insert(entry.name.clone()) {
                self.guide_entries.push(entry);
            }
        }
        if !self.guide_entries.is_empty() && !has_subcommand(&self.root, "guide") {
            self.root = self.root.clone().subcommand(guide_command());
        }
        self.refresh_root_long();
        self
    }

    /// Resolves busybox/git-style `argv[0]` dispatch before the normal pipeline.
    ///
    /// Returns [`Argv0Outcome::Proceed`] with the (possibly rewritten) argument
    /// vector to feed the normal command pipeline, or [`Argv0Outcome::Handled`]
    /// with a fully rendered result when a personality ran or an explicit `argv0`
    /// invocation was rejected. When no routes are registered this is inert and
    /// returns the arguments unchanged. `depth` counts chained hand-offs and
    /// bounds recursion via [`MAX_ARGV0_DEPTH`].
    async fn resolve_argv0(&self, text_args: Vec<String>, depth: usize) -> Argv0Outcome {
        if self.config.argv0_routes.is_empty() {
            return Argv0Outcome::Proceed(text_args);
        }

        if depth > MAX_ARGV0_DEPTH {
            return Argv0Outcome::Handled(
                self.render_argv0_error(&text_args, "argv0 dispatch recursion limit exceeded"),
            );
        }

        // The hidden `argv0` meta-command (`<bin> argv0 <name> [args...]`) forces
        // a route without an actual symlink. It is recognized positionally as the
        // first argument after the program name and is never registered with clap,
        // so it stays absent from `--help`, `tree`, and `--search`.
        let explicit = text_args.get(1).map(String::as_str) == Some("argv0");
        let (name, rest) = if explicit {
            match text_args.get(2) {
                None => {
                    return Argv0Outcome::Handled(self.render_argv0_error(
                        &text_args,
                        "the argv0 command requires a name to dispatch as",
                    ));
                }
                // Normalize the explicit name the same way as a symlink basename
                // so a route registered as `whatever` matches whether the caller
                // passed `whatever`, `whatever.exe`, or a `.cmd` shim's `whatever.cmd`.
                Some(name) => (
                    program_basename(name),
                    text_args
                        .get(3..)
                        .map(<[String]>::to_vec)
                        .unwrap_or_default(),
                ),
            }
        } else {
            let name = text_args
                .first()
                .map(|arg| program_basename(arg))
                .unwrap_or_default();
            let rest = text_args
                .get(1..)
                .map(<[String]>::to_vec)
                .unwrap_or_default();
            (name, rest)
        };

        match self.config.argv0_routes.get(&name) {
            Some(Argv0Route::Alias(tokens)) => {
                // Rewrite as `<canonical-name> <tokens...> <rest...>`. Element 0 is
                // the canonical name so the downstream program-name skip applies.
                let mut rewritten = Vec::with_capacity(1 + tokens.len() + rest.len());
                rewritten.push(self.config.name.clone());
                rewritten.extend(tokens.iter().cloned());
                rewritten.extend(rest);
                Argv0Outcome::Proceed(rewritten)
            }
            Some(Argv0Route::Personality(build)) => {
                // Hand off to an independent CLI built lazily from the route. Its
                // own config name leads so its help/usage and program-name skip
                // render correctly. `Box::pin` breaks the recursive `async fn`;
                // `depth + 1` bounds a pathological chain of hand-offs.
                let config = build();
                let bin = config.name.clone();
                let alt = Self::new(config);
                let mut alt_args = Vec::with_capacity(1 + rest.len());
                alt_args.push(bin);
                alt_args.extend(rest);
                Argv0Outcome::Handled(Box::pin(alt.run_with_depth(alt_args, depth + 1)).await)
            }
            None if explicit => Argv0Outcome::Handled(self.render_argv0_error(
                &text_args,
                format!(
                    "{name:?} is not a registered argv0 name; known names: {}",
                    self.known_argv0_names()
                ),
            )),
            None => {
                // Unregistered name (e.g. the binary renamed to something we do not
                // recognize): fall through to the default CLI. Normalizing element 0
                // to the canonical name lets a renamed binary parse as the default
                // application instead of treating its name as a command token.
                let mut rewritten = Vec::with_capacity(1 + rest.len());
                rewritten.push(self.config.name.clone());
                rewritten.extend(rest);
                Argv0Outcome::Proceed(rewritten)
            }
        }
    }

    /// Comma-separated, sorted list of registered alternative `argv[0]` names,
    /// used in the error shown for an unknown explicit `argv0` invocation.
    fn known_argv0_names(&self) -> String {
        self.config
            .argv0_routes
            .keys()
            .cloned()
            .collect::<Vec<_>>()
            .join(", ")
    }

    /// Renders an `argv0`-dispatch error through the engine's structured error
    /// envelope so it honors `--output` (parsed from the raw args, since dispatch
    /// runs before clap) and the shared exit-code mapping, matching every other
    /// CLI error rather than emitting bare text.
    fn render_argv0_error(&self, text_args: &[String], message: impl Into<String>) -> CliRunOutput {
        let mut middleware = self.middleware.clone();
        middleware.output_format =
            extract_output_format(text_args, &default_output_format(&self.config.app_id));
        let err = CliCoreError::message(message);
        self.finish_run(render_cli_error(&middleware, &err, &self.config.app_id))
    }

    /// Returns the registered alternative `argv[0]` names, sorted.
    ///
    /// Useful for install or self-healing code that iterates the names and calls
    /// [`Cli::create_link`] for each.
    #[must_use]
    pub fn argv0_names(&self) -> Vec<&str> {
        self.config
            .argv0_routes
            .keys()
            .map(String::as_str)
            .collect()
    }

    /// Creates an on-disk link in `dir` that lets the binary be invoked under the
    /// registered alternative `argv[0]` name `name`, using `method`.
    ///
    /// `target` is the executable the link points at; pass `None` to use the
    /// current executable ([`std::env::current_exe`]), which is the common choice
    /// for install and self-healing code. The file name follows the platform and
    /// method: a symlink or hard link is `<name>` on Unix and `<name>.exe` on
    /// Windows; a [`Argv0LinkMethod::Script`] shim is `<name>.cmd` on Windows and
    /// an executable `<name>` shell script on Unix.
    ///
    /// The call ensures the desired state idempotently: if the destination already
    /// matches what would be created (a symlink to `target`, a hard link with the
    /// same contents, or a shim with identical contents) it is left untouched and
    /// its path returned; if it exists but differs (wrong kind, stale target, or
    /// edited shim) it is replaced. This makes the call safe to re-run as install
    /// or self-healing code, restoring both deleted and corrupted links. The
    /// directory is created if necessary.
    ///
    /// # Errors
    ///
    /// Returns an error if `name` is not a registered route, if the current
    /// executable cannot be resolved (when `target` is `None`), or if the
    /// directory or link cannot be created or replaced (e.g. insufficient
    /// privilege for a Windows symlink, or a hard link across volumes).
    pub fn create_link(
        &self,
        name: &str,
        dir: impl AsRef<Path>,
        target: Option<&Path>,
        method: Argv0LinkMethod,
    ) -> std::io::Result<PathBuf> {
        if !self.config.argv0_routes.contains_key(name) {
            return Err(std::io::Error::new(
                std::io::ErrorKind::InvalidInput,
                format!("{name:?} is not a registered argv0 name"),
            ));
        }

        let dir = dir.as_ref();
        std::fs::create_dir_all(dir)?;
        let link = dir.join(argv0_link_file_name(name, method));

        // Resolve the target up front so an existing entry can be compared against it.
        let resolved_target;
        let target = match target {
            Some(target) => target,
            None => {
                resolved_target = std::env::current_exe()?;
                resolved_target.as_path()
            }
        };

        // Ensure-desired-state. `symlink_metadata` does not follow links, so a
        // present-but-dangling link still counts as existing. A matching entry is
        // left untouched (idempotent); a differing one is removed and recreated.
        if std::fs::symlink_metadata(&link).is_ok() {
            if argv0_link_matches(&link, target, name, method)? {
                return Ok(link);
            }
            std::fs::remove_file(&link)?;
        }

        match method {
            Argv0LinkMethod::SoftLink => create_symlink(target, &link)?,
            Argv0LinkMethod::HardLink => std::fs::hard_link(target, &link)?,
            Argv0LinkMethod::Script => {
                std::fs::write(&link, argv0_script_contents(target, name))?;
                make_executable(&link)?;
            }
        }
        Ok(link)
    }

    /// Runs the CLI with provided args and captures the rendered result.
    pub async fn run<I, S>(&self, args: I) -> CliRunOutput
    where
        I: IntoIterator<Item = S>,
        S: Into<std::ffi::OsString> + Clone,
    {
        self.run_with_depth(args, 0).await
    }

    /// Runs the CLI like [`Cli::run`], threading the `argv0` dispatch recursion
    /// `depth` so a chain of personality hand-offs is bounded by [`MAX_ARGV0_DEPTH`].
    async fn run_with_depth<I, S>(&self, args: I, depth: usize) -> CliRunOutput
    where
        I: IntoIterator<Item = S>,
        S: Into<std::ffi::OsString> + Clone,
    {
        let raw_args = args
            .into_iter()
            .map(Into::into)
            .collect::<Vec<std::ffi::OsString>>();
        let text_args = raw_args
            .iter()
            .map(|arg| arg.to_string_lossy().into_owned())
            .collect::<Vec<_>>();
        let text_args = match self.resolve_argv0(text_args, depth).await {
            Argv0Outcome::Handled(output) => return output,
            Argv0Outcome::Proceed(args) => args,
        };
        let mut clap_args = normalize_optional_global_flags_before_command(&self.root, &text_args);
        if has_root_version_flag(&text_args, &self.root, &self.config.name) {
            return self.finish_run(CliRunOutput {
                exit_code: 0,
                rendered: format!(
                    "{} version {}\n",
                    self.config.name,
                    self.config.build.version_string()
                ),
            });
        }
        if let Some(output) = self.try_run_schema_bypass(&text_args) {
            return output;
        }
        if let Some(output) = self.try_run_search_bypass(&text_args) {
            return output;
        }
        // Resolve the positional command path once and share it between the
        // group-help rewrite and the unknown-command check below.
        let bool_flags = derive_bool_flags(&self.root);
        let value_flags = derive_value_flags(&self.root);
        let positionals =
            positional_command_tokens(&text_args, &self.config.name, &bool_flags, &value_flags);
        // Positional tokens after a `--` separator are literal operands, not
        // command keywords, so the group-help shim must not treat a `help`
        // among them as a help request. Count the positionals that precede any
        // `--` to mark where genuine command keywords end.
        let command_keyword_count = match text_args.iter().position(|arg| arg == "--") {
            Some(end) => positional_command_tokens(
                &text_args[..end],
                &self.config.name,
                &bool_flags,
                &value_flags,
            )
            .len(),
            None => positionals.len(),
        };
        if let Some(parts) =
            group_help_target_parts(&self.root, &positionals, command_keyword_count)
        {
            // Rewrite `<group> help [sub...]` into the canonical
            // `help <group> [sub...]` so it flows through the curated root
            // `help` command, which also runs global-flag parsing and the
            // `pre_run` hook (matching `help <group>` and bare-group help).
            // Only the positional command tokens are reordered; every flag and
            // its value is preserved in place so e.g. `--output json` survives.
            clap_args = rewrite_group_help_args(
                &clap_args,
                &self.config.name,
                &bool_flags,
                &value_flags,
                &parts,
            );
        } else if let Some(message) = unknown_group_command_message(&self.root, &positionals) {
            return self.finish_run(CliRunOutput {
                exit_code: 1,
                rendered: message,
            });
        }

        let matches = match self.root.clone().try_get_matches_from(clap_args) {
            Ok(matches) => matches,
            Err(err) => {
                return self.finish_run(CliRunOutput {
                    exit_code: err.exit_code(),
                    rendered: err.to_string(),
                });
            }
        };

        let default_format = default_output_format(&self.config.app_id);
        let flags = global_flags_from_matches(&matches, &default_format);
        let command_timeout = match parse_command_timeout(&flags.timeout) {
            Ok(timeout) => timeout,
            Err(err) => {
                return self.finish_run(render_cli_error(
                    &self.middleware,
                    &err,
                    &self.config.app_id,
                ));
            }
        };
        let mut middleware = self.middleware.clone();
        apply_global_flags(&mut middleware, &flags, command_timeout);
        if let Err(err) = self.apply_config_flags(&matches, &mut middleware) {
            return self.finish_run(render_cli_error(&middleware, &err, &self.config.app_id));
        }

        let command_path = command_path_from_matches(&self.config.name, &matches);
        if command_path == "help" {
            if let Err(err) = self.run_pre_run(&mut middleware, &command_path, &help_args(&matches))
            {
                return self.finish_run(render_cli_error(&middleware, &err, &self.config.app_id));
            }
            return self.finish_run(self.render_help_command(&matches));
        }
        if command_path == "tree" {
            if let Err(err) = self.run_pre_run(
                &mut middleware,
                &command_path,
                &crate::middleware::ValueMap::new(),
            ) {
                return self.finish_run(render_cli_error(&middleware, &err, &self.config.app_id));
            }
            return self.finish_run(tree_render::render_tree(
                &self.root,
                &self.config.app_id,
                &middleware,
            ));
        }
        if command_path == "guide" {
            if let Err(err) =
                self.run_pre_run(&mut middleware, &command_path, &guide_args(&matches))
            {
                return self.finish_run(render_cli_error(&middleware, &err, &self.config.app_id));
            }
            return self.finish_run(self.render_guide(&matches));
        }
        let Some(command) = self.commands.get(&command_path) else {
            if !command_path.is_empty()
                && let Some(group) = find_command_by_colon_path(&self.root, &command_path)
                && group.get_subcommands().next().is_some()
            {
                if let Err(err) = self.run_pre_run(
                    &mut middleware,
                    &command_path,
                    &crate::middleware::ValueMap::new(),
                ) {
                    return self.finish_run(render_cli_error(
                        &middleware,
                        &err,
                        &self.config.app_id,
                    ));
                }
                return self.finish_run(CliRunOutput {
                    exit_code: 0,
                    rendered: group.clone().render_long_help().to_string(),
                });
            }
            if command_path.is_empty()
                && let Some(root_next_actions) = &self.root_next_actions
            {
                // Bare-root discovery is static (help text / metadata + action
                // pointers) and must always be available as a cold-start entry
                // point, so we skip `pre_run` here — matching the no-hook
                // bare-root path below, which also renders help without it.
                let actions = root_next_actions();
                return self.finish_run(self.render_root(&middleware, actions));
            }
            return self.finish_run(CliRunOutput {
                exit_code: if command_path.is_empty() { 0 } else { 1 },
                rendered: if command_path.is_empty() {
                    self.root.clone().render_long_help().to_string()
                } else {
                    format!("unknown command {command_path:?}")
                },
            });
        };

        let mut middleware = match self.initialized_middleware() {
            Ok(middleware) => middleware,
            Err(err) => {
                return self.finish_run(render_cli_error(&middleware, &err, &self.config.app_id));
            }
        };
        apply_global_flags(&mut middleware, &flags, command_timeout);
        if let Err(err) = self.apply_config_flags(&matches, &mut middleware) {
            return self.finish_run(render_cli_error(&middleware, &err, &self.config.app_id));
        }

        let leaf = leaf_matches(&matches);
        let args = command_args_from_matches(leaf, &command.spec, false);
        let user_args = command_args_from_matches(leaf, &command.spec, true);
        if let Err(err) = self.run_pre_run(&mut middleware, &command_path, &args) {
            return self.finish_run(render_cli_error(&middleware, &err, &self.config.app_id));
        }
        let meta = self.resolve_meta(&command_path, command.spec.metadata());
        let default_fields = command.spec.default_fields.clone().unwrap_or_default();
        let system = command.spec.system.clone().unwrap_or_default();

        if let Some(streaming_handler) = command.streaming_handler.clone() {
            let result = run_with_timeout(
                command_timeout,
                &flags.timeout,
                run_streaming_command(
                    &middleware,
                    MiddlewareRequest {
                        meta,
                        command_path: &command_path,
                        system: &system,
                        user_args,
                        args,
                        default_fields: &default_fields,
                        auth: command.spec.auth,
                    },
                    Arc::new(leaf.clone()),
                    streaming_handler,
                ),
            )
            .await;
            return self.finish_run(match result {
                Ok(output) => output,
                Err(err) => render_cli_error(&middleware, &err, &self.config.app_id),
            });
        }

        let handler = command.handler.clone();
        let args_for_handler = args.clone();
        let user_args_for_handler = user_args.clone();
        let handler_path = command_path.clone();
        let middleware_for_handler = middleware.clone();
        let raw_matches_for_handler = Arc::new(leaf.clone());
        let result = run_with_timeout(
            command_timeout,
            &flags.timeout,
            middleware.run(
                MiddlewareRequest {
                    meta,
                    command_path: &command_path,
                    system: &system,
                    user_args,
                    args,
                    default_fields: &default_fields,
                    auth: command.spec.auth,
                },
                async move |credential| {
                    handler(CommandContext {
                        credential,
                        args: args_for_handler,
                        user_args: user_args_for_handler,
                        command_path: handler_path,
                        middleware: middleware_for_handler,
                        raw_matches: raw_matches_for_handler,
                    })
                    .await
                },
            ),
        )
        .await;

        match result {
            Ok(output) => self.finish_run(output.into()),
            Err(err) => self.finish_run(render_cli_error(&middleware, &err, &self.config.app_id)),
        }
    }

    fn try_run_search_bypass(&self, args: &[String]) -> Option<CliRunOutput> {
        let query = extract_search_query(args);
        if query.is_empty() {
            return None;
        }
        let scope = self.search_scope(args);
        let output_format =
            extract_output_format(args, &default_output_format(&self.config.app_id));
        Some(self.render_search(&query, &scope, &output_format))
    }

    fn try_run_schema_bypass(&self, args: &[String]) -> Option<CliRunOutput> {
        if !has_true_schema_flag(args) {
            return None;
        }
        let bool_flags = derive_bool_flags(&self.root);
        let value_flags = derive_value_flags(&self.root);
        let command_path =
            self.canonical_command_path(&extract_command_path(args, &bool_flags, &value_flags));
        let schema = self.middleware.schema_registry.get_by_path(&command_path)?;
        let output_format =
            extract_output_format(args, &default_output_format(&self.config.app_id));
        Some(self.render_schema(schema, &output_format))
    }

    fn render_schema(
        &self,
        schema: crate::output::SchemaInfo,
        output_format: &str,
    ) -> CliRunOutput {
        let format: crate::output::OutputFormat = match output_format.parse() {
            Ok(format) => format,
            Err(err) => {
                return CliRunOutput {
                    exit_code: exit_code_for_error(&err),
                    rendered: err.to_string(),
                };
            }
        };
        let envelope =
            crate::Envelope::success(schema, self.config.app_id.clone()).prepare_for_render("");
        match crate::output::render(format, &envelope) {
            Ok(rendered) => CliRunOutput {
                exit_code: 0,
                rendered,
            },
            Err(err) => CliRunOutput {
                exit_code: exit_code_for_error(&err),
                rendered: err.to_string(),
            },
        }
    }

    fn render_search(&self, query: &str, scope: &str, output_format: &str) -> CliRunOutput {
        let format: crate::output::OutputFormat = match output_format.parse() {
            Ok(format) => format,
            Err(err) => {
                return CliRunOutput {
                    exit_code: exit_code_for_error(&err),
                    rendered: err.to_string(),
                };
            }
        };
        let docs = self.search_documents(scope);
        let results = SearchIndex::new(docs).search(query, 10);
        let envelope =
            crate::Envelope::success(results, self.config.app_id.clone()).prepare_for_render("");
        match crate::output::render(format, &envelope) {
            Ok(rendered) => CliRunOutput {
                exit_code: 0,
                rendered,
            },
            Err(err) => CliRunOutput {
                exit_code: exit_code_for_error(&err),
                rendered: err.to_string(),
            },
        }
    }

    /// Renders the bare-root response. For human output, renders long help plus
    /// a "Next actions" section so a human invoking the CLI with no arguments
    /// gets readable guidance; for machine-readable output, emits a discovery
    /// envelope (light metadata + next actions). The output format has already
    /// resolved the TTY/env/flag policy, so this just branches on it.
    fn render_root(&self, middleware: &Middleware, actions: Vec<NextAction>) -> CliRunOutput {
        // Reject an invalid explicit `--output` here too, matching the normal
        // command path (`Middleware::render_envelope`). `OutputFormat::from_str`
        // is infallible and would otherwise silently coerce an unrecognized
        // value (e.g. `--output yaml`) to JSON instead of reporting the error.
        if !crate::output::is_valid_output_format(&middleware.output_format) {
            let err = CliCoreError::InvalidOutputFormat(middleware.output_format.clone());
            return CliRunOutput {
                exit_code: exit_code_for_error(&err),
                rendered: err.to_string(),
            };
        }
        let format = middleware
            .output_format
            .parse()
            .unwrap_or(crate::output::OutputFormat::Json);
        if format == crate::output::OutputFormat::Human {
            // Fold the suggested actions into the root long-about so they render
            // alongside the other curated sections (before Usage) instead of
            // dangling beneath clap's options dump.
            let base_long = self
                .root
                .get_long_about()
                .map(ToString::to_string)
                .unwrap_or_default();
            let long = format!("{base_long}{}", render_next_actions_human(&actions));
            let rendered = self
                .root
                .clone()
                .long_about(long)
                .render_long_help()
                .to_string();
            return CliRunOutput {
                exit_code: 0,
                rendered,
            };
        }
        let description = self
            .config
            .long
            .as_deref()
            .filter(|long| !long.is_empty())
            .unwrap_or(self.config.short.as_str());
        let data = serde_json::json!({
            "description": description,
            "version": self.config.build.version,
        });
        let envelope = crate::Envelope::success(data, self.config.app_id.clone())
            .with_next_actions(actions)
            .prepare_for_render(&middleware.verbose);
        match crate::output::render(format, &envelope) {
            Ok(rendered) => CliRunOutput {
                exit_code: 0,
                rendered,
            },
            Err(err) => CliRunOutput {
                exit_code: exit_code_for_error(&err),
                rendered: err.to_string(),
            },
        }
    }

    fn search_documents(&self, scope: &str) -> Vec<SearchDocument> {
        let (scoped, mut prefix) = find_command_and_canonical_path_by_colon_path(&self.root, scope)
            .unwrap_or((&self.root, Vec::new()));
        let mut docs = Vec::new();
        let mut aliases = Vec::new();
        append_command_alias_terms(scoped, &mut aliases);
        collect_command_search_documents(scoped, &mut prefix, &mut aliases, &mut docs);
        if scope.is_empty() {
            for entry in &self.guide_entries {
                docs.push(SearchDocument {
                    id: format!("guide:{}", entry.name),
                    kind: "guide".to_owned(),
                    title: format!("guide {}", entry.name),
                    summary: entry.summary.clone(),
                    content: format!("{} {}", entry.summary, entry.content),
                });
            }
            if let Some(extra_search_docs) = &self.extra_search_docs {
                docs.extend(extra_search_docs());
            }
        }
        docs
    }

    fn search_scope(&self, args: &[String]) -> String {
        let parts = extract_search_scope_parts(args);
        canonical_path_from_parts(&self.root, &parts).unwrap_or_default()
    }

    fn canonical_command_path(&self, command_path: &str) -> String {
        find_command_and_canonical_path_by_colon_path(&self.root, command_path).map_or_else(
            || command_path.to_owned(),
            |(_, canonical)| canonical.join(":"),
        )
    }

    fn render_guide(&self, matches: &ArgMatches) -> CliRunOutput {
        let leaf = leaf_matches(matches);
        let topic = leaf.get_one::<String>("topic").map(String::as_str);
        match guide_content(&self.guide_entries, topic) {
            Ok(rendered) => CliRunOutput {
                exit_code: 0,
                rendered,
            },
            Err(err) => CliRunOutput {
                exit_code: 1,
                rendered: err,
            },
        }
    }

    fn render_help_command(&self, matches: &ArgMatches) -> CliRunOutput {
        let leaf = leaf_matches(matches);
        let parts = leaf
            .get_many::<String>("command")
            .map(|values| values.map(String::as_str).collect::<Vec<_>>())
            .unwrap_or_default();
        self.render_help_for_parts(&parts)
    }

    /// Renders the curated help text for a resolved command path.
    ///
    /// Empty `parts` render the root help. A path that resolves to a group or
    /// command renders that command's long help; an unresolved path returns the
    /// standard "unknown command" guidance with a non-zero exit code. Shared by
    /// the root `help <path>` command and the `<group> help` subcommand form.
    fn render_help_for_parts(&self, parts: &[&str]) -> CliRunOutput {
        if parts.is_empty() {
            return CliRunOutput {
                exit_code: 0,
                rendered: self.root.clone().render_long_help().to_string(),
            };
        }
        let Some(command) = find_help_target(&self.root, parts) else {
            return CliRunOutput {
                exit_code: 1,
                rendered: format!(
                    "unknown command {:?} — run '{} help' for available commands",
                    parts.join(" "),
                    self.config.name
                ),
            };
        };
        CliRunOutput {
            exit_code: 0,
            rendered: command.clone().render_long_help().to_string(),
        }
    }

    fn refresh_root_long(&mut self) {
        // Module-categorized entries, plus any visible top-level command that is
        // neither categorized nor an engine built-in, listed under a generic
        // "Commands" section. This keeps every command discoverable once clap's
        // auto subcommand list is suppressed by the root help template.
        const BUILTINS: [&str; 4] = ["help", "guide", "tree", "completion"];
        let categorized: BTreeSet<&str> = self
            .module_entries
            .iter()
            .map(|entry| entry.name.as_str())
            .collect();
        let mut generic: Vec<ModuleHelpEntry> = self
            .root
            .get_subcommands()
            .filter(|command| !command.is_hide_set())
            .filter(|command| !BUILTINS.contains(&command.get_name()))
            .filter(|command| !categorized.contains(command.get_name()))
            .map(|command| ModuleHelpEntry {
                category: "Commands".to_owned(),
                name: command.get_name().to_owned(),
                short: command
                    .get_about()
                    .map(ToString::to_string)
                    .unwrap_or_default(),
            })
            .collect();
        generic.sort_by(|left, right| left.name.cmp(&right.name));

        let mut entries = self.module_entries.clone();
        entries.extend(generic);
        let has_guide = !self.guide_entries.is_empty() || has_subcommand(&self.root, "guide");
        let intro = self
            .config
            .long
            .as_deref()
            .filter(|long| !long.is_empty())
            .unwrap_or(self.config.short.as_str());
        self.root = self
            .root
            .clone()
            .long_about(build_root_long(intro, &entries, has_guide));
    }

    fn ensure_auth_command(&mut self) {
        let default_provider = self.default_auth_provider();
        let registered_names = self.middleware.auth.registered_names();
        if default_provider.is_empty() && registered_names.is_empty() {
            return;
        }
        let replacing_builtin = self.commands.contains_key("auth:login");
        if has_subcommand(&self.root, "auth") && !replacing_builtin {
            return;
        }
        let group = auth_command_group(&default_provider, &registered_names);
        let mut prefix = Vec::new();
        group.register_commands(&mut prefix, &mut self.commands);
        let mut prefix = Vec::new();
        let clap_group = runtime_group_clap_command_with_schema_help(
            &group,
            &mut prefix,
            &self.middleware.schema_registry,
        );
        self.root = if replacing_builtin {
            self.root.clone().mut_subcommand("auth", |_| clap_group)
        } else {
            self.root.clone().subcommand(clap_group)
        };
        // Categorize `auth` wherever it is ensured (construction or a later
        // `register_auth_provider`), so it never falls into the generic
        // "Commands" bucket. Idempotent via the `already_listed` guard.
        self.register_auth_help_entry();
    }

    fn default_auth_provider(&self) -> String {
        if !self.middleware.default_auth_provider.is_empty() {
            return self.middleware.default_auth_provider.clone();
        }
        self.middleware
            .auth
            .registered_names()
            .into_iter()
            .next()
            .unwrap_or_default()
    }

    fn initialized_middleware(&self) -> Result<Middleware> {
        let Some(init_deps) = &self.init_deps else {
            return Ok(self.middleware.clone());
        };
        let mut guard = self
            .init_state
            .lock()
            .map_err(|_| CliCoreError::message("init deps lock poisoned"))?;
        if let Some(result) = guard.as_ref() {
            return result.clone().map_err(InitFailure::into_error);
        }
        let mut middleware = self.middleware.clone();
        let result = init_deps(&mut middleware)
            .map(|()| middleware)
            .map_err(|err| InitFailure::capture(&err));
        *guard = Some(result.clone());
        result.map_err(InitFailure::into_error)
    }

    fn apply_config_flags(&self, matches: &ArgMatches, middleware: &mut Middleware) -> Result<()> {
        if let Some(apply_flags) = &self.apply_flags {
            apply_flags(matches, middleware)?;
        }
        Ok(())
    }

    fn run_pre_run(
        &self,
        middleware: &mut Middleware,
        command_path: &str,
        args: &crate::middleware::ValueMap,
    ) -> Result<()> {
        if let Some(pre_run) = &self.pre_run {
            pre_run(middleware, command_path, args)?;
        }
        Ok(())
    }

    fn resolve_meta(&self, command_path: &str, meta: CommandMeta) -> CommandMeta {
        if let Some(resolver) = &self.meta_resolver {
            resolver(command_path, meta)
        } else {
            meta
        }
    }

    fn finish_run(&self, output: CliRunOutput) -> CliRunOutput {
        if let Some(on_shutdown) = &self.on_shutdown {
            on_shutdown();
        }
        output
    }
}

fn apply_global_flags(middleware: &mut Middleware, flags: &GlobalFlags, timeout: Option<Duration>) {
    middleware.output_format = flags.output_format.clone();
    middleware.verbose = flags.verbose.clone();
    middleware.dry_run = flags.dry_run;
    middleware.fields = flags.fields.clone();
    middleware.filter = flags.filter.clone();
    middleware.expr = flags.expr.clone();
    middleware.limit = flags.limit;
    middleware.offset = flags.offset;
    middleware.reason = flags.reason.clone();
    middleware.schema = flags.schema;
    middleware.timeout = timeout;
    middleware.debug = flags.debug.clone();
    middleware.search = flags.search.clone();
}

async fn run_with_timeout<F, T>(
    timeout: Option<Duration>,
    timeout_label: &str,
    future: F,
) -> Result<T>
where
    F: Future<Output = Result<T>>,
{
    let Some(timeout) = timeout else {
        return future.await;
    };
    match tokio::time::timeout(timeout, future).await {
        Ok(result) => result,
        Err(_) => Err(CliCoreError::message(format!(
            "command timed out after {timeout_label}"
        ))),
    }
}

async fn run_until_signal<Run, Shutdown>(run: Run, shutdown: Shutdown) -> CliRunOutput
where
    Run: Future<Output = CliRunOutput>,
    Shutdown: Future<Output = ()>,
{
    tokio::pin!(run);
    tokio::pin!(shutdown);
    tokio::select! {
        output = &mut run => output,
        () = &mut shutdown => CliRunOutput {
            exit_code: 130,
            rendered: "command interrupted\n".to_owned(),
        },
    }
}

#[cfg(unix)]
async fn shutdown_signal() {
    let ctrl_c = tokio::signal::ctrl_c();
    match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
        Ok(mut sigterm) => {
            tokio::select! {
                _ = ctrl_c => {},
                _ = sigterm.recv() => {},
            }
        }
        Err(_) => {
            drop(ctrl_c.await);
        }
    }
}

#[cfg(not(unix))]
async fn shutdown_signal() {
    drop(tokio::signal::ctrl_c().await);
}

fn parse_command_timeout(raw: &str) -> Result<Option<Duration>> {
    let raw = raw.trim();
    if raw.is_empty() {
        return Ok(Some(Duration::from_secs(60)));
    }
    let Some(seconds) = parse_duration_seconds(raw) else {
        return Err(CliCoreError::message(format!(
            "invalid timeout {raw:?}: expected duration like 60s, 5m, or 0s"
        )));
    };
    if seconds <= 0.0 {
        Ok(None)
    } else {
        Ok(Some(Duration::from_secs_f64(seconds)))
    }
}

fn parse_duration_seconds(raw: &str) -> Option<f64> {
    for (suffix, seconds) in [
        ("ns", 0.000_000_001_f64),
        ("us", 0.000_001_f64),
        ("µs", 0.000_001_f64),
        ("ms", 0.001_f64),
        ("s", 1.0_f64),
        ("m", 60.0_f64),
        ("h", 3600.0_f64),
    ] {
        if let Some(number) = raw.strip_suffix(suffix) {
            let value = number.parse::<f64>().ok()?;
            if !value.is_finite() {
                return None;
            }
            return Some(value * seconds);
        }
    }
    None
}

fn render_cli_error(
    middleware: &Middleware,
    err: &(dyn std::error::Error + 'static),
    system: &str,
) -> CliRunOutput {
    let format = middleware
        .output_format
        .parse::<crate::output::OutputFormat>()
        .unwrap_or(crate::output::OutputFormat::Json);
    let envelope =
        crate::output::build_error_envelope(err, system).prepare_for_render(&middleware.verbose);
    match crate::output::render(format, &envelope) {
        Ok(rendered) => CliRunOutput {
            exit_code: exit_code_for_error(err),
            rendered,
        },
        Err(render_err) => CliRunOutput {
            exit_code: exit_code_for_error(err),
            rendered: render_err.to_string(),
        },
    }
}

fn find_command_by_colon_path<'command>(
    root: &'command Command,
    path: &str,
) -> Option<&'command Command> {
    find_command_and_canonical_path_by_colon_path(root, path).map(|(command, _)| command)
}

fn find_help_target<'command>(
    root: &'command Command,
    parts: &[&str],
) -> Option<&'command Command> {
    let mut current = root;
    let mut matched_any = false;
    for part in parts {
        let Some(next) = current.find_subcommand(part) else {
            break;
        };
        current = next;
        matched_any = true;
    }
    matched_any.then_some(current)
}

fn find_command_and_canonical_path_by_colon_path<'command>(
    root: &'command Command,
    path: &str,
) -> Option<(&'command Command, Vec<String>)> {
    if path.is_empty() {
        return Some((root, Vec::new()));
    }
    let mut current = root;
    let mut canonical = Vec::new();
    for part in path.split(':') {
        current = current.find_subcommand(part)?;
        canonical.push(current.get_name().to_owned());
    }
    Some((current, canonical))
}

fn canonical_path_from_parts(root: &Command, parts: &[String]) -> Option<String> {
    if parts.is_empty() {
        return Some(String::new());
    }
    let mut current = root;
    let mut canonical = Vec::new();
    for part in parts {
        current = current.find_subcommand(part)?;
        canonical.push(current.get_name().to_owned());
    }
    Some(canonical.join(":"))
}

fn extract_search_scope_parts(args: &[String]) -> Vec<String> {
    let mut parts = Vec::new();
    let mut index = 1;
    while index < args.len() {
        let arg = &args[index];
        if arg == "--search" || arg.starts_with("--search=") {
            break;
        }
        if arg.starts_with('-') {
            if !arg.contains('=') && index + 1 < args.len() && !args[index + 1].starts_with('-') {
                index += 2;
            } else {
                index += 1;
            }
            continue;
        }
        parts.push(arg.clone());
        index += 1;
    }
    parts
}

fn collect_command_search_documents(
    command: &Command,
    prefix: &mut Vec<String>,
    aliases: &mut Vec<String>,
    docs: &mut Vec<SearchDocument>,
) {
    if command.is_hide_set() || command.get_name() == "completion" {
        return;
    }
    if command.get_subcommands().next().is_some() {
        for child in command.get_subcommands() {
            prefix.push(child.get_name().to_owned());
            let alias_len = aliases.len();
            append_command_alias_terms(child, aliases);
            collect_command_search_documents(child, prefix, aliases, docs);
            aliases.truncate(alias_len);
            prefix.pop();
        }
        return;
    }
    if prefix.is_empty() {
        prefix.push(command.get_name().to_owned());
        append_command_alias_terms(command, aliases);
    }
    let path = prefix.join(" ");
    let alias_text = aliases.join(" ");
    docs.push(SearchDocument {
        id: format!("cmd:{path}"),
        kind: "command".to_owned(),
        title: path,
        summary: command
            .get_about()
            .map(ToString::to_string)
            .unwrap_or_default(),
        content: format!(
            "{} {} {} {}",
            command
                .get_about()
                .map(ToString::to_string)
                .unwrap_or_default(),
            command
                .get_long_about()
                .map(ToString::to_string)
                .unwrap_or_default(),
            command_flag_text(command),
            alias_text
        ),
    });
    if prefix.len() == 1 && prefix[0] == command.get_name() {
        prefix.pop();
    }
}

fn append_command_alias_terms(command: &Command, aliases: &mut Vec<String>) {
    aliases.extend(command.get_all_aliases().map(str::to_owned));
    aliases.extend(
        command
            .get_all_short_flag_aliases()
            .map(|alias| alias.to_string()),
    );
    aliases.extend(command.get_all_long_flag_aliases().map(str::to_owned));
}

fn command_flag_text(command: &Command) -> String {
    command
        .get_arguments()
        .filter_map(|arg| {
            let mut names = Vec::new();
            if let Some(short) = arg.get_short() {
                names.push(format!("-{short}"));
            }
            if let Some(long) = arg.get_long() {
                names.push(format!("--{long}"));
            }
            if let Some(short_aliases) = arg.get_all_short_aliases() {
                names.extend(
                    short_aliases
                        .into_iter()
                        .map(|short_alias| format!("-{short_alias}")),
                );
            }
            if let Some(aliases) = arg.get_all_aliases() {
                names.extend(aliases.into_iter().map(|alias| format!("--{alias}")));
            }
            (!names.is_empty()).then(|| names.join(" "))
        })
        .collect::<Vec<_>>()
        .join(" ")
}

fn has_subcommand(command: &Command, name: &str) -> bool {
    command
        .get_subcommands()
        .any(|child| child.get_name() == name)
}

fn has_root_version_flag(args: &[String], root: &Command, root_name: &str) -> bool {
    let bool_flags = derive_bool_flags(root);
    let value_flags = derive_value_flags(root);
    let mut iter = args.iter().peekable();
    if iter
        .peek()
        .is_some_and(|arg| arg_matches_root_name(arg, root_name))
    {
        iter.next();
    }

    while let Some(arg) = iter.next() {
        match arg.as_str() {
            "--version" | "-v" => return true,
            "--" => return false,
            value if value.contains('=') || bool_flags.contains(value) => continue,
            value
                if value_flags.contains(value)
                    || unknown_flag_consumes_value(value, iter.peek()) =>
            {
                iter.next();
            }
            value if value.starts_with('-') => {}
            _ => return false,
        }
    }
    false
}

fn normalize_optional_global_flags_before_command(root: &Command, args: &[String]) -> Vec<String> {
    let optional_string_defaults = BTreeMap::from([("--verbose", "all"), ("--debug", "*")]);
    let optional_bool_defaults = BTreeMap::from([("--dry-run", "true"), ("--schema", "true")]);
    let mut normalized = Vec::with_capacity(args.len());
    let mut index = 0;
    let mut current = root;
    while index < args.len() {
        let arg = &args[index];
        if index == 0 && arg_matches_root_name(arg, root.get_name()) {
            normalized.push(arg.clone());
            index += 1;
            continue;
        }

        if let Some(default) = optional_bool_defaults.get(arg.as_str()) {
            normalized.push(format!("{arg}={default}"));
            index += 1;
            continue;
        }

        if let Some(default) = optional_string_defaults.get(arg.as_str()) {
            match args.get(index + 1) {
                None => {
                    normalized.push(format!("{arg}={default}"));
                    index += 1;
                    continue;
                }
                Some(next)
                    if current.get_name() == root.get_name()
                        || next.starts_with('-')
                        || direct_subcommand(current, next).is_some() =>
                {
                    normalized.push(format!("{arg}={default}"));
                    index += 1;
                    continue;
                }
                Some(next) => {
                    normalized.push(arg.clone());
                    normalized.push(next.clone());
                    index += 2;
                    continue;
                }
            }
        }

        normalized.push(arg.clone());
        if !arg.starts_with('-')
            && let Some(next_command) = direct_subcommand(current, arg)
        {
            current = next_command;
        }
        index += 1;
    }
    normalized
}

fn direct_subcommand<'command>(
    command: &'command Command,
    token: &str,
) -> Option<&'command Command> {
    command.get_subcommands().find(|child| {
        child.get_name() == token || child.get_all_aliases().any(|alias| alias == token)
    })
}

fn unknown_group_command_message(root: &Command, positionals: &[String]) -> Option<String> {
    if positionals.is_empty() {
        return None;
    }

    let mut current = root;
    let mut path = vec![root.get_name().to_owned()];
    for token in positionals {
        if let Some(next) = current.find_subcommand(token) {
            current = next;
            path.push(next.get_name().to_owned());
            continue;
        }
        if current.get_subcommands().next().is_some() {
            return Some(format!(
                "unknown command {token:?} for {:?}",
                path.join(" ")
            ));
        }
        return None;
    }
    None
}

/// Detects the `<group> help [sub...]` form and returns the command path whose
/// help should be rendered.
///
/// The engine ships a curated root `help` command, so it disables clap's
/// auto-generated help subcommand on the root. That setting propagates to every
/// subcommand and cannot be re-enabled per child, so `<group> help` would
/// otherwise hit clap's "unrecognized subcommand" error even though the group's
/// help listing advertises a `help` entry. We recognize the form here so the
/// caller can route it through the curated help renderer, matching clap's
/// documented equivalence between `cmd group help sub` and `cmd help group sub`.
///
/// Only groups (commands that have subcommands) are matched: a group is pure
/// subcommand dispatch, so a `help` token in that position is unambiguously a
/// help request. Leaf commands may accept a literal `help` positional argument,
/// so they are left for clap to parse (`<leaf> --help` still works). A group
/// that registers its own real `help` subcommand is likewise deferred to clap,
/// which dispatches the user-defined command (only auto-generated help is
/// suppressed).
///
/// `command_keyword_count` is the number of leading positionals that are
/// genuine command keywords (those before any `--`). A `help` at or beyond that
/// index is a literal operand after `--`, not a help request, so it is ignored.
fn group_help_target_parts(
    root: &Command,
    positionals: &[String],
    command_keyword_count: usize,
) -> Option<Vec<String>> {
    let help_index = positionals.iter().position(|token| token == "help")?;
    // A leading `help` is the curated root help command; let it flow through.
    if help_index == 0 {
        return None;
    }
    // A `help` after a `--` separator is a literal operand; leave it for clap.
    if help_index >= command_keyword_count {
        return None;
    }
    let prefix = &positionals[..help_index];
    let mut current = root;
    for token in prefix {
        current = current.find_subcommand(token)?;
    }
    // The token before `help` must resolve to a group; leaves are left to clap.
    current.get_subcommands().next()?;
    // Defer to clap when the group defines a real `help` subcommand of its own.
    if current.find_subcommand("help").is_some() {
        return None;
    }
    // `<group> help <sub...>` shows help for `<group> <sub...>`.
    let suffix = &positionals[help_index + 1..];
    Some(prefix.iter().chain(suffix).cloned().collect())
}

/// Rewrites a `<group> help [sub...]` invocation into the canonical
/// `help <group> [sub...]` argument vector.
///
/// Only the positional command tokens are reordered (from `[group..., help,
/// sub...]` to `[help, group..., sub...]`); every flag — including `key=value`
/// forms, value-consuming flags, unknown flags that consume a value, and
/// anything after `--` — is preserved in its original place. Reordering keeps
/// the positional count unchanged, so the rewritten stream is filled slot for
/// slot. `parts` is the resolved command path (group + subcommand) from
/// [`group_help_target_parts`].
fn rewrite_group_help_args(
    clap_args: &[String],
    root_name: &str,
    bool_flags: &BTreeSet<String>,
    value_flags: &BTreeSet<String>,
    parts: &[String],
) -> Vec<String> {
    // New positional order: the curated `help` command, then the command path.
    let mut next_positional = std::iter::once("help".to_owned())
        .chain(parts.iter().cloned())
        .peekable();
    let mut out = Vec::with_capacity(clap_args.len());
    let mut iter = clap_args.iter().peekable();
    if iter
        .peek()
        .is_some_and(|arg| arg_matches_root_name(arg, root_name))
        && let Some(program) = iter.next()
    {
        out.push(program.clone());
    }

    let mut take_positional =
        |fallback: &String| next_positional.next().unwrap_or(fallback.clone());

    while let Some(arg) = iter.next() {
        if arg == "--" {
            out.push(arg.clone());
            // Everything after `--` is positional.
            for rest in iter.by_ref() {
                out.push(take_positional(rest));
            }
            break;
        }
        if arg.contains('=') || bool_flags.contains(arg) {
            out.push(arg.clone());
            continue;
        }
        if value_flags.contains(arg) || unknown_flag_consumes_value(arg, iter.peek()) {
            out.push(arg.clone());
            if let Some(value) = iter.next() {
                out.push(value.clone());
            }
            continue;
        }
        if arg.starts_with('-') {
            out.push(arg.clone());
            continue;
        }
        out.push(take_positional(arg));
    }
    // Defensive: emit any positionals not yet placed (counts normally match).
    out.extend(next_positional);
    out
}

fn positional_command_tokens(
    args: &[String],
    root_name: &str,
    bool_flags: &BTreeSet<String>,
    value_flags: &BTreeSet<String>,
) -> Vec<String> {
    let mut tokens = Vec::new();
    let mut iter = args.iter().peekable();
    if iter
        .peek()
        .is_some_and(|arg| arg_matches_root_name(arg, root_name))
    {
        iter.next();
    }

    while let Some(arg) = iter.next() {
        if arg == "--" {
            tokens.extend(iter.cloned());
            break;
        }
        if arg.contains('=') {
            continue;
        }
        if bool_flags.contains(arg) {
            continue;
        }
        if value_flags.contains(arg) || unknown_flag_consumes_value(arg, iter.peek()) {
            iter.next();
            continue;
        }
        if arg.starts_with('-') {
            continue;
        }
        tokens.push(arg.clone());
    }
    tokens
}

fn unknown_flag_consumes_value(arg: &str, next: Option<&&String>) -> bool {
    arg.starts_with('-') && next.is_some_and(|value| !value.starts_with('-'))
}

fn arg_matches_root_name(arg: &str, root_name: &str) -> bool {
    arg == root_name
        || Path::new(arg)
            .file_stem()
            .and_then(|n| n.to_str())
            .is_some_and(|n| n == root_name)
}

/// Outcome of [`Cli::resolve_argv0`]: either rewritten arguments to feed the
/// normal pipeline, or a fully rendered result to return immediately.
enum Argv0Outcome {
    /// Continue the normal run pipeline with these arguments.
    Proceed(Vec<String>),
    /// Return this already-rendered result without further processing.
    Handled(CliRunOutput),
}

/// Extracts the bare program name from an `argv[0]` value, dropping any directory
/// path and file extension (e.g. `/usr/bin/pl` or `pl.exe` both yield `pl`).
/// Falls back to the raw value when no file stem can be derived.
fn program_basename(arg: &str) -> String {
    Path::new(arg)
        .file_stem()
        .and_then(|stem| stem.to_str())
        .map_or_else(|| arg.to_owned(), ToOwned::to_owned)
}

/// Returns `true` when `name` is a valid alternative `argv[0]` route name: a
/// non-empty token of ASCII letters, digits, `-`, or `_`. This keeps the name
/// safe as a link/shim filename and as an `argv[0]` basename (which is matched
/// with its extension stripped, so an embedded dot would break matching).
fn is_valid_argv0_name(name: &str) -> bool {
    !name.is_empty()
        && name.chars().all(|character| {
            character.is_ascii_alphanumeric() || character == '-' || character == '_'
        })
}

/// Returns `true` when the entry at `link` already matches what [`Cli::create_link`]
/// would produce for `method`/`target`/`name`, so it can be left untouched. A
/// mismatch (wrong kind, stale symlink target, or differing contents) returns
/// `false` so the caller replaces it.
fn argv0_link_matches(
    link: &Path,
    target: &Path,
    name: &str,
    method: Argv0LinkMethod,
) -> std::io::Result<bool> {
    let metadata = std::fs::symlink_metadata(link)?;
    match method {
        Argv0LinkMethod::SoftLink => {
            Ok(metadata.file_type().is_symlink() && std::fs::read_link(link)? == target)
        }
        Argv0LinkMethod::HardLink => {
            if metadata.file_type().is_symlink() {
                return Ok(false);
            }
            // A correct hard link is indistinguishable from the target by content;
            // comparing bytes also accepts an identical copy, which is harmless.
            Ok(std::fs::read(link)? == std::fs::read(target)?)
        }
        Argv0LinkMethod::Script => {
            if metadata.file_type().is_symlink() {
                return Ok(false);
            }
            Ok(std::fs::read_to_string(link).ok() == Some(argv0_script_contents(target, name)))
        }
    }
}

/// File name for an alternative `argv[0]` link, per method and host platform.
fn argv0_link_file_name(name: &str, method: Argv0LinkMethod) -> String {
    let extension = match method {
        Argv0LinkMethod::Script if cfg!(windows) => ".cmd",
        // Unix scripts are extension-less executables; links carry `.exe` on Windows.
        Argv0LinkMethod::Script => "",
        _ if cfg!(windows) => ".exe",
        _ => "",
    };
    format!("{name}{extension}")
}

/// Contents of an alternative `argv[0]` shim script that forwards to `target`
/// via the explicit `argv0` command. A `.cmd` batch file on Windows, an
/// executable POSIX shell script elsewhere.
fn argv0_script_contents(target: &Path, name: &str) -> String {
    let target = target.display();
    if cfg!(windows) {
        format!("@\"{target}\" argv0 {name} %*\r\n")
    } else {
        format!("#!/bin/sh\nexec \"{target}\" argv0 {name} \"$@\"\n")
    }
}

#[cfg(unix)]
fn create_symlink(target: &Path, link: &Path) -> std::io::Result<()> {
    std::os::unix::fs::symlink(target, link)
}

#[cfg(windows)]
fn create_symlink(target: &Path, link: &Path) -> std::io::Result<()> {
    std::os::windows::fs::symlink_file(target, link)
}

#[cfg(not(any(unix, windows)))]
fn create_symlink(_target: &Path, _link: &Path) -> std::io::Result<()> {
    Err(std::io::Error::new(
        std::io::ErrorKind::Unsupported,
        "symlink creation is not supported on this platform",
    ))
}

/// Marks a freshly written shim script executable on Unix; a no-op elsewhere.
#[cfg(unix)]
fn make_executable(path: &Path) -> std::io::Result<()> {
    use std::os::unix::fs::PermissionsExt;
    let mut permissions = std::fs::metadata(path)?.permissions();
    permissions.set_mode(0o755);
    std::fs::set_permissions(path, permissions)
}

#[cfg(not(unix))]
fn make_executable(_path: &Path) -> std::io::Result<()> {
    Ok(())
}

fn register_runtime_group_schemas(
    group: &RuntimeGroupSpec,
    prefix: &mut Vec<String>,
    schemas: &mut SchemaRegistry,
) {
    prefix.push(group.group.name.clone());
    for child_group in &group.groups {
        register_runtime_group_schemas(child_group, prefix, schemas);
    }
    for child in &group.commands {
        prefix.push(child.spec.name.clone());
        register_command_schema(&child.spec, &prefix.join(":"), schemas);
        prefix.pop();
    }
    prefix.pop();
}

fn register_command_schema(spec: &CommandSpec, command_path: &str, schemas: &mut SchemaRegistry) {
    if let Some(schema) = &spec.output_schema {
        schemas.register_info(command_path.to_owned(), schema.clone());
    }
}

fn runtime_group_clap_command_with_schema_help(
    group: &RuntimeGroupSpec,
    prefix: &mut Vec<String>,
    schemas: &SchemaRegistry,
) -> Command {
    let mut command = group_clap_command_without_children(&group.group);
    prefix.push(group.group.name.clone());
    for child_group in &group.groups {
        command = command.subcommand(runtime_group_clap_command_with_schema_help(
            child_group,
            prefix,
            schemas,
        ));
    }
    for child in &group.commands {
        prefix.push(child.spec.name.clone());
        let command_path = prefix.join(":");
        command = command.subcommand(command_clap_command_with_schema_help(
            &child.spec,
            &command_path,
            schemas,
        ));
        prefix.pop();
    }
    prefix.pop();
    command
}

fn group_clap_command_without_children(group: &GroupSpec) -> Command {
    let mut command = Command::new(group.name.clone())
        .about(group.short.clone())
        .help_template(GROUP_HELP_TEMPLATE);
    if let Some(long) = &group.long
        && !long.is_empty()
    {
        command = command.long_about(long.clone());
    }
    for alias in &group.aliases {
        command = command.alias(alias.clone());
    }
    if group.hidden {
        command = command.hide(true);
    }
    command
}

fn command_clap_command_with_schema_help(
    spec: &CommandSpec,
    command_path: &str,
    schemas: &SchemaRegistry,
) -> Command {
    let mut command = spec.clap_command();
    let Some(schema) = schemas.get_by_path(command_path) else {
        return command;
    };
    let schema_help = format_help_section(&schema.fields);
    if schema_help.is_empty() {
        return command;
    }
    let base = spec
        .long
        .as_ref()
        .filter(|long| !long.is_empty())
        .cloned()
        .unwrap_or_else(|| spec.short.clone());
    let long = if base.is_empty() {
        schema_help
    } else {
        format!("{base}\n\n{schema_help}")
    };
    command = command.long_about(long);
    command
}

fn process_exit_code(code: i32) -> ExitCode {
    if code == 0 {
        return ExitCode::SUCCESS;
    }
    match u8::try_from(code) {
        Ok(code) if code != 0 => ExitCode::from(code),
        Ok(_) | Err(_) => ExitCode::from(1),
    }
}

async fn run_streaming_command(
    middleware: &Middleware,
    request: MiddlewareRequest<'_>,
    raw_matches: Arc<ArgMatches>,
    streaming_handler: crate::command::StreamingCommandHandler,
) -> Result<CliRunOutput> {
    use tokio::{io::AsyncWriteExt, sync::mpsc};

    let args_for_handler = request.args.clone();
    let user_args_for_handler = request.user_args.clone();
    let handler_path = request.command_path.to_owned();
    let middleware_for_handler = middleware.clone();
    let raw_matches_for_handler = raw_matches;

    let (tx, mut rx) = mpsc::channel::<serde_json::Value>(64);
    let sender = StreamSender(tx);

    // Drain the channel concurrently so the handler's sends don't stall
    // while the writer flushes to stdout. If stdout is under backpressure
    // the bounded channel can still fill and the handler will await send.
    let writer = tokio::spawn(async move {
        let mut stdout = tokio::io::stdout();
        while let Some(event) = rx.recv().await {
            let Ok(line) = serde_json::to_string(&event) else {
                continue;
            };
            if stdout.write_all(line.as_bytes()).await.is_err()
                || stdout.write_all(b"\n").await.is_err()
                || stdout.flush().await.is_err()
            {
                break;
            }
        }
    });

    let output = middleware
        .run(request, async move |credential| {
            streaming_handler(
                CommandContext {
                    credential,
                    args: args_for_handler,
                    user_args: user_args_for_handler,
                    command_path: handler_path,
                    middleware: middleware_for_handler,
                    raw_matches: raw_matches_for_handler,
                },
                sender,
            )
            .await?;
            Ok(crate::CommandResult::new(serde_json::Value::Null))
        })
        .await;

    // Handler has completed; its sender is dropped, which closes the channel.
    // Wait for the writer task to flush all remaining events.
    let _write_result = writer.await;

    match output {
        Ok(out) if out.exit_code == 0 => Ok(CliRunOutput {
            exit_code: 0,
            rendered: String::new(),
        }),
        Ok(out) => Ok(out.into()),
        Err(err) => Ok(CliRunOutput {
            exit_code: exit_code_for_error(&err),
            rendered: render_cli_error(middleware, &err, middleware.app_id.as_str()).rendered,
        }),
    }
}