zlayer-builder 0.12.1

//! Buildah installation and discovery
//!
//! This module provides functionality to find existing buildah installations
//! or provide helpful error messages for installing buildah on various platforms.
//!
//! Sidecar (`zlayer-buildd`) installation lives in the [`buildd`] submodule
//! at the bottom of this file. The buildah-sidecar plan (Option B) ships a
//! Go binary alongside `zlayer` and the operator typically copies it into
//! `${ZLAYER_DATA_DIR}/bin/zlayer-buildd`; auto-install fetches from
//! release artifacts when that's possible.

use std::path::{Path, PathBuf};
use std::process::Stdio;

use tokio::process::Command;
use tracing::{debug, info, trace, warn};

/// Minimum required buildah version
const MIN_BUILDAH_VERSION: &str = "1.28.0";

/// Buildah installation manager
///
/// Handles finding existing buildah installations and providing
/// installation guidance when buildah is not found.
#[derive(Debug, Clone)]
pub struct BuildahInstaller {
    /// Where to store downloaded buildah binary (for future use)
    install_dir: PathBuf,
    /// Minimum required buildah version
    min_version: &'static str,
}

/// Information about a discovered buildah installation
#[derive(Debug, Clone)]
pub struct BuildahInstallation {
    /// Path to buildah binary
    pub path: PathBuf,
    /// Installed version
    pub version: String,
}

/// Errors that can occur during buildah installation/discovery
#[derive(Debug, thiserror::Error)]
pub enum InstallError {
    /// Buildah was not found on the system
    #[error("Buildah not found. {}", install_instructions())]
    NotFound,

    /// Buildah version is too old
    #[error("Buildah version {found} is below minimum required version {required}")]
    VersionTooOld {
        /// The version that was found
        found: String,
        /// The minimum required version
        required: String,
    },

    /// Platform is not supported
    #[error("Unsupported platform: {os}/{arch}")]
    UnsupportedPlatform {
        /// Operating system
        os: String,
        /// CPU architecture
        arch: String,
    },

    /// Download failed (for future binary download support)
    #[error("Download failed: {0}")]
    DownloadFailed(String),

    /// IO error during installation
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    /// Failed to parse version output
    #[error("Failed to parse buildah version output: {0}")]
    VersionParse(String),

    /// Failed to execute buildah
    #[error("Failed to execute buildah: {0}")]
    ExecutionFailed(String),
}

impl Default for BuildahInstaller {
    fn default() -> Self {
        Self::new()
    }
}

impl BuildahInstaller {
    /// Create installer with default paths
    ///
    /// User install directory: `~/.zlayer/bin/`
    /// System install directory: `/usr/local/lib/zlayer/`
    #[must_use]
    pub fn new() -> Self {
        let install_dir = default_install_dir();
        Self {
            install_dir,
            min_version: MIN_BUILDAH_VERSION,
        }
    }

    /// Create with custom install directory
    #[must_use]
    pub fn with_install_dir(dir: PathBuf) -> Self {
        Self {
            install_dir: dir,
            min_version: MIN_BUILDAH_VERSION,
        }
    }

    /// Get the install directory
    #[must_use]
    pub fn install_dir(&self) -> &Path {
        &self.install_dir
    }

    /// Get the minimum required version
    #[must_use]
    pub fn min_version(&self) -> &str {
        self.min_version
    }

