Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust
42.4 KB
Raw Blame
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

//! The source installer owns app bundles, service definitions, and installation metadata.

use serde::{Deserialize, Serialize};
use std::{
    fs,
    io::{Read, Write},
    net::{SocketAddr, TcpStream},
    path::{Path, PathBuf},
    process::{Command, Stdio},
    thread,
    time::{Duration, Instant, SystemTime, UNIX_EPOCH},
};

use switchyard_costs::Pricing;

use crate::config::{
    self, Config, DEFAULT_PORT, DESKTOP_CONFIG, HOME_DIR, PRICES_FILE, ROUTING_LOG, SERVER_CONFIG,
};

pub mod credentials;
// Linux and any other system without launchd or Task Scheduler use systemd; execute rejects
// unsupported systems before they change anything.
#[cfg(not(any(target_os = "macos", windows)))]
mod linux;
#[cfg(not(any(target_os = "macos", windows)))]
use linux as platform;
#[cfg(target_os = "macos")]
mod macos;
#[cfg(target_os = "macos")]
use macos as platform;
#[cfg(windows)]
pub mod windows;
#[cfg(windows)]
use windows as platform;

pub fn executable_name(name: &str) -> String {
    format!("{name}{}", std::env::consts::EXE_SUFFIX)
}

pub const BUNDLED_CONFIG: &str = include_str!("../../../scripts/config/composite.toml");
const UPDATE_LOCK: &str = ".switchyard-desktop-update.lock";
const PORT_ERROR: &str = "SY_PORT must be a number from 1 to 65535.";

#[derive(Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Settings {
    pub home: PathBuf,
    pub sy_home: PathBuf,
    pub codex_home: PathBuf,
    pub service_dir: PathBuf,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub app_dir: Option<PathBuf>,
    pub source: PathBuf,
    pub cargo: PathBuf,
    pub port: u16,
    pub profile: String,
    pub model: String,
}

impl Settings {
    pub fn for_uninstall() -> Result<Self, String> {
        let defaults = Self::from_env()?;
        let recorded = defaults.install_record();
        if !present(&recorded)? {
            return Ok(defaults);
        }
        let selected = Self::load(&recorded)?;
        for (name, differs) in [
            (
                "SY_HOME",
                defaults.sy_home.as_os_str() != selected.sy_home.as_os_str(),
            ),
            (
                "CODEX_HOME",
                defaults.codex_home.as_os_str() != selected.codex_home.as_os_str(),
            ),
            ("SY_PROFILE", defaults.profile != selected.profile),
        ] {
            if differs && std::env::var_os(name).is_some() {
                return Err(format!(
                    "{name} differs from the recorded installation at {}. \
                     Use uninstall --settings FILE to choose a different installation.",
                    recorded.display()
                ));
            }
        }
        Ok(selected)
    }
    pub fn from_env() -> Result<Self, String> {
        let home = config::home_dir()?;
        let path = |name, default| std::env::var_os(name).map(PathBuf::from).unwrap_or(default);
        let value = |name: &str, default: &str| {
            std::env::var(name).or_else(|error| match error {
                std::env::VarError::NotPresent => Ok(default.to_owned()),
                std::env::VarError::NotUnicode(_) => Err(format!("{name} must be UTF-8.")),
            })
        };
        let port = value("SY_PORT", &DEFAULT_PORT.to_string())?;
        if !port.bytes().all(|b| b.is_ascii_digit()) {
            return Err(PORT_ERROR.into());
        }
        let settings = Self {
            sy_home: path("SY_HOME", home.join(HOME_DIR)),
            codex_home: path("CODEX_HOME", home.join(".codex")),
            service_dir: if cfg!(target_os = "macos") {
                home.join("Library/LaunchAgents")
            } else if cfg!(windows) {
                path("APPDATA", home.join("AppData/Roaming"))
                    .join("Microsoft/Windows/Start Menu/Programs")
            } else {
                path("XDG_CONFIG_HOME", home.join(".config")).join("systemd/user")
            },
            app_dir: cfg!(windows).then(|| {
                path("LOCALAPPDATA", home.join("AppData/Local")).join("Programs/Switchyard")
            }),
            home,
            source: Path::new(env!("CARGO_MANIFEST_DIR"))
                .parent()
                .and_then(Path::parent)
                .ok_or("Could not find the source checkout.")?
                .to_path_buf(),
            cargo: PathBuf::from(env!("CARGO")),
            port: port.parse().map_err(|_| PORT_ERROR)?,
            profile: value("SY_PROFILE", "sy")?,
            model: value("SY_MODEL", "composite-gpt-6-sol-gpt-6-luna")?,
        };
        settings.validate()?;
        Ok(settings)
    }

    pub fn load(file: &Path) -> Result<Self, String> {
        let text = fs::read_to_string(file).map_err(|e| format!("Read {}: {e}", file.display()))?;
        let settings: Self =
            toml::from_str(&text).map_err(|e| format!("Parse {}: {e}", file.display()))?;
        settings.validate()?;
        Ok(settings)
    }

