zlayer-toolchain 0.14.1

//! Fetch self-contained, **relocation-free** language toolchains as prebuilt
//! vendor archives — "our apt-get" for the macOS sandbox, the prebuilt arm.
//!
//! # Why a prebuilt archive (vs a source build)
//!
//! The C-tool population ([`crate::source_build`]) has to be compiled at an
//! absolute keg prefix so its baked install-names point at real paths. The
//! language toolchains don't: vendors (go.dev, nodejs.org, the
//! `astral-sh`/`oven-sh`/`denoland`/`ziglang`/Adoptium/`GraalVM` releases) publish
//! macOS archives that are already position-independent and link only the macOS
//! system libraries (`/usr/lib/...`). Dropping one into an absolute **keg** and
//! pointing `PATH` / `GOROOT` / `JAVA_HOME` / `CARGO_HOME` at that keg yields a
//! tool that runs unmodified under a deny-default Seatbelt profile.
//!
//! # What this builds
//!
//! A keg for one of go/node/rust/python/deno/bun/zig/java/graalvm: resolve the
//! requested `formula` to a concrete vendor URL (replicating the live
//! version-resolution that the rootfs provisioner in `zlayer-builder` performs),
//! download it, extract it into the keg with the canonical per-language on-disk
//! layout, and write a [`KegManifest`] whose `path_dirs` + `env` are absolute
//! keg-rooted paths. Swift is intentionally **not** handled here — on macOS it is
//! provisioned from the host Xcode, so it falls through to the source arm.
//!
//! The resolvers, API structs and extraction logic are duplicated from
//! `zlayer_builder::macos_toolchain` on purpose: `zlayer-toolchain` is a leaf
//! crate and must not depend on `zlayer-builder` (that would re-introduce the
//! build cycle this crate exists to break).

use std::collections::HashMap;
use std::path::{Path, PathBuf};

use tracing::{debug, info, warn};

use crate::error::{Result, ToolchainError};
use crate::manifest::{KegManifest, KegSource};

// ---------------------------------------------------------------------------
// Public API
// ---------------------------------------------------------------------------

/// A resolved prebuilt toolchain: the concrete version, the vendor download URL,
/// and the upstream-published sha256 when one is available.
///
/// `sha256` is `None` for the "compute-on-download" path — vendors that publish
/// no per-artifact digest (or exact-version code paths that construct the URL
/// without querying the release index). [`download_verified`] then records the
/// digest it computes over the bytes.
///
/// [`download_verified`]: crate::package_index::download_verified
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PrebuiltResolution {
    /// The concrete resolved version (e.g. `1.23.6`).
    pub version: String,
    /// The vendor download URL.
    pub url: String,
    /// The upstream-published sha256 (bare hex), when available.
    pub sha256: Option<String>,
}

/// Resolve `formula` to a [`PrebuiltResolution`] for `vendor_arch`
/// (`arm64` / `amd64`) without downloading — used by the lockfile resolver.
///
/// # Errors
///
/// Returns [`ToolchainError::RegistryError`] if the version cannot be resolved.
pub(crate) async fn resolve_prebuilt(
    formula: &str,
    vendor_arch: &str,
) -> Result<PrebuiltResolution> {
    let (language, version_token) = formula_language_version(formula);
    resolve_prebuilt_url(&language, &version_token, vendor_arch).await
}

/// Return `true` if `formula` names a language toolchain handled by the prebuilt
/// fetcher (go/golang, node/nodejs, rust, python/python3/`python@N`, deno, bun,
/// zig, java/openjdk/`openjdk@N`, and any `graalvm`-containing name).
///
/// Returns `false` for everything else — including `swift`, which on macOS is
/// provisioned from the host Xcode by the source arm.
#[must_use]
#[allow(clippy::module_name_repetitions)]
pub fn is_prebuilt_formula(formula: &str) -> bool {
    let (language, _) = formula_language_version(formula);
    matches!(
        language.as_str(),
        "go" | "node" | "rust" | "python" | "deno" | "bun" | "zig" | "java" | "graalvm"
    )
}

/// Fetch + extract the prebuilt toolchain for `formula` into a keg under
/// `cache_dir`, write its [`KegManifest`], and return the keg path.
///
/// Idempotent: a `<keg>/.ready` marker (written LAST, after `toolchain.json`)
/// short-circuits a populated keg. A cold fetch removes any partial keg,
/// downloads into a scratch subdir, extracts into the keg root, writes the
/// manifest, cleans scratch, then stamps `.ready`.
///
/// The keg directory is `<cache_dir>/<formula>-<resolved_version>-<arch>`, where
/// `formula` is the **original** request string (so `python@3.12` / `node@22`
/// keep their `@`, matching how the cache is keyed elsewhere) and
/// `resolved_version` is the concrete version the vendor API resolved to.
///
/// # Errors
///
/// Returns [`ToolchainError::RegistryError`] on version-resolution, download or
/// extraction failure, and propagates I/O errors via
/// [`ToolchainError::IoError`].
#[allow(clippy::module_name_repetitions)]
pub async fn ensure_prebuilt(
    formula: &str,
    cache_dir: &Path,
    lockfile: Option<&crate::ToolchainLockfile>,
) -> Result<PathBuf> {
    use crate::ToolchainLockfileExt;
    let (language, version_token) = formula_language_version(formula);

    // A lock hit pins the exact version + URL + digest (consume-only). Otherwise
    // resolve live: `host_arch()` (arm64/amd64) is the token vendor URLs use; the
    // keg dir uses `arch_token()` (arm64/x86_64).
    let (resolved_version, url, expected_sha) =
        if let Some(locked) = lockfile.and_then(|l| l.lookup(formula, "macos", arch_token())) {
            (
                locked.version.clone(),
                locked.url.clone(),
                Some(locked.sha256.clone()),
            )
        } else {
            let resolution = resolve_prebuilt_url(&language, &version_token, host_arch()).await?;
            (resolution.version, resolution.url, resolution.sha256)
        };

    let keg = cache_dir.join(format!("{formula}-{resolved_version}-{}", arch_token()));
    let ready_marker = keg.join(".ready");

    if tokio::fs::try_exists(&ready_marker).await.unwrap_or(false) {
        return Ok(keg);
    }

    // Fresh fetch. Drop any partial keg from a crashed prior attempt.
    let _ = tokio::fs::remove_dir_all(&keg).await;
    tokio::fs::create_dir_all(&keg).await?;

    let scratch = keg.join(".download");
    tokio::fs::create_dir_all(&scratch).await?;

    info!(
        formula,
        language,
        version = %resolved_version,
        url = %url,
        "fetching prebuilt toolchain archive"
    );

    // 1. Download the vendor archive into the scratch dir, verifying against the
    //    upstream/lockfile digest when known (else recording the computed hash).
    let archive = scratch.join("archive");
    let computed_sha =
        crate::package_index::download_verified(&url, &archive, expected_sha.as_deref()).await?;

    // 2. Extract it into the keg root with the canonical per-language layout.
    extract_toolchain(&language, &archive, &keg).await?;

    // 3. Rust standalone installs its binaries under `<keg>/bin`; create the
    //    writable CARGO_HOME/RUSTUP_HOME dirs the manifest env points at so a
    //    later `cargo install` lands on `PATH` (`<keg>/cargo/bin`).
    if language == "rust" {
        tokio::fs::create_dir_all(keg.join("cargo/bin")).await?;
        tokio::fs::create_dir_all(keg.join("rustup")).await?;
    }

    // node's bundled OpenSSL 3 loads an openssl config at startup; under the
    // Seatbelt sandbox the system default config fails ("OpenSSL configuration
    // error") even though the binary runs fine on the host. Drop an empty config
    // into the keg (covered by the toolchain-cache Seatbelt grant) and point
    // OPENSSL_CONF at it (see keg_path_dirs_and_env) so node uses built-in
    // defaults. TLS still works — node uses its own bundled root CAs.
    if language == "node" {
        tokio::fs::create_dir_all(keg.join("etc")).await?;
        tokio::fs::write(keg.join("etc/openssl_sandbox.cnf"), b"").await?;
    }

    // 4. Write the manifest, clean scratch, then stamp `.ready` LAST.
    let manifest = build_manifest(&language, &resolved_version, &url, &computed_sha, &keg).await;
    manifest.write_to_keg(&keg).await?;

    if let Err(e) = tokio::fs::remove_dir_all(&scratch).await {
        warn!(error = %e, "failed to clean prebuilt download scratch dir (non-fatal)");
    }
    tokio::fs::write(&ready_marker, b"").await?;

    Ok(keg)
}