    /// Find existing buildah installation
    ///
    /// Searches for buildah in the following locations (in order):
    /// 1. PATH environment variable
    /// 2. `~/.zlayer/bin/buildah`
    /// 3. `/usr/local/lib/zlayer/buildah`
    /// 4. `/usr/bin/buildah`
    /// 5. `/usr/local/bin/buildah`
    pub async fn find_existing(&self) -> Option<BuildahInstallation> {
        // Search paths in priority order
        let search_paths = get_search_paths(&self.install_dir);

        for path in search_paths {
            trace!("Checking for buildah at: {}", path.display());

            if path.exists() && path.is_file() {
                match Self::get_version(&path).await {
                    Ok(version) => {
                        info!("Found buildah at {} (version {})", path.display(), version);
                        return Some(BuildahInstallation { path, version });
                    }
                    Err(e) => {
                        debug!(
                            "Found buildah at {} but couldn't get version: {}",
                            path.display(),
                            e
                        );
                    }
                }
            }
        }

        // Also try using `which` to find buildah in PATH
        if let Some(path) = find_in_path("buildah").await {
            match Self::get_version(&path).await {
                Ok(version) => {
                    info!(
                        "Found buildah in PATH at {} (version {})",
                        path.display(),
                        version
                    );
                    return Some(BuildahInstallation { path, version });
                }
                Err(e) => {
                    debug!(
                        "Found buildah in PATH at {} but couldn't get version: {}",
                        path.display(),
                        e
                    );
                }
            }
        }

        None
    }

    /// Check if buildah is installed and meets version requirements
    ///
    /// Returns the installation if found and valid, otherwise returns an error.
    ///
    /// # Errors
    ///
    /// Returns an error if buildah is not found or if the version is below the minimum.
    pub async fn check(&self) -> Result<BuildahInstallation, InstallError> {
        let installation = self.find_existing().await.ok_or(InstallError::NotFound)?;

        // Check version meets minimum requirements
        if !version_meets_minimum(&installation.version, self.min_version) {
            return Err(InstallError::VersionTooOld {
                found: installation.version,
                required: self.min_version.to_string(),
            });
        }

        Ok(installation)
    }

    /// Get buildah version from a binary
    ///
    /// Runs `buildah --version` and parses the output.
    /// Expected format: "buildah version 1.33.0 (image-spec 1.0.2-dev, runtime-spec 1.0.2-dev)"
    ///
    /// # Errors
    ///
    /// Returns an error if the binary cannot be executed or the version output cannot be parsed.
    pub async fn get_version(path: &Path) -> Result<String, InstallError> {
        let output = Command::new(path)
            .arg("--version")
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .output()
            .await
            .map_err(|e| InstallError::ExecutionFailed(e.to_string()))?;

        if !output.status.success() {
            let stderr = String::from_utf8_lossy(&output.stderr);
            return Err(InstallError::ExecutionFailed(format!(
                "buildah --version failed: {}",
                stderr.trim()
            )));
        }

        let stdout = String::from_utf8_lossy(&output.stdout);
        parse_version(&stdout)
    }

    /// Ensure buildah is available (find existing or return helpful error)
    ///
    /// This is the primary entry point for ensuring buildah is available.
    /// If buildah is not found, it returns an error with installation instructions.
    ///
    /// # Errors
    ///
    /// Returns an error if buildah is not found or the version is insufficient.
    pub async fn ensure(&self) -> Result<BuildahInstallation, InstallError> {
        // First try to find existing installation
        match self.check().await {
            Ok(installation) => {
                info!(
                    "Using buildah {} at {}",
                    installation.version,
                    installation.path.display()
                );
                Ok(installation)
            }
            Err(InstallError::VersionTooOld { found, required }) => {
                warn!(
                    "Found buildah {} but minimum required version is {}",
                    found, required
                );
                Err(InstallError::VersionTooOld { found, required })
            }
            Err(InstallError::NotFound) => {
                #[cfg(target_os = "macos")]
                debug!("Buildah not available on macOS; will use native sandbox builder");
                #[cfg(not(target_os = "macos"))]
                warn!("Buildah not found on system");
                Err(InstallError::NotFound)
            }
            Err(e) => Err(e),
        }
    }