    pub fn validate(&self) -> Result<(), String> {
        let profile = self.profile.as_bytes();
        if !profile.first().is_some_and(u8::is_ascii_alphanumeric)
            || profile.len() > 128
            || !profile
                .iter()
                .all(|&b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
        {
            return Err(
                "SY_PROFILE must start with an ASCII letter or digit and contain only ASCII \
                 letters, digits, underscores, or hyphens, up to 128 characters."
                    .into(),
            );
        }
        if self.model.is_empty() || self.model.bytes().any(|b| b.is_ascii_control()) {
            return Err(
                "SY_MODEL must be a nonempty public route ID without ASCII control characters."
                    .into(),
            );
        }
        if self.port == 0 {
            return Err(PORT_ERROR.into());
        }
        for (name, path) in [
            ("HOME", &self.home),
            ("SY_HOME", &self.sy_home),
            ("CODEX_HOME", &self.codex_home),
            ("service directory", &self.service_dir),
            ("source checkout", &self.source),
            ("Cargo executable", &self.cargo),
        ]
        .into_iter()
        .chain(self.app_dir.as_ref().map(|path| ("LOCALAPPDATA", path)))
        {
            if !path.is_absolute()
                || path
                    .to_str()
                    .is_none_or(|s| s.bytes().any(|b| b.is_ascii_control()))
            {
                return Err(format!(
                    "{name} must be an absolute UTF-8 path without ASCII control characters."
                ));
            }
        }
        Ok(())
    }

    pub fn app(&self) -> PathBuf {
        self.home.join("Applications/Switchyard.app")
    }
    pub fn bin_dir(&self) -> PathBuf {
        if cfg!(windows) {
            self.app_dir
                .clone()
                .unwrap_or_else(|| self.home.join("AppData/Local/Programs/Switchyard"))
        } else {
            self.sy_home.join("bin")
        }
    }
    pub fn binary(&self, name: &str) -> PathBuf {
        self.bin_dir().join(executable_name(name))
    }
    pub fn desktop_settings(&self) -> PathBuf {
        self.sy_home.join(DESKTOP_CONFIG)
    }
    /// This optional file overrides bundled rates for the server and app baseline.
    pub fn prices_file(&self) -> PathBuf {
        self.sy_home.join(PRICES_FILE)
    }
    /// This method builds the installed server command with any existing price override.
    /// The caller configures and starts the process.
    pub fn server_command(&self) -> Result<Command, String> {
        let config = Config::load(&self.desktop_settings())?;
        let mut command = Command::new(self.binary("switchyard-server"));
        command.arg("--config").arg(&config.config_file);
        let url = crate::health::validate_url(&config.server_url)?;
        command.args(["--host", "127.0.0.1"]);
        command.arg("--port").arg(
            url.port_or_known_default()
                .ok_or("Missing server port.")?
                .to_string(),
        );
        command.arg("--routing-log-file").arg(&config.routing_log);
        if let Some(prices) = &config.prices_file {
            command.arg("--pricing-file").arg(prices);
        }
        Ok(command)
    }

    fn profile_file(&self) -> PathBuf {
        self.codex_home
            .join(format!("{}.config.toml", self.profile))
    }
    fn release(&self, binary: &str) -> PathBuf {
        self.source
            .join("target/release")
            .join(executable_name(binary))
    }
    /// Uninstall reads this copy of the settings to find the installation.
    fn install_record(&self) -> PathBuf {
        self.home.join(".switchyard-desktop-install.toml")
    }
}

/// The app reads this metadata to retain a custom SY_HOME when Finder or a Windows shortcut starts it.
pub fn bundle_metadata(executable: &Path) -> PathBuf {
    // Windows keeps the metadata beside the executable; macOS keeps it in the bundle's Resources.
    let (levels, file) = if cfg!(windows) {
        (1, "install.toml")
    } else {
        (2, "Resources/install.toml")
    };
    executable
        .ancestors()
        .nth(levels)
        .unwrap_or(Path::new("."))
        .join(file)
}

/// The updater runs separately because installation restarts the app that requested it.
pub fn start_update(settings_file: &Path) -> Result<PathBuf, String> {
    let settings = Settings::load(settings_file)?;
    let guard = update_lock(&settings)?;
    if update_starting(&update_status(settings_file)?) {
        return Err(
            "A Switchyard update is already starting. View its progress in Settings.".into(),
        );
    }
    set_update_state(
        &settings,
        "starting",
        "start",
        "Starting the source update.",
    )?;
    let log_path = settings.sy_home.join("logs/update.log");
    let log = fs::OpenOptions::new()
        .create(true)
        .append(true)
        .open(&log_path)
        .map_err(err)?;
    let error_log = log.try_clone().map_err(err)?;
    #[cfg(windows)]
    let updater_path = windows::temporary_updater(&settings.binary("switchyard-desktop-install"))?;
    #[cfg(not(windows))]
    let updater_path = settings.binary("switchyard-desktop-install");
    let mut updater = Command::new(&updater_path);
    #[cfg(windows)]
    windows::hide_console(&mut updater);
    #[cfg(unix)]
    {
        use std::os::unix::process::CommandExt;
        // A separate process group keeps launchd from stopping the updater with the app.
        updater.process_group(0);
    }
    // The child must acquire the update lock, so the parent releases it before spawning.
    drop(guard);
    let mut child = updater
        .args(["update", "--settings"])
        .arg(settings_file)
        .stdin(Stdio::null())
        .stdout(log)
        .stderr(error_log)
        .spawn()
        .map_err(|e| {
            let message = format!("Could not start the source update: {e}");
            let _ = set_update_state(&settings, "failed", "start", &message);
            message
        })?;
    #[cfg(windows)]
    updater_path.keep().map_err(err)?;
    // This thread reaps the updater if it exits before installation stops the app.
    thread::spawn(move || {
        let _ = child.wait();
    });
    Ok(log_path)
}

pub fn execute(settings: &Settings, action: &str, dry_run: bool) -> Result<(), String> {
    settings.validate()?;
    if !matches!(action, "install" | "uninstall" | "update") {
        return Err("Choose install, update, or uninstall.".into());
    }
    if !cfg!(any(target_os = "macos", target_os = "linux", windows)) {
        return Err("Installation supports macOS, Linux, and Windows.".into());
    }
    if dry_run {
        println!("{}", installation_plan(settings, action));
        return Ok(());
    }
    if action == "uninstall" {
        return uninstall(settings);
    }
    let _job = update_lock(settings)?;
    if action == "update" {
        set_update_state(settings, "running", "build", "Building the app and server.")?;
    }
    match install(settings, action == "update") {
        Ok(None) => set_update_state(
            settings,
            "completed",
            "completed",
            "Installed the app and server. Switchyard is ready.",
        ),
        Ok(Some(warning)) => set_update_state(settings, "warning", "readiness", &warning),
        Err(error) => {
            // The failure keeps the stage that the install last recorded.
            if settings.sy_home.exists() {
                let stage = update_status(&settings.sy_home.join("install.toml"))
                    .ok()
                    .and_then(|s| s["stage"].as_str().map(str::to_owned))
                    .unwrap_or_else(|| "installation".into());
                let _ = set_update_state(settings, "failed", &stage, &error);
            }
            Err(error)
        }
    }
}

// The persistent file keeps concurrent commands locking the same inode; exit releases the lock.
fn lock(path: &Path, busy: impl FnOnce(fs::TryLockError) -> String) -> Result<fs::File, String> {
    let file = fs::OpenOptions::new()
        .create(true)
        .truncate(false)
        .read(true)
        .write(true)
        .open(path)
        .map_err(err)?;
    file.try_lock().map_err(busy)?;
    Ok(file)
}
fn update_lock(settings: &Settings) -> Result<fs::File, String> {
    lock(&settings.home.join(UPDATE_LOCK), |_| {
        "A Switchyard update is already running. Open Settings to view its progress.".into()
    })
}
fn lock_installation(s: &Settings) -> Result<fs::File, String> {
    lock(&s.home.join(".switchyard-desktop-install.lock"), |e| {
        format!("Could not lock the desktop installation: {e}")
    })
}
fn set_update_state(
    settings: &Settings,
    state: &str,
    stage: &str,
    message: &str,
) -> Result<(), String> {
    let updated_at = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map_err(err)?
        .as_secs();
    let record = serde_json::json!({"state": state, "stage": stage, "message": message,
        "source": settings.source, "updated_at": updated_at});
    write(
        &settings.sy_home.join("update-status.toml"),
        toml::to_string(&record).map_err(err)?.as_bytes(),
        false,
    )
}
// A marker under 10 seconds old marks the child as starting before it acquires the lock.
fn update_starting(record: &serde_json::Value) -> bool {
    record["state"] == "starting"
        && record["updated_at"].as_u64().is_some_and(|stamp| {
            SystemTime::now()
                .duration_since(UNIX_EPOCH)
                .is_ok_and(|now| now.as_secs().saturating_sub(stamp) < 10)
        })
}
pub fn update_status(settings_file: &Path) -> Result<serde_json::Value, String> {
    let settings = Settings::load(settings_file)?;
    let Some(text) = read_optional(&settings.sy_home.join("update-status.toml")).map_err(err)?
    else {
        return Ok(serde_json::json!({"state":"idle"}));
    };
    let value: toml::Value = toml::from_str(&text).map_err(err)?;
    let mut record = serde_json::to_value(value).map_err(err)?;
    if !update_starting(&record)
        && matches!(record["state"].as_str(), Some("starting" | "running"))
        && let Ok(lock) = fs::OpenOptions::new()
            .read(true)
            .write(true)
            .open(settings.home.join(UPDATE_LOCK))
        && lock.try_lock().is_ok()
    {
        record["state"] = serde_json::json!("interrupted");
        record["message"] = serde_json::json!(
            "The update stopped before recording completion. Open the update log, then retry."
        );
    }
    Ok(record)
}
pub fn preview_update(settings_file: &Path) -> Result<serde_json::Value, String> {
    let settings = Settings::load(settings_file)?;
    let git = |args: &[&str]| -> String {
        let mut command = Command::new("git");
        #[cfg(windows)]
        windows::hide_console(&mut command);
        command
            .arg("-C")
            .arg(&settings.source)
            .args(args)
            .output()
            .ok()
            .filter(|o| o.status.success())
            .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
            .unwrap_or_else(|| "Unavailable".into())
    };
    Ok(
        serde_json::json!({"source":settings.source,"revision":git(&["rev-parse","HEAD"]),"branch":git(&["branch","--show-current"]),"changes":git(&["status","--short"]),"plan":installation_plan(&settings,"update"),"status":update_status(settings_file)?}),
    )
}
fn installation_plan(s: &Settings, action: &str) -> String {
    let removing = action == "uninstall";
    let needs_setup = !removing && matches!(config::needs_setup(&s.desktop_settings()), Ok(true));
    let pick = |remove, install| if removing { remove } else { install };
    let app = if cfg!(target_os = "macos") {
        "macOS desktop app"
    } else if cfg!(windows) {
        "Windows desktop app"
    } else {
        "Linux terminal app"
    };
    let profile = s.profile_file();
    let profile_action = if removing {
        "Preserve recovery copy, then remove"
    } else if needs_setup {
        "Defer until after setup:"
    } else if !profile.exists() {
        "Create"
    } else if action == "update" {
        "Preserve"
    } else {
        "Back up, then update"
    };
    let binaries = if !removing {
        "Replace"
    } else if cfg!(windows) {
        "Remove"
    } else {
        "Preserve"
    };
    let mut rows = vec![
        format!(
            "{} {app} and local server from {}",
            pick("Remove", "Build and install"),
            s.source.display()
        ),
        format!("Route: {} · Server: http://127.0.0.1:{}", s.model, s.port),
        format!(
            "{} service definitions in {}. The server {}.",
            pick("Remove", "Replace"),
            s.service_dir.display(),
            if needs_setup {
                "will wait for setup before starting"
            } else {
                pick("will stop", "will restart after build and validation")
            }
        ),
    ];
    for (path, label) in [
        (s.desktop_settings(), "app settings"),
        (s.sy_home.join(SERVER_CONFIG), "server config"),
        (s.sy_home.join(ROUTING_LOG), "usage history"),
    ] {
        let verb = if needs_setup {
            "Defer until setup"
        } else if removing || path.exists() {
            "Preserve"
        } else {
            "Create"
        };
        rows.push(format!("{verb} {label}: {}", path.display()));
    }
    if s.prices_file().exists() {
        rows.push(format!(
            "Preserve model price override: {}",
            s.prices_file().display()
        ));
    }
    rows.push(format!(
        "{profile_action} Codex profile: {}",
        profile.display()
    ));
    rows.push(format!("{binaries} binaries: {}", s.bin_dir().display()));
    rows.push(format!(
        "Preserve accounts and logs: {}",
        s.sy_home.display()
    ));
    if cfg!(target_os = "macos") {
        rows.push(format!(
            "{} app bundle: {}",
            pick("Remove", "Replace"),
            s.app().display()
        ));
    }
    rows.push(
        "Preview changes no files. Build prerequisites, full server config validation, \
         and readiness are checked during installation."
            .into(),
    );
    if removing {
        rows.extend(removal_notes(s));
    }
    rows.join("\n")
}

/// Lists the coding-tool files that uninstall leaves in place for the user to review.
fn removal_notes(s: &Settings) -> Vec<String> {
    let mut destinations = vec![
        s.codex_home.join("sy.config.toml"),
        s.codex_home.join("config.toml"),
        s.home.join(".claude/settings.json"),
        s.home.join(".pi/agent/models.json"),
        s.home.join(".pi/agent/settings.json"),
    ];
    for (tool, file) in [("codex", "config.toml"), ("claude", "settings.json")] {
        let root = s.home.join(".switchyard/accounts").join(tool);
        // symlink_metadata does not follow a symlink, so a linked accounts directory is skipped.
        if fs::symlink_metadata(&root).is_ok_and(|m| m.is_dir())
            && let Ok(accounts) = fs::read_dir(&root)
        {
            let accounts = accounts
                .flatten()
                .filter(|a| a.file_type().is_ok_and(|t| t.is_dir()));
            destinations.extend(accounts.map(|account| account.path().join(file)));
        }
    }
    let mut notes = Vec::new();
    for destination in destinations {
        let saved = ["switchyard-original", "switchyard-original-missing"]
            .iter()
            .any(|suffix| PathBuf::from(format!("{}.{suffix}", destination.display())).exists());
        if saved {
            notes.push(format!(
                "Preserve coding-tool destination with a Switchyard backup: {}. \
                 Restore it in Connect tools before removal.",
                destination.display()
            ));
        }
    }
    notes.push("Custom destinations outside these known locations are not inventoried.".into());
    notes.push(
        "Restore routing from Connect tools before uninstalling. \
         Custom and account tool settings are preserved and may still point at this server."
            .into(),
    );
    notes
}

fn wait_for_health(port: u16) -> bool {
    let deadline = Instant::now() + Duration::from_secs(10);
    let address: SocketAddr = ([127, 0, 0, 1], port).into();
    while Instant::now() < deadline {
        if let Ok(mut stream) = TcpStream::connect_timeout(&address, Duration::from_millis(250)) {
            let _ = stream.set_read_timeout(Some(Duration::from_millis(300)));
            let _ = stream.set_write_timeout(Some(Duration::from_millis(300)));
            if write!(
                stream,
                "GET /health HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\nConnection: close\r\n\r\n"
            )
            .is_ok()
            {
                let mut bytes = [0; 8192];
                let mut used = 0;
                let mut complete = false;
                while used < bytes.len() {
                    let Some(remaining) = deadline.checked_duration_since(Instant::now()) else {
                        break;
                    };
                    if remaining.is_zero()
                        || stream
                            .set_read_timeout(Some(remaining.min(Duration::from_millis(300))))
                            .is_err()
                    {
                        break;
                    }
                    match stream.read(&mut bytes[used..]) {
                        Ok(0) => {
                            complete = true;
                            break;
                        }
                        Ok(count) => used += count,
                        Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue,
                        Err(_) => break,
                    }
                }
                if (complete || used == bytes.len())
                    && let Ok(response) = std::str::from_utf8(&bytes[..used])
                    && let Some((headers, body)) = response.split_once("\r\n\r\n")
                    && headers
                        .lines()
                        .next()
                        .and_then(|line| line.split_whitespace().nth(1))
                        == Some("200")
                    && serde_json::from_str::<serde_json::Value>(body)
                        .is_ok_and(|v| v["status"] == "ok")
                {
                    return true;
                }
            }
        }
        thread::sleep(Duration::from_millis(200));
    }
    false
}

fn run(command: &mut Command) -> Result<(), String> {
    #[cfg(windows)]
    windows::hide_console(command);
    let invocation = format!(
        "{:?} {:?}",
        command.get_program(),
        command.get_args().collect::<Vec<_>>()
    );
    println!("Running {invocation}");
    let status = command
        .status()
        .map_err(|e| format!("Could not run {invocation}: {e}"))?;
    if status.success() {
        Ok(())
    } else {
        Err(format!("{invocation} exited with {status}"))
    }
}

fn err(error: impl std::fmt::Display) -> String {
    error.to_string()
}

fn present(path: &Path) -> Result<bool, String> {
    path.try_exists().map_err(err)
}

/// Reads a text file; a missing file is `None`.
fn read_optional(path: &Path) -> std::io::Result<Option<String>> {
    match fs::read_to_string(path) {
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
        result => result.map(Some),
    }
}

// Atomic replacement keeps existing executables readable while an update is staged.
fn write(path: &Path, bytes: &[u8], executable: bool) -> Result<(), String> {
    let parent = path
        .parent()
        .ok_or("The destination has no parent directory.")?;
    fs::create_dir_all(parent).map_err(err)?;
    let mut temp = tempfile::NamedTempFile::new_in(parent).map_err(err)?;
    temp.write_all(bytes).map_err(err)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mode = if executable { 0o755 } else { 0o600 };
        temp.as_file()
            .set_permissions(fs::Permissions::from_mode(mode))
            .map_err(err)?;
    }
    #[cfg(not(unix))]
    let _ = executable;
    temp.as_file().sync_all().map_err(err)?;
    temp.persist(path)
        .map_err(|e| format!("Write {}: {e}", path.display()))?;
    Ok(())
}

