mise 2026.9.2

//! Plugin-declared system dependencies with capability detection.
//!
//! Source-compiling plugins (php, erlang, postgres, ...) need system
//! prerequisites — build tools, libraries, headers. Historically these lived
//! as README prose, so users only discovered them when a build failed halfway
//! through. A plugin can instead declare them as structured *capability
//! checks* (see [`SystemDepCheck`]) plus per-package-manager remediation hints.
//!
//! Detection is the source of truth: a check that passes is satisfied,
//! full stop — mise never asks *how* the capability got there, so nix,
//! MacPorts, and from-source installs all pass without ceremony. The package
//! hints are consulted only to *offer* installing the missing subset via the
//! existing [`crate::system::packages`] engine.

use std::collections::HashMap;
use std::fmt;
use std::sync::{Arc, Mutex};

use indexmap::IndexMap;
use once_cell::sync::Lazy;
use versions::Versioning;

use crate::config::Settings;
use crate::system::packages::{self, PackageRequest, SystemPackageManager};

/// A single capability a plugin requires before it can install.
#[derive(Debug, Clone)]
pub(crate) struct SystemDep {
    pub check: SystemDepCheck,
    /// Optional version constraint (only meaningful for `Bin`/`PkgConfig`).
    pub version: Option<VersionConstraint>,
    /// If set, this dependency is optional and this string is the reason it
    /// might be wanted (e.g. "observer GUI"). Missing optional deps never
    /// prompt or fail — they surface as a single informational line.
    pub optional: Option<String>,
    /// manager name -> candidate package names, used only for remediation
    /// hints. More than one candidate means the same capability is packaged
    /// under different names across distro releases (apt's `libaio1` became
    /// `libaio1t64` in the 64-bit time_t transition); the first candidate the
    /// manager actually has wins, resolved lazily at remediation time.
    pub packages: IndexMap<String, Vec<String>>,
}

/// How to detect whether a [`SystemDep`] is satisfied.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum SystemDepCheck {
    /// executable resolvable on `PATH`
    Bin(String),
    /// `pkg-config --exists <name>` (a `.pc` module)
    PkgConfig(String),
    /// dynamic linker can resolve a soname, e.g. `libaio.so.1` (Linux only)
    SharedLib(String),
    /// escape hatch: a shell command whose exit status 0 means satisfied
    Command(String),
}

impl SystemDepCheck {
    fn kind(&self) -> &'static str {
        match self {
            SystemDepCheck::Bin(_) => "bin",
            SystemDepCheck::PkgConfig(_) => "pkgconfig",
            SystemDepCheck::SharedLib(_) => "sharedlib",
            SystemDepCheck::Command(_) => "command",
        }
    }

    fn value(&self) -> &str {
        match self {
            SystemDepCheck::Bin(s)
            | SystemDepCheck::PkgConfig(s)
            | SystemDepCheck::SharedLib(s)
            | SystemDepCheck::Command(s) => s,
        }
    }
}

/// A version comparison operator for [`VersionConstraint`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum VersionOp {
    AtLeast,
    Greater,
    AtMost,
    Less,
    Exact,
}

impl VersionOp {
    fn symbol(self) -> &'static str {
        match self {
            VersionOp::AtLeast => ">=",
            VersionOp::Greater => ">",
            VersionOp::AtMost => "<=",
            VersionOp::Less => "<",
            VersionOp::Exact => "=",
        }
    }
}

/// A parsed version constraint like `>=3.0`. A bare version (`3.0`) means
/// `>=3.0` — the common "at least this" case.
///
/// Note: this compares versions of *system binaries/libraries* declared by a
/// plugin author against what is installed on the machine. It is NOT used to
/// resolve or order mise tool versions (see the semver rules in CLAUDE.md);
/// it is the same class of comparison as [`crate::config::config_file::min_version`].
#[derive(Debug, Clone)]
pub(crate) struct VersionConstraint {
    pub op: VersionOp,
    pub version: Versioning,
}

