Skip to main content

cascade_environment/
lib.rs

1//! Execution-environment domain model for Cascade.
2//!
3//! This crate owns environment intent, executable-origin classification, tool
4//! requirements, detection reports, and setup-plan contracts. Detection command
5//! execution remains deferred to backend modules so these values stay portable
6//! and deterministic in tests.
7
8use std::path::{Path, PathBuf};
9
10use cascade_core::{CascadeError, CascadeResult};
11use serde::{Deserialize, Serialize};
12
13mod backend;
14mod detection;
15mod probe;
16mod remediation;
17mod rendering;
18mod runner;
19
20pub use backend::*;
21pub use detection::*;
22pub use probe::*;
23pub use remediation::*;
24pub use rendering::*;
25pub use runner::*;
26
27/// Execution environment selected for a workspace.
28#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
29#[serde(tag = "kind", rename_all = "kebab-case")]
30pub enum EnvironmentKind {
31    /// The operating-system environment running Cascade.
32    Host,
33    /// A named Windows Subsystem for Linux distribution.
34    Wsl { distribution: String },
35}
36
37impl EnvironmentKind {
38    /// Creates a validated WSL environment selection.
39    pub fn wsl(distribution: impl Into<String>) -> CascadeResult<Self> {
40        let distribution = distribution.into();
41        if distribution.trim().is_empty() {
42            return Err(CascadeError::new("WSL distribution cannot be empty"));
43        }
44        Ok(Self::Wsl { distribution })
45    }
46}
47
48/// How commands cross the selected environment boundary.
49#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
50#[serde(rename_all = "kebab-case")]
51pub enum ExecutionMode {
52    /// Cascade and the selected agent are installed inside the environment.
53    Native,
54    /// Host executables are launched through an environment interoperability layer.
55    #[default]
56    HostInterop,
57}
58
59/// Origin of an executable visible from an environment.
60#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
61#[serde(rename_all = "kebab-case")]
62pub enum ExecutableOrigin {
63    /// Executable is installed inside the selected environment.
64    Native,
65    /// Executable is inherited from the host through a mounted host path.
66    HostInherited,
67    /// Detection found a path whose ownership cannot be established safely.
68    Unknown,
69}
70
71/// Stable roles used when checking environment readiness.
72#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
73#[serde(rename_all = "kebab-case")]
74pub enum ToolRole {
75    Git,
76    Shell,
77    Terminal,
78    Agent,
79    AgentRuntime,
80    Cascade,
81}
82
83/// Required executable origin for one tool.
84#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
85#[serde(rename_all = "kebab-case")]
86pub enum RequiredOrigin {
87    Any,
88    Native,
89    HostInherited,
90}
91
92/// Requirement declared by a backend for a selected environment.
93#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
94pub struct ToolRequirement {
95    pub command: String,
96    pub role: ToolRole,
97    pub required_origin: RequiredOrigin,
98}
99
100/// Executable resolved during environment detection.
101#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
102pub struct ResolvedExecutable {
103    pub command: String,
104    pub path: PathBuf,
105    pub origin: ExecutableOrigin,
106    pub version: Option<String>,
107}
108
109/// Classifies a command path as seen from a WSL distribution.
110///
111/// Paths under `/mnt/<drive>/` are Windows-host executables inherited through
112/// WSL interop. Other absolute Unix paths are native to the distribution.
113pub fn classify_wsl_executable(path: &Path) -> ExecutableOrigin {
114    let normalized = path.to_string_lossy().replace('\\', "/");
115    let mut components = normalized.split('/').filter(|part| !part.is_empty());
116    match (components.next(), components.next(), components.next()) {
117        (Some("mnt"), Some(drive), Some(_))
118            if drive.len() == 1
119                && drive
120                    .as_bytes()
121                    .first()
122                    .is_some_and(u8::is_ascii_alphabetic) =>
123        {
124            ExecutableOrigin::HostInherited
125        }
126        _ if normalized.starts_with('/') => ExecutableOrigin::Native,
127        _ => ExecutableOrigin::Unknown,
128    }
129}
130
131/// Readiness state derived for a requirement.
132#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
133#[serde(rename_all = "kebab-case")]
134pub enum ToolReadiness {
135    Ready,
136    Missing,
137    WrongOrigin,
138}
139
140/// Result of checking one tool requirement.
141#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
142pub struct ToolReport {
143    pub requirement: ToolRequirement,
144    pub resolved: Option<ResolvedExecutable>,
145    pub readiness: ToolReadiness,
146}
147
148impl ToolReport {
149    /// Derives readiness without executing a command.
150    pub fn from_detection(
151        requirement: ToolRequirement,
152        resolved: Option<ResolvedExecutable>,
153    ) -> Self {
154        let readiness = match resolved.as_ref() {
155            None => ToolReadiness::Missing,
156            Some(executable)
157                if origin_satisfies(requirement.required_origin, executable.origin) =>
158            {
159                ToolReadiness::Ready
160            }
161            Some(_) => ToolReadiness::WrongOrigin,
162        };
163        Self {
164            requirement,
165            resolved,
166            readiness,
167        }
168    }
169}
170
171/// Evaluates backend requirements against environment-scoped executable facts.
172///
173/// Resolution is keyed by the declared command. Backends should preserve all
174/// probe issues separately in `EnvironmentReport::issues`.
175pub fn evaluate_requirements(
176    requirements: &[ToolRequirement],
177    resolved: &[ResolvedExecutable],
178) -> Vec<ToolReport> {
179    requirements
180        .iter()
181        .cloned()
182        .map(|requirement| {
183            let executable = resolved
184                .iter()
185                .find(|executable| executable.command == requirement.command)
186                .cloned();
187            ToolReport::from_detection(requirement, executable)
188        })
189        .collect()
190}
191
192fn origin_satisfies(required: RequiredOrigin, actual: ExecutableOrigin) -> bool {
193    match required {
194        RequiredOrigin::Any => actual != ExecutableOrigin::Unknown,
195        RequiredOrigin::Native => actual == ExecutableOrigin::Native,
196        RequiredOrigin::HostInherited => actual == ExecutableOrigin::HostInherited,
197    }
198}
199
200#[cfg(test)]
201mod tests {
202    use super::*;
203
204    #[test]
205    fn validates_wsl_distribution_name() {
206        assert!(EnvironmentKind::wsl("Ubuntu").is_ok());
207        assert!(EnvironmentKind::wsl("  ").is_err());
208    }
209
210    #[test]
211    fn classifies_wsl_native_executables() {
212        assert_eq!(
213            classify_wsl_executable(Path::new("/home/user/.nvm/versions/node/v24/bin/codex")),
214            ExecutableOrigin::Native
215        );
216        assert_eq!(
217            classify_wsl_executable(Path::new("/usr/bin/git")),
218            ExecutableOrigin::Native
219        );
220    }
221
222    #[test]
223    fn classifies_wsl_host_inherited_executables_without_fixed_drive() {
224        assert_eq!(
225            classify_wsl_executable(Path::new("/mnt/c/Users/user/AppData/Roaming/npm/codex")),
226            ExecutableOrigin::HostInherited
227        );
228        assert_eq!(
229            classify_wsl_executable(Path::new("/mnt/z/tools/cascade.exe")),
230            ExecutableOrigin::HostInherited
231        );
232    }
233
234    #[test]
235    fn reports_wrong_origin_for_native_requirement() {
236        let requirement = ToolRequirement {
237            command: "codex".to_owned(),
238            role: ToolRole::Agent,
239            required_origin: RequiredOrigin::Native,
240        };
241        let resolved = ResolvedExecutable {
242            command: "codex".to_owned(),
243            path: PathBuf::from("/mnt/c/Users/user/AppData/Roaming/npm/codex"),
244            origin: ExecutableOrigin::HostInherited,
245            version: Some("0.144.5".to_owned()),
246        };
247
248        assert_eq!(
249            ToolReport::from_detection(requirement, Some(resolved)).readiness,
250            ToolReadiness::WrongOrigin
251        );
252    }
253
254    #[test]
255    fn evaluates_ready_missing_and_wrong_origin_requirements() {
256        let requirements = vec![
257            ToolRequirement {
258                command: "git".to_owned(),
259                role: ToolRole::Git,
260                required_origin: RequiredOrigin::Native,
261            },
262            ToolRequirement {
263                command: "codex".to_owned(),
264                role: ToolRole::Agent,
265                required_origin: RequiredOrigin::Native,
266            },
267            ToolRequirement {
268                command: "node".to_owned(),
269                role: ToolRole::AgentRuntime,
270                required_origin: RequiredOrigin::Native,
271            },
272        ];
273        let resolved = vec![
274            ResolvedExecutable {
275                command: "git".to_owned(),
276                path: PathBuf::from("/usr/bin/git"),
277                origin: ExecutableOrigin::Native,
278                version: None,
279            },
280            ResolvedExecutable {
281                command: "codex".to_owned(),
282                path: PathBuf::from("/mnt/c/tools/codex"),
283                origin: ExecutableOrigin::HostInherited,
284                version: None,
285            },
286        ];
287
288        let reports = evaluate_requirements(&requirements, &resolved);
289
290        assert_eq!(reports[0].readiness, ToolReadiness::Ready);
291        assert_eq!(reports[1].readiness, ToolReadiness::WrongOrigin);
292        assert_eq!(reports[2].readiness, ToolReadiness::Missing);
293    }
294}