xbp_cli/cli/

mod.rs

pub mod app;
pub mod auto_commit;
pub mod commands;
pub mod error;
pub mod features;
pub mod handlers;
pub mod help_render;
pub mod mcp_tools_export;
pub mod router;
pub mod ui;

pub use handlers::*;

use crate::cli::app::AppContext;
use crate::cli::error::{CliError, CliResult, ErrorFactory};
use crate::commands::cli_session::{
    post_cli_error_report, require_authenticated_cli_session, run_login_status, run_logout,
    run_whoami, CliErrorReportPayload,
};
use crate::commands::curl;
#[cfg(feature = "openapi-gen")]
use crate::commands::generate_openapi::{run_generate_openapi, GenerateOpenApiArgs};
use crate::commands::generate_systemd::{run_generate_systemd, GenerateSystemdArgs};
use crate::commands::redeploy_v2::run_redeploy_v2;
use crate::commands::{
    install_package, list_services, open_global_config, pick_service_for_command, run_commit,
    run_config, run_config_cloudflare_account_delete, run_config_cloudflare_account_set,
    run_config_cloudflare_account_show, run_config_cloudflare_login, run_config_cloudflare_setup,
    run_config_cloudflare_status, run_config_crates_login, run_config_crates_logout,
    run_config_discord, run_config_openapi_setup, run_config_openapi_show,
    run_config_publish_setup, run_config_release_setup, run_config_secret_delete,
    run_config_secret_set, run_config_secret_show, run_cursor_ingest, run_generate_config,
    run_github, run_init,
    run_login, run_migrate_config_file, run_publish_command, run_redeploy, run_redeploy_service,
    run_service_command, run_service_interactive, run_setup, run_todos, run_update_check,
    run_version_bump_command, run_version_command, run_version_discover_services,
    run_version_domain_command, run_version_release_command, run_version_workspace_command,
    show_service_help, CommitArgs, CommitError, CommitRunOutcome, GenerateConfigArgs,
    PublishCommandOptions, ReleaseLatestPolicy, UpdateCheckOptions, VersionDomainCommand,
    VersionDomainCommandOptions, VersionDomainDiagnoseOptions, VersionDomainDoctorOptions,
    VersionDomainInitOptions, VersionDomainReleaseOptions, VersionDomainSyncOptions,
    VersionReleaseOptions, WorkspacePublishHealOptions, WorkspacePublishPlanOptions,
    WorkspacePublishRunOptions, WorkspaceVersionCheckOptions, WorkspaceVersionCommand,
    WorkspaceVersionCommandOptions, WorkspaceVersionSyncOptions, WorkspaceVersionValidateOptions,
};
#[cfg(feature = "linear")]
use crate::commands::{run_config_linear_select_initiative, run_linear};
use crate::commands::{run_diag, run_nginx};
use crate::config::{resolve_device_identity, sync_versioning_files_registry};
use crate::logging::{init_logger, log_error, log_info, log_success, log_warn};
use crate::utils::{
    find_xbp_config_upwards, git_remote_url_from_metadata, parse_github_repo_from_remote_url,
};
use chrono::Utc;
use clap::{error::ErrorKind as ClapErrorKind, Parser};
use colored::Colorize;
use commands::Cli;
use std::env;

pub async fn run() -> CliResult<()> {
    // Allow `xbp -h -q deploy`: clap treats -h as exclusive help, so strip root
    // help flags when a search query is present (subcommand help is unchanged).
    let argv = preprocess_argv_for_help_query(std::env::args().collect());
    let cli: Cli = match Cli::try_parse_from(argv) {
        Ok(cli) => cli,
        Err(err) => {
            let kind = err.kind();
            let rendered = err.to_string();
            if kind == ClapErrorKind::DisplayVersion {
                help_render::emit_version_info(env!("CARGO_PKG_VERSION"));
                return Ok(());
            }
            if kind == ClapErrorKind::DisplayHelp
                || kind == ClapErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
                || rendered.contains("Manage the XBP API server")
            {
                ui::configure_color_output();
                if help_render::is_root_help_text(&rendered) {
                    crate::commands::print_help().await;
                } else {
                    help_render::emit_styled_help(&rendered, help_render::HelpScope::Auto);
                }
                return Ok(());
            }
            let error = ErrorFactory::clap_parse(err);
            report_cli_error("cli", &error).await;
            return Err(error);
        }
    };

    if cli.commands {
        help_render::print_command_catalog();
        return Ok(());
    }

    // `xbp -q deploy` / `xbp -h -q deploy` / `xbp --query webhook`
    if let Some(query) = cli.query.as_ref().map(|q| q.trim()).filter(|q| !q.is_empty()) {
        crate::commands::help::print_help_query(query);
        return Ok(());
    }

    // Keep plain `xbp` aligned with `xbp --help` instead of entering
    // interactive project selection flow.
    if should_print_help(&cli) {
        ui::configure_color_output();
        crate::commands::print_help().await;
        return Ok(());
    }

    let debug: bool = cli.debug;
    ui::configure_color_output();
    let command_name = cli
        .command
        .as_ref()
        .map(commands::command_label)
        .unwrap_or("interactive");
    ui::print_cli_header(command_name, debug);

    if let Err(e) = init_logger(debug).await {
        let _ = log_error(
            "system",
            "Failed to initialize logger",
            Some(&e.to_string()),
        )
        .await;
    }
    if let Err(e) = sync_versioning_files_registry() {
        let _ = log_warn("config", "Failed to sync versioning registry", Some(&e)).await;
    }

    let background_cursor_trigger =
        background_cursor_ingest_trigger(cli.command.as_ref()).map(str::to_string);
    let background_system_inventory_trigger =
        background_system_inventory_refresh_trigger(cli.command.as_ref()).map(str::to_string);
    let mut ctx = AppContext::new(debug);
    let result = router::dispatch(cli, &mut ctx).await;

    if result.is_ok() {
        if let Some(trigger) = background_cursor_trigger {
            if let Err(error) =
                crate::commands::cursor_ingest::maybe_start_background_cursor_ingest(&trigger)
            {
                let _ = log_warn(
                    "cursor",
                    "Background Cursor ingest could not be started",
                    Some(&error),
                )
                .await;
            }
        }
        if let Some(trigger) = background_system_inventory_trigger {
            if let Err(error) = crate::commands::system_inventory_refresh::
                maybe_start_background_system_inventory_refresh(&trigger)
            {
                let _ = log_warn(
                    "codetime",
                    "Background system inventory refresh could not be started",
                    Some(&error),
                )
                .await;
            }
        }
    } else if let Err(ref error) = result {
        report_cli_error(command_name, error).await;
    }

    result
}

/// Soft-report a CLI failure to xbp.app (D1). Never raises; missing login skips.
async fn report_cli_error(command: &str, error: &CliError) {
    let message = redact_sensitive_text(&strip_ansi(&error.to_string()));
    if message.trim().is_empty() {
        return;
    }

    let cwd = env::current_dir().ok();
    let project_path = cwd
        .as_ref()
        .and_then(|dir| find_xbp_config_upwards(dir))
        .map(|found| found.project_root.display().to_string());
    let (repository_owner, repository_name) = cwd
        .as_ref()
        .and_then(|dir| {
            let root = find_xbp_config_upwards(dir)
                .map(|found| found.project_root)
                .unwrap_or_else(|| dir.clone());
            git_remote_url_from_metadata(&root, "origin")
                .ok()
                .flatten()
                .and_then(|url| parse_github_repo_from_remote_url(&url))
        })
        .map(|(owner, repo)| (Some(owner), Some(repo)))
        .unwrap_or((None, None));

    let hardware_id = resolve_device_identity()
        .ok()
        .map(|device| device.hardware_id);
    let hostname = env::var("COMPUTERNAME")
        .or_else(|_| env::var("HOSTNAME"))
        .ok()
        .map(|value| value.trim().to_string())
        .filter(|value| !value.is_empty());

    let payload = CliErrorReportPayload {
        command: command.to_string(),
        action: extract_labeled_field(&message, "Action"),
        kind: extract_error_kind(&message),
        message: message.clone(),
        details: extract_labeled_field(&message, "Details")
            .or_else(|| extract_labeled_field(&message, "Reason")),
        hint: extract_labeled_field(&message, "Hint"),
        project_path,
        cwd: cwd.map(|path| path.display().to_string()),
        repository_owner,
        repository_name,
        cli_version: Some(env!("CARGO_PKG_VERSION").to_string()),
        platform: Some(format!(
            "{}-{}",
            std::env::consts::OS,
            std::env::consts::ARCH
        )),
        hostname,
        hardware_id,
        occurred_at: Some(Utc::now().to_rfc3339()),
    };

    let _ = post_cli_error_report(&payload).await;
}

