Maintain/Run/

Environment.rs

//=============================================================================//
// File Path: Element/Maintain/Source/Run/Environment.rs
//=============================================================================//
// Module: Environment
//
// Brief Description: Environment variable management for run operations.
//
// RESPONSIBILITIES:
// ================
//
// Primary:
// - Resolve environment variables from profiles
// - Merge environment variables from multiple sources
// - Validate environment configuration
//
// Secondary:
// - Provide environment variable templates
// - Support environment inheritance
//
// ARCHITECTURAL ROLE:
// ===================
//
// Position:
// - Infrastructure/Environment management layer
// - Environment resolution
//
// Dependencies (What this module requires):
// - External crates: std
// - Internal modules: Constant, Definition, Error
// - Traits implemented: None
//
// Dependents (What depends on this module):
// - Run CLI module
// - Run Process module
//
//=============================================================================//
// IMPLEMENTATION
//=============================================================================//

use crate::Run::Constant::*;
use crate::Run::Definition::Profile;
use crate::Run::Error::Result;

use std::collections::HashMap;

/// Resolves environment variables for a run profile.
///
/// This function combines environment variables from multiple sources:
/// 1. Template defaults
/// 2. Shell environment (if enabled)
/// 3. Profile-specific variables
/// 4. CLI overrides
///
/// # Arguments
///
/// * `profile` - The profile to resolve environment for
/// * `merge_shell` - Whether to merge with shell environment
/// * `overrides` - CLI-provided environment overrides
///
/// # Returns
///
/// A HashMap of resolved environment variables
pub fn resolve(
    profile: &Profile,
    merge_shell: bool,
    overrides: &[(String, String)],
) -> Result<HashMap<String, String>> {
    let mut env = HashMap::new();

    // Layer 1: Template defaults
    apply_template_defaults(&mut env);

    // Layer 2: Shell environment (if enabled)
    if merge_shell {
        merge_shell_env(&mut env);
    }

    // Layer 3: Profile environment
    if let Some(profile_env) = &profile.env {
        for (key, value) in profile_env {
            env.insert(key.clone(), value.clone());
        }
    }

    // Layer 4: CLI overrides (highest priority)
    for (key, value) in overrides {
        env.insert(key.clone(), value.clone());
    }

    Ok(env)
}

/// Applies template default environment variables.
///
/// # Arguments
///
/// * `env` - The environment HashMap to populate
fn apply_template_defaults(env: &mut HashMap<String, String>) {
    // Default Node.js configuration
    env.entry("NODE_VERSION".to_string()).or_insert("22".to_string());
    env.entry("NODE_OPTIONS".to_string())
        .or_insert("--max-old-space-size=16384".to_string());

    // Default run configuration
    env.entry("HOT_RELOAD".to_string()).or_insert("true".to_string());
    env.entry("WATCH".to_string()).or_insert("true".to_string());
    env.entry("LIVE_RELOAD_PORT".to_string())
        .or_insert(DefaultLiveReloadPort.to_string());

    // Default logging
    env.entry("Level".to_string()).or_insert("silent".to_string());
    env.entry("RUST_LOG".to_string()).or_insert("info".to_string());
}

/// Merges shell environment variables into the environment.
///
/// Only merges build system-related environment variables.
///
/// # Arguments
///
/// * `env` - The environment HashMap to merge into
fn merge_shell_env(env: &mut HashMap<String, String>) {
    let relevant_vars = [
        "Browser", "Bundle", "Clean", "Compile", "Debug", "Dependency",
        "Mountain", "Wind", "Electron", "BrowserProxy",
        "NODE_ENV", "NODE_VERSION", "NODE_OPTIONS",
        "RUST_LOG", "AIR_LOG_JSON", "AIR_LOG_FILE", "Level",
        "HOT_RELOAD", "WATCH", "LIVE_RELOAD_PORT",
    ];

    for var in relevant_vars {
        if let Ok(value) = std::env::var(var) {
            env.insert(var.to_string(), value);
        }
    }
}

