zlayer_toolchain/

registry.rs

//! Toolchain-artifact OCI registry publish/pull.
//!
//! A provisioned, [relocatable](crate::relocate) toolchain is published to a
//! **single** OCI repository under a **structured tag** and pulled back down by
//! any consumer that lacks it locally. This is the network tier of the
//! toolchain cache: the source-build / prebuilt paths land a toolchain at an
//! absolute prefix, [`crate::relocate::make_relocatable`] proves (or fails to
//! prove) it prefix-independent, and this module ships the result so the next
//! machine skips the compile.
//!
//! # Naming scheme
//!
//! - Repository: env `ZLAYER_TOOLCHAIN_REGISTRY`, default
//!   [`DEFAULT_TOOLCHAIN_REGISTRY`] (`ghcr.io/blackleafdigital/zlayer/toolchains`).
//! - Immutable tag: `{tool}-{version}-{os}-{arch}` ([`artifact_tag`]).
//! - Movable alias: `{tool}-latest-{os}-{arch}` ([`latest_tag`]), repointed to
//!   the freshly-published manifest on every publish.
//!
//! Tag components are [sanitized](sanitize_tag_component) (lowercase, `@`→`-`,
//! anything outside `[a-z0-9._-]`→`-`, so `openssl@3` → `openssl-3`) because OCI
//! tags are a restricted grammar. The *exact* identity is never lost — it is
//! preserved verbatim in manifest annotations (`com.zlayer.toolchain.{tool,
//! version,os,arch,prefix,relocatable}`) and inside the config blob.
//!
//! # Artifact shape
//!
//! - `artifactType` = [`ARTIFACT_TYPE`] (`application/vnd.zlayer.toolchain.v1`).
//! - Config blob (`application/vnd.zlayer.toolchain.config.v1+json`) = a
//!   [`ToolchainArtifactConfig`] JSON carrying the identity, the built prefix,
//!   the relocatability flag, and the embedded [`ToolchainManifest`].
//! - ONE layer = the toolchain tree packed by
//!   [`zlayer_registry::pack::pack_dir_tar_zstd`] (excluding the `.build` /
//!   `.ready` stamps) as `tar+zstd`.

// `registry_repo` / `registry_auth_from_env` are the spec-mandated public API
// names; they repeat this module's name (`registry`) by design, so the pedantic
// naming lint is not actionable here.
#![allow(clippy::module_name_repetitions)]

use std::collections::BTreeMap;
use std::path::Path;

use serde::{Deserialize, Serialize};
use tracing::{info, warn};

use zlayer_registry::pack::{pack_dir_tar_zstd, DEFAULT_ZSTD_LEVEL};
use zlayer_registry::{
    ArtifactLayer, BlobCache, ImagePuller, LayerUnpacker, OciImageManifest, RegistryAuth,
    RegistryError,
};

use crate::error::{Result, ToolchainError};
use crate::manifest::{ToolchainManifest, ToolchainSource};
use crate::relocate::{relocate_pulled, RelocationReport};

/// Default toolchain-artifact repository when `ZLAYER_TOOLCHAIN_REGISTRY` is
/// unset. A single repo holds every tool; the structured tag disambiguates.
pub const DEFAULT_TOOLCHAIN_REGISTRY: &str = "ghcr.io/blackleafdigital/zlayer/toolchains";

/// OCI `artifactType` for a published toolchain manifest.
pub const ARTIFACT_TYPE: &str = "application/vnd.zlayer.toolchain.v1";

/// Media type of the toolchain-artifact config blob (a
/// [`ToolchainArtifactConfig`] JSON document).
pub const CONFIG_MEDIA_TYPE: &str = "application/vnd.zlayer.toolchain.config.v1+json";

/// `org.opencontainers.image.title` hint stored on the single toolchain layer.
const LAYER_TITLE: &str = "toolchain.tar.zst";

// Manifest annotation keys carrying the EXACT (un-sanitized) identity.
const ANN_TOOL: &str = "com.zlayer.toolchain.tool";
const ANN_VERSION: &str = "com.zlayer.toolchain.version";
const ANN_OS: &str = "com.zlayer.toolchain.os";
const ANN_ARCH: &str = "com.zlayer.toolchain.arch";
const ANN_PREFIX: &str = "com.zlayer.toolchain.prefix";
const ANN_RELOCATABLE: &str = "com.zlayer.toolchain.relocatable";

/// The toolchain-artifact repository: `ZLAYER_TOOLCHAIN_REGISTRY` or, when unset
/// or blank, [`DEFAULT_TOOLCHAIN_REGISTRY`].
#[must_use]
pub fn registry_repo() -> String {
    std::env::var("ZLAYER_TOOLCHAIN_REGISTRY")
        .ok()
        .filter(|s| !s.trim().is_empty())
        .unwrap_or_else(|| DEFAULT_TOOLCHAIN_REGISTRY.to_string())
}

/// The immutable artifact tag `{tool}-{version}-{os}-{arch}` (each component
/// [sanitized](sanitize_tag_component)).
#[must_use]
pub fn artifact_tag(tool: &str, version: &str, os: &str, arch: &str) -> String {
    format!(
        "{}-{}-{}-{}",
        sanitize_tag_component(tool),
        sanitize_tag_component(version),
        sanitize_tag_component(os),
        sanitize_tag_component(arch),
    )
}

/// The movable alias tag `{tool}-latest-{os}-{arch}` (each component
/// [sanitized](sanitize_tag_component)) repointed on every publish.
#[must_use]
pub fn latest_tag(tool: &str, os: &str, arch: &str) -> String {
    format!(
        "{}-latest-{}-{}",
        sanitize_tag_component(tool),
        sanitize_tag_component(os),
        sanitize_tag_component(arch),
    )
}

/// Lowercase a tag component and replace every character outside `[a-z0-9._-]`
/// (in particular `@`) with `-`, so an arbitrary tool/version/os/arch token
/// becomes a valid OCI tag segment (`openssl@3` → `openssl-3`, `2.55.0` stays).
#[must_use]
pub fn sanitize_tag_component(s: &str) -> String {
    s.chars()
        .map(|c| {
            let c = c.to_ascii_lowercase();
            match c {
                'a'..='z' | '0'..='9' | '.' | '_' | '-' => c,
                _ => '-',
            }
        })
        .collect()
}

