zoi_cli/

cli.rs

use std::io::{self};
use std::path::PathBuf;

use clap::builder::styling;
use clap::{
    ColorChoice, CommandFactory, FromArgMatches, Parser, Subcommand, ValueHint
};
use clap_complete::{Shell, generate};
use colored::Colorize;
use zoi_common::Runnable;

use crate::pkg::lock;
use crate::{cmd, utils};

/// The ZFVM branch identifier of the current build (Prod, Dev, Spec, Pub).
///
/// This is the identifier, not the long-form name: the ZFVM Canonical Form is
/// `Prod Beta 1.2.3`, never `Production Beta 1.2.3`. Long-form names are for
/// display only and are mapped in `utils::format_version_summary`.
///
/// Updated by `scripts/bump.sh`, not by hand.
const BRANCH: &str = "Prod";

/// The ZFVM status of the current build (Pre-Alpha, Alpha, Beta, RC, Release).
///
/// Updated by `scripts/bump.sh`, not by hand.
const STATUS: &str = "Release";

/// The core version of the current build, as `X.Y.Z`.
///
/// Updated by `scripts/bump.sh`, not by hand.
const NUMBER: &str = "1.29.3";
/// Help text for package source identifiers.
const PKG_SOURCE_HELP: &str =
    "Package identifier (e.g. @repo/name, #git@repo/name, path, or URL)";

/// Zoi - The Advanced Package Manager & Environment Orchestrator.
///
/// Part of the Zillowe Development Suite (ZDS), Zoi is designed to streamline
/// your development workflow by managing tools and project environments.
#[derive(Parser)]
#[command(name = "zoi", author, about, long_about = None, disable_version_flag = true,
    trailing_var_arg = true,
    color = ColorChoice::Auto,
    arg_required_else_help = true,
)]
pub struct Cli {
    /// The subcommand to execute.
    #[command(subcommand)]
    command: Option<Commands>,

    /// Print detailed version information.
    #[arg(
        short = 'v',
        long = "version",
        help = "Print detailed version information"
    )]
    version_flag: bool,

    /// Automatically answer yes to all prompts.
    #[arg(
        short = 'y',
        long,
        help = "Automatically answer yes to all prompts",
        global = true
    )]
    yes: bool,

    /// Operate on a different root directory.
    #[arg(
        long = "root",
        help = "Operate on a different root directory",
        global = true,
        value_hint = ValueHint::DirPath
    )]
    pub root: Option<std::path::PathBuf>,

    /// Do not attempt to connect to the network.
    #[arg(
        long = "offline",
        help = "Do not attempt to connect to the network",
        global = true
    )]
    pub offline: bool,

    /// Additional directory to search for .zpa archives.
    #[arg(
        long = "pkg-dir",
        help = "Additional directory to search for .zpa archives",
        global = true,
        value_hint = ValueHint::DirPath
    )]
    /// Additional directory to search for .zpa archives.
    pub pkg_dirs: Vec<std::path::PathBuf>
}

/// The target scope for system-level operations.
#[derive(clap::ValueEnum, Clone, Debug, Copy, PartialEq, Eq)]
pub enum SetupScope {
    /// The current user's scope.
    User,
    /// The system-wide scope.
    System
}

/// The target scope for package installation.
#[derive(clap::ValueEnum, Clone, Debug, Copy)]
pub enum InstallScope {
    /// The current user's scope.
    User,
    /// The system-wide scope.
    System,
    /// The current project's scope.
    Project
}

/// Subcommands for `zoi alt`, which manages alternative implementations.
///
/// Separate from the main command enum because `Alt` carries its own
/// subcommand tree, and clap needs the nested variant declared here.
#[derive(Subcommand)]
pub enum AltCommand {
    /// List every registered alternative
    #[command(alias = "ls")]
    List {
        /// Show each group's candidates and their owners
        #[arg(short, long)]
        verbose: bool
    },
    /// Show one alternative in detail
    Get {
        /// Name of the alternative, e.g. awk
        name: String
    },
    /// Select an implementation for an alternative
    Set {
        /// Name of the alternative, e.g. awk
        name: String,
        /// Path of the implementation to select, e.g. /usr/bin/mawk
        path: String
    },
    /// Return to selecting the highest-priority implementation
    Auto {
        /// Name of the alternative, e.g. awk
        name: String
    },
    /// Remove one implementation from an alternative
    Remove {
        /// Name of the alternative, e.g. awk
        name: String,
        /// Path of the implementation to remove
        path: String
    }
}

/// The available subcommands for Zoi.
#[derive(Subcommand)]
enum Commands {
    /// Generates shell completion scripts
    #[command(hide = true)]
    GenerateCompletions {
        /// The shell to generate completions for
        #[arg(value_enum)]
        shell: Shell
    },

    /// Dynamic shell completions (internal use)
    #[command(hide = true)]
    Complete {
        /// The shell to complete for
        #[arg(value_enum)]
        shell: Shell,
        /// Current word index (1-based)
        index: usize,
        /// All words in the command line
        words: Vec<String>
    },