fn write_once(path: &Path, text: &str) -> Result<(), String> {
    if present(path)? {
        return Ok(());
    }
    write(path, text.as_bytes(), false)
}

fn backup(path: &Path, label: &str) -> Result<(), String> {
    let name = path.file_name().ok_or("Missing file name.")?;
    let parent = path.parent().ok_or("Missing parent directory.")?;
    let mut copy = tempfile::Builder::new()
        .prefix(&format!("{}.{label}.", name.to_string_lossy()))
        .tempfile_in(parent)
        .map_err(err)?;
    copy.write_all(&fs::read(path).map_err(err)?).map_err(err)?;
    copy.as_file().sync_all().map_err(err)?;
    let (_, saved) = copy.keep().map_err(err)?;
    println!("Preserved {} at {}", path.display(), saved.display());
    Ok(())
}

fn remove(path: &Path) -> Result<(), String> {
    match fs::remove_file(path) {
        Ok(()) => Ok(()),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
        Err(e) => Err(format!("Remove {}: {e}", path.display())),
    }
}

/// What an install gathers and checks before it changes the installation.
struct Prepared {
    needs_setup: bool,
    /// The Codex profile to save.
    profile: String,
    /// App settings rewritten for a new port, when the port changes.
    desktop_settings: Option<String>,
    /// API key variables in the server config that have no saved key.
    missing_keys: Vec<String>,
}

