bootc_lib/

cli.rs

//! # Bootable container image CLI
//!
//! Command line tool to manage bootable ostree-based containers.

use std::ffi::{CString, OsStr, OsString};
use std::fs::File;
use std::io::{BufWriter, Seek, SeekFrom};
use std::os::fd::AsFd;
use std::os::unix::process::CommandExt;
use std::process::Command;

use anyhow::{Context, Result, anyhow, ensure};
use camino::{Utf8Path, Utf8PathBuf};
use cap_std_ext::cap_std;
use cap_std_ext::cap_std::fs::Dir;
use clap::CommandFactory;
use clap::Parser;
use clap::ValueEnum;
use composefs::dumpfile;
use composefs::erofs::format::FormatVersion;
use composefs::fsverity;
use composefs::fsverity::FsVerityHashValue;
use composefs_ctl::composefs;
use composefs_ctl::composefs_boot;
use composefs_ctl::composefs_oci;

use composefs_boot::BootOps as _;
use etc_merge::{compute_diff, print_diff};
use fn_error_context::context;
use indoc::indoc;
use ocidir::cap_std::ambient_authority;
use ostree::gio;
use ostree_container::store::PrepareResult;
use ostree_ext::container as ostree_container;

use ostree_ext::keyfileext::KeyFileExt;
use ostree_ext::ostree;
use ostree_ext::sysroot::SysrootLock;
use schemars::schema_for;
use serde::{Deserialize, Serialize};

use crate::bootc_composefs::boot::BootType;
use crate::bootc_composefs::delete::delete_composefs_deployment;
use crate::bootc_composefs::gc::{GCOpts, composefs_gc};
use crate::bootc_composefs::soft_reboot::{prepare_soft_reboot_composefs, reset_soft_reboot};
use crate::bootc_composefs::state::get_usr_overlay_status;
use crate::bootc_composefs::status::get_composefs_status;
use crate::bootc_composefs::uki_addons_cli::handle_addon_cli_cmd;
use crate::bootc_composefs::{
    aboot,
    digest::{compute_composefs_digest, new_temp_composefs_repo},
    finalize::{composefs_backend_finalize, get_etc_diff},
    rollback::composefs_rollback,
    service::start_finalize_stated_svc,
    state::composefs_usr_overlay,
    switch::switch_composefs,
    update::upgrade_composefs,
};
use crate::deploy::{MergeState, RequiredHostSpec};
use crate::install::UkiAddonOpts;
use crate::podstorage::set_additional_image_store;
use crate::progress_jsonl::{ProgressWriter, RawProgressFd};
use crate::spec::FilesystemOverlayAccessMode;
use crate::spec::Host;
use crate::spec::ImageReference;
use crate::status::get_host;
use crate::store::{BootedOstree, Storage};
use crate::store::{BootedStorage, BootedStorageKind};
use crate::utils::sigpolicy_from_opt;
use crate::{bootc_composefs, lints};

/// Shared progress options
#[derive(Clone, Debug, Parser, PartialEq, Eq)]
pub(crate) struct ProgressOptions {
    /// File descriptor number which must refer to an open pipe.
    ///
    /// Progress is written as JSON lines to this file descriptor.
    #[clap(long, hide = true)]
    pub(crate) progress_fd: Option<RawProgressFd>,
}

impl TryFrom<ProgressOptions> for ProgressWriter {
    type Error = anyhow::Error;

    fn try_from(value: ProgressOptions) -> Result<Self> {
        let r = value
            .progress_fd
            .map(TryInto::try_into)
            .transpose()?
            .unwrap_or_default();
        Ok(r)
    }
}

#[derive(Debug, Parser, PartialEq, Eq)]
pub(crate) struct DownloadOnlyOpts {
    /// Download and stage the update without applying it.
    ///
    /// Download the image and ensure it's retained on disk for the lifetime of this system boot,
    /// but it will not be applied on reboot. If the system is rebooted without applying the update,
    /// the image will be eligible for garbage collection again.
    #[clap(long, conflicts_with = "apply")]
    pub(crate) download_only: bool,

    /// Apply a staged deployment that was previously downloaded with --download-only.
    ///
    /// This unlocks the staged deployment without fetching updates from the container image source.
    /// The deployment will be applied on the next shutdown or reboot. Use with --apply to
    /// reboot immediately.
    #[clap(long, conflicts_with_all = ["download_only", "scoped", "global"])]
    pub(crate) from_downloaded: bool,
}

/// Perform an upgrade operation
#[derive(Debug, Parser, PartialEq, Eq)]
pub(crate) struct UpgradeOpts {
    /// Don't display progress
    #[clap(long)]
    pub(crate) quiet: bool,

    /// Check if an update is available without applying it.
    ///
    /// This only downloads updated metadata, not the full image layers.
    #[clap(long, conflicts_with_all = ["apply", "download_only", "from_downloaded", "scoped", "global"])]
    pub(crate) check: bool,

    /// Restart or reboot into the new target image.
    ///
    /// Use --soft-reboot to request a userspace-only restart when supported.
    #[clap(long, conflicts_with = "check")]
    pub(crate) apply: bool,

    /// Configure soft reboot behavior.
    ///
    /// 'required' fails if soft reboot is unavailable; 'auto' uses it when possible.
    /// See bootc-upgrades(7) for backend-specific fallback behavior.
    #[clap(long = "soft-reboot", conflicts_with = "check")]
    pub(crate) soft_reboot: Option<SoftRebootMode>,

    #[clap(flatten)]
    pub(crate) download_opts: DownloadOnlyOpts,

    /// Upgrade to a different tag of the currently booted image.
    ///
    /// This derives the target image by replacing the tag portion of the current
    /// booted image reference.
    #[clap(long)]
    pub(crate) tag: Option<String>,

    /// Upgrade from a local oci-delta artifact instead of the network.
    ///
    /// The delta must have been created against an image that is already
    /// present on this system.
    #[clap(long, value_name = "PATH", conflicts_with_all = ["check", "from_downloaded", "tag"])]
    pub(crate) from_delta: Option<Utf8PathBuf>,

    #[clap(flatten)]
    pub(crate) progress: ProgressOptions,

    // This is kinda unfortunate that we can't gate this only for composefs systems
    #[clap(flatten)]
    pub(crate) uki_addon_opts: UkiAddonOpts,
}

/// Perform an switch operation
#[derive(Debug, Parser, PartialEq, Eq)]
pub(crate) struct SwitchOpts {
    /// Don't display progress
    #[clap(long)]
    pub(crate) quiet: bool,

    /// Restart or reboot into the new target image.
    ///
    /// Use --soft-reboot to request a userspace-only restart when supported.
    #[clap(long)]
    pub(crate) apply: bool,

    /// Configure soft reboot behavior.
    ///
    /// 'required' fails if soft reboot is unavailable; 'auto' uses it when possible.
    /// See bootc-upgrades(7) for backend-specific fallback behavior.
    #[clap(long = "soft-reboot")]
    pub(crate) soft_reboot: Option<SoftRebootMode>,

    /// The transport; e.g. registry, oci, oci-archive, docker-daemon, containers-storage.  Defaults to `registry`.
    #[clap(long, default_value = "registry")]
    pub(crate) transport: String,

    #[clap(flatten)]
    pub(crate) download_opts: DownloadOnlyOpts,

    /// This argument is deprecated and does nothing.
    #[clap(long, hide = true)]
    pub(crate) no_signature_verification: bool,

    /// This is the inverse of the previous `--target-no-signature-verification` (which is now
    /// a no-op).
    ///
    /// Enabling this option enforces that `containers-policy.json` (see `man
    /// containers-policy.json` for the full search path) includes a default
    /// policy which requires signatures.
    #[clap(long)]
    pub(crate) enforce_container_sigpolicy: bool,

    /// Don't create a new deployment, but directly mutate the booted state.
    /// This is hidden because it's not something we generally expect to be done,
    /// but this can be used in e.g. Anaconda %post to fixup
    #[clap(long, hide = true)]
    pub(crate) mutate_in_place: bool,

    /// Retain reference to currently booted image
    #[clap(long)]
    pub(crate) retain: bool,

    /// Use unified storage path to pull images (experimental)
    ///
    /// When enabled, this uses bootc's container storage (/usr/lib/bootc/storage) to pull
    /// the image first, then imports it from there. This is the same approach used for
    /// logically bound images.
    #[clap(long = "experimental-unified-storage", hide = true)]
    pub(crate) unified_storage_exp: bool,

    /// Switch using a local oci-delta artifact instead of the network.
    ///
    /// The delta must have been created against an image that is already
    /// present on this system.
    #[clap(long, value_name = "PATH", conflicts_with_all = [
        "from_downloaded",
        "transport",
        "mutate_in_place",
        "unified_storage_exp",
        "enforce_container_sigpolicy",
    ])]
    pub(crate) from_delta: Option<Utf8PathBuf>,

    /// Target image to use for the next boot.
    /// Required unless `--from-downloaded` is present.
    #[clap(
        required_unless_present = "from_downloaded",
        conflicts_with = "from_downloaded"
    )]
    pub(crate) target: Option<String>,

    #[clap(flatten)]
    pub(crate) progress: ProgressOptions,

    // This is kinda unfortunate that we can't gate this only for composefs systems
    #[clap(flatten)]
    pub(crate) uki_addon_opts: UkiAddonOpts,
}

/// Finalize a staged composefs deployment.
///
/// This is invoked at shutdown by `bootc-finalize-staged.service`.
#[derive(Debug, Parser, PartialEq, Eq)]
pub(crate) struct ComposefsFinalizeStagedOpts {
    /// Hold /boot open until terminated, instead of finalizing.
    ///
    /// This is used by `bootc-finalize-staged-hold.service` to keep an
    /// automounted /boot from expiring while a deployment is staged.
    #[clap(long)]
    pub(crate) hold: bool,
}

/// Options controlling rollback
#[derive(Debug, Parser, PartialEq, Eq)]
pub(crate) struct RollbackOpts {
    /// Restart or reboot into the rollback image.
    ///
    /// Currently, this option always reboots.  In the future this command
    /// will detect the case where no kernel changes are queued, and perform
    /// a userspace-only restart.
    #[clap(long)]
    pub(crate) apply: bool,

    /// Configure soft reboot behavior.
    ///
    /// 'required' fails if soft reboot unavailable, 'auto' falls back to regular reboot.
    #[clap(long = "soft-reboot")]
    pub(crate) soft_reboot: Option<SoftRebootMode>,
}

/// Perform an edit operation
#[derive(Debug, Parser, PartialEq, Eq)]
pub(crate) struct EditOpts {
    /// Use filename to edit system specification
    #[clap(long, short = 'f')]
    pub(crate) filename: Option<String>,

    /// Don't display progress
    #[clap(long)]
    pub(crate) quiet: bool,
}

#[derive(Debug, Clone, ValueEnum, PartialEq, Eq)]
#[clap(rename_all = "lowercase")]
pub(crate) enum OutputFormat {
    /// Output in Human Readable format.
    HumanReadable,
    /// Output in YAML format.
    Yaml,
    /// Output in JSON format.
    Json,
}

#[derive(Debug, Clone, Copy, ValueEnum, PartialEq, Eq)]
#[clap(rename_all = "lowercase")]
pub(crate) enum SoftRebootMode {
    /// Require a soft reboot; fail if not possible
    Required,
    /// Automatically use soft reboot if possible, otherwise use regular reboot
    Auto,
}

/// Perform an status operation
#[derive(Debug, Parser, PartialEq, Eq)]
pub(crate) struct StatusOpts {
    /// Output in JSON format.
    ///
    /// Superseded by the `format` option.
    #[clap(long, hide = true)]
    pub(crate) json: bool,

    /// The output format.
    #[clap(long)]
    pub(crate) format: Option<OutputFormat>,

    /// The desired format version. There is currently one supported
    /// version, which is exposed as both `0` and `1`. Pass this
    /// option to explicitly request it; it is possible that another future
    /// version 2 or newer will be supported in the future.
    #[clap(long)]
    pub(crate) format_version: Option<u32>,

    /// Only display status for the booted deployment.
    #[clap(long)]
    pub(crate) booted: bool,

    /// Include additional fields in human readable format.
    #[clap(long, short = 'v')]
    pub(crate) verbose: bool,
}

/// Add a transient overlayfs on /usr
#[derive(Debug, Parser, PartialEq, Eq)]
pub(crate) struct UsrOverlayOpts {
    /// Mount the overlayfs as read-only. A read-only overlayfs is useful since it may be remounted
    /// as read/write in a private mount namespace and written to while the mount point remains
    /// read-only to the rest of the system.
    #[clap(long)]
    pub(crate) read_only: bool,
}

#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum InstallOpts {
    /// Mount an installed deployment into a caller-owned directory.
    Mount(crate::mount::MountOpts),
    /// Install to the target block device.
    ///
    /// This command must be invoked inside of the container, which will be
    /// installed. The container must be run in `--privileged` mode, and hence
    /// will be able to see all block devices on the system.
    ///
    /// The default storage layout uses the root filesystem type configured
    /// in the container image, alongside any required system partitions such as
    /// the EFI system partition. Use `install to-filesystem` for anything more
    /// complex such as RAID, LVM, LUKS etc.
    #[cfg(feature = "install-to-disk")]
    ToDisk(crate::install::InstallToDiskOpts),
    /// Install to an externally created filesystem structure.
    ///
    /// In this variant of installation, the root filesystem alongside any necessary
    /// platform partitions (such as the EFI system partition) are prepared and mounted by an
    /// external tool or script. The root filesystem is currently expected to be empty
    /// by default.
    ToFilesystem(crate::install::InstallToFilesystemOpts),
    /// Install to the host root filesystem.
    ///
    /// This is a variant of `install to-filesystem` that is designed to install "alongside"
    /// the running host root filesystem. Currently, the host root filesystem's `/boot` partition
    /// will be wiped, but the content of the existing root will otherwise be retained, and will
    /// need to be cleaned up if desired when rebooted into the new root.
    ToExistingRoot(crate::install::InstallToExistingRootOpts),
    /// Nondestructively create a fresh installation state inside an existing bootc system.
    ///
    /// This is a nondestructive variant of `install to-existing-root` that works only inside
    /// an existing bootc system.
    #[clap(hide = true)]
    Reset(crate::install::InstallResetOpts),
    /// Execute this as the penultimate step of an installation using `install to-filesystem`.
    ///
    Finalize {
        /// Path to the mounted root filesystem.
        root_path: Utf8PathBuf,
    },
    /// Intended for use in environments that are performing an ostree-based installation, not bootc.
    ///
    /// In this scenario the installation may be missing bootc specific features such as
    /// kernel arguments, logically bound images and more. This command can be used to attempt
    /// to reconcile. At the current time, the only tested environment is Anaconda using `ostreecontainer`
    /// and it is recommended to avoid usage outside of that environment. Instead, ensure your
    /// code is using `bootc install to-filesystem` from the start.
    EnsureCompletion {},
    /// Output JSON to stdout that contains the merged installation configuration
    /// as it may be relevant to calling processes using `install to-filesystem`
    /// that in particular want to discover the desired root filesystem type from the container image.
    ///
    /// At the current time, the only output key is `root-fs-type` which is a string-valued
    /// filesystem name suitable for passing to `mkfs.$type`.
    PrintConfiguration(crate::install::InstallPrintConfigurationOpts),
}