    /// Prints concise version and build information
    #[command(
        alias = "v",
        long_about = "Displays the version number, build status, branch, and \
                      commit hash. This is the same output provided by the -v \
                      and --version flags."
    )]
    Version,

    /// Shows detailed application information and credits
    #[command(long_about = "Displays the full application name, description, \
                            author, license, and homepage information.")]
    About,

    /// Displays detected operating system and architecture information
    #[command(long_about = "Detects and displays key system details, \
                            including the OS, CPU architecture, Linux \
                            distribution (if applicable), and available \
                            package managers.")]
    Info,

    /// Downloads a package archive or source bundle
    #[command(
        alias = "dl",
        long_about = "Downloads the binary archive (.zpa) or source bundle \
                      (.zsa) for a package to the local cache or a specified \
                      directory."
    )]
    Download {
        /// Package identifier (e.g. @repo/name, path, or URL)
        #[arg(value_name = "PACKAGE", required = true, help = PKG_SOURCE_HELP)]
        package: String,

        /// Download the binary archive (.zpa) [default]
        #[arg(long, group = "type")]
        archive: bool,

        /// Download the source bundle (.zsa)
        #[arg(long, group = "type")]
        source: bool,

        /// Directory to output the downloaded file to
        #[arg(short, long)]
        output_dir: Option<PathBuf>
    },

    /// Downloads or updates the package database from the remote repository
    #[command(
        alias = "sy",
        long_about = "Clones the official package database from GitLab to \
                      Zoi's user data directory. If the database already \
                      exists, it verifies the remote URL and pulls the latest \
                      changes."
    )]
    Sync {
        /// The sync subcommand to execute.
        #[command(subcommand)]
        command: Option<SyncCommands>,

        /// Show the full git output
        #[arg(short, long)]
        verbose: bool,

        /// Fallback to other mirrors if the default one fails
        #[arg(long)]
        fallback: bool,

        /// Do not check for installed package managers
        #[arg(long = "no-pm")]
        no_package_managers: bool,

        /// Force re-sync by removing existing databases and re-cloning from
        /// scratch
        #[arg(long)]
        force: bool,

        /// Sync registries to the project's local .zoi/pkgs/db/ using
        /// revisions from zoi.lua
        #[arg(long)]
        local: bool,

        /// When used with --local, sync using revisions from zoi.lock instead
        /// of zoi.lua
        #[arg(long)]
        frozen: bool,

        /// The scope to sync the registries to
        #[arg(long, value_enum, conflicts_with = "local")]
        scope: Option<SetupScope>
    },

    /// Migration helpers for converting external manifests to Zoi package files
    Migrate(cmd::migrate::MigrateCommand),

    /// Lists installed or all available packages
    #[command(alias = "ls")]
    List {
        /// List all packages from the database, not just installed ones
        #[arg(short, long)]
        all: bool,
        /// List only installed packages that have updates available
        #[arg(short, long)]
        outdated: bool,
        /// Filter by registry handle (e.g. 'zoidberg')
        #[arg(long)]
        registry: Option<String>,
        /// Filter by repository (e.g. 'main', 'extra')
        #[arg(long)]
        repo: Option<String>,
        /// Filter by package type (package, app, collection, extension)
        #[arg(short = 't', long = "type")]
        package_type: Option<String>,
        /// List packages not found in any configured registry
        #[arg(short = 'm', long)]
        foreign: bool,
        /// List only package names (internal use for completions)
        #[arg(long, hide = true)]
        names: bool,
        /// List packages with descriptions for completion
        #[arg(long, hide = true)]
        completion: bool
    },

    /// Shows detailed information about a package
    Show {
        /// The package identifier.
        #[arg(value_name = "ALL_PACKAGES", help = PKG_SOURCE_HELP)]
        package_name: String,
        /// Display the raw, unformatted package file
        #[arg(long)]
        raw: bool,
        /// Use PURL (Package URL) specification for resolving package
        #[arg(long)]
        purl: bool
    },

    /// Pin a package to a specific version
    Pin {
        /// The package identifier.
        #[arg(value_name = "INST_PACKAGES", help = PKG_SOURCE_HELP)]
        package: String,
        /// The version to pin the package to
        version: String
    },

    /// Find which package provides a specific command or file
    Provides {
        /// The command or file path to search for
        term: String
    },

    /// Visualize the dependency tree of a package
    Tree {
        /// The package identifier(s).
        #[arg(value_name = "ALL_PACKAGES", required = true, help = PKG_SOURCE_HELP)]
        packages: Vec<String>
    },

    /// Unpin a package, allowing it to be updated
    Unpin {
        /// The package identifier.
        #[arg(value_name = "INST_PACKAGES", help = PKG_SOURCE_HELP)]
        package: String
    },

    /// Modify the installation reason of a package
    #[command(
        alias = "m",
        long_about = "Changes whether a package is considered explicitly installed or a dependency. Explicit packages are not removed by 'autoremove', while dependencies are if no other package requires them.",
        group(clap::ArgGroup::new("mode").required(true).args(["as_dependency", "as_explicit"]))
    )]
    Mark {
        /// The package identifier(s).
        #[arg(value_name = "INST_PACKAGES", required = true, help = PKG_SOURCE_HELP)]
        packages: Vec<String>,

        /// Mark packages as dependencies
        #[arg(long, aliases = ["asdeps"])]
        as_dependency: bool,

        /// Mark packages as explicitly installed
        #[arg(long, aliases = ["asexpl"], conflicts_with = "as_dependency")]
        as_explicit: bool
    },

    /// Updates one or more packages to their latest versions
    #[command(
        alias = "up",
        arg_required_else_help = true,
        group(clap::ArgGroup::new("target").required(true).args(["package_names", "all"]))
    )]
    Update {
        /// The package names to update.
        #[arg(value_name = "INST_PACKAGES", help = PKG_SOURCE_HELP)]
        package_names: Vec<String>,

        /// Update all installed packages
        #[arg(long, conflicts_with = "package_names")]
        all: bool,

        /// Do not actually perform the update, just show what would be done
        #[arg(long)]
        dry_run: bool,
        /// Explain why each selected update is included or skipped
        #[arg(long)]
        explain: bool,
        /// Emit machine-readable update plan JSON
        #[arg(long, requires = "dry_run")]
        plan_json: bool,
        /// Show additional update details
        #[arg(long, short)]
        verbose: bool,
        /// Interactively choose which upgradable packages to update (with
        /// --all)
        #[arg(long, requires = "all")]
        interactive: bool
    },

    /// Installs one or more packages from a name, local file, URL, or git
    /// repository
    #[command(aliases = ["i", "in", "add"])]
    Install(cmd::install::args::InstallArgs),

    /// Uninstalls one or more packages previously installed by Zoi
    #[command(
        aliases = ["un", "rm", "remove"],
        long_about = "Removes one or more packages' files from the Zoi store and deletes their symlinks from the bin directory. This command will fail if a package was not installed by Zoi."
    )]
    Uninstall(cmd::uninstall::args::UninstallArgs),

    /// Execute a command defined in a local zoi.lua file
    #[command(long_about = "Execute a command from zoi.lua. If no command is \
                            specified, it will launch an interactive prompt \
                            to choose one.")]
    Run {
        /// The alias of the command to execute
        cmd_alias: Option<String>,
        /// Arguments to pass to the command
        args: Vec<String>
    },

    /// Manage and set up project environments from a local zoi.lua file
    #[command(long_about = "Checks for required packages and runs setup \
                            commands for a defined environment. If no \
                            environment is specified, it launches an \
                            interactive prompt.")]
    Env {
        /// The alias of the environment to set up
        env_alias: Option<String>,

        /// Export environment variables for the current shell
        #[arg(long, value_enum, hide = true)]
        export_shell: Option<Shell>
    },

    /// Enter a development shell for the current project
    #[command(
        alias = "develop",
        long_about = "Loads the project configuration from zoi.lua, ensures \
                      all required packages are installed locally, sets up \
                      environment variables (PATH, LD_LIBRARY_PATH, etc.), \
                      and drops you into a subshell."
    )]
    Dev {
        /// Command to run in the dev shell instead of an interactive shell
        #[arg(short, long)]
        run: Option<String>,
        /// Temporary clone a repository and enter its development shell
        #[arg(long)]
        repo: Option<String>
    },

    /// Upgrades the Zoi binary to the latest version
    #[command(
        alias = "ug",
        long_about = "Upgrades Zoi to the latest version. By default, it \
                      attempts a delta upgrade (bsdiff) to minimize download \
                      size. If the delta upgrade is unavailable or fails, it \
                      automatically falls back to a full download."
    )]
    Upgrade {
        /// Force a full download instead of a delta upgrade
        #[arg(long)]
        force: bool,

        /// Upgrade to a specific git tag
        #[arg(long)]
        tag: Option<String>,

        /// Upgrade to the latest release of a specific branch (e.g. Prod, Pub)
        #[arg(long)]
        branch: Option<String>
    },

    /// Removes packages that were installed as dependencies but are no longer
    /// needed
    Autoremove {
        /// Do not actually remove packages, just show what would be done
        #[arg(long)]
        dry_run: bool
    },

    /// Explains why a package is installed
    Why {
        /// The package identifier.
        #[arg(value_name = "INST_PACKAGES", help = PKG_SOURCE_HELP)]
        package_name: String
    },

    /// Find which package owns a file
    #[command(alias = "owns")]
    Owner {
        /// Path to the file
        #[arg(value_hint = ValueHint::FilePath)]
        path: std::path::PathBuf
    },

    /// List all files owned by a package
    Files {
        /// The package identifier.
        #[arg(value_name = "INST_PACKAGES", help = PKG_SOURCE_HELP)]
        package: String
    },

    /// Inspect and choose alternative implementations
    ///
    /// For commands with several interchangeable implementations, such as awk,
    /// vi or editor. Packages register alternatives and Zoi keeps the canonical
    /// path pointing at the one with the highest priority, which can be
    /// overridden per system without reinstalling anything.
    #[command(subcommand, name = "alt")]
    Alt(AltCommand),

    /// Shows the history of package operations
    History {
        /// Verify audit log chain integrity instead of printing history
        /// entries
        #[arg(long, conflicts_with = "export")]
        verify: bool,
        /// Export audit history to a file (default format: JSON array with
        /// chain fields)
        #[arg(long, value_hint = ValueHint::FilePath, conflicts_with = "verify")]
        export: Option<std::path::PathBuf>,
        /// Export in newline-delimited JSON (ndjson) instead of a JSON array
        #[arg(long, requires = "export")]
        ndjson: bool
    },

    /// Searches for packages by name or description
    #[command(
        alias = "s",
        long_about = "Searches for a case-insensitive term in the name, \
                      description, and tags of all available packages in the \
                      database. Filter by repo, type, or tags."
    )]
    Search {
        /// The term to search for (e.g. 'editor', 'cli')
        search_term: String,
        /// Filter by registry handle (e.g. 'zoidberg')
        #[arg(long)]
        registry: Option<String>,
        /// Filter by repository (e.g. 'main', 'extra')
        #[arg(long)]
        repo: Option<String>,
        /// Filter by package type (package, app, collection, extension)
        #[arg(long = "type")]
        package_type: Option<String>,
        /// Filter by tags (any match). Multiple via comma or repeated -t
        #[arg(short = 't', long = "tag", value_delimiter = ',', num_args = 1..)]
        tags: Option<Vec<String>>,
        /// Sort results by field (name, repo, type)
        #[arg(long, default_value = "name")]
        sort: String,
        /// Search for files provided by packages instead of package names
        #[arg(short, long)]
        files: bool,
        /// Open results in an interactive TUI
        #[arg(short = 'i', long)]
        interactive: bool
    },

    /// Manage background services for installed packages
    #[command(alias = "svc")]
    Service(cmd::service::ServiceCommand),

    /// Set up shell completions or enter an ephemeral environment with specific
    /// packages
    #[command(
        long_about = "If a shell is provided, it installs completion scripts. If 'hook' is provided, it outputs shell-specific hook scripts for auto-activation. If packages are provided via --package/-p, it enters a temporary subshell with those packages available in PATH.",
        arg_required_else_help = true,
        group(clap::ArgGroup::new("shell_action").required(true).args(["shell", "hook", "packages"]).multiple(true))
    )]
    Shell {
        /// The shell to set up completions for
        #[arg(value_enum)]
        shell: Option<Shell>,
        /// Generate a shell hook for automatic environment activation
        #[arg(long)]
        hook: bool,
        /// The scope to apply the setup to (user or system-wide)
        #[arg(long, value_enum, default_value = "user")]
        scope: SetupScope,
        /// Packages to include in the ephemeral environment
        #[arg(short, long = "package", value_name = "ALL_PACKAGES")]
        packages: Vec<String>,
        /// Command to run in the ephemeral environment instead of an
        /// interactive shell
        #[arg(short, long)]
        run: Option<String>,
        /// Show additional details (resolution, installation progress, etc.)
        #[arg(long, short)]
        verbose: bool
    },

    /// Execute a package binary directly with its dependencies resolved
    #[command(
        alias = "x",
        long_about = "Resolves a package and its dependencies, installs them \
                      if needed, then runs the requested binary directly. By \
                      default runs the first binary the package provides. \
                      Uses bwrap for sandboxed packages."
    )]
    Exec {
        /// The package source identifier.
        #[arg(value_name = "ALL_SOURCES", help = PKG_SOURCE_HELP)]
        source: String,

        /// Specific binary to run (required if package provides multiple
        /// binaries)
        #[arg(long)]
        bin: Option<String>,

        /// Show additional execution details
        #[arg(long, short)]
        verbose: bool,

        /// Arguments to pass to the executed binary
        #[arg(value_name = "ARGS")]
        args: Vec<String>
    },

    /// Clones the git repository of a package
    Clone {
        /// The package identifier (e.g. @repo/name, path, or URL)
        #[arg(value_name = "ALL_PACKAGES", required = true, help = PKG_SOURCE_HELP)]
        package: String,
        /// The location to clone the repository to
        #[arg(value_name = "LOCATION")]
        location: Option<String>
    },

    /// Manage Zoi's local cache
    Cache {
        /// The cache subcommand to execute.
        #[command(subcommand)]
        command: CacheCommands
    },

    /// Inspect recorded transactions
    #[command(alias = "tx")]
    Transaction {
        /// The transaction subcommand to execute.
        #[command(subcommand)]
        command: TransactionCommands
    },

    /// Manage and author Zoi registries
    #[command(alias = "reg")]
    Registry(cmd::registry::RegistryCommand),

    /// Manage declarative user environments (`ZoiOS` only)
    Home(cmd::home::HomeCommand),

    /// Manage the underlying `ZoiOS` system (`ZoiOS` only)
    System(cmd::system::SystemCommand),

    /// Manage package repositories
    #[command(
        aliases = ["repositories"],
        long_about = "Manages the list of package repositories used by Zoi.\n\nCommands:\n- add (alias: a): Add an official repo by name or clone from a git URL.\n- remove|rm: Remove a repo from active list (repo rm <name>).\n- list|ls: Show active repositories by default; use 'list all' to show all available repositories.\n- git: Manage cloned git repositories (git ls, git rm <repo-name>)."
    )]
    Repo(cmd::repo::RepoCommand),

    /// Manage telemetry settings (opt-in analytics)
    #[command(long_about = "Manage opt-in anonymous telemetry used to \
                            understand package popularity. Default is \
                            disabled.")]
    Telemetry {
        /// The telemetry subcommand to execute.
        #[command(subcommand)]
        command: TelemetrySubcommand
    },

    /// Create a zoi.lua project file in the current directory
    Init {
        /// Overwrite an existing zoi.lua
        #[arg(short, long)]
        force: bool
    },

    /// Create an application using a package template
    Create {
        /// The package source identifier.
        #[arg(value_name = "ALL_SOURCES", help = PKG_SOURCE_HELP)]
        source: String,
        /// The application name to substitute into template commands
        app_name: Option<String>
    },

    /// Downgrade a package to a specific version from local cache or store
    #[command(
        alias = "dg",
        long_about = "Interactively choose and install an older version of a \
                      package from the local store or archive cache. This is \
                      useful if a recent update has introduced bugs or \
                      compatibility issues."
    )]
    Downgrade {
        /// The package identifier.
        #[arg(value_name = "INST_PACKAGES", help = PKG_SOURCE_HELP)]
        package: String
    },

    /// Manage Zoi extensions
    #[command(alias = "ext")]
    Extension(ExtensionCommand),

    /// Rollback a package to the previously installed version
    Rollback {
        /// The package identifier.
        #[arg(value_name = "INST_PACKAGES", help = PKG_SOURCE_HELP)]
        package: String
    },

    /// Shows a package's manual
    Man {
        /// The package identifier.
        #[arg(value_name = "ALL_PACKAGES", help = PKG_SOURCE_HELP)]
        package_name: String,
        /// Always look at the upstream manual even if it's downloaded
        #[arg(long)]
        upstream: bool,
        /// Print the manual to the terminal raw
        #[arg(long)]
        raw: bool,
        /// Show a specific manual page (e.g. 'zbsdiff.1' or 'zbsdiff.3').
        /// Defaults to the page matching the package name in section 1.
        #[arg(long)]
        page: Option<String>
    },

    /// Build, create, and manage Zoi packages
    #[command(alias = "pkg")]
    Package(cmd::package::PackageCommand),

    /// Manage PGP keys for package signature verification
    Pgp(cmd::pgp::PgpCommand),

    /// Helper commands for various tasks
    Helper(cmd::helper::HelperCommand),

    /// Checks for common issues and provides actionable suggestions
    Doctor,

    /// Audit installed or all packages for security vulnerabilities
    Audit {
        /// Show all vulnerabilities from the database, not just for installed
        /// packages
        #[arg(short, long)]
        all: bool,
        /// Filter by registry handle
        #[arg(long)]
        registry: Option<String>,
        /// Filter by repository
        #[arg(long)]
        repo: Option<String>
    },

    /// Execute an external subcommand.
    #[command(external_subcommand)]
    External(Vec<String>)
}

