xbp_cli/utils/

mod.rs

//! utility functions for xbp cli
//!
//! provides utility modules for common operations
//! includes version api integration and other helper functions

pub mod cargo_manifest;
pub mod env_files;
pub mod node_toolchain;
pub mod pnpm_package_json;
pub mod process_monitor_json;
pub mod project_paths;
pub mod tray_runtime;
pub mod version;
pub mod xbp_ignore;

pub use cargo_manifest::{
    resolve_cargo_package_version, resolve_cargo_package_version_required,
    write_cargo_package_version,
};
pub use env_files::{
    first_lookup_value, load_env_lookup, normalize_env_key, normalize_env_value, parse_env_content,
    parse_env_file, resolve_env_placeholders, strip_utf8_bom, to_env_references,
    CLOUDFLARE_ACCOUNT_ID_ENV_KEYS,
};
pub use node_toolchain::{
    find_node_toolchain_root, is_node_toolchain_command, node_toolchain_wrapper_path,
};
pub use process_monitor_json::{
    fix_cursor_process_monitor_json, fix_cursor_process_monitor_json_file,
    CursorProcessMonitorJsonFix,
};
pub use pnpm_package_json::{migrate_package_json_pnpm_settings, PnpmSettingsMigration};
pub use project_paths::{
    collapse_project_path, resolve_project_dir, resolve_project_path, resolve_service_root,
};
pub use version::{fetch_version, increment_version};
pub use xbp_ignore::{
    default_global_worktree_ignore_content, default_xbp_ignore_path,
    load_global_worktree_ignore_from_path, load_project_xbp_ignore, sync_global_worktree_ignore_file,
    xbp_ignore_file_candidates, XbpIgnoreSet, DEFAULT_DISCOVERY_SKIP_DIRS,
    DEFAULT_GLOBAL_WORKTREE_IGNORE_PATTERNS, DEFAULT_NOISE_DIR_NAMES,
    GLOBAL_WORKTREE_IGNORE_FILENAME,
};

use serde::de::DeserializeOwned;
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use std::collections::{BTreeMap, HashMap, HashSet};
use std::fs;
use std::path::{Path, PathBuf};
use std::process::Command;
use sysinfo::{Pid, System};

use crate::profile::find_all_xbp_projects;

#[derive(Debug, Clone)]
pub struct FoundXbpConfig {
    pub project_root: PathBuf,
    pub config_path: PathBuf,
    pub kind: &'static str,
    pub location: String,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct KnownXbpProject {
    pub root: PathBuf,
    pub name: String,
}

#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ListeningPortOwnership {
    pub pids: Vec<u32>,
    pub xbp_projects: Vec<String>,
}

pub fn default_project_yaml_config_path(project_root: &Path) -> PathBuf {
    project_root.join(".xbp").join("xbp.yaml")
}

pub fn find_existing_yaml_xbp_config(project_root: &Path) -> Option<PathBuf> {
    let candidates = [
        project_root.join(".xbp").join("xbp.yaml"),
        project_root.join(".xbp").join("xbp.yml"),
        project_root.join("xbp.yaml"),
        project_root.join("xbp.yml"),
    ];

    candidates.into_iter().find(|candidate| candidate.exists())
}

pub fn maybe_auto_convert_legacy_xbp_json_to_yaml(
    project_root: &Path,
    config_path: &Path,
) -> Result<Option<PathBuf>, String> {
    if config_path.file_name() != Some(std::ffi::OsStr::new("xbp.json")) {
        return Ok(None);
    }

    if !config_path.exists() {
        return Ok(None);
    }

    if let Some(existing_yaml) = find_existing_yaml_xbp_config(project_root) {
        return Ok(Some(existing_yaml));
    }

    let content = fs::read_to_string(config_path).map_err(|e| {
        format!(
            "Failed to read legacy JSON config {}: {}",
            config_path.display(),
            e
        )
    })?;
    let value: Value = serde_json::from_str(&content)
        .map_err(|e| format!("Failed to parse legacy JSON config: {}", e))?;

    let yaml_path = default_project_yaml_config_path(project_root);
    if let Some(parent) = yaml_path.parent() {
        fs::create_dir_all(parent).map_err(|e| {
            format!(
                "Failed to create config directory {}: {}",
                parent.display(),
                e
            )
        })?;
    }

    let yaml = serialize_xbp_yaml(&value)?;
    fs::write(&yaml_path, yaml)
        .map_err(|e| format!("Failed to write YAML config {}: {}", yaml_path.display(), e))?;

    Ok(Some(yaml_path))
}

/// Canonical schema URL for project `.xbp/xbp.yaml` IntelliSense (yaml-language-server).
pub const XBP_PROJECT_YAML_SCHEMA_URL: &str =
    "https://raw.githubusercontent.com/xylex-group/xbp/main/schemas/xbp.project.schema.json";

/// Comment directive understood by the YAML Language Server / VS Code YAML extension.
pub const XBP_PROJECT_YAML_SCHEMA_DIRECTIVE: &str =
    "# yaml-language-server: $schema=https://raw.githubusercontent.com/xylex-group/xbp/main/schemas/xbp.project.schema.json\n";

pub fn serialize_xbp_yaml<T: Serialize>(value: &T) -> Result<String, String> {
    let yaml = serde_yaml::to_string(value)
        .map_err(|e| format!("Failed to serialize YAML config: {}", e))?;
    let body = normalize_xbp_yaml_environment_quotes(&yaml);
    Ok(ensure_xbp_yaml_schema_directive(&body))
}

/// Ensure the yaml-language-server `$schema` comment is present at the top of a project config.
pub fn ensure_xbp_yaml_schema_directive(yaml: &str) -> String {
    let trimmed = yaml.trim_start_matches('\u{feff}');
    if trimmed
        .lines()
        .take(8)
        .any(|line| line.contains("yaml-language-server") && line.contains("$schema"))
    {
        return yaml.to_string();
    }
    // Preserve a leading `---` document marker if present.
    if let Some(rest) = trimmed.strip_prefix("---") {
        let rest = rest.strip_prefix('\r').unwrap_or(rest);
        let rest = rest.strip_prefix('\n').unwrap_or(rest);
        return format!("---\n{XBP_PROJECT_YAML_SCHEMA_DIRECTIVE}{rest}");
    }
    format!("{XBP_PROJECT_YAML_SCHEMA_DIRECTIVE}{trimmed}")
}

fn normalize_xbp_yaml_environment_quotes(yaml: &str) -> String {
    let mut rendered = String::with_capacity(yaml.len());
    let mut environment_indent: Option<usize> = None;

    for raw_line in yaml.split_inclusive('\n') {
        let line = raw_line.strip_suffix('\n').unwrap_or(raw_line);
        let newline = if raw_line.ends_with('\n') { "\n" } else { "" };
        let indent = line
            .chars()
            .take_while(|character| *character == ' ')
            .count();

        if let Some(active_indent) = environment_indent {
            if !line.trim().is_empty() && indent <= active_indent {
                environment_indent = None;
            }
        }

        if line.trim() == "environment:" {
            environment_indent = Some(indent);
            rendered.push_str(line);
            rendered.push_str(newline);
            continue;
        }

        if let Some(active_indent) = environment_indent {
            if !line.trim().is_empty() && indent > active_indent {
                if let Some(rewritten) = rewrite_environment_scalar_line(line) {
                    rendered.push_str(&rewritten);
                    rendered.push_str(newline);
                    continue;
                }
            }
        }

        rendered.push_str(line);
        rendered.push_str(newline);
    }

    rendered
}