/// Subcommands which can be executed as part of a container build.
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum ContainerOpts {
    /// Output information about the container image.
    ///
    /// By default, a human-readable summary is output. Use --json or --format
    /// to change the output format.
    Inspect {
        /// Operate on the provided rootfs.
        #[clap(long, default_value = "/")]
        rootfs: Utf8PathBuf,

        /// Output in JSON format.
        #[clap(long)]
        json: bool,

        /// The output format.
        #[clap(long, conflicts_with = "json")]
        format: Option<OutputFormat>,
    },
    /// Perform relatively inexpensive static analysis checks as part of a container
    /// build.
    ///
    /// This is intended to be invoked via e.g. `RUN bootc container lint` as part
    /// of a build process; it will error if any problems are detected.
    Lint {
        /// Operate on the provided rootfs.
        #[clap(long, default_value = "/")]
        rootfs: Utf8PathBuf,

        /// Make warnings fatal.
        #[clap(long)]
        fatal_warnings: bool,

        /// Instead of executing the lints, just print all available lints.
        /// At the current time, this will output in YAML format because it's
        /// reasonably human friendly. However, there is no commitment to
        /// maintaining this exact format; do not parse it via code or scripts.
        #[clap(long)]
        list: bool,

        /// Skip checking the targeted lints, by name. Use `--list` to discover the set
        /// of available lints.
        ///
        /// Example: --skip nonempty-boot --skip baseimage-root
        #[clap(long)]
        skip: Vec<String>,

        /// Don't truncate the output. By default, only a limited number of entries are
        /// shown for each lint, followed by a count of remaining entries.
        #[clap(long)]
        no_truncate: bool,
    },
    /// Output the bootable composefs digest for a directory.
    ///
    /// This is the digest that `bootc container ukify` embeds in the kernel
    /// command line of a UKI. It is useful for scripting and debugging outside
    /// of that flow.
    ComputeComposefsDigest {
        /// Path to the filesystem root
        #[clap(default_value = "/target")]
        path: Utf8PathBuf,

        /// Additionally generate a dumpfile for the preferred digest, written to the target path
        #[clap(long)]
        write_dumpfile_to: Option<Utf8PathBuf>,

        /// EROFS format version to use when computing the composefs digest.
        ///
        /// V1 produces a `composefs.digest=v1-sha512-12:<hex>` karg (C-tool compatible).
        /// V2 produces the legacy `composefs=<hex>` karg (composefs-rs native).
        #[clap(long, default_value = "v1")]
        erofs_version: ErofsVersionArg,
    },
    /// Output the bootable composefs digest from container storage.
    #[clap(hide = true)]
    ComputeComposefsDigestFromStorage {
        /// Additionally generate a dumpfile for the preferred digest, written to the target path
        #[clap(long)]
        write_dumpfile_to: Option<Utf8PathBuf>,

        /// EROFS format version to use when computing the composefs digest.
        ///
        /// Must match the format used by `compute-composefs-digest` (and by
        /// `container ukify`) for the two views to be comparable.
        #[clap(long, default_value = "v1")]
        erofs_version: ErofsVersionArg,

        /// Identifier for image; if not provided, the running image will be used.
        image: Option<String>,
    },
    /// Split kernel and rootfs from a container image
    ///
    /// This command extracts the kernel (vmlinuz and initramfs.img) from the
    /// container rootfs and moves them to a separate output directory, organized
    /// by kernel version. Files that belong to the kernel binary are moved
    /// along with it, currently the FIPS HMAC file (.vmlinuz.hmac) that Fedora
    /// and RHEL derivatives ship.
    ///
    /// Example:
    ///   bootc container split-kernel-and-rootfs --rootfs /target-rootfs --output /out
    SplitKernelAndRootfs {
        /// Operate on the provided rootfs
        #[clap(long, default_value = "/")]
        rootfs: Utf8PathBuf,

        /// Output directory for the extracted kernel files
        #[clap(long)]
        output: Utf8PathBuf,
    },
    /// Build a Unified Kernel Image (UKI) using ukify.
    ///
    /// This command computes the necessary arguments from the container image
    /// (kernel, initrd, cmdline, os-release) and invokes ukify with them.
    /// Any additional arguments after `--` are passed through to ukify unchanged.
    ///
    /// Example:
    ///   bootc container ukify --rootfs /target -- --output /output/uki.efi
    Ukify {
        /// Operate on the provided rootfs.
        #[clap(long, default_value = "/")]
        rootfs: Utf8PathBuf,

        /// Additional kernel arguments to append to the cmdline.
        /// Can be specified multiple times.
        /// This is a temporary workaround and will be removed.
        #[clap(long = "karg", hide = true)]
        kargs: Vec<String>,

        /// Make fs-verity validation optional in case the filesystem doesn't support it
        #[clap(long)]
        allow_missing_verity: bool,

        /// EROFS format version to use when computing the composefs digest.
        ///
        /// By default, produce V1 then V2 kargs for compatibility. V1 produces a
        /// `composefs.digest=v1-sha512-12:<hex>` karg (C-tool compatible), while V2
        /// produces the legacy `composefs=<hex>` karg (composefs-rs native).
        /// V1-only omits the V2 fallback to shorten the kernel command line.
        /// Explicit V2 produces only the V2 karg as a compatibility escape hatch.
        #[clap(long)]
        erofs_version: Option<BootArtifactErofsVersionArg>,

        /// Write a dumpfile to this path
        #[clap(long)]
        write_dumpfile_to: Option<Utf8PathBuf>,

        /// The directory containing the kernel and initramfs.img
        /// Must be of the format /parent/$kernel_version
        ///
        /// Ex. /boot/6.18.7-100.fc42.x86_64
        #[clap(long)]
        kernel_dir: Option<Utf8PathBuf>,

        /// Additional arguments to pass to ukify (after `--`).
        #[clap(last = true)]
        args: Vec<OsString>,
    },
    /// Build an Android boot or ukiboot image using aboot-update.
    Aboot {
        /// Operate on the provided rootfs.
        #[clap(long, default_value = "/")]
        rootfs: Utf8PathBuf,

        /// Make fs-verity validation optional in case the filesystem doesn't support it
        #[clap(long)]
        allow_missing_verity: bool,

        /// EROFS format version to use when computing the composefs digest.
        ///
        /// By default, produce V1 then V2 kargs for compatibility.
        /// V1-only omits the V2 fallback to shorten the kernel command line.
        /// Explicit V2 produces only the legacy V2 karg.
        #[clap(long)]
        erofs_version: Option<BootArtifactErofsVersionArg>,

        /// Write a dumpfile to this path
        #[clap(long)]
        write_dumpfile_to: Option<Utf8PathBuf>,

        /// The directory containing vmlinuz and initramfs.img.
        /// Must be of the format /parent/$kernel_version.
        #[clap(long)]
        kernel_dir: Option<Utf8PathBuf>,

        /// Output directory. Defaults to $rootfs/boot.
        #[clap(long)]
        out: Option<Utf8PathBuf>,
    },
    /// Export container filesystem as a tar archive.
    ///
    /// This command exports the container filesystem in a bootable format with proper
    /// SELinux labeling. The output is written to stdout by default or to a specified file.
    ///
    /// Example:
    ///   bootc container export /target > output.tar
    #[clap(hide = true)]
    Export {
        /// Format for export output
        #[clap(long, default_value = "tar")]
        format: ExportFormat,

        /// Output file (defaults to stdout)
        #[clap(long, short = 'o')]
        output: Option<Utf8PathBuf>,

        /// Copy kernel and initramfs from /usr/lib/modules to /boot for legacy compatibility.
        /// This is useful for installers that expect the kernel in /boot.
        #[clap(long)]
        kernel_in_boot: bool,

        /// SELinux labeling mode for exported entries.
        #[clap(long, default_value = "enabled")]
        selinux: ExportSelinuxMode,

        /// Path to the container filesystem root
        target: Utf8PathBuf,
    },
}

/// EROFS format version for computing a composefs digest.
#[derive(Debug, Clone, Copy, ValueEnum, PartialEq, Eq)]
pub(crate) enum ErofsVersionArg {
    /// V1 EROFS (C-tool compatible, `composefs.digest=v1-sha512-12:<hex>` karg).  Default.
    V1,
    /// V2 EROFS (composefs-rs native, `composefs=` karg).
    V2,
}

impl From<ErofsVersionArg> for FormatVersion {
    fn from(v: ErofsVersionArg) -> Self {
        match v {
            ErofsVersionArg::V1 => FormatVersion::V1,
            ErofsVersionArg::V2 => FormatVersion::V2,
        }
    }
}

/// EROFS format and compatibility arguments to embed in a boot artifact.
#[derive(Debug, Clone, Copy, ValueEnum, PartialEq, Eq)]
pub(crate) enum BootArtifactErofsVersionArg {
    /// V1 EROFS with a V2 compatibility fallback. Default.
    V1,
    /// V1 EROFS without a backwards compatibility V2 fallback.
    V1Only,
    /// V2 EROFS with only the legacy `composefs=` argument.
    V2,
}

#[derive(Debug, Clone, ValueEnum, PartialEq, Eq)]
pub(crate) enum ExportSelinuxMode {
    /// Compute and apply SELinux labels; error if any file has no policy match.
    Enabled,
    /// Compute and apply SELinux labels; warn (don't error) for files with no policy match.
    WarnOnMissing,
    /// Do not apply SELinux labels.
    Disabled,
}

#[derive(Debug, Clone, ValueEnum, PartialEq, Eq)]
pub(crate) enum ExportFormat {
    /// Export as tar archive
    Tar,
}

/// Subcommands which operate on images.
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum ImageCmdOpts {
    /// Wrapper for `podman image list` in bootc storage.
    List {
        #[clap(allow_hyphen_values = true)]
        args: Vec<OsString>,
    },
    /// Wrapper for `podman image build` in bootc storage.
    Build {
        #[clap(allow_hyphen_values = true)]
        args: Vec<OsString>,
    },
    /// Pull image(s) into bootc storage.
    Pull {
        /// Image references to pull (e.g. quay.io/myorg/myimage:latest)
        #[clap(required = true)]
        images: Vec<String>,
    },
    /// Wrapper for `podman image push` in bootc storage.
    Push {
        #[clap(allow_hyphen_values = true)]
        args: Vec<OsString>,
    },
}

#[derive(ValueEnum, Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "kebab-case")]
pub(crate) enum ImageListType {
    /// List all images
    #[default]
    All,
    /// List only logically bound images
    Logical,
    /// List only host images
    Host,
}

impl std::fmt::Display for ImageListType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.to_possible_value().unwrap().get_name().fmt(f)
    }
}

#[derive(ValueEnum, Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "kebab-case")]
pub(crate) enum ImageListFormat {
    /// Human readable table format
    #[default]
    Table,
    /// JSON format
    Json,
}
impl std::fmt::Display for ImageListFormat {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.to_possible_value().unwrap().get_name().fmt(f)
    }
}

/// Subcommands which operate on images.
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum ImageOpts {
    /// List fetched images stored in the bootc storage.
    ///
    /// Note that these are distinct from images stored via e.g. `podman`.
    List {
        /// Type of image to list
        #[clap(long = "type")]
        #[arg(default_value_t)]
        list_type: ImageListType,
        #[clap(long = "format")]
        #[arg(default_value_t)]
        list_format: ImageListFormat,
    },
    /// Copy a container image from the bootc storage to `containers-storage:`.
    ///
    /// The source and target are both optional; if both are left unspecified,
    /// via a simple invocation of `bootc image copy-to-storage`, then the default is to
    /// push the currently booted image to `containers-storage` (as used by podman, etc.)
    /// and tagged with the image name `localhost/bootc`,
    ///
    /// ## Copying a non-default container image
    ///
    /// It is also possible to copy an image other than the currently booted one by
    /// specifying `--source`.
    ///
    /// ## Pulling images
    ///
    /// At the current time there is no explicit support for pulling images other than indirectly
    /// via e.g. `bootc switch` or `bootc upgrade`.
    CopyToStorage {
        #[clap(long)]
        /// The source image; if not specified, the booted image will be used.
        source: Option<String>,

        #[clap(long)]
        /// The destination; if not specified, then the default is to push to `containers-storage:localhost/bootc`;
        /// this will make the image accessible via e.g. `podman run localhost/bootc` and for builds.
        target: Option<String>,
    },
    /// Re-pull the currently booted image into the bootc-owned container storage.
    ///
    /// This onboards the system to the unified storage path so that future
    /// upgrade/switch operations can read from the bootc storage directly.
    SetUnified,
    /// Copy a container image from the default `containers-storage:` to the bootc-owned container storage.
    PullFromDefaultStorage {
        /// The image to pull
        image: String,
    },
    /// Wrapper for selected `podman image` subcommands in bootc storage.
    #[clap(subcommand)]
    Cmd(ImageCmdOpts),
}

#[derive(Debug, Clone, clap::ValueEnum, PartialEq, Eq)]
pub(crate) enum SchemaType {
    Host,
    Progress,
}

/// Options for consistency checking
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum FsverityOpts {
    /// Measure the fsverity digest of the target file.
    Measure {
        /// Path to file
        path: Utf8PathBuf,
    },
    /// Enable fsverity on the target file.
    Enable {
        /// Ptah to file
        path: Utf8PathBuf,
    },
}

#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum UkiSubcommands {
    /// Extract kernel + initrd from a UKI
    /// The output (vmlinuz + initramfs.img) is placed in a directory named
    /// after the kernel version found in the UKI
    Extract {
        /// The path to the UKI PE
        path: Utf8PathBuf,
        /// The output path
        output_path: Utf8PathBuf,
    },
}

/// Subcommands for `bootc internals selinux`.
#[cfg(feature = "selinux")]
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum SelinuxOpts {
    /// Exit successfully when PATH is unlabeled; otherwise exit with status 1.
    IsUnlabeled {
        /// Absolute path to inspect without following a final symbolic link.
        #[arg(value_parser = parse_absolute_path)]
        path: Utf8PathBuf,
    },
}