impl VersionConstraint {
    pub(crate) fn parse(s: &str) -> eyre::Result<Self> {
        let s = s.trim();
        let (op, rest) = if let Some(r) = s.strip_prefix(">=") {
            (VersionOp::AtLeast, r)
        } else if let Some(r) = s.strip_prefix("<=") {
            (VersionOp::AtMost, r)
        } else if let Some(r) = s.strip_prefix('>') {
            (VersionOp::Greater, r)
        } else if let Some(r) = s.strip_prefix('<') {
            (VersionOp::Less, r)
        } else if let Some(r) = s.strip_prefix('=') {
            (VersionOp::Exact, r)
        } else {
            (VersionOp::AtLeast, s)
        };
        let version = Versioning::new(rest.trim())
            .ok_or_else(|| eyre::eyre!("invalid version constraint '{s}'"))?;
        Ok(Self { op, version })
    }

    pub(crate) fn satisfied_by(&self, current: &Versioning) -> bool {
        match self.op {
            VersionOp::AtLeast => current >= &self.version,
            VersionOp::Greater => current > &self.version,
            VersionOp::AtMost => current <= &self.version,
            VersionOp::Less => current < &self.version,
            VersionOp::Exact => current == &self.version,
        }
    }
}

impl fmt::Display for VersionConstraint {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}{}", self.op.symbol(), self.version)
    }
}

impl SystemDep {
    /// Human-readable capability label, e.g. `bison >=3.0`, `pkg-config libxml-2.0`.
    pub(crate) fn label(&self) -> String {
        let base = match &self.check {
            SystemDepCheck::Bin(name) => name.clone(),
            SystemDepCheck::PkgConfig(name) => format!("pkg-config {name}"),
            SystemDepCheck::SharedLib(name) => format!("shared library {name}"),
            SystemDepCheck::Command(cmd) => format!("`{cmd}`"),
        };
        match &self.version {
            Some(v) => format!("{base} {v}"),
            None => base,
        }
    }

    /// Stable fingerprint used to memoize detection across tools that declare
    /// the same dependency (php + postgres both needing bison probe once).
    fn fingerprint(&self) -> String {
        match &self.version {
            Some(v) => format!("{}:{}:{v}", self.check.kind(), self.check.value()),
            None => format!("{}:{}", self.check.kind(), self.check.value()),
        }
    }
}

impl fmt::Display for SystemDep {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.label())
    }
}

/// The result of probing one [`SystemDep`] on the host.
#[derive(Debug, Clone)]
pub(crate) struct DepStatus {
    pub dep: SystemDep,
    /// detected version, if a version was extracted
    pub found: Option<String>,
    pub satisfied: bool,
    /// why it is unsatisfied (or a note when satisfied)
    pub reason: Option<String>,
}

impl TryFrom<vfox::SystemDependency> for SystemDep {
    type Error = eyre::Error;

    fn try_from(d: vfox::SystemDependency) -> eyre::Result<Self> {
        let check = match (&d.bin, &d.pkgconfig, &d.sharedlib, &d.command) {
            (Some(b), None, None, None) => SystemDepCheck::Bin(b.clone()),
            (None, Some(p), None, None) => SystemDepCheck::PkgConfig(p.clone()),
            (None, None, Some(s), None) => SystemDepCheck::SharedLib(s.clone()),
            (None, None, None, Some(c)) => SystemDepCheck::Command(c.clone()),
            _ => eyre::bail!(
                "systemDependencies entry must set exactly one of bin/pkgconfig/sharedlib/command"
            ),
        };
        // A version constraint is only meaningful for bin/pkgconfig (we probe
        // `--version` / `--modversion`). If declared on sharedlib/command,
        // keep the check but drop the version with a warning rather than
        // silently honoring a constraint that is never enforced.
        let version = match (&check, &d.version) {
            (_, None) => None,
            (SystemDepCheck::Bin(_) | SystemDepCheck::PkgConfig(_), Some(v)) => {
                Some(VersionConstraint::parse(v)?)
            }
            (check, Some(_)) => {
                warn!(
                    "systemDependencies: `version` is only supported for bin/pkgconfig checks, ignoring it for the {} check",
                    check.kind()
                );
                None
            }
        };
        // Normalize candidate names here so nothing downstream can pass a
        // package manager a padded or empty operand, and a hint left with no
        // usable name at all reports as unremediable rather than as a nameless
        // install.
        let packages = d
            .packages
            .into_iter()
            .map(|(mgr, candidates)| {
                let candidates: Vec<String> = candidates
                    .into_iter()
                    .map(|c| c.trim().to_string())
                    .filter(|c| !c.is_empty())
                    .collect();
                (mgr, candidates)
            })
            .filter(|(_, candidates)| !candidates.is_empty())
            .collect();
        Ok(SystemDep {
            check,
            version,
            optional: d.optional.clone(),
            packages,
        })
    }
}