/// The extension management command.
#[derive(clap::Parser, Debug)]
pub struct ExtensionCommand {
    /// The extension subcommand to execute.
    #[command(subcommand)]
    pub command: ExtensionCommands
}

/// The available extension subcommands.
#[derive(clap::Subcommand, Debug)]
pub enum ExtensionCommands {
    /// Add an extension
    Add {
        /// The name of the extension to add
        #[arg(required = true)]
        name: String
    },
    /// Remove an extension
    Remove {
        /// The name of the extension to remove
        #[arg(required = true)]
        name: String
    }
}

/// The available sync subcommands.
#[derive(clap::Subcommand, Clone)]
pub enum SyncCommands {
    /// Add a new registry
    Add {
        /// URL of the registry to add
        url: String
    },
    /// Remove a configured registry by its handle
    Remove {
        /// Handle of the registry to remove
        handle: String
    },
    /// List configured registries
    #[command(alias = "ls")]
    List,
    /// Set the default registry URL
    Set {
        /// URL or keyword (default, github, gitlab, codeberg)
        url: String
    }
}

/// The available cache management subcommands.
#[derive(clap::Subcommand)]
pub enum CacheCommands {
    /// Add package archive(s) to the local cache
    Add {
        /// Path to the .zpa archive(s)
        #[arg(required = true)]
        files: Vec<std::path::PathBuf>
    },
    /// Clear the entire Zoi cache
    #[command(alias = "clean")]
    Clear {
        /// Do not actually clear the cache, just show what would be done
        #[arg(long)]
        dry_run: bool
    },
    /// List all archives currently in the cache
    #[command(alias = "ls")]
    List,
    /// Manage cache mirrors used for archive downloads
    Mirror {
        /// The cache mirror subcommand to execute.
        #[command(subcommand)]
        command: CacheMirrorCommands
    }
}