// ---------------------------------------------------------------------------
// Formula -> (language, version) mapping
// ---------------------------------------------------------------------------

/// Split a `formula` into its `(language, version_token)`.
///
/// Strips a `@<ver>` suffix for the version token (`python@3.12` ->
/// `("python", "3.12")`, `node@22` -> `("node", "22")`); a bare formula resolves
/// to `"latest"` (`go` -> `("go", "latest")`). The language is normalized via
/// [`normalize_language`].
fn formula_language_version(formula: &str) -> (String, String) {
    let (name, version) = match formula.split_once('@') {
        Some((n, v)) if !v.is_empty() => (n, v.to_string()),
        _ => (formula, "latest".to_string()),
    };
    (normalize_language(name), version)
}

/// Canonicalize a toolchain alias to its language key: `golang` -> `go`,
/// `nodejs` -> `node`, `python3` -> `python`, `openjdk` -> `java`, and any name
/// containing `graalvm` -> `graalvm`. Unrecognized names are returned lowercased
/// unchanged (so `swift` stays `swift` and is rejected by
/// [`is_prebuilt_formula`]).
fn normalize_language(name: &str) -> String {
    let lower = name.to_ascii_lowercase();
    if lower.contains("graalvm") {
        return "graalvm".to_string();
    }
    let canonical = match lower.as_str() {
        "go" | "golang" => "go",
        "node" | "nodejs" => "node",
        "rust" => "rust",
        "python" | "python3" => "python",
        "deno" => "deno",
        "bun" => "bun",
        "zig" => "zig",
        "java" | "openjdk" => "java",
        other => other,
    };
    canonical.to_string()
}

// ---------------------------------------------------------------------------
// Keg layout (path_dirs + env) + manifest
// ---------------------------------------------------------------------------

/// Compute the candidate `path_dirs` and `env` for a language keg, all rooted at
/// absolute keg paths. `path_dirs` are candidates — [`build_manifest`] filters
/// them to those that actually exist on disk after extraction.
///
/// Mirrors the `ToolchainSpec::*` constructors, but with `/usr/local/<lang>`
/// rewritten to the keg prefix:
/// - go: `GOROOT=<keg>`, `GOFLAGS=-buildvcs=false`, `PATH += <keg>/bin`
/// - rust: `CARGO_HOME=<keg>/cargo`, `RUSTUP_HOME=<keg>/rustup`,
///   `PATH += <keg>/cargo/bin, <keg>/bin`
/// - java: `JAVA_HOME=<keg>`, `PATH += <keg>/bin`
/// - graalvm: `JAVA_HOME=<keg>`, `GRAALVM_HOME=<keg>`, `PATH += <keg>/bin`
/// - node/python/deno/bun/zig: no env, `PATH += <keg>/bin`
fn keg_path_dirs_and_env(language: &str, keg: &Path) -> (Vec<String>, HashMap<String, String>) {
    let keg_str = keg.display().to_string();
    let bin = keg.join("bin").display().to_string();
    let mut env = HashMap::new();

    let path_dirs = match language {
        "go" => {
            env.insert("GOROOT".to_string(), keg_str);
            env.insert("GOFLAGS".to_string(), "-buildvcs=false".to_string());
            vec![bin]
        }
        "rust" => {
            env.insert(
                "CARGO_HOME".to_string(),
                keg.join("cargo").display().to_string(),
            );
            env.insert(
                "RUSTUP_HOME".to_string(),
                keg.join("rustup").display().to_string(),
            );
            vec![keg.join("cargo/bin").display().to_string(), bin]
        }
        "java" => {
            env.insert("JAVA_HOME".to_string(), keg_str);
            vec![bin]
        }
        "graalvm" => {
            env.insert("JAVA_HOME".to_string(), keg_str.clone());
            env.insert("GRAALVM_HOME".to_string(), keg_str);
            vec![bin]
        }
        "node" => {
            // See ensure_prebuilt: point node at an empty OpenSSL config in the
            // keg so its OpenSSL 3 uses built-in defaults under Seatbelt instead
            // of failing on the system config ("OpenSSL configuration error").
            env.insert(
                "OPENSSL_CONF".to_string(),
                keg.join("etc/openssl_sandbox.cnf").display().to_string(),
            );
            vec![bin]
        }
        // python, deno, bun, zig — bin only, no extra env.
        _ => vec![bin],
    };

    (path_dirs, env)
}

/// Build the [`KegManifest`] for a freshly-extracted prebuilt keg, keeping only
/// the `path_dirs` that exist on disk.
async fn build_manifest(
    language: &str,
    resolved_version: &str,
    url: &str,
    sha256: &str,
    keg: &Path,
) -> KegManifest {
    let (candidates, env) = keg_path_dirs_and_env(language, keg);

    let mut path_dirs = Vec::with_capacity(candidates.len());
    for dir in candidates {
        if tokio::fs::try_exists(&dir).await.unwrap_or(false) {
            path_dirs.push(dir);
        }
    }

    KegManifest {
        tool: language.to_string(),
        version: resolved_version.to_string(),
        arch: arch_token().to_string(),
        platform: "macos".to_string(),
        path_dirs,
        env,
        source: KegSource::Prebuilt {
            url: url.to_string(),
            sha256: sha256.to_string(),
        },
        build_deps: Vec::new(),
        provisioned_at: chrono::Utc::now().to_rfc3339(),
    }
}

// ---------------------------------------------------------------------------
// Architecture tokens
// ---------------------------------------------------------------------------

/// Host architecture token used in cache keys (`arm64` / `x86_64`), matching the
/// keg-dir convention in [`crate::source_build`].
fn arch_token() -> &'static str {
    match std::env::consts::ARCH {
        "aarch64" => "arm64",
        other => other,
    }
}

/// Host architecture token used in **vendor download URLs** (`arm64` / `amd64`).
fn host_arch() -> &'static str {
    if cfg!(target_arch = "aarch64") {
        "arm64"
    } else {
        "amd64"
    }
}

// ---------------------------------------------------------------------------
// Version resolution dispatch
// ---------------------------------------------------------------------------

/// Resolve a `(language, version, arch)` request to a [`PrebuiltResolution`].
async fn resolve_prebuilt_url(
    language: &str,
    version: &str,
    arch: &str,
) -> Result<PrebuiltResolution> {
    match language {
        "go" => resolve_go(version, arch).await,
        "node" => resolve_node(version, arch).await,
        "rust" => resolve_rust(version, arch).await,
        "python" => resolve_python(version, arch).await,
        "deno" => resolve_deno(version, arch).await,
        "bun" => resolve_bun(version, arch).await,
        "zig" => resolve_zig(version, arch).await,
        "java" => resolve_java(version, arch).await,
        "graalvm" => resolve_graalvm(version, arch).await,
        other => Err(ToolchainError::RegistryError {
            message: format!(
                "no prebuilt toolchain provisioner for '{other}'. \
                 Supported: go, node, rust, python, deno, bun, zig, java, graalvm."
            ),
        }),
    }
}

// ---------------------------------------------------------------------------
// Go resolver
// ---------------------------------------------------------------------------

/// Resolve a Go version to a download URL (exact / partial via go.dev API / latest).
///
/// The go.dev downloads JSON publishes a `sha256` per file (verified live:
/// `files[].{filename,os,arch,version,sha256,size,kind}`), so a best-effort
/// lookup pins the archive digest.
async fn resolve_go(version: &str, arch: &str) -> Result<PrebuiltResolution> {
    let resolved = if version == "latest" {
        resolve_go_version_from_api(version).await?
    } else if version.matches('.').count() < 2 {
        // Partial like "1.23": the go.dev API only lists the two most recent
        // series, so fall back to "{version}.0" (Go always ships a .0 release).
        resolve_go_version_from_api(version)
            .await
            .unwrap_or_else(|_| format!("{version}.0"))
    } else {
        version.to_string()
    };

    let filename = format!("go{resolved}.darwin-{arch}.tar.gz");
    let url = format!("https://go.dev/dl/{filename}");
    let sha256 = fetch_go_sha256(&filename).await;
    Ok(PrebuiltResolution {
        version: resolved,
        url,
        sha256,
    })
}