/// Identity coordinates of a toolchain artifact: the four tokens that form its
/// immutable tag and annotations.
///
/// Bundling them avoids a wide `publish_toolchain(tool, version, os, arch, …)`
/// argument list and keeps the tool identity as one value through the pipeline.
#[derive(Debug, Clone)]
pub struct ToolchainArtifactId {
    /// Brew/tool name (e.g. `jq`, `openssl@3`) — stored verbatim in annotations.
    pub tool: String,
    /// Resolved version (e.g. `1.8.1`).
    pub version: String,
    /// Platform token (`macos` / `windows`).
    pub os: String,
    /// Architecture token (`arm64` / `x86_64`).
    pub arch: String,
}

impl ToolchainArtifactId {
    /// The immutable tag for this identity — see [`artifact_tag`].
    #[must_use]
    pub fn artifact_tag(&self) -> String {
        artifact_tag(&self.tool, &self.version, &self.os, &self.arch)
    }

    /// The movable alias tag for this identity — see [`latest_tag`].
    #[must_use]
    pub fn latest_tag(&self) -> String {
        latest_tag(&self.tool, &self.os, &self.arch)
    }
}

/// GHCR-style auth resolution for `registry_host`, mirroring
/// `zlayer_builder::macos_image_resolver::resolve_ghcr_auth`
/// (`crates/zlayer-builder/src/macos_image_resolver.rs:304`) — replicated
/// rather than imported because this leaf crate must not depend on the builder.
///
/// Order: `GHCR_TOKEN` → `GITHUB_TOKEN` → `~/.docker/config.json`
/// (`auths.<registry_host>.auth`, base64 `user:pass`) → [`RegistryAuth::Anonymous`].
#[must_use]
pub fn registry_auth_from_env(registry_host: &str) -> RegistryAuth {
    if let Ok(token) = std::env::var("GHCR_TOKEN") {
        if !token.is_empty() {
            return RegistryAuth::Basic("_token".to_string(), token);
        }
    }
    if let Ok(token) = std::env::var("GITHUB_TOKEN") {
        if !token.is_empty() {
            return RegistryAuth::Basic("_token".to_string(), token);
        }
    }
    if let Some(auth) = docker_config_auth(registry_host) {
        return auth;
    }
    RegistryAuth::Anonymous
}

/// Read `auths.<registry_host>.auth` (base64 `user:pass`) from
/// `~/.docker/config.json`, if present.
fn docker_config_auth(registry_host: &str) -> Option<RegistryAuth> {
    if registry_host.is_empty() {
        return None;
    }
    let home = std::env::var_os("HOME").or_else(|| std::env::var_os("USERPROFILE"))?;
    let path = Path::new(&home).join(".docker").join("config.json");
    let contents = std::fs::read_to_string(path).ok()?;
    let config: serde_json::Value = serde_json::from_str(&contents).ok()?;
    let auth_b64 = config
        .get("auths")?
        .get(registry_host)?
        .get("auth")?
        .as_str()?;
    let decoded = base64_decode(auth_b64.trim())?;
    let decoded = String::from_utf8(decoded).ok()?;
    let (user, pass) = decoded.split_once(':')?;
    Some(RegistryAuth::Basic(user.to_string(), pass.to_string()))
}

/// Minimal standard-alphabet base64 decoder (no external dep). Skips padding /
/// whitespace; returns `None` on any invalid character.
fn base64_decode(s: &str) -> Option<Vec<u8>> {
    fn sextet(c: u8) -> Option<u32> {
        match c {
            b'A'..=b'Z' => Some(u32::from(c - b'A')),
            b'a'..=b'z' => Some(u32::from(c - b'a') + 26),
            b'0'..=b'9' => Some(u32::from(c - b'0') + 52),
            b'+' => Some(62),
            b'/' => Some(63),
            _ => None,
        }
    }
    let mut out = Vec::new();
    let mut acc = 0u32;
    let mut bits = 0u32;
    for &c in s.as_bytes() {
        if matches!(c, b'=' | b'\n' | b'\r' | b' ' | b'\t') {
            continue;
        }
        acc = (acc << 6) | sextet(c)?;
        bits += 6;
        if bits >= 8 {
            bits -= 8;
            out.push(u8::try_from((acc >> bits) & 0xff).ok()?);
        }
    }
    Some(out)
}

/// Registry host of a repository / reference string: the segment before the
/// first `/` when it looks like a host (`.`, `:`, or `localhost`), else `""`
/// (an unqualified name has no host).
fn registry_host(reference: &str) -> &str {
    match reference.split_once('/') {
        Some((head, _)) if head.contains('.') || head.contains(':') || head == "localhost" => head,
        _ => "",
    }
}

/// The config-blob document (`application/vnd.zlayer.toolchain.config.v1+json`):
/// the toolchain identity plus the embedded [`ToolchainManifest`] the consumer
/// re-homes on pull.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolchainArtifactConfig {
    /// Schema version (currently `1`).
    pub format: u32,
    /// Tool name (verbatim, e.g. `openssl@3`).
    pub tool: String,
    /// Resolved version.
    pub version: String,
    /// Platform token.
    pub os: String,
    /// Architecture token.
    pub arch: String,
    /// The absolute prefix the toolchain was built at (its recorded prefix —
    /// what [`relocate_pulled`] rewrites away from).
    pub built_prefix: String,
    /// Whether the publisher proved the artifact fully prefix-independent. When
    /// `false`, the consumer must null-pad patch binaries and can only install
    /// at a prefix no longer than `built_prefix`.
    pub relocatable: bool,
    /// The toolchain manifest, with `path_dirs` / `env` rooted at
    /// `built_prefix`. Re-homed to the local dir on pull.
    pub manifest: ToolchainManifest,
}

/// Outcome of a successful [`publish_toolchain`].
#[derive(Debug, Clone)]
pub struct PublishedToolchain {
    /// The immutable pull reference (`{repo}:{artifact_tag}`).
    pub reference: String,
    /// The pushed manifest digest (`sha256:...`).
    pub digest: String,
}