/// Host-only detection result: `(satisfied, found_version, reason)`.
type DetectOutcome = (bool, Option<String>, Option<String>);

static CACHE: Lazy<Mutex<HashMap<String, DetectOutcome>>> =
    Lazy::new(|| Mutex::new(HashMap::new()));

/// Detect all `deps`, memoized. Concurrency-safe; two calls with the same
/// fingerprint reuse the first result.
pub(crate) async fn detect(deps: &[SystemDep]) -> Vec<DepStatus> {
    detect_inner(deps, true).await
}

/// Detect all `deps`, bypassing (and refreshing) the memo cache. Used to
/// re-verify after remediation, since a package we just installed changes the
/// answer.
pub(crate) async fn detect_fresh(deps: &[SystemDep]) -> Vec<DepStatus> {
    detect_inner(deps, false).await
}

async fn detect_inner(deps: &[SystemDep], use_cache: bool) -> Vec<DepStatus> {
    let mut out = Vec::with_capacity(deps.len());
    for dep in deps {
        // The cache keys on the check + version only (the fingerprint), so it
        // must store just the detection *outcome* — not the whole DepStatus.
        // The `dep` (its `optional`/`packages`) belongs to the current caller;
        // reusing the first caller's dep would misclassify a required dep as
        // optional when two tools share the same check.
        let fp = dep.fingerprint();
        let (satisfied, found, reason) =
            if use_cache && let Some(cached) = CACHE.lock().unwrap().get(&fp).cloned() {
                cached
            } else {
                let outcome = detect_outcome(dep).await;
                CACHE.lock().unwrap().insert(fp, outcome.clone());
                outcome
            };
        out.push(DepStatus {
            dep: dep.clone(),
            found,
            satisfied,
            reason,
        });
    }
    out
}

/// Probe a single dep, returning `(satisfied, found_version, reason)` — the
/// part of the result that depends only on the host, not on which tool
/// declared the dep.
async fn detect_outcome(dep: &SystemDep) -> DetectOutcome {
    match &dep.check {
        SystemDepCheck::Bin(name) => check_bin(name, dep.version.as_ref()).await,
        SystemDepCheck::PkgConfig(name) => check_pkgconfig(name, dep.version.as_ref()).await,
        SystemDepCheck::SharedLib(name) => check_sharedlib(name).await,
        SystemDepCheck::Command(cmd) => check_command(cmd).await,
    }
}

async fn check_bin(
    name: &str,
    constraint: Option<&VersionConstraint>,
) -> (bool, Option<String>, Option<String>) {
    let Some(path) = crate::file::which_spawnable(name) else {
        return (false, None, Some(format!("`{name}` not found on PATH")));
    };
    let Some(constraint) = constraint else {
        return (true, None, None);
    };
    match run_capture(&path, &["--version"]).await {
        Some((_, output)) => match extract_version(&output) {
            Some(v) => {
                let versioning = Versioning::new(&v);
                match versioning {
                    Some(versioning) => {
                        let ok = constraint.satisfied_by(&versioning);
                        (ok, Some(v), None)
                    }
                    // unparseable — do not block; presence is enough
                    None => {
                        debug!(
                            "system dep: `{name}` version '{v}' unparseable, treating as satisfied"
                        );
                        (true, Some(v), None)
                    }
                }
            }
            None => {
                debug!(
                    "system dep: could not extract version from `{name} --version`, treating as satisfied"
                );
                (true, None, None)
            }
        },
        None => {
            debug!("system dep: `{name} --version` failed to run, treating as satisfied");
            (true, None, None)
        }
    }
}