fn rewrite_environment_scalar_line(line: &str) -> Option<String> {
    let (prefix, raw_value) = line.split_once(':')?;
    let value_fragment = raw_value.trim_start();
    if value_fragment.is_empty() {
        return Some(format!("{prefix}: \"\""));
    }

    let parsed =
        serde_yaml::from_str::<serde_yaml::Value>(&format!("value: {value_fragment}\n")).ok()?;
    let value = match parsed {
        serde_yaml::Value::Mapping(mut mapping) => {
            mapping.remove(serde_yaml::Value::String("value".to_string()))?
        }
        _ => return None,
    };

    let text = match value {
        serde_yaml::Value::String(text) => text,
        serde_yaml::Value::Bool(value) => value.to_string(),
        serde_yaml::Value::Number(value) => value.to_string(),
        serde_yaml::Value::Null => String::new(),
        _ => return None,
    };

    Some(format!(
        "{prefix}: {}",
        render_yaml_environment_scalar(&text)
    ))
}

fn render_yaml_environment_scalar(value: &str) -> String {
    if value.is_empty() {
        return "\"\"".to_string();
    }

    let contains_control = value
        .chars()
        .any(|character| matches!(character, '\n' | '\r' | '\t') || character.is_control());

    if !contains_control && value.contains('"') {
        let escaped = value.replace('\'', "''");
        format!("'{escaped}'")
    } else {
        format!("\"{}\"", escape_yaml_double_quoted(value))
    }
}

fn escape_yaml_double_quoted(value: &str) -> String {
    let mut escaped = String::with_capacity(value.len());

    for character in value.chars() {
        match character {
            '\\' => escaped.push_str("\\\\"),
            '"' => escaped.push_str("\\\""),
            '\n' => escaped.push_str("\\n"),
            '\r' => escaped.push_str("\\r"),
            '\t' => escaped.push_str("\\t"),
            character if character.is_control() => {
                use std::fmt::Write as _;
                let _ = write!(&mut escaped, "\\u{:04x}", character as u32);
            }
            character => escaped.push(character),
        }
    }

    escaped
}

pub fn write_json_config_from_any_xbp_config(
    config_path: &Path,
    output_json_path: &Path,
) -> Result<(), String> {
    let content = fs::read_to_string(config_path)
        .map_err(|e| format!("Failed to read config {}: {}", config_path.display(), e))?;

    let kind = if config_path
        .extension()
        .and_then(|ext| ext.to_str())
        .map(|ext| ext.eq_ignore_ascii_case("yaml") || ext.eq_ignore_ascii_case("yml"))
        .unwrap_or(false)
    {
        "yaml"
    } else {
        "json"
    };

    let value = if kind == "yaml" {
        let (yaml_value, _) = parse_yaml_config_documents(&content)
            .map_err(|e| format!("Failed to parse YAML config: {}", e))?;
        serde_json::to_value(yaml_value)
            .map_err(|e| format!("Failed to convert YAML config to JSON value: {}", e))?
    } else {
        let stripped = strip_utf8_bom(&content);
        serde_json::from_str::<Value>(stripped)
            .map_err(|e| format!("Failed to parse JSON config: {}", e))?
    };

    if let Some(parent) = output_json_path.parent() {
        fs::create_dir_all(parent).map_err(|e| {
            format!(
                "Failed to create config directory {}: {}",
                parent.display(),
                e
            )
        })?;
    }

    let rendered = serde_json::to_string_pretty(&value)
        .map_err(|e| format!("Failed to serialize JSON config: {}", e))?;
    fs::write(output_json_path, rendered).map_err(|e| {
        format!(
            "Failed to write JSON config {}: {}",
            output_json_path.display(),
            e
        )
    })?;

    Ok(())
}

pub fn find_xbp_config_upwards(start_dir: &Path) -> Option<FoundXbpConfig> {
    for dir in start_dir.ancestors() {
        let candidates: [(PathBuf, &'static str); 6] = [
            (dir.join(".xbp").join("xbp.yaml"), "yaml"),
            (dir.join(".xbp").join("xbp.yml"), "yaml"),
            (dir.join(".xbp").join("xbp.json"), "json"),
            (dir.join("xbp.yaml"), "yaml"),
            (dir.join("xbp.yml"), "yaml"),
            (dir.join("xbp.json"), "json"),
        ];

        for (path, kind) in candidates {
            if !path.exists() {
                continue;
            }

            let project_root = path
                .parent()
                .and_then(|p| {
                    if p.file_name() == Some(std::ffi::OsStr::new(".xbp")) {
                        p.parent().map(|pp| pp.to_path_buf())
                    } else {
                        Some(p.to_path_buf())
                    }
                })
                .unwrap_or_else(|| dir.to_path_buf());

            let location = path
                .strip_prefix(&project_root)
                .ok()
                .map(|p| p.to_string_lossy().replace('\\', "/"))
                .unwrap_or_else(|| path.to_string_lossy().replace('\\', "/"));

            return Some(FoundXbpConfig {
                project_root,
                config_path: path,
                kind,
                location,
            });
        }
    }

    None
}

pub fn collect_known_xbp_projects() -> Vec<KnownXbpProject> {
    let mut projects = Vec::new();
    let mut seen_roots = HashSet::new();

    for project in find_all_xbp_projects() {
        let root = canonicalize_or_fallback(&project.path);
        if seen_roots.insert(root.clone()) {
            projects.push(KnownXbpProject {
                root,
                name: project.name,
            });
        }
    }

    if let Ok(current_dir) = std::env::current_dir() {
        if let Some(found) = find_xbp_config_upwards(&current_dir) {
            let root = canonicalize_or_fallback(&found.project_root);
            if seen_roots.insert(root.clone()) {
                let name = root
                    .file_name()
                    .and_then(|value| value.to_str())
                    .unwrap_or("current")
                    .to_string();
                projects.push(KnownXbpProject { root, name });
            }
        }
    }

    projects.sort_by(|left, right| {
        right
            .root
            .components()
            .count()
            .cmp(&left.root.components().count())
            .then_with(|| left.name.cmp(&right.name))
    });
    projects
}

pub fn resolve_xbp_project_for_path(
    candidate: &Path,
    known_projects: &[KnownXbpProject],
) -> Option<String> {
    if candidate.as_os_str().is_empty() {
        return None;
    }

    if let Some(found) = find_xbp_config_upwards(candidate) {
        let found_root = canonicalize_or_fallback(&found.project_root);
        if let Some(project) = known_projects
            .iter()
            .find(|project| canonicalize_or_fallback(&project.root) == found_root)
        {
            return Some(project.name.clone());
        }

        if known_projects.is_empty() {
            return found_root
                .file_name()
                .and_then(|value| value.to_str())
                .map(|value| value.to_string());
        }
    }

    let candidate_path = canonicalize_or_fallback(candidate);
    known_projects
        .iter()
        .find(|project| candidate_path.starts_with(canonicalize_or_fallback(&project.root)))
        .map(|project| project.name.clone())
}

pub fn collect_listening_port_ownership() -> Result<BTreeMap<u16, ListeningPortOwnership>, String> {
    use netstat2::{get_sockets_info, AddressFamilyFlags, ProtocolFlags, ProtocolSocketInfo};

    let af_flags = AddressFamilyFlags::IPV4 | AddressFamilyFlags::IPV6;
    let proto_flags = ProtocolFlags::TCP;
    let sockets = get_sockets_info(af_flags, proto_flags)
        .map_err(|e| format!("Failed to get sockets info: {}", e))?;

    let mut system = System::new_all();
    system.refresh_all();
    let known_projects = collect_known_xbp_projects();
    let mut pid_project_cache: HashMap<u32, Option<String>> = HashMap::new();
    let mut ports: BTreeMap<u16, ListeningPortOwnership> = BTreeMap::new();

    for socket in sockets {
        if let ProtocolSocketInfo::Tcp(tcp) = socket.protocol_socket_info {
            let state = format!("{:?}", tcp.state);
            if state != "Listen" && state != "LISTEN" {
                continue;
            }

            let row = ports.entry(tcp.local_port).or_default();
            for pid in socket.associated_pids {
                row.pids.push(pid);
                if let Some(project) = pid_project_cache
                    .entry(pid)
                    .or_insert_with(|| resolve_xbp_project_for_pid(pid, &system, &known_projects))
                    .clone()
                {
                    row.xbp_projects.push(project);
                }
            }
        }
    }

    for row in ports.values_mut() {
        row.pids.sort_unstable();
        row.pids.dedup();
        row.xbp_projects.sort();
        row.xbp_projects.dedup();
    }

    Ok(ports)
}

fn resolve_xbp_project_for_pid(
    pid: u32,
    system: &System,
    known_projects: &[KnownXbpProject],
) -> Option<String> {
    let process = system.process(Pid::from_u32(pid))?;

    if let Some(project) = process
        .cwd()
        .and_then(|path| resolve_xbp_project_for_path(path, known_projects))
    {
        return Some(project);
    }

    process
        .exe()
        .and_then(|path| path.parent())
        .and_then(|path| resolve_xbp_project_for_path(path, known_projects))
}

fn canonicalize_or_fallback(path: &Path) -> PathBuf {
    fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf())
}