/// Publish a relocatable toolchain at `dir` (built at `built_prefix`) to the
/// toolchain registry under both its immutable tag and its `latest` alias.
///
/// The layer is [`dir`](pack_dir_tar_zstd) minus the `.build` / `.ready`
/// stamps; the config blob is a [`ToolchainArtifactConfig`] carrying `manifest`;
/// the manifest annotations carry the exact identity + relocatability. An
/// artifact the publisher could NOT prove relocatable
/// (`!report.is_fully_relocatable()`) is STILL published, with
/// `relocatable="false"` and the built prefix recorded so the pull side can
/// null-pad patch (or decline).
///
/// The `latest` alias is repointed by a second [`push_artifact`] of byte-identical
/// content: OCI has no server-side re-tag primitive in `oci-client`, and identical
/// bytes yield the identical manifest digest, so the alias resolves to the SAME
/// manifest as the immutable tag. The blobs already exist from the first push, so
/// the registry mounts them and only the manifest + tag are written.
///
/// [`push_artifact`]: zlayer_registry::ImagePuller::push_artifact
///
/// # Errors
///
/// Returns [`ToolchainError::RegistryError`] on a packing, auth, or push failure
/// (an auth failure / anonymous-denied push is surfaced, never swallowed).
pub async fn publish_toolchain(
    dir: &Path,
    manifest: &ToolchainManifest,
    report: &RelocationReport,
    built_prefix: &Path,
    id: &ToolchainArtifactId,
) -> Result<PublishedToolchain> {
    let repo = registry_repo();
    let reference = format!("{repo}:{}", id.artifact_tag());
    let latest_ref = format!("{repo}:{}", id.latest_tag());
    let relocatable = report.is_fully_relocatable();

    let (config_blob, layer, annotations) =
        build_artifact(dir, manifest, built_prefix, id, relocatable, report).await?;

    let auth = registry_auth_from_env(registry_host(&repo));
    let cache = BlobCache::new().map_err(|e| ToolchainError::RegistryError {
        message: format!("failed to init blob cache for toolchain publish: {e}"),
    })?;
    let puller = ImagePuller::new(cache);

    let layers = std::slice::from_ref(&layer);
    info!(
        reference = %reference,
        relocatable,
        "publishing toolchain artifact"
    );
    let push = puller
        .push_artifact(
            &reference,
            ARTIFACT_TYPE,
            CONFIG_MEDIA_TYPE,
            &config_blob,
            layers,
            annotations.clone(),
            &auth,
        )
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("push toolchain artifact {reference}: {e}"),
        })?;

    // Repoint the `latest` alias to the SAME content (identical bytes → identical
    // digest → same manifest). See the fn docs for why this is a second push.
    puller
        .push_artifact(
            &latest_ref,
            ARTIFACT_TYPE,
            CONFIG_MEDIA_TYPE,
            &config_blob,
            layers,
            annotations,
            &auth,
        )
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("repoint latest alias {latest_ref}: {e}"),
        })?;

    info!(
        reference = %reference,
        digest = %push.manifest_digest,
        "toolchain artifact published"
    );
    Ok(PublishedToolchain {
        reference,
        digest: push.manifest_digest,
    })
}

/// Build the `(config_blob, layer, annotations)` triple for a publish: pack the
/// toolchain tree (excluding `.build` / `.ready`) and serialize the config.
///
/// The LIVE toolchain tree is never mutated here: text files that carry the
/// built prefix (`report.text_files_with_prefix`) must keep their real absolute
/// paths on disk so same-machine dependent builds resolve `.pc`/cmake/scripts.
/// So the tree is copied to a scratch dir, the placeholders are applied to the
/// COPY, and the copy is what gets packed. Mach-O `@loader_path` rewrites are
/// already in the live tree (done by `make_relocatable`), so the copy inherits
/// them; only the text files differ (real in the live tree, placeholdered in
/// the artifact).
async fn build_artifact(
    dir: &Path,
    manifest: &ToolchainManifest,
    built_prefix: &Path,
    id: &ToolchainArtifactId,
    relocatable: bool,
    report: &RelocationReport,
) -> Result<(Vec<u8>, ArtifactLayer, BTreeMap<String, String>)> {
    let built_prefix = built_prefix.to_string_lossy().into_owned();
    let config = ToolchainArtifactConfig {
        format: 1,
        tool: id.tool.clone(),
        version: id.version.clone(),
        os: id.os.clone(),
        arch: id.arch.clone(),
        built_prefix: built_prefix.clone(),
        relocatable,
        manifest: manifest.clone(),
    };
    let config_blob = serde_json::to_vec(&config).map_err(|e| ToolchainError::RegistryError {
        message: format!("serialize toolchain artifact config for {}: {e}", id.tool),
    })?;

    // Pack from a scratch COPY with text placeholders applied, so the live tree
    // keeps real absolute paths. When no text file carries the prefix, pack the
    // live tree directly (nothing to placeholder → no copy needed).
    let (layer_bytes, layer_media) = if report.text_files_with_prefix.is_empty() {
        let root = dir.to_path_buf();
        tokio::task::spawn_blocking(move || {
            pack_dir_tar_zstd(&root, &[".build", ".ready"], DEFAULT_ZSTD_LEVEL)
        })
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("toolchain layer packing task failed: {e}"),
        })??
    } else {
        let scratch = tempfile::tempdir().map_err(|e| ToolchainError::RegistryError {
            message: format!("create publish scratch dir for {}: {e}", id.tool),
        })?;
        let copy_root = scratch.path().join("tree");
        copy_tree(dir, &copy_root).await?;
        crate::relocate::apply_text_placeholders(
            &copy_root,
            Path::new(built_prefix.as_str()),
            dir,
            &report.text_files_with_prefix,
        )
        .await?;
        let root = copy_root.clone();
        tokio::task::spawn_blocking(move || {
            pack_dir_tar_zstd(&root, &[".build", ".ready"], DEFAULT_ZSTD_LEVEL)
        })
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("toolchain layer packing task failed: {e}"),
        })??
        // `scratch` drops here, removing the copy.
    };

    let mut annotations = BTreeMap::new();
    annotations.insert(ANN_TOOL.to_string(), id.tool.clone());
    annotations.insert(ANN_VERSION.to_string(), id.version.clone());
    annotations.insert(ANN_OS.to_string(), id.os.clone());
    annotations.insert(ANN_ARCH.to_string(), id.arch.clone());
    annotations.insert(ANN_PREFIX.to_string(), built_prefix);
    annotations.insert(
        ANN_RELOCATABLE.to_string(),
        if relocatable { "true" } else { "false" }.to_string(),
    );

    let layer = ArtifactLayer {
        data: layer_bytes,
        media_type: layer_media,
        title: Some(LAYER_TITLE.to_string()),
    };
    Ok((config_blob, layer, annotations))
}

