rsconstruct 0.9.78

//! External tool registry and installation engine.
//!
//! Lives at the crate root because nothing here depends on the `Processor`
//! trait, and every file under `src/processors/` must be a real processor.
//! This is the data and the mechanics of "what tools exist and how do we
//! install them", which `builder/tools.rs` orchestrates on top of.


/// Central registry of all known external tools — single source of truth for
/// runtime category and install command. Both `tool_install_command()` and
/// `tool_runtime()` (in `builder/tools.rs`) look up data from this table.
///
/// Runtime categories: "python", "node", "ruby", "rust", "perl", "jvm", "system"
///
/// A single way to install a tool.
pub struct InstallMethod {
    /// Package manager or method name (e.g., "pip", "apt", "npm", "snap", "cargo", "binary")
    pub method: &'static str,
    /// Package name for the package manager (e.g., "taplo-cli" for cargo, "texlive-latex-base" for apt)
    pub package: &'static str,
}

/// Context for executing an install: verbosity and eatmydata preference.
///
/// `sudo` is decided at execution time via `crate::platform::needs_sudo()`;
/// callers don't need to pass it in.
pub struct InstallCtx {
    /// When true, print each subprocess argv before running it.
    pub verbose: bool,
    /// When true, prepend `eatmydata` to system-package-manager calls
    /// (apt/dnf/pacman) for faster installs. No-op when eatmydata isn't
    /// on PATH.
    pub use_eatmydata: bool,
}

impl InstallMethod {
    /// Human-readable preview of what installing this entry's package
    /// would do — first line of the first describe step. Lossy for
    /// multi-step installs (binary fetches), but adequate for `tools list`.
    pub fn command(&self) -> String {
        let steps = describe(self.method, &[self.package]);
        steps.first().map_or_else(|| format!("({}) {}", self.method, self.package), |argv| join_argv(argv))
    }
}

/// Display the steps that `run(method, packages, ctx)` would execute,
/// without executing them. Used for logs and previews.
pub fn describe(method: &str, packages: &[&str]) -> Vec<Vec<String>> {
    let sudo = sudo_argv();
    let strs = |parts: &[&str]| -> Vec<String> {
        parts.iter().map(|s| (*s).to_string()).collect()
    };
    let prefix = |head: &[&str], tail: &[&str]| -> Vec<String> {
        sudo.iter().chain(head.iter()).chain(tail.iter())
            .map(|s| (*s).to_string()).collect()
    };
    match method {
        "apt" => {
            // Run `apt-get update` first so the package index isn't stale.
            // CI runners ship with indexes a few days old; without this, an
            // `install` for a security-updated package 404s on the mirror.
            let update = prefix(&["apt-get", "update"], &[]);
            let mut install = prefix(&["apt-get", "install", "-y"], &[]);
            install.extend(packages.iter().map(|s| (*s).to_string()));
            vec![update, install]
        }
        "dnf" => {
            let mut argv = prefix(&["dnf", "install", "-y"], &[]);
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            vec![argv]
        }
        "pacman" => {
            let mut argv = prefix(&["pacman", "-S", "--noconfirm"], &[]);
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            vec![argv]
        }
        "brew" => {
            let mut argv = strs(&["brew", "install"]);
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            vec![argv]
        }
        "snap" => {
            let mut argv = prefix(&["snap", "install"], &[]);
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            vec![argv]
        }
        "pip"   => vec![{ let mut a = strs(&["pip", "install"]); a.extend(packages.iter().map(|s| (*s).to_string())); a }],
        "uv"    => vec![{ let mut a = uv_pip_install_argv(); a.extend(packages.iter().map(|s| (*s).to_string())); a }],
        "npm"   => vec![{ let mut a = strs(&["npm", "install", "-g"]); a.extend(packages.iter().map(|s| (*s).to_string())); a }],
        "cargo" => vec![{ let mut a = strs(&["cargo", "install"]); a.extend(packages.iter().map(|s| (*s).to_string())); a }],
        "gem"   => vec![{ let mut a = gem_install_argv(); a.extend(packages.iter().map(|s| (*s).to_string())); a }],
        "binary" => packages.iter().flat_map(|p| describe_binary(p)).collect(),
        "manual" => packages.iter()
            .map(|p| vec!["# manual:".to_string(), (*p).to_string()])
            .collect(),
        _ => packages.iter()
            .map(|p| vec![format!("# unknown method '{}':", method), (*p).to_string()])
            .collect(),
    }
}

/// Execute the install for `method` over `packages` (batched when the
/// method supports it). Each subprocess runs argv-style — never via a
/// shell. Returns Err on the first failure.
pub fn run(method: &str, packages: &[&str], ctx: &InstallCtx) -> anyhow::Result<()> {
    use anyhow::Context as _;
    use std::process::Command;
    if packages.is_empty() {
        return Ok(());
    }
    let exec = |argv: &[String]| -> anyhow::Result<()> {
        if ctx.verbose {
            println!("Running: {}", join_argv(argv));
        }
        // Deliberately NOT routed through run_command: installers must
        // inherit the terminal, both so `sudo` can prompt for a password and
        // so apt/dnf can render progress. Capturing would hang on the
        // password prompt. This is one of the two documented exceptions to
        // the "everything goes through the central runner" rule (see
        // docs/src/internal/architecture.md).
        let status = Command::new(&argv[0]).args(&argv[1..]).status()
            .with_context(|| format!("failed to spawn: {}", join_argv(argv)))?;
        if !status.success() {
            anyhow::bail!(
                "{} exited with code {}",
                join_argv(argv),
                status.code().map_or_else(|| "unknown".to_string(), |c| c.to_string())
            );
        }
        Ok(())
    };
    let sudo = sudo_argv();
    let eatmydata: &[&str] = if ctx.use_eatmydata && which::which("eatmydata").is_ok() {
        &["eatmydata"]
    } else {
        &[]
    };
    let pkgmgr_argv = |head: &[&str]| -> Vec<String> {
        sudo.iter()
            .chain(eatmydata.iter())
            .chain(head.iter())
            .map(|s| (*s).to_string())
            .collect()
    };
    match method {
        "apt" => {
            // Refresh the package index before installing — CI runners ship
            // with stale indexes that 404 on security-updated packages.
            let update = pkgmgr_argv(&["apt-get", "update"]);
            exec(&update)?;
            let mut argv = pkgmgr_argv(&["apt-get", "install", "-y"]);
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            exec(&argv)
        }
        "dnf" => {
            let mut argv = pkgmgr_argv(&["dnf", "install", "-y"]);
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            exec(&argv)
        }
        "pacman" => {
            let mut argv = pkgmgr_argv(&["pacman", "-S", "--noconfirm"]);
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            exec(&argv)
        }
        "brew" => {
            // brew is macOS-only; no sudo, no eatmydata.
            let mut argv = vec!["brew".to_string(), "install".to_string()];
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            exec(&argv)
        }
        "snap" => {
            // snap doesn't need eatmydata.
            let mut argv: Vec<String> = sudo.iter().chain(["snap", "install"].iter())
                .map(|s| (*s).to_string()).collect();
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            exec(&argv)
        }
        "pip" => {
            let mut argv = vec!["pip".to_string(), "install".to_string()];
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            exec(&argv)
        }
        "uv" => {
            let mut argv = uv_pip_install_argv();
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            exec(&argv)
        }
        "npm" => {
            let mut argv = vec!["npm".to_string(), "install".to_string(), "-g".to_string()];
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            exec(&argv)
        }
        "cargo" => {
            let mut argv = vec!["cargo".to_string(), "install".to_string()];
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            exec(&argv)
        }
        "gem" => {
            let mut argv = gem_install_argv();
            argv.extend(packages.iter().map(|s| (*s).to_string()));
            exec(&argv)
            // The bin dir a `--user-install` just created becomes visible to
            // the NEXT rsconstruct invocation, via the PATH augmentation at
            // startup. Nothing in this process probes for the tool after
            // installing it, and re-augmenting here would mutate the
            // environment with tokio threads alive (see platform::set_env).
        }
        "binary" => {
            for pkg in packages {
                run_binary(pkg, ctx)?;
            }
            Ok(())
        }
        "manual" => anyhow::bail!(
            "method '{}' is manual-only — install these packages by hand: {}",
            method, packages.join(", ")
        ),
        other => anyhow::bail!("unknown install method '{other}'"),
    }
}

