waterui-cli 0.4.0

//! Platform abstraction for `WaterUI` CLI.

use std::str::FromStr;

use crate::build::{BuildProfile, BuildProgress};
use target_lexicon::{
    Aarch64Architecture, Architecture, DefaultToHost, Environment, OperatingSystem,
    Riscv32Architecture, Triple, Vendor,
};

// ============================================================================
// Target Platform Enum (New Architecture)
// ============================================================================

/// Target platform for building and running `WaterUI` apps.
///
/// This enum replaces the old `Platform` trait with a simpler, more explicit model.
/// Each variant represents a specific target platform that `WaterUI` can build for.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TargetPlatform {
    // Apple platforms
    /// macOS (current machine architecture)
    MacOS,
    /// iOS (physical device, ARM64)
    IOS,
    /// iOS Simulator (host machine architecture)
    IOSSimulator,
    /// tvOS (physical device)
    TvOS,
    /// tvOS Simulator
    TvOSSimulator,
    /// watchOS (physical device)
    WatchOS,
    /// watchOS Simulator
    WatchOSSimulator,
    /// visionOS (physical device)
    VisionOS,
    /// visionOS Simulator
    VisionOSSimulator,

    // Other platforms
    /// Android
    Android,
    /// Linux (GTK4)
    Linux,
    /// Windows (Hydrolysis)
    Windows,
    /// Web (WASM + WebGPU)
    Web,
    /// ESP32-S3 (Xtensa, ESP-IDF firmware via the Dew backend)
    Esp32S3,
    /// ESP32-C3 (RISC-V, ESP-IDF firmware via the Dew backend)
    Esp32C3,
    /// ESP32-P4 (RISC-V with FPU, ESP-IDF firmware via the Dew backend)
    Esp32P4,
}

/// Backend types available for building.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TargetBackend {
    /// Apple backend (Xcode, UIKit/AppKit)
    Apple,
    /// Android backend (Gradle, Android Views)
    Android,
    /// GTK4 backend (pure Rust binary)
    Gtk4,
    /// Hydrolysis backend (self-drawn renderer)
    Hydrolysis,
    /// `WinUI` backend (Windows App SDK / `WinUI` 3, pure Rust binary)
    WinUi,
    /// Dew backend (embedded-first CPU renderer for ESP32-class chips)
    Dew,
}

impl TargetBackend {
    /// The framework scaffold packages the backend's generated crate links —
    /// the names a `framework.json` `scaffold` (or `experimental-packages`)
    /// table keys on. A withheld package means the selected channel cannot
    /// scaffold the backend at all.
    #[must_use]
    pub const fn scaffold_packages(&self) -> &'static [&'static str] {
        match self {
            Self::Apple | Self::Android => &[],
            Self::Gtk4 => &["waterui-gtk"],
            Self::Hydrolysis => &["hydrolysis", "hydrolysis-m3"],
            Self::WinUi => &["waterui-winui"],
            Self::Dew => &["waterui-dew"],
        }
    }

    /// The [`BuildProfile`] a development `water build` or `water run` uses
    /// for this backend when the user passes no profile flag.
    ///
    /// Self-drawn backends spend their per-frame budget in the rendering
    /// stack, so a Hydrolysis development build lifts the `dev` profile to a
    /// light optimization level rather than paying debug-code frame times;
    /// every other backend builds the declared `dev` profile. The two
    /// commands must agree on this default: generated backend crates share
    /// one Cargo target directory, and a profile mismatch re-fingerprints
    /// every dependency unit — the build's artifacts then warm nothing the
    /// run reuses.
    #[must_use]
    pub const fn default_development_profile(&self) -> BuildProfile {
        match self {
            Self::Hydrolysis => BuildProfile::Optimized,
            _ => BuildProfile::Debug,
        }
    }
}

