cascade-environment 0.1.0-alpha.2

Execution-environment detection and planning contracts for Cascade.
Documentation
//! Execution-environment domain model for Cascade.
//!
//! This crate owns environment intent, executable-origin classification, tool
//! requirements, detection reports, and setup-plan contracts. Detection command
//! execution remains deferred to backend modules so these values stay portable
//! and deterministic in tests.

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

use cascade_core::{CascadeError, CascadeResult};
use serde::{Deserialize, Serialize};

mod backend;
mod detection;
mod probe;
mod remediation;
mod rendering;
mod runner;

pub use backend::*;
pub use detection::*;
pub use probe::*;
pub use remediation::*;
pub use rendering::*;
pub use runner::*;

/// Execution environment selected for a workspace.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
pub enum EnvironmentKind {
    /// The operating-system environment running Cascade.
    Host,
    /// A named Windows Subsystem for Linux distribution.
    Wsl { distribution: String },
}

impl EnvironmentKind {
    /// Creates a validated WSL environment selection.
    pub fn wsl(distribution: impl Into<String>) -> CascadeResult<Self> {
        let distribution = distribution.into();
        if distribution.trim().is_empty() {
            return Err(CascadeError::new("WSL distribution cannot be empty"));
        }
        Ok(Self::Wsl { distribution })
    }
}

/// How commands cross the selected environment boundary.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ExecutionMode {
    /// Cascade and the selected agent are installed inside the environment.
    Native,
    /// Host executables are launched through an environment interoperability layer.
    #[default]
    HostInterop,
}

/// Origin of an executable visible from an environment.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ExecutableOrigin {
    /// Executable is installed inside the selected environment.
    Native,
    /// Executable is inherited from the host through a mounted host path.
    HostInherited,
    /// Detection found a path whose ownership cannot be established safely.
    Unknown,
}

/// Stable roles used when checking environment readiness.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ToolRole {
    Git,
    Shell,
    Terminal,
    Agent,
    AgentRuntime,
    Cascade,
}

/// Required executable origin for one tool.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum RequiredOrigin {
    Any,
    Native,
    HostInherited,
}

/// Requirement declared by a backend for a selected environment.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ToolRequirement {
    pub command: String,
    pub role: ToolRole,
    pub required_origin: RequiredOrigin,
}

/// Executable resolved during environment detection.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResolvedExecutable {
    pub command: String,
    pub path: PathBuf,
    pub origin: ExecutableOrigin,
    pub version: Option<String>,
}

/// Classifies a command path as seen from a WSL distribution.
///
/// Paths under `/mnt/<drive>/` are Windows-host executables inherited through
/// WSL interop. Other absolute Unix paths are native to the distribution.
pub fn classify_wsl_executable(path: &Path) -> ExecutableOrigin {
    let normalized = path.to_string_lossy().replace('\\', "/");
    let mut components = normalized.split('/').filter(|part| !part.is_empty());
    match (components.next(), components.next(), components.next()) {
        (Some("mnt"), Some(drive), Some(_))
            if drive.len() == 1
                && drive
                    .as_bytes()
                    .first()
                    .is_some_and(u8::is_ascii_alphabetic) =>
        {
            ExecutableOrigin::HostInherited
        }
        _ if normalized.starts_with('/') => ExecutableOrigin::Native,
        _ => ExecutableOrigin::Unknown,
    }
}

/// Readiness state derived for a requirement.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ToolReadiness {
    Ready,
    Missing,
    WrongOrigin,
}

/// Result of checking one tool requirement.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ToolReport {
    pub requirement: ToolRequirement,
    pub resolved: Option<ResolvedExecutable>,
    pub readiness: ToolReadiness,
}

impl ToolReport {
    /// Derives readiness without executing a command.
    pub fn from_detection(
        requirement: ToolRequirement,
        resolved: Option<ResolvedExecutable>,
    ) -> Self {
        let readiness = match resolved.as_ref() {
            None => ToolReadiness::Missing,
            Some(executable)
                if origin_satisfies(requirement.required_origin, executable.origin) =>
            {
                ToolReadiness::Ready
            }
            Some(_) => ToolReadiness::WrongOrigin,
        };
        Self {
            requirement,
            resolved,
            readiness,
        }
    }
}