pub(crate) fn parse_absolute_path(value: &str) -> std::result::Result<Utf8PathBuf, String> {
    let path = Utf8PathBuf::from(value);
    if path.is_absolute() {
        Ok(path)
    } else {
        Err("path must be absolute".to_string())
    }
}

/// Hidden, internal only options
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum InternalsOpts {
    SystemdGenerator {
        normal_dir: Utf8PathBuf,
        #[allow(dead_code)]
        early_dir: Option<Utf8PathBuf>,
        #[allow(dead_code)]
        late_dir: Option<Utf8PathBuf>,
    },
    FixupEtcFstab,
    /// Remove orphaned and duplicate entries from /etc/shadow and /etc/gshadow
    /// before systemd-sysusers runs.
    SysusersSync,
    /// Should only be used by `make update-generated`
    PrintJsonSchema {
        #[clap(long)]
        of: SchemaType,
    },
    #[clap(subcommand)]
    Fsverity(FsverityOpts),
    #[cfg(feature = "selinux")]
    #[clap(subcommand)]
    Selinux(SelinuxOpts),
    /// Perform consistency checking.
    Fsck,
    /// Perform cleanup actions
    Cleanup,
    Relabel {
        #[clap(long)]
        /// Relabel using this path as root
        as_path: Option<Utf8PathBuf>,

        /// Relabel this path
        path: Utf8PathBuf,
    },
    /// Relabel the overlay mount point inodes after SELinux policy load.
    /// Called by the generated bootc-early-overlay-relabel unit.
    RelabelOverlayMountpoints,
    /// Proxy frontend for the `ostree-ext` CLI.
    OstreeExt {
        #[clap(allow_hyphen_values = true)]
        args: Vec<OsString>,
    },
    /// Proxy frontend for the `cfsctl` CLI
    Cfs {
        #[clap(allow_hyphen_values = true)]
        args: Vec<OsString>,
    },
    /// Proxy frontend for the legacy `ostree container` CLI.
    OstreeContainer {
        #[clap(allow_hyphen_values = true)]
        args: Vec<OsString>,
    },
    /// Ensure that a composefs repository is initialized
    TestComposefs,
    /// Record the booted aboot slot in persistent deployment state.
    ComposefsAbootReconcile,
    /// Loopback device cleanup helper (internal use only)
    LoopbackCleanupHelper {
        /// Device path to clean up
        #[clap(long)]
        device: String,
    },
    /// Test loopback device allocation and cleanup (internal use only)
    AllocateCleanupLoopback {
        /// File path to create loopback device for
        #[clap(long)]
        file_path: Utf8PathBuf,
    },
    /// Invoked from ostree-ext to complete an installation.
    BootcInstallCompletion {
        /// Path to the sysroot
        sysroot: Utf8PathBuf,

        // The stateroot
        stateroot: String,
    },
    /// Initiate a reboot the same way we would after --apply; intended
    /// primarily for testing.
    Reboot,
    #[cfg(feature = "rhsm")]
    /// Publish subscription-manager facts to /etc/rhsm/facts/bootc.facts
    PublishRhsmFacts,
    /// Internal command for testing etc-diff/etc-merge
    DirDiff {
        /// Directory path to the pristine_etc
        pristine_etc: Utf8PathBuf,
        /// Directory path to the current_etc
        current_etc: Utf8PathBuf,
        /// Directory path to the new_etc
        new_etc: Utf8PathBuf,
        /// Whether to perform the three way merge or not
        #[clap(long)]
        merge: bool,
    },
    #[cfg(feature = "docgen")]
    /// Dump CLI structure as JSON for documentation generation
    DumpCliJson,
    PrepSoftReboot {
        #[clap(required_unless_present = "reset")]
        deployment: Option<String>,
        #[clap(long, conflicts_with = "reset")]
        reboot: bool,
        #[clap(long, conflicts_with = "reboot")]
        reset: bool,
    },
    ComposefsGC {
        #[clap(long)]
        dry_run: bool,
        /// Exit with an error if GC would remove any objects or prune any symlinks.
        /// Implies `--dry-run`.  Intended for use in tests and health-checks.
        #[clap(long)]
        assert_no_op: bool,
        /// Prune the composefs repository in addition to boot binaries
        #[clap(long)]
        prune_repo: bool,
    },
    /// Block device inspection tools.
    #[clap(subcommand)]
    Blockdev(BlockdevOpts),
    /// For various UKI operations
    #[clap(subcommand)]
    Uki(UkiSubcommands),
}

/// Subcommands for `bootc internals blockdev`.
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum BlockdevOpts {
    /// List block device information (as JSON) for a given device path.
    ///
    /// This runs lsblk and backfills any missing partition metadata,
    /// including falling back to `blkid -p` when the udev database
    /// is unavailable.
    Ls {
        /// Block device path (e.g. /dev/vda)
        device: Utf8PathBuf,
    },
    /// List block device information (as JSON) for the device backing a filesystem.
    ///
    /// Takes a directory path, finds the underlying block device, and
    /// outputs its full device tree with backfilled metadata.
    LsFilesystem {
        /// Filesystem path (e.g. /sysroot)
        path: Utf8PathBuf,
    },
}

/// Options for the `set-options-for-source` subcommand.
#[derive(Debug, Parser, PartialEq, Eq)]
pub(crate) struct SetOptionsForSourceOpts {
    /// The name of the source that owns these kernel arguments.
    ///
    /// Must contain only alphanumeric characters, hyphens, or underscores.
    /// Examples: "tuned", "admin", "bootc-kargs-d"
    #[clap(long)]
    pub(crate) source: String,

    /// The kernel arguments to set for this source.
    ///
    /// If not provided, the source is removed and its options are
    /// dropped from the merged `options` line.
    #[clap(long)]
    pub(crate) options: Option<String>,
}

/// Operations on Boot Loader Specification (BLS) entries.
///
/// These commands support managing kernel arguments from multiple independent
/// sources (e.g., TuneD, admin, bootc kargs.d) by tracking argument ownership
/// via `x-options-source-<name>` extension keys in BLS config files.
///
/// See <https://github.com/ostreedev/ostree/pull/3570>
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum LoaderEntriesOpts {
    /// Set or update the kernel arguments owned by a specific source.
    ///
    /// Each source's arguments are tracked via `x-options-source-<name>`
    /// keys in BLS config files. The `options` line is recomputed as the
    /// merge of all tracked sources plus any untracked (pre-existing) options.
    ///
    /// This stages a new deployment with the updated kernel arguments.
    ///
    /// ## Examples
    ///
    /// Add TuneD kernel arguments:
    /// bootc loader-entries set-options-for-source --source tuned --options "isolcpus=1-3 nohz_full=1-3"
    ///
    /// Update TuneD kernel arguments:
    /// bootc loader-entries set-options-for-source --source tuned --options "isolcpus=0-7"
    ///
    /// Remove TuneD kernel arguments:
    /// bootc loader-entries set-options-for-source --source tuned
    SetOptionsForSource(SetOptionsForSourceOpts),
}

/// The name of the `bootc loader-entries` subcommand.
const LOADER_ENTRIES_SUBCOMMAND: &str = "loader-entries";

#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum StateOpts {
    /// Remove all ostree deployments from this system
    WipeOstree,
}

impl InternalsOpts {
    /// The name of the binary we inject into /usr/lib/systemd/system-generators
    const GENERATOR_BIN: &'static str = "bootc-systemd-generator";
}

#[derive(Debug, Clone, Copy, clap::ValueEnum, PartialEq, Eq)]
pub(crate) enum UkiAddonScope {
    Global,
    Scoped,
}

#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum UkiAddonCliOpts {
    /// List all installed UKI Addons
    List {
        /// Output in JSON format
        #[clap(long)]
        json: bool,
        /// List all staged addons as well
        #[clap(long)]
        verbose: bool,
    },
    /// Remove a UKI Addon from the currently booted deployment. If there is
    /// a staged deployment present, the operation is performed on the staged
    /// deployment's addons
    Remove {
        /// Addon name to be provided without the `.addon.efi` suffix
        name: String,
        /// The type of addon being removed, global or scoped
        addon_type: UkiAddonScope,
    },
    /// Add a UKI Addon to the currently booted deployment. If there is
    /// a staged deployment present, the operation is performed on the staged
    /// deployment
    Add {
        /// Addon name to be provided without the `.addon.efi` suffix
        name: String,
        /// The type of addon being added, global or scoped
        addon_type: UkiAddonScope,
    },
    /// List all referenced UKI Addons across all deployments
    ListReferenced {
        /// Output in JSON format
        #[clap(long)]
        json: bool,
    },
}

/// Deploy and transactionally in-place with bootable container images.
///
/// The `bootc` project currently uses ostree-containers as a backend
/// to support a model of bootable container images.  Once installed,
/// whether directly via `bootc install` (executed as part of a container)
/// or via another mechanism such as an OS installer tool, further
/// updates can be pulled and `bootc upgrade`.
#[derive(Debug, Parser, PartialEq, Eq)]
#[clap(name = "bootc")]
#[clap(rename_all = "kebab-case")]
#[clap(version,long_version=clap::crate_version!())]
#[allow(clippy::large_enum_variant)]
pub(crate) enum Opt {
    /// Download and queue an updated container image to apply.
    ///
    /// This does not affect the running system; updates operate in an "A/B" style by default.
    ///
    /// A queued update is visible as `staged` in `bootc status`.
    ///
    /// Currently by default, the update will be applied at shutdown time via `ostree-finalize-staged.service`.
    /// There is also an explicit `bootc upgrade --apply` verb which will automatically take action (rebooting)
    /// if the system has changed.
    ///
    /// However, in the future this is likely to change such that reboots outside of a `bootc upgrade --apply`
    /// do *not* automatically apply the update in addition.
    #[clap(alias = "update")]
    Upgrade(UpgradeOpts),
    /// Target a new container image reference to boot.
    ///
    /// This is almost exactly the same operation as `upgrade`, but additionally changes the container image reference
    /// instead.
    ///
    /// ## Usage
    ///
    /// A common pattern is to have a management agent control operating system updates via container image tags;
    /// for example, `quay.io/exampleos/someuser:v1.0` and `quay.io/exampleos/someuser:v1.1` where some machines
    /// are tracking `:v1.0`, and as a rollout progresses, machines can be switched to `v:1.1`.
    Switch(SwitchOpts),
    /// Change the bootloader entry ordering; the deployment under `rollback` will be queued for the next boot,
    /// and the current will become rollback.  If there is a `staged` entry (an unapplied, queued upgrade)
    /// then it will be discarded.
    ///
    /// Note that absent any additional control logic, if there is an active agent doing automated upgrades
    /// (such as the default `bootc-fetch-apply-updates.timer` and associated `.service`) the
    /// change here may be reverted.  It's recommended to only use this in concert with an agent that
    /// is in active control.
    ///
    /// A systemd journal message will be logged with `MESSAGE_ID=26f3b1eb24464d12aa5e7b544a6b5468` in
    /// order to detect a rollback invocation.
    #[command(after_help = indoc! {r#"
        Note on Rollbacks and the `/etc` Directory:

        When you perform a rollback (e.g., with `bootc rollback`), any
        changes made to files in the `/etc` directory won't carry over
        to the rolled-back deployment.  The `/etc` files will revert
        to their state from that previous deployment instead.

        This is because `bootc rollback` just reorders the existing
        deployments. It doesn't create new deployments. The `/etc`
        merges happen when new deployments are created.
    "#})]
    Rollback(RollbackOpts),
    /// Apply full changes to the host specification.
    ///
    /// This command operates very similarly to `kubectl apply`; if invoked interactively,
    /// then the current host specification will be presented in the system default `$EDITOR`
    /// for interactive changes.
    ///
    /// It is also possible to directly provide new contents via `bootc edit --filename`.
    ///
    /// Only changes to the `spec` section are honored.
    Edit(EditOpts),
    /// Display status.
    ///
    /// Shows bootc system state. Outputs YAML by default, human-readable if terminal detected.
    Status(StatusOpts),
    /// Add a transient overlayfs on `/usr`.
    ///
    /// Allows temporary package installation that will be discarded on reboot.
    #[clap(alias = "usroverlay")]
    UsrOverlay(UsrOverlayOpts),
    /// Install the running container to a target.
    ///
    /// Takes a container image and installs it to disk in a bootable format.
    #[clap(subcommand)]
    Install(InstallOpts),
    /// Operations which can be executed as part of a container build.
    #[clap(subcommand)]
    Container(ContainerOpts),
    /// Operations on container images.
    ///
    /// Stability: This interface may change in the future.
    #[clap(subcommand, hide = true)]
    Image(ImageOpts),
    /// Operations on Boot Loader Specification (BLS) entries.
    ///
    /// Manage kernel arguments from multiple independent sources.
    //
    // Unavailable on hosts whose ostree lacks `bootconfig-extra` support;
    // see `apply_host_feature_gates`.
    #[clap(subcommand, name = LOADER_ENTRIES_SUBCOMMAND)]
    LoaderEntries(LoaderEntriesOpts),
    /// Execute the given command in the host mount namespace
    #[clap(hide = true)]
    ExecInHostMountNamespace {
        #[clap(trailing_var_arg = true, allow_hyphen_values = true)]
        args: Vec<OsString>,
    },
    /// Modify the state of the system
    #[clap(hide = true)]
    #[clap(subcommand)]
    State(StateOpts),
    #[clap(subcommand)]
    #[clap(hide = true)]
    Internals(InternalsOpts),
    #[clap(hide = true)]
    ComposefsFinalizeStaged(ComposefsFinalizeStagedOpts),
    /// Diff current /etc configuration versus default
    #[clap(hide = true)]
    ConfigDiff,
    /// Generate shell completion script for supported shells.
    ///
    /// Example: `bootc completion bash` prints a bash completion script to stdout.
    #[clap(hide = true)]
    Completion {
        /// Shell type to generate (bash, zsh, fish)
        #[clap(value_enum)]
        shell: clap_complete::aot::Shell,
    },
    #[clap(hide = true)]
    DeleteDeployment { depl_id: String },

    /// Perform operations related to UKI Addons
    #[clap(subcommand)]
    UkiAddon(UkiAddonCliOpts),
}