async fn check_pkgconfig(
    name: &str,
    constraint: Option<&VersionConstraint>,
) -> (bool, Option<String>, Option<String>) {
    let Some(path) = crate::file::which_spawnable("pkg-config") else {
        return (
            false,
            None,
            Some("pkg-config is not installed (needed to detect this library)".to_string()),
        );
    };
    match run_capture(&path, &["--exists", name]).await {
        Some((true, _)) => {}
        Some((false, _)) => {
            return (
                false,
                None,
                Some(format!("pkg-config module `{name}` not found")),
            );
        }
        None => {
            // Timeout or spawn failure — inconclusive, so don't block (matches
            // the "presence is enough" fallback in check_bin).
            debug!(
                "system dep: `pkg-config --exists {name}` timed out or failed to spawn, treating as satisfied"
            );
            return (true, None, None);
        }
    }
    let Some(constraint) = constraint else {
        return (true, None, None);
    };
    match run_capture(&path, &["--modversion", name]).await {
        Some((true, output)) => {
            let v = output.trim().to_string();
            match Versioning::new(&v) {
                Some(versioning) => (constraint.satisfied_by(&versioning), Some(v), None),
                None => {
                    debug!(
                        "system dep: pkg-config modversion '{v}' unparseable, treating as satisfied"
                    );
                    (true, Some(v), None)
                }
            }
        }
        _ => (true, None, None),
    }
}

#[cfg(target_os = "linux")]
async fn check_sharedlib(soname: &str) -> (bool, Option<String>, Option<String>) {
    // Primary: ldconfig's cache lists every soname the dynamic linker knows.
    // Each entry looks like `	libaio.so.1 (libc6,x86-64) => /path/libaio.so.1`,
    // so match the advertised soname as the whole first token — a substring
    // check would let `libfoo.so.10` satisfy a request for `libfoo.so.1`.
    for ldconfig in ["ldconfig", "/sbin/ldconfig"] {
        if let Some((true, output)) = run_capture(ldconfig, &["-p"]).await {
            if output
                .lines()
                .any(|l| l.split_whitespace().next() == Some(soname))
            {
                return (true, None, None);
            }
            // ldconfig ran and did not list it; still check LD_LIBRARY_PATH below
            break;
        }
    }
    // Fallback: honor LD_LIBRARY_PATH dirs the cache doesn't cover.
    if let Ok(paths) = std::env::var("LD_LIBRARY_PATH") {
        for dir in std::env::split_paths(&paths) {
            if dir.join(soname).exists() {
                return (true, None, None);
            }
        }
    }
    (
        false,
        None,
        Some(format!(
            "shared library `{soname}` not found by the dynamic linker"
        )),
    )
}

#[cfg(not(target_os = "linux"))]
async fn check_sharedlib(soname: &str) -> (bool, Option<String>, Option<String>) {
    debug!("system dep: sharedlib check for `{soname}` is Linux-only, treating as satisfied");
    (true, None, None)
}

async fn check_command(cmd: &str) -> (bool, Option<String>, Option<String>) {
    let (program, args): (&str, Vec<&str>) = if cfg!(windows) {
        ("cmd", vec!["/C", cmd])
    } else {
        ("sh", vec!["-c", cmd])
    };
    match run_capture(program, &args).await {
        Some((true, _)) => (true, None, None),
        _ => (
            false,
            None,
            Some(format!("command `{cmd}` did not succeed")),
        ),
    }
}

/// Run a short command, capturing combined stdout+stderr. Returns
/// `(success, output)` or `None` if it could not be spawned or timed out.
/// Silent and side-effect free — never elevates. A 5s wall-clock timeout keeps
/// a hanging binary (e.g. one that blocks on `--version`) from stalling the
/// whole install.
async fn run_capture(
    program: impl AsRef<std::ffi::OsStr>,
    args: &[&str],
) -> Option<(bool, String)> {
    let program = program.as_ref();
    let fut = tokio::process::Command::new(program)
        .args(args)
        .stdin(std::process::Stdio::null())
        .output();
    let output = match tokio::time::timeout(std::time::Duration::from_secs(5), fut).await {
        Ok(Ok(output)) => output,
        Ok(Err(_)) => return None,
        Err(_) => {
            debug!(
                "system dep: `{}` timed out, treating check as inconclusive",
                program.to_string_lossy()
            );
            return None;
        }
    };
    let mut combined = String::from_utf8_lossy(&output.stdout).into_owned();
    combined.push_str(&String::from_utf8_lossy(&output.stderr));
    Some((output.status.success(), combined))
}