/// A single file entry from the go.dev downloads JSON (`files[]`), carrying the
/// published `sha256` for that archive.
#[derive(serde::Deserialize)]
struct GoFile {
    #[serde(default)]
    filename: String,
    #[serde(default)]
    sha256: String,
}

/// A go.dev release with its file list (superset of [`GoRelease`]).
#[derive(serde::Deserialize)]
struct GoReleaseFiles {
    #[serde(default)]
    files: Vec<GoFile>,
}

/// Best-effort: look up the published sha256 for a Go archive `filename` from
/// the go.dev downloads JSON. `None` when the version is too old to be listed or
/// the API is unreachable.
async fn fetch_go_sha256(filename: &str) -> Option<String> {
    let releases: Vec<GoReleaseFiles> = reqwest::get("https://go.dev/dl/?mode=json")
        .await
        .ok()?
        .json()
        .await
        .ok()?;
    for release in &releases {
        for file in &release.files {
            if file.filename == filename && is_hex_sha256(&file.sha256) {
                return Some(file.sha256.to_ascii_lowercase());
            }
        }
    }
    None
}

/// Fetch the Go downloads API and resolve a version prefix to a concrete version.
async fn resolve_go_version_from_api(version_prefix: &str) -> Result<String> {
    let api_url = "https://go.dev/dl/?mode=json";
    let response = reqwest::get(api_url)
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to fetch Go versions from {api_url}: {e}"),
        })?;

    let releases: Vec<GoRelease> =
        response
            .json()
            .await
            .map_err(|e| ToolchainError::RegistryError {
                message: format!("Failed to parse Go versions JSON: {e}"),
            })?;

    if version_prefix == "latest" {
        return releases
            .first()
            .map(|r| {
                r.version
                    .strip_prefix("go")
                    .unwrap_or(&r.version)
                    .to_string()
            })
            .ok_or_else(|| ToolchainError::RegistryError {
                message: "No Go releases found".to_string(),
            });
    }

    // Match "go1.23." (trailing dot) or exact "go1.23" to avoid "go1.23rc1".
    let prefix_dot = format!("go{version_prefix}.");
    let prefix_exact = format!("go{version_prefix}");
    for release in &releases {
        if (release.version.starts_with(&prefix_dot) || release.version == prefix_exact)
            && release.stable
        {
            return Ok(release
                .version
                .strip_prefix("go")
                .unwrap_or(&release.version)
                .to_string());
        }
    }

    for release in &releases {
        if release.version.starts_with(&prefix_dot) || release.version == prefix_exact {
            return Ok(release
                .version
                .strip_prefix("go")
                .unwrap_or(&release.version)
                .to_string());
        }
    }

    Err(ToolchainError::RegistryError {
        message: format!("No Go release found matching version '{version_prefix}'"),
    })
}

#[derive(serde::Deserialize)]
struct GoRelease {
    version: String,
    stable: bool,
}

// ---------------------------------------------------------------------------
// Node.js resolver
// ---------------------------------------------------------------------------

/// Resolve a Node.js version to a download URL.
///
/// Node publishes a `SHASUMS256.txt` per release directory (verified live: lines
/// are `<hex>  <filename>`), so a best-effort lookup pins the archive digest.
async fn resolve_node(version: &str, arch: &str) -> Result<PrebuiltResolution> {
    let node_arch = match arch {
        "arm64" => "arm64",
        _ => "x64",
    };

    // `latest`, the `lts` token, and a bare major (`24`) all carry no dot and are
    // resolved live against the dist index; a fully-pinned `24.18.0` is used as-is.
    let resolved = if version == "latest" || !version.contains('.') {
        resolve_node_version_from_api(version).await?
    } else {
        version.to_string()
    };

    let filename = format!("node-v{resolved}-darwin-{node_arch}.tar.gz");
    let url = format!("https://nodejs.org/dist/v{resolved}/{filename}");
    let shasums = format!("https://nodejs.org/dist/v{resolved}/SHASUMS256.txt");
    let sha256 = fetch_sha256_for(&shasums, &filename).await;
    Ok(PrebuiltResolution {
        version: resolved,
        url,
        sha256,
    })
}

/// Fetch the Node.js dist index and resolve a version prefix.
async fn resolve_node_version_from_api(version_prefix: &str) -> Result<String> {
    let api_url = "https://nodejs.org/dist/index.json";
    let response = reqwest::get(api_url)
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to fetch Node.js versions from {api_url}: {e}"),
        })?;

    let releases: Vec<NodeRelease> =
        response
            .json()
            .await
            .map_err(|e| ToolchainError::RegistryError {
                message: format!("Failed to parse Node.js versions JSON: {e}"),
            })?;

    if version_prefix == "latest" {
        return releases
            .first()
            .map(|r| {
                r.version
                    .strip_prefix('v')
                    .unwrap_or(&r.version)
                    .to_string()
            })
            .ok_or_else(|| ToolchainError::RegistryError {
                message: "No Node.js releases found".to_string(),
            });
    }

    // `node@lts` (version token "lts"): the newest Long-Term-Support line. Pick
    // the highest-semver release whose `lts` field is a truthy codename string —
    // derived LIVE from the dist index every run, NO hardcoded major (today that
    // resolves to v24.x "Krypton"; it moves to v26 when v26 enters LTS).
    if version_prefix == "lts" {
        return select_newest_node_lts(&releases).ok_or_else(|| ToolchainError::RegistryError {
            message: "No Node.js LTS release found in dist index".to_string(),
        });
    }

    // Find the latest version matching the major (e.g. "20" -> "20.18.1").
    let prefix = format!("v{version_prefix}");
    for release in &releases {
        if release.version.starts_with(&prefix)
            && release
                .version
                .chars()
                .nth(prefix.len())
                .is_none_or(|c| c == '.')
        {
            return Ok(release
                .version
                .strip_prefix('v')
                .unwrap_or(&release.version)
                .to_string());
        }
    }

    Err(ToolchainError::RegistryError {
        message: format!("No Node.js release found matching version '{version_prefix}'"),
    })
}

#[derive(serde::Deserialize)]
struct NodeRelease {
    version: String,
    /// The nodejs.org dist-index `lts` field: either the JSON boolean `false`
    /// (a "Current" line) or the LTS codename string (e.g. `"Krypton"`).
    /// Captured as `Some(codename)` for an LTS release, `None` otherwise.
    #[serde(default, deserialize_with = "deserialize_node_lts")]
    lts: Option<String>,
}

/// Deserialize the dist-index `lts` field, which is `false` for a non-LTS line
/// or a codename string for an LTS line. Maps the string case to `Some(codename)`
/// and every other shape (`false`, `null`, missing) to `None`.
fn deserialize_node_lts<'de, D>(deserializer: D) -> std::result::Result<Option<String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    use serde::Deserialize;
    Ok(match serde_json::Value::deserialize(deserializer)? {
        serde_json::Value::String(s) => Some(s),
        _ => None,
    })
}

/// Parse a `vX.Y.Z` Node.js version into a `(major, minor, patch)` tuple for
/// semver-ordered comparison; unparsable components sort as `0`.
fn parse_node_semver(version: &str) -> (u64, u64, u64) {
    let v = version.strip_prefix('v').unwrap_or(version);
    let mut parts = v.split('.').map(|p| p.parse::<u64>().unwrap_or(0));
    (
        parts.next().unwrap_or(0),
        parts.next().unwrap_or(0),
        parts.next().unwrap_or(0),
    )
}

/// From a parsed dist index, pick the newest LTS release's version (no `v`
/// prefix): the highest-semver entry whose `lts` is a truthy codename string.
/// Returns `None` when the index has no LTS line at all.
fn select_newest_node_lts(releases: &[NodeRelease]) -> Option<String> {
    releases
        .iter()
        .filter(|r| r.lts.is_some())
        .max_by_key(|r| parse_node_semver(&r.version))
        .map(|r| {
            r.version
                .strip_prefix('v')
                .unwrap_or(&r.version)
                .to_string()
        })
}

// ---------------------------------------------------------------------------
// Rust resolver
// ---------------------------------------------------------------------------