fn sudo_argv() -> &'static [&'static str] {
    if crate::platform::needs_sudo() { &["sudo"] } else { &[] }
}

/// The argv prefix for installing gems. Appends `--user-install` when a
/// plain `gem install` would die on an unwritable default gem dir — the
/// apt-ruby case, where gems go to root-owned `/var/lib/gems` and rsconstruct
/// deliberately doesn't sudo-wrap language package managers. Used by both
/// `describe` and `run` so the printed plan matches what executes.
fn gem_install_argv() -> Vec<String> {
    let mut argv = vec!["gem".to_string(), "install".to_string()];
    if gem_needs_user_install() {
        argv.push("--user-install".to_string());
    }
    argv
}

/// The argv prefix for installing Python packages with uv. `--python
/// python3` targets whichever interpreter `python3` on PATH resolves to —
/// the same environment a bare `pip install` would touch (the active venv
/// when one is on PATH, the system interpreter on a CI runner).
///
/// `--system` is passed only for a non-venv interpreter, where uv needs it
/// (without it uv refuses with "No virtual environment found" even when
/// `--python` names the interpreter). It is NOT harmless for a venv target:
/// uv documents `--system` as "do not consider virtual environments", and
/// with `--python` resolving to a venv's python it installs into that
/// venv's *base* interpreter instead — on a Debian/Ubuntu image that base
/// is PEP 668 externally-managed, and the install fails with "the
/// interpreter at /usr is externally managed ... Virtual environments were
/// not considered due to the --system flag". Omitting `--system` makes uv
/// install into the venv the interpreter belongs to, which is what a bare
/// `pip install` does there.
///
/// When the target is a non-venv interpreter whose site-packages is
/// unwritable (a CI runner's apt python), pip would silently fall back to a
/// user install; uv has no user scheme, so `--prefix <user base>`
/// reproduces that fallback's exact layout
/// (`~/.local/lib/pythonX.Y/site-packages` + `~/.local/bin` on Linux).
/// PEP 668 externally-managed markers are still respected — no
/// `--break-system-packages` — matching what a bare `pip install` refuses.
/// Used by both `describe` and `run` so the printed plan matches what
/// executes.
fn uv_pip_install_argv() -> Vec<String> {
    let probe = python_probe();
    uv_pip_install_argv_for(probe.in_venv, probe.user_prefix.as_deref())
}

/// The argv `uv_pip_install_argv` builds, with the machine probe factored
/// out so both branches are unit-testable regardless of the host's python3.
fn uv_pip_install_argv_for(in_venv: bool, user_prefix: Option<&str>) -> Vec<String> {
    let mut argv: Vec<String> = ["uv", "pip", "install", "--python", "python3"]
        .iter().map(|s| (*s).to_string()).collect();
    if !in_venv {
        argv.push("--system".to_string());
    }
    if let Some(user_base) = user_prefix {
        argv.push("--prefix".to_string());
        argv.push(user_base.to_string());
    }
    argv
}

/// What `python3` on PATH is: whether it is a venv interpreter, and the
/// `--prefix` a uv install must use to emulate pip's user-install fallback
/// (None when uv can write the target directly: a venv is active,
/// site-packages is writable, or `python3` is missing or broken — the
/// install then fails with uv's own message, like the gem probe below).
/// Asks `python3` once per process for its venv-ness, purelib, and user base.
#[derive(Clone, Default)]
struct PythonProbe {
    in_venv: bool,
    user_prefix: Option<String>,
}

fn python_probe() -> PythonProbe {
    static PROBE: std::sync::OnceLock<PythonProbe> = std::sync::OnceLock::new();
    PROBE.get_or_init(|| {
        let Ok(out) = std::process::Command::new("python3")
            .args(["-c", "import sys, sysconfig, site; \
                    print(int(sys.prefix != sys.base_prefix)); \
                    print(sysconfig.get_path('purelib')); \
                    print(site.getuserbase())"])
            .output() else {
            return PythonProbe::default();
        };
        if !out.status.success() {
            return PythonProbe::default();
        }
        let stdout = String::from_utf8_lossy(&out.stdout);
        let mut lines = stdout.lines();
        let in_venv = lines.next().is_some_and(|l| l == "1");
        let purelib = lines.next().map_or("", str::trim);
        let user_base = lines.next().map_or("", str::trim);
        let user_prefix = if in_venv || purelib.is_empty() || user_base.is_empty()
            || nearest_existing_ancestor_is_writable(std::path::Path::new(purelib))
        {
            None
        } else {
            Some(user_base.to_string())
        };
        PythonProbe { in_venv, user_prefix }
    }).clone()
}

/// Whether the default gem dir is unwritable for the current user (never
/// true for root). Asks `gem env gemdir` once per process; a missing or
/// broken `gem` reports false and lets the install fail with gem's own
/// message.
fn gem_needs_user_install() -> bool {
    static NEEDS: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
    *NEEDS.get_or_init(|| {
        if crate::platform::is_root() {
            return false;
        }
        let Ok(out) = std::process::Command::new("gem").args(["env", "gemdir"]).output() else {
            return false;
        };
        if !out.status.success() {
            return false;
        }
        let stdout = String::from_utf8_lossy(&out.stdout);
        let gemdir = std::path::Path::new(stdout.trim());
        if gemdir.as_os_str().is_empty() {
            return false;
        }
        !nearest_existing_ancestor_is_writable(gemdir)
    })
}