/// Recursively copy `src` into `dest` (created), preserving directories, file
/// contents+permissions, and symlinks AS symlinks (toolchain trees carry
/// `opt/` symlinks that must survive into the packed layer). Used only to make
/// a publish scratch copy — never touches the live toolchain tree.
async fn copy_tree(src: &Path, dest: &Path) -> Result<()> {
    let mut stack = vec![(src.to_path_buf(), dest.to_path_buf())];
    while let Some((from, to)) = stack.pop() {
        let meta = tokio::fs::symlink_metadata(&from).await?;
        let ft = meta.file_type();
        if ft.is_symlink() {
            let target = tokio::fs::read_link(&from).await?;
            #[cfg(unix)]
            tokio::fs::symlink(&target, &to).await?;
            #[cfg(windows)]
            {
                // Best-effort: file symlink (dir symlinks are rare in toolchains).
                let _ = tokio::fs::symlink_file(&target, &to).await;
            }
        } else if ft.is_dir() {
            tokio::fs::create_dir_all(&to).await?;
            let mut rd = tokio::fs::read_dir(&from).await?;
            while let Some(entry) = rd.next_entry().await? {
                let name = entry.file_name();
                stack.push((from.join(&name), to.join(&name)));
            }
        } else {
            if let Some(parent) = to.parent() {
                tokio::fs::create_dir_all(parent).await?;
            }
            tokio::fs::copy(&from, &to).await?;
        }
    }
    Ok(())
}

/// Outcome of a successful [`try_pull_toolchain`].
#[derive(Debug, Clone)]
pub struct PulledToolchain {
    /// The immutable reference the toolchain was pulled from.
    pub reference: String,
    /// The manifest digest (`sha256:...`) the pull was pinned to.
    pub digest: String,
}

/// Try to pull `id`'s toolchain artifact into `dest_dir`.
///
/// Resolves `{repo}:{artifact_tag}` (anonymous first, retrying with
/// [`registry_auth_from_env`] on an auth error). A missing tag (404 /
/// manifest-unknown) is **`Ok(None)`** — the caller builds instead; a real
/// transport error is **`Err`**. On a hit the layer is unpacked into `dest_dir`
/// and [`relocate_pulled`] re-homes it from the recorded prefix to `dest_dir`.
/// A non-relocatable artifact whose local prefix would be LONGER than the
/// recorded one cannot be null-pad patched: `dest_dir` is cleared and
/// **`Ok(None)`** returned (the caller falls back to building).
///
/// The embedded manifest is re-homed (absolute built-prefix paths in
/// `path_dirs` / `env` rewritten to `dest_dir`), stamped
/// [`ToolchainSource::Registry`], and written as `dest_dir/toolchain.json`. The
/// `.ready` marker is deliberately NOT written — the caller's finalize owns it.
///
/// # Errors
///
/// Returns [`ToolchainError::RegistryError`] on a transport / unpack failure and
/// propagates relocation / I/O errors.
pub async fn try_pull_toolchain(
    id: &ToolchainArtifactId,
    dest_dir: &Path,
) -> Result<Option<PulledToolchain>> {
    let repo = registry_repo();
    let reference = format!("{repo}:{}", id.artifact_tag());
    let cache = BlobCache::new().map_err(|e| ToolchainError::RegistryError {
        message: format!("failed to init blob cache for toolchain pull: {e}"),
    })?;
    let puller = ImagePuller::new(cache);
    pull_with(&puller, &reference, dest_dir).await
}

/// Pull-and-rehome against an already-constructed [`ImagePuller`] (so tests can
/// wire a [`LocalRegistry`](zlayer_registry::LocalRegistry) in-process).
async fn pull_with(
    puller: &ImagePuller,
    reference: &str,
    dest_dir: &Path,
) -> Result<Option<PulledToolchain>> {
    let Some((manifest, digest, auth)) = resolve_manifest(puller, reference).await? else {
        info!(reference = %reference, "toolchain artifact not published; will build");
        return Ok(None);
    };

    let config = pull_config(puller, reference, &manifest, &auth).await?;

    // Pull every layer (the toolchain is one layer, but resolve generically).
    let mut layers: Vec<(Vec<u8>, String)> = Vec::with_capacity(manifest.layers.len());
    for descriptor in &manifest.layers {
        let data = puller
            .pull_blob(reference, &descriptor.digest, &auth)
            .await
            .map_err(|e| ToolchainError::RegistryError {
                message: format!(
                    "pull toolchain layer {} for {reference}: {e}",
                    descriptor.digest
                ),
            })?;
        layers.push((data, descriptor.media_type.clone()));
    }

    tokio::fs::create_dir_all(dest_dir).await?;

    // Mirror `relocate_pulled`'s guard BEFORE writing anything: a
    // non-relocatable artifact is null-pad patched in place, so it cannot grow
    // the prefix. A longer local prefix means "unusable here" → clean + build.
    let local_prefix = dest_dir.to_string_lossy().into_owned();
    if !config.relocatable && local_prefix.len() > config.built_prefix.len() {
        warn!(
            reference = %reference,
            recorded_prefix = %config.built_prefix,
            local_prefix = %local_prefix,
            "pulled toolchain is not relocatable to this (longer) local prefix; will build"
        );
        let _ = tokio::fs::remove_dir_all(dest_dir).await;
        return Ok(None);
    }

    let mut unpacker = LayerUnpacker::new(dest_dir.to_path_buf());
    unpacker
        .unpack_layers(&layers)
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("unpack toolchain layers into {}: {e}", dest_dir.display()),
        })?;

    relocate_pulled(dest_dir, &config.built_prefix, dest_dir, config.relocatable).await?;

    // Re-home the embedded manifest onto the local dir and record provenance.
    let mut rehomed = config.manifest;
    rehome_manifest(&mut rehomed, &config.built_prefix, &local_prefix);
    rehomed.source = ToolchainSource::Registry {
        reference: reference.to_string(),
        digest: digest.clone(),
    };
    rehomed.write_to_toolchain(dest_dir).await?;

    info!(reference = %reference, digest = %digest, dest = %dest_dir.display(), "toolchain artifact pulled");
    Ok(Some(PulledToolchain {
        reference: reference.to_string(),
        digest,
    }))
}