// Every check and the build run before services stop, so a failure leaves the current
// installation running.
fn install(s: &Settings, preserve_profile: bool) -> Result<Option<String>, String> {
    let prepared = prepare(s, preserve_profile)?;
    let _lock = lock_installation(s)?;
    set_update_state(
        s,
        "running",
        "install",
        "Build and config validation passed. Replacing the installation.",
    )?;
    replace_installation(
        s,
        prepared.desktop_settings.as_deref(),
        prepared.needs_setup,
    )?;
    platform::install(s, !prepared.needs_setup && prepared.missing_keys.is_empty())?;
    if prepared.needs_setup {
        let message = "Installed. Open Switchyard to choose your configuration. Existing files will skip setup on later installs.".to_string();
        println!("{message}");
        return Ok(Some(message));
    }
    if !preserve_profile || !present(&s.profile_file())? {
        save_profile(s, &prepared.profile)?;
    }
    report_readiness(s, &prepared.missing_keys)
}

fn prepare(s: &Settings, preserve_profile: bool) -> Result<Prepared, String> {
    let needs_setup = config::needs_setup(&s.desktop_settings())?;
    let profile = s.profile_file();
    let desktop_settings = reconcile_desktop_port(s)?;
    let server_url = if desktop_settings.is_some() || !present(&s.desktop_settings())? {
        config::server_url(s.port)
    } else {
        Config::load(&s.desktop_settings())?.server_url
    };
    let profile_text = if needs_setup {
        String::new()
    } else {
        let context_window = route_context_window(s)?;
        if profile.exists() && !preserve_profile {
            let current = fs::read_to_string(&profile).map_err(err)?;
            merge_codex_profile(s, &current, context_window, &server_url)?
        } else {
            codex_profile(s, context_window, &server_url)
        }
    };
    #[cfg(not(windows))]
    platform::preflight()?;
    let prices = if needs_setup {
        None
    } else {
        Config::load(&s.desktop_settings())?
            .prices_file
            .or_else(|| {
                // An installation with only a server config still imports its adjacent price override.
                (!s.desktop_settings().exists() && s.prices_file().exists())
                    .then(|| s.prices_file())
            })
    };
    if let Some(prices) = prices {
        Pricing::load(&prices).map_err(|e| format!("{e}. Fix this file before installing."))?;
    }
    build(s)?;
    let missing_keys = if needs_setup {
        Vec::new()
    } else {
        check_server_config(s, !preserve_profile || !profile.exists())?
    };
    Ok(Prepared {
        needs_setup,
        profile: profile_text,
        desktop_settings,
        missing_keys,
    })
}