/// `access(W_OK)` on the path, or — when it doesn't exist yet — on its
/// nearest existing ancestor, which is what decides whether the path could
/// be created.
fn nearest_existing_ancestor_is_writable(path: &std::path::Path) -> bool {
    let mut p = path;
    loop {
        if p.exists() {
            return crate::platform::path_is_writable(p);
        }
        match p.parent() {
            Some(parent) => p = parent,
            None => return false,
        }
    }
}

/// Make user-installed gem executables resolvable: append the user gem bin
/// dirs that exist to this process's PATH, so `which`-based tool probes and
/// every spawned child (tools, processor scripts) see them. `gem install
/// --user-install` puts binaries in a dir that is on nobody's PATH by
/// default, which would otherwise leave a just-installed tool reported as
/// missing.
///
/// Called once at the top of `main()`, before any thread exists — the
/// safety condition of `platform::set_env`.
pub fn augment_path_with_user_gem_bins() {
    let Some(home) = std::env::var_os("HOME") else { return };
    let gem_home = std::env::var_os("GEM_HOME");
    let dirs = user_gem_bin_dirs(std::path::Path::new(&home), gem_home.as_deref());
    if dirs.is_empty() {
        return;
    }
    let path = std::env::var_os("PATH").unwrap_or_default();
    if let Some(new_path) = path_with_appended_dirs(&path, &dirs) {
        crate::platform::set_env("PATH", &new_path);
    }
}

/// Existing user-level gem executable dirs: `$GEM_HOME/bin` plus the
/// per-ruby-version `bin` dirs of both user-install layouts —
/// `~/.gem/ruby/<version>/bin` (upstream rubygems) and
/// `~/.local/share/gem/ruby/<version>/bin` (the Debian/Ubuntu XDG patch).
/// Only dirs that exist are returned; globbing the layouts costs two
/// readdirs and avoids spawning ruby at every startup.
fn user_gem_bin_dirs(home: &std::path::Path, gem_home: Option<&std::ffi::OsStr>) -> Vec<std::path::PathBuf> {
    let mut dirs = Vec::new();
    if let Some(gem_home) = gem_home {
        let bin = std::path::Path::new(gem_home).join("bin");
        if bin.is_dir() {
            dirs.push(bin);
        }
    }
    for base in [home.join(".gem/ruby"), home.join(".local/share/gem/ruby")] {
        let Ok(entries) = std::fs::read_dir(&base) else { continue };
        let mut versions: Vec<std::path::PathBuf> = entries
            .flatten()
            .map(|e| e.path().join("bin"))
            .filter(|p| p.is_dir())
            .collect();
        versions.sort();
        dirs.append(&mut versions);
    }
    dirs
}

/// `path` with the dirs not already on it appended, or None when every dir
/// is already present. Append rather than prepend: a system-installed tool
/// keeps winning over a user gem of the same name.
fn path_with_appended_dirs(path: &std::ffi::OsStr, dirs: &[std::path::PathBuf]) -> Option<std::ffi::OsString> {
    let existing: Vec<std::path::PathBuf> = std::env::split_paths(path).collect();
    let missing: Vec<std::path::PathBuf> = dirs.iter()
        .filter(|d| !existing.contains(d))
        .cloned()
        .collect();
    if missing.is_empty() {
        return None;
    }
    // join_paths only errors on an entry containing the separator, which
    // can't happen: every entry came from split_paths or is a real dir.
    std::env::join_paths(existing.into_iter().chain(missing)).ok()
}

fn join_argv(argv: &[String]) -> String {
    argv.join(" ")
}

/// Description of the steps that `run_binary` would execute. Used for
/// preview/logging only.
fn describe_binary(pkg: &str) -> Vec<Vec<String>> {
    match binary_recipe(pkg) {
        // A .deb goes through apt, not the download/chmod/mv shape below: the
        // asset URL is resolved from the latest release at install time, so
        // it can only be described generically here.
        Some(BinaryRecipe { archive: ArchiveKind::Deb { source }, dest, .. }) => {
            let sudo = sudo_argv();
            let deb = format!("/tmp/{dest}.deb");
            let (note, url) = match source {
                DebSource::GithubRelease { repo, asset_pattern } => (
                    Some(format!("# resolve latest '{asset_pattern}' .deb asset from {repo}")),
                    "<resolved-asset-url>".to_string(),
                ),
                DebSource::Url(url) => (None, url.to_string()),
            };
            let mut steps: Vec<Vec<String>> = Vec::new();
            if let Some(note) = note {
                steps.push(vec![note]);
            }
            steps.push(crate::download::curl_argv(&url, &deb));
            steps.push(sudo.iter().chain(["apt-get", "install", "-y", &deb].iter())
                .map(|s| (*s).to_string()).collect());
            steps
        }
        Some(BinaryRecipe { url, archive, dest, .. }) => {
            let tmp = format!("/tmp/{dest}");
            let dl = format!("/tmp/{dest}.dl");
            let final_path = format!("/usr/local/bin/{dest}");
            let download = crate::download::curl_argv(url, &dl);
            let extract = match archive {
                ArchiveKind::TarGz { inner } => vec![
                    "tar".to_string(), "-xzf".to_string(),
                    dl,
                    "-C".to_string(), "/tmp".to_string(),
                    inner.to_string(),
                ],
                ArchiveKind::Gunzip => vec![
                    "gunzip".to_string(), "-f".to_string(),
                    dl,
                ],
                ArchiveKind::Raw => vec![
                    "mv".to_string(), dl, tmp.clone(),
                ],
                ArchiveKind::Deb { .. } => unreachable!("matched by the Deb arm above"),
            };
            let chmod = vec!["chmod".to_string(), "+x".to_string(), tmp.clone()];
            let sudo = sudo_argv();
            let mv = sudo.iter().chain(["mv", &tmp, &final_path].iter())
                .map(|s| (*s).to_string()).collect();
            vec![download, extract, chmod, mv]
        }
        None => vec![vec![format!("# unknown binary recipe '{pkg}'")]],
    }
}

/// The GitHub API token to authenticate release lookups with, if one is set.
///
/// `GITHUB_TOKEN` is the name Actions uses and `GH_TOKEN` the one the `gh`
/// CLI uses; accepting both means the same binary is authenticated on a
/// runner and on a developer machine that has `gh` set up, with no extra
/// configuration in either place. An empty value is treated as unset —
/// `env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}` expands to the empty
/// string rather than disappearing when the secret is unavailable, and
/// sending `Bearer ` with no token earns a 401 instead of the anonymous
/// access that would otherwise still work.
fn github_token() -> Option<String> {
    github_token_from(|name| std::env::var(name).ok())
}

