zlayer_toolchain/

lib.rs

//! `zlayer-toolchain` — reusable runtime toolchain provisioning.
//!
//! This is a **leaf** crate: it depends only on other leaf crates
//! (`zlayer-paths`, `zlayer-registry`, `zlayer-types`) and external crates. It
//! depends on neither `zlayer-agent` nor `zlayer-builder`. It exists to break
//! the `zlayer-builder` -> `zlayer-agent` build cycle: the macOS sandboxes
//! (Seatbelt / HCS) have no package manager, so this crate is "our apt-get" —
//! it provisions a named tool into a self-contained, absolute-prefix **keg** and
//! returns a [`ToolchainHandle`] describing how to run it.
//!
//! # Provisioning strategy (macOS)
//!
//! A keg is produced one of two ways, both relocation-free (no `@@HOMEBREW@@`):
//! - **Source build** ([`source_build`]): fetch the Homebrew formula's
//!   `urls.stable.url` source tarball and build it at an absolute keg prefix
//!   with the host Command Line Tools (the homebrew-core C-tool population:
//!   git, jq, cmake, ...).
//! - **Prebuilt fetch** ([`prebuilt`]): land a self-contained vendor archive
//!   for the language toolchains (go/node/rust/...).
//!
//! Every keg carries a [`manifest::KegManifest`] (`toolchain.json`) describing
//! its `path_dirs` + `env`, so the resolver is generic — no tool is special-
//! cased on the handle path.
//!
//! # Surface
//!
//! - [`ensure_toolchain`] — provision a named tool and return a
//!   [`ToolchainHandle`].
//! - [`probe_ready_toolchain`] — non-blocking, filesystem-only `.ready` probe
//!   that reconstructs a handle from an already-provisioned keg.
//!
//! The old Homebrew **bottle** resolver/installer (download a prebuilt bottle
//! and rewrite its `@@HOMEBREW@@` install-name placeholders) has been removed
//! entirely — see the module docs on [`source_build`] for why that path was a
//! dead end under Seatbelt.

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

pub mod brew_emulate;
pub mod error;
pub mod formula;
pub mod lockfile;
pub mod manifest;
pub mod package_index;
pub mod prebuilt;
pub mod source_build;
pub mod windows;

pub use error::{Result, ToolchainError};
pub use lockfile::{LockedTool, ToolchainLockfile, ToolchainLockfileExt, LOCKFILE_NAME};

/// Target platform for a toolchain provisioning request.
///
/// Both platforms provision into the same keg format. macOS goes through
/// source-build / prebuilt-fetch / brew-emulate ([`ensure_macos_keg`]); Windows
/// goes through MinGit / portable-artifact extraction ([`windows`]). A Windows
/// formula with no relocatable portable artifact returns
/// [`ToolchainError::NotImplemented`] so the caller routes it to the HCS
/// choco-capture path in the runtime layer.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ToolPlatform {
    /// macOS host — provision via source build / prebuilt fetch into a keg.
    MacOS,
    /// Windows host — provision via MinGit / portable artifact into a keg.
    Windows,
}

/// A provisioned toolchain: where it lives and how to run it.
///
/// `path_dirs` are absolute directories to prepend to `PATH`; `env` are extra
/// environment variables the caller should set so the tool resolves its own
/// libraries / exec helpers out of the keg instead of the host. Both are a
/// direct projection of the keg's [`manifest::KegManifest`].
#[derive(Debug, Clone)]
pub struct ToolchainHandle {
    /// Root directory of the provisioned keg (the cache key dir).
    pub install_dir: PathBuf,
    /// Absolute directories to prepend to `PATH`.
    pub path_dirs: Vec<String>,
    /// Extra environment variables for running the tool.
    pub env: HashMap<String, String>,
}

/// Host architecture token used in cache keys (`arm64` / `x86_64`).
fn arch_token() -> &'static str {
    match std::env::consts::ARCH {
        "aarch64" => "arm64",
        other => other,
    }
}

/// Split a package request into `(formula, version_token)`.
///
/// `git` -> `("git", "latest")`; `openssl@3` -> `("openssl@3", "3")`. The full
/// `pkg` is always the brew formula name (brew versioned formulae keep their
/// `@major` suffix); the version token only feeds the cache key.
fn split_pkg(pkg: &str) -> (&str, &str) {
    match pkg.split_once('@') {
        Some((_, ver)) if !ver.is_empty() => (pkg, ver),
        _ => (pkg, "latest"),
    }
}