/// The available cache mirror management subcommands.
#[derive(clap::Subcommand)]
pub enum CacheMirrorCommands {
    /// Add a cache mirror base URL
    Add {
        /// Mirror base URL
        url: String
    },
    /// Remove a cache mirror base URL
    Remove {
        /// Mirror base URL
        url: String
    },
    /// List configured cache mirrors
    #[command(alias = "ls")]
    List
}

/// The available transaction management subcommands.
#[derive(clap::Subcommand)]
pub enum TransactionCommands {
    /// List known transaction logs
    #[command(alias = "ls")]
    List,
    /// Show details for a transaction
    Show {
        /// Transaction ID
        id: String
    },
    /// List modified files for a transaction
    Files {
        /// Transaction ID
        id: String
    },
    /// Undo a transaction by reverting all of its recorded operations.
    /// Defaults to the most recent transaction when no ID is given.
    #[command(alias = "rollback")]
    Undo {
        /// Transaction ID (defaults to the last transaction)
        id: Option<String>,

        /// Do not prompt for confirmation
        #[arg(long)]
        yes: bool
    }
}

/// The available actions for telemetry.
#[derive(clap::Subcommand, Clone)]
pub enum TelemetrySubcommand {
    /// Show the current telemetry status.
    Status,
    /// Enable anonymous telemetry.
    Enable,
    /// Disable anonymous telemetry.
    Disable,
    /// Manage local crash reports (`.zoicrash` files in
    /// `$XDG_STATE_HOME/zoi/crash`).
    Crash {
        /// The crash-report action to perform.
        #[command(subcommand)]
        command: CrashSubcommand
    },
    /// Deliver queued analytics events (internal: spawned detached after
    /// commands that enqueue telemetry, never runs on the hot path).
    #[command(hide = true)]
    Flush
}