/// This function builds the server from the main workspace and the app from its own
/// experimental workspace before it installs binaries or changes services.
fn build(s: &Settings) -> Result<(), String> {
    println!(
        "Building the desktop app and server from {}",
        s.source.display()
    );
    // Cargo and rustc must come from the same toolchain, including GUI-triggered updates.
    let cargo_dir = s.cargo.parent().ok_or("Cargo has no parent directory.")?;
    let mut paths = vec![cargo_dir.to_path_buf()];
    if let Some(path) = std::env::var_os("PATH") {
        paths.extend(std::env::split_paths(&path));
    }
    let path = std::env::join_paths(paths).map_err(err)?;
    for (manifest, package) in [
        ("Cargo.toml", "switchyard-server"),
        (
            "experimental/switchyard-desktop/Cargo.toml",
            "switchyard-desktop",
        ),
    ] {
        run(Command::new(&s.cargo)
            .current_dir(&s.source)
            .args(["build", "--locked", "--release", "--manifest-path"])
            .arg(s.source.join(manifest))
            .arg("--target-dir")
            .arg(s.source.join("target"))
            .args(["-p", package])
            .env("PATH", &path))?;
    }
    Ok(())
}

/// Checks the server config that the install keeps, or the bundled one on a first install, and
/// returns the API key variables that have no saved key.
fn check_server_config(s: &Settings, require_route: bool) -> Result<Vec<String>, String> {
    let config = Config::load(&s.desktop_settings())?.config_file;
    let existing = present(&config)?;
    let staged = tempfile::NamedTempFile::new().map_err(err)?;
    let checked = if existing {
        config.as_path()
    } else {
        fs::write(staged.path(), BUNDLED_CONFIG).map_err(err)?;
        staged.path()
    };
    // Install never saves keys; the app's Settings → Server keys does. Placeholder values let the
    // dry run check the config without reading any key.
    let mut checker = Command::new(s.release("switchyard-server"));
    for name in credentials::variables(checked)? {
        checker.env(name, "placeholder-for-config-check");
    }
    run(checker.arg("--config").arg(checked).arg("--dry-run"))?;
    // Finding an item does not read its key, so this check never asks for Keychain access.
    let missing = credentials::status(checked)?
        .into_iter()
        .filter(|key| !key.saved)
        .map(|key| key.name)
        .collect();
    if require_route {
        check_public_route(checked, &s.model)?;
    }
    Ok(missing)
}