fn strip_ansi(input: &str) -> String {
    let bytes = input.as_bytes();
    let mut out = String::with_capacity(input.len());
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] == 0x1b {
            i += 1;
            if i < bytes.len() && bytes[i] == b'[' {
                i += 1;
                while i < bytes.len() {
                    let b = bytes[i];
                    i += 1;
                    if (b'@'..=b'~').contains(&b) {
                        break;
                    }
                }
            }
            continue;
        }
        out.push(bytes[i] as char);
        i += 1;
    }
    out
}

fn redact_sensitive_text(input: &str) -> String {
    // Best-effort: avoid shipping obvious tokens/keys if they appear in stderr.
    let mut out = input.to_string();
    for pattern in [
        r"(?i)ghp_[A-Za-z0-9]{20,}",
        r"(?i)gho_[A-Za-z0-9]{20,}",
        r"(?i)github_pat_[A-Za-z0-9_]{20,}",
        r"(?i)xbp_[A-Za-z0-9_-]{20,}",
        r"(?i)sk-[A-Za-z0-9]{20,}",
        r"(?i)Bearer\s+[A-Za-z0-9._\-+/=]{16,}",
    ] {
        if let Ok(re) = regex::Regex::new(pattern) {
            out = re.replace_all(&out, "[redacted]").into_owned();
        }
    }
    if out.len() > 8_000 {
        out.truncate(8_000);
        out.push_str("…");
    }
    out
}

fn extract_labeled_field(message: &str, label: &str) -> Option<String> {
    let prefix = format!("{label}:");
    for line in message.lines() {
        let trimmed = line.trim();
        if let Some(rest) = trimmed.strip_prefix(&prefix).or_else(|| {
            // colored headers sometimes leave trailing spaces after labels
            trimmed
                .split_once(':')
                .filter(|(head, _)| head.trim().eq_ignore_ascii_case(label))
                .map(|(_, rest)| rest)
        }) {
            let value = rest.trim();
            if !value.is_empty() {
                return Some(value.to_string());
            }
        }
    }
    None
}

fn extract_error_kind(message: &str) -> Option<String> {
    let trimmed = message.trim_start();
    if let Some(rest) = trimmed.strip_prefix('[') {
        if let Some(end) = rest.find(']') {
            let kind = rest[..end].trim();
            if !kind.is_empty() && kind.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
                return Some(kind.to_string());
            }
        }
    }
    // SECRETS / VERSION-style banners
    message
        .lines()
        .next()
        .and_then(|line| line.split_whitespace().next())
        .map(|word| word.trim().to_ascii_uppercase())
        .filter(|word| {
            word.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') && word.len() <= 24
        })
}

pub(super) async fn handle_init(debug: bool) -> CliResult<()> {
    if let Err(e) = run_init(debug).await {
        let _ = log_error("init", "Init failed", Some(&e)).await;
        return Err(e.into());
    }
    Ok(())
}

pub(super) async fn handle_commit(cmd: commands::CommitCmd) -> CliResult<()> {
    if cmd.push {
        crate::cli::auto_commit::set_explicit_push(true);
    }

    let args = CommitArgs {
        dry_run: cmd.dry_run,
        push: crate::cli::auto_commit::explicit_push_requested(),
        no_ai: cmd.no_ai,
        model: cmd.model,
        scope: cmd.scope,
    };

    match run_commit(args).await {
        Ok(CommitRunOutcome::Completed) | Ok(CommitRunOutcome::NothingToCommit) => Ok(()),
        Err(error) => Err(map_commit_error(error)),
    }
}

pub(super) async fn handle_push() -> CliResult<()> {
    match crate::commands::push::run_push().await {
        Ok(()) => Ok(()),
        Err(error) => Err(ErrorFactory::operation(
            "push",
            "sync and push current branch",
            error,
            Some(
                "If rebase conflicts remain, resolve them, run `git rebase --continue`, then `xbp push` again. Dirty WIP is stashed as `xbp auto-rebase: temporary stash`.",
            ),
        )),
    }
}

pub(super) async fn handle_deploy(cmd: commands::DeployCmd, debug: bool) -> CliResult<()> {
    use crate::commands::deploy_engine::{run_deploy, DeployRequest};
    use xbp_deploy::{DeployFlags, DeployMode};

    // Exactly one mode: clap ArgGroup enforces mutual exclusion when multiple set.
    let mode_count = [
        cmd.plan,
        cmd.run,
        cmd.verify,
        cmd.status,
        cmd.history,
        cmd.promote.is_some(),
    ]
    .into_iter()
    .filter(|v| *v)
    .count();
    if mode_count > 1 {
        return Err(ErrorFactory::validation(
            "deploy",
            "exactly one of --plan, --run, --verify, --status, --history, --promote is allowed",
            Some("Example: `xbp deploy athena --env production --plan`"),
        ));
    }

    let mode = if cmd.history {
        DeployMode::History
    } else if cmd.promote.is_some() {
        DeployMode::Promote
    } else if cmd.verify {
        DeployMode::Verify
    } else if cmd.status {
        DeployMode::Status
    } else if cmd.run {
        DeployMode::Run
    } else {
        DeployMode::Plan
    };

    let request = DeployRequest {
        target: cmd.target,
        env: cmd.env,
        mode,
        flags: DeployFlags {
            dry_run: cmd.dry_run,
            skip_oci: cmd.skip_oci,
            skip_apply: cmd.skip_apply,
            skip_rollout: cmd.skip_rollout,
            skip_health: cmd.skip_health,
            yes: cmd.yes,
            json: cmd.json,
            namespace: cmd.namespace,
            context: cmd.context,
            promote_tag: cmd.promote,
            history_limit: cmd.limit,
            output: cmd.output,
        },
        debug,
    };

    let target_label = request.target.clone();
    let env_label = request.env.clone().unwrap_or_else(|| "default".to_string());
    let mode_label = format!("{:?}", request.mode).to_ascii_lowercase();

    match run_deploy(request).await {
        Ok(()) => {
            if let Ok((root, cfg)) = crate::commands::service::load_xbp_config_with_root().await {
                crate::commands::discord_notify::notify_discord_for_project(
                    &root,
                    Some(&cfg),
                    None,
                    crate::commands::discord_notify::deploy_notification(
                        &target_label,
                        &env_label,
                        &mode_label,
                        crate::commands::discord_notify::DiscordStatus::Success,
                        "Deploy orchestration completed",
                    ),
                )
                .await;
            }
            Ok(())
        }
        Err(error) => {
            if let Ok((root, cfg)) = crate::commands::service::load_xbp_config_with_root().await {
                crate::commands::discord_notify::notify_discord_for_project(
                    &root,
                    Some(&cfg),
                    None,
                    crate::commands::discord_notify::deploy_notification(
                        &target_label,
                        &env_label,
                        &mode_label,
                        crate::commands::discord_notify::DiscordStatus::Failure,
                        &error.to_string(),
                    ),
                )
                .await;
            }
            Err(ErrorFactory::operation(
                "deploy",
                "orchestrate service deploy",
                error,
                Some(
                    "Use `xbp deploy <target> --plan` first. Configure services[].deploy.envs.<env> and optional deploy.groups. Pass --yes for non-interactive k8s apply.",
                ),
            ))
        }
    }
}

pub(super) async fn handle_oci(cmd: commands::OciCmd, debug: bool) -> CliResult<()> {
    match crate::oci::run_oci(cmd, debug).await {
        Ok(()) => Ok(()),
        Err(error) => Err(ErrorFactory::operation(
            "oci",
            "run OCI registry command",
            error,
            Some(
                "Check image reference, registry auth (GH_TOKEN / xbp config oci), or use --anonymous for public pulls.",
            ),
        )),
    }
}

fn map_commit_error(error: CommitError) -> CliError {
    match error {
        CommitError::PushFailed {
            summary,
            commit_sha,
        } => {
            let details = if let Some(commit_sha) = commit_sha {
                format!("Created local commit {commit_sha} but push failed: {summary}")
            } else {
                format!("Push failed: {summary}")
            };
            ErrorFactory::operation(
                "commit",
                "push changes",
                details,
                commit_push_hint(&summary),
            )
        }
        CommitError::TerminalSessionsBlocked(message) => ErrorFactory::validation(
            "commit",
            message,
            Some("Add `/terminals` to `.gitignore` and run `git rm -r --cached terminals/`."),
        ),
        CommitError::Operation(message) => ErrorFactory::operation(
            "commit",
            "create conventional commit",
            message,
            Some("Run `xbp commit --dry-run` after saving changes."),
        ),
    }
}