pub fn expand_home_in_string(input: &str) -> String {
    let home = dirs::home_dir()
        .unwrap_or_else(|| std::path::PathBuf::from("."))
        .to_string_lossy()
        .to_string();

    if input == "~" {
        return home;
    }

    if let Some(rest) = input
        .strip_prefix("~/")
        .or_else(|| input.strip_prefix("~\\"))
    {
        return format!("{}{}{}", home, std::path::MAIN_SEPARATOR, rest);
    }

    if let Some(rest) = input
        .strip_prefix("$HOME/")
        .or_else(|| input.strip_prefix("$HOME\\"))
    {
        return format!("{}{}{}", home, std::path::MAIN_SEPARATOR, rest);
    }

    if let Some(rest) = input
        .strip_prefix("${HOME}/")
        .or_else(|| input.strip_prefix("${HOME}\\"))
    {
        return format!("{}{}{}", home, std::path::MAIN_SEPARATOR, rest);
    }

    input.to_string()
}

pub fn collapse_home_to_env(input: &str) -> String {
    let home = dirs::home_dir()
        .unwrap_or_else(|| std::path::PathBuf::from("."))
        .to_string_lossy()
        .to_string();

    if input == home {
        return "$HOME".to_string();
    }

    if let Some(rest) = input.strip_prefix(&(home.clone() + "/")) {
        return format!("$HOME/{}", rest);
    }

    if let Some(rest) = input.strip_prefix(&(home.clone() + "\\")) {
        return format!("$HOME\\{}", rest);
    }

    input.to_string()
}

pub fn cargo_program() -> PathBuf {
    std::env::var_os("CARGO")
        .map(PathBuf::from)
        .unwrap_or_else(|| PathBuf::from("cargo"))
}

pub fn cargo_command_exists() -> bool {
    let program = cargo_program();
    if program.is_absolute() {
        return program.is_file();
    }
    command_exists(program.to_string_lossy().as_ref())
}

pub fn command_exists(program: &str) -> bool {
    let Some(path_var) = std::env::var_os("PATH") else {
        return false;
    };

    for dir in std::env::split_paths(&path_var) {
        let candidate = dir.join(program);
        if candidate.is_file() {
            return true;
        }

        #[cfg(windows)]
        for ext in ["exe", "cmd", "bat"] {
            let candidate = dir.join(format!("{}.{}", program, ext));
            if candidate.is_file() {
                return true;
            }
        }
    }

    false
}

pub fn git_remote_url_from_metadata(
    project_root: &Path,
    remote: &str,
) -> Result<Option<String>, String> {
    let Some(git_dir) = resolve_git_dir(project_root)? else {
        return Ok(None);
    };

    let config_path = git_dir.join("config");
    if !config_path.exists() {
        return Ok(None);
    }

    let content = fs::read_to_string(&config_path)
        .map_err(|e| format!("Failed to read git config {}: {}", config_path.display(), e))?;

    Ok(parse_git_remote_url_from_config(&content, remote))
}

pub fn parse_github_repo_from_remote_url(url: &str) -> Option<(String, String)> {
    let normalized: &str = url.trim();

    let repo_path: String = if let Some(path) = normalized.strip_prefix("git@github.com:") {
        path.to_string()
    } else if let Some(path) = parse_github_https_repo_path(normalized) {
        path
    } else if let Some(path) = normalized.strip_prefix("ssh://git@github.com/") {
        path.to_string()
    } else {
        return None;
    };

    let cleaned: &str = repo_path.trim_end_matches('/').trim_end_matches(".git");
    let mut segments: std::str::Split<'_, char> = cleaned.split('/');
    let owner: &str = segments.next()?.trim();
    let repo: &str = segments.next()?.trim();
    if owner.is_empty() || repo.is_empty() || segments.next().is_some() {
        return None;
    }

    Some((owner.to_string(), repo.to_string()))
}

pub fn redact_remote_url_credentials(url: &str) -> String {
    if !url.contains('@') || !url.contains("://") {
        return url.to_string();
    }
    let mut parsed: reqwest::Url = match reqwest::Url::parse(url) {
        Ok(value) => value,
        Err(_) => return url.to_string(),
    };
    if parsed.password().is_some() {
        let _ = parsed.set_password(Some("REDACTED"));
    }
    if !parsed.username().is_empty() {
        let _ = parsed.set_username("REDACTED");
    }
    parsed.to_string()
}

fn resolve_git_dir(project_root: &Path) -> Result<Option<PathBuf>, String> {
    // Walk ancestors so package/subfolder project roots (e.g. monorepo packages with
    // their own `.xbp/xbp.yaml`) still resolve the enclosing repository's remotes.
    for dir in project_root.ancestors() {
        if let Some(git_dir) = resolve_git_dir_at(dir)? {
            return Ok(Some(git_dir));
        }
    }
    Ok(None)
}

fn resolve_git_dir_at(dir: &Path) -> Result<Option<PathBuf>, String> {
    let dot_git = dir.join(".git");
    if dot_git.is_dir() {
        return Ok(Some(dot_git));
    }

    if !dot_git.exists() {
        return Ok(None);
    }

    let content = fs::read_to_string(&dot_git)
        .map_err(|e| format!("Failed to read git metadata {}: {}", dot_git.display(), e))?;
    let git_dir = content
        .lines()
        .find_map(|line| line.trim().strip_prefix("gitdir:").map(str::trim))
        .filter(|value| !value.is_empty())
        .ok_or_else(|| format!("Failed to parse gitdir pointer from {}", dot_git.display()))?;

    let git_dir_path = PathBuf::from(git_dir);
    let resolved = if git_dir_path.is_absolute() {
        git_dir_path
    } else {
        dot_git.parent().unwrap_or(dir).join(git_dir_path)
    };

    Ok(Some(resolved))
}