/// The variable-selection half of [`github_token`], split out so it can be
/// tested without mutating the process environment — `set_var` is global
/// state and the test harness runs threads in parallel.
fn github_token_from(lookup: impl Fn(&str) -> Option<String>) -> Option<String> {
    // The emptiness filter is inside find_map, not after it: an empty
    // GITHUB_TOKEN must fall through to GH_TOKEN rather than mask it.
    ["GITHUB_TOKEN", "GH_TOKEN"].iter()
        .find_map(|name| lookup(name).filter(|token| !token.trim().is_empty()))
}

/// Resolve the browser-download URL of the newest release asset in `repo`
/// whose name contains `asset_pattern` and ends in `.deb`. Resolving at
/// install time (instead of pinning a URL in the recipe) is what keeps the
/// recipe from breaking every time upstream cuts a release.
fn resolve_latest_deb_asset(repo: &str, asset_pattern: &str) -> anyhow::Result<String> {
    use anyhow::Context as _;
    let api = format!("https://api.github.com/repos/{repo}/releases/latest");
    // Authenticate when a token is available. Unauthenticated api.github.com
    // allows 60 requests/hour *per source IP*, and GitHub-hosted runners
    // share egress IPs — so a busy runner pool exhausts the budget and this
    // call fails instantly with 403 (CI run 33967438754). A token raises the
    // limit to 5000/hour for the account it belongs to. Absent locally, where
    // one machine never approaches 60/hour, so this stays optional.
    //
    // Read once, outside the retry closure: the environment cannot change
    // between attempts, and re-reading it per attempt would only repeat work.
    let token = github_token();
    // Retried via download::with_retry for the same reason downloads are:
    // a connection reset here fails the whole install. See
    // docs/src/internal/download-policy.md.
    let body = crate::download::with_retry(|| {
        let mut req = ureq::get(&api)
            // GitHub rejects API requests without a User-Agent.
            .header("User-Agent", "rsconstruct");
        if let Some(token) = &token {
            req = req.header("Authorization", &format!("Bearer {token}"));
        }
        req.call()
            .with_context(|| format!("Failed to query GitHub releases API for {repo}"))?
            .body_mut()
            .read_to_string()
            .with_context(|| format!("Failed to read GitHub releases response for {repo}"))
    })?;
    let release: serde_json::Value = serde_json::from_str(&body)
        .with_context(|| format!("Failed to parse GitHub releases JSON for {repo}"))?;
    release["assets"].as_array()
        .with_context(|| format!("GitHub release for {repo} has no 'assets' array"))?
        .iter()
        .find_map(|a| {
            let name = a["name"].as_str()?;
            let is_deb = std::path::Path::new(name).extension()
                .is_some_and(|ext| ext.eq_ignore_ascii_case("deb"));
            (name.contains(asset_pattern) && is_deb)
                .then(|| a["browser_download_url"].as_str())?
                .map(std::string::ToString::to_string)
        })
        .with_context(|| format!(
            "No .deb asset matching '{asset_pattern}' in the latest {repo} release"
        ))
}

fn run_binary(pkg: &str, ctx: &InstallCtx) -> anyhow::Result<()> {
    use anyhow::Context as _;
    use std::process::Command;
    let recipe = binary_recipe(pkg)
        .ok_or_else(|| anyhow::anyhow!("no binary install recipe for '{pkg}'"))?;
    let download = format!("/tmp/{}.dl", recipe.dest);
    let final_tmp = format!("/tmp/{}", recipe.dest);
    let final_path = format!("/usr/local/bin/{}", recipe.dest);
    let exec = |argv: &[&str]| -> anyhow::Result<()> {
        if ctx.verbose {
            println!("Running: {}", argv.join(" "));
        }
        // Same exception as `run()` above: the binary installer shells out to
        // `sudo install`, which needs the terminal for its password prompt.
        let status = Command::new(argv[0]).args(&argv[1..]).status()
            .with_context(|| format!("failed to spawn: {}", argv.join(" ")))?;
        if !status.success() {
            anyhow::bail!(
                "{} exited with code {}",
                argv.join(" "),
                status.code().map_or_else(|| "unknown".to_string(), |c| c.to_string())
            );
        }
        Ok(())
    };
    // A .deb is installed by apt, so it skips the download/chmod/mv shape
    // entirely: apt pulls the dependency tree the bare binary would be
    // missing, and the payload is not a single executable.
    if let ArchiveKind::Deb { source } = recipe.archive {
        let deb = format!("/tmp/{}.deb", recipe.dest);
        let asset_url = match source {
            DebSource::GithubRelease { repo, asset_pattern } => {
                resolve_latest_deb_asset(repo, asset_pattern)?
            }
            DebSource::Url(url) => url.to_string(),
        };
        let dl = crate::download::curl_argv(&asset_url, &deb);
        exec(&dl.iter().map(String::as_str).collect::<Vec<_>>())?;
        let sudo = sudo_argv();
        let mut install: Vec<&str> = sudo.to_vec();
        install.extend(["apt-get", "install", "-y", &deb]);
        let result = exec(&install);
        std::fs::remove_file(&deb).ok();
        return result;
    }
    let dl = crate::download::curl_argv(recipe.url, &download);
    exec(&dl.iter().map(String::as_str).collect::<Vec<_>>())?;
    match recipe.archive {
        ArchiveKind::Deb { .. } => unreachable!("returned early by the Deb branch above"),
        ArchiveKind::TarGz { inner } => {
            exec(&["tar", "-xzf", &download, "-C", "/tmp", inner])?;
            // After tar, the inner file is at /tmp/<inner>; rename to final_tmp.
            let inner_path = format!("/tmp/{inner}");
            if inner_path != final_tmp {
                std::fs::rename(&inner_path, &final_tmp)
                    .with_context(|| format!("rename {inner_path} -> {final_tmp}"))?;
            }
            std::fs::remove_file(&download).ok();
        }
        ArchiveKind::Gunzip => {
            // gunzip strips the .gz extension. Our download path ends in
            // .dl; rename to .dl.gz so gunzip leaves /tmp/<dest>.dl, then
            // move to final_tmp.
            let gz = format!("{download}.gz");
            std::fs::rename(&download, &gz).with_context(|| format!("rename {download} -> {gz}"))?;
            exec(&["gunzip", "-f", &gz])?;
            std::fs::rename(&download, &final_tmp)
                .with_context(|| format!("rename {download} -> {final_tmp}"))?;
        }
        ArchiveKind::Raw => {
            std::fs::rename(&download, &final_tmp)
                .with_context(|| format!("rename {download} -> {final_tmp}"))?;
        }
    }
    crate::platform::set_permissions_mode(std::path::Path::new(&final_tmp), 0o755)
        .with_context(|| format!("chmod +x {final_tmp}"))?;
    let sudo = sudo_argv();
    let mut mv: Vec<&str> = sudo.to_vec();
    mv.extend(["mv", &final_tmp, &final_path]);
    exec(&mv)
}

