use std::ffi::OsString;
use std::path::Path;
use cascade_core::{CascadeError, CascadeResult};
use crate::{
DetectionRequest, EnvironmentCommandRunner, EnvironmentDetector, EnvironmentIssue,
EnvironmentIssueSeverity, EnvironmentKind, EnvironmentReport, ExecutableOrigin, ExecutionMode,
ProcessEnvironmentCommandRunner, ResolvedExecutable, ToolReport, evaluate_requirements,
parse_executable_path, parse_version_output, parse_wsl_distributions,
};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HostPlatform {
Windows,
Unix,
}
impl HostPlatform {
pub fn current() -> Self {
if cfg!(windows) {
Self::Windows
} else {
Self::Unix
}
}
}
#[derive(Debug, Clone)]
pub struct HostEnvironmentDetector<R = ProcessEnvironmentCommandRunner> {
runner: R,
platform: HostPlatform,
}
impl Default for HostEnvironmentDetector {
fn default() -> Self {
Self {
runner: ProcessEnvironmentCommandRunner,
platform: HostPlatform::current(),
}
}
}
impl<R> HostEnvironmentDetector<R> {
pub fn new(runner: R, platform: HostPlatform) -> Self {
Self { runner, platform }
}
}
impl<R: EnvironmentCommandRunner> EnvironmentDetector for HostEnvironmentDetector<R> {
fn detect(&self, request: &DetectionRequest) -> CascadeResult<EnvironmentReport> {
if request.environment != EnvironmentKind::Host {
return Err(CascadeError::new(
"host detector requires the host environment",
));
}
let mut resolved = Vec::new();
let mut issues = Vec::new();
for requirement in &request.requirements {
let path_output = self.lookup(&requirement.command);
let path = match path_output {
Ok(output) if output.succeeded() => parse_executable_path(&output.stdout),
Ok(_) => None,
Err(error) => {
issues.push(probe_issue(
"executable-probe-failed",
EnvironmentIssueSeverity::Error,
&requirement.command,
error.to_string(),
));
None
}
};
if let Some(path) = path {
let version = supports_version_probe(requirement.role)
.then(|| self.version(&path, &requirement.command, &mut issues))
.flatten();
resolved.push(ResolvedExecutable {
command: requirement.command.clone(),
path,
origin: ExecutableOrigin::Native,
version,
});
}
}
Ok(EnvironmentReport {
environment: request.environment.clone(),
execution_mode: request.execution_mode,
tools: evaluate_requirements(&request.requirements, &resolved),
issues,
})
}
}
impl<R: EnvironmentCommandRunner> HostEnvironmentDetector<R> {
fn lookup(&self, command: &str) -> CascadeResult<crate::ProbeOutput> {
if Path::new(command).is_file() {
return Ok(crate::ProbeOutput {
stdout: command.to_owned(),
stderr: String::new(),
exit_code: Some(0),
});
}
match self.platform {
HostPlatform::Windows => {
let output = self.runner.run("where", &[OsString::from(command)])?;
if output.succeeded() && parse_executable_path(&output.stdout).is_some() {
return Ok(output);
}
self.runner.run(
"pwsh",
&[
OsString::from("-NoProfile"),
OsString::from("-CommandWithArgs"),
OsString::from(
"$resolved = Get-Command -CommandType Application,ExternalScript -ErrorAction SilentlyContinue -- $args[0]; if ($resolved) { $resolved.Source } else { exit 1 }",
),
OsString::from(command),
],
)
}
HostPlatform::Unix => self.runner.run(
"sh",
&[
OsString::from("-c"),
OsString::from("command -v -- \"$1\""),
OsString::from("cascade-probe"),
OsString::from(command),
],
),
}
}
fn version(
&self,
path: &Path,
command: &str,
issues: &mut Vec<EnvironmentIssue>,
) -> Option<String> {
let version_output = if self.platform == HostPlatform::Windows
&& path.extension().is_some_and(|extension| extension == "ps1")
{
self.runner.run(
"pwsh",
&[
OsString::from("-NoProfile"),
OsString::from("-File"),
path.as_os_str().to_owned(),
OsString::from("--version"),
],
)
} else {
self.runner
.run(&path.to_string_lossy(), &[OsString::from("--version")])
};
match version_output {
Ok(output) if output.succeeded() => parse_version_output(&output.stdout),
Ok(output) => {
issues.push(probe_issue(
"version-probe-failed",
EnvironmentIssueSeverity::Warning,
command,
probe_failure_detail(&output),
));
None
}
Err(error) => {
issues.push(probe_issue(
"version-probe-failed",
EnvironmentIssueSeverity::Warning,
command,
error.to_string(),
));
None
}
}
}
}
#[derive(Debug, Clone)]
pub struct WslEnvironmentDetector<R = ProcessEnvironmentCommandRunner> {
runner: R,
}
impl Default for WslEnvironmentDetector {
fn default() -> Self {
Self {
runner: ProcessEnvironmentCommandRunner,
}
}
}
impl<R> WslEnvironmentDetector<R> {
pub fn new(runner: R) -> Self {
Self { runner }
}
}
impl<R: EnvironmentCommandRunner> WslEnvironmentDetector<R> {
pub fn list_distributions(&self) -> CascadeResult<Vec<String>> {
let output = self.runner.run(
"wsl",
&[OsString::from("--list"), OsString::from("--quiet")],
)?;
if !output.succeeded() {
return Err(CascadeError::new(format!(
"failed to list WSL distributions: {}",
probe_failure_detail(&output)
)));
}
Ok(parse_wsl_distributions(&output.stdout))
}
}
impl<R: EnvironmentCommandRunner> EnvironmentDetector for WslEnvironmentDetector<R> {
fn detect(&self, request: &DetectionRequest) -> CascadeResult<EnvironmentReport> {
let EnvironmentKind::Wsl { distribution } = &request.environment else {
return Err(CascadeError::new("WSL detector requires a WSL environment"));
};
let mut issues = Vec::new();
let distributions = match self.list_distributions() {
Ok(distributions) => distributions,
Err(error) => {
issues.push(EnvironmentIssue {
code: "wsl-unavailable".to_owned(),
severity: EnvironmentIssueSeverity::Error,
message: error.to_string(),
command: Some("wsl".to_owned()),
});
return Ok(empty_report(request, issues));
}
};
if !distributions.iter().any(|value| value == distribution) {
issues.push(EnvironmentIssue {
code: "wsl-distribution-missing".to_owned(),
severity: EnvironmentIssueSeverity::Error,
message: format!("WSL distribution `{distribution}` is not installed"),
command: Some("wsl".to_owned()),
});
return Ok(empty_report(request, issues));
}
let mut resolved = Vec::new();
for requirement in &request.requirements {
let path_output = self.wsl_lookup(distribution, &requirement.command);
let path = match path_output {
Ok(output) if output.succeeded() => parse_executable_path(&output.stdout),
Ok(_) => None,
Err(error) => {
issues.push(probe_issue(
"executable-probe-failed",
EnvironmentIssueSeverity::Error,
&requirement.command,
error.to_string(),
));
None
}
};
if let Some(path) = path {
let version = supports_version_probe(requirement.role)
.then(|| {
self.wsl_version(distribution, &path, &requirement.command, &mut issues)
})
.flatten();
let origin = crate::classify_wsl_executable(&path);
resolved.push(ResolvedExecutable {
command: requirement.command.clone(),
path,
origin,
version,
});
}
}
let tools = evaluate_requirements(&request.requirements, &resolved);
if request.execution_mode == ExecutionMode::Native {
for tool in &tools {
if tool
.resolved
.as_ref()
.is_some_and(|executable| executable.origin == ExecutableOrigin::HostInherited)
{
issues.push(probe_issue(
"host-inherited-tool",
EnvironmentIssueSeverity::Error,
&tool.requirement.command,
"native WSL mode requires a guest-side executable".to_owned(),
));
}
}
}
Ok(EnvironmentReport {
environment: request.environment.clone(),
execution_mode: request.execution_mode,
tools,
issues,
})
}
}
impl<R: EnvironmentCommandRunner> WslEnvironmentDetector<R> {
fn wsl_lookup(&self, distribution: &str, command: &str) -> CascadeResult<crate::ProbeOutput> {
self.runner.run(
"wsl",
&[
OsString::from("--distribution"),
OsString::from(distribution),
OsString::from("--exec"),
OsString::from("sh"),
OsString::from("-c"),
OsString::from("command -v -- \"$1\""),
OsString::from("cascade-probe"),
OsString::from(command),
],
)
}
fn wsl_version(
&self,
distribution: &str,
path: &Path,
command: &str,
issues: &mut Vec<EnvironmentIssue>,
) -> Option<String> {
let output = self.runner.run(
"wsl",
&[
OsString::from("--distribution"),
OsString::from(distribution),
OsString::from("--exec"),
path.as_os_str().to_owned(),
OsString::from("--version"),
],
);
match output {
Ok(output) if output.succeeded() => parse_version_output(&output.stdout),
Ok(output) => {
issues.push(probe_issue(
"version-probe-failed",
EnvironmentIssueSeverity::Warning,
command,
probe_failure_detail(&output),
));
None
}
Err(error) => {
issues.push(probe_issue(
"version-probe-failed",
EnvironmentIssueSeverity::Warning,
command,
error.to_string(),
));
None
}
}
}
}
fn empty_report(request: &DetectionRequest, issues: Vec<EnvironmentIssue>) -> EnvironmentReport {
EnvironmentReport {
environment: request.environment.clone(),
execution_mode: request.execution_mode,
tools: request
.requirements
.iter()
.cloned()
.map(|requirement| ToolReport::from_detection(requirement, None))
.collect(),
issues,
}
}
fn supports_version_probe(role: crate::ToolRole) -> bool {
!matches!(role, crate::ToolRole::Terminal | crate::ToolRole::Cascade)
}
fn probe_issue(
code: &str,
severity: EnvironmentIssueSeverity,
command: &str,
detail: String,
) -> EnvironmentIssue {
EnvironmentIssue {
code: code.to_owned(),
severity,
message: format!("probe for `{command}` failed: {detail}"),
command: Some(command.to_owned()),
}
}
fn probe_failure_detail(output: &crate::ProbeOutput) -> String {
let stderr = output.stderr.trim();
if !stderr.is_empty() {
return stderr.to_owned();
}
format!("process exited with status {:?}", output.exit_code)
}
#[cfg(test)]
mod tests {
use std::collections::VecDeque;
use std::sync::{Arc, Mutex};
use super::*;
use crate::{RequiredOrigin, ToolReadiness, ToolRequirement, ToolRole};
type RecordedCall = (String, Vec<OsString>);
#[derive(Debug, Clone)]
struct FakeRunner {
calls: Arc<Mutex<Vec<RecordedCall>>>,
outputs: Arc<Mutex<VecDeque<CascadeResult<crate::ProbeOutput>>>>,
}
impl FakeRunner {
fn new(outputs: Vec<CascadeResult<crate::ProbeOutput>>) -> Self {
Self {
calls: Arc::new(Mutex::new(Vec::new())),
outputs: Arc::new(Mutex::new(outputs.into())),
}
}
fn calls(&self) -> Vec<RecordedCall> {
self.calls.lock().unwrap().clone()
}
}
impl EnvironmentCommandRunner for FakeRunner {
fn run(&self, program: &str, args: &[OsString]) -> CascadeResult<crate::ProbeOutput> {
self.calls
.lock()
.unwrap()
.push((program.to_owned(), args.to_vec()));
self.outputs
.lock()
.unwrap()
.pop_front()
.expect("fake output")
}
}
fn output(stdout: &str) -> CascadeResult<crate::ProbeOutput> {
Ok(crate::ProbeOutput {
stdout: stdout.to_owned(),
stderr: String::new(),
exit_code: Some(0),
})
}
fn requirement(command: &str, origin: RequiredOrigin) -> ToolRequirement {
ToolRequirement {
command: command.to_owned(),
role: ToolRole::Agent,
required_origin: origin,
}
}
#[test]
fn unix_host_lookup_passes_tool_as_positional_argument() {
let runner = FakeRunner::new(vec![output("/usr/bin/git\n"), output("git 2.45\n")]);
let detector = HostEnvironmentDetector::new(runner.clone(), HostPlatform::Unix);
let request = DetectionRequest {
environment: EnvironmentKind::Host,
execution_mode: ExecutionMode::Native,
requirements: vec![requirement("git", RequiredOrigin::Native)],
};
let report = detector.detect(&request).unwrap();
let calls = runner.calls();
assert!(report.is_ready());
assert_eq!(calls[0].0, "sh");
assert_eq!(calls[0].1.last(), Some(&OsString::from("git")));
assert!(!calls[0].1[1].to_string_lossy().contains("git"));
}
#[test]
fn windows_host_uses_where_without_platform_dependent_path_parsing() {
let runner = FakeRunner::new(vec![
output("C:\\tools\\codex.exe\r\n"),
output("codex 0.144.5\r\n"),
]);
let detector = HostEnvironmentDetector::new(runner.clone(), HostPlatform::Windows);
let request = DetectionRequest {
environment: EnvironmentKind::Host,
execution_mode: ExecutionMode::Native,
requirements: vec![requirement("codex", RequiredOrigin::Native)],
};
let report = detector.detect(&request).unwrap();
assert!(report.is_ready());
assert_eq!(runner.calls()[0].0, "where");
assert_eq!(
report.tools[0].resolved.as_ref().unwrap().origin,
ExecutableOrigin::Native
);
}
#[test]
fn windows_host_falls_back_to_powershell_external_script_resolution() {
let runner = FakeRunner::new(vec![
Ok(crate::ProbeOutput {
stdout: String::new(),
stderr: "not found".to_owned(),
exit_code: Some(1),
}),
output("C:\\Users\\user\\AppData\\Roaming\\npm\\codex.ps1\r\n"),
output("codex-cli 0.144.5\r\n"),
]);
let detector = HostEnvironmentDetector::new(runner.clone(), HostPlatform::Windows);
let request = DetectionRequest {
environment: EnvironmentKind::Host,
execution_mode: ExecutionMode::Native,
requirements: vec![requirement("codex", RequiredOrigin::Native)],
};
let report = detector.detect(&request).unwrap();
let calls = runner.calls();
assert!(report.is_ready());
assert_eq!(calls[1].0, "pwsh");
assert_eq!(calls[1].1[1], OsString::from("-CommandWithArgs"));
assert_eq!(calls[2].0, "pwsh");
assert_eq!(calls[2].1[1], OsString::from("-File"));
}
#[test]
fn wsl_detector_classifies_inherited_tool_and_preserves_failed_version_path() {
let runner = FakeRunner::new(vec![
output("Ubuntu\n"),
output("/mnt/c/tools/codex\n"),
Ok(crate::ProbeOutput {
stdout: String::new(),
stderr: "version unsupported".to_owned(),
exit_code: Some(2),
}),
]);
let detector = WslEnvironmentDetector::new(runner);
let request = DetectionRequest {
environment: EnvironmentKind::wsl("Ubuntu").unwrap(),
execution_mode: ExecutionMode::Native,
requirements: vec![requirement("codex", RequiredOrigin::Native)],
};
let report = detector.detect(&request).unwrap();
assert_eq!(report.tools[0].readiness, ToolReadiness::WrongOrigin);
assert!(report.tools[0].resolved.is_some());
assert!(
report
.issues
.iter()
.any(|issue| issue.code == "version-probe-failed")
);
assert!(
report
.issues
.iter()
.any(|issue| issue.code == "host-inherited-tool")
);
}
#[test]
fn wsl_detector_reports_unknown_distribution_before_tool_probes() {
let runner = FakeRunner::new(vec![output("Debian\n")]);
let detector = WslEnvironmentDetector::new(runner.clone());
let request = DetectionRequest {
environment: EnvironmentKind::wsl("Ubuntu").unwrap(),
execution_mode: ExecutionMode::Native,
requirements: vec![requirement("git", RequiredOrigin::Native)],
};
let report = detector.detect(&request).unwrap();
assert_eq!(runner.calls().len(), 1);
assert_eq!(report.tools[0].readiness, ToolReadiness::Missing);
assert_eq!(report.issues[0].code, "wsl-distribution-missing");
}
#[test]
fn missing_wsl_returns_partial_report_instead_of_aborting_detection() {
let runner = FakeRunner::new(vec![Err(CascadeError::new("program not found"))]);
let detector = WslEnvironmentDetector::new(runner);
let request = DetectionRequest {
environment: EnvironmentKind::wsl("Ubuntu").unwrap(),
execution_mode: ExecutionMode::HostInterop,
requirements: vec![requirement("cascade", RequiredOrigin::HostInherited)],
};
let report = detector.detect(&request).unwrap();
assert_eq!(report.issues[0].code, "wsl-unavailable");
assert_eq!(report.tools[0].readiness, ToolReadiness::Missing);
}
}