/// Stops the services and replaces the app files. The macOS app bundle is staged and signed
/// before the services stop.
fn replace_installation(
    s: &Settings,
    desktop_settings: Option<&str>,
    needs_setup: bool,
) -> Result<(), String> {
    let metadata = toml::to_string(s).map_err(err)?;
    #[cfg(target_os = "macos")]
    let bundle = platform::stage_bundle(s, &metadata)?;
    fs::create_dir_all(&s.sy_home).map_err(err)?;
    set_update_state(
        s,
        "running",
        "services",
        "Stopping services and replacing app files. Existing config and history are retained.",
    )?;
    platform::stop(s)?;
    fs::create_dir_all(s.sy_home.join("logs")).map_err(err)?;
    #[cfg(windows)]
    windows::replace_binaries(s)?;
    #[cfg(not(windows))]
    for binary in [
        "switchyard-server",
        "switchyard-desktop",
        "switchyard-desktop-install",
    ] {
        let bytes = fs::read(s.release(binary)).map_err(err)?;
        write(&s.binary(binary), &bytes, true)?;
    }
    if !needs_setup {
        if let Some(text) = desktop_settings {
            write(&s.desktop_settings(), text.as_bytes(), false)?;
        } else {
            write_once(&s.desktop_settings(), &desktop_config(s)?)?;
        }
    }
    for record in [s.sy_home.join("install.toml"), s.install_record()] {
        write(&record, metadata.as_bytes(), false)?;
    }
    #[cfg(target_os = "macos")]
    platform::replace_app(s, bundle)?;
    Ok(())
}