fn commit_push_hint(summary: &str) -> Option<&'static str> {
    let lowered = summary.to_ascii_lowercase();
    if lowered.contains("unstaged changes")
        || lowered.contains("uncommitted changes")
        || lowered.contains("please commit or stash")
        || lowered.contains("temporary stash")
    {
        Some(
            "XBP stashes dirty WIP for auto-rebase. If push still failed: `git stash list`, restore the `xbp auto-rebase` stash if needed, then `git pull --rebase` and `git push`.",
        )
    } else if lowered.contains("auto-rebase failed") || lowered.contains("conflict") {
        Some("Resolve rebase conflicts, run `git rebase --continue`, then `git push`.")
    } else if lowered.contains("behind") || lowered.contains("non-fast-forward") {
        Some("XBP should auto-rebase; if it did not, run `git pull --rebase` then `git push`.")
    } else {
        Some("Verify GitHub auth and branch permissions, then push again.")
    }
}

pub(super) async fn handle_publish(cmd: commands::PublishCmd, _debug: bool) -> CliResult<()> {
    let options = PublishCommandOptions {
        dry_run: cmd.dry_run,
        allow_dirty: cmd.allow_dirty,
        force: cmd.force,
        include_prereqs: cmd.include_prereqs,
        auto_fix: true,
        target: cmd.target,
        service: cmd.service,
        manifest_path: cmd.manifest_path,
        expected_version: None,
    };

    if let Err(e) = run_publish_command(options).await {
        let _ = log_error("publish", "Publish command failed", Some(&e)).await;
        return Err(ErrorFactory::operation(
            "publish",
            "run publish workflow",
            e,
            Some("Configure project targets with `xbp config npm setup-release` or `xbp config crates setup-release`."),
        ));
    }

    Ok(())
}

pub(super) async fn handle_setup(debug: bool) -> CliResult<()> {
    if let Err(e) = ui::with_loader("Running setup checks", run_setup(debug)).await {
        let _ = log_error("setup", "Setup failed", Some(&e)).await;
        return Err(ErrorFactory::operation(
            "setup",
            "setup environment",
            e,
            Some("Run with `--debug` for command-level output."),
        ));
    }
    Ok(())
}

pub(super) async fn handle_redeploy(service_name: Option<String>, debug: bool) -> CliResult<()> {
    if let Some(name) = service_name {
        if let Err(e) = ui::with_loader(
            &format!("Redeploying service `{}`", name),
            run_redeploy_service(&name, debug),
        )
        .await
        {
            let _ = log_error("redeploy", "Service redeploy failed", Some(&e)).await;
            return Err(ErrorFactory::operation(
                "redeploy",
                &format!("redeploy service `{}`", name),
                e,
                Some("Verify service name with `xbp services`."),
            ));
        }
    } else if let Err(e) = ui::with_loader("Redeploying full project", run_redeploy()).await {
        let _ = log_error("redeploy", "Redeploy failed", Some(&e)).await;
        return Err(ErrorFactory::operation(
            "redeploy",
            "redeploy project",
            e,
            Some("Try `xbp redeploy <service>` for scoped retries."),
        ));
    }
    Ok(())
}

pub(super) async fn handle_redeploy_v2(cmd: commands::RedeployV2Cmd, debug: bool) -> CliResult<()> {
    let _ = log_info("redeploy_v2", "Starting remote redeploy process", None).await;
    match run_redeploy_v2(cmd.password, cmd.username, cmd.host, cmd.project_dir, debug).await {
        Ok(()) => Ok(()),
        Err(e) => {
            let _ = log_error("redeploy_v2", "Remote redeploy failed", Some(&e)).await;
            Err(e.into())
        }
    }
}