struct BinaryRecipe {
    url: &'static str,
    archive: ArchiveKind,
    dest: &'static str,
}

enum ArchiveKind {
    TarGz { inner: &'static str },
    Gunzip,
    /// The download is the binary itself, no extraction needed.
    Raw,
    /// The download is a `.deb` installed with apt, not a bare binary dropped
    /// into /usr/local/bin: apt pulls the dependency tree a raw binary would
    /// be missing.
    ///
    /// `source` says where the `.deb` comes from — a GitHub release whose
    /// asset is resolved at install time (so the recipe doesn't pin a version
    /// that goes stale the moment upstream cuts a release), or a vendor URL
    /// that is already stable.
    Deb { source: DebSource },
}

/// Where a [`ArchiveKind::Deb`] payload is fetched from.
enum DebSource {
    /// Newest asset in `repo`'s latest release whose name contains
    /// `asset_pattern` and ends in `.deb`.
    GithubRelease { repo: &'static str, asset_pattern: &'static str },
    /// A vendor URL that always points at the current build.
    Url(&'static str),
}

fn binary_recipe(pkg: &str) -> Option<BinaryRecipe> {
    match pkg {
        "rumdl" => Some(BinaryRecipe {
            url: "https://github.com/rvben/rumdl/releases/download/v0.2.66/rumdl-v0.2.66-x86_64-unknown-linux-gnu.tar.gz",
            archive: ArchiveKind::TarGz { inner: "rumdl" },
            dest: "rumdl",
        }),
        // Pinned rather than tracking latest, unlike taplo/hadolint below.
        // zola 0.23 renamed config keys (highlight_code -> [markdown.highlighting])
        // and swapped the syntax highlighter, so an unpinned upgrade can fail a
        // site build on config alone -- a breakage that lands in the consuming
        // project's CI, not here. Bump this deliberately.
        "zola" => Some(BinaryRecipe {
            url: "https://github.com/getzola/zola/releases/download/v0.23.3/zola-v0.23.3-x86_64-unknown-linux-gnu.tar.gz",
            archive: ArchiveKind::TarGz { inner: "zola" },
            dest: "zola",
        }),
        "taplo" => Some(BinaryRecipe {
            url: "https://github.com/tamasfe/taplo/releases/latest/download/taplo-linux-x86_64.gz",
            archive: ArchiveKind::Gunzip,
            dest: "taplo",
        }),
        // Pinned like zola: actionlint's release assets embed the version in
        // the filename (actionlint_1.7.12_linux_amd64.tar.gz), so there is no
        // stable `releases/latest/download/...` URL to track the way taplo
        // and hadolint do. Bump this deliberately.
        "actionlint" => Some(BinaryRecipe {
            url: "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz",
            archive: ArchiveKind::TarGz { inner: "actionlint" },
            dest: "actionlint",
        }),
        "hadolint" => Some(BinaryRecipe {
            url: "https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64",
            archive: ArchiveKind::Raw,
            dest: "hadolint",
        }),
        // checkpatch.pl ships only inside the kernel tree — there is no release
        // artifact and no distro package. Fetching the single script from
        // torvalds/linux master is the automatable equivalent of "copy it out
        // of a kernel checkout", and keeps the tool out of the manual-only
        // bucket that `tools install --all` rejects.
        "checkpatch.pl" => Some(BinaryRecipe {
            url: "https://raw.githubusercontent.com/torvalds/linux/master/scripts/checkpatch.pl",
            archive: ArchiveKind::Raw,
            dest: "checkpatch.pl",
        }),
        // drawio ships an official .deb but has no apt repo, and its snap
        // needs a running snapd — unavailable in containers and flaky on CI
        // runners, which made this the one tool `--all` could not provision.
        "drawio" => Some(BinaryRecipe {
            url: "https://github.com/jgraph/drawio-desktop/releases/latest",
            archive: ArchiveKind::Deb {
                source: DebSource::GithubRelease {
                    repo: "jgraph/drawio-desktop",
                    asset_pattern: "amd64",
                },
            },
            dest: "drawio",
        }),
        // Chrome is not in the Ubuntu archive — `apt install
        // google-chrome-stable` only works after adding Google's repo. The
        // vendor .deb is the official route and is not version-pinned.
        "google-chrome-stable" => Some(BinaryRecipe {
            url: "https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb",
            archive: ArchiveKind::Deb {
                source: DebSource::Url(
                    "https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb",
                ),
            },
            dest: "google-chrome",
        }),
        _ => None,
    }
}

/// Information about an external tool: its name, runtime category, and install methods.
pub struct ToolInfo {
    /// Bare binary name, as found on `$PATH` — never a path.
    ///
    /// This is the detection key: it goes straight to `which::which` (see
    /// `builder/tools.rs` and `tool_lock.rs`), so it decides whether a tool
    /// reports `installed` or `missing`, and which binary gets version-locked.
    ///
    /// `which` switches behaviour on the presence of a separator, so a name
    /// containing `/` is NOT looked up on `$PATH` — it is resolved relative to
    /// the *current working directory*. A vendored-looking entry such as
    /// `gems/bin/mdl` therefore only resolves when rsconstruct happens to be
    /// invoked from the one directory with that subtree beneath it, and reports
    /// `missing` everywhere else — including for a user who has the tool
    /// installed and on `$PATH` at, say, `~/install/gems/bin/mdl`. Two such
    /// entries were removed for exactly this reason; keep names bare.
    ///
    /// In both modes `which` also requires the executable bit, so a present but
    /// non-executable file reads as `missing`.
    ///
    /// To pin a project-local binary, set the per-processor `command` config
    /// field (`config/processor_configs.rs`) instead — that is the value that
    /// actually gets executed. This field stays a bare name so detection works
    /// from any cwd.
    pub name: &'static str,
    /// Runtime category ("python", "node", "ruby", "rust", "perl", "jvm", "system")
    pub runtime: &'static str,
    /// Install methods, ordered by preference (first is the default)
    pub install_methods: &'static [InstallMethod],
}

pub static TOOLS: &[ToolInfo] = &[
    // Python tools
    ToolInfo { name: "ruff", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "ruff" }] },
    ToolInfo { name: "pylint", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "pylint" }] },
    ToolInfo { name: "mypy", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "mypy" }] },
    ToolInfo { name: "pyrefly", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "pyrefly" }] },
    ToolInfo { name: "yamllint", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "yamllint" }] },
    ToolInfo { name: "sphinx-build", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "sphinx" }] },
    ToolInfo { name: "pip", runtime: "python", install_methods: &[InstallMethod { method: "apt", package: "python3-pip" }] },
    ToolInfo { name: "uv", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "uv" }] },
    ToolInfo { name: "jsonlint", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "demjson3" }] },
    ToolInfo { name: "cpplint", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "cpplint" }] },
    ToolInfo { name: "black", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "black" }] },
    ToolInfo { name: "pytest", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "pytest" }] },
    ToolInfo { name: "a2x", runtime: "python", install_methods: &[InstallMethod { method: "apt", package: "asciidoc" }] },
    // The mako processor runs `python3 -c "import mako..."`, so what it really
    // needs is the Mako *library*, which the registry can't probe directly (it
    // probes executables). The `mako-render` console script ships in the same
    // distribution, so probing it is an exact proxy for "the library is
    // importable", and installing it installs the library.
    ToolInfo { name: "mako-render", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "mako" }] },
    ToolInfo { name: "python3", runtime: "python", install_methods: &[InstallMethod { method: "apt", package: "python3" }] },
    // Node tools
    ToolInfo { name: "marp", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "@marp-team/marp-cli" }] },
    ToolInfo { name: "mmdc", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "@mermaid-js/mermaid-cli" }] },
    ToolInfo { name: "markdownlint", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "markdownlint-cli" }] },
    ToolInfo { name: "prettier", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "prettier" }] },
    ToolInfo { name: "eslint", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "eslint" }] },
    ToolInfo { name: "htmlhint", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "htmlhint" }] },
    ToolInfo { name: "jshint", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "jshint" }] },
    ToolInfo { name: "npm", runtime: "node", install_methods: &[InstallMethod { method: "apt", package: "npm" }] },
    ToolInfo { name: "node", runtime: "node", install_methods: &[InstallMethod { method: "apt", package: "nodejs" }] },
    // Ruby tools
    ToolInfo { name: "mdl", runtime: "ruby", install_methods: &[InstallMethod { method: "gem", package: "mdl" }] },
    ToolInfo { name: "bundle", runtime: "ruby", install_methods: &[InstallMethod { method: "gem", package: "bundler" }] },
    ToolInfo { name: "ruby", runtime: "ruby", install_methods: &[InstallMethod { method: "apt", package: "ruby" }] },
    // Rust tools
    ToolInfo { name: "mdbook", runtime: "rust", install_methods: &[InstallMethod { method: "cargo", package: "mdbook" }] },
    ToolInfo { name: "rumdl", runtime: "rust", install_methods: &[
        InstallMethod { method: "binary", package: "rumdl" },
        InstallMethod { method: "cargo", package: "rumdl" },
    ]},
    // Binary only, no cargo fallback: upstream does not publish zola to
    // crates.io. The `zola` crate there is an unrelated squatter -- version
    // 0.0.0, yanked, described as "zola installer" -- so `cargo install zola`
    // would fail or fetch the wrong thing. The GitHub release is the only
    // automatable route.
    ToolInfo { name: "zola", runtime: "rust", install_methods: &[
        InstallMethod { method: "binary", package: "zola" },
    ]},
    ToolInfo { name: "taplo", runtime: "rust", install_methods: &[
        InstallMethod { method: "binary", package: "taplo" },
        InstallMethod { method: "cargo", package: "taplo-cli" },
    ]},
    // rustup is the canonical route, but `apt install rustc/cargo` is a real,
    // automatable install and is what makes these reachable from
    // `tools install --all` on a bare machine. A host that already has a
    // rustup toolchain never reaches the install path: `which` finds these
    // first.
    ToolInfo { name: "cargo", runtime: "rust", install_methods: &[InstallMethod { method: "apt", package: "cargo" }] },
    ToolInfo { name: "rustc", runtime: "rust", install_methods: &[InstallMethod { method: "apt", package: "rustc" }] },
    // Perl tools
    ToolInfo { name: "perl", runtime: "perl", install_methods: &[InstallMethod { method: "apt", package: "perl" }] },
    ToolInfo { name: "markdown", runtime: "perl", install_methods: &[InstallMethod { method: "apt", package: "markdown" }] },
    ToolInfo { name: "checkpatch.pl", runtime: "perl", install_methods: &[InstallMethod { method: "binary", package: "checkpatch.pl" }] },
    ToolInfo { name: "perltidy", runtime: "perl", install_methods: &[InstallMethod { method: "apt", package: "perltidy" }] },
    // System tools
    // xelatex ships in texlive-xetex, not in a package of its own; pandoc's
    // `pdf_engine = "xelatex"` needs the binary, so probe the binary and
    // install the distribution that provides it.
    ToolInfo { name: "xelatex", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "texlive-xetex" }] },
    // ARM bare-metal cross toolchain. Debian splits it the same way as the
    // native one: the compiler driver comes from gcc-arm-none-eabi, while ar
    // and objcopy come from binutils-arm-none-eabi.
    ToolInfo { name: "arm-none-eabi-gcc", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "gcc-arm-none-eabi" }] },
    ToolInfo { name: "arm-none-eabi-ar", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "binutils-arm-none-eabi" }] },
    ToolInfo { name: "arm-none-eabi-objcopy", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "binutils-arm-none-eabi" }] },
    ToolInfo { name: "shellcheck", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "shellcheck" }] },
    ToolInfo { name: "luacheck", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "lua-check" }] },
    ToolInfo { name: "cppcheck", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "cppcheck" }] },
    ToolInfo { name: "clang-tidy", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "clang-tidy" }] },
    ToolInfo { name: "gcc", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "gcc" }] },
    ToolInfo { name: "g++", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "g++" }] },
    ToolInfo { name: "clang", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "clang" }] },
    ToolInfo { name: "clang++", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "clang" }] },
    ToolInfo { name: "ar", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "binutils" }] },
    ToolInfo { name: "make", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "make" }] },
    ToolInfo { name: "jq", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "jq" }] },
    ToolInfo { name: "aspell", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "aspell" }] },
    ToolInfo { name: "pandoc", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "pandoc" }] },
    ToolInfo { name: "pdflatex", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "texlive-latex-base" }] },
    ToolInfo { name: "qpdf", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "qpdf" }] },
    ToolInfo { name: "dot", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "graphviz" }] },
    ToolInfo { name: "drawio", runtime: "system", install_methods: &[InstallMethod { method: "binary", package: "drawio" }] },
    ToolInfo { name: "libreoffice", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "libreoffice" }] },
    ToolInfo { name: "flock", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "util-linux" }] },
    ToolInfo { name: "uname", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "coreutils" }] },
    ToolInfo { name: "sh", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "dash" }] },
    ToolInfo { name: "git", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "git" }] },
    ToolInfo { name: "pdfunite", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "poppler-utils" }] },
    ToolInfo { name: "google-chrome", runtime: "system", install_methods: &[InstallMethod { method: "binary", package: "google-chrome-stable" }] },
    ToolInfo { name: "objdump", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "binutils" }] },
    ToolInfo { name: "tidy", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "tidy" }] },
    ToolInfo { name: "xmllint", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "libxml2-utils" }] },
    ToolInfo { name: "clojure", runtime: "jvm", install_methods: &[
        // Debian/Ubuntu package the Clojure CLI, which is what makes this
        // installable without the official shell installer; brew is the macOS
        // route. See https://clojure.org/guides/install_clojure
        InstallMethod { method: "apt", package: "clojure" },
        InstallMethod { method: "brew", package: "clojure/tools/clojure" },
    ]},
    ToolInfo { name: "svglint", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "svglint" }] },
    ToolInfo { name: "svgo", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "svgo" }] },
    ToolInfo { name: "cmakelint", runtime: "python", install_methods: &[InstallMethod { method: "pip", package: "cmakelint" }] },
    ToolInfo { name: "protoc", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "protobuf-compiler" }] },
    ToolInfo { name: "sass", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "sass" }] },
    ToolInfo { name: "hadolint", runtime: "system", install_methods: &[
        InstallMethod { method: "binary", package: "hadolint" },
        InstallMethod { method: "brew", package: "hadolint" },
        InstallMethod { method: "apt", package: "hadolint" },
    ]},
    ToolInfo { name: "php", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "php-cli" }] },
    ToolInfo { name: "checkstyle", runtime: "jvm", install_methods: &[InstallMethod { method: "apt", package: "checkstyle" }] },
    ToolInfo { name: "yq", runtime: "system", install_methods: &[
        InstallMethod { method: "pip", package: "yq" },
        InstallMethod { method: "snap", package: "yq" },
        InstallMethod { method: "apt", package: "yq" },
    ]},
    // Node tools (additional)
    ToolInfo { name: "stylelint", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "stylelint" }] },
    ToolInfo { name: "jslint", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "jslint" }] },
    ToolInfo { name: "standard", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "standard" }] },
    ToolInfo { name: "htmllint", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "htmllint-cli" }] },
    ToolInfo { name: "slidev", runtime: "node", install_methods: &[InstallMethod { method: "npm", package: "@slidev/cli" }] },
    // Perl tools (additional)
    ToolInfo { name: "perlcritic", runtime: "perl", install_methods: &[InstallMethod { method: "apt", package: "libperl-critic-perl" }] },
    // Ruby tools (additional)
    ToolInfo { name: "jekyll", runtime: "ruby", install_methods: &[InstallMethod { method: "gem", package: "jekyll" }] },
    // Built-in / coreutils
    ToolInfo { name: "true", runtime: "system", install_methods: &[InstallMethod { method: "apt", package: "coreutils" }] },
];

