zlayer_builder/

builder.rs

//! `ImageBuilder` - High-level API for building container images
//!
//! This module provides the [`ImageBuilder`] type which orchestrates the full
//! container image build process, from Dockerfile parsing through buildah
//! execution to final image creation.
//!
//! # Example
//!
//! ```no_run
//! use zlayer_builder::{ImageBuilder, Runtime};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Build from a Dockerfile
//!     let image = ImageBuilder::new("./my-app").await?
//!         .tag("myapp:latest")
//!         .tag("myapp:v1.0.0")
//!         .build()
//!         .await?;
//!
//!     println!("Built image: {}", image.image_id);
//!     Ok(())
//! }
//! ```
//!
//! # Using Runtime Templates
//!
//! ```no_run
//! use zlayer_builder::{ImageBuilder, Runtime};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Build using a runtime template (no Dockerfile needed)
//!     let image = ImageBuilder::new("./my-node-app").await?
//!         .runtime(Runtime::Node20)
//!         .tag("myapp:latest")
//!         .build()
//!         .await?;
//!
//!     println!("Built image: {}", image.image_id);
//!     Ok(())
//! }
//! ```
//!
//! # Multi-stage Builds with Target
//!
//! ```no_run
//! use zlayer_builder::ImageBuilder;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Build only up to a specific stage
//!     let image = ImageBuilder::new("./my-app").await?
//!         .target("builder")
//!         .tag("myapp:builder")
//!         .build()
//!         .await?;
//!
//!     println!("Built intermediate image: {}", image.image_id);
//!     Ok(())
//! }
//! ```
//!
//! # With TUI Progress Updates
//!
//! ```no_run
//! use zlayer_builder::{ImageBuilder, BuildEvent};
//! use std::sync::mpsc;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let (tx, rx) = mpsc::channel::<BuildEvent>();
//!
//!     // Start TUI in another thread
//!     std::thread::spawn(move || {
//!         // Process events from rx...
//!         while let Ok(event) = rx.recv() {
//!             println!("Event: {:?}", event);
//!         }
//!     });
//!
//!     let image = ImageBuilder::new("./my-app").await?
//!         .tag("myapp:latest")
//!         .with_events(tx)
//!         .build()
//!         .await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! # With Cache Backend (requires `cache` feature)
//!
//! ```no_run,ignore
//! use zlayer_builder::ImageBuilder;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let image = ImageBuilder::new("./my-app").await?
//!         .with_cache_dir("/var/cache/zlayer")  // Use persistent disk cache
//!         .tag("myapp:latest")
//!         .build()
//!         .await?;
//!
//!     println!("Built image: {}", image.image_id);
//!     Ok(())
//! }
//! ```

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

use tokio::fs;
#[cfg(feature = "local-registry")]
use tracing::warn;
use tracing::{debug, info, instrument};
#[cfg(feature = "local-registry")]
use zlayer_paths::ZLayerDirs;

use crate::backend::BuildBackend;
#[cfg(feature = "local-registry")]
use crate::buildah::BuildahCommand;
use crate::buildah::BuildahExecutor;
use crate::dockerfile::{Dockerfile, RunMount};
use crate::error::{BuildError, Result};
use crate::templates::{get_template, Runtime};
use crate::tui::BuildEvent;

#[cfg(feature = "cache")]
use zlayer_registry::cache::BlobCacheBackend;

#[cfg(feature = "local-registry")]
use zlayer_registry::LocalRegistry;

#[cfg(feature = "local-registry")]
use zlayer_registry::import_image;

/// Output from parsing a `ZImagefile` - either a Dockerfile for container builds
/// or a WASM build result for WebAssembly builds.
///
/// Most `ZImagefile` modes (runtime, single-stage, multi-stage) produce a
/// [`Dockerfile`] IR that is then built with buildah. WASM mode produces
/// a compiled artifact directly, bypassing the container build pipeline.
#[derive(Debug)]
pub enum BuildOutput {
    /// Standard container build - produces a Dockerfile to be built with buildah.
    Dockerfile(Dockerfile),
    /// WASM component build - already built, produces artifact path.
    WasmArtifact {
        /// Path to the compiled WASM binary.
        wasm_path: PathBuf,
        /// Path to the OCI artifact directory (if exported).
        oci_path: Option<PathBuf>,
        /// OCI manifest digest (e.g. `sha256:...`) for the exported artifact,
        /// or `None` if export did not run (should always be `Some` when
        /// `oci_path` is `Some`).
        manifest_digest: Option<String>,
        /// OCI artifact type (e.g. `application/vnd.wasm.component.v1+wasm`).
        artifact_type: Option<String>,
        /// Source language used.
        language: String,
        /// Whether optimization was applied.
        optimized: bool,
        /// Size of the output file in bytes.
        size: u64,
    },
}

/// Configuration for the layer cache backend.
///
/// This enum specifies which cache backend to use for storing and retrieving
/// cached layers during builds. The cache feature must be enabled for this
/// to be available.
///
/// # Example
///
/// ```no_run,ignore
/// use zlayer_builder::{ImageBuilder, CacheBackendConfig};
///
/// # async fn example() -> Result<(), zlayer_builder::BuildError> {
/// // Use persistent disk cache
/// let builder = ImageBuilder::new("./my-app").await?
///     .with_cache_config(CacheBackendConfig::Persistent {
///         path: "/var/cache/zlayer".into(),
///     })
///     .tag("myapp:latest");
/// # Ok(())
/// # }
/// ```
#[cfg(feature = "cache")]
#[derive(Debug, Clone, Default)]
pub enum CacheBackendConfig {
    /// In-memory cache (cleared when process exits).
    ///
    /// Useful for CI/CD environments where persistence isn't needed
    /// but you want to avoid re-downloading base image layers within
    /// a single build session.
    #[default]
    Memory,

    /// Persistent disk-based cache using redb.
    ///
    /// Requires the `cache-persistent` feature. Layers are stored on disk
    /// and persist across builds, significantly speeding up repeated builds.
    #[cfg(feature = "cache-persistent")]
    Persistent {
        /// Path to the cache directory or database file.
        /// If a directory, `blob_cache.redb` will be created inside it.
        path: PathBuf,
    },

    /// S3-compatible object storage backend.
    ///
    /// Requires the `cache-s3` feature. Useful for distributed build systems
    /// where multiple build machines need to share a cache.
    #[cfg(feature = "cache-s3")]
    S3 {
        /// S3 bucket name
        bucket: String,
        /// AWS region (optional, uses SDK default if not set)
        region: Option<String>,
        /// Custom endpoint URL (for S3-compatible services like R2, B2, `MinIO`)
        endpoint: Option<String>,
        /// Key prefix for cached blobs (default: "zlayer/layers/")
        prefix: Option<String>,
    },
}

/// Built image information returned after a successful build
#[derive(Debug, Clone)]
pub struct BuiltImage {
    /// Image ID (sha256:...)
    pub image_id: String,
    /// Applied tags
    pub tags: Vec<String>,
    /// Number of layers in the final image
    pub layer_count: usize,
    /// Total size in bytes (0 if not computed)
    pub size: u64,
    /// Build duration in milliseconds
    pub build_time_ms: u64,
    /// Whether this image is a manifest list (multi-arch).
    pub is_manifest: bool,
}

/// Registry authentication credentials
#[derive(Debug, Clone)]
pub struct RegistryAuth {
    /// Registry username
    pub username: String,
    /// Registry password or token
    pub password: String,
}

impl RegistryAuth {
    /// Create new registry authentication
    pub fn new(username: impl Into<String>, password: impl Into<String>) -> Self {
        Self {
            username: username.into(),
            password: password.into(),
        }
    }
}

/// Strategy for pulling the base image before building.
///
/// Controls the `--pull` flag passed to `buildah from`. The default is
/// [`PullBaseMode::Newer`], matching the behaviour users expect from
/// modern build tools: fast when nothing has changed, correct when the
/// upstream base image has been republished.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum PullBaseMode {
    /// Pull only if the registry has a newer version (`--pull=newer`).
    /// Default behaviour.
    #[default]
    Newer,
    /// Always pull, even if a local copy exists (`--pull=always`).
    Always,
    /// Never pull — use whatever is in local storage (no `--pull` flag passed).
    Never,
}

/// Build options for customizing the image build process
#[derive(Debug, Clone)]
#[allow(clippy::struct_excessive_bools)]
pub struct BuildOptions {
    /// Dockerfile path (default: Dockerfile in context)
    pub dockerfile: Option<PathBuf>,
    /// `ZImagefile` path (alternative to Dockerfile)
    pub zimagefile: Option<PathBuf>,
    /// Use runtime template instead of Dockerfile
    pub runtime: Option<Runtime>,
    /// Build arguments (ARG values)
    pub build_args: HashMap<String, String>,
    /// Pipeline variables (`${VAR}`) expanded into the `ZImagefile` body
    /// (`base:`, `run:`, ...) before parsing. Used by the pipeline executor to
    /// parametrize a single `ZImagefile` set across e.g. Windows LTSC lines
    /// (`--set LTSC=ltsc2025`). Empty for direct (non-pipeline) builds.
    /// Only applied to `ZImagefile` bodies, never to Dockerfiles (whose
    /// `${ARG}` syntax is parsed natively).
    pub pipeline_vars: HashMap<String, String>,
    /// Target stage for multi-stage builds
    pub target: Option<String>,
    /// Image tags to apply
    pub tags: Vec<String>,
    /// Disable layer caching
    pub no_cache: bool,
    /// Push to registry after build
    pub push: bool,
    /// Registry auth (if pushing)
    pub registry_auth: Option<RegistryAuth>,
    /// Squash all layers into one
    pub squash: bool,
    /// Image format (oci or docker)
    pub format: Option<String>,
    /// Enable buildah layer caching (--layers flag for `buildah build`).
    /// Default: true
    ///
    /// Note: `ZLayer` uses manual container creation (`buildah from`, `buildah run`,
    /// `buildah commit`) rather than `buildah build`, so this flag is reserved
    /// for future use when/if we switch to `buildah build` (bud) command.
    pub layers: bool,
    /// Registry to pull cache from (--cache-from for `buildah build`).
    ///
    /// Note: This would be used with `buildah build --cache-from=<registry>`.
    /// Currently `ZLayer` uses manual container creation, so this is reserved
    /// for future implementation or for switching to `buildah build`.
    ///
    /// TODO: Implement remote cache support. This would require either:
    /// 1. Switching to `buildah build` command which supports --cache-from natively
    /// 2. Implementing custom layer caching with registry push/pull for intermediate layers
    pub cache_from: Option<String>,
    /// Registry to push cache to (--cache-to for `buildah build`).
    ///
    /// Note: This would be used with `buildah build --cache-to=<registry>`.
    /// Currently `ZLayer` uses manual container creation, so this is reserved
    /// for future implementation or for switching to `buildah build`.
    ///
    /// TODO: Implement remote cache support. This would require either:
    /// 1. Switching to `buildah build` command which supports --cache-to natively
    /// 2. Implementing custom layer caching with registry push/pull for intermediate layers
    pub cache_to: Option<String>,
    /// Maximum cache age (--cache-ttl for `buildah build`).
    ///
    /// Note: This would be used with `buildah build --cache-ttl=<duration>`.
    /// Currently `ZLayer` uses manual container creation, so this is reserved
    /// for future implementation or for switching to `buildah build`.
    ///
    /// TODO: Implement cache TTL support. This would require either:
    /// 1. Switching to `buildah build` command which supports --cache-ttl natively
    /// 2. Implementing custom cache expiration logic for our layer caching system
    pub cache_ttl: Option<std::time::Duration>,
    /// Cache backend configuration (requires `cache` feature).
    ///
    /// When configured, the builder will store layer data in the specified
    /// cache backend for faster subsequent builds. This is separate from
    /// buildah's native caching and operates at the `ZLayer` level.
    ///
    /// # Integration Points
    ///
    /// The cache backend is used at several points during the build:
    ///
    /// 1. **Before instruction execution**: Check if a cached layer exists
    ///    for the (`instruction_hash`, `base_layer`) tuple
    /// 2. **After instruction execution**: Store the resulting layer data
    ///    in the cache for future builds
    /// 3. **Base image layers**: Cache pulled base image layers to avoid
    ///    re-downloading from registries
    ///
    /// TODO: Wire up cache lookups in the build loop once layer digests
    /// are properly computed and tracked.
    #[cfg(feature = "cache")]
    pub cache_backend_config: Option<CacheBackendConfig>,
    /// Default OCI/WASM-compatible registry to check for images before falling
    /// back to Docker Hub qualification.
    ///
    /// When set, the builder will probe this registry for short image names
    /// before qualifying them to `docker.io`. For example, if set to
    /// `"git.example.com:5000"` and the `ZImagefile` uses `base: "myapp:latest"`,
    /// the builder will check `git.example.com:5000/myapp:latest` first.
    pub default_registry: Option<String>,
    /// Default cache mounts injected into all RUN instructions.
    /// These are merged with any step-level cache mounts (deduped by target path).
    pub default_cache_mounts: Vec<RunMount>,
    /// Number of retries for failed RUN steps (0 = no retries, default)
    pub retries: u32,
    /// Target platform for the build (e.g., "linux/amd64", "linux/arm64").
    /// When set, `buildah from` pulls the platform-specific image variant.
    pub platform: Option<String>,
    /// Resolved target OS pin, mirrored from [`ImageBuilder::target_os`] right
    /// before the backend runs. `None` = darwin-native (the macOS Seatbelt
    /// sandbox provisions a Mac-native rootfs); `Some(Linux)`/`Some(Windows)` =
    /// an explicit cross-OS target. The macOS sandbox backend reads this to
    /// decide whether to provision a macOS-native toolchain for the base image
    /// — it must NOT do so for an explicit Linux target.
    pub target_os: Option<crate::backend::ImageOs>,
    /// Target platforms for a multi-arch build (e.g. `["linux/amd64",
    /// "linux/arm64"]`). When more than one is set, `build()` builds each
    /// sequentially and assembles a manifest list. A single entry is treated
    /// like `platform`. Empty = single-arch build governed by `platform`.
    pub platforms: Vec<String>,
    /// SHA-256 hash of the source Dockerfile/ZImagefile content.
    ///
    /// When set, the sandbox builder can skip a rebuild if the cached image
    /// was produced from identical source content (content-based invalidation).
    pub source_hash: Option<String>,
    /// How to handle base-image pulling during `buildah from`.
    ///
    /// Default: [`PullBaseMode::Newer`] — only pull if the registry has a
    /// newer version. Set to [`PullBaseMode::Always`] for CI builds that
    /// must always refresh, or [`PullBaseMode::Never`] for offline builds.
    pub pull: PullBaseMode,
    /// Windows LTSC line to target for FROM image rewrites
    /// (e.g. `"ltsc2022"`, `"ltsc2025"`).
    ///
    /// Only consumed by the Windows (HCS / WCOW) backend. When set, the
    /// builder rewrites generic Docker Hub references (`ubuntu:24.04`,
    /// `golang:1.24`, etc.) to the equivalent prebuilt Windows image via
    /// `windows_image_resolver::rewrite_image_for_windows`. `None` means
    /// the backend uses its built-in default (`ltsc2022`).
    pub windows_ltsc: Option<String>,
    /// Force `--net=host` on every `buildah run` for this build.
    ///
    /// When `true`, the buildah backend asks [`DockerfileTranslator`] to
    /// emit `--net=host` on every translated `RUN` instruction, overriding
    /// any per-instruction `network` value. This mirrors Docker's
    /// `docker build --network=host` flag and bypasses buildah's CNI /
    /// netavark plumbing entirely — the container shares the host's
    /// network namespace.
    ///
    /// Default: `false`. Wired up from the top-level `zlayer
    /// --host-network` CLI flag (see `bin/zlayer/src/cli.rs`).
    pub host_network: bool,
    /// Override the auto-detected build backend.
    ///
    /// `None` means "use `detect_backend()`'s default for the host × target
    /// combination" (current behavior). `Some(kind)` forces that backend; if it's
    /// unavailable for this host × target combination, the build fails with
    /// `BuildError::NotSupported { operation: ... }`.
    pub backend_override: Option<zlayer_types::builder::BuilderBackendKind>,
}