pub(super) async fn handle_config(cmd: commands::ConfigCmd, debug: bool) -> CliResult<()> {
    let commands::ConfigCmd {
        project,
        no_open,
        provider,
    } = cmd;

    if provider.is_some() && (project || no_open) {
        return Err(ErrorFactory::validation(
            "config",
            "`xbp config <provider> ...` cannot be combined with `--project` or `--no-open`.",
            Some("Run either provider key management OR project/global config actions."),
        ));
    }

    if let Some(provider_cmd) = provider {
        match provider_cmd {
            commands::ConfigProviderCmd::MigrateConfigFile(subcmd) => {
                run_migrate_config_file(
                    &subcmd.format,
                    subcmd.from.as_deref(),
                    subcmd.output.as_deref(),
                )
                .map_err(|error| {
                    ErrorFactory::operation("config", "migrate config file", error, None)
                })?;
            }
            commands::ConfigProviderCmd::Openrouter(subcmd) => match subcmd.action {
                commands::ConfigSecretAction::SetKey { key } => {
                    if let Err(e) = run_config_secret_set("openrouter", key).await {
                        let _ = log_error("config", "Failed to set OpenRouter key", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "set OpenRouter key",
                            e,
                            Some("Run `xbp config openrouter show` to confirm key state."),
                        ));
                    }
                }
                commands::ConfigSecretAction::DeleteKey => {
                    if let Err(e) = run_config_secret_delete("openrouter").await {
                        let _ =
                            log_error("config", "Failed to delete OpenRouter key", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "delete OpenRouter key",
                            e,
                            Some("Use `xbp config openrouter show` to verify removal."),
                        ));
                    }
                }
                commands::ConfigSecretAction::Show { raw } => {
                    if let Err(e) = run_config_secret_show("openrouter", raw).await {
                        let _ =
                            log_error("config", "Failed to show OpenRouter key", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "show OpenRouter key",
                            e,
                            None,
                        ));
                    }
                }
            },
            commands::ConfigProviderCmd::Github(subcmd) => match subcmd.action {
                commands::ConfigSecretAction::SetKey { key } => {
                    if let Err(e) = run_config_secret_set("github", key).await {
                        let _ = log_error("config", "Failed to set GitHub token", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "set GitHub token",
                            e,
                            Some("Use a token with repo scope for private repos."),
                        ));
                    }
                }
                commands::ConfigSecretAction::DeleteKey => {
                    if let Err(e) = run_config_secret_delete("github").await {
                        let _ =
                            log_error("config", "Failed to delete GitHub token", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "delete GitHub token",
                            e,
                            None,
                        ));
                    }
                }
                commands::ConfigSecretAction::Show { raw } => {
                    if let Err(e) = run_config_secret_show("github", raw).await {
                        let _ = log_error("config", "Failed to show GitHub token", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "show GitHub token",
                            e,
                            None,
                        ));
                    }
                }
            },
            commands::ConfigProviderCmd::Cloudflare(subcmd) => match subcmd.action {
                None => {
                    if let Err(e) = run_config_cloudflare_setup().await {
                        let _ =
                            log_error("config", "Failed to configure Cloudflare", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "configure Cloudflare",
                            e,
                            Some(
                                "Run `xbp config cloudflare status` to inspect credential sources.",
                            ),
                        ));
                    }
                }
                Some(commands::CloudflareConfigAction::SetKey { key }) => {
                    if let Err(e) = run_config_secret_set("cloudflare", key).await {
                        let _ =
                            log_error("config", "Failed to set Cloudflare token", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "set Cloudflare token",
                            e,
                            Some("Use a Cloudflare API token with Secrets Store and DNS permissions."),
                        ));
                    }
                }
                Some(commands::CloudflareConfigAction::DeleteKey) => {
                    if let Err(e) = run_config_secret_delete("cloudflare").await {
                        let _ = log_error("config", "Failed to delete Cloudflare token", Some(&e))
                            .await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "delete Cloudflare token",
                            e,
                            None,
                        ));
                    }
                }
                Some(commands::CloudflareConfigAction::ShowKey { raw }) => {
                    if let Err(e) = run_config_secret_show("cloudflare", raw).await {
                        let _ =
                            log_error("config", "Failed to show Cloudflare token", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "show Cloudflare token",
                            e,
                            None,
                        ));
                    }
                }
                Some(commands::CloudflareConfigAction::SetAccountId { account_id }) => {
                    if let Err(e) = run_config_cloudflare_account_set(account_id).await {
                        let _ =
                            log_error("config", "Failed to set Cloudflare account ID", Some(&e))
                                .await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "set Cloudflare account ID",
                            e,
                            None,
                        ));
                    }
                }
                Some(commands::CloudflareConfigAction::DeleteAccountId) => {
                    if let Err(e) = run_config_cloudflare_account_delete().await {
                        let _ =
                            log_error("config", "Failed to delete Cloudflare account ID", Some(&e))
                                .await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "delete Cloudflare account ID",
                            e,
                            None,
                        ));
                    }
                }
                Some(commands::CloudflareConfigAction::ShowAccountId { raw }) => {
                    if let Err(e) = run_config_cloudflare_account_show(raw).await {
                        let _ =
                            log_error("config", "Failed to show Cloudflare account ID", Some(&e))
                                .await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "show Cloudflare account ID",
                            e,
                            None,
                        ));
                    }
                }
                Some(commands::CloudflareConfigAction::Login) => {
                    if let Err(e) = run_config_cloudflare_login().await {
                        let _ = log_error("config", "Failed to link Cloudflare", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "link Cloudflare",
                            e,
                            None,
                        ));
                    }
                }
                Some(commands::CloudflareConfigAction::Status) => {
                    if let Err(e) = run_config_cloudflare_status().await {
                        let _ =
                            log_error("config", "Failed to show Cloudflare status", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "show Cloudflare status",
                            e,
                            None,
                        ));
                    }
                }
                Some(commands::CloudflareConfigAction::Setup) => {
                    if let Err(e) = run_config_cloudflare_setup().await {
                        let _ =
                            log_error("config", "Failed to configure Cloudflare", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "configure Cloudflare",
                            e,
                            None,
                        ));
                    }
                }
            },
            #[cfg(feature = "linear")]
            commands::ConfigProviderCmd::Linear(subcmd) => match subcmd.action {
                commands::LinearConfigAction::SetKey { key } => {
                    if let Err(e) = run_config_secret_set("linear", key).await {
                        let _ = log_error("config", "Failed to set Linear API key", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "set Linear API key",
                            e,
                            Some("Use this to link Linear issue IDs in generated release notes and publish release updates to Linear initiatives."),
                        ));
                    }
                }
                commands::LinearConfigAction::DeleteKey => {
                    if let Err(e) = run_config_secret_delete("linear").await {
                        let _ =
                            log_error("config", "Failed to delete Linear API key", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "delete Linear API key",
                            e,
                            None,
                        ));
                    }
                }
                commands::LinearConfigAction::Show { raw } => {
                    if let Err(e) = run_config_secret_show("linear", raw).await {
                        let _ =
                            log_error("config", "Failed to show Linear API key", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "show Linear API key",
                            e,
                            None,
                        ));
                    }
                }
                commands::LinearConfigAction::SelectInitiative => {
                    if let Err(e) = run_config_linear_select_initiative().await {
                        let _ = log_error(
                            "config",
                            "Failed to select repo Linear initiative",
                            Some(&e),
                        )
                        .await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "select repo Linear initiative",
                            e,
                            Some("Run this inside an XBP project and configure a Linear key with `xbp config linear set-key` first."),
                        ));
                    }
                }
            },
            commands::ConfigProviderCmd::Npm(subcmd) => match subcmd.action {
                commands::RegistryConfigAction::SetKey { key } => {
                    if let Err(e) = run_config_secret_set("npm", key).await {
                        let _ = log_error("config", "Failed to set npm token", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "set npm token",
                            e,
                            Some("Use a valid npm automation or granular publish token."),
                        ));
                    }
                }
                commands::RegistryConfigAction::DeleteKey => {
                    if let Err(e) = run_config_secret_delete("npm").await {
                        let _ = log_error("config", "Failed to delete npm token", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "delete npm token",
                            e,
                            None,
                        ));
                    }
                }
                commands::RegistryConfigAction::Show { raw } => {
                    if let Err(e) = run_config_secret_show("npm", raw).await {
                        let _ = log_error("config", "Failed to show npm token", Some(&e)).await;
                        return Err(ErrorFactory::operation("config", "show npm token", e, None));
                    }
                }
                commands::RegistryConfigAction::SetupRelease => {
                    if let Err(e) = run_config_publish_setup("npm").await {
                        let _ =
                            log_error("config", "Failed to configure npm publish", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "configure npm publish",
                            e,
                            Some("Run this inside the target XBP project and ensure the package manifest exists."),
                        ));
                    }
                }
            },
            commands::ConfigProviderCmd::Crates(subcmd) => match subcmd.action {
                commands::CratesConfigAction::SetKey { key } => {
                    if let Err(e) = run_config_secret_set("crates", key).await {
                        let _ = log_error("config", "Failed to set crates token", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "set crates token",
                            e,
                            Some("Use a crates.io API token or rely on CARGO_REGISTRY_TOKEN. Then run `xbp config crates login` if you also want Cargo's local credentials file updated."),
                        ));
                    }
                }
                commands::CratesConfigAction::DeleteKey => {
                    if let Err(e) = run_config_secret_delete("crates").await {
                        let _ =
                            log_error("config", "Failed to delete crates token", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "delete crates token",
                            e,
                            None,
                        ));
                    }
                }
                commands::CratesConfigAction::Show { raw } => {
                    if let Err(e) = run_config_secret_show("crates", raw).await {
                        let _ = log_error("config", "Failed to show crates token", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "show crates token",
                            e,
                            None,
                        ));
                    }
                }
                commands::CratesConfigAction::SetupRelease => {
                    if let Err(e) = run_config_publish_setup("crates").await {
                        let _ = log_error("config", "Failed to configure crates publish", Some(&e))
                            .await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "configure crates publish",
                            e,
                            Some("Run this inside the target XBP project and point the workflow at the crate manifest you want to publish."),
                        ));
                    }
                }
                commands::CratesConfigAction::Login { key } => {
                    if let Err(e) = run_config_crates_login(key).await {
                        let _ = log_error("config", "Failed to log Cargo into crates.io", Some(&e))
                            .await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "log Cargo into crates.io",
                            e,
                            Some("Store a crates token with `xbp config crates set-key` first, or pass it directly to `xbp config crates login <token>`."),
                        ));
                    }
                }
                commands::CratesConfigAction::Logout => {
                    if let Err(e) = run_config_crates_logout().await {
                        let _ =
                            log_error("config", "Failed to log Cargo out of crates.io", Some(&e))
                                .await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "log Cargo out of crates.io",
                            e,
                            Some("This only clears Cargo's local credentials. Use `xbp config crates delete-key` if you also want to remove the token from global XBP config."),
                        ));
                    }
                }
            },
            commands::ConfigProviderCmd::Release(subcmd) => match subcmd.action {
                commands::ReleaseConfigAction::Setup => {
                    if let Err(e) = run_config_release_setup().await {
                        let _ =
                            log_error("config", "Failed to configure release settings", Some(&e))
                                .await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "configure release settings",
                            e,
                            Some("Run this inside the target XBP project to update .xbp/xbp.yaml."),
                        ));
                    }
                }
            },
            commands::ConfigProviderCmd::Discord(subcmd) => {
                if let Err(e) = run_config_discord(subcmd.action).await {
                    let _ = log_error("config", "Failed to configure Discord webhook", Some(&e))
                        .await;
                    return Err(ErrorFactory::operation(
                        "config",
                        "configure Discord webhook notifications",
                        e,
                        Some(
                            "Run `xbp config discord setup` inside a project, or use `--global` for ~/.xbp/config.yaml. Set DISCORD_WEBHOOK_URL as an alternative.",
                        ),
                    ));
                }
            }
            commands::ConfigProviderCmd::Openapi(subcmd) => match subcmd.action {
                None | Some(commands::OpenapiConfigAction::Setup) => {
                    if let Err(e) = run_config_openapi_setup().await {
                        let _ =
                            log_error("config", "Failed to configure OpenAPI generation", Some(&e))
                                .await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "configure OpenAPI generation",
                            e,
                            Some("Run this inside the target XBP project to update .xbp/xbp.yaml."),
                        ));
                    }
                }
                Some(commands::OpenapiConfigAction::Show) => {
                    if let Err(e) = run_config_openapi_show().await {
                        let _ =
                            log_error("config", "Failed to show OpenAPI config", Some(&e)).await;
                        return Err(ErrorFactory::operation(
                            "config",
                            "show OpenAPI config",
                            e,
                            Some("Run this inside the target XBP project."),
                        ));
                    }
                }
            },
            commands::ConfigProviderCmd::Oci(subcmd) => {
                if let Err(e) = crate::oci::run_config_oci(subcmd.action).await {
                    let _ = log_error("config", "Failed to configure OCI registry credentials", Some(&e))
                        .await;
                    return Err(ErrorFactory::operation(
                        "config",
                        "configure OCI registry credentials",
                        e,
                        Some(
                            "Use `xbp config oci set-registry-token --registry ghcr.io --username USER` (token masked in show).",
                        ),
                    ));
                }
            }
        }
    } else if project {
        if let Err(e) = run_config(debug).await {
            return Err(ErrorFactory::operation(
                "config",
                "read project config",
                e,
                Some("Ensure you're inside an XBP project root."),
            ));
        }
    } else if let Err(e) = open_global_config(no_open).await {
        let _ = log_error("config", "Failed to open global config", Some(&e)).await;
        return Err(ErrorFactory::operation(
            "config",
            "open global config",
            e,
            None,
        ));
    }
    Ok(())
}