/// Resolve the artifact manifest: anonymous first, retry with env auth on an
/// auth error. `Ok(None)` on not-found OR a persistent auth failure; `Err` only
/// on a real transport error. The returned [`RegistryAuth`] is the one that
/// worked (reused for blob pulls).
///
/// A persistent 401 (anonymous 401 → retry with env creds → still 401) is
/// treated as a MISS, not an error: GHCR returns 401 for a repo/tag that does
/// not exist yet, so for our OWN toolchain repo "unauthorized after trying real
/// creds" means "nothing published here" → build it (pull-miss → build is always
/// safe). This keeps a cold/empty registry from logging a scary auth WARN on
/// every resolve.
async fn resolve_manifest(
    puller: &ImagePuller,
    reference: &str,
) -> Result<Option<(OciImageManifest, String, RegistryAuth)>> {
    match puller
        .pull_manifest(reference, &RegistryAuth::Anonymous)
        .await
    {
        Ok((manifest, digest)) => Ok(Some((manifest, digest, RegistryAuth::Anonymous))),
        Err(ref e) if err_is_not_found(e) => Ok(None),
        Err(ref e) if err_is_auth(e) => {
            let auth = registry_auth_from_env(registry_host(reference));
            match puller.pull_manifest(reference, &auth).await {
                Ok((manifest, digest)) => Ok(Some((manifest, digest, auth))),
                // Not-found OR still-unauthorized after real creds == not
                // published to us yet → miss, build it (never a scary warn).
                Err(ref e2) if err_is_not_found(e2) || err_is_auth(e2) => Ok(None),
                Err(e2) => Err(ToolchainError::RegistryError {
                    message: format!("pull toolchain manifest {reference} (authed): {e2}"),
                }),
            }
        }
        Err(e) => Err(ToolchainError::RegistryError {
            message: format!("pull toolchain manifest {reference}: {e}"),
        }),
    }
}

/// Pull + parse the config blob referenced by `manifest.config`.
async fn pull_config(
    puller: &ImagePuller,
    reference: &str,
    manifest: &OciImageManifest,
    auth: &RegistryAuth,
) -> Result<ToolchainArtifactConfig> {
    let bytes = puller
        .pull_blob(reference, &manifest.config.digest, auth)
        .await
        .map_err(|e| ToolchainError::RegistryError {
            message: format!("pull toolchain config blob for {reference}: {e}"),
        })?;
    serde_json::from_slice(&bytes).map_err(|e| ToolchainError::RegistryError {
        message: format!("parse toolchain config blob for {reference}: {e}"),
    })
}

/// Rewrite every absolute `recorded`-prefixed string in the manifest's
/// `path_dirs` / `env` values to `local` (the pulled dir).
fn rehome_manifest(manifest: &mut ToolchainManifest, recorded: &str, local: &str) {
    for dir in &mut manifest.path_dirs {
        if dir.contains(recorded) {
            *dir = dir.replace(recorded, local);
        }
    }
    for value in manifest.env.values_mut() {
        if value.contains(recorded) {
            *value = value.replace(recorded, local);
        }
    }
}

/// Does this registry error mean "the manifest/tag does not exist" (→ `Ok(None)`)
/// as opposed to a real transport failure (→ `Err`)?
///
/// A structural [`RegistryError::NotFound`] is definitive. `oci-client` surfaces a
/// registry 404 as an [`RegistryError::Oci`] whose `Display` we cannot match
/// structurally without depending on `oci-client`, so we string-match the
/// documented not-found shapes (see [`msg_is_not_found`]).
fn err_is_not_found(err: &RegistryError) -> bool {
    matches!(err, RegistryError::NotFound { .. }) || msg_is_not_found(&err.to_string())
}

/// Not-found substrings across `oci-client`'s error `Display`s:
/// `ImageManifestNotFoundError` ("… not found"), a 404 `ServerError`
/// ("code: 404"), and registry-envelope codes
/// (`MANIFEST_UNKNOWN`/`NAME_UNKNOWN`/`BLOB_UNKNOWN`/`NOT_FOUND`).
fn msg_is_not_found(msg: &str) -> bool {
    let m = msg.to_ascii_lowercase();
    m.contains("not found")
        || m.contains("notfound")
        || m.contains("not_found")
        || m.contains("manifest unknown")
        || m.contains("manifestunknown")
        || m.contains("manifest_unknown")
        || m.contains("name unknown")
        || m.contains("nameunknown")
        || m.contains("name_unknown")
        || m.contains("blob unknown")
        || m.contains("blobunknown")
        || m.contains("blob_unknown")
        || m.contains("code: 404")
        || m.contains("404")
}

/// Does this error indicate an auth failure (→ retry with env credentials)?
fn err_is_auth(err: &RegistryError) -> bool {
    matches!(err, RegistryError::AuthFailed { .. }) || msg_is_auth(&err.to_string())
}