impl Default for BuildOptions {
    fn default() -> Self {
        Self {
            dockerfile: None,
            zimagefile: None,
            runtime: None,
            build_args: HashMap::new(),
            pipeline_vars: HashMap::new(),
            target: None,
            tags: Vec::new(),
            no_cache: false,
            push: false,
            registry_auth: None,
            squash: false,
            format: None,
            layers: true,
            cache_from: None,
            cache_to: None,
            cache_ttl: None,
            #[cfg(feature = "cache")]
            cache_backend_config: None,
            default_registry: None,
            default_cache_mounts: Vec::new(),
            retries: 0,
            platform: None,
            target_os: None,
            platforms: Vec::new(),
            source_hash: None,
            pull: PullBaseMode::default(),
            windows_ltsc: None,
            host_network: false,
            backend_override: None,
        }
    }
}

/// Expand `${VAR}` references in a `ZImagefile` body using pipeline variables.
///
/// Mirrors `pipeline::executor::expand_tag_with_vars`: each `${key}` is replaced
/// with its value; unknown references are left intact. Returns `content`
/// unchanged when `vars` is empty (the common direct-build case), so this is a
/// no-op for every non-pipeline caller.
fn expand_zimage_vars(content: &str, vars: &std::collections::HashMap<String, String>) -> String {
    if vars.is_empty() {
        return content.to_string();
    }
    let mut result = content.to_string();
    for (key, value) in vars {
        result = result.replace(&format!("${{{key}}}"), value);
    }
    result
}

/// Map a platform string to the arch suffix used for per-arch member tags
/// (`linux/amd64` → `amd64`, `linux/arm64/v8` → `arm64-v8`).
fn platform_to_suffix(platform: &str) -> String {
    let parts: Vec<&str> = platform.split('/').collect();
    match parts.len() {
        0 | 1 => platform.replace('/', "-"),
        2 => parts[1].to_string(),
        _ => format!("{}-{}", parts[1], parts[2]),
    }
}

/// Verify the host can execute the target architecture: on Linux, a non-native
/// arch needs a `binfmt_misc` qemu handler. Returns
/// [`BuildError::BinfmtNotRegistered`] when it's missing so the caller gets a
/// clear, actionable error instead of an opaque buildah `exec format error`.
///
/// The `Result` is meaningful only on Linux (where the binfmt handler can be
/// missing); on every other target the body is an infallible `Ok(())`, so the
/// `unnecessary_wraps` lint is allowed off-Linux while the signature stays
/// uniform across platforms for the callers.
#[cfg_attr(not(target_os = "linux"), allow(clippy::unnecessary_wraps))]
fn verify_binfmt_for_platform(platform: &str) -> Result<()> {
    #[cfg(target_os = "linux")]
    {
        // arch segment is the 2nd '/'-separated field (`os/arch[/variant]`).
        let arch = platform.split('/').nth(1).unwrap_or(platform);
        let native = std::env::consts::ARCH; // e.g. "x86_64", "aarch64"
        let native_matches = matches!(
            (native, arch),
            ("x86_64", "amd64" | "386")
                | ("aarch64", "arm64" | "arm64/v8")
                | ("arm", "arm")
                | ("powerpc64", "ppc64le")
                | ("s390x", "s390x")
                | ("riscv64", "riscv64")
        );
        if native_matches {
            return Ok(());
        }
        // Map docker arch -> qemu-user-static binfmt handler name.
        let qemu_arch = match arch {
            "amd64" => "x86_64",
            "386" => "i386",
            "arm64" | "arm64/v8" => "aarch64",
            "arm" => "arm",
            "ppc64le" => "ppc64le",
            "s390x" => "s390x",
            "riscv64" => "riscv64",
            other => other,
        };
        let handler = format!("/proc/sys/fs/binfmt_misc/qemu-{qemu_arch}");
        if !std::path::Path::new(&handler).exists() {
            return Err(BuildError::BinfmtNotRegistered {
                platform: platform.to_string(),
                qemu_arch: qemu_arch.to_string(),
            });
        }
        Ok(())
    }
    #[cfg(not(target_os = "linux"))]
    {
        let _ = platform;
        Ok(())
    }
}

/// Discover a `ZImagefile` in the build context directory.
///
/// Resolution order matches user intuition:
///
/// 1. **Literal `ZImagefile`** in the context root — by far the most common
///    layout (e.g. a one-image repo whose build file is just `ZImagefile`).
/// 2. **Any `ZImagefile.<suffix>`** glob — the convention this repo itself
///    uses (`ZImagefile.zlayer-node`, `ZImagefile.zlayer-manager`, …). If
///    exactly one match exists, use it.
/// 3. **Zero matches** → return `Ok(None)` so the caller falls through to the
///    Dockerfile path.
/// 4. **Multiple `ZImagefile.<suffix>` matches and no literal `ZImagefile`**
///    → ambiguous; return an error telling the user to pick one with
///    `-z <path>`. We don't silently pick "the first one" because that's a
///    correctness landmine — a repo with `ZImagefile.prod` and
///    `ZImagefile.dev` would otherwise build whichever entry the filesystem
///    listed first.
///
/// The lookup is sync (a single `read_dir`) and doesn't follow symlinks
/// beyond the standard `DirEntry::file_type()` semantics. Errors reading the
/// directory propagate so the caller can attach a `BuildError::ContextRead`.
///
/// # Errors
///
/// Propagates the `read_dir` error when the context directory exists but
/// cannot be read (a missing directory yields `Ok(None)`, not an error).
pub fn find_context_zimagefile(context: &Path) -> std::io::Result<Option<PathBuf>> {
    // (1) Literal `ZImagefile` wins outright.
    let literal = context.join("ZImagefile");
    if literal.exists() {
        return Ok(Some(literal));
    }

    // (2) Scan for `ZImagefile.<suffix>` entries. We treat any non-empty
    // suffix as a candidate; the suffix is opaque to the builder (it's just
    // a disambiguator, like `Dockerfile.prod`).
    let mut matches: Vec<PathBuf> = Vec::new();
    let entries = match std::fs::read_dir(context) {
        Ok(e) => e,
        // Context dir doesn't exist / not readable: caller will surface a
        // proper error elsewhere. Returning Ok(None) keeps this helper
        // narrow.
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(e) => return Err(e),
    };
    for entry in entries.flatten() {
        let name = entry.file_name();
        let Some(name_str) = name.to_str() else {
            continue;
        };
        if let Some(rest) = name_str.strip_prefix("ZImagefile.") {
            if !rest.is_empty() {
                matches.push(entry.path());
            }
        }
    }

    match matches.len() {
        0 => Ok(None),
        1 => Ok(matches.pop()),
        _ => {
            matches.sort();
            let names: Vec<String> = matches
                .iter()
                .map(|p| {
                    p.file_name()
                        .and_then(|n| n.to_str())
                        .unwrap_or("?")
                        .to_string()
                })
                .collect();
            Err(std::io::Error::new(
                std::io::ErrorKind::InvalidInput,
                format!(
                    "multiple ZImagefile candidates in {}: {} — pass `-z <path>` to pick one",
                    context.display(),
                    names.join(", "),
                ),
            ))
        }
    }
}

/// Image builder - orchestrates the full build process
///
/// `ImageBuilder` provides a fluent API for configuring and executing
/// container image builds using buildah as the backend.
///
/// # Build Process
///
/// 1. Parse Dockerfile (or use runtime template)
/// 2. Resolve target stages if specified
/// 3. Build each stage sequentially:
///    - Create working container from base image
///    - Execute each instruction
///    - Commit intermediate stages for COPY --from
/// 4. Commit final image with tags
/// 5. Push to registry if configured
/// 6. Clean up intermediate containers
///
/// # Cache Backend Integration (requires `cache` feature)
///
/// When a cache backend is configured, the builder can store and retrieve
/// cached layer data to speed up subsequent builds:
///
/// ```no_run,ignore
/// use zlayer_builder::ImageBuilder;
///
/// let builder = ImageBuilder::new("./my-app").await?
///     .with_cache_dir("/var/cache/zlayer")
///     .tag("myapp:latest");
/// ```
pub struct ImageBuilder {
    /// Build context directory
    context: PathBuf,
    /// Build options
    options: BuildOptions,
    /// Buildah executor (kept for backwards compatibility)
    #[allow(dead_code)]
    executor: BuildahExecutor,
    /// Event sender for TUI updates
    event_tx: Option<mpsc::Sender<BuildEvent>>,
    /// Explicit target OS for this build.
    ///
    /// When `Some`, the backend was (or will be) detected for this OS and
    /// it overrides any OS inferred from the `ZImagefile` (`os:` / `platform:`)
    /// during `build()`. When `None`, the builder uses the OS inferred from
    /// the parsed `ZImage` via `ZImage::resolve_target_os()`, falling back to
    /// [`ImageOs::Linux`] when the `ZImagefile` has no OS hint either.
    target_os: Option<crate::backend::ImageOs>,
    /// Pluggable build backend (buildah, sandbox, etc.).
    ///
    /// When set, the `build()` method delegates to this backend instead of
    /// using the inline buildah logic. Set automatically by `new()` via
    /// `detect_backend()`, or explicitly via `with_backend()`.
    backend: Option<Arc<dyn BuildBackend>>,
    /// Cache backend for layer caching (requires `cache` feature).
    ///
    /// When set, the builder will attempt to retrieve cached layers before
    /// executing instructions, and store results in the cache after execution.
    ///
    /// TODO: Implement cache lookups in the build loop. Currently the backend
    /// is stored but not actively used during builds. Integration points:
    /// - Check cache before executing RUN instructions
    /// - Store layer data after successful instruction execution
    /// - Cache base image layers pulled from registries
    #[cfg(feature = "cache")]
    cache_backend: Option<Arc<Box<dyn BlobCacheBackend>>>,
    /// Local OCI registry for checking cached images before remote pulls.
    ///
    /// Stored as an `Arc` so the daemon's per-container Docker-compat socket
    /// build path can hand in the SAME already-open `LocalRegistry` the daemon
    /// serves from (via [`Self::with_local_registry_arc`]) rather than opening a
    /// second on-disk handle — the blob cache it pairs with is single-process
    /// exclusive, so a second open would deadlock.
    #[cfg(feature = "local-registry")]
    local_registry: Option<Arc<LocalRegistry>>,
}