pub(super) async fn handle_install(
    package: Option<String>,
    list: bool,
    force: bool,
    debug: bool,
) -> CliResult<()> {
    if list {
        crate::commands::print_install_targets_help();
        return Ok(());
    }

    let Some(package) = package else {
        crate::commands::print_install_empty_state();
        return Ok(());
    };

    if package.trim().is_empty() {
        crate::commands::print_install_empty_state();
        return Ok(());
    }

    if crate::commands::is_install_listing_request(&package) {
        crate::commands::print_install_targets_help();
        return Ok(());
    }

    let install_msg: String = format!("Installing package: {}", package);
    let _ = log_info("install", &install_msg, None).await;
    match ui::with_loader(
        &format!("Installing package `{}`", package),
        install_package(&package, force, debug),
    )
    .await
    {
        Ok(()) => {
            let success_msg = format!("Successfully installed: {}", package);
            let _ = log_success("install", &success_msg, None).await;
            Ok(())
        }
        Err(e) => Err(e.into()),
    }
}

pub(super) async fn handle_curl(cmd: commands::CurlCmd, debug: bool) -> CliResult<()> {
    let url = cmd
        .url
        .unwrap_or_else(|| "https://example.com/api".to_string());
    if let Err(e) = ui::with_loader(
        &format!("Requesting {}", url),
        curl::run_curl(&url, cmd.no_timeout, debug),
    )
    .await
    {
        let _ = log_error("curl", "Curl command failed", Some(&e)).await;
        return Err(ErrorFactory::operation(
            "curl",
            "execute request",
            e,
            Some("Double-check the URL and network connectivity."),
        ));
    }
    Ok(())
}

pub(super) async fn handle_services(debug: bool) -> CliResult<()> {
    if let Err(e) = ui::with_loader("Loading configured services", list_services(debug)).await {
        let _ = log_error("services", "Failed to list services", Some(&e)).await;
        return Err(ErrorFactory::operation(
            "services",
            "list services",
            e,
            Some("Ensure xbp config is present and valid."),
        ));
    }
    Ok(())
}

pub(super) async fn handle_service(
    command: Option<String>,
    service_name: Option<String>,
    debug: bool,
) -> CliResult<()> {
    match (command.as_deref(), service_name.as_deref()) {
        // Bare `xbp service` → preview + interactive picker (service then command)
        (None, None) => {
            if let Err(e) = run_service_interactive(debug).await {
                let _ = log_error("service", "Interactive service run failed", Some(&e)).await;
                return Err(ErrorFactory::operation(
                    "service",
                    "interactive picker",
                    e,
                    None,
                ));
            }
        }
        // `xbp service <cmd>` (no name) → pick service that supports the cmd
        (Some(cmd), None) if cmd != "help" && cmd != "--help" => {
            if let Err(e) = pick_service_for_command(cmd, debug).await {
                let _ = log_error(
                    "service",
                    &format!("Service pick for '{}' failed", cmd),
                    Some(&e),
                )
                .await;
                return Err(ErrorFactory::operation(
                    "service",
                    &format!("pick service for {}", cmd),
                    e,
                    Some("Pass a service name explicitly, or ensure commands are defined in xbp config."),
                ));
            }
        }
        // `xbp service help <name>` or `xbp service --help <name>`
        (Some(cmd), Some(name)) if cmd == "help" || cmd == "--help" => {
            if let Err(e) = show_service_help(name).await {
                let _ = log_error("service", "Failed to show service help", Some(&e)).await;
                return Err(ErrorFactory::operation(
                    "service",
                    "show service help",
                    e,
                    None,
                ));
            }
        }
        // `xbp service <cmd> <name>` — classic direct execution
        (Some(cmd), Some(name)) => {
            if let Err(e) = run_service_command(cmd, name, debug).await {
                let _ = log_error(
                    "service",
                    &format!("Service command '{}' failed", cmd),
                    Some(&e),
                )
                .await;
                return Err(ErrorFactory::operation(
                    "service",
                    &format!("run `{}` for `{}`", cmd, name),
                    e,
                    Some("Check available services via `xbp services`."),
                ));
            }
        }
        // `xbp service <name>` (no explicit command) — treat as show service info / help
        (None, Some(name)) => {
            if let Err(e) = show_service_help(name).await {
                // fall back to usage if help fails (e.g. unknown service)
                let _ = log_warn(
                    "service",
                    &format!("Could not show help for service '{}': {}", name, e),
                    None,
                )
                .await;
                print_service_usage();
            }
        }
        // `xbp service help` (no name)
        (Some(_), None) => {
            print_service_usage();
        }
    }
    Ok(())
}

pub(super) async fn handle_nginx(cmd: commands::NginxSubCommand, debug: bool) -> CliResult<()> {
    if let Err(e) = run_nginx(cmd, debug).await {
        let _ = log_error("nginx", "Nginx command failed", Some(&e.to_string())).await;
        return Err(ErrorFactory::operation(
            "nginx",
            "execute nginx command",
            e.to_string(),
            Some("Try `xbp nginx --help` for command syntax."),
        ));
    }
    Ok(())
}

pub(super) async fn handle_diag(cmd: commands::DiagCmd, debug: bool) -> CliResult<()> {
    if let Err(e) = ui::with_loader("Running diagnostics", run_diag(cmd, debug)).await {
        let _ = log_error("diag", "Diag command failed", Some(&e.to_string())).await;
        return Err(ErrorFactory::operation(
            "diag",
            "run diagnostics",
            e.to_string(),
            Some("Re-run with `--debug` for more context."),
        ));
    }
    Ok(())
}

pub(super) async fn handle_generate(cmd: commands::GenerateCmd, debug: bool) -> CliResult<()> {
    match cmd.command {
        commands::GenerateSubCommand::Config(subcmd) => {
            let args = GenerateConfigArgs {
                force: subcmd.force,
                update: subcmd.update,
                from_json: subcmd.from_json,
            };
            if let Err(e) = run_generate_config(args, debug).await {
                let _ = log_error(
                    "generate-config",
                    "Failed to generate project config",
                    Some(&e),
                )
                .await;
                return Err(ErrorFactory::operation(
                    "generate-config",
                    "generate .xbp/xbp.yaml",
                    e,
                    Some("Use --update to refresh an existing config or --force to overwrite it."),
                ));
            }
        }
        #[cfg(feature = "openapi-gen")]
        commands::GenerateSubCommand::Openapi(subcmd) => {
            let args = GenerateOpenApiArgs {
                services: subcmd.service,
                all: subcmd.all,
                aggregate: false,
                format: subcmd.format,
                output: subcmd.output,
                check: subcmd.check,
                dry_run: subcmd.dry_run,
                strict: subcmd.strict,
                no_cache: subcmd.no_cache,
                version: None,
            };
            if let Err(e) = run_generate_openapi(args, debug).await {
                let _ = log_error("generate-openapi", "Failed to generate OpenAPI", Some(&e)).await;
                return Err(ErrorFactory::operation(
                    "generate-openapi",
                    "generate OpenAPI documents",
                    e,
                    Some("Check openapi settings in .xbp/xbp.yaml or use --strict for unresolved type details."),
                ));
            }
        }
        commands::GenerateSubCommand::Systemd(subcmd) => {
            let args = GenerateSystemdArgs {
                output_dir: subcmd.output_dir,
                service: subcmd.service,
                api: subcmd.api,
            };
            if let Err(e) = run_generate_systemd(args, debug).await {
                let _ = log_error(
                    "generate-systemd",
                    "Failed to generate systemd units",
                    Some(&e),
                )
                .await;
                return Err(ErrorFactory::operation(
                    "generate-systemd",
                    "generate unit files",
                    e,
                    Some("Use a writable `--output-dir` or run with elevated permissions."),
                ));
            }
        }
    }
    Ok(())
}

pub(super) async fn handle_done(cmd: commands::DoneCmd, _debug: bool) -> CliResult<()> {
    if let Err(e) = crate::commands::run_done(
        cmd.root,
        cmd.since,
        cmd.output,
        cmd.no_ai,
        cmd.recursive,
        cmd.exclude,
    )
    .await
    {
        let _ = log_error("done", "Done command failed", Some(&e)).await;
        return Err(e.into());
    }
    Ok(())
}

#[cfg(feature = "linear")]
pub(super) async fn handle_linear(cmd: commands::LinearIssuesCmd, _debug: bool) -> CliResult<()> {
    if let Err(e) = run_linear(cmd).await {
        let _ = log_error("linear", "Linear command failed", Some(&e)).await;
        return Err(ErrorFactory::operation(
            "linear",
            "run Linear issues command",
            e,
            Some("Configure a key with `xbp config linear set-key`."),
        ));
    }
    Ok(())
}