impl TargetPlatform {
    /// Get the target triple for this platform.
    ///
    /// # Panics
    /// May panic if `target_lexicon` cannot resolve the current host triple for simulator or host-native targets.
    #[must_use]
    pub fn triple(&self) -> Triple {
        match self {
            Self::MacOS => Triple {
                architecture: DefaultToHost::default().0.architecture,
                vendor: Vendor::Apple,
                operating_system: OperatingSystem::Darwin(None),
                environment: Environment::Unknown,
                binary_format: target_lexicon::BinaryFormat::Macho,
            },
            Self::IOS => Triple {
                architecture: Architecture::Aarch64(Aarch64Architecture::Aarch64),
                vendor: Vendor::Apple,
                operating_system: OperatingSystem::IOS(None),
                environment: Environment::Unknown,
                binary_format: target_lexicon::BinaryFormat::Macho,
            },
            Self::IOSSimulator => {
                let arch = DefaultToHost::default().0.architecture;
                let env = match arch {
                    Architecture::X86_64 => Environment::Unknown,
                    _ => Environment::Sim,
                };
                Triple {
                    architecture: arch,
                    vendor: Vendor::Apple,
                    operating_system: OperatingSystem::IOS(None),
                    environment: env,
                    binary_format: target_lexicon::BinaryFormat::Macho,
                }
            }
            Self::TvOS => Triple {
                architecture: Architecture::Aarch64(Aarch64Architecture::Aarch64),
                vendor: Vendor::Apple,
                operating_system: OperatingSystem::TvOS(None),
                environment: Environment::Unknown,
                binary_format: target_lexicon::BinaryFormat::Macho,
            },
            Self::TvOSSimulator => Triple {
                architecture: DefaultToHost::default().0.architecture,
                vendor: Vendor::Apple,
                operating_system: OperatingSystem::TvOS(None),
                environment: Environment::Sim,
                binary_format: target_lexicon::BinaryFormat::Macho,
            },
            Self::WatchOS => Triple {
                architecture: Architecture::Aarch64(Aarch64Architecture::Aarch64),
                vendor: Vendor::Apple,
                operating_system: OperatingSystem::WatchOS(None),
                environment: Environment::Unknown,
                binary_format: target_lexicon::BinaryFormat::Macho,
            },
            Self::WatchOSSimulator => Triple {
                architecture: DefaultToHost::default().0.architecture,
                vendor: Vendor::Apple,
                operating_system: OperatingSystem::WatchOS(None),
                environment: Environment::Sim,
                binary_format: target_lexicon::BinaryFormat::Macho,
            },
            Self::VisionOS => Triple {
                architecture: Architecture::Aarch64(Aarch64Architecture::Aarch64),
                vendor: Vendor::Apple,
                operating_system: OperatingSystem::VisionOS(None),
                environment: Environment::Unknown,
                binary_format: target_lexicon::BinaryFormat::Macho,
            },
            Self::VisionOSSimulator => Triple {
                architecture: DefaultToHost::default().0.architecture,
                vendor: Vendor::Apple,
                operating_system: OperatingSystem::VisionOS(None),
                environment: Environment::Sim,
                binary_format: target_lexicon::BinaryFormat::Macho,
            },
            Self::Android => Triple {
                architecture: Architecture::Aarch64(Aarch64Architecture::Aarch64),
                vendor: Vendor::Unknown,
                operating_system: OperatingSystem::Linux,
                environment: Environment::Android,
                binary_format: target_lexicon::BinaryFormat::Elf,
            },
            Self::Linux | Self::Windows => Triple::host(),
            Self::Web => Triple::from_str("wasm32-unknown-unknown")
                .expect("web target triple must remain valid"),
            Self::Esp32S3 => Triple::from_str("xtensa-esp32s3-espidf")
                .expect("esp32s3 target triple must remain valid"),
            Self::Esp32C3 => Triple::from_str("riscv32imc-esp-espidf")
                .expect("esp32c3 target triple must remain valid"),
            Self::Esp32P4 => Triple::from_str("riscv32imafc-esp-espidf")
                .expect("esp32p4 target triple must remain valid"),
        }
    }