impl ImageBuilder {
    /// Create a new `ImageBuilder` with the given context directory
    ///
    /// The context directory should contain the Dockerfile (unless using
    /// a runtime template) and any files that will be copied into the image.
    ///
    /// # Arguments
    ///
    /// * `context` - Path to the build context directory
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The context directory does not exist
    /// - Buildah is not installed or not accessible
    ///
    /// # Example
    ///
    /// ```no_run
    /// use zlayer_builder::ImageBuilder;
    ///
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?;
    /// # Ok(())
    /// # }
    /// ```
    #[instrument(skip_all, fields(context = %context.as_ref().display()))]
    pub async fn new(context: impl AsRef<Path>) -> Result<Self> {
        Self::new_with_os(context, None).await
    }

    /// Create a new `ImageBuilder` with an explicit target OS.
    ///
    /// This is equivalent to [`ImageBuilder::new`] followed by
    /// [`ImageBuilder::with_target_os`], but avoids the extra round-trip of
    /// detecting a Linux backend first and throwing it away.
    ///
    /// Pass `None` to defer target-OS resolution to `build()` time, where
    /// the effective OS is resolved from the `ZImagefile`'s `os:` or `platform:`
    /// field (priority documented on [`crate::zimage::ZImage::resolve_target_os`]).
    ///
    /// # Errors
    ///
    /// Returns an error if the context directory does not exist, or (on
    /// Linux/Windows) if the buildah executor cannot be initialized.
    #[instrument(skip_all, fields(context = %context.as_ref().display(), target_os = ?target_os))]
    pub async fn new_with_os(
        context: impl AsRef<Path>,
        target_os: Option<crate::backend::ImageOs>,
    ) -> Result<Self> {
        let context = context.as_ref().to_path_buf();

        // Verify context exists
        if !context.exists() {
            return Err(BuildError::ContextRead {
                path: context,
                source: std::io::Error::new(
                    std::io::ErrorKind::NotFound,
                    "Build context directory not found",
                ),
            });
        }

        // Detect the best available build backend for this platform. When
        // `target_os` is None (caller hasn't decided yet), probe for the Linux
        // backend as the common case; `build()` will re-detect if the parsed
        // ZImagefile reveals a different target OS.
        let detection_os = target_os.unwrap_or(crate::backend::ImageOs::Linux);
        let backend = crate::backend::detect_backend(detection_os).await.ok();

        // Initialize buildah executor.
        // On macOS, if buildah is not found we fall back to a default executor
        // (the backend will handle the actual build dispatch).
        let executor = match BuildahExecutor::new_async().await {
            Ok(exec) => exec,
            #[cfg(target_os = "macos")]
            Err(_) => {
                info!("Buildah not found on macOS; backend will handle build dispatch");
                BuildahExecutor::default()
            }
            // Windows has no native buildah. A Windows-image build dispatches to
            // the native HCS backend (`detect_backend(Windows)` above) and a
            // Linux-image build dispatches to the WSL2 backend — neither uses
            // this host `BuildahExecutor` for the build itself (the WSL2 backend
            // builds its own WSL-transport executor in `Wsl2BuildBackend::new`,
            // and the HCS backend drives `WindowsBuilder`). The host executor is
            // only ever touched by the local-registry OCI-export fallback in
            // `build()`, which the HCS path must satisfy natively. So fall back
            // to a default executor here rather than failing construction —
            // mirrors the macOS sandbox path — and let `build()` re-detect /
            // surface a precise backend error (e.g. "WSL2 distro not found")
            // instead of a misleading "buildah not found" at construction time.
            #[cfg(target_os = "windows")]
            Err(_) => {
                info!(
                    "Buildah not available natively on Windows; backend (HCS/WSL2) \
                     will handle build dispatch"
                );
                BuildahExecutor::default()
            }
            #[cfg(all(not(target_os = "macos"), not(target_os = "windows")))]
            Err(e) => return Err(e),
        };

        debug!("Created ImageBuilder for context: {}", context.display());

        Ok(Self {
            context,
            options: BuildOptions::default(),
            executor,
            event_tx: None,
            target_os,
            backend,
            #[cfg(feature = "cache")]
            cache_backend: None,
            #[cfg(feature = "local-registry")]
            local_registry: None,
        })
    }

    /// Override the target OS after construction, re-detecting the backend.
    ///
    /// Use this when the caller only learns the target OS *after* creating
    /// the builder — for example, after parsing a `ZImagefile` to inspect its
    /// `os:`/`platform:` fields. Passing the same OS that was already selected
    /// at construction time is cheap (it still re-runs `detect_backend()`).
    ///
    /// # Errors
    ///
    /// Returns an error if `detect_backend(target_os)` fails for the current
    /// host/target combination (e.g. Windows image requested on a Linux host).
    pub async fn with_target_os(mut self, target_os: crate::backend::ImageOs) -> Result<Self> {
        self.target_os = Some(target_os);
        self.backend = Some(
            crate::backend::detect_backend_with_options(target_os, Some(&self.options)).await?,
        );
        Ok(self)
    }

    /// Create an `ImageBuilder` with a custom buildah executor
    ///
    /// This is useful for testing or when you need to configure
    /// the executor with specific storage options. The executor is
    /// wrapped in a [`BuildahBackend`] so the build dispatches through
    /// the [`BuildBackend`] trait.
    ///
    /// # Errors
    ///
    /// Returns an error if the context directory does not exist.
    pub fn with_executor(context: impl AsRef<Path>, executor: BuildahExecutor) -> Result<Self> {
        let context = context.as_ref().to_path_buf();

        if !context.exists() {
            return Err(BuildError::ContextRead {
                path: context,
                source: std::io::Error::new(
                    std::io::ErrorKind::NotFound,
                    "Build context directory not found",
                ),
            });
        }

        let backend: Arc<dyn BuildBackend> = Arc::new(
            crate::backend::BuildahBackend::with_executor(executor.clone()),
        );

        Ok(Self {
            context,
            options: BuildOptions::default(),
            executor,
            event_tx: None,
            target_os: None,
            backend: Some(backend),
            #[cfg(feature = "cache")]
            cache_backend: None,
            #[cfg(feature = "local-registry")]
            local_registry: None,
        })
    }

    /// Create an `ImageBuilder` with an explicit [`BuildBackend`].
    ///
    /// The backend is used for all build, push, tag, and manifest
    /// operations. The internal `BuildahExecutor` is set to the default
    /// (it is only used if no backend is set).
    ///
    /// # Errors
    ///
    /// Returns an error if the context directory does not exist.
    pub fn with_backend(context: impl AsRef<Path>, backend: Arc<dyn BuildBackend>) -> Result<Self> {
        let context = context.as_ref().to_path_buf();

        if !context.exists() {
            return Err(BuildError::ContextRead {
                path: context,
                source: std::io::Error::new(
                    std::io::ErrorKind::NotFound,
                    "Build context directory not found",
                ),
            });
        }

        Ok(Self {
            context,
            options: BuildOptions::default(),
            executor: BuildahExecutor::default(),
            event_tx: None,
            target_os: None,
            backend: Some(backend),
            #[cfg(feature = "cache")]
            cache_backend: None,
            #[cfg(feature = "local-registry")]
            local_registry: None,
        })
    }

    /// Set a custom Dockerfile path
    ///
    /// By default, the builder looks for a file named `Dockerfile` in the
    /// context directory. Use this method to specify a different path.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use zlayer_builder::ImageBuilder;
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .dockerfile("./my-project/Dockerfile.prod");
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn dockerfile(mut self, path: impl AsRef<Path>) -> Self {
        self.options.dockerfile = Some(path.as_ref().to_path_buf());
        self
    }

    /// Set a custom `ZImagefile` path
    ///
    /// `ZImagefiles` are a YAML-based alternative to Dockerfiles. When set,
    /// the builder will parse the `ZImagefile` and convert it to the internal
    /// Dockerfile IR for execution.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use zlayer_builder::ImageBuilder;
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .zimagefile("./my-project/ZImagefile");
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn zimagefile(mut self, path: impl AsRef<Path>) -> Self {
        self.options.zimagefile = Some(path.as_ref().to_path_buf());
        self
    }

    /// Use a runtime template instead of a Dockerfile
    ///
    /// Runtime templates provide pre-built Dockerfiles for common
    /// development environments. When set, the Dockerfile option is ignored.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use zlayer_builder::{ImageBuilder, Runtime};
    ///
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-node-app").await?
    ///     .runtime(Runtime::Node20);
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn runtime(mut self, runtime: Runtime) -> Self {
        self.options.runtime = Some(runtime);
        self
    }

    /// Add a build argument
    ///
    /// Build arguments are passed to the Dockerfile and can be referenced
    /// using the `ARG` instruction.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use zlayer_builder::ImageBuilder;
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .build_arg("VERSION", "1.0.0")
    ///     .build_arg("DEBUG", "false");
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn build_arg(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.options.build_args.insert(key.into(), value.into());
        self
    }

    /// Set multiple build arguments at once
    #[must_use]
    pub fn build_args(mut self, args: HashMap<String, String>) -> Self {
        self.options.build_args.extend(args);
        self
    }

    /// Set pipeline variables expanded into the `ZImagefile` body before parse.
    ///
    /// `${VAR}` / `$VAR` references in a `ZImagefile`'s `base:`/`run:`/etc. are
    /// replaced with the matching value; unknown references are left untouched.
    /// Only `ZImagefile` bodies are expanded — Dockerfiles keep their native
    /// `${ARG}` semantics. Used by the pipeline executor to drive one
    /// `ZImagefile` set across variants (e.g. Windows `--set LTSC=ltsc2025`).
    #[must_use]
    pub fn pipeline_vars(mut self, vars: HashMap<String, String>) -> Self {
        self.options.pipeline_vars.extend(vars);
        self
    }

    /// Set the Windows LTSC line to target for FROM image rewrites
    /// (e.g. `"ltsc2022"`, `"ltsc2025"`).
    ///
    /// Only consumed by the Windows (HCS / WCOW) backend. The pipeline
    /// executor wires this from the `LTSC` pipeline variable, so a
    /// `zlayer pipeline --set LTSC=ltsc2025` invocation flows down to the
    /// FROM rewriter in `windows_builder::start_build`. Has no effect on
    /// Linux / macOS backends.
    #[must_use]
    pub fn windows_ltsc(mut self, ltsc: impl Into<String>) -> Self {
        self.options.windows_ltsc = Some(ltsc.into());
        self
    }

    /// Set the target stage for multi-stage builds
    ///
    /// When building a multi-stage Dockerfile, you can stop at a specific
    /// stage instead of building all stages.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use zlayer_builder::ImageBuilder;
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// // Dockerfile:
    /// // FROM node:20 AS builder
    /// // ...
    /// // FROM node:20-slim AS runtime
    /// // ...
    ///
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .target("builder")
    ///     .tag("myapp:builder");
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn target(mut self, stage: impl Into<String>) -> Self {
        self.options.target = Some(stage.into());
        self
    }

    /// Add an image tag
    ///
    /// Tags are applied to the final image. You can add multiple tags.
    /// The first tag is used as the primary image name during commit.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use zlayer_builder::ImageBuilder;
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .tag("myapp:latest")
    ///     .tag("myapp:v1.0.0")
    ///     .tag("registry.example.com/myapp:v1.0.0");
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn tag(mut self, tag: impl Into<String>) -> Self {
        self.options.tags.push(tag.into());
        self
    }

    /// Disable layer caching
    ///
    /// When enabled, all layers are rebuilt from scratch even if
    /// they could be served from cache.
    ///
    /// Note: Currently this flag is tracked but not fully implemented in the
    /// build process. `ZLayer` uses manual container creation (`buildah from`,
    /// `buildah run`, `buildah commit`) which doesn't have built-in caching
    /// like `buildah build` does. Future work could implement layer-level
    /// caching by checking instruction hashes against previously built layers.
    #[must_use]
    pub fn no_cache(mut self) -> Self {
        self.options.no_cache = true;
        self
    }

    /// Set the base-image pull strategy for the build.
    ///
    /// By default, `buildah from` is invoked with `--pull=newer`, so an
    /// up-to-date local base image is reused but a newer one on the
    /// registry will be fetched. Pass [`PullBaseMode::Always`] to force a
    /// fresh pull on every build, or [`PullBaseMode::Never`] to stay fully
    /// offline.
    #[must_use]
    pub fn pull(mut self, mode: PullBaseMode) -> Self {
        self.options.pull = mode;
        self
    }