/// Resolve a Rust version to a download URL (exact / partial `.0` / latest channel).
///
/// The Rust dist server publishes a sibling `<archive>.sha256` (a `sha256sum`
/// line), so a best-effort GET of `{url}.sha256` pins the archive digest.
async fn resolve_rust(version: &str, arch: &str) -> Result<PrebuiltResolution> {
    let rust_target = match arch {
        "arm64" => "aarch64-apple-darwin",
        _ => "x86_64-apple-darwin",
    };

    let resolved = if version == "latest" {
        resolve_rust_latest_version().await?
    } else if version.matches('.').count() < 2 {
        // Rust always releases x.y.0 for each minor version.
        format!("{version}.0")
    } else {
        version.to_string()
    };

    let url = format!("https://static.rust-lang.org/dist/rust-{resolved}-{rust_target}.tar.gz");
    let sha256 = fetch_sha256_token(&format!("{url}.sha256")).await;
    Ok(PrebuiltResolution {
        version: resolved,
        url,
        sha256,
    })
}

/// Fetch the Rust stable channel TOML and extract the current stable version.
async fn resolve_rust_latest_version() -> Result<String> {
    let channel_url = "https://static.rust-lang.org/dist/channel-rust-stable.toml";
    let response = reqwest::get(channel_url)
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to fetch Rust stable channel from {channel_url}: {e}"),
        })?;

    let body = response
        .text()
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to read Rust stable channel response: {e}"),
        })?;

    let pkg_rust_pos = body
        .find("[pkg.rust]")
        .ok_or_else(|| ToolchainError::RegistryError {
            message: "Rust stable channel TOML missing [pkg.rust] section".to_string(),
        })?;

    let after_pkg = &body[pkg_rust_pos..];
    let version_prefix = "version = \"";
    let ver_start =
        after_pkg
            .find(version_prefix)
            .ok_or_else(|| ToolchainError::RegistryError {
                message: "No version field found in [pkg.rust] section".to_string(),
            })?
            + version_prefix.len();

    let ver_str: String = after_pkg[ver_start..]
        .chars()
        .take_while(|c| c.is_ascii_digit() || *c == '.')
        .collect();

    if ver_str.is_empty() {
        return Err(ToolchainError::RegistryError {
            message: "Failed to parse Rust version from stable channel".to_string(),
        });
    }

    debug!("Resolved Rust latest stable version: {ver_str}");
    Ok(ver_str)
}

// ---------------------------------------------------------------------------
// Python resolver
// ---------------------------------------------------------------------------

/// Resolve a Python version to a download URL via `astral-sh/python-build-standalone`.
async fn resolve_python(version: &str, arch: &str) -> Result<PrebuiltResolution> {
    let python_target = match arch {
        "arm64" => "aarch64-apple-darwin",
        _ => "x86_64-apple-darwin",
    };

    resolve_python_from_github(version, python_target).await
}

/// Fetch the `astral-sh/python-build-standalone` GitHub releases and find a
/// matching `install_only_stripped` asset for the requested version + target.
async fn resolve_python_from_github(
    version_prefix: &str,
    target: &str,
) -> Result<PrebuiltResolution> {
    let api_url =
        "https://api.github.com/repos/astral-sh/python-build-standalone/releases?per_page=25";

    let client = reqwest::Client::builder()
        .user_agent("zlayer")
        .build()
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to build HTTP client: {e}"),
        })?;

    let response = client
        .get(api_url)
        .send()
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to fetch Python releases from GitHub: {e}"),
        })?;

    if !response.status().is_success() {
        return Err(ToolchainError::RegistryError {
            message: format!(
                "GitHub API returned status {} fetching Python releases",
                response.status()
            ),
        });
    }

    let releases: Vec<GitHubRelease> =
        response
            .json()
            .await
            .map_err(|e| ToolchainError::RegistryError {
                message: format!("Failed to parse GitHub releases JSON: {e}"),
            })?;

    let target_suffix = format!("{target}-install_only_stripped.tar.gz");

    if version_prefix == "latest" {
        for release in &releases {
            for asset in &release.assets {
                if asset.name.starts_with("cpython-")
                    && asset.name.ends_with(&target_suffix)
                    && asset.name.contains("install_only")
                {
                    let py_version = extract_python_version_from_asset(&asset.name);
                    if !py_version.is_empty() {
                        debug!("Resolved Python latest to {py_version}");
                        let sha256 =
                            sibling_sha256(&release.assets, &format!("{}.sha256", asset.name))
                                .await;
                        return Ok(PrebuiltResolution {
                            version: py_version,
                            url: asset.browser_download_url.clone(),
                            sha256,
                        });
                    }
                }
            }
        }
        return Err(ToolchainError::RegistryError {
            message: format!(
                "No Python release found for target '{target}' in recent GitHub releases"
            ),
        });
    }

    let exact_prefix = format!("cpython-{version_prefix}+");
    let partial_prefix = format!("cpython-{version_prefix}.");

    for release in &releases {
        for asset in &release.assets {
            if !asset.name.ends_with(&target_suffix) {
                continue;
            }
            if asset.name.starts_with(&exact_prefix) || asset.name.starts_with(&partial_prefix) {
                let py_version = extract_python_version_from_asset(&asset.name);
                debug!("Resolved Python {version_prefix} to {py_version}");
                let sha256 =
                    sibling_sha256(&release.assets, &format!("{}.sha256", asset.name)).await;
                return Ok(PrebuiltResolution {
                    version: py_version,
                    url: asset.browser_download_url.clone(),
                    sha256,
                });
            }
        }
    }

    Err(ToolchainError::RegistryError {
        message: format!("No Python release found matching version '{version_prefix}'"),
    })
}

/// Extract the Python version from an asset name like
/// `cpython-3.12.8+20250106-aarch64-apple-darwin-install_only_stripped.tar.gz`.
fn extract_python_version_from_asset(asset_name: &str) -> String {
    asset_name
        .strip_prefix("cpython-")
        .and_then(|s| s.split('+').next())
        .unwrap_or("")
        .to_string()
}

#[derive(serde::Deserialize)]
struct GitHubRelease {
    /// Release tag (e.g. `v2.1.4`). Unused by the Python resolver (which keys on
    /// asset names) but read by the deno/bun/graalvm resolvers.
    tag_name: Option<String>,
    assets: Vec<GitHubAsset>,
}

#[derive(serde::Deserialize)]
struct GitHubAsset {
    name: String,
    browser_download_url: String,
}

// ---------------------------------------------------------------------------
// Deno resolver
// ---------------------------------------------------------------------------

/// Resolve a Deno version to a download URL (exact direct / partial+latest via API).
///
/// The exact-version path constructs the URL directly (no digest available →
/// compute-on-download); the API path additionally looks for a sibling
/// `deno-<target>.zip.sha256sum` asset.
async fn resolve_deno(version: &str, arch: &str) -> Result<PrebuiltResolution> {
    let deno_target = match arch {
        "arm64" => "aarch64-apple-darwin",
        _ => "x86_64-apple-darwin",
    };

    if version == "latest" || !version.contains('.') {
        resolve_deno_from_github(version, deno_target).await
    } else {
        let url = format!(
            "https://github.com/denoland/deno/releases/download/v{version}/deno-{deno_target}.zip"
        );
        Ok(PrebuiltResolution {
            version: version.to_string(),
            url,
            sha256: None,
        })
    }
}

/// Fetch the `denoland/deno` GitHub releases and find a matching release/asset.
async fn resolve_deno_from_github(
    version_prefix: &str,
    target: &str,
) -> Result<PrebuiltResolution> {
    let api_url = "https://api.github.com/repos/denoland/deno/releases?per_page=25";

    let client = reqwest::Client::builder()
        .user_agent("zlayer")
        .build()
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to build HTTP client: {e}"),
        })?;

    let response = client
        .get(api_url)
        .send()
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to fetch Deno releases from GitHub: {e}"),
        })?;

    if !response.status().is_success() {
        return Err(ToolchainError::RegistryError {
            message: format!(
                "GitHub API returned status {} fetching Deno releases",
                response.status()
            ),
        });
    }

    let releases: Vec<GitHubRelease> =
        response
            .json()
            .await
            .map_err(|e| ToolchainError::RegistryError {
                message: format!("Failed to parse GitHub releases JSON: {e}"),
            })?;

    let asset_name = format!("deno-{target}.zip");

    if version_prefix == "latest" {
        for release in &releases {
            for asset in &release.assets {
                if asset.name == asset_name {
                    let tag = release
                        .tag_name
                        .as_deref()
                        .unwrap_or("")
                        .strip_prefix('v')
                        .unwrap_or(release.tag_name.as_deref().unwrap_or(""));
                    if !tag.is_empty() {
                        debug!("Resolved Deno latest to {tag}");
                        let sha256 = deno_sibling_sha256(&release.assets, &asset_name).await;
                        return Ok(PrebuiltResolution {
                            version: tag.to_string(),
                            url: asset.browser_download_url.clone(),
                            sha256,
                        });
                    }
                }
            }
        }
        return Err(ToolchainError::RegistryError {
            message: format!(
                "No Deno release found for target '{target}' in recent GitHub releases"
            ),
        });
    }

    let tag_prefix = format!("v{version_prefix}.");
    for release in &releases {
        let tag = release.tag_name.as_deref().unwrap_or("");
        if tag.starts_with(&tag_prefix) {
            for asset in &release.assets {
                if asset.name == asset_name {
                    let ver = tag.strip_prefix('v').unwrap_or(tag);
                    debug!("Resolved Deno {version_prefix} to {ver} (partial)");
                    let sha256 = deno_sibling_sha256(&release.assets, &asset_name).await;
                    return Ok(PrebuiltResolution {
                        version: ver.to_string(),
                        url: asset.browser_download_url.clone(),
                        sha256,
                    });
                }
            }
        }
    }

    Err(ToolchainError::RegistryError {
        message: format!("No Deno release found matching version '{version_prefix}'"),
    })
}