/// Ensure we've entered a mount namespace, so that we can remount
/// `/sysroot` read-write
/// TODO use <https://github.com/ostreedev/ostree/pull/2779> once
/// we can depend on a new enough ostree
#[context("Ensuring mountns")]
pub(crate) fn ensure_self_unshared_mount_namespace(reexec_env: &[(&str, &str)]) -> Result<()> {
    let uid = rustix::process::getuid();
    if !uid.is_root() {
        tracing::debug!("Not root, assuming no need to unshare");
        return Ok(());
    }
    let recurse_env = "_ostree_unshared";
    let ns_pid1 = std::fs::read_link("/proc/1/ns/mnt").context("Reading /proc/1/ns/mnt")?;
    let ns_self = std::fs::read_link("/proc/self/ns/mnt").context("Reading /proc/self/ns/mnt")?;
    // If we already appear to be in a mount namespace, or we're already pid1, we're done
    if ns_pid1 != ns_self {
        tracing::debug!("Already in a mount namespace");
        return Ok(());
    }
    if std::env::var_os(recurse_env).is_some() {
        let am_pid1 = rustix::process::getpid().is_init();
        if am_pid1 {
            tracing::debug!("We are pid 1");
            return Ok(());
        } else {
            anyhow::bail!("Failed to unshare mount namespace");
        }
    }

    // Pass --propagation=slave so that if systemd gpt-auto-generator has
    // automount for /boot it gets propagated inside the new mount ns
    // for us to be able to access the /boot mount even if it's expired
    bootc_utils::reexec::reexec_with_guardenv(
        recurse_env,
        &["unshare", "-m", "--propagation=slave", "--"],
        reexec_env,
    )
}

/// Load global storage state, expecting that we're booted into a bootc system.
/// This prepares the process for write operations (re-exec, mount namespace, etc).
#[context("Initializing storage")]
pub(crate) async fn get_storage() -> Result<crate::store::BootedStorage> {
    let env = crate::store::Environment::detect()?;
    // Always call prepare_for_write() for write operations - it checks
    // for container, root privileges, mount namespace setup, etc.
    prepare_for_write()?;
    let r = BootedStorage::new(env, crate::store::EspAccess::ReadWrite)
        .await?
        .ok_or_else(|| anyhow!("System not booted via bootc"))?;
    r.require_writable()?;
    Ok(r)
}

#[context("Querying root privilege")]
pub(crate) fn require_root(is_container: bool) -> Result<()> {
    ensure!(
        rustix::process::getuid().is_root(),
        if is_container {
            "The user inside the container from which you are running this command must be root"
        } else {
            "This command must be executed as the root user"
        }
    );

    ensure!(
        rustix::thread::capability_is_in_bounding_set(rustix::thread::CapabilitySet::SYS_ADMIN)?,
        if is_container {
            "The container must be executed with full privileges (e.g. --privileged flag)"
        } else {
            "This command requires full root privileges (CAP_SYS_ADMIN)"
        }
    );

    tracing::trace!("Verified uid 0 with CAP_SYS_ADMIN");

    Ok(())
}

/// Check if a deployment has soft reboot capability
fn has_soft_reboot_capability(deployment: Option<&crate::spec::BootEntry>) -> bool {
    deployment.map(|d| d.soft_reboot_capable).unwrap_or(false)
}

/// Prepare a soft reboot for the given deployment
#[context("Preparing soft reboot")]
fn prepare_soft_reboot(sysroot: &SysrootLock, deployment: &ostree::Deployment) -> Result<()> {
    let cancellable = ostree::gio::Cancellable::NONE;
    sysroot
        .deployment_set_soft_reboot(deployment, false, cancellable)
        .context("Failed to prepare soft-reboot")?;
    Ok(())
}

/// Handle soft reboot based on the configured mode
#[context("Handling soft reboot")]
fn handle_soft_reboot<F>(
    soft_reboot_mode: Option<SoftRebootMode>,
    entry: Option<&crate::spec::BootEntry>,
    deployment_type: &str,
    execute_soft_reboot: F,
) -> Result<()>
where
    F: FnOnce() -> Result<()>,
{
    let Some(mode) = soft_reboot_mode else {
        return Ok(());
    };

    let can_soft_reboot = has_soft_reboot_capability(entry);
    match mode {
        SoftRebootMode::Required => {
            if can_soft_reboot {
                execute_soft_reboot()?;
            } else {
                anyhow::bail!(
                    "Soft reboot was required but {} deployment is not soft-reboot capable",
                    deployment_type
                );
            }
        }
        SoftRebootMode::Auto => {
            if can_soft_reboot {
                execute_soft_reboot()?;
            }
        }
    }
    Ok(())
}

/// Handle soft reboot for staged deployments (used by upgrade and switch)
#[context("Handling staged soft reboot")]
fn handle_staged_soft_reboot(
    booted_ostree: &BootedOstree<'_>,
    soft_reboot_mode: Option<SoftRebootMode>,
    host: &crate::spec::Host,
) -> Result<()> {
    handle_soft_reboot(
        soft_reboot_mode,
        host.status.staged.as_ref(),
        "staged",
        || soft_reboot_staged(booted_ostree.sysroot),
    )
}

/// Perform a soft reboot for a staged deployment
#[context("Soft reboot staged deployment")]
fn soft_reboot_staged(sysroot: &SysrootLock) -> Result<()> {
    println!("Staged deployment is soft-reboot capable, preparing for soft-reboot...");

    let deployments_list = sysroot.deployments();
    let staged_deployment = deployments_list
        .iter()
        .find(|d| d.is_staged())
        .ok_or_else(|| anyhow::anyhow!("Failed to find staged deployment"))?;

    prepare_soft_reboot(sysroot, staged_deployment)?;
    Ok(())
}

/// Perform a soft reboot for a rollback deployment
#[context("Soft reboot rollback deployment")]
fn soft_reboot_rollback(booted_ostree: &BootedOstree<'_>) -> Result<()> {
    println!("Rollback deployment is soft-reboot capable, preparing for soft-reboot...");

    let deployments_list = booted_ostree.sysroot.deployments();
    let target_deployment = deployments_list
        .first()
        .ok_or_else(|| anyhow::anyhow!("No rollback deployment found!"))?;

    prepare_soft_reboot(booted_ostree.sysroot, target_deployment)
}

/// A few process changes that need to be made for writing.
/// IMPORTANT: This may end up re-executing the current process,
/// so anything that happens before this should be idempotent.
#[context("Preparing for write")]
pub(crate) fn prepare_for_write() -> Result<()> {
    use std::sync::atomic::{AtomicBool, Ordering};

    // This is intending to give "at most once" semantics to this
    // function. We should never invoke this from multiple threads
    // at the same time, but verifying "on main thread" is messy.
    // Yes, using SeqCst is likely overkill, but there is nothing perf
    // sensitive about this.
    static ENTERED: AtomicBool = AtomicBool::new(false);
    if ENTERED.load(Ordering::SeqCst) {
        return Ok(());
    }
    if ostree_ext::container_utils::running_in_container() {
        anyhow::bail!("Detected container; this command requires a booted host system.");
    }
    crate::cli::require_root(false)?;
    ensure_self_unshared_mount_namespace(&[])?;
    if crate::lsm::selinux_enabled() && !crate::lsm::selinux_ensure_install(&[])? {
        tracing::debug!("Do not have install_t capabilities");
    }
    ENTERED.store(true, Ordering::SeqCst);
    Ok(())
}

struct ApplyFromDownloadedOpts {
    soft_reboot: Option<SoftRebootMode>,
    apply: bool,
}

async fn apply_from_downloaded_ostree(
    storage: &Storage,
    booted_ostree: &BootedOstree<'_>,
    host: &crate::spec::Host,
    opts: &ApplyFromDownloadedOpts,
) -> Result<()> {
    let ostree = storage.get_ostree()?;
    let staged_deployment = ostree
        .staged_deployment()
        .ok_or_else(|| anyhow::anyhow!("No staged deployment found"))?;

    if staged_deployment.is_finalization_locked() {
        crate::boundimage::pull_bound_images(storage, &staged_deployment).await?;
        ostree.change_finalization(&staged_deployment)?;
        println!("Staged deployment will now be applied on reboot");
    } else {
        println!("Staged deployment is already set to apply on reboot");
    }

    handle_staged_soft_reboot(booted_ostree, opts.soft_reboot, &host)?;
    if opts.apply {
        crate::reboot::reboot()?;
    }
    return Ok(());
}

/// Implementation of the `bootc upgrade` CLI command.
#[context("Upgrading")]
async fn upgrade(
    opts: UpgradeOpts,
    storage: &Storage,
    booted_ostree: &BootedOstree<'_>,
) -> Result<()> {
    let delta = crate::delta::open_opt(opts.from_delta.as_deref())
        .await?
        .map(std::sync::Arc::new);

    let repo = &booted_ostree.repo();

    let host = crate::status::get_status(booted_ostree)?.1;
    let current_image = host.spec.image.as_ref();

    // Handle --tag: derive target from current image + new tag
    let derived_image = if let Some(ref tag) = opts.tag {
        let image = current_image.ok_or_else(|| {
            anyhow::anyhow!("--tag requires a booted image with a specified source")
        })?;
        Some(image.with_tag(tag)?)
    } else {
        None
    };

    let imgref = derived_image.as_ref().or(current_image);
    let prog: ProgressWriter = opts.progress.try_into()?;

    // If there's no specified image, let's be nice and check if the booted system is using rpm-ostree
    if imgref.is_none() {
        let booted_incompatible = host.status.booted.as_ref().is_some_and(|b| b.incompatible);

        let staged_incompatible = host.status.staged.as_ref().is_some_and(|b| b.incompatible);

        if booted_incompatible || staged_incompatible {
            return Err(anyhow::anyhow!(
                "Deployment contains local rpm-ostree modifications; cannot upgrade via bootc. You can run `rpm-ostree reset` to undo the modifications."
            ));
        }
    }

    let imgref = imgref.ok_or_else(|| anyhow::anyhow!("No image source specified"))?;
    // Use the derived image reference (if --tag was specified) instead of the spec's image
    let spec = RequiredHostSpec { image: imgref };
    let booted_image = host
        .status
        .booted
        .as_ref()
        .map(|b| b.query_image(repo))
        .transpose()?
        .flatten();
    // Find the currently queued digest, if any before we pull
    let staged = host.status.staged.as_ref();
    let staged_image = staged.as_ref().and_then(|s| s.image.as_ref());
    let mut changed = false;

    // Handle --from-downloaded: unlock existing staged deployment without fetching from image source
    if opts.download_opts.from_downloaded {
        return apply_from_downloaded_ostree(
            storage,
            booted_ostree,
            &host,
            &ApplyFromDownloadedOpts {
                soft_reboot: opts.soft_reboot,
                apply: opts.apply,
            },
        )
        .await;
    }

    // Ensure the bootc storage directory is initialized; the --check path
    // needs this for update_mtime() and the non-check path needs it for
    // unified pull detection.
    let use_unified = crate::deploy::image_exists_in_unified_storage(storage, imgref).await?;
    if let Some(delta) = delta.as_deref() {
        crate::delta::reject_unified_storage(delta, use_unified)?;
    }

    if opts.check {
        let ostree_imgref = imgref.clone().into();
        let mut imp =
            crate::deploy::new_importer(repo, &ostree_imgref, Some(&booted_ostree.deployment))
                .await?;
        match imp.prepare().await? {
            PrepareResult::AlreadyPresent(_) => {
                println!("No changes in: {ostree_imgref:#}");
            }
            PrepareResult::Ready(r) => {
                crate::deploy::check_bootc_label(&r.config);
                println!("Update available for: {ostree_imgref:#}");
                if let Some(version) = r.version() {
                    println!("  Version: {version}");
                }
                println!("  Digest: {}", r.manifest_digest);
                changed = true;
                if let Some(previous_image) = booted_image.as_ref() {
                    let diff =
                        ostree_container::ManifestDiff::new(&previous_image.manifest, &r.manifest);
                    diff.print();
                }
            }
        }
    } else {
        let fetched = if let Some(delta) = delta.clone() {
            crate::deploy::pull_delta(
                repo,
                imgref,
                delta,
                opts.quiet,
                prog.clone(),
                Some(&booted_ostree.deployment),
            )
            .await?
        } else if use_unified {
            crate::deploy::pull_unified(
                repo,
                imgref,
                None,
                opts.quiet,
                prog.clone(),
                storage,
                Some(&booted_ostree.deployment),
            )
            .await?
        } else {
            crate::deploy::pull(
                repo,
                imgref,
                None,
                opts.quiet,
                prog.clone(),
                Some(&booted_ostree.deployment),
            )
            .await?
        };
        let staged_digest = staged_image.map(|s| s.digest().expect("valid digest in status"));
        let fetched_digest = &fetched.manifest_digest;
        tracing::debug!("staged: {staged_digest:?}");
        tracing::debug!("fetched: {fetched_digest}");
        let staged_unchanged = staged_digest
            .as_ref()
            .map(|d| d == fetched_digest)
            .unwrap_or_default();
        let booted_unchanged = booted_image
            .as_ref()
            .map(|img| &img.manifest_digest == fetched_digest)
            .unwrap_or_default();
        if staged_unchanged {
            let staged_deployment = storage.get_ostree()?.staged_deployment();
            let mut download_only_changed = false;

            if let Some(staged) = staged_deployment {
                // Handle download-only mode based on flags
                if opts.download_opts.download_only {
                    // --download-only: set download-only mode
                    if !staged.is_finalization_locked() {
                        storage.get_ostree()?.change_finalization(&staged)?;
                        println!("Image downloaded, but will not be applied on reboot");
                        download_only_changed = true;
                    }
                } else if !opts.check {
                    // --apply or no flags: clear download-only mode
                    // (skip if --check, which is read-only)
                    if staged.is_finalization_locked() {
                        storage.get_ostree()?.change_finalization(&staged)?;
                        println!("Staged deployment will now be applied on reboot");
                        download_only_changed = true;
                    }
                }
            } else if opts.download_opts.download_only || opts.apply {
                anyhow::bail!("No staged deployment found");
            }

            if !download_only_changed {
                println!("Staged update present, not changed");
            }

            handle_staged_soft_reboot(booted_ostree, opts.soft_reboot, &host)?;
            if opts.apply {
                crate::reboot::reboot()?;
            }
        } else if booted_unchanged {
            println!("No update available.")
        } else {
            let stateroot = booted_ostree.stateroot();
            let from = MergeState::from_stateroot(storage, &stateroot)?;
            crate::deploy::stage(
                storage,
                from,
                &fetched,
                &spec,
                prog.clone(),
                opts.download_opts.download_only,
            )
            .await?;
            changed = true;
            if let Some(prev) = booted_image.as_ref() {
                if let Some(fetched_manifest) = fetched.get_manifest(repo)? {
                    let diff =
                        ostree_container::ManifestDiff::new(&prev.manifest, &fetched_manifest);
                    diff.print();
                }
            }
        }
    }
    if changed {
        storage.update_mtime()?;

        if opts.soft_reboot.is_some() {
            // At this point we have new staged deployment and the host definition has changed.
            // We need the updated host status before we check if we can prepare the soft-reboot.
            let updated_host = crate::status::get_status(booted_ostree)?.1;
            handle_staged_soft_reboot(booted_ostree, opts.soft_reboot, &updated_host)?;
        }

        if opts.apply {
            crate::reboot::reboot()?;
        }
    } else {
        tracing::debug!("No changes");
    }

    Ok(())
}