/// The available crash-report actions.
#[derive(clap::Subcommand, Clone)]
pub enum CrashSubcommand {
    /// List locally stored crash reports.
    #[command(alias = "ls")]
    List,
    /// Print a crash report envelope to stdout.
    Show {
        /// Crash report file name or full path.
        file: PathBuf
    },
    /// Upload a crash report to Sentry (requires telemetry opt-in).
    Send {
        /// Crash report file name or full path.
        file: PathBuf,
        /// Skip the confirmation prompt.
        #[arg(long)]
        yes: bool
    },
    /// Delete all locally stored crash reports.
    Clear {
        /// Skip the confirmation prompt.
        #[arg(long)]
        yes: bool
    }
}

/// Returns the analytics name for a subcommand.
fn command_name(command: &Commands) -> &'static str {
    match command {
        Commands::GenerateCompletions { .. } => "generate-completions",
        Commands::Complete { .. } => "complete",
        Commands::Version => "version",
        Commands::About => "about",
        Commands::Info => "info",
        Commands::Download { .. } => "download",
        Commands::Sync { .. } => "sync",
        Commands::Migrate(_) => "migrate",
        Commands::List { .. } => "list",
        Commands::Show { .. } => "show",
        Commands::Pin { .. } => "pin",
        Commands::Provides { .. } => "provides",
        Commands::Tree { .. } => "tree",
        Commands::Unpin { .. } => "unpin",
        Commands::Mark { .. } => "mark",
        Commands::Update { .. } => "update",
        Commands::Install(_) => "install",
        Commands::Uninstall(_) => "uninstall",
        Commands::Run { .. } => "run",
        Commands::Env { .. } => "env",
        Commands::Dev { .. } => "dev",
        Commands::Upgrade { .. } => "upgrade",
        Commands::Autoremove { .. } => "autoremove",
        Commands::Why { .. } => "why",
        Commands::Owner { .. } => "owner",
        Commands::Files { .. } => "files",
        Commands::Alt(_) => "alt",
        Commands::History { .. } => "history",
        Commands::Search { .. } => "search",
        Commands::Service(_) => "service",
        Commands::Shell { .. } => "shell",
        Commands::Exec { .. } => "exec",
        Commands::Clone { .. } => "clone",
        Commands::Cache { .. } => "cache",
        Commands::Transaction { .. } => "transaction",
        Commands::Repo(_) => "repo",
        Commands::Registry(_) => "registry",
        Commands::Home(_) => "home",
        Commands::System { .. } => "system",
        Commands::Telemetry { .. } => "telemetry",
        Commands::Create { .. } => "create",
        Commands::Init { .. } => "init",
        Commands::Downgrade { .. } => "downgrade",
        Commands::Extension(_) => "extension",
        Commands::Rollback { .. } => "rollback",
        Commands::Man { .. } => "man",
        Commands::Package(_) => "package",
        Commands::Pgp(_) => "pgp",
        Commands::Helper(_) => "helper",
        Commands::Doctor => "doctor",
        Commands::Audit { .. } => "audit",
        Commands::External(_) => "external"
    }
}