/// Extract the first version-like token (`3`, `3.0`, `3.12.1`) from text such
/// as `bison (GNU Bison) 3.8.2`.
fn extract_version(text: &str) -> Option<String> {
    static RE: Lazy<regex::Regex> = Lazy::new(|| regex::Regex::new(r"\d+(?:\.\d+)+").unwrap());
    RE.find(text).map(|m| m.as_str().to_string())
}

/// Pick the first available, settings-enabled package manager that has a hint
/// for `dep`. Mirrors the manager selection [`crate::system`] applies so we
/// never propose a manager the driver would reject.
pub(crate) async fn pick_manager(dep: &SystemDep) -> Option<Arc<dyn SystemPackageManager>> {
    let enabled = Settings::get().system_packages.managers.clone();
    for m in packages::all_managers() {
        let name = m.name();
        if enabled
            .as_ref()
            .is_some_and(|e| !e.iter().any(|x| x == name))
        {
            continue;
        }
        if m.unavailable_reason_async().await.is_some() {
            continue;
        }
        // An empty candidate list names no package, so this manager cannot
        // remediate the dep even though it has an entry.
        if dep.packages.get(name).is_some_and(|c| !c.is_empty()) {
            return Some(m);
        }
    }
    None
}

/// Resolve `dep`'s hint for `m` to a single package name.
///
/// With one candidate this is just that name — no query, so the common case
/// costs nothing. With several, ask the manager which ones it actually has and
/// take the first; managers that cannot answer (the default `available`
/// implementation) fall back to the first candidate, which is the behavior
/// before candidate lists existed. Reached only for deps that already failed
/// detection, i.e. when mise is about to install packages anyway.
async fn resolve_package(m: &Arc<dyn SystemPackageManager>, dep: &SystemDep) -> Option<String> {
    let candidates = dep.packages.get(m.name())?;
    match candidates.split_first()? {
        (first, []) => Some(first.clone()),
        (first, _) => match m.available(candidates).await {
            Ok(available) => Some(
                candidates
                    .iter()
                    .zip(available)
                    .find(|(_, exists)| *exists)
                    .map(|(name, _)| name)
                    .unwrap_or(first)
                    .clone(),
            ),
            Err(err) => {
                debug!(
                    "could not query {} for {}, using {first}: {err:#}",
                    m.name(),
                    dep.label()
                );
                Some(first.clone())
            }
        },
    }
}

/// Group missing deps into per-manager [`PackageRequest`]s for remediation.
/// Returns `(by_manager, unremediable)` where `unremediable` are deps with no
/// available manager hint.
pub(crate) async fn build_requests(
    missing: &[&SystemDep],
) -> (IndexMap<String, Vec<PackageRequest>>, Vec<SystemDep>) {
    let mut by_mgr: IndexMap<String, Vec<PackageRequest>> = IndexMap::new();
    let mut unremediable = vec![];
    for dep in missing {
        // A dep with no manager, or whose hint names no package, is reported as
        // unremediable rather than sent to a manager as an empty operand.
        let resolved = match pick_manager(dep).await {
            Some(m) => resolve_package(&m, dep).await.map(|pkg| (m, pkg)),
            None => None,
        };
        match resolved {
            Some((m, pkg)) => {
                let requests = by_mgr.entry(m.name().to_string()).or_default();
                if !requests.iter().any(|r| r.name == pkg) {
                    requests.push(PackageRequest {
                        name: pkg,
                        version: None,
                        tap_url: None,
                        desired: crate::system::packages::PackageDesiredState::Present,
                    });
                }
            }
            None => unremediable.push((*dep).clone()),
        }
    }
    (by_mgr, unremediable)
}