pub(super) async fn handle_github(cmd: commands::GithubIssuesCmd, _debug: bool) -> CliResult<()> {
    if let Err(e) = run_github(cmd).await {
        let _ = log_error("github", "GitHub issues command failed", Some(&e)).await;
        return Err(ErrorFactory::operation(
            "github",
            "run GitHub issues command",
            e,
            Some("Configure a token with `xbp config github set-key` and ensure git origin is a GitHub repo."),
        ));
    }
    Ok(())
}

pub(super) async fn handle_todos(cmd: commands::TodosCmd, _debug: bool) -> CliResult<()> {
    if let Err(e) = run_todos(cmd).await {
        let _ = log_error("todos", "Todos command failed", Some(&e)).await;
        return Err(ErrorFactory::operation(
            "todos",
            "run todos scan/sync",
            e,
            Some("Try `xbp todos scan` first, then `xbp todos sync --to both --dry-run`."),
        ));
    }
    Ok(())
}

pub(super) async fn handle_issues(cmd: commands::TodosCmd, _debug: bool) -> CliResult<()> {
    if let Err(e) = crate::commands::todos::run_issues(cmd).await {
        let _ = log_error("issues", "Issues command failed", Some(&e)).await;
        return Err(ErrorFactory::operation(
            "issues",
            "run issues scan/sync",
            e,
            Some("Try `xbp issues scan` first, then `xbp issues sync --to both --dry-run`."),
        ));
    }
    Ok(())
}

pub(super) async fn handle_fix_process_monitor_json(
    cmd: commands::FixProcessMonitorJsonCmd,
    _debug: bool,
) -> CliResult<()> {
    if let Err(error) =
        crate::commands::run_fix_process_monitor_json(cmd.path, cmd.check, cmd.stdout)
    {
        let _ = log_error(
            "fix-process-monitor-json",
            "Failed to repair process monitor JSON",
            Some(&error),
        )
        .await;
        return Err(error.into());
    }
    Ok(())
}

pub(super) async fn handle_cursor(cmd: commands::CursorCmd) -> CliResult<()> {
    let result = match cmd.command {
        commands::CursorSubCommand::Ingest { dry_run } => run_cursor_ingest(dry_run).await,
    };

    if let Err(error) = result {
        let _ = log_error("cursor", "Cursor command failed", Some(&error)).await;
        return Err(error.into());
    }
    Ok(())
}

pub(super) async fn handle_login(cmd: commands::LoginCmd) -> CliResult<()> {
    let result = match cmd.action {
        Some(commands::LoginSubCommand::Status) => run_login_status().await,
        Some(commands::LoginSubCommand::Logout) => run_logout().await,
        None => run_login().await,
    };

    if let Err(e) = result {
        let _ = log_error("login", "Login command failed", Some(&e)).await;
        return Err(e.into());
    }

    Ok(())
}

pub(super) async fn handle_whoami() -> CliResult<()> {
    if let Err(e) = run_whoami().await {
        let _ = log_error("whoami", "Whoami command failed", Some(&e)).await;
        return Err(e.into());
    }

    Ok(())
}

pub(super) async fn handle_update(cmd: commands::UpdateCmd) -> CliResult<()> {
    let options = UpdateCheckOptions {
        crate_name: cmd.crate_name,
        json: cmd.json,
        install: cmd.install,
        features: cmd.features,
        no_default_features: cmd.no_default_features,
        all_features: cmd.all_features,
        fail_if_outdated: cmd.fail_if_outdated,
    };
    if let Err(e) = run_update_check(options).await {
        let _ = log_error("update", "Update check failed", Some(&e)).await;
        return Err(ErrorFactory::operation(
            "update",
            "check crates.io for a newer XBP release",
            e,
            Some(
                "Confirm network access to https://crates.io/crates/xbp, or install with `cargo install xbp --locked --features all`.",
            ),
        ));
    }
    Ok(())
}

pub(super) async fn handle_version(cmd: commands::VersionCmd, debug: bool) -> CliResult<()> {
    if let Err(e) = require_authenticated_cli_session().await {
        return Err(ErrorFactory::operation(
            "version",
            "verify CLI login",
            e,
            Some("Run `xbp login` before using version workflows."),
        ));
    }

    if cmd.push {
        crate::cli::auto_commit::set_explicit_push(true);
    }

    let commands::VersionCmd {
        target,
        explicit_version,
        git,
        command,
        ..
    } = cmd;
    let resolved_target = explicit_version.or(target);

    if command.is_some() && (resolved_target.is_some() || git) {
        return Err(ErrorFactory::validation(
            "version",
            "`xbp version release` cannot be combined with `--git`, positional targets, or `--version`/`-v` on the parent command.",
            Some(
                "Run `xbp version release` as a standalone command, or use `xbp version --version <x.y.z>` without a subcommand.",
            ),
        ));
    }

    if let Some(subcommand) = command {
        match subcommand {
            commands::VersionSubCommand::Release(release_cmd) => {
                let options = VersionReleaseOptions {
                    explicit_version: release_cmd.version,
                    release_flag: release_cmd.flag.map(|flag| flag.as_str().to_string()),
                    allow_dirty: release_cmd.allow_dirty,
                    title: release_cmd.title,
                    notes: release_cmd.notes,
                    notes_file: release_cmd.notes_file,
                    draft: release_cmd.draft,
                    prerelease: release_cmd.prerelease,
                    publish: release_cmd.publish,
                    force: release_cmd.force,
                    dry_run: release_cmd.dry_run,
                    latest_policy: match release_cmd.make_latest {
                        commands::VersionReleaseLatest::True => ReleaseLatestPolicy::True,
                        commands::VersionReleaseLatest::False => ReleaseLatestPolicy::False,
                        commands::VersionReleaseLatest::Legacy => ReleaseLatestPolicy::Legacy,
                    },
                };
                if let Err(e) = run_version_release_command(options).await {
                    let hint = version_release_error_hint(&e);
                    return Err(ErrorFactory::operation(
                        "version",
                        "release version",
                        e,
                        hint,
                    ));
                }
                return Ok(());
            }
            commands::VersionSubCommand::Discover(discover_cmd) => {
                if let Err(e) = run_version_discover_services(&discover_cmd).await {
                    return Err(ErrorFactory::operation(
                        "version",
                        "discover and register project services",
                        e,
                        Some(
                            "Run `xbp version discover --dry-run` to preview package roots, or `--no-register` to opt out of writing.",
                        ),
                    ));
                }
                return Ok(());
            }
            commands::VersionSubCommand::Bump(bump_cmd) => {
                if bump_cmd.push {
                    crate::cli::auto_commit::set_explicit_push(true);
                }
                if let Err(e) = run_version_bump_command(&bump_cmd).await {
                    return Err(ErrorFactory::operation(
                        "version",
                        "bump mutated package versions",
                        e,
                        Some(
                            "Run `xbp version bump --dry-run` to preview candidates. On a clean tree every registered package is offered; use `--all --patch` (or `--minor`/`--major`) in non-interactive shells.",
                        ),
                    ));
                }
                return Ok(());
            }
            commands::VersionSubCommand::Domain(domain_cmd) => {
                let command = match domain_cmd.command {
                    commands::VersionDomainSubCommand::Init(init_cmd) => {
                        VersionDomainCommand::Init(VersionDomainInitOptions {
                            name: init_cmd.name,
                            root: init_cmd.root,
                            write: init_cmd.write,
                        })
                    }
                    commands::VersionDomainSubCommand::Doctor(doctor_cmd) => {
                        VersionDomainCommand::Doctor(VersionDomainDoctorOptions {
                            domain: doctor_cmd.domain,
                        })
                    }
                    commands::VersionDomainSubCommand::Sync(sync_cmd) => {
                        VersionDomainCommand::Sync(VersionDomainSyncOptions {
                            domain: sync_cmd.domain,
                            write: sync_cmd.write,
                        })
                    }
                    commands::VersionDomainSubCommand::Diagnose(diagnose_cmd) => {
                        VersionDomainCommand::Diagnose(VersionDomainDiagnoseOptions {
                            domain: diagnose_cmd.domain,
                            log: diagnose_cmd.log,
                        })
                    }
                    commands::VersionDomainSubCommand::Release(release_cmd) => {
                        VersionDomainCommand::Release(VersionDomainReleaseOptions {
                            domain: release_cmd.domain,
                            patch: release_cmd.patch,
                            minor: release_cmd.minor,
                            major: release_cmd.major,
                            version: release_cmd.version,
                            deploy: release_cmd.deploy,
                            allow_major_jump: release_cmd.allow_major_jump,
                            allow_cross_domain_version: release_cmd.allow_cross_domain_version,
                        })
                    }
                };
                if let Err(e) =
                    run_version_domain_command(VersionDomainCommandOptions { command }).await
                {
                    return Err(ErrorFactory::operation(
                        "version",
                        "run version-domain command",
                        e,
                        Some("Run `xbp version domain -h` to inspect supported usage."),
                    ));
                }
                return Ok(());
            }
            commands::VersionSubCommand::Workspace(workspace_cmd) => {
                let (repo, json, workspace_command) = match workspace_cmd.command {
                    commands::VersionWorkspaceSubCommand::Check(check_cmd) => (
                        check_cmd.target.repo,
                        check_cmd.target.json,
                        WorkspaceVersionCommand::Check(WorkspaceVersionCheckOptions {
                            version: check_cmd.version,
                        }),
                    ),
                    commands::VersionWorkspaceSubCommand::Sync(sync_cmd) => (
                        sync_cmd.target.repo,
                        sync_cmd.target.json,
                        WorkspaceVersionCommand::Sync(WorkspaceVersionSyncOptions {
                            version: sync_cmd.version,
                            write: sync_cmd.write,
                        }),
                    ),
                    commands::VersionWorkspaceSubCommand::Validate(validate_cmd) => (
                        validate_cmd.target.repo,
                        validate_cmd.target.json,
                        WorkspaceVersionCommand::Validate(WorkspaceVersionValidateOptions {
                            package: validate_cmd.package,
                            cargo_check: validate_cmd.cargo_check,
                            package_dry_run: validate_cmd.package_dry_run,
                        }),
                    ),
                    commands::VersionWorkspaceSubCommand::Publish(publish_cmd) => {
                        match publish_cmd.command {
                            commands::VersionWorkspacePublishSubCommand::Plan(plan_cmd) => (
                                plan_cmd.target.repo,
                                plan_cmd.target.json,
                                WorkspaceVersionCommand::PublishPlan(WorkspacePublishPlanOptions {
                                    only: plan_cmd.only,
                                    include_prereqs: plan_cmd.include_prereqs,
                                }),
                            ),
                            commands::VersionWorkspacePublishSubCommand::Heal(heal_cmd) => (
                                heal_cmd.target.repo,
                                heal_cmd.target.json,
                                WorkspaceVersionCommand::PublishHeal(WorkspacePublishHealOptions {
                                    only: heal_cmd.only,
                                    include_prereqs: heal_cmd.include_prereqs,
                                    write: heal_cmd.write,
                                    version: heal_cmd.version,
                                }),
                            ),
                            commands::VersionWorkspacePublishSubCommand::Run(run_cmd) => (
                                run_cmd.target.repo,
                                run_cmd.target.json,
                                WorkspaceVersionCommand::PublishRun(WorkspacePublishRunOptions {
                                    dry_run: run_cmd.dry_run,
                                    from: run_cmd.from,
                                    only: run_cmd.only,
                                    include_prereqs: run_cmd.include_prereqs,
                                    continue_on_error: run_cmd.continue_on_error,
                                    allow_dirty: run_cmd.allow_dirty,
                                    auto_fix: run_cmd.auto_fix,
                                    timeout_seconds: run_cmd.timeout_seconds,
                                    poll_interval_seconds: run_cmd.poll_interval_seconds,
                                }),
                            ),
                        }
                    }
                };

                if let Err(e) = run_version_workspace_command(WorkspaceVersionCommandOptions {
                    repo,
                    json,
                    command: workspace_command,
                })
                .await
                {
                    return Err(ErrorFactory::operation(
                        "version",
                        "run workspace version command",
                        e,
                        Some("Run `xbp version workspace -h` to inspect supported usage."),
                    ));
                }
                return Ok(());
            }
        }
    }

    if let Err(e) = run_version_command(resolved_target, git, debug).await {
        return Err(ErrorFactory::operation(
            "version",
            "run version command",
            e,
            Some("Run `xbp version -h` to inspect supported usage."),
        ));
    }
    Ok(())
}