/// The main entry point for the Zoi CLI.
///
/// # Errors
///
/// Returns an error if argument parsing fails, plugin loading fails, or if any
/// subcommand fails.
pub fn run() -> anyhow::Result<()> {
    let styles = styling::Styles::styled()
        .header(
            styling::AnsiColor::Yellow.on_default() | styling::Effects::BOLD
        )
        .usage(styling::AnsiColor::Green.on_default() | styling::Effects::BOLD)
        .literal(styling::AnsiColor::Green.on_default())
        .placeholder(styling::AnsiColor::Cyan.on_default());

    let commit: &str = option_env!("ZOI_COMMIT_HASH").unwrap_or("dev");
    let cmd = Cli::command().styles(styles.clone());
    let matches = cmd.clone().get_matches();
    let cli = match Cli::from_arg_matches(&matches) {
        Ok(cli) => cli,
        Err(err) => {
            err.print()?;
            return Err(anyhow::anyhow!("Failed to parse arguments"));
        }
    };

    if let Some(root) = cli.root {
        crate::pkg::sysroot::set_sysroot(root);
    }

    let config = crate::pkg::config::read_config().unwrap_or_default();

    let is_offline = cli.offline || config.offline_mode;
    crate::pkg::offline::set_offline(is_offline);

    // - Always installs the local panic hook so crashes land in
    //   `$XDG_STATE_HOME/zoi/crash/*.zoicrash`.
    // - Initializes Sentry only when opted-in with a DSN.
    // - Prompts to upload pending crashes on interactive TTYs when opted-in,
    //   except for telemetry-management commands: opting out (or inspecting
    //   crashes) must never be gated behind an upload prompt for potentially
    //   sensitive reports.
    let prompt_pending_crashes =
        !matches!(cli.command, Some(Commands::Telemetry { .. }));
    let _telemetry_guards =
        zoi_telemetry::init_telemetry(prompt_pending_crashes);

    let mut all_pkg_dirs = cli.pkg_dirs;
    for dir in config.pkg_dirs {
        let path = std::path::PathBuf::from(dir);
        if !all_pkg_dirs.contains(&path) {
            all_pkg_dirs.push(path);
        }
    }
    crate::pkg::pkgdir::set_pkg_dirs(all_pkg_dirs);

    utils::check_path();

    if let Err(e) = crate::pkg::pgp::ensure_builtin_keys() {
        eprintln!(
            "{}: Failed to ensure builtin PGP keys: {}",
            "Warning".yellow(),
            e
        );
    }

    let plugin_manager = crate::pkg::plugin::PluginManager::new()?;
    if let Err(e) = plugin_manager.load_all(cli.yes) {
        eprintln!("{}: Failed to load plugins: {}", "Warning".yellow(), e);
    }

    if cli.version_flag {
        cmd::version::run(BRANCH, STATUS, NUMBER, commit);
        return Ok(());
    }

    if let Some(command) = cli.command {
        let command_name = command_name(&command);
        // - The detached queue flusher delivers; it must never enqueue (and
        //   re-spawn) itself. The library reentrancy guard
        //   (`ZOI_TELEMETRY_FLUSHING`) backs this up.
        let is_flush_command = matches!(
            command,
            Commands::Telemetry {
                command: TelemetrySubcommand::Flush
            }
        );
        // Exposed to the crash reporter so panic envelopes can tag the
        // in-flight command. Set before dispatch, cleared afterwards.
        // SAFETY: Set at startup before worker threads do telemetry work.
        unsafe {
            std::env::set_var("ZOI_CRASH_COMMAND", command_name);
        }

        let needs_lock = matches!(
            command,
            Commands::Install { .. }
                | Commands::Uninstall { .. }
                | Commands::Update { .. }
                | Commands::Autoremove { .. }
                | Commands::Rollback { .. }
                | Commands::Package(_)
        );

        let _lock_guard = if needs_lock {
            Some(lock::acquire_lock()?)
        } else {
            None
        };

        let result = match command {
            Commands::GenerateCompletions { shell } => {
                let mut cmd = Cli::command();
                let bin_name = cmd.get_name().to_string();
                generate(shell, &mut cmd, bin_name, &mut io::stdout());
                Ok(())
            }
            Commands::Complete {
                shell,
                index,
                words
            } => cmd::complete::run(shell, index, &words),
            Commands::Version => {
                cmd::version::run(BRANCH, STATUS, NUMBER, commit);
                Ok(())
            }
            Commands::About => {
                cmd::about::run(BRANCH, STATUS, NUMBER, commit);
                Ok(())
            }
            Commands::Info => cmd::info::run(BRANCH, STATUS, NUMBER, commit),
            Commands::Sync {
                command,
                verbose,
                fallback,
                no_package_managers,
                force,
                local,
                frozen,
                scope
            } => {
                if let Some(cmd) = command {
                    match cmd {
                        SyncCommands::Add { url } => {
                            cmd::sync::add_registry(&url)
                        }
                        SyncCommands::Remove { handle } => {
                            cmd::sync::remove_registry(&handle)
                        }
                        SyncCommands::List => cmd::sync::list_registries(),
                        SyncCommands::Set { url } => {
                            cmd::sync::set_registry(&url)
                        }
                    }
                } else if local {
                    plugin_manager.trigger_hook("on_pre_sync", None)?;
                    let res =
                        cmd::sync::run_local(verbose, fallback, force, frozen);
                    plugin_manager.trigger_hook_nonfatal("on_post_sync", None);
                    res
                } else {
                    plugin_manager.trigger_hook("on_pre_sync", None)?;
                    let res = cmd::sync::run(
                        verbose,
                        fallback,
                        no_package_managers,
                        force,
                        scope
                    );
                    plugin_manager.trigger_hook_nonfatal("on_post_sync", None);
                    res
                }
            }
            Commands::Migrate(args) => cmd::migrate::run(args),
            Commands::List {
                all,
                outdated,
                registry,
                repo,
                package_type,
                foreign,
                names,
                completion
            } => cmd::list::run(
                all,
                outdated,
                registry.as_deref(),
                repo.as_deref(),
                package_type.as_deref(),
                foreign,
                names,
                completion
            ),
            Commands::Show {
                package_name,
                raw,
                purl
            } => cmd::show::run(&package_name, raw, purl),
            Commands::Pin { package, version } => {
                cmd::pin::run(&package, &version, cli.yes)
            }
            Commands::Provides { term } => cmd::provides::run(&term),
            Commands::Tree { packages } => cmd::tree::run(&packages),
            Commands::Unpin { package } => cmd::unpin::run(&package, cli.yes),
            Commands::Mark {
                packages,
                as_dependency,
                as_explicit
            } => cmd::mark::run(&packages, as_dependency, as_explicit),
            Commands::Update {
                package_names,
                all,
                dry_run,
                explain,
                plan_json,
                verbose,
                interactive
            } => cmd::update::run(
                all,
                &package_names,
                cli.yes,
                dry_run,
                explain,
                plan_json,
                verbose,
                interactive
            )
            .map_err(|e| cmd::ux::with_failure_hint("update", e)),
            Commands::Install(args) => args
                .run(cli.yes)
                .map_err(|e| cmd::ux::with_failure_hint("install", e)),
            Commands::Uninstall(args) => args
                .run(cli.yes)
                .map_err(|e| cmd::ux::with_failure_hint("uninstall", e)),
            Commands::Run { cmd_alias, args } => {
                cmd::run::run(cmd_alias.as_deref(), &args)
            }
            Commands::Env {
                env_alias,
                export_shell
            } => cmd::env::run(env_alias.as_deref(), export_shell),
            Commands::Dev { run, repo } => cmd::dev::run(run, repo),
            Commands::Upgrade { force, tag, branch } => {
                match cmd::upgrade::run(
                    BRANCH, STATUS, NUMBER, force, tag, branch
                ) {
                    Ok(()) => {
                        println!(
                            "\n{}",
                            "Zoi upgraded successfully! Please restart your \
                             shell for changes to take effect."
                                .green()
                        );
                        println!(
                            "\n{}: https://github.com/zillowe/zoi/blob/main/CHANGELOG.md",
                            "Changelog".cyan().bold()
                        );
                        println!(
                            "\n{}: To update shell completions, run 'zoi \
                             shell <your-shell>'.",
                            "Hint".cyan().bold()
                        );
                    }
                    Err(e) if e.to_string() == "already_on_latest" => {}
                    Err(e) if e.to_string() == "managed_by_package_manager" => {
                    }
                    Err(e) => return Err(e)
                }
                Ok(())
            }
            Commands::Autoremove { dry_run } => {
                cmd::autoremove::run(cli.yes, dry_run)
            }
            Commands::Why { package_name } => cmd::why::run(&package_name),
            Commands::Owner { path } => cmd::owner::run(&path),
            Commands::Alt(ref args) => cmd::alt::run(args),
            Commands::Files { package } => cmd::files::run(&package),
            Commands::History {
                verify,
                export,
                ndjson
            } => cmd::history::run(verify, export, ndjson),
            Commands::Search {
                search_term,
                registry,
                repo,
                package_type,
                tags,
                sort,
                files,
                interactive
            } => cmd::search::run(
                &search_term,
                registry.as_deref(),
                repo.as_deref(),
                package_type.as_deref(),
                tags,
                &sort,
                files,
                interactive
            ),
            Commands::Service(args) => cmd::service::run(args),
            Commands::Shell {
                shell,
                hook,
                scope,
                packages,
                run,
                verbose
            } => {
                let target_shell = shell
                    .or_else(crate::pkg::utils::get_current_shell)
                    .unwrap_or(Shell::Bash);
                if hook {
                    cmd::shell::print_hook(target_shell)
                } else if !packages.is_empty() {
                    cmd::shell::enter_ephemeral_shell(
                        &packages,
                        run,
                        verbose,
                        Some(&plugin_manager)
                    )
                } else {
                    cmd::shell::run(target_shell, scope)
                }
            }
            Commands::Exec {
                source,
                bin,
                verbose,
                args
            } => cmd::exec::run(&source, bin, &args, verbose),
            Commands::Download {
                package,
                archive: _,
                source,
                output_dir
            } => {
                let download_type = if source {
                    cmd::download::DownloadType::Source
                } else {
                    cmd::download::DownloadType::Archive
                };
                cmd::download::run(&package, download_type, output_dir)
            }
            Commands::Clone { package, location } => {
                cmd::clone::run(&package, location, cli.yes)
            }
            Commands::Cache { command } => match command {
                CacheCommands::Add { files } => cmd::cache::add(&files),
                CacheCommands::Clear { dry_run } => cmd::cache::clear(dry_run),
                CacheCommands::List => cmd::cache::list(),
                CacheCommands::Mirror { command } => match command {
                    CacheMirrorCommands::Add { url } => {
                        cmd::cache::add_mirror(&url)
                    }
                    CacheMirrorCommands::Remove { url } => {
                        cmd::cache::remove_mirror(&url)
                    }
                    CacheMirrorCommands::List => cmd::cache::list_mirrors()
                }
            },
            Commands::Transaction { command } => match command {
                TransactionCommands::List => cmd::transaction::list(),
                TransactionCommands::Show { id } => cmd::transaction::show(&id),
                TransactionCommands::Files { id } => {
                    cmd::transaction::files(&id)
                }
                TransactionCommands::Undo { id, yes } => {
                    cmd::transaction::undo(id.as_deref(), yes, cli.yes)
                }
            },
            Commands::Repo(args) => cmd::repo::run(args),
            Commands::Registry(args) => cmd::registry::run(args),
            Commands::Home(args) => cmd::home::run(args),
            Commands::System(args) => cmd::system::run(args, cli.yes),
            Commands::Telemetry { command } => {
                use cmd::telemetry::{CrashCommand, TelemetryCommand, run};
                let cmd = match command {
                    TelemetrySubcommand::Status => TelemetryCommand::Status,
                    TelemetrySubcommand::Enable => TelemetryCommand::Enable,
                    TelemetrySubcommand::Disable => TelemetryCommand::Disable,
                    TelemetrySubcommand::Flush => TelemetryCommand::Flush,
                    TelemetrySubcommand::Crash { command } => {
                        TelemetryCommand::Crash(match command {
                            CrashSubcommand::List => CrashCommand::List,
                            CrashSubcommand::Show { file } => {
                                CrashCommand::Show { file }
                            }
                            CrashSubcommand::Send { file, yes } => {
                                CrashCommand::Send {
                                    file,
                                    yes: yes || cli.yes
                                }
                            }
                            CrashSubcommand::Clear { yes } => {
                                CrashCommand::Clear {
                                    yes: yes || cli.yes
                                }
                            }
                        })
                    }
                };
                run(cmd)
            }
            Commands::Create { source, app_name } => cmd::create::run(
                cmd::create::CreateCommand { source, app_name },
                cli.yes,
                Some(&plugin_manager)
            ),
            Commands::Init { force } => cmd::init::run(cli.yes, force),
            Commands::Downgrade { package } => {
                cmd::downgrade::run(&package, cli.yes, Some(&plugin_manager))
            }
            Commands::Extension(args) => {
                cmd::extension::run(args, cli.yes, Some(&plugin_manager))
            }
            Commands::Rollback { package } => {
                cmd::rollback::run(&package, cli.yes, Some(&plugin_manager))
            }
            Commands::Man {
                package_name,
                upstream,
                raw,
                page
            } => cmd::man::run(&package_name, upstream, raw, page.as_deref()),
            Commands::Package(args) => cmd::package::run(args),
            Commands::Pgp(args) => cmd::pgp::run(args),
            Commands::Helper(args) => cmd::helper::run(args),
            Commands::Doctor => cmd::doctor::run(),
            Commands::Audit {
                all,
                registry,
                repo
            } => cmd::audit::run(all, registry, repo.as_deref()),
            Commands::External(args) => {
                let (cmd_name, cmd_args) =
                    if let Some((first, rest)) = args.split_first() {
                        (first, rest.to_vec())
                    } else {
                        return Err(anyhow::anyhow!("No command specified"));
                    };

                match plugin_manager.run_command(cmd_name, cmd_args) {
                    Ok(true) => Ok(()),
                    Ok(false) => {
                        let mut shadow_cmd = Cli::command().styles(styles);
                        shadow_cmd =
                            shadow_cmd.allow_external_subcommands(false);

                        let err = shadow_cmd
                            .clone()
                            .try_get_matches_from(std::env::args())
                            .err()
                            .unwrap_or_else(|| {
                                shadow_cmd.error(
                                    clap::error::ErrorKind::InvalidSubcommand,
                                    format!(
                                        "unrecognized subcommand '{cmd_name}'"
                                    )
                                )
                            });

                        let plugin_cmds = plugin_manager.list_commands()?;
                        if !plugin_cmds.is_empty() {
                            eprintln!(
                                "{}:",
                                "Available Plugin Commands".cyan().bold()
                            );
                            for (pcmd, pdesc) in plugin_cmds {
                                if pdesc.is_empty() {
                                    eprintln!("  {pcmd}");
                                } else {
                                    eprintln!(
                                        "  {:<12} {}",
                                        pcmd,
                                        pdesc.dimmed()
                                    );
                                }
                            }
                            eprintln!();
                        }

                        err.exit();
                    }
                    Err(e) => Err(e)
                }
            }
        };

        // SAFETY: Paired with the `set_var` above; no telemetry worker reads
        // this after dispatch completes.
        unsafe {
            std::env::remove_var("ZOI_CRASH_COMMAND");
        }

        match &result {
            Ok(()) => {
                // Daily active-user ping (at most one per 24h, no command
                // identity attached). Queued to disk with a detached
                // flusher, so this never blocks on the network. Failures
                // are deliberately excluded here; they go to Sentry below.
                // Telemetry failures must never break the CLI, so the
                // outcome is ignored.
                if !is_flush_command {
                    let _ = zoi_telemetry::posthog_capture_dau_ping();
                }
            }
            Err(e) => {
                zoi_telemetry::sentry_capture_error(command_name, e.as_ref());
            }
        }

        if let Err(e) = result {
            eprintln!("Error: {e}");
            // Flush queued Sentry events (e.g. the failure report above)
            // before exiting: `process::exit` skips destructors, so without
            // this the telemetry guard would never drain the transport queue.
            // Bounded to ~2s inside `shutdown_sentry`, then the process exits
            // regardless of delivery.
            zoi_telemetry::shutdown_sentry();
            std::process::exit(1);
        }
    }
    Ok(())
}