/// Copy-pasteable install hint commands for `missing`, grouped by the manager
/// that would satisfy each. Used by warn mode.
pub(crate) async fn hint_commands(missing: &[&SystemDep]) -> Vec<String> {
    let (by_mgr, _) = build_requests(missing).await;
    by_mgr
        .into_iter()
        .map(|(mgr, requests)| {
            let pkgs = requests
                .iter()
                .map(|r| r.name.as_str())
                .collect::<Vec<_>>()
                .join(" ");
            format!("{}{pkgs}", install_prefix(&mgr))
        })
        .collect()
}

fn install_prefix(mgr: &str) -> &'static str {
    match mgr {
        "brew" => "brew install ",
        "brew-cask" => "brew install --cask ",
        "apt" => "sudo apt-get install -y ",
        "dnf" => "sudo dnf install -y ",
        "pacman" => "sudo pacman -S ",
        "apk" => "sudo apk add ",
        "mas" => "mas install ",
        _ => "",
    }
}

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

    #[test]
    fn test_version_constraint_parse_and_compare() {
        let c = VersionConstraint::parse(">=3.0").unwrap();
        assert_eq!(c.op, VersionOp::AtLeast);
        assert!(!c.satisfied_by(&Versioning::new("2.3").unwrap()));
        assert!(c.satisfied_by(&Versioning::new("3.0").unwrap()));
        assert!(c.satisfied_by(&Versioning::new("3.8.2").unwrap()));

        // bare version means >=
        let bare = VersionConstraint::parse("3.0").unwrap();
        assert_eq!(bare.op, VersionOp::AtLeast);
        assert!(bare.satisfied_by(&Versioning::new("3.1").unwrap()));
        assert!(!bare.satisfied_by(&Versioning::new("2.9").unwrap()));

        assert!(
            VersionConstraint::parse(">2")
                .unwrap()
                .satisfied_by(&Versioning::new("3").unwrap())
        );
        assert!(
            !VersionConstraint::parse(">3")
                .unwrap()
                .satisfied_by(&Versioning::new("3").unwrap())
        );
        assert!(
            VersionConstraint::parse("<=1.2")
                .unwrap()
                .satisfied_by(&Versioning::new("1.2").unwrap())
        );
        assert!(
            VersionConstraint::parse("=3.0")
                .unwrap()
                .satisfied_by(&Versioning::new("3.0").unwrap())
        );
        assert!(
            !VersionConstraint::parse("=3.0")
                .unwrap()
                .satisfied_by(&Versioning::new("3.0.1").unwrap())
        );
    }

    #[test]
    fn test_extract_version() {
        assert_eq!(
            extract_version("bison (GNU Bison) 2.3").as_deref(),
            Some("2.3")
        );
        assert_eq!(extract_version("GNU Make 3.81").as_deref(), Some("3.81"));
        assert_eq!(
            extract_version("OpenSSL 3.0.13 30 Jan 2024").as_deref(),
            Some("3.0.13")
        );
        assert_eq!(extract_version("no version here").as_deref(), None);
    }

    /// Reports only the names in `stock` as available, and records every query
    /// so a single-candidate hint can be shown to query nothing at all.
    struct StubManager {
        stock: Vec<String>,
        queries: Mutex<usize>,
    }

    #[async_trait::async_trait(?Send)]
    impl SystemPackageManager for StubManager {
        fn name(&self) -> &str {
            "stub"
        }
        fn is_available(&self) -> bool {
            true
        }
        fn unavailable_reason(&self) -> String {
            unreachable!()
        }
        async fn installed(
            &self,
            _pkgs: &[PackageRequest],
        ) -> crate::result::Result<Vec<crate::system::packages::PackageStatus>> {
            Ok(vec![])
        }
        async fn available(&self, names: &[String]) -> crate::result::Result<Vec<bool>> {
            *self.queries.lock().unwrap() += 1;
            Ok(names.iter().map(|n| self.stock.contains(n)).collect())
        }
        async fn install(
            &self,
            _pkgs: &[PackageRequest],
            _opts: &crate::system::packages::InstallOpts,
        ) -> crate::result::Result<()> {
            Ok(())
        }
    }

    fn dep_with_packages(candidates: Vec<&str>) -> SystemDep {
        SystemDep {
            check: SystemDepCheck::SharedLib("libaio.so.1".into()),
            version: None,
            optional: None,
            packages: [(
                "stub".to_string(),
                candidates.into_iter().map(str::to_string).collect(),
            )]
            .into_iter()
            .collect(),
        }
    }

    #[tokio::test]
    async fn test_resolve_package_picks_first_available_candidate() {
        let m: Arc<dyn SystemPackageManager> = Arc::new(StubManager {
            stock: vec!["libaio1".to_string()],
            queries: Mutex::new(0),
        });
        // the first candidate does not exist here, so the fallback wins
        let dep = dep_with_packages(vec!["libaio1t64", "libaio1"]);
        assert_eq!(resolve_package(&m, &dep).await.as_deref(), Some("libaio1"));

        // no candidate exists: keep the first so the user still sees a name
        let dep = dep_with_packages(vec!["nonexistent", "also-nonexistent"]);
        assert_eq!(
            resolve_package(&m, &dep).await.as_deref(),
            Some("nonexistent")
        );
    }

    #[tokio::test]
    async fn test_resolve_package_does_not_query_for_a_single_candidate() {
        let m = Arc::new(StubManager {
            stock: vec![],
            queries: Mutex::new(0),
        });
        let dyn_m: Arc<dyn SystemPackageManager> = m.clone();
        let dep = dep_with_packages(vec!["libaio1"]);
        // resolves to the only candidate even though the stub does not stock it
        assert_eq!(
            resolve_package(&dyn_m, &dep).await.as_deref(),
            Some("libaio1")
        );
        assert_eq!(*m.queries.lock().unwrap(), 0);
    }

    #[tokio::test]
    async fn test_resolve_package_returns_none_for_empty_candidates() {
        // `packages = { apt = {} }` names no package, so there is nothing to
        // install — resolution must yield None rather than an empty name.
        let m: Arc<dyn SystemPackageManager> = Arc::new(StubManager {
            stock: vec![],
            queries: Mutex::new(0),
        });
        let dep = dep_with_packages(vec![]);
        assert_eq!(resolve_package(&m, &dep).await, None);
    }

    /// Name of a package manager that can actually run here, or None. Tests
    /// that exercise `pick_manager` need one: it only ever considers managers
    /// from `all_managers()`, so a dep keyed on a fictional name is skipped for
    /// the wrong reason and proves nothing.
    async fn available_manager_name() -> Option<String> {
        for m in packages::all_managers() {
            if m.unavailable_reason_async().await.is_none() {
                return Some(m.name().to_string());
            }
        }
        None
    }

    fn dep_under_manager(mgr: &str, candidates: Vec<&str>) -> SystemDep {
        SystemDep {
            check: SystemDepCheck::SharedLib("libaio.so.1".into()),
            version: None,
            optional: None,
            packages: [(
                mgr.to_string(),
                candidates.into_iter().map(str::to_string).collect(),
            )]
            .into_iter()
            .collect(),
        }
    }

    #[tokio::test]
    async fn test_pick_manager_skips_empty_candidate_list() {
        let Some(mgr) = available_manager_name().await else {
            return; // no usable package manager on this host
        };
        // a real, available manager with a usable name is picked...
        let usable = dep_under_manager(&mgr, vec!["some-package"]);
        assert!(pick_manager(&usable).await.is_some());
        // ...but the same manager naming no package cannot remediate
        let empty = dep_under_manager(&mgr, vec![]);
        assert!(pick_manager(&empty).await.is_none());
        let (by_mgr, unremediable) = build_requests(&[&empty]).await;
        assert!(by_mgr.is_empty());
        assert_eq!(unremediable.len(), 1);
    }

    #[test]
    fn test_blank_candidate_names_are_dropped() {
        // A hint of only blank names must not survive as a nameless install,
        // and a padded name must reach the package manager trimmed rather than
        // as the invalid operand "  libaio  ".
        let d = vfox::SystemDependency {
            sharedlib: Some("libaio.so.1".into()),
            packages: [
                ("apt".to_string(), vec!["".to_string(), "  ".to_string()]),
                (
                    "dnf".to_string(),
                    vec!["".to_string(), "  libaio  ".to_string()],
                ),
            ]
            .into_iter()
            .collect(),
            ..Default::default()
        };
        let dep = SystemDep::try_from(d).unwrap();
        assert!(!dep.packages.contains_key("apt"));
        assert_eq!(dep.packages.get("dnf"), Some(&vec!["libaio".to_string()]));
    }

    #[tokio::test]
    async fn test_resolve_package_falls_back_when_manager_cannot_answer() {
        struct CannotAnswer;
        #[async_trait::async_trait(?Send)]
        impl SystemPackageManager for CannotAnswer {
            fn name(&self) -> &str {
                "stub"
            }
            fn is_available(&self) -> bool {
                true
            }
            fn unavailable_reason(&self) -> String {
                unreachable!()
            }
            async fn installed(
                &self,
                _pkgs: &[PackageRequest],
            ) -> crate::result::Result<Vec<crate::system::packages::PackageStatus>> {
                Ok(vec![])
            }
            async fn available(&self, _names: &[String]) -> crate::result::Result<Vec<bool>> {
                eyre::bail!("apt-cache not found")
            }
            async fn install(
                &self,
                _pkgs: &[PackageRequest],
                _opts: &crate::system::packages::InstallOpts,
            ) -> crate::result::Result<()> {
                Ok(())
            }
        }
        let m: Arc<dyn SystemPackageManager> = Arc::new(CannotAnswer);
        let dep = dep_with_packages(vec!["libaio1t64", "libaio1"]);
        assert_eq!(
            resolve_package(&m, &dep).await.as_deref(),
            Some("libaio1t64")
        );
    }

    #[test]
    fn test_label() {
        let dep = SystemDep {
            check: SystemDepCheck::Bin("bison".into()),
            version: Some(VersionConstraint::parse(">=3.0").unwrap()),
            optional: None,
            packages: Default::default(),
        };
        assert_eq!(dep.label(), "bison >=3.0");

        let dep = SystemDep {
            check: SystemDepCheck::PkgConfig("libxml-2.0".into()),
            version: None,
            optional: None,
            packages: Default::default(),
        };
        assert_eq!(dep.label(), "pkg-config libxml-2.0");
    }

    #[tokio::test]
    async fn test_check_bin_present_and_missing() {
        // The bare name resolves through configured executable extensions on Windows.
        let present = if cfg!(windows) { "cmd" } else { "sh" };
        let (ok, _, _) = check_bin(present, None).await;
        assert!(ok);

        let (ok, _, reason) = check_bin("definitely-not-a-real-binary-xyz", None).await;
        assert!(!ok);
        assert!(reason.is_some());
    }

    #[tokio::test]
    async fn test_check_command() {
        // `true`/`false` aren't cmd built-ins on Windows; use `exit N`, which
        // works in both `sh -c` and `cmd /C`.
        let (succeed, fail) = if cfg!(windows) {
            ("exit 0", "exit 1")
        } else {
            ("true", "false")
        };
        let (ok, _, _) = check_command(succeed).await;
        assert!(ok);
        let (ok, _, _) = check_command(fail).await;
        assert!(!ok);
    }

    #[test]
    fn test_version_only_applies_to_bin_and_pkgconfig() {
        // bin + version is honored
        let d = vfox::SystemDependency {
            bin: Some("bison".into()),
            version: Some(">=3.0".into()),
            ..Default::default()
        };
        let dep = SystemDep::try_from(d).unwrap();
        assert!(dep.version.is_some());

        // sharedlib + version: the check is kept, the version is dropped
        let d = vfox::SystemDependency {
            sharedlib: Some("libaio.so.1".into()),
            version: Some(">=1.0".into()),
            ..Default::default()
        };
        let dep = SystemDep::try_from(d).unwrap();
        assert!(matches!(dep.check, SystemDepCheck::SharedLib(_)));
        assert!(dep.version.is_none());
        // and label must not render a phantom version
        assert_eq!(dep.label(), "shared library libaio.so.1");
    }
}