fn version_release_error_hint(error: &str) -> Option<&'static str> {
    if error.contains("Working tree is dirty") || error.contains("uncommitted changes") {
        return Some(
            "Use `--allow-dirty` if only generated files changed. `--force` also allows a dirty tree when `--publish` is enabled.",
        );
    }
    if error.contains("CARGO_REGISTRY_TOKEN") || error.contains("no token found") {
        return Some(
            "Configure a crates.io token with `xbp config crates set-key` or export `CARGO_REGISTRY_TOKEN`.",
        );
    }
    if error.contains("Workspace version drift detected") {
        return Some(
            "Run `xbp version workspace sync --write` to align crate versions, or pass `--force` to auto-sync during release.",
        );
    }
    if error.contains("Workspace closure detected")
        || error.contains("workspace publish command failed")
    {
        return Some(
            "For multi-crate workspaces, inspect the publish output and run `xbp version workspace publish plan --include-prereqs` first.",
        );
    }
    if error.contains("Duplicate port found") || error.contains("Duplicate service name") {
        return Some(
            "Duplicate service ports/names are deploy-time checks. Re-run `xbp version release` (release no longer blocks on them). Fix ports in `.xbp/xbp.yaml` before `xbp deploy`/`xbp start`.",
        );
    }
    if error.contains("Release cancelled") {
        return Some(
            "Re-run with `--allow-dirty` to skip dirty-tree prompts, or `--force` to auto-heal workspace versions and allow dirty publishes.",
        );
    }
    None
}

fn should_print_help(cli: &Cli) -> bool {
    cli.command.is_none()
        && !cli.list
        && !cli.logs
        && !cli.commands
        && cli.query.is_none()
        && cli.port.is_none()
}

/// When both root help (`-h`/`--help`) and a query (`-q`/`--query`) appear,
/// drop the help flags so clap does not short-circuit before parsing the query.
/// Subcommand help (`xbp workers -h`) is unaffected when no root `-q` is present.
fn preprocess_argv_for_help_query(args: Vec<String>) -> Vec<String> {
    let has_query = args.iter().skip(1).any(|a| {
        a == "-q" || a == "--query" || a.starts_with("--query=") || a.starts_with("-q=")
    });
    if !has_query {
        return args;
    }
    args.into_iter()
        .filter(|a| a != "-h" && a != "--help")
        .collect()
}

#[cfg(test)]
mod help_query_argv_tests {
    use super::preprocess_argv_for_help_query;

    #[test]
    fn strips_root_help_when_query_present() {
        let out = preprocess_argv_for_help_query(vec![
            "xbp".into(),
            "-h".into(),
            "-q".into(),
            "deploy".into(),
        ]);
        assert_eq!(out, vec!["xbp", "-q", "deploy"]);
    }

    #[test]
    fn leaves_argv_when_no_query() {
        let out = preprocess_argv_for_help_query(vec!["xbp".into(), "diag".into(), "-h".into()]);
        assert_eq!(out, vec!["xbp", "diag", "-h"]);
    }

    #[test]
    fn strips_long_help_with_long_query() {
        let out = preprocess_argv_for_help_query(vec![
            "xbp".into(),
            "--help".into(),
            "--query".into(),
            "webhook".into(),
        ]);
        assert_eq!(out, vec!["xbp", "--query", "webhook"]);
    }

    #[test]
    fn strips_both_help_forms() {
        let out = preprocess_argv_for_help_query(vec![
            "xbp".into(),
            "-h".into(),
            "--help".into(),
            "-q".into(),
            "ports".into(),
        ]);
        assert_eq!(out, vec!["xbp", "-q", "ports"]);
    }

    #[test]
    fn keeps_query_equals_form() {
        let out = preprocess_argv_for_help_query(vec![
            "xbp".into(),
            "-h".into(),
            "--query=deploy".into(),
        ]);
        assert_eq!(out, vec!["xbp", "--query=deploy"]);
    }

    #[test]
    fn keeps_short_query_equals_form() {
        let out =
            preprocess_argv_for_help_query(vec!["xbp".into(), "--help".into(), "-q=nginx".into()]);
        assert_eq!(out, vec!["xbp", "-q=nginx"]);
    }

    #[test]
    fn leaves_plain_help_alone() {
        let out = preprocess_argv_for_help_query(vec!["xbp".into(), "--help".into()]);
        assert_eq!(out, vec!["xbp", "--help"]);
    }

    #[test]
    fn leaves_subcommand_help_without_root_query() {
        let out = preprocess_argv_for_help_query(vec![
            "xbp".into(),
            "workers".into(),
            "list".into(),
            "-h".into(),
        ]);
        assert_eq!(out, vec!["xbp", "workers", "list", "-h"]);
    }

    #[test]
    fn strips_help_even_if_query_comes_first() {
        let out = preprocess_argv_for_help_query(vec![
            "xbp".into(),
            "-q".into(),
            "linear".into(),
            "-h".into(),
        ]);
        assert_eq!(out, vec!["xbp", "-q", "linear"]);
    }