#[context("Getting imgref for switch")]
pub(crate) fn imgref_for_switch(opts: &SwitchOpts) -> Result<ImageReference> {
    let transport = ostree_container::Transport::try_from(opts.transport.as_str())?;
    let imgref = ostree_container::ImageReference {
        transport,
        name: opts
            .target
            .as_ref()
            .ok_or_else(|| anyhow!("Target image not found"))?
            .to_string(),
    };
    let sigverify = sigpolicy_from_opt(opts.enforce_container_sigpolicy);
    let target = ostree_container::OstreeImageReference { sigverify, imgref };
    let target = ImageReference::from(target);

    return Ok(target);
}

/// Implementation of the `bootc switch` CLI command for ostree backend.
#[context("Switching (ostree)")]
async fn switch_ostree(
    opts: SwitchOpts,
    storage: &Storage,
    booted_ostree: &BootedOstree<'_>,
) -> Result<()> {
    let delta = crate::delta::open_opt(opts.from_delta.as_deref())
        .await?
        .map(std::sync::Arc::new);

    let (_, host) = crate::status::get_status(booted_ostree)?;

    if opts.download_opts.from_downloaded {
        return apply_from_downloaded_ostree(
            storage,
            booted_ostree,
            &host,
            &ApplyFromDownloadedOpts {
                soft_reboot: opts.soft_reboot,
                apply: opts.apply,
            },
        )
        .await;
    }

    let target = imgref_for_switch(&opts)?;
    let prog: ProgressWriter = opts.progress.try_into()?;
    let cancellable = gio::Cancellable::NONE;

    let repo = &booted_ostree.repo();

    let new_spec = {
        let mut new_spec = host.spec.clone();
        new_spec.image = Some(target.clone());
        new_spec
    };

    if new_spec == host.spec {
        println!("Image specification is unchanged.");
        if opts.apply && host.status.staged.is_some() {
            crate::reboot::reboot()?;
        }
        return Ok(());
    }

    // Log the switch operation to systemd journal
    const SWITCH_JOURNAL_ID: &str = "7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1";
    let old_image = host
        .spec
        .image
        .as_ref()
        .map(|i| i.image.as_str())
        .unwrap_or("none");

    tracing::info!(
        message_id = SWITCH_JOURNAL_ID,
        bootc.old_image_reference = old_image,
        bootc.new_image_reference = &target.image,
        bootc.new_image_transport = &target.transport,
        "Switching from image {} to {}",
        old_image,
        target.image
    );

    let new_spec = RequiredHostSpec::from_spec(&new_spec)?;

    // Determine whether to use unified storage path.
    // If explicitly requested via flag, use unified storage directly.
    // Otherwise, auto-detect based on whether the image exists in bootc storage.
    let use_unified = if opts.unified_storage_exp {
        true
    } else {
        crate::deploy::image_exists_in_unified_storage(storage, &target).await?
    };
    if let Some(delta) = delta.as_deref() {
        crate::delta::reject_unified_storage(delta, use_unified)?;
    }

    let fetched = if let Some(delta) = delta.clone() {
        crate::deploy::pull_delta(
            repo,
            &target,
            delta,
            opts.quiet,
            prog.clone(),
            Some(&booted_ostree.deployment),
        )
        .await?
    } else if use_unified {
        crate::deploy::pull_unified(
            repo,
            &target,
            None,
            opts.quiet,
            prog.clone(),
            storage,
            Some(&booted_ostree.deployment),
        )
        .await?
    } else {
        crate::deploy::pull(
            repo,
            &target,
            None,
            opts.quiet,
            prog.clone(),
            Some(&booted_ostree.deployment),
        )
        .await?
    };

    if !opts.retain {
        // By default, we prune the previous ostree ref so it will go away after later upgrades
        if let Some(booted_origin) = booted_ostree.deployment.origin() {
            if let Some(ostree_ref) = booted_origin.optional_string("origin", "refspec")? {
                let (remote, ostree_ref) =
                    ostree::parse_refspec(&ostree_ref).context("Failed to parse ostree ref")?;
                repo.set_ref_immediate(remote.as_deref(), &ostree_ref, None, cancellable)?;
            }
        }
    }

    let stateroot = booted_ostree.stateroot();
    let from = MergeState::from_stateroot(storage, &stateroot)?;
    crate::deploy::stage(
        storage,
        from,
        &fetched,
        &new_spec,
        prog.clone(),
        opts.download_opts.download_only,
    )
    .await?;

    storage.update_mtime()?;

    if opts.download_opts.download_only {
        return Ok(());
    }

    if opts.soft_reboot.is_some() {
        // At this point we have staged the deployment and the host definition has changed.
        // We need the updated host status before we check if we can prepare the soft-reboot.
        let updated_host = crate::status::get_status(booted_ostree)?.1;
        handle_staged_soft_reboot(booted_ostree, opts.soft_reboot, &updated_host)?;
    }

    // `--apply` cannot be passed along with `--download-only` (handled by clap)
    // but for sanity nonetheless
    if opts.apply {
        crate::reboot::reboot()?;
    }

    Ok(())
}

/// Implementation of the `bootc switch` CLI command.
#[context("Switching")]
async fn switch(opts: SwitchOpts) -> Result<()> {
    // If we're doing an in-place mutation, we shortcut most of the rest of the work here
    // TODO: what we really want here is Storage::detect_from_root() that also handles
    // composefs. But for now this just assumes ostree.
    if opts.mutate_in_place {
        let target = imgref_for_switch(&opts)?;
        let deployid = {
            // Clone to pass into helper thread
            let target = target.clone();
            let root = cap_std::fs::Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
            tokio::task::spawn_blocking(move || {
                crate::deploy::switch_origin_inplace(&root, &target)
            })
            .await??
        };
        println!("Updated {deployid} to pull from {target}");
        return Ok(());
    }
    let storage = &get_storage().await?;
    match storage.kind()? {
        BootedStorageKind::Ostree(booted_ostree) => {
            if opts.uki_addon_opts.scoped.is_some() || opts.uki_addon_opts.global.is_some() {
                anyhow::bail!("UKI Addon options are only supported for composefs backend");
            }

            switch_ostree(opts, storage, &booted_ostree).await
        }
        BootedStorageKind::Composefs(booted_cfs) => {
            switch_composefs(opts, storage, &booted_cfs).await
        }
    }
}

/// Implementation of the `bootc rollback` CLI command for ostree backend.
#[context("Rollback (ostree)")]
async fn rollback_ostree(
    opts: &RollbackOpts,
    storage: &Storage,
    booted_ostree: &BootedOstree<'_>,
) -> Result<()> {
    crate::deploy::rollback(storage).await?;

    if opts.soft_reboot.is_some() {
        // Get status of rollback deployment to check soft-reboot capability
        let host = crate::status::get_status(booted_ostree)?.1;

        handle_soft_reboot(
            opts.soft_reboot,
            host.status.rollback.as_ref(),
            "rollback",
            || soft_reboot_rollback(booted_ostree),
        )?;
    }

    Ok(())
}

/// Implementation of the `bootc rollback` CLI command.
#[context("Rollback")]
async fn rollback(opts: &RollbackOpts) -> Result<()> {
    let storage = &get_storage().await?;
    match storage.kind()? {
        BootedStorageKind::Ostree(booted_ostree) => {
            rollback_ostree(opts, storage, &booted_ostree).await
        }
        BootedStorageKind::Composefs(booted_cfs) => composefs_rollback(storage, &booted_cfs).await,
    }
}

/// Implementation of the `bootc edit` CLI command for ostree backend.
#[context("Editing spec (ostree)")]
async fn edit_ostree(
    opts: EditOpts,
    storage: &Storage,
    booted_ostree: &BootedOstree<'_>,
) -> Result<()> {
    let repo = &booted_ostree.repo();
    let (_, host) = crate::status::get_status(booted_ostree)?;

    let new_host: Host = if let Some(filename) = opts.filename {
        let mut r = std::io::BufReader::new(std::fs::File::open(filename)?);
        serde_yaml::from_reader(&mut r)?
    } else {
        let tmpf = tempfile::NamedTempFile::with_suffix(".yaml")?;
        serde_yaml::to_writer(std::io::BufWriter::new(tmpf.as_file()), &host)?;
        crate::utils::spawn_editor(&tmpf)?;
        tmpf.as_file().seek(std::io::SeekFrom::Start(0))?;
        serde_yaml::from_reader(&mut tmpf.as_file())?
    };

    if new_host.spec == host.spec {
        println!("Edit cancelled, no changes made.");
        return Ok(());
    }
    host.spec.verify_transition(&new_host.spec)?;
    let new_spec = RequiredHostSpec::from_spec(&new_host.spec)?;

    let prog = ProgressWriter::default();

    // We only support two state transitions right now; switching the image,
    // or flipping the bootloader ordering.
    if host.spec.boot_order != new_host.spec.boot_order {
        return crate::deploy::rollback(storage).await;
    }

    let fetched = crate::deploy::pull(
        repo,
        new_spec.image,
        None,
        opts.quiet,
        prog.clone(),
        Some(&booted_ostree.deployment),
    )
    .await?;

    // TODO gc old layers here

    let stateroot = booted_ostree.stateroot();
    let from = MergeState::from_stateroot(storage, &stateroot)?;
    crate::deploy::stage(storage, from, &fetched, &new_spec, prog.clone(), false).await?;

    storage.update_mtime()?;

    Ok(())
}

/// Implementation of the `bootc edit` CLI command.
#[context("Editing spec")]
async fn edit(opts: EditOpts) -> Result<()> {
    let storage = &get_storage().await?;
    match storage.kind()? {
        BootedStorageKind::Ostree(booted_ostree) => {
            edit_ostree(opts, storage, &booted_ostree).await
        }
        BootedStorageKind::Composefs(_) => {
            anyhow::bail!("Edit is not yet supported for composefs backend")
        }
    }
}

/// Implementation of `bootc usroverlay`
async fn usroverlay(access_mode: FilesystemOverlayAccessMode) -> Result<()> {
    let status = get_usr_overlay_status()?;
    if status.is_some() {
        println!("An overlayfs is already mounted on /usr");
        return Ok(());
    }

    // This is just a pass-through today.  At some point we may make this a libostree API
    // or even oxidize it.
    let args = match access_mode {
        // In this context, "--transient" means "read-only overlay"
        FilesystemOverlayAccessMode::ReadOnly => ["admin", "unlock", "--transient"].as_slice(),

        FilesystemOverlayAccessMode::ReadWrite => ["admin", "unlock"].as_slice(),
    };
    Err(Command::new("ostree").args(args).exec().into())
}

/// Join the host IPC namespace if we're in an isolated one and have
/// sufficient privileges. The default for `podman run` is a separate IPC
/// namespace, which for e.g. `bootc install` can cause failures where tools
/// like udev/cryptsetup expect semaphores to be in sync with the host.
/// While we do want callers to pass `--ipc=host`, we don't want to force
/// them to need to either.
///
/// Requires `CAP_SYS_ADMIN` (needed for `setns()`); silently skipped when
/// running unprivileged (e.g. during RPM build for manpage generation).
/// Also skipped when `/proc/1/ns/ipc` is not accessible, which can happen
/// in restricted build environments (e.g. Tekton/Buildah containers) where
/// `/proc` is masked even for processes with `CAP_SYS_ADMIN`.
fn join_host_ipc_namespace() -> Result<()> {
    let caps = rustix::thread::capabilities(None).context("capget")?;
    if !caps
        .effective
        .contains(rustix::thread::CapabilitySet::SYS_ADMIN)
    {
        return Ok(());
    }
    let ns_pid1 = match std::fs::read_link("/proc/1/ns/ipc") {
        Ok(v) => v,
        Err(e) if e.kind() == std::io::ErrorKind::PermissionDenied => {
            return Ok(());
        }
        Err(e) => return Err(e).context("reading /proc/1/ns/ipc"),
    };
    let ns_self = std::fs::read_link("/proc/self/ns/ipc").context("reading /proc/self/ns/ipc")?;
    if ns_pid1 != ns_self {
        let pid1ipcns = std::fs::File::open("/proc/1/ns/ipc").context("open pid1 ipcns")?;
        rustix::thread::move_into_link_name_space(
            pid1ipcns.as_fd(),
            Some(rustix::thread::LinkNameSpaceType::InterProcessCommunication),
        )
        .context("setns(ipc)")?;
    }
    Ok(())
}

/// Perform process global initialization. This should be called as early as possible
/// in the standard `main` function.
#[allow(unsafe_code)]
pub fn global_init() -> Result<()> {
    join_host_ipc_namespace()?;
    // In some cases we re-exec with a temporary binary,
    // so ensure that the syslog identifier is set.
    ostree::glib::set_prgname(bootc_utils::NAME.into());
    if let Err(e) = rustix::thread::set_name(&CString::new(bootc_utils::NAME).unwrap()) {
        // This shouldn't ever happen
        eprintln!("failed to set name: {e}");
    }
    // Silence SELinux log warnings
    ostree::SePolicy::set_null_log();
    let am_root = rustix::process::getuid().is_root();
    // Work around bootc-image-builder not setting HOME, in combination with podman (really c/common)
    // bombing out if it is unset.
    if std::env::var_os("HOME").is_none() && am_root {
        // Setting the environment is thread-unsafe, but we ask calling code
        // to invoke this as early as possible. (In practice, that's just the cli's `main.rs`)
        // xref https://internals.rust-lang.org/t/synchronized-ffi-access-to-posix-environment-variable-functions/15475
        // SAFETY: Called early in main() before any threads are spawned.
        unsafe {
            std::env::set_var("HOME", "/root");
        }
    }
    Ok(())
}

/// The outcome of executing the CLI.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CliExitStatus {
    Success,
    PredicateFalse,
}

#[cfg(feature = "selinux")]
fn is_unlabeled_exit_status(
    state: crate::lsm::SELinuxLabelState,
    path: &Utf8Path,
) -> Result<CliExitStatus> {
    match state {
        crate::lsm::SELinuxLabelState::Unlabeled => Ok(CliExitStatus::Success),
        crate::lsm::SELinuxLabelState::Labeled => Ok(CliExitStatus::PredicateFalse),
        crate::lsm::SELinuxLabelState::Unsupported => {
            anyhow::bail!("SELinux labeling is unsupported for {path}")
        }
    }
}