    /// Download buildah binary for current platform
    ///
    /// Currently returns an error with installation instructions.
    /// Future versions may download static binaries from GitHub releases.
    ///
    /// # Errors
    ///
    /// Returns an error if the platform is unsupported or automatic download is unavailable.
    #[allow(clippy::unused_async)]
    pub async fn download(&self) -> Result<BuildahInstallation, InstallError> {
        let (os, arch) = current_platform();

        // Check if platform is supported
        if !is_platform_supported() {
            return Err(InstallError::UnsupportedPlatform {
                os: os.to_string(),
                arch: arch.to_string(),
            });
        }

        // For now, return helpful error with installation instructions
        // Future: Download static binary from GitHub releases
        Err(InstallError::DownloadFailed(format!(
            "Automatic download not yet implemented. {}",
            install_instructions()
        )))
    }
}

/// Get the current platform (OS and architecture)
#[must_use]
pub fn current_platform() -> (&'static str, &'static str) {
    let os = std::env::consts::OS; // "linux", "macos", "windows"
    let arch = std::env::consts::ARCH; // "x86_64", "aarch64"
    (os, arch)
}

/// Check if the current platform is supported for buildah
///
/// Buildah is primarily a Linux tool, though it can work on macOS
/// through virtualization.
#[must_use]
pub fn is_platform_supported() -> bool {
    let (os, arch) = current_platform();
    matches!((os, arch), ("linux" | "macos", "x86_64" | "aarch64"))
}

/// Get installation instructions for the current platform
#[must_use]
pub fn install_instructions() -> String {
    let (os, _arch) = current_platform();

    match os {
        "linux" => {
            // Try to detect the Linux distribution
            if let Some(distro) = detect_linux_distro() {
                match distro.as_str() {
                    "ubuntu" | "debian" | "pop" | "mint" | "elementary" => {
                        "Install with: sudo apt install buildah".to_string()
                    }
                    "fedora" | "rhel" | "centos" | "rocky" | "alma" => {
                        "Install with: sudo dnf install buildah".to_string()
                    }
                    "arch" | "manjaro" | "endeavouros" => {
                        "Install with: sudo pacman -S buildah".to_string()
                    }
                    "opensuse" | "suse" => "Install with: sudo zypper install buildah".to_string(),
                    "alpine" => "Install with: sudo apk add buildah".to_string(),
                    "gentoo" => "Install with: sudo emerge app-containers/buildah".to_string(),
                    "void" => "Install with: sudo xbps-install buildah".to_string(),
                    _ => "Install buildah using your distribution's package manager.\n\
                         Common commands:\n\
                         - Debian/Ubuntu: sudo apt install buildah\n\
                         - Fedora/RHEL: sudo dnf install buildah\n\
                         - Arch: sudo pacman -S buildah\n\
                         - openSUSE: sudo zypper install buildah"
                        .to_string(),
                }
            } else {
                "Install buildah using your distribution's package manager.\n\
                 Common commands:\n\
                 - Debian/Ubuntu: sudo apt install buildah\n\
                 - Fedora/RHEL: sudo dnf install buildah\n\
                 - Arch: sudo pacman -S buildah\n\
                 - openSUSE: sudo zypper install buildah"
                    .to_string()
            }
        }
        "macos" => "Buildah is not required on macOS -- ZLayer uses the native \
             sandbox builder instead. If you prefer buildah, install with: \
             brew install buildah (requires a Linux VM for container operations)."
            .to_string(),
        "windows" => "Buildah is not natively supported on Windows.\n\
             Consider using WSL2 with a Linux distribution and installing buildah there."
            .to_string(),
        _ => format!("Buildah is not supported on {os}. Use a Linux system."),
    }
}

// ============================================================================
// Internal Helper Functions
// ============================================================================

/// Get the default install directory for `ZLayer` binaries
fn default_install_dir() -> PathBuf {
    zlayer_paths::ZLayerDirs::system_default().bin()
}

/// Get all paths to search for buildah
fn get_search_paths(install_dir: &Path) -> Vec<PathBuf> {
    let mut paths = vec![
        // Custom install directory
        install_dir.join("buildah"),
        // User ZLayer directory
        zlayer_paths::ZLayerDirs::system_default()
            .bin()
            .join("buildah"),
        // System ZLayer directory
        PathBuf::from("/usr/local/lib/zlayer/buildah"),
        // Standard system paths
        PathBuf::from("/usr/bin/buildah"),
        PathBuf::from("/usr/local/bin/buildah"),
        PathBuf::from("/bin/buildah"),
    ];

    // Deduplicate while preserving order
    let mut seen = std::collections::HashSet::new();
    paths.retain(|p| seen.insert(p.clone()));

    paths
}