    #[test]
    fn empty_args_passthrough() {
        let out = preprocess_argv_for_help_query(vec!["xbp".into()]);
        assert_eq!(out, vec!["xbp"]);
    }
}

fn background_cursor_ingest_trigger(command: Option<&commands::Commands>) -> Option<&'static str> {
    match command {
        None => None,
        Some(commands::Commands::Cursor(_)) => None,
        Some(commands::Commands::Diag(_)) => None,
        Some(commands::Commands::Whoami) => None,
        Some(commands::Commands::Update(_)) => None,
        Some(commands::Commands::Login(login_cmd)) => match login_cmd.action {
            None => Some("login"),
            Some(commands::LoginSubCommand::Status | commands::LoginSubCommand::Logout) => None,
        },
        Some(other) => Some(commands::command_label(other)),
    }
}

fn background_system_inventory_refresh_trigger(
    command: Option<&commands::Commands>,
) -> Option<&'static str> {
    match command {
        None => None,
        Some(commands::Commands::Cursor(_)) => None,
        Some(commands::Commands::Diag(_)) => None,
        Some(commands::Commands::Whoami) => None,
        Some(commands::Commands::Update(_)) => None,
        Some(commands::Commands::Login(login_cmd)) => match login_cmd.action {
            None => Some("login"),
            Some(commands::LoginSubCommand::Status | commands::LoginSubCommand::Logout) => None,
        },
        Some(other) => Some(commands::command_label(other)),
    }
}

fn print_service_usage() {
    ui::configure_color_output();
    println!();
    println!("{}", "xbp service".bright_magenta().bold());
    ui::divider(28);
    println!(
        "{} {}",
        "Usage:".bright_cyan().bold(),
        "xbp service [command] [service-name]".bright_white()
    );
    println!();
    println!("Running with no arguments opens an interactive preview + picker.");
    ui::section("Commands");
    for command in ["build", "install", "start", "dev", "pre"] {
        println!("  {}", command.bright_cyan());
    }
    ui::section("Examples");
    println!(
        "  {}",
        "xbp service                      # interactive: pick service → command".dimmed()
    );
    println!(
        "  {}",
        "xbp service start                # pick from services that support start".dimmed()
    );
    println!("  {}", "xbp service build zeus".dimmed());
    ui::tip("Run `xbp service --help <service-name>` for service-specific guidance. All runs are recorded under $HOME/.xbp/logs/service/");
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::cli::commands::{Commands, VersionReleaseLatest, VersionSubCommand};

    #[test]
    fn plain_cli_invocation_prints_help() {
        let cli = Cli::try_parse_from(["xbp"]).expect("parse");
        assert!(should_print_help(&cli));
    }

    #[test]
    fn root_version_short_v_displays_version() {
        let err = Cli::try_parse_from(["xbp", "-v"]).expect_err("version");
        assert_eq!(err.kind(), ClapErrorKind::DisplayVersion);
    }

    #[test]
    fn root_version_capital_v_and_long_still_display_version() {
        let err_v = Cli::try_parse_from(["xbp", "-V"]).expect_err("version -V");
        assert_eq!(err_v.kind(), ClapErrorKind::DisplayVersion);
        let err_long = Cli::try_parse_from(["xbp", "--version"]).expect_err("version long");
        assert_eq!(err_long.kind(), ClapErrorKind::DisplayVersion);
    }

    #[test]
    fn list_flag_skips_help_short_circuit() {
        let cli = Cli::try_parse_from(["xbp", "-l"]).expect("parse");
        assert!(!should_print_help(&cli));
    }

    #[test]
    fn commands_flag_skips_help_short_circuit() {
        let cli = Cli::try_parse_from(["xbp", "--commands"]).expect("parse");
        assert!(!should_print_help(&cli));
        assert!(cli.commands);
    }

    #[test]
    fn install_without_package_parses_and_is_optional() {
        let cli = Cli::try_parse_from(["xbp", "install"]).expect("parse");
        let Some(Commands::Install {
            list,
            force,
            package,
        }) = cli.command
        else {
            panic!("expected install command");
        };
        assert!(!list);
        assert!(!force);
        assert!(package.is_none());
    }

    #[test]
    fn install_with_package_still_parses() {
        let cli = Cli::try_parse_from(["xbp", "install", "docker"]).expect("parse");
        let Some(Commands::Install {
            list,
            force,
            package,
        }) = cli.command
        else {
            panic!("expected install command");
        };
        assert!(!list);
        assert!(!force);
        assert_eq!(package.as_deref(), Some("docker"));
    }

    #[test]
    fn install_force_flag_parses() {
        let cli = Cli::try_parse_from(["xbp", "install", "--force", "nx-brew"]).expect("parse");
        let Some(Commands::Install {
            list,
            force,
            package,
        }) = cli.command
        else {
            panic!("expected install command");
        };
        assert!(!list);
        assert!(force);
        assert_eq!(package.as_deref(), Some("nx-brew"));
    }

    #[test]
    fn install_list_flag_parses() {
        let cli = Cli::try_parse_from(["xbp", "install", "--list"]).expect("parse");
        let Some(Commands::Install {
            list,
            force: _,
            package,
        }) = cli.command
        else {
            panic!("expected install command");
        };
        assert!(list);
        assert!(package.is_none());
    }

    #[test]
    fn install_short_list_flag_parses() {
        let cli = Cli::try_parse_from(["xbp", "install", "-l"]).expect("parse");
        let Some(Commands::Install {
            list,
            force: _,
            package,
        }) = cli.command
        else {
            panic!("expected install command");
        };
        assert!(list);
        assert!(package.is_none());
    }

    #[test]
    fn install_ls_alias_parses_as_package() {
        let cli = Cli::try_parse_from(["xbp", "install", "ls"]).expect("parse");
        let Some(Commands::Install {
            list,
            force: _,
            package,
        }) = cli.command
        else {
            panic!("expected install command");
        };
        assert!(!list);
        assert_eq!(package.as_deref(), Some("ls"));
    }

    #[test]
    fn version_release_make_latest_parses_explicit_value() {
        let cli = Cli::try_parse_from([
            "xbp",
            "version",
            "release",
            "--version",
            "1.2.3",
            "--make-latest",
            "false",
        ])
        .expect("parse");
        let Some(Commands::Version(version_cmd)) = cli.command else {
            panic!("expected version command");
        };
        assert!(version_cmd.explicit_version.is_none());
        let Some(VersionSubCommand::Release(release_cmd)) = version_cmd.command else {
            panic!("expected version release subcommand");
        };
        assert!(matches!(
            release_cmd.make_latest,
            VersionReleaseLatest::False
        ));
    }

    #[test]
    fn version_release_make_latest_defaults_to_legacy() {
        let cli = Cli::try_parse_from(["xbp", "version", "release", "--version", "1.2.3"])
            .expect("parse");
        let Some(Commands::Version(version_cmd)) = cli.command else {
            panic!("expected version command");
        };
        let Some(VersionSubCommand::Release(release_cmd)) = version_cmd.command else {
            panic!("expected version release subcommand");
        };
        assert!(matches!(
            release_cmd.make_latest,
            VersionReleaseLatest::Legacy
        ));
        assert!(!release_cmd.dry_run);
        assert!(!release_cmd.publish);
    }

    #[test]
    fn version_release_parses_dry_run_and_publish() {
        let cli = Cli::try_parse_from([
            "xbp",
            "version",
            "release",
            "--version",
            "1.2.3",
            "--publish",
            "--dry-run",
        ])
        .expect("parse");
        let Some(Commands::Version(version_cmd)) = cli.command else {
            panic!("expected version command");
        };
        let Some(VersionSubCommand::Release(release_cmd)) = version_cmd.command else {
            panic!("expected version release subcommand");
        };
        assert!(release_cmd.dry_run);
        assert!(release_cmd.publish);
    }

    #[test]
    fn version_explicit_flag_parses() {
        let cli = Cli::try_parse_from(["xbp", "version", "--version", "1.2.3"]).expect("parse");
        let Some(Commands::Version(version_cmd)) = cli.command else {
            panic!("expected version command");
        };
        assert_eq!(version_cmd.explicit_version.as_deref(), Some("1.2.3"));
        assert!(version_cmd.target.is_none());
        assert!(version_cmd.command.is_none());
    }

    #[test]
    fn version_short_explicit_flag_parses_with_alias() {
        let cli = Cli::try_parse_from(["xbp", "v", "-v", "1.2.3"]).expect("parse");
        let Some(Commands::Version(version_cmd)) = cli.command else {
            panic!("expected version command");
        };
        assert_eq!(version_cmd.explicit_version.as_deref(), Some("1.2.3"));
        assert!(version_cmd.target.is_none());
        assert!(version_cmd.command.is_none());
    }
}