/// Evaluates backend requirements against environment-scoped executable facts.
///
/// Resolution is keyed by the declared command. Backends should preserve all
/// probe issues separately in `EnvironmentReport::issues`.
pub fn evaluate_requirements(
    requirements: &[ToolRequirement],
    resolved: &[ResolvedExecutable],
) -> Vec<ToolReport> {
    requirements
        .iter()
        .cloned()
        .map(|requirement| {
            let executable = resolved
                .iter()
                .find(|executable| executable.command == requirement.command)
                .cloned();
            ToolReport::from_detection(requirement, executable)
        })
        .collect()
}

fn origin_satisfies(required: RequiredOrigin, actual: ExecutableOrigin) -> bool {
    match required {
        RequiredOrigin::Any => actual != ExecutableOrigin::Unknown,
        RequiredOrigin::Native => actual == ExecutableOrigin::Native,
        RequiredOrigin::HostInherited => actual == ExecutableOrigin::HostInherited,
    }
}

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

    #[test]
    fn validates_wsl_distribution_name() {
        assert!(EnvironmentKind::wsl("Ubuntu").is_ok());
        assert!(EnvironmentKind::wsl("  ").is_err());
    }

    #[test]
    fn classifies_wsl_native_executables() {
        assert_eq!(
            classify_wsl_executable(Path::new("/home/user/.nvm/versions/node/v24/bin/codex")),
            ExecutableOrigin::Native
        );
        assert_eq!(
            classify_wsl_executable(Path::new("/usr/bin/git")),
            ExecutableOrigin::Native
        );
    }

    #[test]
    fn classifies_wsl_host_inherited_executables_without_fixed_drive() {
        assert_eq!(
            classify_wsl_executable(Path::new("/mnt/c/Users/user/AppData/Roaming/npm/codex")),
            ExecutableOrigin::HostInherited
        );
        assert_eq!(
            classify_wsl_executable(Path::new("/mnt/z/tools/cascade.exe")),
            ExecutableOrigin::HostInherited
        );
    }

    #[test]
    fn reports_wrong_origin_for_native_requirement() {
        let requirement = ToolRequirement {
            command: "codex".to_owned(),
            role: ToolRole::Agent,
            required_origin: RequiredOrigin::Native,
        };
        let resolved = ResolvedExecutable {
            command: "codex".to_owned(),
            path: PathBuf::from("/mnt/c/Users/user/AppData/Roaming/npm/codex"),
            origin: ExecutableOrigin::HostInherited,
            version: Some("0.144.5".to_owned()),
        };

        assert_eq!(
            ToolReport::from_detection(requirement, Some(resolved)).readiness,
            ToolReadiness::WrongOrigin
        );
    }

    #[test]
    fn evaluates_ready_missing_and_wrong_origin_requirements() {
        let requirements = vec![
            ToolRequirement {
                command: "git".to_owned(),
                role: ToolRole::Git,
                required_origin: RequiredOrigin::Native,
            },
            ToolRequirement {
                command: "codex".to_owned(),
                role: ToolRole::Agent,
                required_origin: RequiredOrigin::Native,
            },
            ToolRequirement {
                command: "node".to_owned(),
                role: ToolRole::AgentRuntime,
                required_origin: RequiredOrigin::Native,
            },
        ];
        let resolved = vec![
            ResolvedExecutable {
                command: "git".to_owned(),
                path: PathBuf::from("/usr/bin/git"),
                origin: ExecutableOrigin::Native,
                version: None,
            },
            ResolvedExecutable {
                command: "codex".to_owned(),
                path: PathBuf::from("/mnt/c/tools/codex"),
                origin: ExecutableOrigin::HostInherited,
                version: None,
            },
        ];

        let reports = evaluate_requirements(&requirements, &resolved);

        assert_eq!(reports[0].readiness, ToolReadiness::Ready);
        assert_eq!(reports[1].readiness, ToolReadiness::WrongOrigin);
        assert_eq!(reports[2].readiness, ToolReadiness::Missing);
    }
}