/// Best-effort: find Deno's sibling checksum asset for `asset_name`. Deno
/// publishes `<asset>.sha256sum`; some releases use `<asset>.sha256`.
async fn deno_sibling_sha256(assets: &[GitHubAsset], asset_name: &str) -> Option<String> {
    if let Some(sha) = sibling_sha256(assets, &format!("{asset_name}.sha256sum")).await {
        return Some(sha);
    }
    sibling_sha256(assets, &format!("{asset_name}.sha256")).await
}

// ---------------------------------------------------------------------------
// Bun resolver
// ---------------------------------------------------------------------------

/// Resolve a Bun version to a download URL (exact direct / partial+latest via API).
///
/// Bun releases ship a `SHASUMS256.txt` asset; the API path looks up the digest
/// for the darwin archive there. The exact-version path has no digest available.
async fn resolve_bun(version: &str, arch: &str) -> Result<PrebuiltResolution> {
    let bun_arch = match arch {
        "arm64" => "aarch64",
        _ => "x64",
    };

    if version == "latest" || !version.contains('.') {
        resolve_bun_from_github(version, bun_arch).await
    } else {
        let url = format!(
            "https://github.com/oven-sh/bun/releases/download/bun-v{version}/bun-darwin-{bun_arch}.zip"
        );
        Ok(PrebuiltResolution {
            version: version.to_string(),
            url,
            sha256: None,
        })
    }
}

/// Fetch the `oven-sh/bun` GitHub releases and find a matching release.
async fn resolve_bun_from_github(
    version_prefix: &str,
    bun_arch: &str,
) -> Result<PrebuiltResolution> {
    let api_url = "https://api.github.com/repos/oven-sh/bun/releases?per_page=25";

    let client = reqwest::Client::builder()
        .user_agent("zlayer")
        .build()
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to build HTTP client: {e}"),
        })?;

    let response = client
        .get(api_url)
        .send()
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to fetch Bun releases from GitHub: {e}"),
        })?;

    if !response.status().is_success() {
        return Err(ToolchainError::RegistryError {
            message: format!(
                "GitHub API returned status {} fetching Bun releases",
                response.status()
            ),
        });
    }

    let releases: Vec<GitHubRelease> =
        response
            .json()
            .await
            .map_err(|e| ToolchainError::RegistryError {
                message: format!("Failed to parse GitHub releases JSON: {e}"),
            })?;

    let asset_name = format!("bun-darwin-{bun_arch}.zip");

    if version_prefix == "latest" {
        for release in &releases {
            let tag = release.tag_name.as_deref().unwrap_or("");
            let ver = tag
                .strip_prefix("bun-v")
                .unwrap_or(tag.strip_prefix('v').unwrap_or(tag));
            if ver.is_empty() {
                continue;
            }
            for asset in &release.assets {
                if asset.name == asset_name {
                    debug!("Resolved Bun latest to {ver}");
                    let sha256 = bun_sha256(&release.assets, &asset_name).await;
                    return Ok(PrebuiltResolution {
                        version: ver.to_string(),
                        url: asset.browser_download_url.clone(),
                        sha256,
                    });
                }
            }
        }
        return Err(ToolchainError::RegistryError {
            message: format!(
                "No Bun release found for arch '{bun_arch}' in recent GitHub releases"
            ),
        });
    }

    let tag_prefix = format!("bun-v{version_prefix}.");
    for release in &releases {
        let tag = release.tag_name.as_deref().unwrap_or("");
        if tag.starts_with(&tag_prefix) {
            for asset in &release.assets {
                if asset.name == asset_name {
                    let ver = tag.strip_prefix("bun-v").unwrap_or(tag);
                    debug!("Resolved Bun {version_prefix} to {ver} (partial)");
                    let sha256 = bun_sha256(&release.assets, &asset_name).await;
                    return Ok(PrebuiltResolution {
                        version: ver.to_string(),
                        url: asset.browser_download_url.clone(),
                        sha256,
                    });
                }
            }
        }
    }

    Err(ToolchainError::RegistryError {
        message: format!("No Bun release found matching version '{version_prefix}'"),
    })
}

/// Best-effort: read Bun's `SHASUMS256.txt` release asset and return the digest
/// for `asset_name` (falling back to a sibling `<asset>.sha256` if present).
async fn bun_sha256(assets: &[GitHubAsset], asset_name: &str) -> Option<String> {
    if let Some(shasums) = assets.iter().find(|a| a.name == "SHASUMS256.txt") {
        if let Some(sha) = fetch_sha256_for(&shasums.browser_download_url, asset_name).await {
            return Some(sha);
        }
    }
    sibling_sha256(assets, &format!("{asset_name}.sha256")).await
}

// ---------------------------------------------------------------------------
// Zig resolver
// ---------------------------------------------------------------------------

/// A single platform entry from the Zig download index. The index publishes the
/// tarball's sha256 in `shasum` alongside the `tarball` URL.
#[derive(serde::Deserialize)]
struct ZigDownloadInfo {
    tarball: String,
    #[serde(default)]
    shasum: String,
}

/// Resolve a Zig version to a download URL via `ziglang.org/download/index.json`.
async fn resolve_zig(version: &str, arch: &str) -> Result<PrebuiltResolution> {
    let platform_key = match arch {
        "arm64" => "aarch64-macos",
        _ => "x86_64-macos",
    };

    let index_url = "https://ziglang.org/download/index.json";
    let response = reqwest::get(index_url)
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to fetch Zig download index from {index_url}: {e}"),
        })?;

    let index: HashMap<String, serde_json::Value> =
        response
            .json()
            .await
            .map_err(|e| ToolchainError::RegistryError {
                message: format!("Failed to parse Zig download index JSON: {e}"),
            })?;

    let resolved = if version == "latest" {
        let mut versions: Vec<&String> = index.keys().filter(|k| *k != "master").collect();
        versions.sort_by(|a, b| compare_version_strings(b, a));
        versions
            .first()
            .map(|v| (*v).clone())
            .ok_or_else(|| ToolchainError::RegistryError {
                message: "No stable Zig versions found in download index".to_string(),
            })?
    } else if index.contains_key(version) {
        version.to_string()
    } else {
        let prefix = format!("{version}.");
        let mut candidates: Vec<&String> = index
            .keys()
            .filter(|k| *k != "master" && k.starts_with(&prefix))
            .collect();
        candidates.sort_by(|a, b| compare_version_strings(b, a));
        candidates
            .first()
            .map(|v| (*v).clone())
            .ok_or_else(|| ToolchainError::RegistryError {
                message: format!("No Zig version found matching '{version}'"),
            })?
    };

    let version_data = index
        .get(&resolved)
        .ok_or_else(|| ToolchainError::RegistryError {
            message: format!("Zig version '{resolved}' not found in download index"),
        })?;

    let platform_data =
        version_data
            .get(platform_key)
            .ok_or_else(|| ToolchainError::RegistryError {
                message: format!(
                    "No Zig download found for platform '{platform_key}' in version '{resolved}'"
                ),
            })?;

    let info: ZigDownloadInfo = serde_json::from_value(platform_data.clone()).map_err(|e| {
        ToolchainError::RegistryError {
            message: format!(
                "Failed to parse Zig download info for {platform_key}/{resolved}: {e}"
            ),
        }
    })?;

    debug!("Resolved Zig {version} to {resolved}: {}", info.tarball);
    let sha256 = is_hex_sha256(&info.shasum).then(|| info.shasum.to_ascii_lowercase());
    Ok(PrebuiltResolution {
        version: resolved,
        url: info.tarball,
        sha256,
    })
}