/// Auth-failure substrings across `oci-client`'s error `Display`s
/// (`AuthenticationFailure`, `Not authorized`, a 401 `ServerError`).
fn msg_is_auth(msg: &str) -> bool {
    let m = msg.to_ascii_lowercase();
    m.contains("authentication fail")
        || m.contains("not authorized")
        || m.contains("unauthorized")
        || m.contains("code: 401")
        || m.contains("401")
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::relocate::TEXT_PLACEHOLDER;
    use std::collections::HashMap;
    use std::sync::Arc;
    use zlayer_registry::{BlobCache, BlobCacheBackend, LocalRegistry};

    // -- tag sanitization ---------------------------------------------------

    #[test]
    fn sanitize_lowercases_and_replaces_specials() {
        assert_eq!(sanitize_tag_component("openssl@3"), "openssl-3");
        assert_eq!(sanitize_tag_component("GIT"), "git");
        assert_eq!(sanitize_tag_component("2.55.0"), "2.55.0");
        assert_eq!(
            sanitize_tag_component("weird/name space!"),
            "weird-name-space-"
        );
        // Dots, dashes, underscores survive; everything else collapses to `-`.
        assert_eq!(sanitize_tag_component("a_b-c.d"), "a_b-c.d");
    }

    #[test]
    fn artifact_and_latest_tags_are_structured_and_sanitized() {
        assert_eq!(
            artifact_tag("openssl@3", "3", "macos", "arm64"),
            "openssl-3-3-macos-arm64"
        );
        assert_eq!(
            artifact_tag("GIT", "2.55.0", "macOS", "ARM64"),
            "git-2.55.0-macos-arm64"
        );
        assert_eq!(latest_tag("jq", "macos", "arm64"), "jq-latest-macos-arm64");

        let id = ToolchainArtifactId {
            tool: "jq".to_string(),
            version: "1.8.1".to_string(),
            os: "macos".to_string(),
            arch: "arm64".to_string(),
        };
        assert_eq!(id.artifact_tag(), "jq-1.8.1-macos-arm64");
        assert_eq!(id.latest_tag(), "jq-latest-macos-arm64");
        assert_ne!(id.artifact_tag(), id.latest_tag());
    }

    #[test]
    fn registry_repo_defaults_and_reads_env() {
        // The default holds unless the env var is set; exercised without
        // mutating process env (which would race other tests).
        assert_eq!(
            DEFAULT_TOOLCHAIN_REGISTRY,
            "ghcr.io/blackleafdigital/zlayer/toolchains"
        );
        assert!(registry_repo().contains("toolchains"));
    }

    // -- 404-vs-transport / auth classifiers --------------------------------

    #[test]
    fn not_found_classifier_matches_oci_not_found_shapes() {
        assert!(msg_is_not_found("Image manifest not found: foo"));
        assert!(msg_is_not_found(
            "Registry error: url x, envelope: MANIFEST_UNKNOWN"
        ));
        assert!(msg_is_not_found(
            "Server error: url x, code: 404, message: nope"
        ));
        assert!(msg_is_not_found("NAME_UNKNOWN"));
        // Transport failures are NOT not-found.
        assert!(!msg_is_not_found("connection refused"));
        assert!(!msg_is_not_found("dns error: failed to lookup host"));
        assert!(!msg_is_not_found("operation timed out"));

        // Structural NotFound is definitive.
        assert!(err_is_not_found(&RegistryError::NotFound {
            registry: "local".to_string(),
            image: "x".to_string(),
        }));
    }

    #[test]
    fn auth_classifier_matches_oci_auth_shapes() {
        assert!(msg_is_auth("Authentication failure: bad creds"));
        assert!(msg_is_auth("Not authorized: url https://ghcr.io/token"));
        assert!(msg_is_auth(
            "Server error: url x, code: 401, message: denied"
        ));
        assert!(!msg_is_auth("Image manifest not found: foo"));
        assert!(err_is_auth(&RegistryError::AuthFailed {
            registry: "ghcr.io".to_string(),
            reason: "denied".to_string(),
        }));
    }

    #[test]
    fn rehome_manifest_rewrites_prefix_paths() {
        let mut env = HashMap::new();
        env.insert("JQ_LIB".to_string(), "/built/tc/lib".to_string());
        env.insert("UNRELATED".to_string(), "keepme".to_string());
        let mut m = ToolchainManifest {
            tool: "jq".to_string(),
            version: "1.8.1".to_string(),
            arch: "arm64".to_string(),
            platform: "macos".to_string(),
            path_dirs: vec!["/built/tc/bin".to_string()],
            env,
            source: ToolchainSource::SourceBuild {
                url: String::new(),
                sha256: String::new(),
            },
            build_deps: vec![],
            provisioned_at: String::new(),
        };
        rehome_manifest(&mut m, "/built/tc", "/local/dest");
        assert_eq!(m.path_dirs, vec!["/local/dest/bin".to_string()]);
        assert_eq!(m.env.get("JQ_LIB").unwrap(), "/local/dest/lib");
        assert_eq!(m.env.get("UNRELATED").unwrap(), "keepme");
    }

    #[test]
    fn base64_decode_round_trips_user_pass() {
        // base64("_token:ghp_abc123") == "X3Rva2VuOmdocF9hYmMxMjM="
        let decoded = base64_decode("X3Rva2VuOmdocF9hYmMxMjM=").unwrap();
        assert_eq!(String::from_utf8(decoded).unwrap(), "_token:ghp_abc123");
        assert!(base64_decode("not base64 %%%").is_none());
    }

    // -- LocalRegistry-backed pull round trip (in-process, no network) -------

    /// A tiny fixture toolchain tree: a bin file, a lib symlink, a text file
    /// containing the relocation placeholder, and top-level `.build`/`.ready`
    /// stamps that MUST be excluded from the layer.
    #[cfg(unix)]
    async fn build_fixture_toolchain(src: &Path) {
        tokio::fs::create_dir_all(src.join("bin")).await.unwrap();
        tokio::fs::create_dir_all(src.join("lib")).await.unwrap();
        tokio::fs::create_dir_all(src.join("share")).await.unwrap();
        tokio::fs::write(src.join("bin/jq"), b"#!/bin/sh\nexit 0\n")
            .await
            .unwrap();
        // A .pc-style text file as a PUBLISHED ARTIFACT carries it: the built
        // prefix has been replaced by the placeholder (on the publish copy).
        // The pull path (relocate_pulled) restores it to the local prefix.
        tokio::fs::write(
            src.join("share/jq.pc"),
            format!("prefix={TEXT_PLACEHOLDER}\nlibdir={TEXT_PLACEHOLDER}/lib\n"),
        )
        .await
        .unwrap();
        std::os::unix::fs::symlink("../bin/jq", src.join("lib/jq-link")).unwrap();
        tokio::fs::create_dir_all(src.join(".build")).await.unwrap();
        tokio::fs::write(src.join(".build/stamp"), b"x")
            .await
            .unwrap();
        tokio::fs::write(src.join(".ready"), b"").await.unwrap();
    }

    /// Store a toolchain artifact (config + one layer + annotated manifest)
    /// directly into a [`LocalRegistry`] under `{repo}:{tag}`, exactly as a
    /// publish would leave it — so the pull path resolves it with no network.
    /// Returns the manifest content digest.
    async fn seed_artifact(
        registry: &LocalRegistry,
        repo: &str,
        tag: &str,
        layer_bytes: &[u8],
        layer_media: &str,
        config: &ToolchainArtifactConfig,
    ) -> String {
        let config_blob = serde_json::to_vec(config).unwrap();
        let config_digest = registry.put_blob(&config_blob).await.unwrap();
        let layer_digest = registry.put_blob(layer_bytes).await.unwrap();
        let manifest_json = format!(
            concat!(
                r#"{{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","#,
                r#""artifactType":"{artifact_type}","#,
                r#""config":{{"mediaType":"{config_media}","digest":"{config_digest}","size":{config_size}}},"#,
                r#""layers":[{{"mediaType":"{layer_media}","digest":"{layer_digest}","size":{layer_size}}}],"#,
                r#""annotations":{{"{ann_tool}":"{tool}","{ann_reloc}":"{reloc}"}}}}"#
            ),
            artifact_type = ARTIFACT_TYPE,
            config_media = CONFIG_MEDIA_TYPE,
            config_digest = config_digest,
            config_size = config_blob.len(),
            layer_media = layer_media,
            layer_digest = layer_digest,
            layer_size = layer_bytes.len(),
            ann_tool = ANN_TOOL,
            tool = config.tool,
            ann_reloc = ANN_RELOCATABLE,
            reloc = config.relocatable,
        );
        registry
            .put_manifest(repo, tag, manifest_json.as_bytes())
            .await
            .unwrap()
    }

    fn local_puller(registry: &Arc<LocalRegistry>) -> ImagePuller {
        let cache: Arc<Box<dyn BlobCacheBackend>> = Arc::new(Box::new(BlobCache::new().unwrap()));
        ImagePuller::with_cache(cache).with_local_registry(registry.clone())
    }

    fn fixture_config(built_prefix: &str, relocatable: bool) -> ToolchainArtifactConfig {
        let mut env = HashMap::new();
        env.insert("JQ_LIB".to_string(), format!("{built_prefix}/lib"));
        ToolchainArtifactConfig {
            format: 1,
            tool: "jq".to_string(),
            version: "1.8.1".to_string(),
            os: "macos".to_string(),
            arch: "arm64".to_string(),
            built_prefix: built_prefix.to_string(),
            relocatable,
            manifest: ToolchainManifest {
                tool: "jq".to_string(),
                version: "1.8.1".to_string(),
                arch: "arm64".to_string(),
                platform: "macos".to_string(),
                path_dirs: vec![format!("{built_prefix}/bin")],
                env,
                source: ToolchainSource::SourceBuild {
                    url: String::new(),
                    sha256: String::new(),
                },
                build_deps: vec![],
                provisioned_at: "2026-07-06T00:00:00Z".to_string(),
            },
        }
    }

    /// The publish path must NOT mutate the live toolchain tree: text files
    /// keep their real prefix on disk (so same-machine dependents read them),
    /// while the PACKED artifact carries the placeholder. Proven end-to-end by
    /// `make_relocatable` (records) → `build_artifact` (packs a placeholdered
    /// copy) → pull (rehomes the placeholder to the dest prefix).
    #[cfg(unix)]
    #[tokio::test]
    async fn publish_placeholders_a_copy_not_the_live_tree() {
        let tmp = tempfile::tempdir().unwrap();
        let src = tmp.path().join("jq-1.8.1-macos-arm64");
        tokio::fs::create_dir_all(src.join("bin")).await.unwrap();
        tokio::fs::create_dir_all(src.join("share")).await.unwrap();
        tokio::fs::write(src.join("bin/jq"), b"#!/bin/sh\nexit 0\n")
            .await
            .unwrap();
        let real = src.to_string_lossy().into_owned();
        let pc = src.join("share/jq.pc");
        tokio::fs::write(&pc, format!("prefix={real}\nlibdir={real}/lib\n"))
            .await
            .unwrap();

        let report = crate::relocate::make_relocatable(&src, &src, &[])
            .await
            .unwrap();
        assert_eq!(report.text_files_with_prefix, vec![pc.clone()]);
        assert!(
            tokio::fs::read_to_string(&pc)
                .await
                .unwrap()
                .contains(&real),
            "make_relocatable must leave the live .pc real-pathed"
        );

        let config = fixture_config(&real, report.is_fully_relocatable());
        let id = ToolchainArtifactId {
            tool: "jq".to_string(),
            version: "1.8.1".to_string(),
            os: "macos".to_string(),
            arch: "arm64".to_string(),
        };
        let (_cfg, layer, _ann) = build_artifact(
            &src,
            &config.manifest,
            &src,
            &id,
            report.is_fully_relocatable(),
            &report,
        )
        .await
        .unwrap();

        // The publish packing left the LIVE tree untouched.
        assert!(
            tokio::fs::read_to_string(&pc)
                .await
                .unwrap()
                .contains(&real),
            "publish must not mutate the live toolchain tree"
        );

        // The packed artifact carries the placeholder — prove via a pull.
        let registry = Arc::new(LocalRegistry::new(tmp.path().join("reg")).await.unwrap());
        let repo = registry_repo();
        let tag = id.artifact_tag();
        seed_artifact(
            &registry,
            &repo,
            &tag,
            &layer.data,
            &layer.media_type,
            &config,
        )
        .await;
        let dest = tmp.path().join("dest");
        pull_with(&local_puller(&registry), &format!("{repo}:{tag}"), &dest)
            .await
            .unwrap()
            .expect("pull");
        let dest_pc = tokio::fs::read_to_string(dest.join("share/jq.pc"))
            .await
            .unwrap();
        assert!(
            !dest_pc.contains(TEXT_PLACEHOLDER),
            "pull left a placeholder: {dest_pc}"
        );
        assert!(
            dest_pc.contains(&dest.to_string_lossy().into_owned()),
            "pulled .pc must be rehomed to the dest prefix; got: {dest_pc}"
        );
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn pull_round_trip_from_local_registry_rehomes_and_stamps_source() {
        let tmp = tempfile::tempdir().unwrap();
        let src = tmp.path().join("src");
        build_fixture_toolchain(&src).await;

        let built_prefix = "/opt/zlayer/toolchains/jq-1.8.1-macos-arm64";
        let (layer_bytes, layer_media) =
            pack_dir_tar_zstd(&src, &[".build", ".ready"], DEFAULT_ZSTD_LEVEL).unwrap();
        let config = fixture_config(built_prefix, true);

        let registry = Arc::new(LocalRegistry::new(tmp.path().join("reg")).await.unwrap());
        let repo = registry_repo();
        let tag = artifact_tag("jq", "1.8.1", "macos", "arm64");
        let man_digest =
            seed_artifact(&registry, &repo, &tag, &layer_bytes, &layer_media, &config).await;

        let puller = local_puller(&registry);
        let reference = format!("{repo}:{tag}");
        let dest = tmp.path().join("dest");
        let got = pull_with(&puller, &reference, &dest)
            .await
            .unwrap()
            .expect("published toolchain should pull");

        assert_eq!(got.reference, reference);
        assert_eq!(got.digest, man_digest);

        // Tree materialized; `.build`/`.ready` excluded.
        assert!(dest.join("bin/jq").is_file());
        assert!(std::fs::symlink_metadata(dest.join("lib/jq-link"))
            .unwrap()
            .is_symlink());
        assert!(!dest.join(".build").exists());
        assert!(!dest.join(".ready").exists());

        // Placeholder rewritten to the LOCAL dest prefix.
        let pc = tokio::fs::read_to_string(dest.join("share/jq.pc"))
            .await
            .unwrap();
        assert!(!pc.contains(TEXT_PLACEHOLDER), "placeholder survived: {pc}");
        assert!(
            pc.contains(&dest.to_string_lossy().into_owned()),
            "not re-homed: {pc}"
        );

        // Manifest written, source == Registry, paths re-homed onto dest.
        let m = ToolchainManifest::read_from_toolchain(&dest)
            .await
            .unwrap()
            .unwrap();
        match &m.source {
            ToolchainSource::Registry {
                reference: r,
                digest: d,
            } => {
                assert_eq!(r, &reference);
                assert_eq!(d, &man_digest);
            }
            other => panic!("expected Registry source, got {other:?}"),
        }
        assert_eq!(m.path_dirs, vec![dest.join("bin").display().to_string()]);
        assert_eq!(
            m.env.get("JQ_LIB").unwrap(),
            &dest.join("lib").display().to_string()
        );

        // `.ready` is the caller's to write — pull must not stamp it.
        assert!(!dest.join(".ready").exists());
    }

    #[tokio::test]
    async fn pull_miss_returns_none() {
        let tmp = tempfile::tempdir().unwrap();
        // Empty local registry + an unqualified reference with no default
        // registry ⇒ a clean not-found, no network.
        let registry = Arc::new(LocalRegistry::new(tmp.path().join("reg")).await.unwrap());
        let puller = local_puller(&registry);
        let dest = tmp.path().join("dest");
        let res = pull_with(&puller, "zlayertesttoolchains:jq-9.9.9-macos-arm64", &dest)
            .await
            .unwrap();
        assert!(res.is_none(), "a never-published tag must pull to None");
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn latest_alias_resolves_to_same_digest_as_immutable_tag() {
        let tmp = tempfile::tempdir().unwrap();
        let src = tmp.path().join("src");
        build_fixture_toolchain(&src).await;
        let (layer_bytes, layer_media) =
            pack_dir_tar_zstd(&src, &[".build", ".ready"], DEFAULT_ZSTD_LEVEL).unwrap();
        let config = fixture_config("/opt/zlayer/toolchains/jq-1.8.1-macos-arm64", true);

        let registry = Arc::new(LocalRegistry::new(tmp.path().join("reg")).await.unwrap());
        let repo = registry_repo();
        let tag = artifact_tag("jq", "1.8.1", "macos", "arm64");
        let latest = latest_tag("jq", "macos", "arm64");

        // Publish repoints `latest` to the SAME content as the immutable tag;
        // store both to the same bytes and prove both refs resolve identically.
        let tag_digest =
            seed_artifact(&registry, &repo, &tag, &layer_bytes, &layer_media, &config).await;
        let latest_digest = seed_artifact(
            &registry,
            &repo,
            &latest,
            &layer_bytes,
            &layer_media,
            &config,
        )
        .await;
        assert_eq!(
            tag_digest, latest_digest,
            "same content ⇒ same manifest digest"
        );

        let puller = local_puller(&registry);
        let (_m1, d1) = puller
            .pull_manifest(&format!("{repo}:{tag}"), &RegistryAuth::Anonymous)
            .await
            .unwrap();
        let (_m2, d2) = puller
            .pull_manifest(&format!("{repo}:{latest}"), &RegistryAuth::Anonymous)
            .await
            .unwrap();
        assert_eq!(
            d1, d2,
            "latest alias must resolve to the immutable tag's digest"
        );
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn unrelocatable_longer_prefix_cleans_dest_and_returns_none() {
        let tmp = tempfile::tempdir().unwrap();
        let src = tmp.path().join("src");
        build_fixture_toolchain(&src).await;
        let (layer_bytes, layer_media) =
            pack_dir_tar_zstd(&src, &[".build", ".ready"], DEFAULT_ZSTD_LEVEL).unwrap();
        // relocatable=false + a SHORT recorded prefix ⇒ any tempdir dest is
        // longer ⇒ null-pad patching impossible ⇒ decline + clean.
        let config = fixture_config("/x", false);

        let registry = Arc::new(LocalRegistry::new(tmp.path().join("reg")).await.unwrap());
        let repo = registry_repo();
        let tag = artifact_tag("jq", "1.8.1", "macos", "arm64");
        seed_artifact(&registry, &repo, &tag, &layer_bytes, &layer_media, &config).await;

        let puller = local_puller(&registry);
        let dest = tmp.path().join("dest-much-longer-than-slash-x");
        let res = pull_with(&puller, &format!("{repo}:{tag}"), &dest)
            .await
            .unwrap();
        assert!(res.is_none(), "unrelocatable-to-longer-prefix must decline");
        assert!(!dest.exists(), "partial dest must be cleaned");
    }

    /// The real network path: `publish_toolchain` pushes to an actual registry
    /// (immutable tag + `latest` repoint), then `try_pull_toolchain` pulls it
    /// back. Ignored — needs `ZLAYER_TOOLCHAIN_REGISTRY` pointing at a writable
    /// repo plus `GHCR_TOKEN`/`GITHUB_TOKEN` (or `~/.docker/config.json`) auth.
    /// Run with: `cargo test -p zlayer-toolchain -- --ignored live_publish`.
    #[cfg(unix)]
    #[tokio::test]
    #[ignore = "live: pushes to a real OCI registry (ZLAYER_TOOLCHAIN_REGISTRY + auth)"]
    async fn live_publish_then_pull_round_trip() {
        let tmp = tempfile::tempdir().unwrap();
        let src = tmp.path().join("src");
        build_fixture_toolchain(&src).await;

        let built_prefix = src.canonicalize().unwrap();
        let id = ToolchainArtifactId {
            tool: "zlayer-selftest".to_string(),
            version: "0.0.1".to_string(),
            os: "macos".to_string(),
            arch: "arm64".to_string(),
        };
        let manifest = fixture_config(&built_prefix.to_string_lossy(), true).manifest;
        let report = RelocationReport::default(); // no residue ⇒ fully relocatable

        let published = publish_toolchain(&src, &manifest, &report, &built_prefix, &id)
            .await
            .expect("publish should succeed against the configured registry");
        assert!(published.reference.ends_with(&id.artifact_tag()));

        let dest = tmp.path().join("dest");
        let pulled = try_pull_toolchain(&id, &dest)
            .await
            .expect("pull should not error")
            .expect("the just-published toolchain should pull");
        assert_eq!(pulled.digest, published.digest);
        assert!(dest.join("bin/jq").is_file());
    }
}