fn save_profile(s: &Settings, text: &str) -> Result<(), String> {
    set_update_state(
        s,
        "running",
        "profile",
        "Saving the selected Codex profile.",
    )?;
    let profile = s.profile_file();
    if present(&profile)? && fs::read(&profile).map_err(err)? != text.as_bytes() {
        backup(&profile, "switchyard-backup")?;
    }
    write(&profile, text.as_bytes(), false)
}

/// Returns the warning to record when the server cannot start yet or does not answer /health.
fn report_readiness(s: &Settings, missing_keys: &[String]) -> Result<Option<String>, String> {
    let config = Config::load(&s.desktop_settings())?;
    println!(
        "Installed. Server: {}\nSettings: {}\nUse: codex -p {}",
        config.server_url,
        s.desktop_settings().display(),
        s.profile
    );
    set_update_state(
        s,
        "running",
        "readiness",
        "Installed. Waiting for the server to answer /health.",
    )?;
    if !missing_keys.is_empty() {
        let next = if cfg!(any(target_os = "macos", windows)) {
            "Open Switchyard, go to Settings → Server keys, save each key, \
             and restart the server."
                .to_string()
        } else {
            format!(
                "Save each key with {} key set NAME, \
                 then run systemctl --user restart switchyard.",
                s.binary("switchyard-desktop-install").display()
            )
        };
        let message = format!(
            "Installed the app and server. The server starts after you save a key for {}. {next}",
            missing_keys.join(", ")
        );
        println!("{message}");
        return Ok(Some(message));
    }
    let port = crate::health::validate_url(&config.server_url)?
        .port_or_known_default()
        .ok_or("Missing server port.")?;
    if wait_for_health(port) {
        return Ok(None);
    }
    let message = format!(
        "Installed the app and server, but Switchyard did not answer /health. \
         Check logs at {} and restart the server.",
        s.sy_home.join("logs").display()
    );
    println!("Warning: {message}");
    Ok(Some(message))
}

fn routes(config: &toml::Value) -> impl Iterator<Item = &toml::Value> {
    config
        .get("routes")
        .and_then(toml::Value::as_table)
        .into_iter()
        .flat_map(|routes| routes.values())
}

fn check_public_route(config: &Path, model: &str) -> Result<(), String> {
    let text = fs::read_to_string(config).map_err(err)?;
    let document: toml::Value = toml::from_str(&text).map_err(err)?;
    let ids: Vec<&str> = routes(&document)
        .filter_map(|route| route.get("id")?.as_str())
        .collect();
    if ids.contains(&model) {
        return Ok(());
    }
    Err(format!(
        "Route {model:?} is not in {}. Choose SY_MODEL from: {}. \
         No services or coding-tool settings were changed.",
        config.display(),
        ids.join(", ")
    ))
}

fn reconcile_desktop_port(s: &Settings) -> Result<Option<String>, String> {
    let path = s.desktop_settings();
    let Some(text) = read_optional(&path).map_err(|e| format!("Read {}: {e}", path.display()))?
    else {
        return Ok(None);
    };
    let mut document: toml_edit::DocumentMut = text.parse().map_err(|e| {
        format!(
            "Parse {}: {e}. Fix this file before installing.",
            path.display()
        )
    })?;
    let previous = s.sy_home.join("install.toml");
    let old_port = if previous.exists() {
        Settings::load(&previous)?.port
    } else {
        DEFAULT_PORT
    };
    let expected = config::server_url(old_port);
    let current = document
        .get("server_url")
        .map(|value| {
            value.as_str().ok_or_else(|| {
                format!(
                    "The server_url value in {} must be a string: invalid data. \
                     Fix this file before installing.",
                    path.display()
                )
            })
        })
        .transpose()?;
    if s.port != old_port && current.is_some_and(|url| url != expected) {
        return Err(format!(
            "{} uses a custom server_url, but SY_PORT changes from {old_port} to {}. \
             Review the app URL and port together before reinstalling. No services were stopped.",
            path.display(),
            s.port
        ));
    }
    // Unchanged and custom URLs must retain the original TOML bytes, including quotes and line endings.
    if current.is_some_and(|url| url != expected || s.port == old_port) {
        return Ok(None);
    }
    document["server_url"] = toml_edit::value(config::server_url(s.port));
    let updated = document.to_string();
    Ok((updated != text).then_some(updated))
}