/// Compare two dotted version strings numerically for descending-sort selection.
fn compare_version_strings(a: &str, b: &str) -> std::cmp::Ordering {
    let a_parts: Vec<&str> = a.split('.').collect();
    let b_parts: Vec<&str> = b.split('.').collect();
    for (ap, bp) in a_parts.iter().zip(b_parts.iter()) {
        let ord = match (ap.parse::<u64>(), bp.parse::<u64>()) {
            (Ok(an), Ok(bn)) => an.cmp(&bn),
            _ => ap.cmp(bp),
        };
        if ord != std::cmp::Ordering::Equal {
            return ord;
        }
    }
    a_parts.len().cmp(&b_parts.len())
}

// ---------------------------------------------------------------------------
// Java (Adoptium/Temurin) resolver
// ---------------------------------------------------------------------------

/// Response from the Adoptium available releases API.
#[derive(serde::Deserialize)]
struct AdoptiumAvailableReleases {
    /// The most recent LTS feature version (e.g. 21).
    most_recent_lts: u32,
}

/// Resolve a Java (Adoptium/Temurin) version to a download URL.
///
/// The Adoptium `binary/latest` endpoint is a redirect to the JDK archive and
/// exposes no inline digest, so the sha256 is `None` (computed on download).
async fn resolve_java(version: &str, arch: &str) -> Result<PrebuiltResolution> {
    let adoptium_arch = match arch {
        "arm64" => "aarch64",
        _ => "x64",
    };

    let feature_version = if version == "latest" {
        resolve_java_latest_lts().await?
    } else {
        // Adoptium expects the major feature version only (e.g. "21" not "21.0.5").
        version.split('.').next().unwrap_or(version).to_string()
    };

    let url = format!(
        "https://api.adoptium.net/v3/binary/latest/{feature_version}/ga/mac/{adoptium_arch}/jdk/hotspot/normal/eclipse"
    );

    Ok(PrebuiltResolution {
        version: feature_version,
        url,
        sha256: None,
    })
}

/// Fetch the Adoptium available releases API and return the most recent LTS.
async fn resolve_java_latest_lts() -> Result<String> {
    let api_url = "https://api.adoptium.net/v3/info/available_releases";
    let response = reqwest::get(api_url)
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to fetch Adoptium available releases from {api_url}: {e}"),
        })?;

    if !response.status().is_success() {
        return Err(ToolchainError::RegistryError {
            message: format!(
                "Adoptium API returned status {} fetching available releases",
                response.status()
            ),
        });
    }

    let releases: AdoptiumAvailableReleases =
        response
            .json()
            .await
            .map_err(|e| ToolchainError::RegistryError {
                message: format!("Failed to parse Adoptium available releases JSON: {e}"),
            })?;

    let version = releases.most_recent_lts.to_string();
    debug!("Resolved Java latest LTS to feature version {version}");
    Ok(version)
}

// ---------------------------------------------------------------------------
// GraalVM CE resolver
// ---------------------------------------------------------------------------

/// Resolve a `GraalVM` CE version to a download URL.
///
/// The API path additionally looks for a sibling `<archive>.sha256` asset. The
/// exact-version path constructs the URL directly (digest computed on download).
async fn resolve_graalvm(version: &str, arch: &str) -> Result<PrebuiltResolution> {
    let graalvm_arch = match arch {
        "arm64" => "aarch64",
        _ => "x64",
    };

    if version == "latest" || !version.contains('.') {
        resolve_graalvm_from_github(version, graalvm_arch).await
    } else {
        let url = format!(
            "https://github.com/graalvm/graalvm-ce-builds/releases/download/\
             jdk-{version}/graalvm-community-jdk-{version}_macos-{graalvm_arch}_bin.tar.gz"
        );
        Ok(PrebuiltResolution {
            version: version.to_string(),
            url,
            sha256: None,
        })
    }
}

/// Fetch the `graalvm/graalvm-ce-builds` GitHub releases and find a match.
async fn resolve_graalvm_from_github(
    version_prefix: &str,
    graalvm_arch: &str,
) -> Result<PrebuiltResolution> {
    let api_url = "https://api.github.com/repos/graalvm/graalvm-ce-builds/releases?per_page=25";

    let client = reqwest::Client::builder()
        .user_agent("zlayer")
        .build()
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to build HTTP client: {e}"),
        })?;

    let response = client
        .get(api_url)
        .send()
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("Failed to fetch GraalVM releases from GitHub: {e}"),
        })?;

    if !response.status().is_success() {
        return Err(ToolchainError::RegistryError {
            message: format!(
                "GitHub API returned status {} fetching GraalVM releases",
                response.status()
            ),
        });
    }

    let releases: Vec<GitHubRelease> =
        response
            .json()
            .await
            .map_err(|e| ToolchainError::RegistryError {
                message: format!("Failed to parse GitHub releases JSON: {e}"),
            })?;

    if version_prefix == "latest" {
        for release in &releases {
            let tag = release.tag_name.as_deref().unwrap_or("");
            if let Some(jdk_version) = tag.strip_prefix("jdk-") {
                if jdk_version.is_empty() {
                    continue;
                }
                let filename =
                    format!("graalvm-community-jdk-{jdk_version}_macos-{graalvm_arch}_bin.tar.gz");
                let url = format!(
                    "https://github.com/graalvm/graalvm-ce-builds/releases/download/{tag}/{filename}"
                );
                debug!("Resolved GraalVM latest to {jdk_version}");
                let sha256 = sibling_sha256(&release.assets, &format!("{filename}.sha256")).await;
                return Ok(PrebuiltResolution {
                    version: jdk_version.to_string(),
                    url,
                    sha256,
                });
            }
        }
        return Err(ToolchainError::RegistryError {
            message: "No GraalVM CE release found in recent GitHub releases".to_string(),
        });
    }

    let tag_prefix = format!("jdk-{version_prefix}.");
    for release in &releases {
        let tag = release.tag_name.as_deref().unwrap_or("");
        if tag.starts_with(&tag_prefix) {
            if let Some(jdk_version) = tag.strip_prefix("jdk-") {
                let filename =
                    format!("graalvm-community-jdk-{jdk_version}_macos-{graalvm_arch}_bin.tar.gz");
                let url = format!(
                    "https://github.com/graalvm/graalvm-ce-builds/releases/download/{tag}/{filename}"
                );
                debug!("Resolved GraalVM {version_prefix} to {jdk_version} (partial)");
                let sha256 = sibling_sha256(&release.assets, &format!("{filename}.sha256")).await;
                return Ok(PrebuiltResolution {
                    version: jdk_version.to_string(),
                    url,
                    sha256,
                });
            }
        }
    }

    Err(ToolchainError::RegistryError {
        message: format!("No GraalVM CE release found matching version '{version_prefix}'"),
    })
}

// ---------------------------------------------------------------------------
// Download + extraction
// ---------------------------------------------------------------------------

/// `true` when `s` is a 64-char lowercase/uppercase hex sha256.
fn is_hex_sha256(s: &str) -> bool {
    s.len() == 64 && s.chars().all(|c| c.is_ascii_hexdigit())
}

/// Best-effort: GET `url` and return its first whitespace token when it is a
/// hex sha256. Handles both bare-digest bodies (`<hex>`) and `sha256sum`-style
/// bodies (`<hex>  <file>`). Returns `None` on any failure — the caller then
/// records the digest computed on download instead.
async fn fetch_sha256_token(url: &str) -> Option<String> {
    let text = reqwest::get(url).await.ok()?.text().await.ok()?;
    let token = text.split_whitespace().next()?;
    is_hex_sha256(token).then(|| token.to_ascii_lowercase())
}

/// Best-effort: GET a `sha256sum`-format checksums file at `url` and return the
/// digest whose filename column equals `filename`. Returns `None` on any
/// failure.
async fn fetch_sha256_for(url: &str, filename: &str) -> Option<String> {
    let text = reqwest::get(url).await.ok()?.text().await.ok()?;
    for line in text.lines() {
        let mut cols = line.split_whitespace();
        if let (Some(hash), Some(name)) = (cols.next(), cols.next()) {
            // `sha256sum` writes "hash  name" or "hash *name" (binary marker).
            let name = name.strip_prefix('*').unwrap_or(name);
            if name == filename && is_hex_sha256(hash) {
                return Some(hash.to_ascii_lowercase());
            }
        }
    }
    None
}