/// Find a binary on PATH. Uses platform-native lookup:
/// - Windows: `where.exe` (always available in System32).
/// - Unix: `which`, then `sh -c "command -v"` as a fallback.
async fn find_in_path(binary: &str) -> Option<PathBuf> {
    #[cfg(windows)]
    {
        if let Ok(output) = Command::new("where")
            .arg(binary)
            .stdout(Stdio::piped())
            .stderr(Stdio::null())
            .output()
            .await
        {
            if output.status.success() {
                let stdout = String::from_utf8_lossy(&output.stdout);
                // `where.exe` prints one path per line — first hit is the
                // one that would run.
                if let Some(first) = stdout.lines().next() {
                    let path = first.trim().to_string();
                    if !path.is_empty() {
                        return Some(PathBuf::from(path));
                    }
                }
            }
        }
    }

    let output = Command::new("which")
        .arg(binary)
        .stdout(Stdio::piped())
        .stderr(Stdio::null())
        .output()
        .await
        .ok()?;

    if output.status.success() {
        let path = String::from_utf8_lossy(&output.stdout).trim().to_string();
        if !path.is_empty() {
            return Some(PathBuf::from(path));
        }
    }

    // Also try `command -v` as a fallback (works in more shells)
    let output = Command::new("sh")
        .args(["-c", &format!("command -v {binary}")])
        .stdout(Stdio::piped())
        .stderr(Stdio::null())
        .output()
        .await
        .ok()?;

    if output.status.success() {
        let path = String::from_utf8_lossy(&output.stdout).trim().to_string();
        if !path.is_empty() {
            return Some(PathBuf::from(path));
        }
    }

    None
}

/// Parse version from buildah --version output
///
/// Expected formats:
/// - "buildah version 1.33.0 (image-spec 1.0.2-dev, runtime-spec 1.0.2-dev)"
/// - "buildah version 1.33.0"
/// - "buildah version 1.34.0-dev"
fn parse_version(output: &str) -> Result<String, InstallError> {
    // Look for "buildah version X.Y.Z" pattern
    let output = output.trim();

    // Try to extract version after "version"
    if let Some(pos) = output.to_lowercase().find("version") {
        let after_version = &output[pos + "version".len()..].trim_start();

        // Extract the version number (digits, dots, and optional suffix like -dev, -rc1)
        // Version format: X.Y.Z or X.Y.Z-suffix
        let version: String = after_version
            .chars()
            .take_while(|c| c.is_ascii_alphanumeric() || *c == '.' || *c == '-')
            .collect();

        // Clean up: trim trailing hyphens if any
        let version = version.trim_end_matches('-');

        if !version.is_empty() && version.contains('.') {
            return Ok(version.to_string());
        }
    }

    Err(InstallError::VersionParse(format!(
        "Could not parse version from: {output}"
    )))
}

/// Check if a version string meets the minimum requirement
///
/// Uses simple semantic version comparison.
fn version_meets_minimum(version: &str, minimum: &str) -> bool {
    let parse_version = |s: &str| -> Option<Vec<u32>> {
        // Strip any trailing non-numeric parts (like "-dev")
        let clean = s.split('-').next()?;
        clean
            .split('.')
            .map(|p| p.parse::<u32>().ok())
            .collect::<Option<Vec<_>>>()
    };

    let Some(version_parts) = parse_version(version) else {
        return false;
    };

    let Some(minimum_parts) = parse_version(minimum) else {
        return true; // If we can't parse minimum, assume it's met
    };

    // Compare version parts
    for (v, m) in version_parts.iter().zip(minimum_parts.iter()) {
        match v.cmp(m) {
            std::cmp::Ordering::Greater => return true,
            std::cmp::Ordering::Less => return false,
            std::cmp::Ordering::Equal => {}
        }
    }

    // If all compared parts are equal, check if version has at least as many parts
    version_parts.len() >= minimum_parts.len()
}