// Processor files may submit additional ToolInfo entries via
// `inventory::submit!` — a new processor declares its external tool in its
// own file instead of editing this registry. The central TOOLS table above
// keeps the long-standing shared entries; consumers must iterate
// `all_tools()`, never TOOLS directly.
inventory::collect!(ToolInfo);

/// Every known tool: the central table plus processor-file submissions.
pub fn all_tools() -> impl Iterator<Item = &'static ToolInfo> {
    TOOLS.iter().chain(inventory::iter::<ToolInfo>)
}

/// Look up a tool by name.
pub fn tool_info(tool: &str) -> Option<&'static ToolInfo> {
    all_tools().find(|t| t.name == tool)
}

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

    /// A tool name must have exactly one registry entry — a processor
    /// submitting a name the central table already carries (or two
    /// processors submitting the same name) would make `tool_info`'s answer
    /// depend on iteration order.
    #[test]
    fn tool_names_are_unique_across_central_and_submitted() {
        let mut seen = std::collections::HashSet::new();
        let mut dups: Vec<&str> = Vec::new();
        for t in all_tools() {
            if !seen.insert(t.name) {
                dups.push(t.name);
            }
        }
        dups.sort_unstable();
        assert!(dups.is_empty(), "duplicate tool registry entries: {dups:?}");
    }
}