/// Ensure a runtime tool is provisioned and return a handle describing how to
/// run it.
///
/// The install is idempotent: the keg lives at
/// `{cache_dir}/{formula}-{version}-{arch}` and is guarded by a `.ready` marker
/// (written after the [`manifest::KegManifest`]), so a populated cache
/// short-circuits without any network or build work.
///
/// # Errors
///
/// Returns [`ToolchainError::NotImplemented`] for a Windows formula with no
/// portable artifact (the caller routes those to the HCS choco-capture path).
/// Propagates formula-resolution, download, dependency and build errors.
/// When `lockfile` is `Some`, a lock hit for `(pkg, platform, arch)` pins the
/// exact version + URL and the download is verified against the pinned sha256
/// ("consume-only": this crate never *writes* the lock — the CLI does). A lock
/// miss live-resolves and records the resolved digest in the keg manifest.
pub async fn ensure_toolchain(
    pkg: &str,
    platform: ToolPlatform,
    cache_dir: &Path,
    lockfile: Option<&ToolchainLockfile>,
) -> Result<ToolchainHandle> {
    match platform {
        ToolPlatform::Windows => {
            let keg = windows::ensure_windows_keg(pkg, cache_dir, lockfile).await?;
            build_handle_from_keg(keg).await
        }
        ToolPlatform::MacOS => {
            let keg = ensure_macos_keg(pkg, cache_dir, lockfile).await?;
            build_handle_from_keg(keg).await
        }
    }
}

/// Provision (or reuse) a macOS keg for `pkg`, returning the keg directory.
///
/// Dispatches generically: language toolchains land via the relocation-free
/// prebuilt fetcher; everything else is built from source. Both write a
/// [`manifest::KegManifest`] and converge on the same cache + keg layout. This
/// is the crate-internal entry point that [`source_build`] also re-enters to
/// resolve build dependencies recursively.
pub(crate) async fn ensure_macos_keg(
    pkg: &str,
    cache_dir: &Path,
    lockfile: Option<&ToolchainLockfile>,
) -> Result<PathBuf> {
    let (formula, _version) = split_pkg(pkg);
    if prebuilt::is_prebuilt_formula(formula) {
        // Language toolchains (go/node/rust/...) land as relocation-free
        // self-contained vendor archives.
        prebuilt::ensure_prebuilt(formula, cache_dir, lockfile).await
    } else {
        // The homebrew-core C-tool population (git/jq/cmake/...) is built from
        // source at an absolute keg prefix.
        source_build::ensure_from_source(formula, cache_dir, lockfile).await
    }
}

/// Map a keg arch token (`arm64` / `x86_64`) to the vendor-download arch token
/// (`arm64` / `amd64`) the prebuilt resolvers expect.
fn vendor_arch(arch: &str) -> &str {
    if arch == "x86_64" {
        "amd64"
    } else {
        arch
    }
}

/// The lowercase platform token stored in a manifest / lock entry.
fn platform_token(platform: ToolPlatform) -> &'static str {
    match platform {
        ToolPlatform::MacOS => "macos",
        ToolPlatform::Windows => "windows",
    }
}

/// Sanitize a tool token for use inside a temp-file name.
fn sanitize(tool: &str) -> String {
    tool.chars()
        .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
        .collect()
}

/// Resolve a tool to a fully-pinned [`LockedTool`] by live-resolving its exact
/// version + download URL, streaming the artifact to a temp file, and hashing
/// the bytes (verifying against the upstream-published digest when one exists).
///
/// This is the resolution path the CLI's `zlayer toolchains lock` reuses, so the
/// lock writer never duplicates resolver logic. `arch` is the keg arch token
/// (`arm64` / `x86_64`); the vendor-arch mapping is internal.
///
/// # Errors
///
/// Propagates resolution / download / digest-verification failures.
pub async fn resolve_locked_tool(
    tool: &str,
    platform: ToolPlatform,
    arch: &str,
) -> Result<LockedTool> {
    let (formula, _version) = split_pkg(tool);
    let (version, url, expected): (String, String, Option<String>) = match platform {
        ToolPlatform::MacOS => {
            if prebuilt::is_prebuilt_formula(formula) {
                let r = prebuilt::resolve_prebuilt(formula, vendor_arch(arch)).await?;
                (r.version, r.url, r.sha256)
            } else {
                let spec = source_build::resolve_source_spec(formula).await?;
                let sha = (!spec.sha256.is_empty()).then_some(spec.sha256);
                (spec.version, spec.tarball_url, sha)
            }
        }
        ToolPlatform::Windows => windows::resolve_locked_windows(formula).await?,
    };

    // Stream to a temp file to compute (and, when published, verify) the digest.
    let tmp = std::env::temp_dir().join(format!(
        "zlayer-lock-{}-{arch}-{}",
        sanitize(tool),
        std::process::id()
    ));
    let sha256 = package_index::download_verified(&url, &tmp, expected.as_deref()).await?;
    let _ = tokio::fs::remove_file(&tmp).await;

    Ok(LockedTool {
        tool: tool.to_string(),
        platform: platform_token(platform).to_string(),
        arch: arch.to_string(),
        version,
        url,
        sha256,
        resolved_at: chrono::Utc::now().to_rfc3339(),
    })
}