    /// Force `--net=host` on every `buildah run` emitted by this build.
    ///
    /// Mirrors Docker's `docker build --network=host` flag. When `on` is
    /// `true`, every translated `RUN` instruction is annotated with
    /// `RunNetwork::Host` regardless of any per-instruction `--network`
    /// directive, and the buildah backend emits `--net=host` on the
    /// resulting `buildah run` invocation. This bypasses buildah's CNI /
    /// netavark plumbing entirely (the container shares the host's
    /// network namespace).
    ///
    /// Wired from the top-level `zlayer --host-network` CLI flag.
    #[must_use]
    pub fn with_host_network(mut self, on: bool) -> Self {
        self.options.host_network = on;
        self
    }

    /// Override the auto-detected build backend.
    ///
    /// `None` (the default) leaves backend selection to `detect_backend()`.
    /// `Some(kind)` forces that backend; if it is unavailable for the host ×
    /// target combination, the eventual build will fail with
    /// `BuildError::NotSupported`. Wired from the `zlayer build --backend`
    /// CLI flag.
    #[must_use]
    pub fn with_backend_override(
        mut self,
        backend: Option<zlayer_types::builder::BuilderBackendKind>,
    ) -> Self {
        self.options.backend_override = backend;
        self
    }

    /// Enable or disable layer caching
    ///
    /// This controls the `--layers` flag for buildah. When enabled (default),
    /// buildah can cache and reuse intermediate layers.
    ///
    /// Note: `ZLayer` currently uses manual container creation (`buildah from`,
    /// `buildah run`, `buildah commit`) rather than `buildah build`, so this
    /// flag is reserved for future use when/if we switch to `buildah build`.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use zlayer_builder::ImageBuilder;
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .layers(false)  // Disable layer caching
    ///     .tag("myapp:latest");
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn layers(mut self, enable: bool) -> Self {
        self.options.layers = enable;
        self
    }

    /// Set registry to pull cache from
    ///
    /// This corresponds to buildah's `--cache-from` flag, which allows
    /// pulling cached layers from a remote registry to speed up builds.
    ///
    /// Note: `ZLayer` currently uses manual container creation (`buildah from`,
    /// `buildah run`, `buildah commit`) rather than `buildah build`, so this
    /// option is reserved for future implementation.
    ///
    /// TODO: Implement remote cache support. This would require either:
    /// 1. Switching to `buildah build` command which supports --cache-from natively
    /// 2. Implementing custom layer caching with registry pull for intermediate layers
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use zlayer_builder::ImageBuilder;
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .cache_from("registry.example.com/myapp:cache")
    ///     .tag("myapp:latest");
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn cache_from(mut self, registry: impl Into<String>) -> Self {
        self.options.cache_from = Some(registry.into());
        self
    }

    /// Set registry to push cache to
    ///
    /// This corresponds to buildah's `--cache-to` flag, which allows
    /// pushing cached layers to a remote registry for future builds to use.
    ///
    /// Note: `ZLayer` currently uses manual container creation (`buildah from`,
    /// `buildah run`, `buildah commit`) rather than `buildah build`, so this
    /// option is reserved for future implementation.
    ///
    /// TODO: Implement remote cache support. This would require either:
    /// 1. Switching to `buildah build` command which supports --cache-to natively
    /// 2. Implementing custom layer caching with registry push for intermediate layers
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use zlayer_builder::ImageBuilder;
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .cache_to("registry.example.com/myapp:cache")
    ///     .tag("myapp:latest");
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn cache_to(mut self, registry: impl Into<String>) -> Self {
        self.options.cache_to = Some(registry.into());
        self
    }

    /// Set maximum cache age
    ///
    /// This corresponds to buildah's `--cache-ttl` flag, which sets the
    /// maximum age for cached layers before they are considered stale.
    ///
    /// Note: `ZLayer` currently uses manual container creation (`buildah from`,
    /// `buildah run`, `buildah commit`) rather than `buildah build`, so this
    /// option is reserved for future implementation.
    ///
    /// TODO: Implement cache TTL support. This would require either:
    /// 1. Switching to `buildah build` command which supports --cache-ttl natively
    /// 2. Implementing custom cache expiration logic for our layer caching system
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use zlayer_builder::ImageBuilder;
    /// # use std::time::Duration;
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .cache_ttl(Duration::from_secs(3600 * 24))  // 24 hours
    ///     .tag("myapp:latest");
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn cache_ttl(mut self, ttl: std::time::Duration) -> Self {
        self.options.cache_ttl = Some(ttl);
        self
    }

    /// Push the image to a registry after building
    ///
    /// # Arguments
    ///
    /// * `auth` - Registry authentication credentials
    ///
    /// # Example
    ///
    /// ```no_run
    /// use zlayer_builder::{ImageBuilder, RegistryAuth};
    ///
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .tag("registry.example.com/myapp:v1.0.0")
    ///     .push(RegistryAuth::new("user", "password"));
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn push(mut self, auth: RegistryAuth) -> Self {
        self.options.push = true;
        self.options.registry_auth = Some(auth);
        self
    }

    /// Enable pushing without authentication
    ///
    /// Use this for registries that don't require authentication
    /// (e.g., local registries, insecure registries).
    #[must_use]
    pub fn push_without_auth(mut self) -> Self {
        self.options.push = true;
        self.options.registry_auth = None;
        self
    }

    /// Set a default OCI/WASM-compatible registry to check for images.
    ///
    /// When set, the builder will probe this registry for short image names
    /// before qualifying them to `docker.io`. For example, if set to
    /// `"git.example.com:5000"` and the `ZImagefile` uses `base: "myapp:latest"`,
    /// the builder will check `git.example.com:5000/myapp:latest` first.
    #[must_use]
    pub fn default_registry(mut self, registry: impl Into<String>) -> Self {
        self.options.default_registry = Some(registry.into());
        self
    }

    /// Set a local OCI registry for image resolution.
    ///
    /// When set, the builder checks the local registry for cached images
    /// before pulling from remote registries.
    #[cfg(feature = "local-registry")]
    #[must_use]
    pub fn with_local_registry(mut self, registry: LocalRegistry) -> Self {
        self.local_registry = Some(Arc::new(registry));
        self
    }

    /// Set a local OCI registry from an already-shared `Arc` handle.
    ///
    /// Like [`Self::with_local_registry`], but takes the registry by `Arc` so a
    /// caller that already holds the daemon's open `LocalRegistry` (the
    /// per-container Docker-compat socket build path) can wire in the EXACT same
    /// store the daemon serves from. Pair with [`Self::with_cache_backend`] using
    /// the daemon's shared blob-cache `Arc` so built images import into the live
    /// store without opening a second (single-process-exclusive) handle.
    #[cfg(feature = "local-registry")]
    #[must_use]
    pub fn with_local_registry_arc(mut self, registry: Arc<LocalRegistry>) -> Self {
        self.local_registry = Some(registry);
        self
    }

    /// Squash all layers into a single layer
    ///
    /// This reduces image size but loses layer caching benefits.
    #[must_use]
    pub fn squash(mut self) -> Self {
        self.options.squash = true;
        self
    }

    /// Set the image format
    ///
    /// Valid values are "oci" (default) or "docker".
    #[must_use]
    pub fn format(mut self, format: impl Into<String>) -> Self {
        self.options.format = Some(format.into());
        self
    }

    /// Set default cache mounts to inject into all RUN instructions
    #[must_use]
    pub fn default_cache_mounts(mut self, mounts: Vec<RunMount>) -> Self {
        self.options.default_cache_mounts = mounts;
        self
    }

    /// Set the number of retries for failed RUN steps
    #[must_use]
    pub fn retries(mut self, retries: u32) -> Self {
        self.options.retries = retries;
        self
    }

    /// Set the target platform for cross-architecture builds.
    #[must_use]
    pub fn platform(mut self, platform: impl Into<String>) -> Self {
        self.options.platform = Some(platform.into());
        self
    }

    /// Set multiple target platforms for a multi-arch manifest-list build.
    /// Accepts a comma-separated string (`"linux/amd64,linux/arm64"`) or
    /// individual values via repeated calls; empty/whitespace entries are
    /// dropped. More than one distinct platform triggers the manifest-list
    /// path in [`build`](Self::build).
    #[must_use]
    pub fn platforms<I, S>(mut self, platforms: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        for p in platforms {
            let p = p.into();
            for part in p.split(',') {
                let part = part.trim();
                if !part.is_empty() {
                    self.options.platforms.push(part.to_string());
                }
            }
        }
        self
    }

    /// Set a pre-computed source hash for content-based cache invalidation.
    ///
    /// When set, the sandbox builder can skip a full rebuild if the cached
    /// image was produced from identical source content.
    #[must_use]
    pub fn source_hash(mut self, hash: impl Into<String>) -> Self {
        self.options.source_hash = Some(hash.into());
        self
    }

    /// Set an event sender for TUI progress updates
    ///
    /// Events will be sent as the build progresses, allowing you to
    /// display a progress UI or log build status.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use zlayer_builder::{ImageBuilder, BuildEvent};
    /// use std::sync::mpsc;
    ///
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let (tx, rx) = mpsc::channel::<BuildEvent>();
    ///
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .tag("myapp:latest")
    ///     .with_events(tx);
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn with_events(mut self, tx: mpsc::Sender<BuildEvent>) -> Self {
        self.event_tx = Some(tx);
        self
    }

    /// Configure a persistent disk cache backend for layer caching.
    ///
    /// When configured, the builder will store layer data on disk at the
    /// specified path. This cache persists across builds and significantly
    /// speeds up repeated builds of similar images.
    ///
    /// Requires the `cache-persistent` feature to be enabled.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to the cache directory. If a directory, creates
    ///   `blob_cache.redb` inside it. If a file path, uses it directly.
    ///
    /// # Example
    ///
    /// ```no_run,ignore
    /// use zlayer_builder::ImageBuilder;
    ///
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .with_cache_dir("/var/cache/zlayer")
    ///     .tag("myapp:latest");
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Integration Status
    ///
    /// TODO: The cache backend is currently stored but not actively used
    /// during builds. Future work will wire up:
    /// - Cache lookups before executing RUN instructions
    /// - Storing layer data after successful execution
    /// - Caching base image layers from registry pulls
    #[cfg(feature = "cache-persistent")]
    #[must_use]
    pub fn with_cache_dir(mut self, path: impl AsRef<Path>) -> Self {
        self.options.cache_backend_config = Some(CacheBackendConfig::Persistent {
            path: path.as_ref().to_path_buf(),
        });
        debug!(
            "Configured persistent cache at: {}",
            path.as_ref().display()
        );
        self
    }

    /// Configure an in-memory cache backend for layer caching.
    ///
    /// The in-memory cache is cleared when the process exits, but can
    /// speed up builds within a single session by caching intermediate
    /// layers and avoiding redundant operations.
    ///
    /// Requires the `cache` feature to be enabled.
    ///
    /// # Example
    ///
    /// ```no_run,ignore
    /// use zlayer_builder::ImageBuilder;
    ///
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .with_memory_cache()
    ///     .tag("myapp:latest");
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Integration Status
    ///
    /// TODO: The cache backend is currently stored but not actively used
    /// during builds. See `with_cache_dir` for integration status details.
    #[cfg(feature = "cache")]
    #[must_use]
    pub fn with_memory_cache(mut self) -> Self {
        self.options.cache_backend_config = Some(CacheBackendConfig::Memory);
        debug!("Configured in-memory cache");
        self
    }

    /// Configure an S3-compatible storage backend for layer caching.
    ///
    /// This is useful for distributed build systems where multiple build
    /// machines need to share a layer cache. Supports AWS S3, Cloudflare R2,
    /// Backblaze B2, `MinIO`, and other S3-compatible services.
    ///
    /// Requires the `cache-s3` feature to be enabled.
    ///
    /// # Arguments
    ///
    /// * `bucket` - S3 bucket name
    /// * `region` - AWS region (optional, uses SDK default if not set)
    ///
    /// # Example
    ///
    /// ```no_run,ignore
    /// use zlayer_builder::ImageBuilder;
    ///
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .with_s3_cache("my-build-cache", Some("us-west-2"))
    ///     .tag("myapp:latest");
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Integration Status
    ///
    /// TODO: The cache backend is currently stored but not actively used
    /// during builds. See `with_cache_dir` for integration status details.
    #[cfg(feature = "cache-s3")]
    #[must_use]
    pub fn with_s3_cache(mut self, bucket: impl Into<String>, region: Option<String>) -> Self {
        self.options.cache_backend_config = Some(CacheBackendConfig::S3 {
            bucket: bucket.into(),
            region,
            endpoint: None,
            prefix: None,
        });
        debug!("Configured S3 cache");
        self
    }