/// Return the default install command for a tool, if known.
pub fn tool_install_command(tool: &str) -> Option<String> {
    tool_info(tool).and_then(|t| t.install_methods.first().map(InstallMethod::command))
}

/// Return the runtime category for a tool, if known.
pub fn tool_runtime(tool: &str) -> Option<&'static str> {
    tool_info(tool).map(|t| t.runtime)
}


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

    /// `GITHUB_TOKEN` wins when both are set, an empty value falls through
    /// to the next name rather than masking it (Actions expands a missing
    /// secret to the empty string), and all-unset means anonymous access.
    #[test]
    fn github_token_prefers_github_token_and_skips_empty() {
        let lookup = |vars: &[(&str, &str)], name: &str| {
            vars.iter().find(|(k, _)| *k == name).map(|(_, v)| (*v).to_string())
        };

        assert_eq!(
            github_token_from(|n| lookup(&[("GITHUB_TOKEN", "a"), ("GH_TOKEN", "b")], n)),
            Some("a".to_string())
        );
        assert_eq!(
            github_token_from(|n| lookup(&[("GH_TOKEN", "b")], n)),
            Some("b".to_string())
        );
        // The masking case: empty GITHUB_TOKEN must not hide GH_TOKEN.
        assert_eq!(
            github_token_from(|n| lookup(&[("GITHUB_TOKEN", ""), ("GH_TOKEN", "b")], n)),
            Some("b".to_string())
        );
        assert_eq!(
            github_token_from(|n| lookup(&[("GITHUB_TOKEN", "   ")], n)),
            None
        );
        assert_eq!(github_token_from(|n| lookup(&[], n)), None);
    }

    /// `sudo_argv()` returns either `["sudo"]` or `[]` based on runtime
    /// state. Empty when running as root or when `sudo` isn't on PATH.
    #[test]
    fn sudo_argv_matches_runtime() {
        let prefix = sudo_argv();
        if crate::platform::needs_sudo() {
            assert_eq!(prefix, &["sudo"]);
        } else {
            assert!(prefix.is_empty());
        }
    }

    /// Only bin dirs that actually exist are collected, from all three
    /// layouts: `$GEM_HOME/bin`, `~/.gem/ruby/<v>/bin` (upstream) and
    /// `~/.local/share/gem/ruby/<v>/bin` (Debian/Ubuntu).
    #[test]
    fn user_gem_bin_dirs_collects_existing_layouts() {
        let home = tempfile::TempDir::new().unwrap();
        assert!(user_gem_bin_dirs(home.path(), None).is_empty());

        let upstream = home.path().join(".gem/ruby/3.2.0/bin");
        let debian = home.path().join(".local/share/gem/ruby/3.3.0/bin");
        let gem_home = home.path().join("mygems");
        std::fs::create_dir_all(&upstream).unwrap();
        std::fs::create_dir_all(&debian).unwrap();
        std::fs::create_dir_all(gem_home.join("bin")).unwrap();
        // A version dir without bin/ must not be collected.
        std::fs::create_dir_all(home.path().join(".gem/ruby/2.7.0")).unwrap();

        let dirs = user_gem_bin_dirs(home.path(), Some(gem_home.as_os_str()));
        assert_eq!(dirs, vec![gem_home.join("bin"), upstream, debian]);
    }

    /// Appending keeps the original PATH order, adds only what's missing,
    /// and reports None when there is nothing to add.
    #[test]
    fn path_with_appended_dirs_appends_only_missing() {
        use std::path::PathBuf;
        let path = std::ffi::OsString::from("/usr/bin:/home/u/.gem/ruby/3.2.0/bin");
        let dirs = vec![
            PathBuf::from("/home/u/.gem/ruby/3.2.0/bin"),
            PathBuf::from("/home/u/mygems/bin"),
        ];
        let new_path = path_with_appended_dirs(&path, &dirs).unwrap();
        assert_eq!(new_path, "/usr/bin:/home/u/.gem/ruby/3.2.0/bin:/home/u/mygems/bin");

        assert!(path_with_appended_dirs(&new_path, &dirs).is_none());
        assert!(path_with_appended_dirs(&path, &[]).is_none());
    }

    /// A missing path is judged by its nearest existing ancestor — that is
    /// what decides whether the path could be created.
    #[test]
    fn ancestor_writability_walks_to_existing_dir() {
        let dir = tempfile::TempDir::new().unwrap();
        assert!(nearest_existing_ancestor_is_writable(&dir.path().join("a/b/c")));
        if !crate::platform::is_root() {
            crate::platform::set_permissions_mode(dir.path(), 0o555).unwrap();
            assert!(!nearest_existing_ancestor_is_writable(&dir.path().join("a/b/c")));
            crate::platform::set_permissions_mode(dir.path(), 0o755).unwrap();
        }
    }

    /// `apt` describe must run `apt-get update` first, then call
    /// `apt-get install -y <pkg>` exactly once with the package name
    /// after the flags. Whether `sudo` is prepended depends on runtime
    /// state.
    #[test]
    fn apt_describe_shape_is_correct() {
        let steps = describe("apt", &["cowsay"]);
        assert_eq!(steps.len(), 2);

        let update = &steps[0];
        let upd_idx = update.iter().position(|s| s == "apt-get").expect("apt-get in update argv");
        assert_eq!(update[upd_idx + 1], "update");
        assert_eq!(update.len(), upd_idx + 2);

        let install = &steps[1];
        let pkgmgr_idx = install.iter().position(|s| s == "apt-get").expect("apt-get in install argv");
        assert_eq!(install[pkgmgr_idx + 1], "install");
        assert_eq!(install[pkgmgr_idx + 2], "-y");
        assert_eq!(install[pkgmgr_idx + 3], "cowsay");
        if install[0] == "sudo" {
            assert_eq!(pkgmgr_idx, 1);
        } else {
            assert_eq!(pkgmgr_idx, 0);
        }
    }

    /// `apt` batch describe collapses many packages into one apt-get
    /// install call (still preceded by a single `apt-get update`).
    #[test]
    fn apt_batch_describe_collapses() {
        let steps = describe("apt", &["foo", "bar", "baz"]);
        assert_eq!(steps.len(), 2);
        let install = &steps[1];
        let pkgmgr_idx = install.iter().position(|s| s == "apt-get").expect("apt-get in argv");
        assert_eq!(&install[pkgmgr_idx + 3..], &["foo", "bar", "baz"]);
    }

    /// `pip` describe never uses sudo, regardless of runtime state.
    #[test]
    fn pip_describe_never_has_sudo() {
        let steps = describe("pip", &["ruff"]);
        assert_eq!(steps.len(), 1);
        let argv = &steps[0];
        assert_eq!(argv[0], "pip");
        assert!(!argv.contains(&"sudo".to_string()));
    }

    /// `uv` describe targets `python3` from PATH (the environment a bare
    /// `pip install` would touch), with `--system` only when that is a
    /// non-venv interpreter, passes requirements — markers included — as single argv
    /// elements at the end, and never uses sudo. `--prefix <user base>` may
    /// appear between flags and requirements depending on the machine's
    /// python3 (venv-ness, site-packages writability), so the middle is not
    /// pinned here.
    #[test]
    fn uv_describe_targets_path_python3_without_sudo() {
        let steps = describe("uv", &["flask==3.1.0", "pywin32==312 ; sys_platform == 'win32'"]);
        assert_eq!(steps.len(), 1);
        let argv = &steps[0];
        assert_eq!(argv[..5], ["uv", "pip", "install", "--python", "python3"].map(String::from));
        // --system exactly when python3 on this machine is not a venv interpreter
        assert_eq!(argv.contains(&"--system".to_string()), !python_probe().in_venv);
        assert_eq!(&argv[argv.len() - 2..], &["flask==3.1.0", "pywin32==312 ; sys_platform == 'win32'"]);
        assert!(!argv.contains(&"sudo".to_string()));
    }

    /// A non-venv interpreter gets `--system` (uv refuses without it), plus
    /// `--prefix` when pip would have fallen back to a user install.
    #[test]
    fn uv_argv_non_venv_uses_system_and_optional_prefix() {
        assert_eq!(uv_pip_install_argv_for(false, None), ["uv", "pip", "install", "--python", "python3", "--system"].map(String::from));
        assert_eq!(uv_pip_install_argv_for(false, Some("/home/u/.local")),
            ["uv", "pip", "install", "--python", "python3", "--system", "--prefix", "/home/u/.local"].map(String::from));
    }

    /// A venv interpreter must NOT get `--system`: uv would ignore the venv
    /// and install into its base interpreter, which on Debian/Ubuntu is
    /// externally managed and refuses (seen in the demos-os-linux image).
    #[test]
    fn uv_argv_venv_omits_system() {
        let argv = uv_pip_install_argv_for(true, None);
        assert_eq!(argv, ["uv", "pip", "install", "--python", "python3"].map(String::from));
        assert!(!argv.contains(&"--system".to_string()));
    }

    /// `binary` describe yields a multi-step plan (download, extract,
    /// chmod, mv) with no shell metacharacters anywhere.
    #[test]
    fn binary_describe_has_no_shell_metachars() {
        for pkg in &["taplo", "rumdl", "zola"] {
            let steps = describe("binary", &[pkg]);
            assert!(steps.len() >= 3, "binary {pkg} should have >=3 steps");
            for step in &steps {
                for arg in step {
                    for forbidden in &['|', '>', '<', ';', '&'] {
                        assert!(
                            !arg.contains(*forbidden),
                            "binary {pkg} step contains shell metachar '{forbidden}': {arg:?}"
                        );
                    }
                }
            }
        }
    }
}