/// Parse the provided arguments and execute.
/// Calls [`clap::Error::exit`] on failure, printing the error message and aborting the program.
pub async fn run_from_iter<I>(args: I) -> Result<CliExitStatus>
where
    I: IntoIterator,
    I::Item: Into<OsString> + Clone,
{
    run_from_opt(Opt::parse_including_static(args)).await
}

/// Find the base binary name from argv0 (without a full path). The empty string
/// is never returned; instead a fallback string is used. If the input is not valid
/// UTF-8, a default is used.
fn callname_from_argv0(argv0: &OsStr) -> &str {
    let default = "bootc";
    std::path::Path::new(argv0)
        .file_name()
        .and_then(|s| s.to_str())
        .filter(|s| !s.is_empty())
        .unwrap_or(default)
}

impl Opt {
    /// In some cases (e.g. systemd generator) we dispatch specifically on argv0.  This
    /// requires some special handling in clap.
    fn parse_including_static<I>(args: I) -> Self
    where
        I: IntoIterator,
        I::Item: Into<OsString> + Clone,
    {
        let mut args = args.into_iter();
        let first = if let Some(first) = args.next() {
            let first: OsString = first.into();
            let argv0 = callname_from_argv0(&first);
            tracing::debug!("argv0={argv0:?}");
            let mapped = match argv0 {
                InternalsOpts::GENERATOR_BIN => {
                    Some(["bootc", "internals", "systemd-generator"].as_slice())
                }
                "ostree-container" | "ostree-ima-sign" | "ostree-provisional-repair" => {
                    Some(["bootc", "internals", "ostree-ext"].as_slice())
                }
                _ => None,
            };
            if let Some(base_args) = mapped {
                let base_args = base_args.iter().map(OsString::from);
                return Opt::parse_from_host(base_args.chain(args.map(|i| i.into())));
            }
            Some(first)
        } else {
            None
        };
        Opt::parse_from_host(first.into_iter().chain(args.map(|i| i.into())))
    }

    /// Equivalent to [`clap::Parser::parse_from`], but with host feature gates
    /// applied so that `--help` and error output only advertise what this host
    /// supports, and gated subcommands are rejected before being dispatched.
    ///
    /// [`Opt::command`] always describes the full CLI; it is what documentation
    /// and shell completions are generated from, so those don't vary with the
    /// ostree version on the build host.
    fn parse_from_host<I>(args: I) -> Self
    where
        I: IntoIterator,
        I::Item: Into<OsString> + Clone,
    {
        use clap::FromArgMatches;
        let args: Vec<OsString> = args.into_iter().map(Into::into).collect();
        let bootconfig_extra = crate::loader_entries::ostree_supports_bootconfig_extra();
        let host_command = || apply_host_feature_gates(Opt::command(), bootconfig_extra);
        // A gated subcommand is rejected whatever its arguments, `--help`
        // included, with a distinct exit status so that a caller probing for
        // the feature can tell "unsupported here" from a usage error.
        if host_feature_gate_rejects(&args, bootconfig_extra) {
            let err = host_command().error(
                clap::error::ErrorKind::InvalidSubcommand,
                crate::loader_entries::unsupported_ostree_error(),
            );
            // Only stderr can fail here, and we're exiting anyway.
            let _ = err.print();
            std::process::exit(EXIT_UNAVAILABLE);
        }
        let mut matches = host_command().get_matches_from(args);
        match Self::from_arg_matches_mut(&mut matches) {
            Ok(opt) => opt,
            Err(e) => e.format(&mut host_command()).exit(),
        }
    }
}

/// Exit status when a subcommand is unavailable because the running host
/// lacks the feature behind it (see [`host_feature_gate_rejects`]).  Distinct
/// from a usage error (2) and a runtime failure (1) so that a caller probing
/// for the feature, as TuneD does with
/// `bootc loader-entries set-options-for-source --help`, can tell
/// "not supported here" from "failed".  77 is the status test harnesses use
/// for "skipped".
pub const EXIT_UNAVAILABLE: i32 = 77;

/// Hide subcommands whose backing functionality is missing on the running
/// host from `--help`.  Invoking one is rejected before parsing by
/// [`host_feature_gate_rejects`].
///
/// `bootconfig_extra` is whether the host ostree supports `bootconfig-extra`,
/// which `loader-entries` requires; see
/// [`crate::loader_entries::ostree_supports_bootconfig_extra`].
fn apply_host_feature_gates(cmd: clap::Command, bootconfig_extra: bool) -> clap::Command {
    if bootconfig_extra {
        return cmd;
    }
    cmd.mut_subcommand(LOADER_ENTRIES_SUBCOMMAND, |c| c.hide(true))
}

/// Whether `args` (argv, including argv0) invoke a subcommand that
/// [`apply_host_feature_gates`] made unavailable.  The top-level command has
/// no options that take a value, so the first non-option argument is the
/// subcommand name.
fn host_feature_gate_rejects(args: &[OsString], bootconfig_extra: bool) -> bool {
    if bootconfig_extra {
        return false;
    }
    args.iter()
        .skip(1)
        .find(|a| !a.to_string_lossy().starts_with('-'))
        .is_some_and(|a| a.as_os_str() == OsStr::new(LOADER_ENTRIES_SUBCOMMAND))
}