/// Reconstruct a [`ToolchainHandle`] from a provisioned keg by reading (or, for
/// a pre-manifest keg, synthesizing) its [`manifest::KegManifest`].
async fn build_handle_from_keg(keg: PathBuf) -> Result<ToolchainHandle> {
    let manifest = manifest::KegManifest::load_or_synthesize(&keg).await?;
    Ok(ToolchainHandle {
        install_dir: keg,
        path_dirs: manifest.path_dirs,
        env: manifest.env,
    })
}

/// Non-blocking, filesystem-only probe for an already-provisioned keg.
///
/// Returns `Some(handle)` iff a `.ready`-stamped keg for `(pkg, platform,
/// cache_dir)` exists on disk; otherwise `None`. Does **no** network I/O, no
/// build, and no mutation — it reconstructs the [`ToolchainHandle`] from the
/// keg's manifest exactly as the fast path of [`ensure_toolchain`] does.
///
/// It exists so a caller that provisions in the background (and therefore can't
/// `await` the cold install on its hot path) can still inject a keg already on
/// disk — e.g. from a previous daemon process. Returns `None` for any non-macOS
/// platform or when no ready keg is present.
pub async fn probe_ready_toolchain(
    pkg: &str,
    _platform: ToolPlatform,
    cache_dir: &Path,
) -> Option<ToolchainHandle> {
    // The keg layout + cache key are platform-agnostic, so the probe is too: it
    // just looks for a `.ready`-stamped `<formula>-<ver>-<arch>` keg on disk.
    let (formula, _version) = split_pkg(pkg);
    let keg = newest_ready_keg(formula, cache_dir).await?;
    build_handle_from_keg(keg).await.ok()
}