    /// Configure an S3-compatible storage backend with custom endpoint.
    ///
    /// Use this method for S3-compatible services that require a custom
    /// endpoint URL (e.g., Cloudflare R2, `MinIO`, local development).
    ///
    /// Requires the `cache-s3` feature to be enabled.
    ///
    /// # Arguments
    ///
    /// * `bucket` - S3 bucket name
    /// * `endpoint` - Custom endpoint URL
    /// * `region` - Region (required for some S3-compatible services)
    ///
    /// # Example
    ///
    /// ```no_run,ignore
    /// use zlayer_builder::ImageBuilder;
    ///
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// // Cloudflare R2
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .with_s3_cache_endpoint(
    ///         "my-bucket",
    ///         "https://accountid.r2.cloudflarestorage.com",
    ///         Some("auto".to_string()),
    ///     )
    ///     .tag("myapp:latest");
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(feature = "cache-s3")]
    #[must_use]
    pub fn with_s3_cache_endpoint(
        mut self,
        bucket: impl Into<String>,
        endpoint: impl Into<String>,
        region: Option<String>,
    ) -> Self {
        self.options.cache_backend_config = Some(CacheBackendConfig::S3 {
            bucket: bucket.into(),
            region,
            endpoint: Some(endpoint.into()),
            prefix: None,
        });
        debug!("Configured S3 cache with custom endpoint");
        self
    }