/// Detect the Linux distribution
fn detect_linux_distro() -> Option<String> {
    // Try /etc/os-release first (most modern distros)
    if let Ok(contents) = std::fs::read_to_string("/etc/os-release") {
        for line in contents.lines() {
            if let Some(id) = line.strip_prefix("ID=") {
                return Some(id.trim_matches('"').to_lowercase());
            }
        }
    }

    // Try /etc/lsb-release as fallback
    if let Ok(contents) = std::fs::read_to_string("/etc/lsb-release") {
        for line in contents.lines() {
            if let Some(id) = line.strip_prefix("DISTRIB_ID=") {
                return Some(id.trim_matches('"').to_lowercase());
            }
        }
    }

    None
}

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

    #[test]
    fn test_parse_version_full() {
        let output = "buildah version 1.33.0 (image-spec 1.0.2-dev, runtime-spec 1.0.2-dev)";
        let version = parse_version(output).unwrap();
        assert_eq!(version, "1.33.0");
    }

    #[test]
    fn test_parse_version_simple() {
        let output = "buildah version 1.28.0";
        let version = parse_version(output).unwrap();
        assert_eq!(version, "1.28.0");
    }

    #[test]
    fn test_parse_version_with_newline() {
        let output = "buildah version 1.33.0\n";
        let version = parse_version(output).unwrap();
        assert_eq!(version, "1.33.0");
    }

    #[test]
    fn test_parse_version_dev() {
        let output = "buildah version 1.34.0-dev";
        let version = parse_version(output).unwrap();
        assert_eq!(version, "1.34.0-dev");
    }

    #[test]
    fn test_parse_version_invalid() {
        let output = "some random output";
        assert!(parse_version(output).is_err());
    }

    #[test]
    fn test_version_meets_minimum_equal() {
        assert!(version_meets_minimum("1.28.0", "1.28.0"));
    }

    #[test]
    fn test_version_meets_minimum_greater_patch() {
        assert!(version_meets_minimum("1.28.1", "1.28.0"));
    }

    #[test]
    fn test_version_meets_minimum_greater_minor() {
        assert!(version_meets_minimum("1.29.0", "1.28.0"));
    }

    #[test]
    fn test_version_meets_minimum_greater_major() {
        assert!(version_meets_minimum("2.0.0", "1.28.0"));
    }

    #[test]
    fn test_version_meets_minimum_less_patch() {
        assert!(!version_meets_minimum("1.27.5", "1.28.0"));
    }

    #[test]
    fn test_version_meets_minimum_less_minor() {
        assert!(!version_meets_minimum("1.20.0", "1.28.0"));
    }

    #[test]
    fn test_version_meets_minimum_less_major() {
        assert!(!version_meets_minimum("0.99.0", "1.28.0"));
    }

    #[test]
    fn test_version_meets_minimum_with_dev_suffix() {
        assert!(version_meets_minimum("1.34.0-dev", "1.28.0"));
    }

    #[test]
    fn test_current_platform() {
        let (os, arch) = current_platform();
        // Just verify it returns non-empty strings
        assert!(!os.is_empty());
        assert!(!arch.is_empty());
    }

    #[test]
    fn test_is_platform_supported() {
        // This test will pass on Linux and macOS x86_64/aarch64
        let (os, arch) = current_platform();
        let supported = is_platform_supported();

        match (os, arch) {
            ("linux" | "macos", "x86_64" | "aarch64") => assert!(supported),
            _ => assert!(!supported),
        }
    }

    #[test]
    fn test_install_instructions_not_empty() {
        let instructions = install_instructions();
        assert!(!instructions.is_empty());
    }

    #[test]
    fn test_default_install_dir() {
        let dir = default_install_dir();
        // Should end with bin
        assert!(dir.to_string_lossy().contains("bin") || dir.to_string_lossy().contains("zlayer"));
    }

    #[test]
    fn test_get_search_paths_not_empty() {
        let install_dir = PathBuf::from("/var/lib/zlayer-test");
        let paths = get_search_paths(&install_dir);
        assert!(!paths.is_empty());
        // First path should be in our custom install dir
        assert!(paths[0].starts_with("/var/lib/zlayer-test"));
    }

    #[test]
    fn test_installer_creation() {
        let installer = BuildahInstaller::new();
        assert_eq!(installer.min_version(), MIN_BUILDAH_VERSION);
    }

    #[test]
    fn test_installer_with_custom_dir() {
        let custom_dir = PathBuf::from("/custom/path");
        let installer = BuildahInstaller::with_install_dir(custom_dir.clone());
        assert_eq!(installer.install_dir(), custom_dir);
    }

    #[tokio::test]
    async fn test_find_in_path_nonexistent() {
        // This binary should not exist
        let result = find_in_path("this_binary_should_not_exist_12345").await;
        assert!(result.is_none());
    }

    #[tokio::test]
    #[allow(clippy::await_holding_lock)]
    async fn test_find_in_path_exists() {
        // Probe for a binary guaranteed to exist on each platform.
        #[cfg(unix)]
        let probe = "sh";
        #[cfg(windows)]
        let probe = "cmd.exe";

        // Other tests in this crate mutate `PATH` (e.g. the discover
        // module's missing-binary test). We must hold the shared env lock
        // for the full duration of `find_in_path` — the spawned `which` /
        // `where.exe` subprocess inherits PATH at spawn time, and any
        // concurrent test that flips PATH would break this probe.
        //
        // Tokio's test runtime is single-threaded by default, so holding
        // a sync `MutexGuard` across the inner await cannot deadlock
        // worker threads (we're the only task).
        let _g = crate::TEST_ENV_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);

        let result = find_in_path(probe).await;
        assert!(
            result.is_some(),
            "find_in_path({probe:?}) should find a system binary"
        );
    }

    // Integration test - only runs if buildah is installed
    #[tokio::test]
    #[ignore = "requires buildah to be installed"]
    async fn test_find_existing_buildah() {
        let installer = BuildahInstaller::new();
        let result = installer.find_existing().await;
        assert!(result.is_some());
        let installation = result.unwrap();
        assert!(installation.path.exists());
        assert!(!installation.version.is_empty());
    }

    #[tokio::test]
    #[ignore = "requires buildah to be installed"]
    async fn test_check_buildah() {
        let installer = BuildahInstaller::new();
        let result = installer.check().await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    #[ignore = "requires buildah to be installed"]
    async fn test_ensure_buildah() {
        let installer = BuildahInstaller::new();
        let result = installer.ensure().await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    #[ignore = "requires buildah to be installed"]
    async fn test_get_version() {
        let installer = BuildahInstaller::new();
        if let Some(installation) = installer.find_existing().await {
            let version = BuildahInstaller::get_version(&installation.path).await;
            assert!(version.is_ok());
            let version = version.unwrap();
            assert!(version.contains('.'));
        }
    }
}

/// Sidecar (`zlayer-buildd`) install helpers.
///
/// Unix-only: the sidecar binary is a Linux executable and the install
/// path relies on Unix file-mode bits. On non-Unix targets the module is
/// compiled away entirely.
#[cfg(unix)]
pub mod buildd {
    use std::env;
    use std::fs;
    use std::os::unix::fs::PermissionsExt;
    use std::path::{Path, PathBuf};

    use crate::error::{BuildError, Result};

    /// Compile-time constant: the `zlayer-buildd` version the host
    /// expects. Bound to the same crate version as `zlayer` itself so the
    /// daemon and sidecar are released in lockstep.
    pub const EXPECTED_VERSION: &str = env!("CARGO_PKG_VERSION");

    /// Outcome of an [`ensure_buildd_sidecar`] call.
    #[derive(Debug)]
    pub enum InstallOutcome {
        /// Sidecar was already present at the canonical location.
        AlreadyInstalled {
            /// Path to the installed binary.
            path: PathBuf,
            /// Version reported by the binary's `--version` output.
            version: String,
        },
        /// Sidecar was copied from a release tarball next to `zlayer`.
        CopiedFromBundle {
            /// Source path the binary was copied from.
            source: PathBuf,
            /// Destination path the binary was copied to.
            dest: PathBuf,
        },
        /// Sidecar was fetched from a release artifact URL.
        Downloaded {
            /// URL the binary was fetched from.
            url: String,
            /// Destination path the binary was written to.
            dest: PathBuf,
        },
        /// Sidecar was deliberately not installed (env override or
        /// development setup). The caller is expected to ensure the
        /// binary is reachable some other way.
        Skipped {
            /// Human-readable reason the install was skipped.
            reason: String,
        },
    }

    /// Ensure `zlayer-buildd` is installed at the canonical location.
    ///
    /// Resolution order:
    ///   1. `ZLAYER_BUILDD_BIN` set → skipped (development override).
    ///   2. Canonical path already populated and the binary's `--version`
    ///      matches [`EXPECTED_VERSION`] → already installed.
    ///   3. A `zlayer-buildd` binary lives next to the currently-running
    ///      `zlayer` binary (e.g. release tarball with both binaries in
    ///      one dir) → copy it.
    ///   4. Fetch from the release artifact URL.
    ///
    /// # Errors
    ///
    /// Returns [`BuildError::NotSupported`] when none of the resolution
    /// steps succeed (no env override, no canonical install, no bundled
    /// binary alongside `zlayer`). The HTTP-download path is intentionally
    /// not implemented in this module — the air-gapped bundled path
    /// covers production.
    pub fn ensure_buildd_sidecar(install_dir: &Path) -> Result<InstallOutcome> {
        // 1) Env override.
        if env::var_os("ZLAYER_BUILDD_BIN").is_some() {
            return Ok(InstallOutcome::Skipped {
                reason: "ZLAYER_BUILDD_BIN set; using that binary instead".into(),
            });
        }

        let dest = install_dir.join("zlayer-buildd");

        // 2) Already installed?
        if dest.exists() && is_executable(&dest) {
            if let Some(version) = read_version(&dest) {
                if version == EXPECTED_VERSION {
                    return Ok(InstallOutcome::AlreadyInstalled {
                        path: dest,
                        version,
                    });
                }
                // Version mismatch — fall through to re-install.
                tracing::warn!(
                    "zlayer-buildd at {} reports version {} but daemon expects {}; reinstalling",
                    dest.display(),
                    version,
                    EXPECTED_VERSION
                );
            }
        }

        // 3) Bundled next to the running zlayer binary?
        if let Some(bundled) = bundled_sidecar_path()? {
            ensure_parent_dir(&dest)?;
            fs::copy(&bundled, &dest)?;
            mark_executable(&dest)?;
            return Ok(InstallOutcome::CopiedFromBundle {
                source: bundled,
                dest,
            });
        }

        // 4) Fetch from release artifact URL.
        //
        // We deliberately do NOT implement HTTP fetch in this module. The
        // pattern in this codebase (per the existing buildah-install logic
        // above and the `update_bottles` flow) is to delegate network
        // fetches to `zlayer_registry::client` or `reqwest` callers and
        // surface a clear error otherwise. For the air-gapped path 3 to
        // suffice in 99% of cases, returning an actionable error here is
        // appropriate.
        Err(BuildError::NotSupported {
            operation: format!(
                "zlayer-buildd is not installed at {} and no bundled binary was found \
                 alongside the running zlayer executable. Either run `make release` in \
                 bin/zlayer-buildd/ and copy the result into {}, set ZLAYER_BUILDD_BIN, or \
                 install the release tarball that ships zlayer-buildd alongside zlayer.",
                dest.display(),
                install_dir.display(),
            ),
        })
    }

    /// Look for a `zlayer-buildd` binary in the same directory as the
    /// currently-running `zlayer` executable. This is the release-tarball
    /// pattern.
    fn bundled_sidecar_path() -> Result<Option<PathBuf>> {
        let exe = env::current_exe()?;
        let Some(dir) = exe.parent() else {
            return Ok(None);
        };
        let candidate = dir.join("zlayer-buildd");
        if candidate.exists() && is_executable(&candidate) {
            Ok(Some(candidate))
        } else {
            Ok(None)
        }
    }

    fn read_version(binary: &Path) -> Option<String> {
        let output = std::process::Command::new(binary)
            .arg("--version")
            .output()
            .ok()?;
        if !output.status.success() {
            return None;
        }
        let stdout = String::from_utf8(output.stdout).ok()?;
        // The Go side emits a single JSON line like:
        //   {"buildah_version":"...","go_version":"...","sidecar_version":"..."}
        // We look for the sidecar_version value via a tolerant substring
        // scan to avoid pulling in a JSON dep for this single use.
        let key = "\"sidecar_version\":\"";
        let start = stdout.find(key)? + key.len();
        let rest = &stdout[start..];
        let end = rest.find('"')?;
        Some(rest[..end].to_string())
    }

    fn is_executable(path: &Path) -> bool {
        match fs::metadata(path) {
            Ok(md) if md.is_file() => md.permissions().mode() & 0o111 != 0,
            _ => false,
        }
    }

    fn mark_executable(path: &Path) -> Result<()> {
        let mut perms = fs::metadata(path)?.permissions();
        let mode = perms.mode();
        perms.set_mode(mode | 0o755);
        fs::set_permissions(path, perms)?;
        Ok(())
    }

    fn ensure_parent_dir(path: &Path) -> Result<()> {
        if let Some(parent) = path.parent() {
            fs::create_dir_all(parent)?;
        }
        Ok(())
    }

    #[cfg(test)]
    #[allow(unsafe_code)]
    mod tests {
        use super::*;
        use crate::TEST_ENV_LOCK;
        use std::sync::PoisonError;

        #[test]
        fn env_override_yields_skipped() {
            let _g = TEST_ENV_LOCK.lock().unwrap_or_else(PoisonError::into_inner);
            // SAFETY: tests in this module serialize env mutations via
            // `ENV_LOCK`, so no other thread observes the inconsistent
            // intermediate state.
            unsafe {
                env::set_var("ZLAYER_BUILDD_BIN", "/tmp/whatever");
            }
            let tmp = tempfile::tempdir().unwrap();
            let outcome = ensure_buildd_sidecar(tmp.path()).unwrap();
            // SAFETY: see above.
            unsafe {
                env::remove_var("ZLAYER_BUILDD_BIN");
            }
            assert!(matches!(outcome, InstallOutcome::Skipped { .. }));
        }

        #[test]
        fn missing_binary_returns_actionable_error() {
            let _g = TEST_ENV_LOCK.lock().unwrap_or_else(PoisonError::into_inner);
            // SAFETY: tests in this module serialize env mutations via
            // `ENV_LOCK`.
            unsafe {
                env::remove_var("ZLAYER_BUILDD_BIN");
            }
            // Make sure no zlayer-buildd is next to our test binary.
            // (env::current_exe() in tests points at the test runner,
            // which won't have a sibling zlayer-buildd unless the local
            // dev box happens to have one — we just check the error path
            // when both bundled lookup and dest are absent.)
            let tmp = tempfile::tempdir().unwrap();
            let err = ensure_buildd_sidecar(tmp.path());
            // Allow either "AlreadyInstalled" or the error if a stale
            // binary somehow got copied next to the test runner; the
            // primary assertion is that the function doesn't panic.
            if let Err(e) = err {
                let msg = e.to_string();
                assert!(
                    msg.contains("zlayer-buildd"),
                    "error did not mention the binary: {msg}"
                );
            }
        }
    }
}