/// Internal (non-generic/monomorphized) primary CLI entrypoint
async fn run_from_opt(opt: Opt) -> Result<CliExitStatus> {
    let root = &Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
    let result = match opt {
        Opt::Upgrade(opts) => {
            let storage = &get_storage().await?;
            match storage.kind()? {
                BootedStorageKind::Ostree(booted_ostree) => {
                    if opts.uki_addon_opts.scoped.is_some() || opts.uki_addon_opts.global.is_some()
                    {
                        anyhow::bail!("UKI Addon options are only supported for composefs backend");
                    }

                    upgrade(opts, storage, &booted_ostree).await
                }
                BootedStorageKind::Composefs(booted_cfs) => {
                    upgrade_composefs(opts, storage, &booted_cfs).await
                }
            }
        }
        Opt::Switch(opts) => switch(opts).await,
        Opt::Rollback(opts) => {
            rollback(&opts).await?;
            if opts.apply {
                crate::reboot::reboot()?;
            }
            Ok(())
        }
        Opt::Edit(opts) => edit(opts).await,
        Opt::UsrOverlay(opts) => {
            use crate::store::Environment;
            let env = Environment::detect()?;
            let access_mode = if opts.read_only {
                FilesystemOverlayAccessMode::ReadOnly
            } else {
                FilesystemOverlayAccessMode::ReadWrite
            };
            match env {
                Environment::OstreeBooted => usroverlay(access_mode).await,
                Environment::ComposefsBooted(_) => composefs_usr_overlay(access_mode),
                _ => anyhow::bail!("usroverlay only applies on booted hosts"),
            }
        }
        Opt::Container(opts) => match opts {
            ContainerOpts::Inspect {
                rootfs,
                json,
                format,
            } => crate::status::container_inspect(&rootfs, json, format),
            ContainerOpts::Lint {
                rootfs,
                fatal_warnings,
                list,
                skip,
                no_truncate,
            } => {
                if list {
                    return lints::lint_list(std::io::stdout().lock())
                        .map(|()| CliExitStatus::Success);
                }
                let warnings = if fatal_warnings {
                    lints::WarningDisposition::FatalWarnings
                } else {
                    lints::WarningDisposition::AllowWarnings
                };
                let root_type = if rootfs == "/" {
                    lints::RootType::Running
                } else {
                    lints::RootType::Alternative
                };

                let root = &Dir::open_ambient_dir(rootfs, cap_std::ambient_authority())?;
                let skip = skip.iter().map(|s| s.as_str());
                lints::lint(
                    root,
                    warnings,
                    root_type,
                    skip,
                    std::io::stdout().lock(),
                    no_truncate,
                )?;
                Ok(())
            }
            ContainerOpts::SplitKernelAndRootfs { rootfs, output } => {
                let root = Dir::open_ambient_dir(&rootfs, ambient_authority())
                    .with_context(|| format!("Opening {rootfs}"))?;
                std::fs::create_dir_all(&output).with_context(|| format!("Creating {output}"))?;
                let output = Dir::open_ambient_dir(&output, ambient_authority())
                    .with_context(|| format!("Opening {output}"))?;
                crate::kernel::split_kernel(&root, &output)?;
                Ok(())
            }
            ContainerOpts::ComputeComposefsDigest {
                path,
                write_dumpfile_to,
                erofs_version,
            } => {
                let digest = compute_composefs_digest(
                    &path,
                    erofs_version.into(),
                    write_dumpfile_to.as_deref(),
                )
                .await?;
                println!("{digest}");
                Ok(())
            }
            ContainerOpts::ComputeComposefsDigestFromStorage {
                write_dumpfile_to,
                erofs_version,
                image,
            } => {
                let (_td_guard, repo) = new_temp_composefs_repo(erofs_version.into())?;

                let mut proxycfg = crate::deploy::new_proxy_config();

                let image = if let Some(image) = image {
                    image
                } else {
                    let host_container_store = Utf8Path::new("/run/host-container-storage");
                    // If no image is provided, assume that we're running in a container in privileged mode
                    // with access to the container storage.
                    let container_info = crate::containerenv::get_container_execution_info(&root)?;
                    let iid = container_info.imageid;
                    tracing::debug!("Computing digest of {iid}");

                    if !host_container_store.try_exists()? {
                        anyhow::bail!(
                            "Must be readonly mount of host container store: {host_container_store}"
                        );
                    }
                    // And ensure we're finding the image in the host storage
                    let mut cmd = Command::new(bootc_utils::skopeo_bin());
                    set_additional_image_store(&mut cmd, "/run/host-container-storage");
                    proxycfg.skopeo_cmd = Some(cmd);
                    iid
                };

                let imgref = format!("containers-storage:{image}");
                let host_store = std::path::Path::new("/run/host-container-storage");
                let opts = composefs_oci::PullOptions {
                    img_proxy_config: Some(proxycfg),
                    additional_image_stores: &[host_store],
                    ..Default::default()
                };
                let pull_result = composefs_oci::pull(&repo, &imgref, None, opts)
                    .await
                    .context("Pulling image")?;
                let mut fs = composefs_oci::image::create_filesystem(
                    &repo,
                    &pull_result.config_digest,
                    Some(&pull_result.config_verity),
                    &composefs_oci::OciTransformOptions::default(),
                )
                .context("Populating fs")?;
                fs.transform_for_boot(&repo).context("Preparing for boot")?;
                let id = fs.compute_image_id(repo.erofs_version());
                println!("{}", id.to_hex());

                if let Some(path) = write_dumpfile_to.as_deref() {
                    let mut w = File::create(path)
                        .with_context(|| format!("Opening {path}"))
                        .map(BufWriter::new)?;
                    dumpfile::write_dumpfile(&mut w, &fs).context("Writing dumpfile")?;
                }

                Ok(())
            }
            ContainerOpts::Ukify {
                rootfs,
                kargs,
                allow_missing_verity,
                erofs_version,
                write_dumpfile_to,
                kernel_dir,
                args,
            } => {
                crate::ukify::build_ukify(
                    &rootfs,
                    &kargs,
                    &args,
                    kernel_dir.as_deref(),
                    allow_missing_verity,
                    erofs_version,
                    write_dumpfile_to.as_deref(),
                )
                .await
            }
            ContainerOpts::Aboot {
                rootfs,
                allow_missing_verity,
                erofs_version,
                write_dumpfile_to,
                kernel_dir,
                out,
            } => {
                crate::aboot::build_aboot(
                    &rootfs,
                    kernel_dir.as_deref(),
                    out.as_deref(),
                    allow_missing_verity,
                    erofs_version,
                    write_dumpfile_to.as_deref(),
                )
                .await
            }
            ContainerOpts::Export {
                format,
                target,
                output,
                kernel_in_boot,
                selinux,
            } => {
                crate::container_export::export(
                    &format,
                    &target,
                    output.as_deref(),
                    kernel_in_boot,
                    &selinux,
                )
                .await
            }
        },
        Opt::Completion { shell } => {
            use clap_complete::aot::generate;

            let mut cmd = Opt::command();
            let mut stdout = std::io::stdout();
            let bin_name = "bootc";
            generate(shell, &mut cmd, bin_name, &mut stdout);
            Ok(())
        }
        Opt::Image(opts) => match opts {
            ImageOpts::List {
                list_type,
                list_format,
            } => crate::image::list_entrypoint(list_type, list_format).await,

            ImageOpts::CopyToStorage { source, target } => {
                // We get "host" here to avoid deadlock in the ostree path
                let host = get_host().await?;

                let storage = get_storage().await?;

                match storage.kind()? {
                    BootedStorageKind::Ostree(..) => {
                        crate::image::push_entrypoint(
                            &storage,
                            &host,
                            source.as_deref(),
                            target.as_deref(),
                        )
                        .await
                    }
                    BootedStorageKind::Composefs(booted) => {
                        bootc_composefs::export::export_repo_to_image(
                            &storage,
                            &booted,
                            source.as_deref(),
                            target.as_deref(),
                        )
                        .await
                    }
                }
            }
            ImageOpts::SetUnified => crate::image::set_unified_entrypoint().await,
            ImageOpts::PullFromDefaultStorage { image } => {
                let storage = get_storage().await?;
                storage
                    .get_ensure_imgstore()?
                    .pull_from_host_storage(&image)
                    .await
            }
            ImageOpts::Cmd(opt) => {
                let storage = get_storage().await?;
                let imgstore = storage.get_ensure_imgstore()?;
                match opt {
                    ImageCmdOpts::List { args } => {
                        crate::image::imgcmd_entrypoint(imgstore, "list", &args).await
                    }
                    ImageCmdOpts::Build { args } => {
                        crate::image::imgcmd_entrypoint(imgstore, "build", &args).await
                    }
                    ImageCmdOpts::Pull { images } => {
                        for image in &images {
                            imgstore.pull_with_progress(image).await?;
                        }
                        Ok(())
                    }
                    ImageCmdOpts::Push { args } => {
                        crate::image::imgcmd_entrypoint(imgstore, "push", &args).await
                    }
                }
            }
        },
        Opt::Install(opts) => match opts {
            InstallOpts::Mount(opts) => crate::mount::mount(opts).await,
            #[cfg(feature = "install-to-disk")]
            InstallOpts::ToDisk(opts) => crate::install::install_to_disk(opts).await,
            InstallOpts::ToFilesystem(opts) => {
                crate::install::install_to_filesystem(opts, false, crate::install::Cleanup::Skip)
                    .await
            }
            InstallOpts::ToExistingRoot(opts) => {
                crate::install::install_to_existing_root(opts).await
            }
            InstallOpts::Reset(opts) => crate::install::install_reset(opts).await,
            InstallOpts::PrintConfiguration(opts) => crate::install::print_configuration(opts),
            InstallOpts::EnsureCompletion {} => {
                let rootfs = &Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
                crate::install::completion::run_from_anaconda(rootfs).await
            }
            InstallOpts::Finalize { root_path } => {
                crate::install::install_finalize(&root_path).await
            }
        },
        Opt::LoaderEntries(opts) => match opts {
            LoaderEntriesOpts::SetOptionsForSource(opts) => {
                let storage = get_storage().await?;
                let sysroot = storage.get_ostree()?;
                crate::loader_entries::set_options_for_source_staged(
                    sysroot,
                    &opts.source,
                    opts.options.as_deref(),
                )?;
                Ok(())
            }
        },
        Opt::ExecInHostMountNamespace { args } => {
            crate::install::exec_in_host_mountns(args.as_slice())
        }
        Opt::Status(opts) => super::status::status(opts).await,
        Opt::Internals(opts) => match opts {
            InternalsOpts::ComposefsAbootReconcile => {
                let storage = get_storage().await?;
                let digest = match storage.kind()? {
                    BootedStorageKind::Composefs(booted) => booted.cmdline.digest.to_string(),
                    BootedStorageKind::Ostree(_) => {
                        anyhow::bail!("Aboot reconciliation requires the composefs backend")
                    }
                };
                ensure!(
                    crate::bootc_composefs::state::read_boot_type(&storage.physical_root, &digest)?
                        == Some(crate::bootc_composefs::boot::BootType::Aboot),
                    "Aboot reconciliation requires an aboot deployment"
                );
                let mut state = aboot::AbootState::open(&storage.physical_root)?;
                if state.reconcile(&digest)? {
                    start_finalize_stated_svc()?;
                }
                Ok(())
            }
            InternalsOpts::SystemdGenerator {
                normal_dir,
                early_dir: _,
                late_dir: _,
            } => {
                let unit_dir = &Dir::open_ambient_dir(normal_dir, cap_std::ambient_authority())?;
                crate::generator::generator(root, unit_dir)
            }
            InternalsOpts::OstreeExt { args } => {
                ostree_ext::cli::run_from_iter(["ostree-ext".into()].into_iter().chain(args)).await
            }
            InternalsOpts::OstreeContainer { args } => {
                ostree_ext::cli::run_from_iter(
                    ["ostree-ext".into(), "container".into()]
                        .into_iter()
                        .chain(args),
                )
                .await
            }
            InternalsOpts::TestComposefs => {
                // This is a stub to be replaced
                let storage = get_storage().await?;
                let cfs = storage.get_ensure_composefs()?;
                let testdata = b"some test data";
                let testdata_digest = hex::encode(openssl::sha::sha256(testdata));
                let mut w = cfs.create_stream(0)?;
                w.write_inline(testdata);
                let object = cfs
                    .write_stream(w, &testdata_digest, Some("testobject"))?
                    .to_hex();
                assert_eq!(
                    object,
                    "84245c6936db9939dda9c1fbeafdcbd2b49f7605354c88d4f016c4d941551f45bad0fbcdbee12ba8adfe4fb63541de57ac02729edbacdb556325e342b89d340d"
                );
                Ok(())
            }
            // We don't depend on fsverity-utils today, so re-expose some helpful CLI tools.
            InternalsOpts::Fsverity(args) => match args {
                FsverityOpts::Measure { path } => {
                    let fd =
                        std::fs::File::open(&path).with_context(|| format!("Reading {path}"))?;
                    let digest: fsverity::Sha256HashValue = fsverity::measure_verity(&fd)?;
                    let digest = digest.to_hex();
                    println!("{digest}");
                    Ok(())
                }
                FsverityOpts::Enable { path } => {
                    let fd =
                        std::fs::File::open(&path).with_context(|| format!("Reading {path}"))?;
                    fsverity::enable_verity_raw::<fsverity::Sha256HashValue>(&fd)?;
                    Ok(())
                }
            },
            #[cfg(feature = "selinux")]
            InternalsOpts::Selinux(SelinuxOpts::IsUnlabeled { path }) => {
                ensure!(crate::lsm::selinux_enabled(), "SELinux is not enabled");
                let path = path
                    .strip_prefix("/")
                    .expect("absolute paths have a root prefix");
                match is_unlabeled_exit_status(
                    crate::lsm::has_security_selinux(&root, path)?,
                    path,
                )? {
                    CliExitStatus::Success => Ok(()),
                    CliExitStatus::PredicateFalse => {
                        return Ok(CliExitStatus::PredicateFalse);
                    }
                }
            }
            InternalsOpts::Cfs { args } => composefs_ctl::run_from_iter(args.iter()).await,
            InternalsOpts::Reboot => crate::reboot::reboot(),
            InternalsOpts::Fsck => {
                let storage = &get_storage().await?;
                crate::fsck::fsck(&storage, std::io::stdout().lock()).await?;
                Ok(())
            }
            InternalsOpts::FixupEtcFstab => crate::deploy::fixup_etc_fstab(&root),
            InternalsOpts::SysusersSync => crate::sysusers_cleanup::run(&root),
            InternalsOpts::PrintJsonSchema { of } => {
                let schema = match of {
                    SchemaType::Host => schema_for!(crate::spec::Host),
                    SchemaType::Progress => schema_for!(crate::progress_jsonl::Event),
                };
                let mut stdout = std::io::stdout().lock();
                serde_json::to_writer_pretty(&mut stdout, &schema)?;
                Ok(())
            }
            InternalsOpts::Cleanup => {
                let storage = get_storage().await?;
                crate::deploy::cleanup(&storage).await
            }
            InternalsOpts::Relabel { as_path, path } => {
                let root = &Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
                let path = path.strip_prefix("/")?;
                let sepolicy =
                    &ostree::SePolicy::new(&gio::File::for_path("/"), gio::Cancellable::NONE)?;
                crate::lsm::relabel_recurse(root, path, as_path.as_deref(), sepolicy)?;
                Ok(())
            }
            InternalsOpts::RelabelOverlayMountpoints => {
                crate::generator::relabel_overlay_mountpoints()
            }
            InternalsOpts::BootcInstallCompletion { sysroot, stateroot } => {
                let rootfs = &Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
                crate::install::completion::run_from_ostree(rootfs, &sysroot, &stateroot).await
            }
            InternalsOpts::LoopbackCleanupHelper { device } => {
                crate::blockdev::run_loopback_cleanup_helper(&device).await
            }
            InternalsOpts::AllocateCleanupLoopback { file_path: _ } => {
                // Create a temporary file for testing
                let temp_file =
                    tempfile::NamedTempFile::new().context("Failed to create temporary file")?;
                let temp_path = temp_file.path();

                // Create a loopback device
                let loopback = crate::blockdev::LoopbackDevice::new(temp_path)
                    .context("Failed to create loopback device")?;

                println!("Created loopback device: {}", loopback.path());

                // Close the device to test cleanup
                loopback
                    .close()
                    .context("Failed to close loopback device")?;

                println!("Successfully closed loopback device");
                Ok(())
            }
            #[cfg(feature = "rhsm")]
            InternalsOpts::PublishRhsmFacts => crate::rhsm::publish_facts(&root).await,
            #[cfg(feature = "docgen")]
            InternalsOpts::DumpCliJson => {
                use clap::CommandFactory;
                let cmd = Opt::command();
                let json = crate::cli_json::dump_cli_json(&cmd)?;
                println!("{}", json);
                Ok(())
            }
            InternalsOpts::DirDiff {
                pristine_etc,
                current_etc,
                new_etc,
                merge,
            } => {
                let pristine_etc =
                    Dir::open_ambient_dir(pristine_etc, cap_std::ambient_authority())?;
                let current_etc = Dir::open_ambient_dir(current_etc, cap_std::ambient_authority())?;
                let new_etc = Dir::open_ambient_dir(new_etc, cap_std::ambient_authority())?;

                let (p, c, n) =
                    etc_merge::traverse_etc(&pristine_etc, &current_etc, Some(&new_etc))?;

                let n = n
                    .as_ref()
                    .ok_or_else(|| anyhow::anyhow!("Failed to get new directory tree"))?;

                let diff = compute_diff(&p, &c, &n)?;
                print_diff(&diff, &mut std::io::stdout());

                if merge {
                    etc_merge::merge(&current_etc, &c, &new_etc, &n, &diff)?;
                }

                Ok(())
            }
            InternalsOpts::PrepSoftReboot {
                deployment,
                reboot,
                reset,
            } => {
                let storage = &get_storage().await?;

                match storage.kind()? {
                    BootedStorageKind::Ostree(..) => {
                        // TODO: Call ostree implementation?
                        anyhow::bail!("soft-reboot only implemented for composefs")
                    }

                    BootedStorageKind::Composefs(booted_cfs) => {
                        if reset {
                            return reset_soft_reboot().map(|()| CliExitStatus::Success);
                        }

                        prepare_soft_reboot_composefs(
                            &storage,
                            &booted_cfs,
                            deployment.as_deref(),
                            SoftRebootMode::Required,
                            reboot,
                        )
                        .await
                    }
                }
            }
            InternalsOpts::ComposefsGC {
                dry_run,
                assert_no_op,
                prune_repo,
            } => {
                let storage = &get_storage().await?;

                match storage.kind()? {
                    BootedStorageKind::Ostree(..) => {
                        anyhow::bail!("composefs-gc only works for composefs backend");
                    }

                    BootedStorageKind::Composefs(booted_cfs) => {
                        let dry_run = dry_run || assert_no_op;
                        let gc_result = composefs_gc(
                            storage,
                            &booted_cfs,
                            GCOpts {
                                dry_run,
                                prune_repo,
                            },
                        )
                        .await?;

                        if dry_run {
                            println!("Dry run (no files deleted)");
                        }

                        println!(
                            "Objects: {} removed ({} bytes)",
                            gc_result.objects_removed, gc_result.objects_bytes
                        );

                        if gc_result.images_pruned > 0 || gc_result.streams_pruned > 0 {
                            println!(
                                "Pruned symlinks: {} images, {} streams",
                                gc_result.images_pruned, gc_result.streams_pruned
                            );
                        }

                        if assert_no_op {
                            let is_noop = gc_result.objects_removed == 0
                                && gc_result.images_pruned == 0
                                && gc_result.streams_pruned == 0;
                            if !is_noop {
                                anyhow::bail!(
                                    "--assert-no-op: GC would remove {} object(s), {} image symlink(s), {} stream symlink(s) (issue #1808)",
                                    gc_result.objects_removed,
                                    gc_result.images_pruned,
                                    gc_result.streams_pruned,
                                );
                            }
                        }

                        Ok(())
                    }
                }
            }
            InternalsOpts::Blockdev(opts) => {
                let dev = match opts {
                    BlockdevOpts::Ls { device } => crate::blockdev::list_dev(&device)?,
                    BlockdevOpts::LsFilesystem { path } => {
                        let dir = Dir::open_ambient_dir(&path, cap_std::ambient_authority())?;
                        crate::blockdev::list_dev_by_dir(&dir)?
                    }
                };
                serde_json::to_writer_pretty(std::io::stdout().lock(), &dev)?;
                println!();
                Ok(())
            }
            InternalsOpts::Uki(uki_opts) => match uki_opts {
                UkiSubcommands::Extract { path, output_path } => {
                    let mut uki_file =
                        std::fs::File::open(&path).with_context(|| format!("Opening {path}"))?;

                    let uname =
                        composefs_boot::uki::get_text_section_buffered(&mut uki_file, ".uname")
                            .context("Getting uname")?;

                    std::fs::create_dir_all(&output_path).context("Creating output directory")?;

                    let output_dir = Dir::open_ambient_dir(&output_path, ambient_authority())
                        .context("Opening output dir")?;
                    output_dir.create_dir(&uname)?;

                    let output_dir = output_dir.open_dir(&uname)?;

                    for (section_name, file_name) in
                        [(".linux", "vmlinuz"), (".initrd", "initramfs.img")]
                    {
                        uki_file
                            .seek(SeekFrom::Start(0))
                            .context("Seeking to start")?;
                        let section =
                            composefs_boot::uki::get_section_buffered(&mut uki_file, section_name)
                                .with_context(|| format!("Getting {section_name} section"))?;
                        output_dir
                            .write(file_name, section)
                            .with_context(|| format!("Writing {file_name}"))?;
                    }

                    Ok(())
                }
            },
        },
        Opt::State(opts) => match opts {
            StateOpts::WipeOstree => {
                let sysroot = ostree::Sysroot::new_default();
                sysroot.load(gio::Cancellable::NONE)?;
                crate::deploy::wipe_ostree(sysroot).await?;
                Ok(())
            }
        },

        Opt::ComposefsFinalizeStaged(opts) => {
            if opts.hold {
                // Must happen before loading storage: the hold has to stay in
                // the root mount namespace, and must not depend on anything
                // but /boot.
                crate::bootc_composefs::finalize::hold_boot()
            } else {
                let storage = &get_storage().await?;
                match storage.kind()? {
                    BootedStorageKind::Ostree(_) => {
                        anyhow::bail!(
                            "ComposefsFinalizeStaged is only supported for composefs backend"
                        )
                    }
                    BootedStorageKind::Composefs(booted_cfs) => {
                        composefs_backend_finalize(storage, &booted_cfs).await
                    }
                }
            }
        }

        Opt::ConfigDiff => {
            let storage = &get_storage().await?;
            match storage.kind()? {
                BootedStorageKind::Ostree(_) => {
                    anyhow::bail!("ConfigDiff is only supported for composefs backend")
                }
                BootedStorageKind::Composefs(booted_cfs) => {
                    let diff = get_etc_diff(storage, &booted_cfs, None).await?;
                    print_diff(&diff, &mut std::io::stdout());
                    Ok(())
                }
            }
        }

        Opt::DeleteDeployment { depl_id } => {
            let storage = &get_storage().await?;
            match storage.kind()? {
                BootedStorageKind::Ostree(_) => {
                    anyhow::bail!("DeleteDeployment is only supported for composefs backend")
                }
                BootedStorageKind::Composefs(booted_cfs) => {
                    delete_composefs_deployment(&depl_id, storage, &booted_cfs).await
                }
            }
        }
        Opt::UkiAddon(opts) => {
            let storage = &get_storage().await?;
            match storage.kind()? {
                BootedStorageKind::Ostree(_) => {
                    anyhow::bail!("UKI Addons are only supported for Composefs Backend")
                }
                BootedStorageKind::Composefs(booted_cfs) => {
                    let status = get_composefs_status(storage, &booted_cfs).await?;

                    if status.require_composefs_booted()?.boot_type != BootType::Uki {
                        anyhow::bail!(
                            "Cannot perform UKI Addon operations on systems not booted via UKI"
                        );
                    }

                    handle_addon_cli_cmd(storage, &booted_cfs, &status, &opts)
                }
            }
        }
    };
    result.map(|()| CliExitStatus::Success)
}

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

    #[test]
    fn test_callname() {
        use std::os::unix::ffi::OsStrExt;

        // Cases that change
        let mapped_cases = [
            ("", "bootc"),
            ("/foo/bar", "bar"),
            ("/foo/bar/", "bar"),
            ("foo/bar", "bar"),
            ("../foo/bar", "bar"),
            ("usr/bin/ostree-container", "ostree-container"),
        ];
        for (input, output) in mapped_cases {
            assert_eq!(
                output,
                callname_from_argv0(OsStr::new(input)),
                "Handling mapped case {input}"
            );
        }

        // Invalid UTF-8
        assert_eq!("bootc", callname_from_argv0(OsStr::from_bytes(b"foo\x80")));

        // Cases that are identical
        let ident_cases = ["foo", "bootc"];
        for case in ident_cases {
            assert_eq!(
                case,
                callname_from_argv0(OsStr::new(case)),
                "Handling ident case {case}"
            );
        }
    }

    #[test]
    fn test_parse_from_delta() {
        let o =
            Opt::try_parse_from(["bootc", "switch", "--from-delta", "/d", "quay.io/e/x"]).unwrap();
        match o {
            Opt::Switch(o) => assert_eq!(o.from_delta.as_deref().unwrap(), "/d"),
            o => panic!("Expected switch opts, not {o:?}"),
        }

        // A delta carries its own image content; anything that says where else
        // to get that content, or that asks for a check we can't perform, must
        // be rejected rather than silently ignored.
        let conflicting: &[&[&str]] = &[
            &["switch", "--transport=oci-archive", "quay.io/e/x"],
            &["switch", "--mutate-in-place", "quay.io/e/x"],
            &["switch", "--experimental-unified-storage", "quay.io/e/x"],
            &["switch", "--enforce-container-sigpolicy", "quay.io/e/x"],
            &["upgrade", "--check"],
            &["upgrade", "--tag=other"],
        ];
        for args in conflicting {
            let (subcommand, rest) = args.split_first().unwrap();
            let mut full = vec!["bootc", subcommand, "--from-delta", "/d"];
            full.extend_from_slice(rest);
            let err = Opt::try_parse_from(&full)
                .err()
                .unwrap_or_else(|| panic!("{args:?}: expected a conflict"));
            assert_eq!(
                err.kind(),
                clap::error::ErrorKind::ArgumentConflict,
                "{args:?}: {err}"
            );
        }
    }

    #[test]
    fn test_parse_install_args() {
        // Verify we still process the legacy --target-no-signature-verification
        let o = Opt::try_parse_from([
            "bootc",
            "install",
            "to-filesystem",
            "--target-no-signature-verification",
            "/target",
        ])
        .unwrap();
        let o = match o {
            Opt::Install(InstallOpts::ToFilesystem(fsopts)) => fsopts,
            o => panic!("Expected filesystem opts, not {o:?}"),
        };
        assert!(o.target_opts.target_no_signature_verification);
        assert_eq!(o.filesystem_opts.root_path.as_str(), "/target");
        // Ensure we default to old bound images behavior
        assert_eq!(
            o.config_opts.bound_images,
            crate::install::BoundImagesOpt::Stored
        );
    }

    #[test]
    fn test_parse_boot_artifact_erofs_version_args() {
        for command in ["ukify", "aboot"] {
            for (arg, expected) in [
                (None, None),
                (Some("v1"), Some(BootArtifactErofsVersionArg::V1)),
                (Some("v1-only"), Some(BootArtifactErofsVersionArg::V1Only)),
                (Some("v2"), Some(BootArtifactErofsVersionArg::V2)),
            ] {
                let mut args = vec!["bootc", "container", command];
                if let Some(arg) = arg {
                    args.extend(["--erofs-version", arg]);
                }
                let opt = Opt::try_parse_from(args).unwrap();
                let erofs_version = match opt {
                    Opt::Container(ContainerOpts::Ukify { erofs_version, .. })
                    | Opt::Container(ContainerOpts::Aboot { erofs_version, .. }) => erofs_version,
                    _ => panic!("expected container boot artifact options"),
                };
                assert_eq!(erofs_version, expected, "{command} {arg:?}");
            }
        }
    }

    #[test]
    fn test_parse_opts() {
        assert!(matches!(
            Opt::parse_including_static(["bootc", "status"]),
            Opt::Status(StatusOpts {
                json: false,
                format: None,
                format_version: None,
                booted: false,
                verbose: false
            })
        ));
        assert!(matches!(
            Opt::parse_including_static(["bootc", "status", "--format-version=0"]),
            Opt::Status(StatusOpts {
                format_version: Some(0),
                ..
            })
        ));

        // Test verbose long form
        assert!(matches!(
            Opt::parse_including_static(["bootc", "status", "--verbose"]),
            Opt::Status(StatusOpts { verbose: true, .. })
        ));

        // Test verbose short form
        assert!(matches!(
            Opt::parse_including_static(["bootc", "status", "-v"]),
            Opt::Status(StatusOpts { verbose: true, .. })
        ));

        for (args, hold) in [
            (&["bootc", "composefs-finalize-staged"][..], false),
            (&["bootc", "composefs-finalize-staged", "--hold"][..], true),
        ] {
            assert_eq!(
                Opt::parse_including_static(args),
                Opt::ComposefsFinalizeStaged(ComposefsFinalizeStagedOpts { hold }),
                "{args:?}"
            );
        }

        assert!(matches!(
            Opt::parse_including_static([
                "bootc",
                "container",
                "aboot",
                "--out",
                "/out",
            ]),
            Opt::Container(ContainerOpts::Aboot { out, .. })
                if out.as_deref() == Some(Utf8Path::new("/out"))
        ));
    }

    #[test]
    #[cfg(feature = "selinux")]
    fn test_parse_selinux_is_unlabeled() {
        let opt = Opt::try_parse_from([
            "bootc",
            "internals",
            "selinux",
            "is-unlabeled",
            "/var/lib/probe",
        ])
        .unwrap();
        assert!(matches!(
            opt,
            Opt::Internals(InternalsOpts::Selinux(SelinuxOpts::IsUnlabeled { path }))
                if path == "/var/lib/probe"
        ));
        assert!(
            Opt::try_parse_from(["bootc", "internals", "selinux", "is-unlabeled", "relative",])
                .is_err()
        );
    }

    #[test]
    #[cfg(feature = "selinux")]
    fn test_is_unlabeled_exit_status() {
        let path = Utf8Path::new("probe");
        let cases = [
            (
                crate::lsm::SELinuxLabelState::Unlabeled,
                CliExitStatus::Success,
            ),
            (
                crate::lsm::SELinuxLabelState::Labeled,
                CliExitStatus::PredicateFalse,
            ),
        ];
        for (state, expected) in cases {
            assert_eq!(is_unlabeled_exit_status(state, path).unwrap(), expected);
        }
        assert!(
            is_unlabeled_exit_status(crate::lsm::SELinuxLabelState::Unsupported, path)
                .unwrap_err()
                .to_string()
                .contains("unsupported")
        );
    }

    #[test]
    fn test_parse_generator() {
        assert!(matches!(
            Opt::parse_including_static([
                "/usr/lib/systemd/system/bootc-systemd-generator",
                "/run/systemd/system"
            ]),
            Opt::Internals(InternalsOpts::SystemdGenerator { normal_dir, .. }) if normal_dir == "/run/systemd/system"
        ));
    }

    #[test]
    fn test_parse_ostree_ext() {
        assert!(matches!(
            Opt::parse_including_static(["bootc", "internals", "ostree-container"]),
            Opt::Internals(InternalsOpts::OstreeContainer { .. })
        ));

        fn peel(o: Opt) -> Vec<OsString> {
            match o {
                Opt::Internals(InternalsOpts::OstreeExt { args }) => args,
                o => panic!("unexpected {o:?}"),
            }
        }
        let args = peel(Opt::parse_including_static([
            "/usr/libexec/libostree/ext/ostree-ima-sign",
            "ima-sign",
            "--repo=foo",
            "foo",
            "bar",
            "baz",
        ]));
        assert_eq!(
            args.as_slice(),
            ["ima-sign", "--repo=foo", "foo", "bar", "baz"]
        );

        let args = peel(Opt::parse_including_static([
            "/usr/libexec/libostree/ext/ostree-container",
            "container",
            "image",
            "pull",
        ]));
        assert_eq!(args.as_slice(), ["container", "image", "pull"]);
    }

    #[test]
    fn test_parse_upgrade_options() {
        // Test upgrade with --tag
        let o = Opt::try_parse_from(["bootc", "upgrade", "--tag", "v1.1"]).unwrap();
        match o {
            Opt::Upgrade(opts) => {
                assert_eq!(opts.tag, Some("v1.1".to_string()));
            }
            _ => panic!("Expected Upgrade variant"),
        }

        // Test that --tag works with --check (should compose naturally)
        let o = Opt::try_parse_from(["bootc", "upgrade", "--tag", "v1.1", "--check"]).unwrap();
        match o {
            Opt::Upgrade(opts) => {
                assert_eq!(opts.tag, Some("v1.1".to_string()));
                assert!(opts.check);
            }
            _ => panic!("Expected Upgrade variant"),
        }
    }

    #[test]
    fn test_image_reference_with_tag() {
        // Test basic tag replacement for registry transport
        let current = ImageReference {
            image: "quay.io/example/myapp:v1.0".to_string(),
            transport: "registry".to_string(),
            signature: None,
        };
        let result = current.with_tag("v1.1").unwrap();
        assert_eq!(result.image, "quay.io/example/myapp:v1.1");
        assert_eq!(result.transport, "registry");

        // Test tag replacement with digest (digest should be stripped for registry)
        let current_with_digest = ImageReference {
            image: "quay.io/example/myapp:v1.0@sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890".to_string(),
            transport: "registry".to_string(),
            signature: None,
        };
        let result = current_with_digest.with_tag("v2.0").unwrap();
        assert_eq!(result.image, "quay.io/example/myapp:v2.0");

        // Test that non-registry transport works (containers-storage)
        let containers_storage = ImageReference {
            image: "localhost/myapp:v1.0".to_string(),
            transport: "containers-storage".to_string(),
            signature: None,
        };
        let result = containers_storage.with_tag("v1.1").unwrap();
        assert_eq!(result.image, "localhost/myapp:v1.1");
        assert_eq!(result.transport, "containers-storage");

        // Test digest stripping for non-registry transport
        let containers_storage_with_digest = ImageReference {
            image:
                "localhost/myapp:v1.0@sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
                    .to_string(),
            transport: "containers-storage".to_string(),
            signature: None,
        };
        let result = containers_storage_with_digest.with_tag("v2.0").unwrap();
        assert_eq!(result.image, "localhost/myapp:v2.0");
        assert_eq!(result.transport, "containers-storage");

        // Test image without tag (edge case)
        let no_tag = ImageReference {
            image: "localhost/myapp".to_string(),
            transport: "containers-storage".to_string(),
            signature: None,
        };
        let result = no_tag.with_tag("v1.0").unwrap();
        assert_eq!(result.image, "localhost/myapp:v1.0");
        assert_eq!(result.transport, "containers-storage");
    }

    #[test]
    fn test_generate_completion_scripts_contain_commands() {
        use clap_complete::aot::{Shell, generate};

        // For each supported shell, generate the completion script and
        // ensure obvious subcommands appear in the output. This mirrors
        // the style of completion checks used in other projects (e.g.
        // podman) where the generated script is examined for expected
        // tokens.

        // `completion` is intentionally hidden from --help / suggestions;
        // ensure other visible subcommands are present instead.
        let want = ["install", "upgrade"];

        for shell in [Shell::Bash, Shell::Zsh, Shell::Fish] {
            let mut cmd = Opt::command();
            let mut buf = Vec::new();
            generate(shell, &mut cmd, "bootc", &mut buf);
            let s = String::from_utf8(buf).expect("completion should be utf8");
            for w in &want {
                assert!(s.contains(w), "{shell:?} completion missing {w}");
            }
        }
    }

    #[test]
    fn test_host_feature_gates() {
        // The full CLI (used for docs and completions) always advertises the command.
        let full = Opt::command();
        let sub = full
            .find_subcommand(LOADER_ENTRIES_SUBCOMMAND)
            .expect("loader-entries subcommand");
        assert!(!sub.is_hide_set());

        let invocation = [
            "bootc",
            LOADER_ENTRIES_SUBCOMMAND,
            "set-options-for-source",
            "--source",
            "tuned",
        ];

        // (host ostree supports bootconfig-extra, expect subcommand available)
        for (supported, expect_available) in [(true, true), (false, false)] {
            let cmd = apply_host_feature_gates(Opt::command(), supported);
            let visible: Vec<_> = cmd
                .get_subcommands()
                .filter(|c| !c.is_hide_set())
                .map(clap::Command::get_name)
                .collect();
            assert_eq!(
                visible.contains(&LOADER_ENTRIES_SUBCOMMAND),
                expect_available,
                "bootconfig_extra={supported}: {visible:?}"
            );

            // Any invocation of the gated subcommand, including the `--help`
            // probe TuneD uses, is rejected before parsing on unsupported
            // hosts (with EXIT_UNAVAILABLE); everything else is left to clap.
            let argv = |a: &[&str]| a.iter().map(OsString::from).collect::<Vec<_>>();
            for gated in [
                argv(&["bootc", LOADER_ENTRIES_SUBCOMMAND, "--help"]),
                argv(&[
                    "bootc",
                    LOADER_ENTRIES_SUBCOMMAND,
                    "set-options-for-source",
                    "--help",
                ]),
                argv(&invocation),
            ] {
                assert_eq!(
                    host_feature_gate_rejects(&gated, supported),
                    !expect_available,
                    "bootconfig_extra={supported}: {gated:?}"
                );
            }
            for other in [
                argv(&["bootc", "status"]),
                argv(&["bootc", "--version"]),
                argv(&["bootc"]),
            ] {
                assert!(!host_feature_gate_rejects(&other, supported), "{other:?}");
            }

            // With the gate open the invocation parses normally.
            if expect_available {
                let opt = <Opt as clap::FromArgMatches>::from_arg_matches(
                    &cmd.clone().try_get_matches_from(invocation).unwrap(),
                )
                .unwrap();
                assert!(matches!(opt, Opt::LoaderEntries(_)));
            }
        }
    }
}