    /// Configure a custom cache backend configuration.
    ///
    /// This is the most flexible way to configure the cache backend,
    /// allowing full control over all cache settings.
    ///
    /// Requires the `cache` feature to be enabled.
    ///
    /// # Example
    ///
    /// ```no_run,ignore
    /// use zlayer_builder::{ImageBuilder, CacheBackendConfig};
    ///
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .with_cache_config(CacheBackendConfig::Memory)
    ///     .tag("myapp:latest");
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(feature = "cache")]
    #[must_use]
    pub fn with_cache_config(mut self, config: CacheBackendConfig) -> Self {
        self.options.cache_backend_config = Some(config);
        debug!("Configured custom cache backend");
        self
    }

    /// Set an already-initialized cache backend directly.
    ///
    /// This is useful when you have a pre-configured cache backend instance
    /// that you want to share across multiple builders or when you need
    /// fine-grained control over cache initialization.
    ///
    /// Requires the `cache` feature to be enabled.
    ///
    /// # Example
    ///
    /// ```no_run,ignore
    /// use zlayer_builder::ImageBuilder;
    /// use zlayer_registry::cache::BlobCache;
    /// use std::sync::Arc;
    ///
    /// # async fn example() -> Result<(), zlayer_builder::BuildError> {
    /// let cache = Arc::new(Box::new(BlobCache::new()?) as Box<dyn zlayer_registry::cache::BlobCacheBackend>);
    ///
    /// let builder = ImageBuilder::new("./my-project").await?
    ///     .with_cache_backend(cache)
    ///     .tag("myapp:latest");
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(feature = "cache")]
    #[must_use]
    pub fn with_cache_backend(mut self, backend: Arc<Box<dyn BlobCacheBackend>>) -> Self {
        self.cache_backend = Some(backend);
        debug!("Configured pre-initialized cache backend");
        self
    }

    /// Build each requested platform sequentially (cross-arch can be flaky in
    /// parallel) and assemble a buildah manifest list referencing all of them.
    /// When `options.push` is set, push the manifest list to the registry.
    async fn build_manifest_list(
        &self,
        dockerfile: &crate::dockerfile::Dockerfile,
        start_time: std::time::Instant,
    ) -> Result<BuiltImage> {
        let backend = self
            .backend
            .as_ref()
            .ok_or_else(|| BuildError::BuildahNotFound {
                message: "No build backend configured".into(),
            })?;

        let real_tags = self.options.tags.clone();
        let manifest_name =
            real_tags
                .first()
                .cloned()
                .ok_or_else(|| BuildError::InvalidInstruction {
                    instruction: "--platform".into(),
                    reason: "multi-arch build requires at least one tag (-t)".into(),
                })?;

        let mut arch_tags: Vec<String> = Vec::new();
        let mut total_layers = 0usize;
        let mut total_size = 0u64;

        for platform in &self.options.platforms {
            verify_binfmt_for_platform(platform)?;
            let suffix = platform_to_suffix(platform);
            let platform_tags: Vec<String> =
                real_tags.iter().map(|t| format!("{t}-{suffix}")).collect();

            let mut opts = self.options.clone();
            opts.platform = Some(platform.clone());
            opts.platforms = Vec::new();
            opts.tags.clone_from(&platform_tags);
            opts.push = false; // push the assembled manifest list, not per-arch images

            info!("Building manifest member for platform {platform}");
            let built = backend
                .build_image(&self.context, dockerfile, &opts, self.event_tx.clone())
                .await?;
            total_layers += built.layer_count;
            total_size += built.size;
            if let Some(first) = platform_tags.first() {
                arch_tags.push(first.clone());
            }
        }

        // Assemble the manifest list under the first tag, add each arch member,
        // then apply any remaining tags to the list.
        info!("Creating manifest list {manifest_name}");
        backend.manifest_create(&manifest_name).await?;
        for arch_tag in &arch_tags {
            backend.manifest_add(&manifest_name, arch_tag).await?;
        }
        for tag in real_tags.iter().skip(1) {
            backend.tag_image(&manifest_name, tag).await?;
        }

        if self.options.push {
            for tag in &real_tags {
                info!("Pushing manifest list {tag}");
                backend
                    .manifest_push(
                        tag,
                        &format!("docker://{tag}"),
                        self.options.registry_auth.as_ref(),
                    )
                    .await?;
            }
        }

        #[allow(clippy::cast_possible_truncation)]
        let build_time_ms = start_time.elapsed().as_millis() as u64;
        Ok(BuiltImage {
            image_id: manifest_name,
            tags: real_tags,
            layer_count: total_layers,
            size: total_size,
            build_time_ms,
            is_manifest: true,
        })
    }

    /// Run the build
    ///
    /// This executes the complete build process:
    /// 1. Parse Dockerfile or load runtime template
    /// 2. Build all required stages
    /// 3. Commit and tag the final image
    /// 4. Push to registry if configured
    /// 5. Clean up intermediate containers
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - Dockerfile parsing fails
    /// - A buildah command fails
    /// - Target stage is not found
    /// - Registry push fails
    ///
    /// # Panics
    ///
    /// Panics if an instruction output is missing after all retry attempts (internal invariant).
    #[instrument(skip(self), fields(context = %self.context.display()))]
    #[allow(clippy::too_many_lines)]
    pub async fn build(mut self) -> Result<BuiltImage> {
        let start_time = std::time::Instant::now();

        info!("Starting build in context: {}", self.context.display());

        // 0. Resolve the effective target OS from the priority chain when the
        //    caller did not pin one explicitly. Re-detects the backend if the
        //    resolved OS differs from the one we initially probed (Linux). A
        //    pinned `target_os` wins and skips this resolution entirely.
        self.resolve_target_os_and_backend().await?;

        // Mirror the resolved OS pin into the options so the backend can read
        // it. The macOS Seatbelt sandbox uses this to gate base-image toolchain
        // provisioning to darwin-native builds only (`None`).
        self.options.target_os = self.target_os;

        // 1. Get build output (Dockerfile IR or WASM artifact)
        let build_output = self.get_build_output().await?;

        // If this is a WASM build, return early with the artifact info.
        if let BuildOutput::WasmArtifact {
            wasm_path,
            // `oci_path` drives the optional push branch below; when the
            // `local-registry` feature is off the push branch is compiled
            // out, so the binding is unused.
            #[cfg_attr(not(feature = "local-registry"), allow(unused_variables))]
            oci_path,
            manifest_digest,
            artifact_type: _,
            language,
            optimized,
            size,
        } = build_output
        {
            #[allow(clippy::cast_possible_truncation)]
            let build_time_ms = start_time.elapsed().as_millis() as u64;

            // Prefer a user tag as the image id; otherwise fall back to the
            // OCI manifest digest (sha256:...), which is what WASM tooling
            // references in `oci-archive:` / `oci:` URIs. As a last resort
            // (no tag, no digest — only possible if export somehow produced
            // no digest) use a `wasm-path:` marker so downstream code can
            // tell this was a WASM build.
            let image_id = if let Some(tag) = self.options.tags.first() {
                tag.clone()
            } else if let Some(digest) = manifest_digest.as_ref() {
                format!("wasm:{digest}")
            } else {
                format!("wasm-path:{}", wasm_path.display())
            };

            // Push WASM OCI artifact(s) to the remote registry if the user
            // both supplied tags and requested a push (e.g. `zlayer build
            // -t ghcr.io/org/mod:v1 --push`). Mirrors the container flow at
            // `BuildahBackend::build_image` where `options.push` drives
            // `push_image_internal` for each tag.
            //
            // Gated on `local-registry` because `ImagePuller::push_wasm` is
            // behind the `zlayer-registry/local` feature, matching the other
            // push-to-registry sites in this crate.
            #[cfg(feature = "local-registry")]
            if let Some(oci_dir) = oci_path
                .as_ref()
                .filter(|_| self.options.push && !self.options.tags.is_empty())
            {
                self.push_wasm_oci(&wasm_path, oci_dir).await?;
            }

            self.send_event(BuildEvent::BuildComplete {
                image_id: image_id.clone(),
            });

            info!(
                "WASM build completed in {}ms: {} ({}, {} bytes, optimized={}, image_id={})",
                build_time_ms,
                wasm_path.display(),
                language,
                size,
                optimized,
                image_id,
            );

            return Ok(BuiltImage {
                image_id,
                tags: self.options.tags.clone(),
                layer_count: 1,
                size,
                build_time_ms,
                is_manifest: false,
            });
        }

        // Extract the Dockerfile from the BuildOutput.
        let BuildOutput::Dockerfile(mut dockerfile) = build_output else {
            unreachable!("WasmArtifact case handled above");
        };
        // Docker semantics: ARGs declared before the first FROM participate
        // in FROM-line expansion (`FROM ${BASE_IMAGE}`), with build args
        // overriding their defaults. The parser keeps such targets as raw
        // stage strings (it has no build args), so resolve them here — for
        // every struct-consuming backend — or multi-stage Dockerfiles with
        // parameterised bases fail with "Stage '${...}' not found".
        dockerfile.resolve_from_args(&self.options.build_args);
        debug!("Parsed Dockerfile with {} stages", dockerfile.stages.len());

        // L-5: Static guard — catch `RUN choco install ...` /
        // `RUN winget install ...` on a nanoserver base image before we hand
        // the Dockerfile off to the backend. Nanoserver ships no package
        // manager, so without this check the build fails deep inside buildah
        // / HCS with an opaque "`choco` is not recognized" message.
        //
        // The validator is a pure AST walk; it runs regardless of the
        // resolved target OS because a Dockerfile pinning a Windows base
        // should be diagnosed the same way on a Linux build host doing a
        // cross-OS build as on a Windows host.
        if let Err(err) = crate::windows::deps::validate_dockerfile(&dockerfile) {
            return Err(BuildError::InvalidInstruction {
                instruction: "RUN".to_string(),
                reason: err.to_string(),
            });
        }

        // Single-platform convenience: a one-entry `platforms` list behaves like
        // `platform`. Promote it so the single-build path below picks it up.
        if self.options.platform.is_none() && self.options.platforms.len() == 1 {
            self.options.platform = Some(self.options.platforms[0].clone());
        }
        // Multi-arch: build each platform and assemble a manifest list.
        if self.options.platforms.len() > 1 {
            return self.build_manifest_list(&dockerfile, start_time).await;
        }

        // Delegate the build to the backend.
        let backend = self
            .backend
            .as_ref()
            .ok_or_else(|| BuildError::BuildahNotFound {
                message: "No build backend configured".into(),
            })?;

        info!("Delegating build to {} backend", backend.name());
        let built = backend
            .build_image(
                &self.context,
                &dockerfile,
                &self.options,
                self.event_tx.clone(),
            )
            .await?;

        // Import the built image into ZLayer's local registry and blob cache
        // so the runtime can find it without pulling from a remote registry.
        //
        // A user who wired up a local registry clearly wants built images to
        // live there — if the import fails (almost always EACCES on the
        // registry dir for an unprivileged user), bail with the registry path
        // in the message instead of silently producing a build that the
        // daemon can't find.
        #[cfg(feature = "local-registry")]
        if let Some(ref registry) = self.local_registry {
            if !built.tags.is_empty() {
                let tmp_dir = ZLayerDirs::system_default().tmp();
                std::fs::create_dir_all(&tmp_dir).ok();
                let tmp_path = tmp_dir.join(format!(
                    "zlayer-build-{}-{}.tar",
                    std::process::id(),
                    start_time.elapsed().as_nanos()
                ));

                // Export the built image to an OCI archive for the local-registry
                // import. Backend-owned: a non-buildah backend (the macOS Seatbelt
                // sandbox) assembles the archive natively from its rootfs; backends
                // that decline (`Ok(false)`) fall back to `buildah push …
                // oci-archive:` via the buildah executor. This is what lets a
                // buildah-less macOS host populate ~/.zlayer/registry.
                let export_tag = &built.tags[0];
                if !backend.export_oci_archive(export_tag, &tmp_path).await? {
                    let dest = format!("oci-archive:{}", tmp_path.display());
                    let push_cmd = BuildahCommand::push_to(export_tag, &dest);

                    self.executor
                        .execute_checked(&push_cmd)
                        .await
                        .map_err(|e| BuildError::RegistryError {
                            message: format!(
                                "failed to export image to OCI archive for local registry \
                                 import at {}: {e}",
                                registry.root().display()
                            ),
                        })?;
                }

                // Resolve the blob cache backend (if available).
                let blob_cache: Option<&dyn zlayer_registry::cache::BlobCacheBackend> =
                    self.cache_backend.as_ref().map(|arc| arc.as_ref().as_ref());

                let import_result = async {
                    for tag in &built.tags {
                        let info = import_image(
                            registry.as_ref(),
                            &tmp_path,
                            Some(tag.as_str()),
                            blob_cache,
                        )
                        .await
                        .map_err(|e| BuildError::RegistryError {
                            message: format!(
                                "failed to import '{tag}' into local registry at {}: {e}",
                                registry.root().display()
                            ),
                        })?;
                        info!(
                            tag = %tag,
                            digest = %info.digest,
                            "Imported into local registry"
                        );
                    }
                    Ok::<(), BuildError>(())
                }
                .await;

                // Clean up the temporary archive regardless of whether the
                // import succeeded (best-effort; warn on failure).
                if let Err(e) = fs::remove_file(&tmp_path).await {
                    warn!(path = %tmp_path.display(), error = %e, "Failed to remove temp OCI archive");
                }

                import_result?;
            }
        }

        Ok(built)
    }

    /// Resolve the effective target OS for this build and re-detect the
    /// backend when it differs from what was probed at construction.
    ///
    /// Priority (highest first):
    /// 1. `self.target_os` — explicit pin from the caller (e.g. CLI `--platform`).
    /// 2. `ZImage::resolve_target_os()` — `os:` field, else OS parsed from
    ///    the `platform:` field of the `ZImagefile`.
    /// 3. [`ImageOs::Linux`] — the historical default, applied whenever the
    ///    `ZImagefile` has neither hint and the caller didn't pin an OS.
    ///
    /// The runtime-template and plain-Dockerfile paths never carry an OS
    /// hint, so they fall through to the caller's pin or the default.
    async fn resolve_target_os_and_backend(&mut self) -> Result<()> {
        // Explicit pin always wins: the backend was already detected for
        // this OS by `new_with_os`/`with_target_os`. But the caller may
        // have set `backend_override` AFTER construction (via
        // `with_backend_override`), in which case the cached backend was
        // selected without that hint — re-detect so the override is honored.
        if let Some(target_os) = self.target_os {
            if self.options.backend_override.is_some() {
                self.backend = Some(
                    crate::backend::detect_backend_with_options(target_os, Some(&self.options))
                        .await?,
                );
            }
            return Ok(());
        }

        // Peek at the ZImagefile (if the caller pointed us at one, or if one
        // lives in the context dir). We only inspect the OS-related fields so
        // a malformed ZImagefile body defers its error to `get_build_output`.
        // Auto-detection accepts both a literal `ZImagefile` and any
        // `ZImagefile.<suffix>`. Read errors / ambiguity here are non-fatal
        // for OS peeking — `get_build_output` will surface them with a
        // proper `BuildError::ContextRead`.
        let zimage_path = self
            .options
            .zimagefile
            .clone()
            .or_else(|| find_context_zimagefile(&self.context).ok().flatten());

        let Some(path) = zimage_path else {
            // No ZImagefile — Dockerfile / runtime template paths have no OS
            // metadata, so the initial Linux detection stands. If the caller
            // set a backend_override after construction, re-resolve so the
            // cached default backend is replaced.
            if self.options.backend_override.is_some() {
                self.backend = Some(
                    crate::backend::detect_backend_with_options(
                        crate::backend::ImageOs::Linux,
                        Some(&self.options),
                    )
                    .await?,
                );
            }
            return Ok(());
        };

        // Let `get_build_output()` surface any real read / parse errors.
        let Ok(content) = fs::read_to_string(&path).await else {
            return Ok(());
        };
        let content = expand_zimage_vars(&content, &self.options.pipeline_vars);
        let Ok(zimage) = crate::zimage::parse_zimagefile(&content) else {
            return Ok(());
        };

        // Resolve the effective target OS. Explicit ZImagefile `os:`/`platform:`
        // hints win; when absent, sniff the produced binary's OS (mirrors the
        // CLI front-end). Both feed the same backend-selection path below, so a
        // binary-detected OS is treated exactly like an explicit hint.
        let resolved_os = zimage
            .resolve_target_os()
            .or_else(|| crate::zimage::detect_image_os_from_binary(&zimage, &self.context));

        if let Some(resolved) = resolved_os {
            // Re-detect only if the resolved OS differs from the one we
            // probed at construction. `new_with_os(None)` probes Linux, so
            // the common Linux case short-circuits — unless the caller
            // set a backend_override after construction, in which case we
            // must re-detect even for the initial OS to apply the override.
            let initial = crate::backend::ImageOs::Linux;
            if resolved != initial || self.options.backend_override.is_some() {
                info!(
                    "Re-detecting build backend for target OS {:?} (inferred from ZImagefile)",
                    resolved
                );
                self.backend = Some(
                    crate::backend::detect_backend_with_options(resolved, Some(&self.options))
                        .await?,
                );
            }
            self.target_os = Some(resolved);
        } else if self.options.backend_override.is_some() {
            // ZImagefile present but resolves to no explicit OS — apply the
            // override against the Linux default that was cached.
            self.backend = Some(
                crate::backend::detect_backend_with_options(
                    crate::backend::ImageOs::Linux,
                    Some(&self.options),
                )
                .await?,
            );
        }

        Ok(())
    }

    /// Detection order:
    /// 1. If `runtime` is set -> use template string -> parse as Dockerfile
    /// 2. If `zimagefile` is explicitly set -> read & parse `ZImagefile` -> convert
    /// 3. If a file called `ZImagefile` exists in the context dir -> same as (2)
    /// 4. Fall back to reading a Dockerfile (from `dockerfile` option or default)
    ///
    /// Returns [`BuildOutput::Dockerfile`] for container builds or
    /// [`BuildOutput::WasmArtifact`] for WASM builds.
    async fn get_build_output(&self) -> Result<BuildOutput> {
        // (a) Runtime template takes highest priority.
        if let Some(runtime) = &self.options.runtime {
            debug!("Using runtime template: {}", runtime);
            let content = get_template(*runtime);
            return Ok(BuildOutput::Dockerfile(Dockerfile::parse(content)?));
        }

        // (b) Explicit ZImagefile path.
        if let Some(ref zimage_path) = self.options.zimagefile {
            debug!("Reading ZImagefile: {}", zimage_path.display());
            let content =
                fs::read_to_string(zimage_path)
                    .await
                    .map_err(|e| BuildError::ContextRead {
                        path: zimage_path.clone(),
                        source: e,
                    })?;
            let content = expand_zimage_vars(&content, &self.options.pipeline_vars);
            let zimage = crate::zimage::parse_zimagefile(&content)?;
            return self.handle_zimage(&zimage).await;
        }

        // (c) Auto-detect ZImagefile in context directory. Accepts both a
        // literal `ZImagefile` and any `ZImagefile.<suffix>` (the convention
        // ZLayer itself uses: `ZImagefile.zlayer-node`,
        // `ZImagefile.zlayer-manager`, etc.). Ambiguity (multiple
        // `ZImagefile.<suffix>` entries with no literal tiebreaker) is a
        // hard error — the user must pass `-z <path>` to disambiguate.
        let auto_zimage_path =
            find_context_zimagefile(&self.context).map_err(|e| BuildError::ContextRead {
                path: self.context.clone(),
                source: e,
            })?;
        if let Some(auto_zimage_path) = auto_zimage_path {
            debug!(
                "Found ZImagefile in context: {}",
                auto_zimage_path.display()
            );
            let content = fs::read_to_string(&auto_zimage_path).await.map_err(|e| {
                BuildError::ContextRead {
                    path: auto_zimage_path,
                    source: e,
                }
            })?;
            let content = expand_zimage_vars(&content, &self.options.pipeline_vars);
            let zimage = crate::zimage::parse_zimagefile(&content)?;
            return self.handle_zimage(&zimage).await;
        }

        // (d) Fall back to Dockerfile.
        let dockerfile_path = self
            .options
            .dockerfile
            .clone()
            .unwrap_or_else(|| self.context.join("Dockerfile"));

        debug!("Reading Dockerfile: {}", dockerfile_path.display());

        let content =
            fs::read_to_string(&dockerfile_path)
                .await
                .map_err(|e| BuildError::ContextRead {
                    path: dockerfile_path,
                    source: e,
                })?;

        Ok(BuildOutput::Dockerfile(Dockerfile::parse(&content)?))
    }

    /// Convert a parsed [`ZImage`] into a [`BuildOutput`].
    ///
    /// Handles all four `ZImage` modes:
    /// - **Runtime** mode: delegates to the template system -> [`BuildOutput::Dockerfile`]
    /// - **Single-stage / Multi-stage**: converts via [`zimage_to_dockerfile`] -> [`BuildOutput::Dockerfile`]
    /// - **WASM** mode: builds a WASM component -> [`BuildOutput::WasmArtifact`]
    ///
    /// Any `build:` directives are resolved first by spawning nested builds.
    async fn handle_zimage(&self, zimage: &crate::zimage::ZImage) -> Result<BuildOutput> {
        // Runtime mode: delegate to template system.
        if let Some(ref runtime_name) = zimage.runtime {
            let rt = Runtime::from_name(runtime_name).ok_or_else(|| {
                BuildError::zimagefile_validation(format!(
                    "unknown runtime '{runtime_name}' in ZImagefile"
                ))
            })?;
            let content = get_template(rt);
            return Ok(BuildOutput::Dockerfile(Dockerfile::parse(content)?));
        }

        // WASM mode: build a WASM component.
        if zimage.wasm.is_some() {
            return self.handle_wasm_build(zimage).await;
        }

        // Resolve any `build:` directives to concrete base image tags.
        let resolved = self.resolve_build_directives(zimage).await?;

        // Single-stage or multi-stage: convert to Dockerfile IR directly.
        Ok(BuildOutput::Dockerfile(
            crate::zimage::zimage_to_dockerfile(&resolved)?,
        ))
    }

    /// Build a WASM component from the `ZImagefile` wasm configuration.
    ///
    /// Converts [`ZWasmConfig`](crate::zimage::ZWasmConfig) into a
    /// [`WasmBuildConfig`](crate::wasm_builder::WasmBuildConfig) and invokes
    /// the WASM builder pipeline.
    #[allow(clippy::too_many_lines)]
    async fn handle_wasm_build(&self, zimage: &crate::zimage::ZImage) -> Result<BuildOutput> {
        use crate::wasm_builder::{build_wasm, WasiTarget, WasmBuildConfig, WasmLanguage};
        use zlayer_registry::wasm::WasiVersion;
        use zlayer_registry::{export_wasm_as_oci, WasmExportConfig};

        // Caller guarantees `zimage.wasm` is `Some`.
        let wasm_config = zimage.wasm.as_ref().expect(
            "handle_wasm_build invoked without a wasm section in ZImage; caller must check",
        );

        info!("ZImagefile specifies WASM mode, running WASM build");

        // Convert target string to WasiTarget enum.
        let target = match wasm_config.target.as_str() {
            "preview1" => WasiTarget::Preview1,
            _ => WasiTarget::Preview2,
        };

        // Resolve language: parse from string or leave as None for auto-detection.
        let language = wasm_config
            .language
            .as_deref()
            .and_then(WasmLanguage::from_name);

        if let Some(ref lang_str) = wasm_config.language {
            if language.is_none() {
                return Err(BuildError::zimagefile_validation(format!(
                    "unknown WASM language '{lang_str}'. Supported: rust, go, python, \
                     typescript, assemblyscript, c, zig"
                )));
            }
        }

        // Build the WasmBuildConfig.
        let mut config = WasmBuildConfig {
            language,
            target,
            optimize: wasm_config.optimize,
            opt_level: wasm_config
                .opt_level
                .clone()
                .unwrap_or_else(|| "Oz".to_string()),
            wit_path: wasm_config.wit.as_ref().map(PathBuf::from),
            output_path: wasm_config.output.as_ref().map(PathBuf::from),
            world: wasm_config.world.clone(),
            features: wasm_config.features.clone(),
            build_args: wasm_config.build_args.clone(),
            pre_build: Vec::new(),
            post_build: Vec::new(),
            adapter: wasm_config.adapter.as_ref().map(PathBuf::from),
        };

        // Convert ZCommand pre/post build steps to Vec<Vec<String>>.
        for cmd in &wasm_config.pre_build {
            config.pre_build.push(zcommand_to_args(cmd));
        }
        for cmd in &wasm_config.post_build {
            config.post_build.push(zcommand_to_args(cmd));
        }

        // Build the WASM component.
        let result = build_wasm(&self.context, config).await?;

        let language_name = result.language.name().to_string();
        let wasm_path = result.wasm_path;
        let size = result.size;

        info!(
            "WASM build complete: {} ({} bytes, optimized={})",
            wasm_path.display(),
            size,
            wasm_config.optimize
        );

        // `wasm.oci: false` opts out of OCI artifact packaging and push —
        // the compilation pipeline above still runs (with caching, wasm-opt,
        // and the preview1 -> preview2 adapter), we simply skip the layout
        // write and leave `oci_path`/`manifest_digest`/`artifact_type` as
        // `None`. The push branch in `build()` keys off `oci_path.is_some()`
        // so skipping it here transparently disables push for this build.
        if !wasm_config.oci {
            info!(
                "WASM OCI export skipped (wasm.oci = false); raw .wasm at {}",
                wasm_path.display()
            );
            return Ok(BuildOutput::WasmArtifact {
                wasm_path,
                oci_path: None,
                manifest_digest: None,
                artifact_type: None,
                language: language_name,
                optimized: wasm_config.optimize,
                size,
            });
        }

        // Derive a module name for OCI annotations. Prefer the first tag's
        // repository component (`repo` from `repo:version` or `host/repo`),
        // falling back to the wasm file stem, then "wasm-module".
        let module_name = self
            .options
            .tags
            .first()
            .map(|t| module_name_from_tag(t))
            .or_else(|| {
                wasm_path
                    .file_stem()
                    .and_then(|s| s.to_str())
                    .map(str::to_string)
            })
            .unwrap_or_else(|| "wasm-module".to_string());

        // Map the selected WASI target to a WasiVersion so the export uses
        // the correct artifact_type without re-analyzing the binary.
        let wasi_version = match target {
            WasiTarget::Preview1 => Some(WasiVersion::Preview1),
            WasiTarget::Preview2 => Some(WasiVersion::Preview2),
        };

        // Carry ZImage labels across as OCI manifest annotations, matching
        // the behaviour of container image builds that emit LABEL -> annotations.
        let annotations: HashMap<String, String> = zimage.labels.clone();

        let export_config = WasmExportConfig {
            wasm_path: wasm_path.clone(),
            module_name: module_name.clone(),
            wasi_version,
            annotations,
        };

        let export =
            export_wasm_as_oci(&export_config)
                .await
                .map_err(|e| BuildError::RegistryError {
                    message: format!("failed to export WASM as OCI artifact: {e}"),
                })?;

        // Write the OCI image layout to disk next to the WASM file. The
        // layout directory name is `<module>-oci`, mirroring the CLI
        // `zlayer wasm export` layout in bin/zlayer/src/commands/wasm.rs.
        let layout_parent = wasm_path
            .parent()
            .map_or_else(|| self.context.clone(), Path::to_path_buf);
        let oci_dir = layout_parent.join(format!("{module_name}-oci"));
        write_wasm_oci_layout(&oci_dir, &export, &module_name).await?;

        info!(
            manifest_digest = %export.manifest_digest,
            artifact_type = %export.artifact_type,
            oci_path = %oci_dir.display(),
            "WASM OCI artifact written"
        );

        Ok(BuildOutput::WasmArtifact {
            wasm_path,
            oci_path: Some(oci_dir),
            manifest_digest: Some(export.manifest_digest),
            artifact_type: Some(export.artifact_type),
            language: language_name,
            optimized: wasm_config.optimize,
            size,
        })
    }

    /// Resolve `build:` directives in a `ZImage` by running nested builds.
    ///
    /// For each `build:` directive (top-level or per-stage), this method:
    /// 1. Determines the build context directory
    /// 2. Auto-detects the build file (`ZImagefile` > Dockerfile) unless specified
    /// 3. Spawns a nested `ImageBuilder` to build the context
    /// 4. Tags the result and replaces `build` with `base`
    async fn resolve_build_directives(
        &self,
        zimage: &crate::zimage::ZImage,
    ) -> Result<crate::zimage::ZImage> {
        let mut resolved = zimage.clone();

        // Resolve top-level `build:` directive.
        if let Some(ref build_ctx) = resolved.build {
            let tag = self.run_nested_build(build_ctx, "toplevel").await?;
            resolved.base = Some(tag);
            resolved.build = None;
        }

        // Resolve per-stage `build:` directives.
        if let Some(ref mut stages) = resolved.stages {
            for (name, stage) in stages.iter_mut() {
                if let Some(ref build_ctx) = stage.build {
                    let tag = self.run_nested_build(build_ctx, name).await?;
                    stage.base = Some(tag);
                    stage.build = None;
                }
            }
        }

        Ok(resolved)
    }

    /// Run a nested build from a `build:` directive and return the resulting image tag.
    fn run_nested_build<'a>(
        &'a self,
        build_ctx: &'a crate::zimage::types::ZBuildContext,
        stage_name: &'a str,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<String>> + Send + 'a>> {
        Box::pin(self.run_nested_build_inner(build_ctx, stage_name))
    }

    async fn run_nested_build_inner(
        &self,
        build_ctx: &crate::zimage::types::ZBuildContext,
        stage_name: &str,
    ) -> Result<String> {
        let context_dir = build_ctx.context_dir(&self.context);

        if !context_dir.exists() {
            return Err(BuildError::ContextRead {
                path: context_dir,
                source: std::io::Error::new(
                    std::io::ErrorKind::NotFound,
                    format!(
                        "build context directory not found for build directive in '{stage_name}'"
                    ),
                ),
            });
        }

        info!(
            "Building nested image for '{}' from context: {}",
            stage_name,
            context_dir.display()
        );

        // Create a tag for the nested build result.
        let tag = format!(
            "zlayer-build-dep-{}:{}",
            stage_name,
            chrono_lite_timestamp()
        );

        // Create nested builder. Inherit the parent's target_os (if any) so
        // a Windows top-level build doesn't silently spawn a Linux nested
        // build for its `build:` dependency.
        let mut nested = ImageBuilder::new_with_os(&context_dir, self.target_os).await?;
        nested = nested.tag(&tag);

        // Apply explicit build file if specified.
        if let Some(file) = build_ctx.file() {
            let file_path = context_dir.join(file);
            if std::path::Path::new(file).extension().is_some_and(|ext| {
                ext.eq_ignore_ascii_case("yml") || ext.eq_ignore_ascii_case("yaml")
            }) || file.starts_with("ZImagefile")
            {
                nested = nested.zimagefile(file_path);
            } else {
                nested = nested.dockerfile(file_path);
            }
        }

        // Apply build args.
        for (key, value) in build_ctx.args() {
            nested = nested.build_arg(&key, &value);
        }

        // Propagate default registry if set.
        if let Some(ref reg) = self.options.default_registry {
            nested = nested.default_registry(reg.clone());
        }

        // Run the nested build.
        let result = nested.build().await?;
        info!(
            "Nested build for '{}' completed: {}",
            stage_name, result.image_id
        );

        Ok(tag)
    }

    /// Push the WASM OCI artifact produced by `handle_wasm_build` to every
    /// user-supplied registry tag.
    ///
    /// Mirrors the container push flow in [`BuildahBackend::build_image`]:
    /// when `options.push` is true, each tag in `options.tags` is pushed.
    /// Tags that look like bare image names (no registry host, e.g.
    /// `myapp:wasm`) are skipped with an info log, matching how bare tags
    /// are treated elsewhere — a registryless tag has nowhere to be pushed.
    ///
    /// Re-runs [`export_wasm_as_oci`] on the produced `wasm_path` to obtain
    /// the [`WasmExportResult`] blobs required by [`ImagePuller::push_wasm`].
    /// The export is deterministic (same WASM binary produces the same
    /// blobs and digests), so the digests match the layout on disk at
    /// `oci_dir` that A1.2 wrote.
    ///
    /// [`BuildahBackend::build_image`]: crate::backend::buildah::BuildahBackend
    /// [`export_wasm_as_oci`]: zlayer_registry::export_wasm_as_oci
    /// [`WasmExportResult`]: zlayer_registry::WasmExportResult
    /// [`ImagePuller::push_wasm`]: zlayer_registry::ImagePuller::push_wasm
    #[cfg(feature = "local-registry")]
    async fn push_wasm_oci(&self, wasm_path: &Path, oci_dir: &Path) -> Result<()> {
        use zlayer_registry::wasm::WasiVersion;
        use zlayer_registry::{export_wasm_as_oci, BlobCache, ImagePuller, WasmExportConfig};

        // Derive the module name the same way `handle_wasm_build` did so the
        // re-exported artifact carries identical OCI annotations.
        let module_name = self
            .options
            .tags
            .first()
            .map(|t| module_name_from_tag(t))
            .or_else(|| {
                wasm_path
                    .file_stem()
                    .and_then(|s| s.to_str())
                    .map(str::to_string)
            })
            .unwrap_or_else(|| "wasm-module".to_string());

        // Reconstruct the export result from the on-disk WASM binary. The
        // `wasi_version` is left `None` so it is re-detected from the binary
        // (matches whatever A1.2 wrote unless the user mutated the file).
        let export_config = WasmExportConfig {
            wasm_path: wasm_path.to_path_buf(),
            module_name,
            wasi_version: None::<WasiVersion>,
            annotations: HashMap::new(),
        };
        let export =
            export_wasm_as_oci(&export_config)
                .await
                .map_err(|e| BuildError::RegistryError {
                    message: format!(
                        "failed to re-export WASM for push from {}: {e}",
                        wasm_path.display()
                    ),
                })?;

        // Build the puller once; reuse for every tag.
        let cache = BlobCache::new().map_err(|e| BuildError::RegistryError {
            message: format!("failed to create blob cache for WASM push: {e}"),
        })?;
        let puller = ImagePuller::new(cache);

        for tag in &self.options.tags {
            if !tag_has_registry_host(tag) {
                info!(
                    "Skipping WASM push for bare tag '{}' (no registry host); \
                     OCI layout still available at {}",
                    tag,
                    oci_dir.display()
                );
                continue;
            }

            let oci_auth = Self::resolve_wasm_push_auth(self.options.registry_auth.as_ref());

            info!("Pushing WASM artifact: {}", tag);
            let push_result = puller
                .push_wasm(tag, &export, &oci_auth)
                .await
                .map_err(|e| BuildError::RegistryError {
                    message: format!("failed to push WASM artifact '{tag}': {e}"),
                })?;
            info!(
                "Pushed WASM artifact: {} (manifest digest: {})",
                tag, push_result.manifest_digest
            );
        }

        Ok(())
    }

    /// Resolve registry auth for a WASM push.
    ///
    /// Uses the explicitly provided credentials when set; otherwise falls
    /// back to anonymous. Mirrors the minimal behaviour of the buildah push
    /// path (`--creds user:pass` when provided, otherwise let the registry
    /// decide).
    #[cfg(feature = "local-registry")]
    fn resolve_wasm_push_auth(auth: Option<&RegistryAuth>) -> zlayer_registry::RegistryAuth {
        match auth {
            Some(a) => zlayer_registry::RegistryAuth::Basic(a.username.clone(), a.password.clone()),
            None => zlayer_registry::RegistryAuth::Anonymous,
        }
    }

    /// Send an event to the TUI (if configured)
    fn send_event(&self, event: BuildEvent) {
        if let Some(tx) = &self.event_tx {
            // Ignore send errors - the receiver may have been dropped
            let _ = tx.send(event);
        }
    }
}