/// Find the newest `{formula}-<ver>-<arch>` keg under `cache_dir` that is
/// stamped `.ready` (mtime-ordered). Returns `None` for a cold/partial cache.
async fn newest_ready_keg(formula: &str, cache_dir: &Path) -> Option<PathBuf> {
    let prefix = format!("{formula}-");
    let arch_suffix = format!("-{}", arch_token());
    let mut entries = tokio::fs::read_dir(cache_dir).await.ok()?;
    let mut best: Option<(std::time::SystemTime, PathBuf)> = None;
    while let Ok(Some(entry)) = entries.next_entry().await {
        let name = entry.file_name();
        let Some(name) = name.to_str() else { continue };
        if !name.starts_with(&prefix) || !name.ends_with(&arch_suffix) {
            continue;
        }
        let keg = entry.path();
        if !tokio::fs::try_exists(keg.join(".ready"))
            .await
            .unwrap_or(false)
        {
            continue;
        }
        let mtime = entry
            .metadata()
            .await
            .ok()
            .and_then(|m| m.modified().ok())
            .unwrap_or(std::time::UNIX_EPOCH);
        if best.as_ref().is_none_or(|(t, _)| mtime >= *t) {
            best = Some((mtime, keg));
        }
    }
    best.map(|(_, keg)| keg)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::manifest::{KegManifest, KegSource};

    #[test]
    fn split_pkg_plain_defaults_to_latest() {
        assert_eq!(split_pkg("git"), ("git", "latest"));
    }

    #[test]
    fn split_pkg_versioned_keeps_full_formula() {
        assert_eq!(split_pkg("openssl@3"), ("openssl@3", "3"));
    }

    #[test]
    fn split_pkg_trailing_at_is_latest() {
        assert_eq!(split_pkg("weird@"), ("weird@", "latest"));
    }

    /// A Windows formula with no portable artifact returns `NotImplemented`
    /// (routed to the HCS choco-capture path). `git` IS implemented on Windows
    /// (MinGit) so it is NOT used here — that path is network-bound and lives in
    /// the `windows` module's own tests.
    #[tokio::test]
    async fn windows_non_portable_formula_is_not_implemented() {
        let tmp = tempfile::tempdir().unwrap();
        let err = ensure_toolchain("cowsay", ToolPlatform::Windows, tmp.path(), None)
            .await
            .unwrap_err();
        assert!(matches!(err, ToolchainError::NotImplemented(_)));
    }

    /// Lay down a source-built `git` keg WITHOUT a manifest (the pre-manifest
    /// layout) so the offline tests exercise the backward-compatible synthesis
    /// path of [`build_handle_from_keg`].
    async fn seed_legacy_git_keg(cache_dir: &Path, version: &str) -> PathBuf {
        let keg = cache_dir.join(format!("git-{version}-{}", arch_token()));
        tokio::fs::create_dir_all(keg.join("bin")).await.unwrap();
        tokio::fs::create_dir_all(keg.join("libexec/git-core"))
            .await
            .unwrap();
        tokio::fs::create_dir_all(keg.join("etc")).await.unwrap();
        tokio::fs::write(keg.join("etc/gitconfig"), b"")
            .await
            .unwrap();
        tokio::fs::write(keg.join(".ready"), b"").await.unwrap();
        keg
    }

    /// Lay down a keg WITH a `toolchain.json` manifest so the resolver's generic
    /// (non-synthesized) path is covered.
    async fn seed_keg_with_manifest(cache_dir: &Path, tool: &str, version: &str) -> PathBuf {
        let keg = cache_dir.join(format!("{tool}-{version}-{}", arch_token()));
        let bin = keg.join("bin");
        tokio::fs::create_dir_all(&bin).await.unwrap();
        let mut env = HashMap::new();
        env.insert("FOO".to_string(), "bar".to_string());
        let manifest = KegManifest {
            tool: tool.to_string(),
            version: version.to_string(),
            arch: arch_token().to_string(),
            platform: "macos".to_string(),
            path_dirs: vec![bin.display().to_string()],
            env,
            source: KegSource::SourceBuild {
                url: String::new(),
                sha256: String::new(),
            },
            build_deps: vec![],
            provisioned_at: "2026-06-30T00:00:00Z".to_string(),
        };
        manifest.write_to_keg(&keg).await.unwrap();
        tokio::fs::write(keg.join(".ready"), b"").await.unwrap();
        keg
    }

    /// A pre-manifest `git` keg synthesizes a handle whose env is ONLY
    /// `GIT_EXEC_PATH` (→ `<keg>/libexec/git-core`), with NO
    /// `DYLD_FALLBACK_LIBRARY_PATH` and NO `GIT_CONFIG_SYSTEM`.
    #[tokio::test]
    async fn handle_synthesized_for_legacy_git_keg_drops_dyld() {
        let tmp = tempfile::tempdir().unwrap();
        let keg = seed_legacy_git_keg(tmp.path(), "2.55.0").await;

        let handle = build_handle_from_keg(keg.clone()).await.unwrap();

        assert_eq!(handle.install_dir, keg);
        assert_eq!(
            handle.path_dirs,
            vec![keg.join("bin").display().to_string()]
        );
        assert_eq!(
            handle.env.get("GIT_EXEC_PATH"),
            Some(&keg.join("libexec/git-core").display().to_string())
        );
        assert!(!handle.env.contains_key("DYLD_FALLBACK_LIBRARY_PATH"));
        assert!(!handle.env.contains_key("GIT_CONFIG_SYSTEM"));
    }

    /// A keg WITH a manifest projects the manifest's `path_dirs` + `env`
    /// verbatim onto the handle.
    #[tokio::test]
    async fn handle_reads_manifest_when_present() {
        let tmp = tempfile::tempdir().unwrap();
        let keg = seed_keg_with_manifest(tmp.path(), "jq", "1.8.2").await;

        let handle = build_handle_from_keg(keg.clone()).await.unwrap();
        assert_eq!(handle.install_dir, keg);
        assert_eq!(
            handle.path_dirs,
            vec![keg.join("bin").display().to_string()]
        );
        assert_eq!(handle.env.get("FOO"), Some(&"bar".to_string()));
    }

    /// The on-disk fallback the runtime relies on: a `.ready` keg is probed
    /// (no install) and reconstructs the SAME handle as the fast path.
    #[tokio::test]
    async fn probe_ready_returns_handle_for_ready_keg() {
        let tmp = tempfile::tempdir().unwrap();
        let keg = seed_legacy_git_keg(tmp.path(), "2.55.0").await;

        let handle = probe_ready_toolchain("git", ToolPlatform::MacOS, tmp.path())
            .await
            .expect("ready keg should be probed without install");

        assert_eq!(handle.install_dir, keg);
        assert_eq!(
            handle.env.get("GIT_EXEC_PATH"),
            Some(&keg.join("libexec/git-core").display().to_string())
        );
    }

    /// Probing a different tool's keg works generically (not git-special).
    #[tokio::test]
    async fn probe_ready_is_generic_across_tools() {
        let tmp = tempfile::tempdir().unwrap();
        let keg = seed_keg_with_manifest(tmp.path(), "jq", "1.8.2").await;

        let handle = probe_ready_toolchain("jq", ToolPlatform::MacOS, tmp.path())
            .await
            .expect("ready jq keg should be probed");
        assert_eq!(handle.install_dir, keg);
        assert_eq!(handle.env.get("FOO"), Some(&"bar".to_string()));
    }

    /// A keg dir that exists but is NOT stamped `.ready` (mid-build) must probe
    /// to `None` — never inject a partial keg.
    #[tokio::test]
    async fn probe_ready_returns_none_without_ready_marker() {
        let tmp = tempfile::tempdir().unwrap();
        let keg = tmp.path().join(format!("git-2.55.0-{}", arch_token()));
        tokio::fs::create_dir_all(keg.join("bin")).await.unwrap();

        assert!(
            probe_ready_toolchain("git", ToolPlatform::MacOS, tmp.path())
                .await
                .is_none(),
            "an unstamped keg must not be injected"
        );
    }

    /// Cold cache, an absent tool, and non-macOS requests all probe to `None`.
    #[tokio::test]
    async fn probe_ready_returns_none_for_cold_or_unsupported() {
        let tmp = tempfile::tempdir().unwrap();
        assert!(
            probe_ready_toolchain("git", ToolPlatform::MacOS, tmp.path())
                .await
                .is_none(),
            "cold cache should probe None"
        );
        assert!(
            probe_ready_toolchain("jq", ToolPlatform::MacOS, tmp.path())
                .await
                .is_none(),
            "absent tool should probe None"
        );
        assert!(
            probe_ready_toolchain("git", ToolPlatform::Windows, tmp.path())
                .await
                .is_none(),
            "cold cache probes None on every platform"
        );
    }

    /// Full end-to-end provision of BOTH verification targets: build `git` and
    /// `jq` FROM SOURCE and run them. Asserts each built binary carries NO
    /// `@@HOMEBREW@@` placeholder (the bottle-relocation failure mode) and that
    /// a manifest was written. `#[ignore]` because it hits the network + the
    /// compiler and only works on macOS with CLT; run with:
    ///   `cargo test -p zlayer-toolchain -- --ignored`.
    #[tokio::test]
    #[ignore = "live build test; fetches + compiles git and jq from source (macOS + CLT only)"]
    async fn ensure_git_and_jq_build_from_source_and_run() {
        let tmp = tempfile::tempdir().unwrap();

        for (tool, version_needle) in [("git", "git version"), ("jq", "jq-")] {
            let handle = ensure_toolchain(tool, ToolPlatform::MacOS, tmp.path(), None)
                .await
                .unwrap_or_else(|e| panic!("{tool} toolchain should build from source: {e}"));

            let bin = handle.install_dir.join("bin").join(tool);
            assert!(
                bin.exists(),
                "{tool} binary should exist at <keg>/bin/{tool}"
            );

            // The keg must carry a manifest.
            let manifest = KegManifest::read_from_keg(&handle.install_dir)
                .await
                .unwrap()
                .unwrap_or_else(|| panic!("{tool} keg must have a manifest"));
            assert_eq!(manifest.tool, tool);

            // No @@HOMEBREW@@ anywhere in the built binary.
            let bytes = tokio::fs::read(&bin).await.expect("read binary");
            assert!(
                !contains_subslice_bytes(&bytes, b"@@HOMEBREW"),
                "source-built {tool} must contain NO @@HOMEBREW@@ references"
            );

            let mut cmd = tokio::process::Command::new(&bin);
            for (k, v) in &handle.env {
                cmd.env(k, v);
            }
            let out = cmd.arg("--version").output().await.expect("run --version");
            assert!(out.status.success(), "{tool} --version should succeed");
            assert!(
                String::from_utf8_lossy(&out.stdout).contains(version_needle)
                    || String::from_utf8_lossy(&out.stderr).contains(version_needle),
                "{tool} --version output should contain '{version_needle}'"
            );
        }
    }

    /// Tiny byte-substring helper for the binary placeholder scan above.
    fn contains_subslice_bytes(haystack: &[u8], needle: &[u8]) -> bool {
        if needle.is_empty() || haystack.len() < needle.len() {
            return false;
        }
        haystack
            .windows(needle.len())
            .any(|window| window == needle)
    }
}