/// Best-effort: find a sibling checksum asset in `assets` named exactly
/// `sibling` (e.g. `<artifact>.sha256`), fetch it, and return the hex token.
async fn sibling_sha256(assets: &[GitHubAsset], sibling: &str) -> Option<String> {
    let asset = assets.iter().find(|a| a.name == sibling)?;
    fetch_sha256_token(&asset.browser_download_url).await
}

/// Extract a toolchain archive into the keg root with the canonical per-language
/// layout, so that `<keg>/bin/<primary-binary>` ends up directly runnable.
///
/// Several arms issue an identical `tar xzf … --strip-components=1` (the
/// per-language branches are kept distinct for clarity and future divergence),
/// so `match_same_arms` is intentionally allowed here.
#[allow(clippy::too_many_lines, clippy::match_same_arms)]
async fn extract_toolchain(language: &str, archive: &Path, target_dir: &Path) -> Result<()> {
    let archive_str = archive.display().to_string();
    let target_str = target_dir.display().to_string();

    let output = match language {
        "go" | "node" => {
            // go/ and node-v.../ both strip their single top-level dir.
            tokio::process::Command::new("tar")
                .args([
                    "xzf",
                    &archive_str,
                    "-C",
                    &target_str,
                    "--strip-components=1",
                ])
                .output()
                .await?
        }
        "rust" => {
            // Rust standalone ships an installer. Extract to a temp dir, then run
            // install.sh --prefix=<keg> to land rustc/cargo into <keg>/bin.
            let extract_tmp = target_dir.join("_extract");
            tokio::fs::create_dir_all(&extract_tmp).await?;
            let extract_tmp_str = extract_tmp.display().to_string();

            let tar_out = tokio::process::Command::new("tar")
                .args([
                    "xzf",
                    &archive_str,
                    "-C",
                    &extract_tmp_str,
                    "--strip-components=1",
                ])
                .output()
                .await?;

            if !tar_out.status.success() {
                let stderr = String::from_utf8_lossy(&tar_out.stderr);
                let _ = tokio::process::Command::new("chmod")
                    .args(["-R", "u+w"])
                    .arg(&extract_tmp)
                    .status()
                    .await;
                let _ = tokio::process::Command::new("rm")
                    .args(["-rf"])
                    .arg(&extract_tmp)
                    .status()
                    .await;
                return Err(ToolchainError::RegistryError {
                    message: format!("Failed to extract Rust tarball: {stderr}"),
                });
            }

            let install_sh = extract_tmp.join("install.sh");
            let install_out = tokio::process::Command::new("sh")
                .arg(install_sh.display().to_string())
                .arg(format!("--prefix={target_str}"))
                .arg("--disable-ldconfig")
                .output()
                .await?;

            let _ = tokio::process::Command::new("chmod")
                .args(["-R", "u+w"])
                .arg(&extract_tmp)
                .status()
                .await;
            let _ = tokio::process::Command::new("rm")
                .args(["-rf"])
                .arg(&extract_tmp)
                .status()
                .await;

            if !install_out.status.success() {
                let stderr = String::from_utf8_lossy(&install_out.stderr);
                return Err(ToolchainError::RegistryError {
                    message: format!("Rust install.sh failed: {stderr}"),
                });
            }

            return Ok(());
        }
        "deno" => {
            // Deno zip holds a single `deno` binary — move it into bin/.
            let out = tokio::process::Command::new("unzip")
                .args(["-o", &archive_str, "-d", &target_str])
                .output()
                .await?;
            if out.status.success() {
                let bin_dir = target_dir.join("bin");
                tokio::fs::create_dir_all(&bin_dir).await?;
                let deno_binary = target_dir.join("deno");
                if deno_binary.exists() {
                    tokio::fs::rename(&deno_binary, bin_dir.join("deno")).await?;
                }
            }
            out
        }
        "zig" => {
            // Zig .tar.xz extracts as zig-macos-{arch}-{ver}/ with `zig` + lib/
            // directly (no bin/). Strip the top dir, then make bin/zig -> ../zig.
            let out = tokio::process::Command::new("tar")
                .args([
                    "xJf",
                    &archive_str,
                    "-C",
                    &target_str,
                    "--strip-components=1",
                ])
                .output()
                .await?;
            if out.status.success() {
                let bin_dir = target_dir.join("bin");
                tokio::fs::create_dir_all(&bin_dir).await?;
                let zig_binary = target_dir.join("zig");
                if zig_binary.exists() && !bin_dir.join("zig").exists() {
                    // `bin/zig` -> `../zig`. `tokio::fs::symlink` is Unix-only;
                    // this Zig-on-macOS path never runs on Windows but must still
                    // COMPILE there (all non-cfg'd code is type-checked per target),
                    // so fall back to a copy on Windows.
                    #[cfg(unix)]
                    tokio::fs::symlink(Path::new("../zig"), &bin_dir.join("zig")).await?;
                    #[cfg(windows)]
                    {
                        tokio::fs::copy(&zig_binary, bin_dir.join("zig")).await?;
                    }
                }
            }
            out
        }
        "java" | "graalvm" => {
            // Adoptium/GraalVM macOS tarballs nest under
            // jdk-X/Contents/Home/... — strip 3 to reach the JDK root.
            tokio::process::Command::new("tar")
                .args([
                    "xzf",
                    &archive_str,
                    "-C",
                    &target_str,
                    "--strip-components=3",
                ])
                .output()
                .await?
        }
        "bun" => {
            // Bun zip extracts as bun-darwin-{arch}/bun — move into bin/.
            let out = tokio::process::Command::new("unzip")
                .args(["-o", &archive_str, "-d", &target_str])
                .output()
                .await?;
            if out.status.success() {
                let bin_dir = target_dir.join("bin");
                tokio::fs::create_dir_all(&bin_dir).await?;
                if let Ok(mut entries) = tokio::fs::read_dir(target_dir).await {
                    while let Ok(Some(entry)) = entries.next_entry().await {
                        if entry.file_name().to_string_lossy().starts_with("bun-") {
                            let bun_binary = entry.path().join("bun");
                            if bun_binary.exists() {
                                tokio::fs::rename(&bun_binary, bin_dir.join("bun")).await?;
                                let _ = tokio::process::Command::new("chmod")
                                    .args(["-R", "u+w"])
                                    .arg(entry.path())
                                    .status()
                                    .await;
                                let _ = tokio::process::Command::new("rm")
                                    .args(["-rf"])
                                    .arg(entry.path())
                                    .status()
                                    .await;
                            }
                        }
                    }
                }
            }
            out
        }
        // python (install_only_stripped) and any other tar.gz: strip the top dir.
        _ => {
            tokio::process::Command::new("tar")
                .args([
                    "xzf",
                    &archive_str,
                    "-C",
                    &target_str,
                    "--strip-components=1",
                ])
                .output()
                .await?
        }
    };

    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        return Err(ToolchainError::RegistryError {
            message: format!("Failed to extract {language} toolchain: {stderr}"),
        });
    }

    Ok(())
}

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

    #[test]
    fn is_prebuilt_accepts_languages_and_aliases() {
        for f in [
            "go",
            "golang",
            "node",
            "nodejs",
            "rust",
            "python",
            "python3",
            "python@3.12",
            "deno",
            "bun",
            "zig",
            "java",
            "openjdk",
            "openjdk@17",
            "node@22",
            "graalvm",
            "graalvm-ce",
            "graalvm-community",
        ] {
            assert!(is_prebuilt_formula(f), "{f} should be a prebuilt formula");
        }
    }

    #[test]
    fn is_prebuilt_rejects_non_languages_and_swift() {
        for f in ["swift", "git", "jq", "cmake", "ripgrep", "openssl@3"] {
            assert!(
                !is_prebuilt_formula(f),
                "{f} should NOT be a prebuilt formula"
            );
        }
    }

    #[test]
    fn formula_split_maps_language_and_version() {
        assert_eq!(
            formula_language_version("python@3.12"),
            ("python".to_string(), "3.12".to_string())
        );
        assert_eq!(
            formula_language_version("node@22"),
            ("node".to_string(), "22".to_string())
        );
        assert_eq!(
            formula_language_version("go"),
            ("go".to_string(), "latest".to_string())
        );
        assert_eq!(
            formula_language_version("golang"),
            ("go".to_string(), "latest".to_string())
        );
        assert_eq!(
            formula_language_version("openjdk@17"),
            ("java".to_string(), "17".to_string())
        );
        assert_eq!(
            formula_language_version("python3"),
            ("python".to_string(), "latest".to_string())
        );
        assert_eq!(
            formula_language_version("graalvm-ce"),
            ("graalvm".to_string(), "latest".to_string())
        );
        assert_eq!(
            formula_language_version("nodejs"),
            ("node".to_string(), "latest".to_string())
        );
    }

    #[test]
    fn node_lts_selection_picks_highest_lts_codename() {
        // Shape mirrors nodejs.org/dist/index.json: Current lines carry `lts:false`,
        // LTS lines carry the codename string. Newest LTS here is v24.18.0.
        let json = r#"[
            {"version":"v26.0.0","lts":false},
            {"version":"v25.2.0","lts":false},
            {"version":"v24.18.0","lts":"Krypton"},
            {"version":"v22.20.0","lts":"Jod"},
            {"version":"v20.19.0","lts":"Iron"}
        ]"#;
        let releases: Vec<NodeRelease> = serde_json::from_str(json).unwrap();
        assert_eq!(
            select_newest_node_lts(&releases).as_deref(),
            Some("24.18.0"),
            "LTS resolver must pick the newest line whose lts is a codename string"
        );
    }

    #[test]
    fn node_lts_selection_is_none_when_no_lts_line() {
        let json = r#"[{"version":"v26.0.0","lts":false},{"version":"v25.2.0","lts":false}]"#;
        let releases: Vec<NodeRelease> = serde_json::from_str(json).unwrap();
        assert_eq!(select_newest_node_lts(&releases), None);
    }

    #[test]
    fn node_lts_token_is_a_prebuilt_node_formula() {
        // `node@lts` must classify as a node prebuilt formula and split to the
        // ("node", "lts") language/version pair the resolver branches on.
        assert!(is_prebuilt_formula("node@lts"));
        assert_eq!(
            formula_language_version("node@lts"),
            ("node".to_string(), "lts".to_string())
        );
    }

    #[test]
    fn go_keg_layout_sets_goroot_and_bin() {
        let keg = Path::new("/cache/go-1.23.6-arm64");
        let (path_dirs, env) = keg_path_dirs_and_env("go", keg);
        assert_eq!(path_dirs, vec!["/cache/go-1.23.6-arm64/bin".to_string()]);
        assert_eq!(
            env.get("GOROOT").map(String::as_str),
            Some("/cache/go-1.23.6-arm64")
        );
        assert_eq!(
            env.get("GOFLAGS").map(String::as_str),
            Some("-buildvcs=false")
        );
    }

    #[test]
    fn rust_keg_layout_sets_cargo_and_rustup_homes() {
        let keg = Path::new("/cache/rust-1.82.0-arm64");
        let (path_dirs, env) = keg_path_dirs_and_env("rust", keg);
        assert_eq!(
            path_dirs,
            vec![
                "/cache/rust-1.82.0-arm64/cargo/bin".to_string(),
                "/cache/rust-1.82.0-arm64/bin".to_string(),
            ]
        );
        assert_eq!(
            env.get("CARGO_HOME").map(String::as_str),
            Some("/cache/rust-1.82.0-arm64/cargo")
        );
        assert_eq!(
            env.get("RUSTUP_HOME").map(String::as_str),
            Some("/cache/rust-1.82.0-arm64/rustup")
        );
    }

    #[test]
    fn graalvm_keg_layout_sets_both_homes() {
        let keg = Path::new("/cache/graalvm-21.0.5-arm64");
        let (_, env) = keg_path_dirs_and_env("graalvm", keg);
        assert_eq!(
            env.get("JAVA_HOME").map(String::as_str),
            Some("/cache/graalvm-21.0.5-arm64")
        );
        assert_eq!(
            env.get("GRAALVM_HOME").map(String::as_str),
            Some("/cache/graalvm-21.0.5-arm64")
        );
    }

    #[test]
    fn node_keg_layout_sets_openssl_conf() {
        let keg = Path::new("/cache/node-22.1.0-arm64");
        let (path_dirs, env) = keg_path_dirs_and_env("node", keg);
        assert_eq!(path_dirs, vec!["/cache/node-22.1.0-arm64/bin".to_string()]);
        // node's bundled OpenSSL 3 fails to load the system openssl config under
        // the Seatbelt sandbox; point it at an empty in-keg config so it uses
        // built-in defaults (TLS still works via node's bundled root CAs).
        assert_eq!(
            env.get("OPENSSL_CONF").map(String::as_str),
            Some("/cache/node-22.1.0-arm64/etc/openssl_sandbox.cnf")
        );
    }

    #[test]
    fn python_version_extracted_from_asset_name() {
        assert_eq!(
            extract_python_version_from_asset(
                "cpython-3.12.8+20250106-aarch64-apple-darwin-install_only_stripped.tar.gz"
            ),
            "3.12.8"
        );
        assert_eq!(extract_python_version_from_asset("cpython-"), "");
        assert_eq!(extract_python_version_from_asset("not-cpython"), "");
    }

    #[test]
    fn version_strings_compare_numerically() {
        use std::cmp::Ordering;
        assert_eq!(
            compare_version_strings("0.14.0", "0.13.0"),
            Ordering::Greater
        );
        assert_eq!(
            compare_version_strings("1.0.0", "0.14.0"),
            Ordering::Greater
        );
        assert_eq!(
            compare_version_strings("0.14.1", "0.14.0"),
            Ordering::Greater
        );
        assert_eq!(compare_version_strings("0.14.0", "0.14.0"), Ordering::Equal);
    }

    // Pure (no-network) exact-URL resolution tests — modeled on the
    // macos_toolchain exact-URL tests. Exact versions construct the URL directly
    // without any API call.

    #[tokio::test]
    async fn resolve_deno_exact_url() {
        let r = resolve_deno("2.1.4", "arm64").await.unwrap();
        assert_eq!(r.version, "2.1.4");
        assert_eq!(
            r.url,
            "https://github.com/denoland/deno/releases/download/v2.1.4/deno-aarch64-apple-darwin.zip"
        );
        // Exact path: no digest is fetched (compute-on-download).
        assert!(r.sha256.is_none());
    }

    #[tokio::test]
    async fn resolve_bun_exact_url() {
        let r = resolve_bun("1.2.3", "arm64").await.unwrap();
        assert_eq!(r.version, "1.2.3");
        assert_eq!(
            r.url,
            "https://github.com/oven-sh/bun/releases/download/bun-v1.2.3/bun-darwin-aarch64.zip"
        );
        assert!(r.sha256.is_none());
    }

    #[tokio::test]
    async fn resolve_graalvm_exact_url() {
        let r = resolve_graalvm("21.0.5", "arm64").await.unwrap();
        assert_eq!(r.version, "21.0.5");
        assert_eq!(
            r.url,
            "https://github.com/graalvm/graalvm-ce-builds/releases/download/\
             jdk-21.0.5/graalvm-community-jdk-21.0.5_macos-aarch64_bin.tar.gz"
        );
        assert!(r.sha256.is_none());
    }

    #[tokio::test]
    async fn resolve_java_exact_url_strips_to_major() {
        let r = resolve_java("21.0.5", "arm64").await.unwrap();
        assert_eq!(r.version, "21");
        assert_eq!(
            r.url,
            "https://api.adoptium.net/v3/binary/latest/21/ga/mac/aarch64/jdk/hotspot/normal/eclipse"
        );
        assert!(r.sha256.is_none());
    }

    #[test]
    fn zig_download_info_parses_shasum() {
        let info: ZigDownloadInfo = serde_json::from_str(
            r#"{"tarball":"https://ziglang.org/x.tar.xz","shasum":"aa","size":"1"}"#,
        )
        .unwrap();
        assert_eq!(info.tarball, "https://ziglang.org/x.tar.xz");
        assert_eq!(info.shasum, "aa");
    }

    #[test]
    fn hex_sha256_validation() {
        assert!(is_hex_sha256(
            "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
        ));
        assert!(!is_hex_sha256("tooshort"));
        assert!(!is_hex_sha256(
            "zz4d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
        ));
    }
}