// Helper function to generate a timestamp-based name
fn chrono_lite_timestamp() -> String {
    use std::time::{SystemTime, UNIX_EPOCH};
    let duration = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default();
    format!("{}", duration.as_secs())
}

/// Convert a [`ZCommand`](crate::zimage::ZCommand) into a vector of string arguments
/// suitable for passing to [`WasmBuildConfig`](crate::wasm_builder::WasmBuildConfig)
/// pre/post build command lists.
fn zcommand_to_args(cmd: &crate::zimage::ZCommand) -> Vec<String> {
    match cmd {
        crate::zimage::ZCommand::Shell(s) => {
            vec!["/bin/sh".to_string(), "-c".to_string(), s.clone()]
        }
        crate::zimage::ZCommand::Exec(args) => args.clone(),
    }
}

/// Extract a short "module name" suitable for OCI annotations from an image
/// tag. Strips any registry host, leading path segments, and tag/digest.
///
/// Examples:
/// - `myapp:latest` -> `myapp`
/// - `ghcr.io/org/myapp:v1.2.3` -> `myapp`
/// - `myapp@sha256:...` -> `myapp`
fn module_name_from_tag(tag: &str) -> String {
    let last_segment = tag.rsplit('/').next().unwrap_or(tag);
    let without_tag = last_segment.split(':').next().unwrap_or(last_segment);
    let without_digest = without_tag.split('@').next().unwrap_or(without_tag);
    without_digest.to_string()
}