/// Validates environment variables for a run.
///
/// # Arguments
///
/// * `env` - The environment variables to validate
///
/// # Returns
///
/// A list of validation errors (empty if valid)
pub fn validate(env: &HashMap<String, String>) -> Vec<String> {
    let mut errors = Vec::new();

    // Check NODE_VERSION is set
    if !env.contains_key("NODE_VERSION") {
        errors.push("NODE_VERSION environment variable is required".to_string());
    }

    // Check NODE_ENV is set
    if !env.contains_key("NODE_ENV") {
        errors.push("NODE_ENV environment variable is required".to_string());
    }

    // Check at least one workbench is enabled
    let workbenches = ["Browser", "Wind", "Mountain", "Electron"];
    let has_workbench = workbenches.iter().any(|w| {
        env.get(*w).map(|v| v == "true").unwrap_or(false)
    });

    if !has_workbench {
        errors.push("At least one workbench must be enabled (Browser, Wind, Mountain, or Electron)".to_string());
    }

    // Check LIVE_RELOAD_PORT is valid
    if let Some(port_str) = env.get("LIVE_RELOAD_PORT") {
        if let Ok(port) = port_str.parse::<u16>() {
            if port == 0 {
                errors.push("LIVE_RELOAD_PORT cannot be 0".to_string());
            }
        } else {
            errors.push("LIVE_RELOAD_PORT must be a valid port number".to_string());
        }
    }

    errors
}

/// Gets the workbench type from environment variables.
///
/// # Arguments
///
/// * `env` - The environment variables
///
/// # Returns
///
/// The name of the enabled workbench, or None if none enabled
pub fn get_workbench(env: &HashMap<String, String>) -> Option<String> {
    let workbenches = [
        ("Browser", "Browser"),
        ("Wind", "Wind"),
        ("Mountain", "Mountain"),
        ("Electron", "Electron"),
    ];

    for (var, name) in workbenches {
        if env.get(var).map(|v| v == "true").unwrap_or(false) {
            return Some(name.to_string());
        }
    }

    None
}

/// Checks if debug mode is enabled.
///
/// # Arguments
///
/// * `env` - The environment variables
///
/// # Returns
///
/// True if debug mode is enabled
pub fn is_debug(env: &HashMap<String, String>) -> bool {
    env.get(DebugEnv).map(|v| v == "true").unwrap_or(false)
}

/// Checks if hot-reload is enabled.
///
/// # Arguments
///
/// * `env` - The environment variables
///
/// # Returns
///
/// True if hot-reload is enabled
pub fn is_hot_reload_enabled(env: &HashMap<String, String>) -> bool {
    env.get(HotReloadEnv).map(|v| v == "true").unwrap_or(true)
}

/// Checks if watch mode is enabled.
///
/// # Arguments
///
/// * `env` - The environment variables
///
/// # Returns
///
/// True if watch mode is enabled
pub fn is_watch_enabled(env: &HashMap<String, String>) -> bool {
    env.get(WatchEnv).map(|v| v == "true").unwrap_or(true)
}

/// Formats environment variables for display.
///
/// # Arguments
///
/// * `env` - The environment variables to format
///
/// # Returns
///
/// A formatted string representation
pub fn format_for_display(env: &HashMap<String, String>) -> String {
    let mut lines: Vec<String> = env.iter()
        .map(|(k, v)| {
            let display_value = if v.is_empty() {
                "(empty)".to_string()
            } else {
                v.clone()
            };
            format!("  {} = {}", k, display_value)
        })
        .collect();

    lines.sort();
    lines.join("\n")
}

/// Filters environment variables to only include run-related ones.
///
/// # Arguments
///
/// * `env` - The full environment
///
/// # Returns
///
/// A filtered HashMap with only run-related variables
pub fn filter_run_vars(env: &HashMap<String, String>) -> HashMap<String, String> {
    let run_prefixes = [
        "NODE_", "HOT_", "WATCH", "LIVE_", "AIR_", "RUST_",
        "Browser", "Bundle", "Clean", "Compile", "Debug",
        "Dependency", "Mountain", "Wind", "Electron", "Level",
    ];

    env.iter()
        .filter(|(k, _)| {
            run_prefixes.iter().any(|prefix| k.starts_with(prefix))
        })
        .map(|(k, v)| (k.clone(), v.clone()))
        .collect()
}