    /// Get available backends for this platform.
    #[must_use]
    pub const fn available_backends(&self) -> &[TargetBackend] {
        match self {
            Self::MacOS => &[TargetBackend::Apple, TargetBackend::Hydrolysis],
            Self::IOS
            | Self::IOSSimulator
            | Self::TvOS
            | Self::TvOSSimulator
            | Self::WatchOS
            | Self::WatchOSSimulator
            | Self::VisionOS
            | Self::VisionOSSimulator => &[TargetBackend::Apple],
            Self::Android => &[TargetBackend::Android],
            Self::Linux => &[TargetBackend::Gtk4, TargetBackend::Hydrolysis],
            Self::Windows => &[TargetBackend::Hydrolysis, TargetBackend::WinUi],
            Self::Web => &[TargetBackend::Hydrolysis],
            Self::Esp32S3 | Self::Esp32C3 | Self::Esp32P4 => &[TargetBackend::Dew],
        }
    }

    /// Get the default backend for this platform.
    #[must_use]
    pub const fn default_backend(&self) -> TargetBackend {
        match self {
            Self::MacOS
            | Self::IOS
            | Self::IOSSimulator
            | Self::TvOS
            | Self::TvOSSimulator
            | Self::WatchOS
            | Self::WatchOSSimulator
            | Self::VisionOS
            | Self::VisionOSSimulator => TargetBackend::Apple,
            Self::Android => TargetBackend::Android,
            Self::Linux => TargetBackend::Gtk4,
            Self::Windows | Self::Web => TargetBackend::Hydrolysis,
            Self::Esp32S3 | Self::Esp32C3 | Self::Esp32P4 => TargetBackend::Dew,
        }
    }

    /// Check if this platform is a simulator/emulator.
    #[must_use]
    pub const fn is_simulator(&self) -> bool {
        matches!(
            self,
            Self::IOSSimulator
                | Self::TvOSSimulator
                | Self::WatchOSSimulator
                | Self::VisionOSSimulator
        )
    }

    /// Get the SDK name for Apple platforms.
    #[must_use]
    pub const fn sdk_name(&self) -> Option<&'static str> {
        match self {
            Self::MacOS => Some("macosx"),
            Self::IOS => Some("iphoneos"),
            Self::IOSSimulator => Some("iphonesimulator"),
            Self::TvOS => Some("appletvos"),
            Self::TvOSSimulator => Some("appletvsimulator"),
            Self::WatchOS => Some("watchos"),
            Self::WatchOSSimulator => Some("watchsimulator"),
            Self::VisionOS => Some("xros"),
            Self::VisionOSSimulator => Some("xrsimulator"),
            Self::Android
            | Self::Linux
            | Self::Windows
            | Self::Web
            | Self::Esp32S3
            | Self::Esp32C3
            | Self::Esp32P4 => None,
        }
    }

    /// Get the architecture for this platform.
    #[must_use]
    pub fn arch(&self) -> Architecture {
        match self {
            Self::MacOS
            | Self::IOSSimulator
            | Self::TvOSSimulator
            | Self::WatchOSSimulator
            | Self::VisionOSSimulator
            | Self::Linux
            | Self::Windows => DefaultToHost::default().0.architecture,
            Self::IOS | Self::TvOS | Self::WatchOS | Self::VisionOS | Self::Android => {
                Architecture::Aarch64(Aarch64Architecture::Aarch64)
            }
            Self::Web => Architecture::Wasm32,
            Self::Esp32S3 => Architecture::XTensa,
            Self::Esp32C3 => Architecture::Riscv32(Riscv32Architecture::Riscv32imc),
            Self::Esp32P4 => Architecture::Riscv32(Riscv32Architecture::Riscv32imafc),
        }
    }
}

// ============================================================================
// Package Options
// ============================================================================

/// Configuration options for packaging the application.
///
/// This struct contains settings that control how the application
/// is packaged for distribution across different platforms.
#[derive(Debug, Clone)]
pub struct PackageOptions {
    /// Whether to prepare the package for store distribution.
    ///
    /// When `true`, the package will be configured for submission to
    /// official app stores (App Store for iOS/macOS or Play Store for Android).
    ///
    /// When `false`, the package will be prepared for direct distribution
    /// or development purposes.
    ///
    /// # Warning
    ///
    /// Enable this option only change your packaging format, it does not change your build configuration.
    /// For a real world distribution build, you may also want to disable `debug` in `BuildOptions`.
    distribution: bool,