/// Heuristic: does `tag` include an explicit registry host?
///
/// Used to decide which tags are push-eligible. A tag is treated as
/// registry-qualified when it has at least one `/` and the first path
/// component looks like a host — it contains a `.` (FQDN like `ghcr.io`,
/// `registry.example.com`), a `:` (host:port like `localhost:5000`), or
/// equals the literal `localhost`. Bare names like `myapp:wasm` and
/// Docker-Hub-style `org/app:v1` are skipped because there is no explicit
/// registry to push to.
#[cfg(feature = "local-registry")]
fn tag_has_registry_host(tag: &str) -> bool {
    // No `/` means the whole string is `name[:tag]` with no host component.
    if !tag.contains('/') {
        return false;
    }
    let Some(first) = tag.split('/').next() else {
        return false;
    };
    first.contains('.') || first.contains(':') || first == "localhost"
}

/// Write an OCI image layout directory (`oci-layout`, `index.json`,
/// `blobs/sha256/...`) for a WASM artifact on disk. This mirrors the layout
/// emitted by the `zlayer wasm export` CLI command so the directory can be
/// consumed by tools that expect a standard OCI layout.
async fn write_wasm_oci_layout(
    oci_dir: &Path,
    export: &zlayer_registry::WasmExportResult,
    ref_name: &str,
) -> Result<()> {
    let map_io = |path: PathBuf| {
        move |e: std::io::Error| BuildError::ContextRead {
            path: path.clone(),
            source: e,
        }
    };

    fs::create_dir_all(oci_dir)
        .await
        .map_err(map_io(oci_dir.to_path_buf()))?;

    // `oci-layout` marker file.
    let layout_marker = oci_dir.join("oci-layout");
    let oci_layout = serde_json::json!({ "imageLayoutVersion": "1.0.0" });
    fs::write(
        &layout_marker,
        serde_json::to_vec_pretty(&oci_layout).map_err(|e| BuildError::RegistryError {
            message: format!("failed to serialize oci-layout marker: {e}"),
        })?,
    )
    .await
    .map_err(map_io(layout_marker.clone()))?;

    // `blobs/sha256/` directory.
    let blobs_dir = oci_dir.join("blobs").join("sha256");
    fs::create_dir_all(&blobs_dir)
        .await
        .map_err(map_io(blobs_dir.clone()))?;

    // Write config, wasm-layer, and manifest blobs under their digests.
    let write_blob = |digest: &str, data: &[u8]| {
        let hash = digest.strip_prefix("sha256:").unwrap_or(digest).to_string();
        let path = blobs_dir.join(hash);
        let data = data.to_vec();
        async move {
            fs::write(&path, &data)
                .await
                .map_err(map_io(path.clone()))?;
            Ok::<(), BuildError>(())
        }
    };

    write_blob(&export.config_digest, &export.config_blob).await?;
    write_blob(&export.wasm_layer_digest, &export.wasm_binary).await?;
    write_blob(&export.manifest_digest, &export.manifest_json).await?;

    // Write `index.json` pointing at the manifest.
    let index = serde_json::json!({
        "schemaVersion": 2,
        "mediaType": "application/vnd.oci.image.index.v1+json",
        "manifests": [{
            "mediaType": "application/vnd.oci.image.manifest.v1+json",
            "digest": export.manifest_digest,
            "size": export.manifest_size,
            "artifactType": export.artifact_type,
            "annotations": {
                "org.opencontainers.image.ref.name": ref_name,
            }
        }]
    });
    let index_path = oci_dir.join("index.json");
    fs::write(
        &index_path,
        serde_json::to_vec_pretty(&index).map_err(|e| BuildError::RegistryError {
            message: format!("failed to serialize OCI index.json: {e}"),
        })?,
    )
    .await
    .map_err(map_io(index_path.clone()))?;

    Ok(())
}

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

    #[test]
    fn expand_zimage_vars_substitutes_known_and_keeps_unknown() {
        let mut vars = std::collections::HashMap::new();
        vars.insert("LTSC".to_string(), "ltsc2025".to_string());
        vars.insert(
            "REGISTRY".to_string(),
            "ghcr.io/blackleafdigital/zlayer".to_string(),
        );
        let content = "base: ${REGISTRY}/base:windows-${LTSC}\nrun: echo ${UNKNOWN}\n";
        let out = expand_zimage_vars(content, &vars);
        assert_eq!(
            out,
            "base: ghcr.io/blackleafdigital/zlayer/base:windows-ltsc2025\nrun: echo ${UNKNOWN}\n"
        );
    }

    #[test]
    fn expand_zimage_vars_empty_is_noop() {
        let vars = std::collections::HashMap::new();
        let content = "base: mcr.microsoft.com/windows/servercore:${LTSC}\n";
        assert_eq!(expand_zimage_vars(content, &vars), content);
    }

    #[test]
    fn find_context_zimagefile_prefers_literal() {
        let dir = tempfile::tempdir().unwrap();
        // Both a literal `ZImagefile` AND a `.suffix` variant exist — the
        // literal wins outright per the documented resolution order.
        std::fs::write(dir.path().join("ZImagefile"), "base: alpine\n").unwrap();
        std::fs::write(dir.path().join("ZImagefile.prod"), "base: alpine\n").unwrap();
        let found = find_context_zimagefile(dir.path()).unwrap();
        assert_eq!(found, Some(dir.path().join("ZImagefile")));
    }

    #[test]
    fn find_context_zimagefile_picks_unique_suffix() {
        let dir = tempfile::tempdir().unwrap();
        // Only one `ZImagefile.<suffix>` and no literal — auto-detect
        // returns it. This is the common multi-image-repo convention
        // (e.g. `ZImagefile.zataserver`).
        std::fs::write(dir.path().join("ZImagefile.zataserver"), "base: rust\n").unwrap();
        let found = find_context_zimagefile(dir.path()).unwrap();
        assert_eq!(found, Some(dir.path().join("ZImagefile.zataserver")));
    }

    #[test]
    fn find_context_zimagefile_none_when_only_dockerfile() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("Dockerfile"), "FROM alpine\n").unwrap();
        let found = find_context_zimagefile(dir.path()).unwrap();
        assert_eq!(found, None);
    }

    #[test]
    fn find_context_zimagefile_ambiguous_errors() {
        let dir = tempfile::tempdir().unwrap();
        // Two `.suffix` variants and NO literal `ZImagefile` to break the
        // tie — silently picking either one is a footgun, so this MUST
        // surface as an error pointing the user at `-z <path>`.
        std::fs::write(dir.path().join("ZImagefile.prod"), "base: alpine\n").unwrap();
        std::fs::write(dir.path().join("ZImagefile.dev"), "base: alpine\n").unwrap();
        let err = find_context_zimagefile(dir.path()).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("multiple ZImagefile candidates"),
            "error must explain ambiguity, got: {msg}"
        );
        assert!(msg.contains("ZImagefile.dev"));
        assert!(msg.contains("ZImagefile.prod"));
        assert!(msg.contains("-z"));
    }

    #[test]
    fn find_context_zimagefile_ignores_empty_suffix() {
        // A file named literally `ZImagefile.` (with a trailing dot and no
        // suffix) is a weird edge case but it shouldn't be picked up as a
        // candidate — the helper requires a non-empty suffix.
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(dir.path().join("ZImagefile."), "junk\n").unwrap();
        let found = find_context_zimagefile(dir.path()).unwrap();
        assert_eq!(found, None);
    }

    #[test]
    fn test_registry_auth_new() {
        let auth = RegistryAuth::new("user", "pass");
        assert_eq!(auth.username, "user");
        assert_eq!(auth.password, "pass");
    }

    #[test]
    fn test_build_options_default() {
        let opts = BuildOptions::default();
        assert!(opts.dockerfile.is_none());
        assert!(opts.zimagefile.is_none());
        assert!(opts.runtime.is_none());
        assert!(opts.build_args.is_empty());
        assert!(opts.target.is_none());
        assert!(opts.tags.is_empty());
        assert!(!opts.no_cache);
        assert!(!opts.push);
        assert!(!opts.squash);
        // New cache-related fields
        assert!(opts.layers); // Default is true
        assert!(opts.cache_from.is_none());
        assert!(opts.cache_to.is_none());
        assert!(opts.cache_ttl.is_none());
        // Cache backend config (only with cache feature)
        #[cfg(feature = "cache")]
        assert!(opts.cache_backend_config.is_none());
    }

    fn create_test_builder() -> ImageBuilder {
        // Create a minimal builder for testing (without async initialization)
        ImageBuilder {
            context: PathBuf::from("/tmp/test"),
            options: BuildOptions::default(),
            executor: BuildahExecutor::with_path("/usr/bin/buildah"),
            event_tx: None,
            target_os: None,
            backend: None,
            #[cfg(feature = "cache")]
            cache_backend: None,
            #[cfg(feature = "local-registry")]
            local_registry: None,
        }
    }

    // Builder method chaining tests
    #[test]
    fn test_builder_chaining() {
        let mut builder = create_test_builder();

        builder = builder
            .dockerfile("./Dockerfile.test")
            .runtime(Runtime::Node20)
            .build_arg("VERSION", "1.0")
            .target("builder")
            .tag("myapp:latest")
            .tag("myapp:v1")
            .no_cache()
            .squash()
            .format("oci");

        assert_eq!(
            builder.options.dockerfile,
            Some(PathBuf::from("./Dockerfile.test"))
        );
        assert_eq!(builder.options.runtime, Some(Runtime::Node20));
        assert_eq!(
            builder.options.build_args.get("VERSION"),
            Some(&"1.0".to_string())
        );
        assert_eq!(builder.options.target, Some("builder".to_string()));
        assert_eq!(builder.options.tags.len(), 2);
        assert!(builder.options.no_cache);
        assert!(builder.options.squash);
        assert_eq!(builder.options.format, Some("oci".to_string()));
    }

    #[test]
    fn test_builder_push_with_auth() {
        let mut builder = create_test_builder();
        builder = builder.push(RegistryAuth::new("user", "pass"));

        assert!(builder.options.push);
        assert!(builder.options.registry_auth.is_some());
        let auth = builder.options.registry_auth.unwrap();
        assert_eq!(auth.username, "user");
        assert_eq!(auth.password, "pass");
    }

    #[test]
    fn test_builder_push_without_auth() {
        let mut builder = create_test_builder();
        builder = builder.push_without_auth();

        assert!(builder.options.push);
        assert!(builder.options.registry_auth.is_none());
    }

    #[test]
    fn test_builder_layers() {
        let mut builder = create_test_builder();
        // Default is true
        assert!(builder.options.layers);

        // Disable layers
        builder = builder.layers(false);
        assert!(!builder.options.layers);

        // Re-enable layers
        builder = builder.layers(true);
        assert!(builder.options.layers);
    }

    #[test]
    fn test_builder_cache_from() {
        let mut builder = create_test_builder();
        assert!(builder.options.cache_from.is_none());

        builder = builder.cache_from("registry.example.com/myapp:cache");
        assert_eq!(
            builder.options.cache_from,
            Some("registry.example.com/myapp:cache".to_string())
        );
    }

    #[test]
    fn test_builder_cache_to() {
        let mut builder = create_test_builder();
        assert!(builder.options.cache_to.is_none());

        builder = builder.cache_to("registry.example.com/myapp:cache");
        assert_eq!(
            builder.options.cache_to,
            Some("registry.example.com/myapp:cache".to_string())
        );
    }

    #[test]
    fn test_builder_cache_ttl() {
        use std::time::Duration;

        let mut builder = create_test_builder();
        assert!(builder.options.cache_ttl.is_none());

        builder = builder.cache_ttl(Duration::from_secs(3600));
        assert_eq!(builder.options.cache_ttl, Some(Duration::from_secs(3600)));
    }

    #[test]
    fn test_builder_cache_options_chaining() {
        use std::time::Duration;

        let builder = create_test_builder()
            .layers(true)
            .cache_from("registry.example.com/cache:input")
            .cache_to("registry.example.com/cache:output")
            .cache_ttl(Duration::from_secs(7200))
            .no_cache();

        assert!(builder.options.layers);
        assert_eq!(
            builder.options.cache_from,
            Some("registry.example.com/cache:input".to_string())
        );
        assert_eq!(
            builder.options.cache_to,
            Some("registry.example.com/cache:output".to_string())
        );
        assert_eq!(builder.options.cache_ttl, Some(Duration::from_secs(7200)));
        assert!(builder.options.no_cache);
    }

    #[test]
    fn test_chrono_lite_timestamp() {
        let ts = chrono_lite_timestamp();
        // Should be a valid number
        let parsed: u64 = ts.parse().expect("Should be a valid u64");
        // Should be reasonably recent (after 2024)
        assert!(parsed > 1_700_000_000);
    }
}