fn parse_git_remote_url_from_config(content: &str, remote: &str) -> Option<String> {
    let expected_quoted = format!(r#"remote "{}""#, remote);
    let expected_dotted = format!("remote.{}", remote);
    let mut in_target_section = false;

    for line in content.lines() {
        let trimmed = line.trim();
        if trimmed.is_empty() || trimmed.starts_with('#') || trimmed.starts_with(';') {
            continue;
        }

        if trimmed.starts_with('[') && trimmed.ends_with(']') {
            let section = trimmed.trim_start_matches('[').trim_end_matches(']').trim();
            in_target_section = section.eq_ignore_ascii_case(&expected_quoted)
                || section.eq_ignore_ascii_case(&expected_dotted);
            continue;
        }

        if !in_target_section {
            continue;
        }

        let Some((key, value)) = trimmed.split_once('=') else {
            continue;
        };
        if key.trim().eq_ignore_ascii_case("url") {
            let value = value.trim();
            if !value.is_empty() {
                return Some(value.to_string());
            }
        }
    }

    None
}

fn parse_github_https_repo_path(url: &str) -> Option<String> {
    let parsed: reqwest::Url = reqwest::Url::parse(url).ok()?;
    if !matches!(parsed.scheme(), "http" | "https") {
        return None;
    }
    if parsed.host_str()?.eq_ignore_ascii_case("github.com") {
        return Some(parsed.path().trim_start_matches('/').to_string());
    }
    None
}

pub fn first_available_command(candidates: &[&str]) -> Option<String> {
    candidates
        .iter()
        .find(|candidate| command_exists(candidate))
        .map(|candidate| (*candidate).to_string())
}

pub fn preferred_python_command() -> String {
    first_available_command(&["python3", "python"]).unwrap_or_else(|| {
        if cfg!(target_os = "windows") {
            "python".to_string()
        } else {
            "python3".to_string()
        }
    })
}

pub fn preferred_pip_command() -> String {
    first_available_command(&["pip3", "pip"]).unwrap_or_else(|| {
        if cfg!(target_os = "windows") {
            "pip".to_string()
        } else {
            "pip3".to_string()
        }
    })
}

pub fn open_with_default_handler(target: &str) -> Result<(), String> {
    let mut command = if cfg!(target_os = "windows") {
        let mut cmd = Command::new("cmd");
        cmd.arg("/C").arg("start").arg("").arg(target);
        cmd
    } else if cfg!(target_os = "macos") {
        let mut cmd = Command::new("open");
        cmd.arg(target);
        cmd
    } else {
        let mut cmd = Command::new("xdg-open");
        cmd.arg(target);
        cmd
    };

    command
        .spawn()
        .map_err(|e| format!("Failed to open '{}': {}", target, e))?;
    Ok(())
}

pub fn open_path_with_editor(path: &Path) -> Result<(), String> {
    if let Ok(editor) = std::env::var("EDITOR") {
        let mut parts = editor.split_whitespace();
        let binary = parts
            .next()
            .ok_or_else(|| "EDITOR is set but empty".to_string())?;
        let mut command = Command::new(binary);
        for part in parts {
            command.arg(part);
        }
        command
            .arg(path)
            .spawn()
            .map_err(|e| format!("Failed to launch editor '{}': {}", editor, e))?;
        return Ok(());
    }

    open_with_default_handler(&path.display().to_string())
}

/// Metadata about structural YAML/JSON fixes applied before field-level auto-heal.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
struct ConfigParseNormalizeMeta {
    /// Leading UTF-8 BOM was present and stripped.
    had_bom: bool,
    /// File contained more than one YAML document; documents were merged.
    multi_document: bool,
    /// Duplicate top-level keys were dropped (later nulls lose to earlier values).
    duplicate_top_level_keys: bool,
}

impl ConfigParseNormalizeMeta {
    fn needs_rewrite(&self) -> bool {
        self.had_bom || self.multi_document || self.duplicate_top_level_keys
    }
}

/// Drop later top-level keys that would make `serde_yaml` fail with
/// `duplicate entry with key "…"`. Keeps the first occurrence of each key.
///
/// Large monorepo configs sometimes end up with a second `openapi: null` (or
/// similar) after the services list when generators append fields at the wrong
/// indent level.
fn dedupe_yaml_top_level_keys(content: &str) -> (String, bool) {
    let mut output = String::with_capacity(content.len());
    let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
    let mut skipping_duplicate_block = false;
    let mut changed = false;

    for raw_line in content.split_inclusive('\n') {
        let line = raw_line.strip_suffix('\n').unwrap_or(raw_line);
        let newline = if raw_line.ends_with('\n') { "\n" } else { "" };
        let trimmed = line.trim_start();
        let indent = line.len().saturating_sub(trimmed.len());

        // Document separators reset key tracking within multi-doc streams.
        if trimmed == "---" || trimmed.starts_with("--- ") {
            skipping_duplicate_block = false;
            seen.clear();
            output.push_str(line);
            output.push_str(newline);
            continue;
        }

        if indent == 0 && !trimmed.is_empty() && !trimmed.starts_with('#') {
            // Top-level mapping key: `key:` or `key: value`
            if let Some(key) = top_level_yaml_key(trimmed) {
                if !seen.insert(key) {
                    // Skip this key and any nested indented block that follows.
                    skipping_duplicate_block = true;
                    changed = true;
                    continue;
                }
                skipping_duplicate_block = false;
            } else {
                // Top-level list item or scalar — stop skipping.
                skipping_duplicate_block = false;
            }
        } else if skipping_duplicate_block {
            // Nested content of a dropped duplicate key.
            if indent > 0 || trimmed.is_empty() || trimmed.starts_with('#') {
                changed = true;
                continue;
            }
            skipping_duplicate_block = false;
        }

        if skipping_duplicate_block {
            changed = true;
            continue;
        }

        output.push_str(line);
        output.push_str(newline);
    }

    (output, changed)
}

fn top_level_yaml_key(trimmed_line: &str) -> Option<String> {
    if trimmed_line.starts_with('-') {
        return None;
    }
    let without_comment = trimmed_line
        .split_once(" #")
        .map(|(left, _)| left)
        .unwrap_or(trimmed_line)
        .trim_end();
    let (key, rest) = without_comment.split_once(':')?;
    let key = key.trim();
    if key.is_empty() || key.contains(' ') || key.contains('\t') {
        return None;
    }
    // `http://...` style bare strings are not keys.
    if rest.starts_with("//") {
        return None;
    }
    Some(key.to_string())
}

/// Parse YAML that may include a UTF-8 BOM and/or multiple documents.
///
/// Windows editors often write a BOM; `serde_yaml::from_str` then fails with
/// "deserializing from YAML containing more than one document is not supported".
/// Multi-document streams (split by `---`) are deep-merged into one mapping so
/// legacy/split configs still load. Callers rewrite a single clean document.
/// Duplicate top-level keys are dropped (first wins) so monorepo configs with a
/// stray trailing `openapi: null` still load.
fn parse_yaml_config_documents(
    content: &str,
) -> Result<(serde_yaml::Value, ConfigParseNormalizeMeta), String> {
    let had_bom = content.starts_with('\u{feff}');
    let stripped = strip_utf8_bom(content);
    let (deduped, duplicate_top_level_keys) = dedupe_yaml_top_level_keys(stripped);
    let stripped = deduped.as_str();

    let mut documents = Vec::new();
    for document in serde_yaml::Deserializer::from_str(stripped) {
        let value = serde_yaml::Value::deserialize(document).map_err(|e| e.to_string())?;
        // Skip empty documents that appear between `---` separators.
        if !matches!(value, serde_yaml::Value::Null) {
            documents.push(value);
        }
    }

    if documents.is_empty() {
        return Ok((
            serde_yaml::Value::Mapping(serde_yaml::Mapping::new()),
            ConfigParseNormalizeMeta {
                had_bom,
                multi_document: false,
                duplicate_top_level_keys,
            },
        ));
    }

    let multi_document = documents.len() > 1;
    let merged = if multi_document {
        merge_yaml_values(documents)
    } else {
        documents
            .into_iter()
            .next()
            .unwrap_or(serde_yaml::Value::Null)
    };

    Ok((
        merged,
        ConfigParseNormalizeMeta {
            had_bom,
            multi_document,
            duplicate_top_level_keys,
        },
    ))
}

fn merge_yaml_values(documents: Vec<serde_yaml::Value>) -> serde_yaml::Value {
    let mut merged = serde_yaml::Value::Mapping(serde_yaml::Mapping::new());
    for document in documents {
        deep_merge_yaml(&mut merged, document);
    }
    merged
}

/// Deep-merge `incoming` into `base`. Mappings merge recursively; sequences and
/// scalars from later documents replace earlier values.
fn deep_merge_yaml(base: &mut serde_yaml::Value, incoming: serde_yaml::Value) {
    match (base, incoming) {
        (serde_yaml::Value::Mapping(base_map), serde_yaml::Value::Mapping(incoming_map)) => {
            for (key, value) in incoming_map {
                match base_map.get_mut(&key) {
                    Some(existing) => deep_merge_yaml(existing, value),
                    None => {
                        base_map.insert(key, value);
                    }
                }
            }
        }
        (base_slot, incoming) => {
            *base_slot = incoming;
        }
    }
}

pub fn parse_config_with_auto_heal<T: DeserializeOwned>(
    content: &str,
    kind: &str,
) -> Result<(T, Option<String>), String> {
    let (mut value, structural_heal) = match kind {
        "yaml" => {
            let (yaml_value, meta) = parse_yaml_config_documents(content)?;
            let json = serde_json::to_value(yaml_value).map_err(|e| e.to_string())?;
            (json, meta.needs_rewrite())
        }
        "json" => {
            let had_bom = content.starts_with('\u{feff}');
            let stripped = strip_utf8_bom(content);
            let json = serde_json::from_str::<Value>(stripped).map_err(|e| e.to_string())?;
            (json, had_bom)
        }
        _ => return Err(format!("Unsupported config kind: {}", kind)),
    };

    let field_healed = auto_heal_xbp_config_value(&mut value);
    let healed = field_healed || structural_heal;
    let parsed = serde_json::from_value::<T>(value.clone()).map_err(|e| e.to_string())?;

    let healed_content = if healed {
        Some(match kind {
            "yaml" => serialize_xbp_yaml(&value)?,
            "json" => serde_json::to_string_pretty(&value).map_err(|e| e.to_string())?,
            _ => unreachable!(),
        })
    } else {
        None
    };

    Ok((parsed, healed_content))
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct XbpConfigHealResult {
    pub config_path: PathBuf,
    pub fixes: Vec<String>,
}

pub fn detect_xbp_config_heal_opportunities(content: &str) -> Vec<String> {
    let mut fixes = Vec::new();

    if content.starts_with('\u{feff}') {
        fixes.push("strip leading UTF-8 BOM".to_string());
    }

    let stripped = strip_utf8_bom(content);
    // Count non-empty YAML documents; multi-doc streams are collapsed on load.
    if content_looks_like_yaml_multidoc(stripped) {
        fixes.push("collapse multi-document YAML into a single document".to_string());
    }

    for line in content.lines() {
        let trimmed = line.trim();
        if !trimmed.starts_with("systemd:") {
            continue;
        }
        let value = trimmed.trim_start_matches("systemd:").trim();
        if value.is_empty() || value == "null" || value.starts_with('{') {
            continue;
        }
        let normalized = value.trim_matches('"').trim_matches('\'');
        fixes.push(format!(
            "normalize `systemd: {normalized}` to `systemd_service_name`"
        ));
    }

    fixes.sort();
    fixes.dedup();
    fixes
}

fn content_looks_like_yaml_multidoc(content: &str) -> bool {
    let mut document_count = 0usize;
    for document in serde_yaml::Deserializer::from_str(content) {
        match serde_yaml::Value::deserialize(document) {
            Ok(serde_yaml::Value::Null) => {}
            Ok(_) => {
                document_count += 1;
                if document_count > 1 {
                    return true;
                }
            }
            Err(_) => return false,
        }
    }
    false
}

pub fn heal_project_xbp_config(start_dir: &Path) -> Result<Option<XbpConfigHealResult>, String> {
    let found = match find_xbp_config_upwards(start_dir) {
        Some(found) => found,
        None => return Ok(None),
    };

    let content = fs::read_to_string(&found.config_path)
        .map_err(|e| format!("Failed to read {}: {}", found.config_path.display(), e))?;
    let fixes = detect_xbp_config_heal_opportunities(&content);
    let healed = heal_config_file(&found.config_path, found.kind)?;

    if !healed && fixes.is_empty() {
        return Ok(None);
    }

    Ok(Some(XbpConfigHealResult {
        config_path: found.config_path,
        fixes: if fixes.is_empty() {
            vec!["normalized legacy config fields".to_string()]
        } else {
            fixes
        },
    }))
}

pub fn heal_config_file(path: &Path, kind: &str) -> Result<bool, String> {
    let content = fs::read_to_string(path)
        .map_err(|e| format!("Failed to read {}: {}", path.display(), e))?;
    let (_, healed_content) = parse_config_with_auto_heal::<Value>(&content, kind)?;

    if let Some(healed_content) = healed_content {
        fs::write(path, healed_content)
            .map_err(|e| format!("Failed to write healed config {}: {}", path.display(), e))?;
        return Ok(true);
    }

    Ok(false)
}

pub(crate) fn normalize_xbp_config_value(value: &mut Value) -> bool {
    auto_heal_xbp_config_value(value)
}

fn auto_heal_xbp_config_value(value: &mut Value) -> bool {
    let Some(root) = value.as_object_mut() else {
        return false;
    };

    let mut changed = false;

    if let Some(environment) = root.get_mut("environment") {
        changed |= normalize_environment_value(environment);
    }

    changed |= normalize_systemd_shorthand(root);

    if let Some(services) = root.get_mut("services").and_then(Value::as_array_mut) {
        for service in services {
            let Some(service) = service.as_object_mut() else {
                continue;
            };

            if let Some(environment) = service.get_mut("environment") {
                changed |= normalize_environment_value(environment);
            }

            changed |= normalize_systemd_shorthand(service);
        }
    }

    changed
}

fn normalize_systemd_shorthand(map: &mut Map<String, Value>) -> bool {
    let Some(systemd) = map.get("systemd") else {
        return false;
    };

    let Value::String(service_name) = systemd else {
        return false;
    };

    let systemd_service_name_missing = map
        .get("systemd_service_name")
        .map(|value| value.is_null())
        .unwrap_or(true);

    if systemd_service_name_missing && !service_name.is_empty() {
        map.insert(
            "systemd_service_name".to_string(),
            Value::String(service_name.clone()),
        );
    }

    map.remove("systemd");
    true
}

fn normalize_environment_value(value: &mut Value) -> bool {
    let Value::Object(map) = value else {
        return false;
    };

    let original = map.clone();
    let mut normalized = Map::new();
    let mut changed = false;

    flatten_environment_entries(&original, &mut normalized, &mut changed);

    if normalized != original {
        *map = normalized;
        changed = true;
    }

    changed
}

fn flatten_environment_entries(
    source: &Map<String, Value>,
    target: &mut Map<String, Value>,
    changed: &mut bool,
) {
    for (key, value) in source {
        match value {
            Value::String(string) => {
                target.insert(key.clone(), Value::String(string.clone()));
            }
            Value::Number(number) => {
                *changed = true;
                target.insert(key.clone(), Value::String(number.to_string()));
            }
            Value::Bool(boolean) => {
                *changed = true;
                target.insert(key.clone(), Value::String(boolean.to_string()));
            }
            Value::Null => {
                *changed = true;
                target.insert(key.clone(), Value::String(String::new()));
            }
            Value::Array(items) => {
                *changed = true;
                let serialized = serde_json::to_string(items).unwrap_or_else(|_| "[]".to_string());
                target.insert(key.clone(), Value::String(serialized));
            }
            Value::Object(nested) => {
                *changed = true;
                flatten_environment_entries(nested, target, changed);
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{
        command_exists, detect_xbp_config_heal_opportunities, first_available_command,
        git_remote_url_from_metadata, maybe_auto_convert_legacy_xbp_json_to_yaml,
        parse_config_with_auto_heal, parse_github_repo_from_remote_url, preferred_pip_command,
        preferred_python_command, redact_remote_url_credentials, resolve_xbp_project_for_path,
        write_json_config_from_any_xbp_config, KnownXbpProject,
    };
    use crate::strategies::XbpConfig;
    use std::fs;
    use std::path::PathBuf;
    use std::sync::{Mutex, OnceLock};

    fn path_lock() -> &'static Mutex<()> {
        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
        LOCK.get_or_init(|| Mutex::new(()))
    }

    fn make_temp_path(name: &str) -> PathBuf {
        let mut path = std::env::temp_dir();
        path.push(format!("xbp-test-{}-{}", name, std::process::id()));
        path
    }

    fn with_path<F>(entries: &[PathBuf], test: F)
    where
        F: FnOnce(),
    {
        let _guard = path_lock().lock().expect("path lock should be available");
        let original = std::env::var_os("PATH");
        let joined = std::env::join_paths(entries).expect("PATH entries should join");
        std::env::set_var("PATH", joined);
        test();
        match original {
            Some(path) => std::env::set_var("PATH", path),
            None => std::env::remove_var("PATH"),
        }
    }

    #[test]
    fn parses_yaml_with_leading_utf8_bom_and_rewrites_clean_file() {
        // serde_yaml::from_str fails on BOM with a misleading multi-document error.
        let yaml = "\u{feff}project_name: demo\nport: 3000\nbuild_dir: $HOME/demo\n";

        let (config, healed_content) =
            parse_config_with_auto_heal::<XbpConfig>(yaml, "yaml").expect("BOM yaml should parse");

        assert_eq!(config.project_name, "demo");
        assert_eq!(config.port, 3000);
        let healed = healed_content.expect("BOM should trigger autonomous rewrite");
        assert!(
            !healed.starts_with('\u{feff}'),
            "healed yaml must not retain BOM"
        );
        assert!(healed.contains("project_name: demo"));
    }

    #[test]
    fn drops_duplicate_top_level_openapi_null_and_keeps_first_block() {
        let yaml = r#"
project_name: athena
version: 1.0.0
port: 4052
build_dir: ./
openapi:
  enabled: true
  auto_detect_services: false
services:
  - name: athena
    target: rust
    branch: main
    port: 4052
    openapi: null
openapi: null
workers:
  - name: athena-auth
    root: services/athena-auth
"#;

        let (config, healed_content) = parse_config_with_auto_heal::<XbpConfig>(yaml, "yaml")
            .expect("duplicate openapi key should be healed");
        assert_eq!(config.project_name, "athena");
        assert_eq!(
            config.openapi.as_ref().and_then(|o| o.enabled),
            Some(true)
        );
        assert!(config.workers.is_some());
        let healed = healed_content.expect("duplicate key should trigger rewrite");
        let top_level_openapi_lines = healed
            .lines()
            .filter(|line| line.starts_with("openapi:"))
            .count();
        assert_eq!(
            top_level_openapi_lines, 1,
            "healed yaml should keep a single top-level openapi block: {healed}"
        );
        assert!(
            !healed.contains("\nopenapi: null\n") && !healed.ends_with("openapi: null"),
            "stray top-level openapi: null must be dropped: {healed}"
        );
    }

    #[test]
    fn merges_multi_document_yaml_and_rewrites_single_document() {
        let yaml = r#"
project_name: demo
port: 3000
build_dir: $HOME/demo
---
environment:
  LOG_LEVEL: info
---
services:
  - name: api
    target: rust
    branch: main
    port: 3001
"#;

        let (config, healed_content) = parse_config_with_auto_heal::<XbpConfig>(yaml, "yaml")
            .expect("multi-document yaml should merge");

        assert_eq!(config.project_name, "demo");
        assert_eq!(config.port, 3000);
        let environment = config.environment.expect("merged environment should exist");
        assert_eq!(environment.get("LOG_LEVEL"), Some(&"info".to_string()));
        let services = config.services.expect("merged services should exist");
        assert_eq!(services.len(), 1);
        assert_eq!(services[0].name, "api");

        let healed = healed_content.expect("multi-doc should trigger rewrite");
        assert!(
            !healed.lines().any(|line| line.trim() == "---"),
            "healed yaml should be a single document"
        );
        assert!(healed.contains("project_name: demo"));
        assert!(healed.contains("LOG_LEVEL"));
        assert!(healed.contains("name: api"));
    }

    #[test]
    fn parses_bom_prefixed_multi_document_yaml() {
        let yaml = "\u{feff}project_name: demo\nport: 3000\nbuild_dir: ./\n---\nversion: 1.2.3\n";

        let (config, healed_content) = parse_config_with_auto_heal::<XbpConfig>(yaml, "yaml")
            .expect("BOM + multi-doc yaml should parse");

        assert_eq!(config.project_name, "demo");
        assert_eq!(config.version, "1.2.3");
        assert!(healed_content.is_some());
    }

    #[test]
    fn ensure_xbp_yaml_schema_directive_is_idempotent() {
        let bare = "project_name: demo\nport: 3000\nbuild_dir: .\n";
        let once = super::ensure_xbp_yaml_schema_directive(bare);
        assert!(once.starts_with("# yaml-language-server: $schema="));
        assert!(once.contains("project_name: demo"));
        let twice = super::ensure_xbp_yaml_schema_directive(&once);
        assert_eq!(
            once.matches("yaml-language-server").count(),
            1,
            "should not duplicate schema directive"
        );
        assert_eq!(twice, once);

        let with_doc = "---\nproject_name: demo\n";
        let headed = super::ensure_xbp_yaml_schema_directive(with_doc);
        assert!(headed.starts_with("---\n# yaml-language-server:"));
    }

    #[test]
    fn detect_heal_opportunities_reports_bom_and_multidoc() {
        let yaml = "\u{feff}project_name: demo\n---\nsystemd: athena.service\n";
        let fixes = detect_xbp_config_heal_opportunities(yaml);
        assert!(
            fixes.iter().any(|fix| fix.contains("UTF-8 BOM")),
            "expected BOM fix, got {fixes:?}"
        );
        assert!(
            fixes.iter().any(|fix| fix.contains("multi-document")),
            "expected multi-doc fix, got {fixes:?}"
        );
        assert!(
            fixes.iter().any(|fix| fix.contains("systemd")),
            "expected systemd fix, got {fixes:?}"
        );
    }

    #[test]
    fn heal_config_file_strips_bom_on_disk() {
        let project_root = make_temp_path("heal-bom-yaml");
        fs::create_dir_all(project_root.join(".xbp")).expect("xbp dir should be created");
        let yaml_path = project_root.join(".xbp").join("xbp.yaml");
        fs::write(
            &yaml_path,
            "\u{feff}project_name: demo\nport: 3000\nbuild_dir: $HOME/demo\n",
        )
        .expect("yaml should be written with BOM");

        let healed = super::heal_config_file(&yaml_path, "yaml").expect("heal should succeed");
        assert!(healed, "BOM config should be rewritten");

        let rewritten = fs::read_to_string(&yaml_path).expect("healed yaml should be readable");
        assert!(
            !rewritten.starts_with('\u{feff}'),
            "rewritten file must not start with BOM"
        );
        assert!(rewritten.contains("project_name: demo"));

        // Second pass is a no-op once the file is clean (unless field heals apply).
        let (config, second_heal) =
            parse_config_with_auto_heal::<XbpConfig>(&rewritten, "yaml").expect("reparse");
        assert_eq!(config.project_name, "demo");
        // Environment/systemd heals may not apply; structural heal should be false.
        // Field heals are also false for this minimal fixture.
        assert!(second_heal.is_none());

        fs::remove_dir_all(project_root).expect("temp project should be removed");
    }

    #[test]
    fn heals_nested_yaml_environment_blocks() {
        let yaml = r#"
project_name: demo
port: 3000
build_dir: $HOME/demo
environment:
  production:
    DATABASE_URL: postgres://localhost/demo
    LOG_LEVEL: info
services:
  - name: api
    target: rust
    branch: main
    port: 3001
    environment:
      production:
        SERVICE_TOKEN: abc123
"#;

        let (config, healed_content) =
            parse_config_with_auto_heal::<XbpConfig>(yaml, "yaml").expect("config should heal");

        let environment = config.environment.expect("top-level env should exist");
        assert_eq!(
            environment.get("DATABASE_URL"),
            Some(&"postgres://localhost/demo".to_string())
        );
        assert_eq!(environment.get("LOG_LEVEL"), Some(&"info".to_string()));

        let service_environment = config.services.expect("services should exist")[0]
            .environment
            .clone()
            .expect("service env should exist");
        assert_eq!(
            service_environment.get("SERVICE_TOKEN"),
            Some(&"abc123".to_string())
        );
        assert!(healed_content.is_some());
    }

    #[test]
    fn detect_xbp_config_heal_opportunities_finds_systemd_shorthand() {
        let yaml = r#"
services:
  - name: api
    systemd: athena.service
    systemd_service_name: athena
"#;
        let fixes = detect_xbp_config_heal_opportunities(yaml);
        assert_eq!(fixes.len(), 1);
        assert!(fixes[0].contains("athena.service"));
    }

    #[test]
    fn heals_systemd_string_shorthand_in_yaml() {
        let yaml = r#"
project_name: athena
port: 3000
build_dir: $HOME/athena
systemd: athena.service
services:
  - name: api
    target: rust
    branch: main
    port: 3001
    systemd: athena-api.service
"#;

        let (config, healed_content) =
            parse_config_with_auto_heal::<XbpConfig>(yaml, "yaml").expect("config should heal");

        assert_eq!(
            config.systemd_service_name.as_deref(),
            Some("athena.service")
        );
        assert!(config.systemd.is_none());

        let service = &config.services.expect("services should exist")[0];
        assert_eq!(
            service.systemd_service_name.as_deref(),
            Some("athena-api.service")
        );
        assert!(service.systemd.is_none());
        assert!(healed_content.is_some());
        assert!(!healed_content
            .expect("healed content should exist")
            .contains("systemd: athena"));
    }

    #[test]
    fn heals_systemd_string_shorthand_without_overwriting_existing_service_name() {
        let yaml = r#"
project_name: athena
port: 4052
build_dir: $HOME/athena
services:
  - name: athena-gateway
    target: rust
    branch: main
    port: 4052
    systemd: athena.service
    systemd_service_name: athena
"#;

        let (config, healed_content) =
            parse_config_with_auto_heal::<XbpConfig>(yaml, "yaml").expect("config should heal");

        let service = &config.services.expect("services should exist")[0];
        assert_eq!(service.systemd_service_name.as_deref(), Some("athena"));
        assert!(service.systemd.is_none());
        assert!(healed_content.is_some());
    }

    #[test]
    fn heals_non_string_environment_values_in_json() {
        let json = r#"{
  "project_name": "demo",
  "port": 3000,
  "build_dir": "$HOME/demo",
  "environment": {
    "PORT": 3000,
    "DEBUG": true,
    "EMPTY": null
  }
}"#;

        let (config, healed_content) =
            parse_config_with_auto_heal::<XbpConfig>(json, "json").expect("config should heal");

        let environment = config.environment.expect("top-level env should exist");
        assert_eq!(environment.get("PORT"), Some(&"3000".to_string()));
        assert_eq!(environment.get("DEBUG"), Some(&"true".to_string()));
        assert_eq!(environment.get("EMPTY"), Some(&String::new()));
        assert!(healed_content.is_some());
    }

    #[test]
    fn command_helpers_respect_path_order() {
        let bin_dir = make_temp_path("bin");
        fs::create_dir_all(&bin_dir).expect("temp dir should be created");
        fs::write(bin_dir.join("python"), b"").expect("python file should be created");
        fs::write(bin_dir.join("pip"), b"").expect("pip file should be created");

        with_path(std::slice::from_ref(&bin_dir), || {
            assert!(command_exists("python"));
            assert_eq!(
                first_available_command(&["python3", "python"]),
                Some("python".to_string())
            );
            assert_eq!(preferred_python_command(), "python".to_string());
            assert_eq!(preferred_pip_command(), "pip".to_string());
        });

        fs::remove_dir_all(&bin_dir).expect("temp dir should be removed");
    }

    #[test]
    fn resolves_xbp_project_for_nested_paths() {
        let project_root = make_temp_path("ownership");
        let service_dir = project_root.join("services").join("api");
        fs::create_dir_all(project_root.join(".xbp")).expect("xbp dir should be created");
        fs::create_dir_all(&service_dir).expect("service dir should be created");
        fs::write(
            project_root.join(".xbp").join("xbp.json"),
            br#"{"project_name":"demo"}"#,
        )
        .expect("xbp config should be written");

        let known_projects = vec![KnownXbpProject {
            root: project_root.clone(),
            name: "demo".to_string(),
        }];

        assert_eq!(
            resolve_xbp_project_for_path(&service_dir, &known_projects),
            Some("demo".to_string())
        );

        fs::remove_dir_all(&project_root).expect("temp project should be removed");
    }

    #[test]
    fn ignores_non_xbp_paths_for_project_resolution() {
        let project_root = make_temp_path("ownership-miss");
        let other_dir = make_temp_path("ownership-other");
        fs::create_dir_all(project_root.join(".xbp")).expect("xbp dir should be created");
        fs::create_dir_all(&other_dir).expect("other dir should be created");
        fs::write(
            project_root.join(".xbp").join("xbp.json"),
            br#"{"project_name":"demo"}"#,
        )
        .expect("xbp config should be written");

        let known_projects = vec![KnownXbpProject {
            root: project_root.clone(),
            name: "demo".to_string(),
        }];

        assert_eq!(
            resolve_xbp_project_for_path(&other_dir, &known_projects),
            None
        );

        fs::remove_dir_all(&project_root).expect("temp project should be removed");
        fs::remove_dir_all(&other_dir).expect("temp other dir should be removed");
    }

    #[test]
    fn auto_converts_legacy_json_to_yaml() {
        let project_root = make_temp_path("json-to-yaml");
        fs::create_dir_all(project_root.join(".xbp")).expect("xbp dir should be created");
        let json_path = project_root.join(".xbp").join("xbp.json");
        fs::write(
            &json_path,
            br#"{"project_name":"demo","port":3000,"build_dir":"$HOME/demo"}"#,
        )
        .expect("json should be written");

        let output = maybe_auto_convert_legacy_xbp_json_to_yaml(&project_root, &json_path)
            .expect("conversion should succeed")
            .expect("yaml path should be returned");
        assert!(output.exists(), "converted yaml should exist");

        let yaml = fs::read_to_string(output).expect("yaml should be readable");
        assert!(yaml.contains("project_name: demo"));

        fs::remove_dir_all(project_root).expect("temp project should be removed");
    }

    #[test]
    fn normalizes_environment_quotes_in_yaml_output() {
        let yaml = super::normalize_xbp_yaml_environment_quotes(
            r#"project_name: demo
port: 3000
build_dir: ./
environment:
  API_PATH: /api/auth
  WITH_DOUBLE: 'look "here"'
  WITH_SINGLE: "can't fail"
services:
  - name: api
    target: rust
    branch: main
    port: 3001
    environment:
      CALLBACK_PATH: /api/auth/callback
      CALLBACK_TITLE: "the 'quoted' callback"
"#,
        );

        assert!(yaml.contains("API_PATH: \"/api/auth\""));
        assert!(yaml.contains("WITH_DOUBLE: 'look \"here\"'"));
        assert!(yaml.contains("WITH_SINGLE: \"can't fail\""));
        assert!(yaml.contains("CALLBACK_PATH: \"/api/auth/callback\""));
        assert!(yaml.contains("CALLBACK_TITLE: \"the 'quoted' callback\""));
    }

    #[test]
    fn writes_json_from_yaml_config() {
        let project_root = make_temp_path("yaml-to-json");
        fs::create_dir_all(project_root.join(".xbp")).expect("xbp dir should be created");
        let yaml_path = project_root.join(".xbp").join("xbp.yaml");
        let json_out = project_root.join("xbp.json");
        fs::write(
            &yaml_path,
            "project_name: demo\nport: 3000\nbuild_dir: $HOME/demo\n",
        )
        .expect("yaml should be written");

        write_json_config_from_any_xbp_config(&yaml_path, &json_out)
            .expect("json should be generated from yaml");

        let json = fs::read_to_string(json_out).expect("json should be readable");
        assert!(json.contains("\"project_name\": \"demo\""));

        fs::remove_dir_all(project_root).expect("temp project should be removed");
    }

    #[test]
    fn parses_github_repo_from_supported_remote_urls() {
        assert_eq!(
            parse_github_repo_from_remote_url("https://github.com/xylex-group/xbp.git"),
            Some(("xylex-group".to_string(), "xbp".to_string()))
        );
        assert_eq!(
            parse_github_repo_from_remote_url("git@github.com:xylex-group/xbp.git"),
            Some(("xylex-group".to_string(), "xbp".to_string()))
        );
        assert_eq!(
            parse_github_repo_from_remote_url("ssh://git@github.com/xylex-group/xbp"),
            Some(("xylex-group".to_string(), "xbp".to_string()))
        );
        assert_eq!(
            parse_github_repo_from_remote_url("https://gitlab.com/xylex-group/xbp.git"),
            None
        );
        assert_eq!(
            parse_github_repo_from_remote_url("https://github.com/xylex-group/xbp/extra.git"),
            None
        );
    }

    #[test]
    fn redacts_credentials_in_remote_urls() {
        let redacted = redact_remote_url_credentials("https://token@example.com/xylex-group/xbp");
        assert!(redacted.contains("REDACTED"));
        assert!(!redacted.contains("token@example.com"));
    }

    #[test]
    fn reads_origin_remote_url_from_git_config_directory() {
        let project_root = make_temp_path("git-config-dir");
        let git_dir = project_root.join(".git");
        fs::create_dir_all(&git_dir).expect("git dir should be created");
        fs::write(
            git_dir.join("config"),
            "[remote \"origin\"]\n\turl = https://github.com/xylex-group/xbp.git\n",
        )
        .expect("git config should be written");

        let remote = git_remote_url_from_metadata(&project_root, "origin")
            .expect("git metadata should parse")
            .expect("origin remote should exist");
        assert_eq!(remote, "https://github.com/xylex-group/xbp.git");

        fs::remove_dir_all(project_root).expect("temp project should be removed");
    }

    #[test]
    fn reads_origin_remote_url_from_gitdir_pointer() {
        let project_root = make_temp_path("git-config-file");
        let nested_git_dir = project_root.join(".git-real");
        fs::create_dir_all(&nested_git_dir).expect("gitdir target should be created");
        fs::write(project_root.join(".git"), "gitdir: .git-real\n")
            .expect("gitdir pointer should be written");
        fs::write(
            nested_git_dir.join("config"),
            "[remote \"origin\"]\n\turl = git@github.com:xylex-group/xbp.git\n",
        )
        .expect("git config should be written");

        let remote = git_remote_url_from_metadata(&project_root, "origin")
            .expect("git metadata should parse")
            .expect("origin remote should exist");
        assert_eq!(remote, "git@github.com:xylex-group/xbp.git");

        fs::remove_dir_all(project_root).expect("temp project should be removed");
    }

    #[test]
    fn reads_origin_remote_url_from_ancestor_git_dir() {
        // Monorepo package with its own project root, no local .git — walk up.
        let repo_root = make_temp_path("git-ancestor-repo");
        let package_root = repo_root.join("packages").join("athena-auth-ui");
        fs::create_dir_all(&package_root).expect("package dir should be created");
        let git_dir = repo_root.join(".git");
        fs::create_dir_all(&git_dir).expect("git dir should be created");
        fs::write(
            git_dir.join("config"),
            "[remote \"origin\"]\n\turl = https://github.com/xylex-group/athena.git\n",
        )
        .expect("git config should be written");

        let remote = git_remote_url_from_metadata(&package_root, "origin")
            .expect("git metadata should parse")
            .expect("origin remote should exist via ancestor .git");
        assert_eq!(remote, "https://github.com/xylex-group/athena.git");

        fs::remove_dir_all(repo_root).expect("temp project should be removed");
    }
}