    /// Whether to enable debug mode in the packaged application.
    ///
    /// When `true`, the application will include additional debug information
    /// and logging capabilities to facilitate troubleshooting during development.
    ///
    /// When `false`, the application will be optimized for release with
    /// minimal debug information.
    ///
    /// This flag is not conflict with `distribution`, since `distribution` decide the package format,
    /// while `debug` decide the build configuration.
    debug: bool,

    /// Whether the package embeds the shared `WaterUI` Rust runtime.
    shared_rust_runtime: bool,

    /// How `include_web!` mounts reach the packaged app.
    web_frontend: WebFrontendMode,

    /// Sink compile progress is reported to while packaging runs cargo —
    /// asset-manifest planning compiles the project rlib for its symbol table.
    progress: Option<BuildProgress>,
}

/// Whether an `include_web!` mount is staged from a frontend build or served
/// by a running dev server.
///
/// In dev-server mode staging skips a web mount entirely — no frontend build
/// and no copied output — since the app opens the bundler's dev-server URL
/// instead of the staged bundle. `water run` selects it in debug mode;
/// packaging and `--release` runs never do.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum WebFrontendMode {
    /// Build the frontend and stage its output into the bundle.
    #[default]
    Stage,
    /// A running dev server serves the mount; nothing is staged for it.
    DevServer,
}

impl PackageOptions {
    /// Create options for installing and running a development build.
    #[must_use]
    pub const fn development() -> Self {
        Self {
            distribution: false,
            debug: true,
            shared_rust_runtime: true,
            web_frontend: WebFrontendMode::Stage,
            progress: None,
        }
    }

    /// Create options for a self-contained package artifact.
    #[must_use]
    pub const fn packaging(distribution: bool, debug: bool) -> Self {
        Self {
            distribution,
            debug,
            shared_rust_runtime: false,
            web_frontend: WebFrontendMode::Stage,
            progress: None,
        }
    }

    /// Override the debug flag without changing the runtime linkage.
    #[must_use]
    pub const fn with_debug(mut self, debug: bool) -> Self {
        self.debug = debug;
        self
    }

    /// Mark web mounts as dev-server-served for this packaging pass.
    #[must_use]
    pub const fn with_dev_server(mut self, dev_server: bool) -> Self {
        self.web_frontend = if dev_server {
            WebFrontendMode::DevServer
        } else {
            WebFrontendMode::Stage
        };
        self
    }

    /// Whether to package in distribution mode
    #[must_use]
    pub const fn is_distribution(&self) -> bool {
        self.distribution
    }

    /// Whether to package in debug mode
    #[must_use]
    pub const fn is_debug(&self) -> bool {
        self.debug
    }

    /// Whether the package must embed the shared `WaterUI` Rust runtime.
    #[must_use]
    pub const fn uses_shared_rust_runtime(&self) -> bool {
        self.shared_rust_runtime
    }

    /// Whether web mounts are dev-server-served and skipped during staging.
    #[must_use]
    pub const fn uses_dev_server(&self) -> bool {
        matches!(self.web_frontend, WebFrontendMode::DevServer)
    }

    /// Attach a compile-progress sink the cargo invocations this packaging
    /// pass performs report to.
    #[must_use]
    pub fn with_progress(mut self, progress: BuildProgress) -> Self {
        self.progress = Some(progress);
        self
    }

    /// The compile-progress sink, when one is attached.
    #[must_use]
    pub const fn progress(&self) -> Option<&BuildProgress> {
        self.progress.as_ref()
    }
}

#[cfg(test)]
mod package_options_tests {
    use super::PackageOptions;

    #[test]
    fn development_embeds_shared_runtime_and_packaging_does_not() {
        let development = PackageOptions::development();
        assert!(development.is_debug());
        assert!(!development.is_distribution());
        assert!(development.uses_shared_rust_runtime());

        for options in [
            PackageOptions::packaging(false, true),
            PackageOptions::packaging(true, false),
        ] {
            assert!(!options.uses_shared_rust_runtime());
        }
    }
}