// Returns the `context_window` of the route that SY_MODEL names, from the existing server
// config or, on a new install, the bundled one. A missing route returns `None` here;
// check_public_route rejects it later with the list of valid route IDs.
fn route_context_window(s: &Settings) -> Result<Option<i64>, String> {
    let path = Config::load(&s.desktop_settings())?.config_file;
    let text = read_optional(&path).map_err(|e| format!("Read {}: {e}", path.display()))?;
    let document: toml::Value = toml::from_str(text.as_deref().unwrap_or(BUNDLED_CONFIG))
        .map_err(|e| format!("Parse {}: {e}", path.display()))?;
    Ok(routes(&document)
        .find(|route| route.get("id").and_then(toml::Value::as_str) == Some(&s.model))
        .and_then(|route| route.get("context_window")?.as_integer()))
}

// Codex compacts a thread when its usage nears the model's context window. Codex does not
// know a Switchyard route ID, so the profile names the route's window. Without it, Codex
// never compacts on the route, and a long thread fails when the upstream rejects it.
fn codex_profile(s: &Settings, context_window: Option<i64>, server_url: &str) -> String {
    let mut value: toml::Value = toml::from_str(
        include_str!("../../../scripts/config/codex.sy.toml")
            .replace("@SY_PORT@", &s.port.to_string())
            .as_str(),
    )
    .expect("bundled profile is valid TOML");
    value["model"] = s.model.clone().into();
    value["model_providers"]["sy"]["base_url"] =
        format!("{}/v1", server_url.trim_end_matches('/')).into();
    if let (Some(window), Some(table)) = (context_window, value.as_table_mut()) {
        table.insert("model_context_window".into(), window.into());
    }
    toml::to_string(&value).expect("profile values serialize")
}
fn merge_codex_profile(
    s: &Settings,
    current: &str,
    context_window: Option<i64>,
    server_url: &str,
) -> Result<String, String> {
    let mut document: toml_edit::DocumentMut = current
        .parse()
        .map_err(|e| format!("Read Codex profile: {e}"))?;
    let template: toml_edit::DocumentMut = codex_profile(s, context_window, server_url)
        .parse()
        .expect("generated profile is valid TOML");
    for key in ["model", "model_provider"] {
        document[key] = template[key].clone();
    }
    // A window kept from an earlier route would make Codex compact at the wrong size.
    match template.get("model_context_window") {
        Some(window) => document["model_context_window"] = window.clone(),
        None => {
            document.remove("model_context_window");
        }
    }
    if document.get("model_providers").is_none() {
        document["model_providers"] = toml_edit::table();
    }
    let providers = &mut document["model_providers"];
    if !providers.is_table_like() {
        return Err(
            "Codex model_providers must be a table. No services or profiles were changed.".into(),
        );
    }
    let sy = providers.get("sy");
    if sy.is_some_and(|item| !item.is_table_like()) {
        return Err(
            "Codex model_providers.sy must be a table. No services or profiles were changed."
                .into(),
        );
    }
    if sy.is_none() {
        providers["sy"] = toml_edit::table();
    }
    for key in ["name", "base_url", "wire_api", "requires_openai_auth"] {
        providers["sy"][key] = template["model_providers"]["sy"][key].clone();
    }
    Ok(document.to_string())
}

// The installer and app share defaults so generated settings keep the selected directory and port.
fn desktop_config(s: &Settings) -> Result<String, String> {
    let mut config = Config::for_directory(&s.sy_home, s.port);
    let prices = s.prices_file();
    if prices.exists() {
        config.prices_file = Some(prices);
    }
    toml::to_string(&config).map_err(err)
}

#[cfg(any(target_os = "macos", windows))]
fn xml(value: &str) -> String {
    value
        .replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
}
fn uninstall(s: &Settings) -> Result<(), String> {
    let _lock = lock_installation(s)?;
    println!("{}", installation_plan(s, "uninstall"));
    let profile = s.profile_file();
    if profile.exists() {
        backup(&profile, "switchyard-uninstall-recovery")?;
    }
    platform::stop(s)?;
    platform::uninstall(s)?;
    remove(&profile)?;
    println!(
        "Removed services, app, and profile. Kept settings, accounts, {}and history at {}.",
        if cfg!(windows) { "" } else { "binaries, " },
        s.sy_home.display()
    );
    let recorded = s.install_record();
    if recorded.exists() && Settings::load(&recorded)?.sy_home == s.sy_home {
        remove(&recorded)?;
    }
    Ok(())
}