superfluid_daemon/

selfupdate.rs

//! `superfluid self update|list|use|check|install`: releases side by side under `$SUPERFLUID_HOME/versions`, a
//! `current` link the commands on PATH go through, and the daily check `serve` runs.

use std::io::{BufRead, IsTerminal, Write};
use std::path::{Path, PathBuf};
use std::process::{Command, Output};
use std::time::{Duration, SystemTime, UNIX_EPOCH};

use serde_json::{json, Value};
use superfluid_adapter_kit::install::{fetch, single_top, unpack, version_key, Asset};

use crate::runtime_pick::RuntimeId;
use crate::runtimes::Catalog;

pub const REPO: &str = "basecompute/superfluid";
const LISTING: &str = "https://api.github.com/repos/basecompute/superfluid/releases?per_page=20";
/// A release younger than this is not announced by the daily check, so early reports land first.
pub const HOLD_OFF_DAYS: i64 = 3;
const CHECK_EVERY: Duration = Duration::from_secs(24 * 60 * 60);
pub const NO_CHECK_ENV: &str = "SUPERFLUID_NO_UPDATE_CHECK";
/// Where the release listing is read from, for a mirror or a test: a URL or a file.
pub const LISTING_ENV: &str = "SUPERFLUID_RELEASES";
const LINKED: &[&str] = &["superfluid", "superfluid-workerd", "superfluid-noded"];
/// The file at the root of a release a package manager installed (Homebrew, pip, npm), one line `<manager>: <command>`:
/// the copy is that manager's to update, with that command.
pub const INSTALLED_BY: &str = "installed-by";
/// The stamp basert writes at the root of the superfluid it installs for `basert serve`, before it also wrote an
/// `installed-by` file naming itself: such a copy is basert's, not the install script's.
const BASERT_STAMP: &str = ".release";
/// How long a new copy's `--version` or `runtimes --json` may take: it runs under the lock, which a copy that hangs
/// would hold for every later update. Longer than the runtime checks `runtimes --json` makes, a minute each at most.
const PROBE_TIMEOUT: Duration = Duration::from_secs(5 * 60);

pub const HELP: &str = "Update superfluid itself, or switch between the versions installed here.

Usage:
  superfluid self update [--version <v>] [--dry-run] [--yes]
                                                        Install the newest release that fits this machine and make it current
  superfluid self check                                 Ask whether a newer release exists, without installing
  superfluid self list                                  The versions installed here, and which is current
  superfluid self use <v>                               Make an installed version current (the one an update replaced stays)
  superfluid self install --from <dir> [--prefix <dir>] Place an unpacked release here; what the install script runs

Releases live side by side under $SUPERFLUID_HOME/versions/<v>, with a `current` link that the
`superfluid` on PATH goes through. An update unpacks the new release beside the old one, proves
it starts, flips the link, keeps the version it replaced and removes older ones (a version with
a `keep` file inside, or one a running server started from, stays). A running server keeps the
version it started with until it is started again.

With a baseRT engine here, a release must declare the engine's ABI number; with llama.cpp or
MLX only, the newest release fits. A superfluid installed by a package manager or cargo is
updated the way it was installed: for Homebrew, a global npm, pipx, uv and cargo this command
runs that manager's update (asking first; --yes runs it without asking, and is needed without
a terminal), and for pip in an environment or a project's npm dependency it names the command.
The superfluid basert installs for `basert serve` is basert's: this command runs
`basert superfluid install`, which picks the release that serves basert's engine.

`superfluid serve` checks for a newer release once a day, after the server is up, and prints
one line; SUPERFLUID_NO_UPDATE_CHECK=1 or --offline turns that off. A release is announced a
few days after it is published.
";

/// The release asset name for this build's platform.
pub fn target() -> Option<&'static str> {
    match (std::env::consts::OS, std::env::consts::ARCH) {
        ("macos", "aarch64") => Some("aarch64-apple-darwin"),
        ("linux", "aarch64") => Some("aarch64-unknown-linux-gnu"),
        ("linux", "x86_64") => Some("x86_64-unknown-linux-gnu"),
        _ => None,
    }
}

pub fn running() -> &'static str {
    env!("CARGO_PKG_VERSION")
}


/// Whether `v` can name a version directory: it starts with a digit and holds only what a version does, so it is one
/// path component and never empty, `.` or `..`, which would make the version's directory the layout or above it.
fn is_version(v: &str) -> bool {
    v.starts_with(|c: char| c.is_ascii_digit()) && v.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '-' | '+'))
}

/// A part of a pre-release, `rc` or `1` in `0.2.0-rc.1`: a number comes before a word, as semver orders them.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
enum PreRelease {
    Number(u64),
    Word(String),
}

/// A version's place in release order: by its numbers, then a release after the pre-releases that lead to it
/// (`0.2.0-rc.1` before `0.2.0`, which the numbers alone put the other way), then the pre-release part by part; build
/// metadata after a `+` counts for nothing.
fn release_order(v: &str) -> (Vec<u64>, bool, Vec<PreRelease>) {
    let v = v.split('+').next().unwrap_or(v);
    let (numbers, pre) = match v.split_once('-') {
        Some((numbers, pre)) => (numbers, Some(pre)),
        None => (v, None),
    };
    let parts = pre
        .map(|p| p.split('.').map(|id| id.parse().map(PreRelease::Number).unwrap_or_else(|_| PreRelease::Word(id.to_string()))).collect())
        .unwrap_or_default();
    (version_key(numbers), pre.is_none(), parts)
}

/// `$SUPERFLUID_HOME/versions`: a directory per release, `current`, `previous`, and `prefix` naming the bin directory that links here.
pub struct Versions {
    pub dir: PathBuf,
}

impl Versions {
    pub fn of(home: &Path) -> Versions {
        Versions { dir: home.join("versions") }
    }

    pub fn version_dir(&self, v: &str) -> PathBuf {
        self.dir.join(v)
    }

    fn binary(&self, v: &str) -> PathBuf {
        self.version_dir(v).join("bin").join("superfluid")
    }

    pub fn current(&self) -> Option<String> {
        let target = std::fs::read_link(self.dir.join("current")).ok()?;
        target.file_name().and_then(|n| n.to_str()).map(str::to_string)
    }

    pub fn previous(&self) -> Option<String> {
        let v = std::fs::read_to_string(self.dir.join("previous")).ok()?.trim().to_string();
        (!v.is_empty() && self.binary(&v).is_file()).then_some(v)
    }

    /// The complete versions here, newest first.
    pub fn on_disk(&self) -> Vec<String> {
        let mut all: Vec<String> = std::fs::read_dir(&self.dir)
            .map(|rd| {
                rd.flatten()
                    .filter_map(|e| e.file_name().to_str().map(str::to_string))
                    .filter(|n| !n.starts_with('.') && n != "current" && n.chars().next().is_some_and(|c| c.is_ascii_digit()))
                    .filter(|n| self.binary(n).is_file())
                    .collect()
            })
            .unwrap_or_default();
        all.sort_by_key(|v| std::cmp::Reverse(release_order(v)));
        all
    }

    pub fn prefix(&self) -> Option<PathBuf> {
        let p = std::fs::read_to_string(self.dir.join("prefix")).ok()?.trim().to_string();
        (!p.is_empty()).then(|| PathBuf::from(p))
    }

    /// Point `current` at `v`, atomically, remembering what it pointed at.
    pub fn set_current(&self, v: &str) -> Result<(), String> {
        if !self.binary(v).is_file() {
            return Err(format!("{} is not an installed version (see `superfluid self list`)", v));
        }
        if let Some(was) = self.current().filter(|was| was != v) {
            std::fs::write(self.dir.join("previous"), format!("{was}\n")).map_err(|e| format!("{}: {e}", self.dir.display()))?;
        }
        let tmp = self.dir.join(".current.tmp");
        let _ = std::fs::remove_file(&tmp);
        std::os::unix::fs::symlink(v, &tmp).map_err(|e| format!("{}: {e}", tmp.display()))?;
        std::fs::rename(&tmp, self.dir.join("current")).map_err(|e| format!("{}: {e}", self.dir.join("current").display()))
    }

    /// Removes every version but `current`, `previous`, one with a `keep` file, and one a running process started from.
    pub fn prune(&self) -> Result<Vec<String>, String> {
        let (current, previous) = (self.current(), self.previous());
        let mut gone = Vec::new();
        for v in self.on_disk() {
            let dir = self.version_dir(&v);
            if Some(&v) == current.as_ref() || Some(&v) == previous.as_ref() || dir.join("keep").exists() || running_from(&dir) {
                continue;
            }
            std::fs::remove_dir_all(&dir).map_err(|e| format!("{}: {e}", dir.display()))?;
            gone.push(v);
        }
        Ok(gone)
    }

    /// The names in `prefix` that are the install script's real files, not links.
    fn legacy_files(&self, prefix: &Path) -> Vec<&'static str> {
        LINKED.iter().copied().filter(|name| prefix.join(name).symlink_metadata().is_ok_and(|m| m.file_type().is_file())).collect()
    }

    /// The links in `prefix`: the three commands through `current`, and `superfluid-<v>` per version. The install script's
    /// real files are replaced on a migration, except `superfluid-workerd` while a server still runs from it (it starts its
    /// workers by that path), which a `migrating` note has the next link finish once nothing runs from there. The note
    /// names the processes that ran from there, by pid and start time: once a link is renamed over a server's own
    /// executable, macOS may give no path for it, and a server found by its path alone would be missed.
    pub fn link(&self, prefix: &Path, replace_files: bool) -> Result<Vec<String>, String> {
        std::fs::create_dir_all(prefix).map_err(|e| format!("{}: {e}", prefix.display()))?;
        std::fs::write(self.dir.join("prefix"), format!("{}\n", prefix.display())).map_err(|e| format!("{}: {e}", self.dir.display()))?;
        let mut notes = Vec::new();
        let pending = self.dir.join("migrating");
        let legacy = self.legacy_files(prefix);
        let migrating = !legacy.is_empty() && (replace_files || pending.exists());
        // A process the note names counts while it is the one that started then, whatever path is given for it now.
        let mut holding: Vec<(i32, u64)> = match migrating {
            true => std::fs::read_to_string(&pending)
                .unwrap_or_default()
                .lines()
                .skip(1)
                .filter_map(|l| l.split_once(' ').and_then(|(p, at)| Some((p.parse().ok()?, at.parse().ok()?))))
                .filter(|&(p, at)| started_at(p) == Some(at))
                .collect(),
            false => Vec::new(),
        };
        if migrating {
            for p in processes_from(prefix) {
                if !holding.contains(&p) {
                    holding.push(p);
                }
            }
        }
        let in_use = !holding.is_empty();
        let replace: Vec<&str> = match (migrating, in_use) {
            (true, true) => vec!["superfluid"],
            (true, false) => LINKED.to_vec(),
            (false, _) => Vec::new(),
        };
        let ours = |link: &Path| std::fs::read_link(link).map(|t| t.starts_with(&self.dir)).unwrap_or(false);
        let relink = |link: &Path, target: &Path| -> Result<(), String> {
            let tmp = link.with_file_name(format!(".{}.tmp", link.file_name().and_then(|n| n.to_str()).unwrap_or("link")));
            let _ = std::fs::remove_file(&tmp);
            std::os::unix::fs::symlink(target, &tmp).map_err(|e| format!("{}: {e}", tmp.display()))?;
            std::fs::rename(&tmp, link).map_err(|e| format!("{}: {e}", link.display()))
        };
        for name in LINKED {
            let link = prefix.join(name);
            let target = self.dir.join("current").join("bin").join(name);
            match link.symlink_metadata() {
                Ok(m) if m.file_type().is_symlink() && ours(&link) => continue,
                Ok(m) if m.file_type().is_symlink() || replace.contains(name) => relink(&link, &target)?,
                Ok(_) if migrating => continue,
                Ok(_) => {
                    notes.push(format!("{} is not a link into {}; left as it is", link.display(), self.dir.display()));
                    continue;
                }
                Err(_) => relink(&link, &target)?,
            }
        }
        if migrating {
            let libexec = prefix.join("..").join("libexec").join("superfluid");
            if in_use {
                let note: String = holding.iter().map(|(p, at)| format!("{p} {at}\n")).collect();
                std::fs::write(&pending, format!("{}\n{note}", prefix.display())).map_err(|e| format!("{}: {e}", pending.display()))?;
                notes.push(format!(
                    "a server still runs from the copy the install script placed in {}: its superfluid-workerd, superfluid-noded and workers stay until it stops; the next update, switch or install finishes the move",
                    prefix.display()
                ));
            } else {
                if let Ok(rd) = std::fs::read_dir(&libexec) {
                    for e in rd.flatten() {
                        let name = e.file_name().to_string_lossy().to_string();
                        if name.starts_with("superfluid-worker-") || name.starts_with("libsuperfluid_tokenizer_") {
                            let _ = std::fs::remove_file(e.path());
                        }
                    }
                    let _ = std::fs::remove_dir(&libexec);
                }
                let _ = std::fs::remove_file(&pending);
                notes.push(format!("the install script's copy in {} now links into {}; its workers were removed", prefix.display(), self.dir.display()));
            }
        } else if pending.exists() && legacy.is_empty() {
            let _ = std::fs::remove_file(&pending);
        }
        let here = self.on_disk();
        for v in &here {
            let link = prefix.join(format!("superfluid-{v}"));
            if !ours(&link) {
                relink(&link, &self.binary(v))?;
            }
        }
        if let Ok(rd) = std::fs::read_dir(prefix) {
            for e in rd.flatten() {
                let name = e.file_name().to_string_lossy().to_string();
                if let Some(v) = name.strip_prefix("superfluid-") {
                    if v.chars().next().is_some_and(|c| c.is_ascii_digit()) && !here.iter().any(|h| h == v) && ours(&e.path()) {
                        let _ = std::fs::remove_file(e.path());
                    }
                }
            }
        }
        Ok(notes)
    }
}

/// Where the running executable came from, which decides who updates it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Installed {
    /// `<home>/versions/<v>/bin/superfluid`: ours to update.
    Managed { versions: PathBuf, version: String },
    /// The install script's layout before versions existed: real files in `<prefix>/bin` and `<prefix>/libexec/superfluid`.
    InPlace { prefix: PathBuf },
    /// A package manager (an `installed-by` file says which), `cargo install`, or a source build.
    Other(PathBuf),
}

pub fn installed_as(exe: &Path) -> Installed {
    let exe = std::fs::canonicalize(exe).unwrap_or_else(|_| exe.to_path_buf());
    let parts: Vec<&std::ffi::OsStr> = exe.iter().collect();
    let n = parts.len();
    if n >= 4 && parts[n - 2] == "bin" && parts[n - 4] == "versions" {
        let versions = exe.ancestors().nth(3).map(Path::to_path_buf).unwrap_or_default();
        return Installed::Managed { versions, version: parts[n - 3].to_string_lossy().to_string() };
    }
    if let Some(prefix) = exe.parent().filter(|b| b.file_name().is_some_and(|n| n == "bin")).and_then(Path::parent) {
        // A package keeps the release's layout too, so it is told apart by its file, not by where it is.
        if prefix.join(INSTALLED_BY).is_file() || prefix.join(BASERT_STAMP).is_file() {
            return Installed::Other(exe);
        }
        if prefix.join("libexec").join("superfluid").is_dir() {
            return Installed::InPlace { prefix: prefix.to_path_buf() };
        }
    }
    Installed::Other(exe)
}

/// The package manager that installed `exe` and the command that updates it, from the `installed-by` file at the root
/// of its release.
fn package_manager(exe: &Path) -> Option<(String, String)> {
    let line = std::fs::read_to_string(exe.parent()?.parent()?.join(INSTALLED_BY)).ok()?;
    let (manager, command) = line.trim().split_once(": ")?;
    Some((manager.trim().to_string(), command.trim().to_string()))
}

/// The command that updates the running superfluid, for the line `serve` prints when a newer release is out.
fn update_command(exe: &Path) -> String {
    let exe = std::fs::canonicalize(exe).unwrap_or_else(|_| exe.to_path_buf());
    match installed_as(&exe) {
        Installed::Other(p) => delegate(&p).map(|d| d.command().to_string()),
        _ => None,
    }
    .unwrap_or_else(|| "superfluid self update".to_string())
}

fn not_ours(exe: &Path) -> String {
    let p = exe.to_string_lossy();
    if let Some(d) = delegate(exe) {
        return format!("{p} was installed by {}; `{}` updates it", d.manager(), d.command());
    }
    let how = if p.contains("/target/") { "it is a source build: build it again" } else { "update it the way it was installed" };
    format!("{p} was not installed by the install script or by `superfluid self update`; {how}")
}

/// How a copy another tool installed is updated: by that tool's own command, which `self update` runs (after asking),
/// or which it only names, saying why. The command is built here from the manager's name, never read from the
/// `installed-by` file, whose text is for showing.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Delegate {
    /// `argv` is run, its binary found from the copy's own path so that it is the installation that owns the copy;
    /// `path_first` goes first on PATH (npm's `node`, beside it). `command` is what a user would type.
    Run { manager: String, command: String, argv: Vec<String>, path_first: Option<PathBuf> },
    Name { manager: String, command: String, why: String },
}

impl Delegate {
    fn manager(&self) -> &str {
        match self {
            Delegate::Run { manager, .. } | Delegate::Name { manager, .. } => manager,
        }
    }

    fn command(&self) -> &str {
        match self {
            Delegate::Run { command, .. } | Delegate::Name { command, .. } => command,
        }
    }
}

/// The delegate for the copy at the real path `exe` (`<root>/bin/superfluid`), from the manager its `installed-by`
/// file names, or from where it is for packages published before they carried the file; `None` for a copy no package
/// manager or basert placed.
fn delegate(exe: &Path) -> Option<Delegate> {
    let p = exe.to_string_lossy().into_owned();
    let bin = exe.parent()?;
    let root = bin.parent()?;
    // pipx and uv keep the wheel in a venv of their own, whose file says pip.
    if p.contains("/pipx/venvs/") {
        return Some(on_path("pipx", &["upgrade", "superfluid-cli"]));
    }
    if p.contains("/uv/tools/") {
        return Some(on_path("uv", &["tool", "upgrade", "superfluid-cli"]));
    }
    let named = package_manager(exe);
    Some(match named.as_ref().map(|(m, _)| m.to_ascii_lowercase()).as_deref() {
        Some("basert") => basert(root),
        Some("homebrew" | "brew") => homebrew(&p),
        Some("npm") => npm(&p),
        Some("pip") => pip(&p),
        Some("cargo") => cargo(bin),
        Some(_) => {
            let (manager, command) = named?;
            Delegate::Name { manager, command, why: "superfluid runs only Homebrew, npm, pipx, uv, cargo and basert itself".into() }
        }
        None if root.join(BASERT_STAMP).is_file() => basert(root),
        None if p.contains("/Cellar/") => homebrew(&p),
        None if p.contains("/node_modules/") => npm(&p),
        None if p.contains("/site-packages/") => pip(&p),
        None if p.contains("/.cargo/bin/") => cargo(bin),
        None => return None,
    })
}

/// Whether this user may write `path`, as the manager would need to.
fn writable(path: &Path) -> bool {
    use std::os::unix::ffi::OsStrExt;
    let Ok(c) = std::ffi::CString::new(path.as_os_str().as_bytes()) else { return false };
    // SAFETY: `c` is a NUL-terminated path that outlives the call.
    unsafe { libc::access(c.as_ptr(), libc::W_OK) == 0 }
}

fn executable(path: &Path) -> bool {
    use std::os::unix::fs::PermissionsExt;
    std::fs::metadata(path).is_ok_and(|m| m.is_file() && m.permissions().mode() & 0o111 != 0)
}

/// `tool args…` with `tool` from PATH, or named when PATH has none.
fn on_path(tool: &str, args: &[&str]) -> Delegate {
    let command = std::iter::once(tool).chain(args.iter().copied()).collect::<Vec<_>>().join(" ");
    let found = std::env::var_os("PATH").and_then(|path| std::env::split_paths(&path).map(|d| d.join(tool)).find(|p| executable(p)));
    match found {
        Some(bin) => Delegate::Run {
            manager: tool.to_string(),
            command,
            argv: std::iter::once(bin.display().to_string()).chain(args.iter().map(|a| a.to_string())).collect(),
            path_first: None,
        },
        None => Delegate::Name { manager: tool.to_string(), why: format!("no {tool} on PATH"), command },
    }
}

/// The superfluid basert installs for `basert serve` (`<basert dir>/superfluid`, or basert's data directory): basert
/// picks the release that serves its engine. Run by the basert beside it, else the one on PATH.
fn basert(root: &Path) -> Delegate {
    let beside = root.parent().map(|d| d.join("basert")).filter(|b| executable(b));
    match beside {
        Some(b) => Delegate::Run {
            manager: "basert".into(),
            command: "basert superfluid install".into(),
            argv: vec![b.display().to_string(), "superfluid".into(), "install".into()],
            path_first: None,
        },
        None => match on_path("basert", &["superfluid", "install"]) {
            Delegate::Name { command, why, .. } => Delegate::Name { manager: "basert".into(), command, why },
            run => run,
        },
    }
}

/// `brew upgrade <formula>` by the Homebrew whose Cellar holds the copy, unless the formula is pinned or that Homebrew
/// is another user's.
fn homebrew(p: &str) -> Delegate {
    let manager = "Homebrew".to_string();
    let Some(i) = p.find("/Cellar/") else {
        let why = "the Homebrew it came from cannot be told from where it is".to_string();
        return Delegate::Name { manager, command: "brew upgrade superfluid".into(), why };
    };
    let prefix = Path::new(&p[..i]);
    let formula = p[i + "/Cellar/".len()..].split('/').next().unwrap_or("superfluid");
    let command = format!("brew upgrade {formula}");
    let brew = prefix.join("bin").join("brew");
    let why = if !executable(&brew) {
        format!("there is no {}", brew.display())
    } else if prefix.join("var/homebrew/pinned").join(formula).exists() {
        format!("it is pinned in Homebrew: `brew unpin {formula}` first")
    } else if !writable(&prefix.join("Cellar")) {
        format!("the Homebrew in {} is another user's", prefix.display())
    } else {
        let argv = vec![brew.display().to_string(), "upgrade".into(), formula.into()];
        return Delegate::Run { manager, command, argv, path_first: None };
    };
    Delegate::Name { manager, command, why }
}

/// `npm install --global` by the npm whose global folder holds the copy, told that folder's prefix (npm's
/// configuration or NPM_CONFIG_PREFIX may name another); a project's dependency (or pnpm's, yarn's, bun's) is that
/// project's to update.
fn npm(p: &str) -> Delegate {
    let manager = "npm".to_string();
    let command = "npm install --global @basecompute/superfluid@latest".to_string();
    let Some(i) = p.find("/lib/node_modules/") else {
        let why = "it is a project's dependency (or pnpm's, yarn's or bun's): update it in that project".to_string();
        return Delegate::Name { manager, command: "npm install @basecompute/superfluid@latest".into(), why };
    };
    let prefix = Path::new(&p[..i]);
    let bin = prefix.join("bin");
    let npm = bin.join("npm");
    let why = if !executable(&npm) {
        format!("there is no {}", npm.display())
    } else if !writable(&prefix.join("lib").join("node_modules")) {
        format!("npm's global folder in {} needs root to write: run it yourself", prefix.display())
    } else {
        let argv = vec![
            npm.display().to_string(),
            "install".into(),
            "--global".into(),
            "--prefix".into(),
            prefix.display().to_string(),
            "@basecompute/superfluid@latest".into(),
        ];
        return Delegate::Run { manager, command, argv, path_first: Some(bin) };
    };
    Delegate::Name { manager, command, why }
}

/// pip is only named: the environment may be a project's, which a lock file (Poetry, uv, pip-tools) pins, or the
/// system's, which refuses or needs root.
fn pip(p: &str) -> Delegate {
    // .../<env>/lib/python3.x/site-packages/superfluid_cli/release/bin/superfluid
    let python = p.find("/lib/python").map(|i| Path::new(&p[..i]).join("bin").join("python")).filter(|py| executable(py));
    let command = match python {
        Some(py) => format!("{} -m pip install --upgrade superfluid-cli", py.display()),
        None => "pip install --upgrade superfluid-cli".to_string(),
    };
    let why = "its environment may be a project's, pinned by a lock file, or the system's: run it in that environment yourself";
    Delegate::Name { manager: "pip".into(), command, why: why.into() }
}

/// `cargo install superfluid` by the cargo beside the copy.
fn cargo(bin: &Path) -> Delegate {
    let cargo = bin.join("cargo");
    if !executable(&cargo) {
        return on_path("cargo", &["install", "superfluid"]);
    }
    let argv = vec![cargo.display().to_string(), "install".into(), "superfluid".into()];
    Delegate::Run { manager: "cargo".into(), command: "cargo install superfluid".into(), argv, path_first: Some(bin.to_path_buf()) }
}

/// A yes/no question on stderr, answered on stdin; an empty answer is yes.
fn confirm(question: &str) -> Result<bool, String> {
    eprint!("{question}");
    let _ = std::io::stderr().flush();
    let mut answer = String::new();
    std::io::stdin().lock().read_line(&mut answer).map_err(|e| format!("reading the answer: {e}"))?;
    Ok(matches!(answer.trim().to_ascii_lowercase().as_str(), "" | "y" | "yes"))
}

/// `self update` of a copy another tool installed: its manager's command, run after asking (or with `--yes`) when it
/// is one superfluid runs, else named. Nothing runs while a server runs from the copy, which the manager replaces.
/// basert is handed off to (`Report::hand_off`) rather than run: it refuses to replace a copy that anything runs from,
/// this process included.
fn update_by_manager(exe: &Path, opts: &Options) -> Result<Report, String> {
    let mut report = Report::default();
    let Some(plan) = delegate(exe) else { return Err(not_ours(exe)) };
    let p = exe.display();
    let (manager, command, argv, path_first) = match (plan, &opts.version) {
        (Delegate::Name { manager, command, why }, _) => return Err(format!("{p} was installed by {manager}, which updates it: run `{command}` ({why})")),
        (Delegate::Run { manager, command, .. }, Some(_)) if manager == "basert" => {
            return Err(format!("{p} is basert's, which picks the release that serves its engine: `{command}` updates it"))
        }
        (Delegate::Run { manager, command, .. }, Some(_)) => {
            return Err(format!("{p} was installed by {manager}, which chooses its version: `{command}` updates it, and a version is pinned there"))
        }
        (Delegate::Run { manager, command, argv, path_first }, None) => (manager, command, argv, path_first),
    };
    let shown = argv.join(" ");
    if opts.dry_run {
        report.say(format!("{p} was installed by {manager}: `self update` would run {shown}"));
        return Ok(report);
    }
    // Its workers start from the copy's own directories; only superfluid's programs count (a cargo install shares
    // ~/.cargo/bin with other tools).
    let root = exe.parent().and_then(Path::parent).unwrap_or(Path::new("/"));
    let watched = if manager == "cargo" { exe.parent().unwrap_or(root) } else { root };
    let watched = std::fs::canonicalize(watched).unwrap_or_else(|_| watched.to_path_buf());
    let idle = || -> Result<(), String> {
        let busy: Vec<String> = other_processes()
            .into_iter()
            .filter(|(_, e)| e.starts_with(&watched) && e.file_name().and_then(|n| n.to_str()).is_some_and(|n| n.starts_with("superfluid")))
            .map(|(pid, _)| pid.to_string())
            .collect();
        if busy.is_empty() {
            return Ok(());
        }
        Err(format!("a server runs from {} (pid {}), which `{command}` replaces: stop it, then run this again", watched.display(), busy.join(", ")))
    };
    idle()?;
    if !opts.yes {
        if !(std::io::stdin().is_terminal() && std::io::stderr().is_terminal()) {
            return Err(format!("{p} was installed by {manager}: run `{command}`, or `superfluid self update --yes` to let superfluid run it"));
        }
        if !confirm(&format!("superfluid: {p} was installed by {manager}. Run `{shown}`? [Y/n] "))? {
            return Err(format!("nothing was run; `{command}` updates it"));
        }
        // The question may have waited long enough for a server to start.
        idle()?;
    }
    if manager == "cargo" {
        eprintln!("superfluid: cargo builds superfluid from source: this takes a few minutes");
    }
    eprintln!("superfluid: running {shown}");
    let mut run = Command::new(&argv[0]);
    run.args(&argv[1..]);
    if let Some(first) = path_first {
        let rest = std::env::var_os("PATH").unwrap_or_default();
        let path = std::env::join_paths(std::iter::once(first).chain(std::env::split_paths(&rest))).map_err(|e| e.to_string())?;
        run.env("PATH", path);
    }
    if manager == "basert" {
        report.hand_off = Some(run);
        return Ok(report);
    }
    let status = crate::exec::when_not_busy(|| run.status()).map_err(|e| format!("running {}: {e}", argv[0]))?;
    if !status.success() {
        return Err(format!("`{shown}` failed ({status})"));
    }
    report.changed = true;
    report.say(format!("{manager} updated it"));
    Ok(report)
}


#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Release {
    pub version: String,
    /// YYYY-MM-DD
    pub published: String,
    pub tarball: Asset,
    pub sha256_url: String,
    /// The basert engine ABI the release declares in an asset name.
    pub abi: Option<u32>,
    pub compat_url: Option<String>,
}

/// The releases of the listing with a tarball for `target`, newest first; drafts and prereleases left out.
pub fn releases(listing: &Value, target: &str) -> Vec<Release> {
    let tar = format!("superfluid-{target}.tar.gz");
    let mut out: Vec<Release> = listing
        .as_array()
        .map(|a| a.iter().filter_map(|r| release_of(r, &tar, target)).collect())
        .unwrap_or_default();
    out.sort_by_key(|r| std::cmp::Reverse(release_order(&r.version)));
    out
}

fn release_of(r: &Value, tar: &str, target: &str) -> Option<Release> {
    if r["draft"].as_bool().unwrap_or(false) || r["prerelease"].as_bool().unwrap_or(false) {
        return None;
    }
    let version = r["tag_name"].as_str()?.trim_start_matches('v').to_string();
    if !is_version(&version) {
        return None;
    }
    let assets = r["assets"].as_array()?;
    let url = |name: &str| assets.iter().find(|a| a["name"] == name).and_then(|a| a["browser_download_url"].as_str()).map(str::to_string);
    let size = assets.iter().find(|a| a["name"] == tar).and_then(|a| a["size"].as_u64());
    let abi = assets.iter().find_map(|a| a["name"].as_str()?.strip_prefix("superfluid-basert-abi-")?.strip_suffix(".txt")?.parse().ok());
    Some(Release {
        published: r["published_at"].as_str().unwrap_or_default().chars().take(10).collect(),
        tarball: Asset { name: tar.to_string(), url: url(tar)?, sha256: None, size },
        sha256_url: url(&format!("{tar}.sha256"))?,
        abi,
        compat_url: url(&format!("superfluid-{target}.compat.json")),
        version,
    })
}

/// What a release must declare to drive the baseRT engine here.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Engine {
    /// No engine, or none this superfluid can tell: the newest release fits.
    None,
    Abi(u32),
    /// A 0.3.x engine, which states no number: the release must accept that line.
    Unnumbered(String),
}

pub fn engine_here(catalog: &Catalog) -> Engine {
    if std::env::var_os("BASERT_LIB").is_none() && !catalog.package_dir(RuntimeId::new("basert")).is_dir() {
        return Engine::None;
    }
    match catalog.inspect(RuntimeId::new("basert")).usable {
        Ok(rt) => match (rt.abi, rt.version.as_deref()) {
            (Some(n), _) => Engine::Abi(n as u32),
            (None, Some(v)) => Engine::Unnumbered(v.split(|c: char| !c.is_ascii_digit() && c != '.').next().unwrap_or("").split('.').take(2).collect::<Vec<_>>().join(".")),
            (None, None) => Engine::None,
        },
        Err(_) => Engine::None,
    }
}

impl Engine {
    pub fn describe(&self) -> String {
        match self {
            Engine::None => "no baseRT engine here".into(),
            Engine::Abi(n) => format!("the baseRT engine here states ABI {n}"),
            Engine::Unnumbered(minor) => format!("the baseRT engine here is {minor}.x and states no ABI"),
        }
    }
}

/// Whether `release` drives the engine; `compat` fetches its compat.json when the asset names alone do not say.
pub fn fits(release: &Release, engine: &Engine, compat: &dyn Fn(&str) -> Option<Value>) -> bool {
    match engine {
        Engine::None => true,
        Engine::Abi(n) => match release.abi {
            Some(have) => have == *n,
            None => release.compat_url.as_deref().and_then(compat).and_then(|c| c["runtimes"]["basert"]["abi"].as_u64()) == Some(u64::from(*n)),
        },
        Engine::Unnumbered(minor) => release
            .compat_url
            .as_deref()
            .and_then(compat)
            .and_then(|c| c["runtimes"]["basert"]["unnumbered_minor"].as_str().map(str::to_string))
            .is_some_and(|m| m == *minor),
    }
}

/// The newest release that fits, skipping ones published fewer than `hold_off` days ago when given.
pub fn newest<'a>(releases: &'a [Release], engine: &Engine, hold_off: Option<i64>, compat: &dyn Fn(&str) -> Option<Value>) -> Option<&'a Release> {
    releases.iter().find(|r| hold_off.is_none_or(|days| age_days(&r.published).is_some_and(|age| age >= days)) && fits(r, engine, compat))
}

/// The release listing to read: `SUPERFLUID_RELEASES`, else GitHub's.
pub fn listing_source() -> String {
    std::env::var(LISTING_ENV).ok().filter(|s| !s.is_empty()).unwrap_or_else(|| LISTING.to_string())
}

/// A small text or JSON document: a file, or an https URL through curl.
fn get_text(url: &str, max_time: u32) -> Result<String, String> {
    if let Some(path) = url.strip_prefix("file://").or_else(|| (!url.contains("://")).then_some(url)) {
        return std::fs::read_to_string(path).map_err(|e| format!("{path}: {e}"));
    }
    if !url.starts_with("https://") {
        return Err(format!("{url}: only https:// URLs are fetched"));
    }
    let out = Command::new("curl")
        .args(["-fsSL", "--proto", "=https", "--tlsv1.2", "--max-time", &max_time.to_string(), "-H", "Accept: application/vnd.github+json"])
        .arg(url)
        .output()
        .map_err(|e| format!("curl: {e}"))?;
    if !out.status.success() {
        return Err(format!("fetching {url} failed: {}", String::from_utf8_lossy(&out.stderr).trim()));
    }
    Ok(String::from_utf8_lossy(&out.stdout).to_string())
}

fn get_json(url: &str, max_time: u32) -> Result<Value, String> {
    serde_json::from_str(&get_text(url, max_time)?).map_err(|e| format!("{url}: {e}"))
}

pub fn fetch_releases(source: &str, target: &str, max_time: u32) -> Result<Vec<Release>, String> {
    let listing = get_json(source, max_time)?;
    let found = releases(&listing, target);
    if found.is_empty() {
        return Err(format!("{source} lists no release with a superfluid-{target}.tar.gz"));
    }
    Ok(found)
}

fn compat_fetcher(max_time: u32) -> impl Fn(&str) -> Option<Value> {
    move |url: &str| get_json(url, max_time).ok()
}


fn days_from_civil(y: i64, m: i64, d: i64) -> i64 {
    let y = if m <= 2 { y - 1 } else { y };
    let era = if y >= 0 { y } else { y - 399 } / 400;
    let yoe = y - era * 400;
    let mp = (m + 9) % 12;
    let doy = (153 * mp + 2) / 5 + d - 1;
    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
    era * 146097 + doe - 719468
}

fn age_days(published: &str) -> Option<i64> {
    let mut parts = published.split('-').map(|p| p.parse::<i64>().ok());
    let (y, m, d) = (parts.next()??, parts.next()??, parts.next()??);
    let today = (SystemTime::now().duration_since(UNIX_EPOCH).ok()?.as_secs() / 86_400) as i64;
    Some(today - days_from_civil(y, m, d))
}

fn now_secs() -> u64 {
    SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_secs()).unwrap_or(0)
}


/// The other processes on this machine, each with its executable as a real path.
#[cfg(target_os = "linux")]
fn other_processes() -> Vec<(i32, PathBuf)> {
    let me = std::process::id() as i32;
    std::fs::read_dir("/proc")
        .map(|rd| {
            rd.flatten()
                .filter_map(|e| e.file_name().to_str()?.parse::<i32>().ok().filter(|&p| p != me).map(|p| (p, e.path())))
                .filter_map(|(p, dir)| Some((p, std::fs::read_link(dir.join("exe")).ok()?)))
                .collect()
        })
        .unwrap_or_default()
}

/// When `pid` started, in clock ticks since boot: with the pid, what tells a process from a later one given its number.
#[cfg(target_os = "linux")]
fn started_at(pid: i32) -> Option<u64> {
    let stat = std::fs::read_to_string(format!("/proc/{pid}/stat")).ok()?;
    // The command name, in parentheses, may hold spaces; the start time is the 20th field after it.
    stat.rsplit_once(')')?.1.split_whitespace().nth(19)?.parse().ok()
}

#[cfg(target_os = "macos")]
fn other_processes() -> Vec<(i32, PathBuf)> {
    let me = std::process::id() as libc::c_int;
    // SAFETY: with a null buffer, proc_listallpids only reports how many pids there are.
    let n = unsafe { libc::proc_listallpids(std::ptr::null_mut(), 0) };
    if n <= 0 {
        return Vec::new();
    }
    let mut pids = vec![0 as libc::c_int; n as usize * 2 + 16];
    let bytes = (pids.len() * std::mem::size_of::<libc::c_int>()) as libc::c_int;
    // SAFETY: the buffer is this function's, and its size in bytes is what is passed.
    let got = unsafe { libc::proc_listallpids(pids.as_mut_ptr() as *mut libc::c_void, bytes) };
    pids.truncate(got.max(0) as usize);
    pids.into_iter()
        .filter(|&p| p > 0 && p != me)
        .filter_map(|p| {
            let mut buf = vec![0u8; 4096];
            // SAFETY: proc_pidpath writes at most the buffer's length, which it is told.
            let len = unsafe { libc::proc_pidpath(p, buf.as_mut_ptr() as *mut libc::c_void, buf.len() as u32) };
            (len > 0).then(|| (p, PathBuf::from(String::from_utf8_lossy(&buf[..len as usize]).to_string())))
        })
        .collect()
}

/// When `pid` started, in microseconds since the epoch.
#[cfg(target_os = "macos")]
fn started_at(pid: i32) -> Option<u64> {
    // SAFETY: proc_bsdinfo is plain data, for which all zeroes is a value.
    let mut info: libc::proc_bsdinfo = unsafe { std::mem::zeroed() };
    let size = std::mem::size_of::<libc::proc_bsdinfo>() as libc::c_int;
    // SAFETY: proc_pidinfo writes at most `size` bytes into `info`, which is that big.
    let got = unsafe { libc::proc_pidinfo(pid, libc::PROC_PIDTBSDINFO, 0, &mut info as *mut _ as *mut libc::c_void, size) };
    (got == size).then(|| info.pbi_start_tvsec * 1_000_000 + info.pbi_start_tvusec)
}

#[cfg(not(any(target_os = "linux", target_os = "macos")))]
fn other_processes() -> Vec<(i32, PathBuf)> {
    Vec::new()
}

#[cfg(not(any(target_os = "linux", target_os = "macos")))]
fn started_at(_pid: i32) -> Option<u64> {
    None
}

/// Whether another process runs an executable under `dir`.
pub fn running_from(dir: &Path) -> bool {
    !processes_from(dir).is_empty()
}

/// The other processes running an executable under `dir`, by pid and when each started.
fn processes_from(dir: &Path) -> Vec<(i32, u64)> {
    let Ok(dir) = std::fs::canonicalize(dir) else { return Vec::new() };
    other_processes().into_iter().filter(|(_, exe)| exe.starts_with(&dir)).map(|(p, _)| (p, started_at(p).unwrap_or(0))).collect()
}


#[derive(Debug, Default, Clone)]
pub struct Options {
    pub version: Option<String>,
    pub dry_run: bool,
    /// For a copy another tool installed: run its update without asking.
    pub yes: bool,
    /// The release listing; `listing_source()` when not set.
    pub source: Option<String>,
}

/// What `self update` did, line by line.
#[derive(Debug, Default)]
pub struct Report {
    pub lines: Vec<String>,
    pub changed: bool,
    /// The command `superfluid self update` replaces itself with, its own update left to that command.
    pub hand_off: Option<Command>,
}

impl Report {
    fn say(&mut self, line: impl Into<String>) {
        self.lines.push(line.into());
    }
}

/// `cmd`'s output, or an error once it has run for `limit`, when it is killed.
fn output_within(cmd: &mut Command, limit: Duration) -> Result<Output, String> {
    let what = cmd.get_program().to_string_lossy().to_string();
    match crate::exec::output_within(cmd, limit) {
        Ok(Some(out)) => Ok(out),
        Ok(None) => Err(format!("{what} did not answer within {}s", limit.as_secs())),
        Err(e) => Err(format!("{what}: {e}")),
    }
}

fn version_of(binary: &Path) -> Result<String, String> {
    let out = output_within(Command::new(binary).arg("--version"), PROBE_TIMEOUT)?;
    let text = String::from_utf8_lossy(&out.stdout);
    text.split_whitespace().nth(1).map(str::to_string).filter(|v| out.status.success() && is_version(v)).ok_or_else(|| {
        format!("{} did not say its version ({}): {}", binary.display(), out.status, String::from_utf8_lossy(&out.stderr).trim())
    })
}

/// The proof a host runs: the copy's `--version` and `runtimes --json`, the basert row ready when an engine is in use.
fn probe(versions: &Versions, v: &str, home: &Path, engine: &Engine) -> Result<(), String> {
    probe_binary(&versions.binary(v), v, home, engine)
}

/// The same proof of a copy wherever it is, so a replacement is proved before anything it replaces is touched.
fn probe_binary(binary: &Path, v: &str, home: &Path, engine: &Engine) -> Result<(), String> {
    // A copy cut short can hold the command and nothing beside it; it starts, and its server finds no workerd.
    if !binary.with_file_name("superfluid-workerd").is_file() {
        return Err(format!("{} has no superfluid-workerd beside it", binary.display()));
    }
    let said = version_of(binary)?;
    if said != v {
        return Err(format!("{} says it is {said}, not {v}", binary.display()));
    }
    let out = output_within(Command::new(binary).args(["runtimes", "--json"]).env("SUPERFLUID_HOME", home).env(NO_CHECK_ENV, "1"), PROBE_TIMEOUT)?;
    if !out.status.success() {
        return Err(format!("{} runtimes --json failed ({}): {}", binary.display(), out.status, String::from_utf8_lossy(&out.stderr).trim()));
    }
    if *engine != Engine::None {
        let rows: Value = serde_json::from_slice(&out.stdout).map_err(|e| format!("{} runtimes --json: {e}", binary.display()))?;
        let basert = rows.as_array().and_then(|a| a.iter().find(|r| r["id"] == "basert"));
        match basert.map(|r| &r["ready"]) {
            Some(Value::Bool(true)) => {}
            Some(Value::String(why)) => return Err(format!("{v} cannot drive the engine here: {why}")),
            _ => return Err(format!("{v} reports no basert runtime, which this machine serves with")),
        }
    }
    Ok(())
}

fn move_tree(from: &Path, to: &Path) -> Result<(), String> {
    if std::fs::rename(from, to).is_ok() {
        return Ok(());
    }
    copy_tree(from, to)?;
    std::fs::remove_dir_all(from).map_err(|e| format!("{}: {e}", from.display()))
}

fn copy_tree(from: &Path, to: &Path) -> Result<(), String> {
    std::fs::create_dir_all(to).map_err(|e| format!("{}: {e}", to.display()))?;
    for e in std::fs::read_dir(from).map_err(|e| format!("{}: {e}", from.display()))?.flatten() {
        let (src, dest) = (e.path(), to.join(e.file_name()));
        let kind = e.file_type().map_err(|e| format!("{}: {e}", src.display()))?;
        if kind.is_dir() {
            copy_tree(&src, &dest)?;
        } else if kind.is_symlink() {
            let target = std::fs::read_link(&src).map_err(|e| format!("{}: {e}", src.display()))?;
            std::os::unix::fs::symlink(target, &dest).map_err(|e| format!("{}: {e}", dest.display()))?;
        } else {
            std::fs::copy(&src, &dest).map_err(|e| format!("{} -> {}: {e}", src.display(), dest.display()))?;
        }
    }
    Ok(())
}

/// Download, check and unpack `release` into the layout; nothing is placed until the whole tree is verified, and what
/// was downloaded goes whether or not it was placed.
fn place(versions: &Versions, release: &Release, report: &mut Report) -> Result<(), String> {
    let staging = versions.dir.join(".staging").join(&release.version);
    let _ = std::fs::remove_dir_all(&staging);
    let placed = place_through(versions, release, &staging, report);
    let _ = std::fs::remove_dir_all(&staging);
    placed
}

fn place_through(versions: &Versions, release: &Release, staging: &Path, report: &mut Report) -> Result<(), String> {
    let v = &release.version;
    std::fs::create_dir_all(staging).map_err(|e| format!("{}: {e}", staging.display()))?;
    let want = get_text(&release.sha256_url, 30)?.split_whitespace().next().unwrap_or_default().to_ascii_lowercase();
    if want.len() != 64 || !want.bytes().all(|b| b.is_ascii_hexdigit()) {
        return Err(format!("{}: not a SHA-256", release.sha256_url));
    }
    let asset = Asset { sha256: Some(want), ..release.tarball.clone() };
    report.say(format!("downloading {} ({})", asset.name, asset.size.map(|s| format!("{:.1} MB", s as f64 / 1e6)).unwrap_or_else(|| "size unknown".into())));
    let (archive, _) = fetch(&asset, staging)?;
    let unpacked = staging.join("unpacked");
    unpack(&archive, &unpacked)?;
    let top = single_top(&unpacked)?;
    for needed in ["bin/superfluid", "bin/superfluid-workerd"] {
        if !top.join(needed).is_file() {
            return Err(format!("{} holds no {needed}", asset.name));
        }
    }
    let dest = versions.version_dir(v);
    let _ = std::fs::remove_dir_all(&dest);
    // A move cut short across filesystems leaves part of a tree, which is not a version.
    move_tree(&top, &dest).inspect_err(|_| {
        let _ = std::fs::remove_dir_all(&dest);
    })
}

/// The install script's in-place copy, kept under the layout as the version to go back to. It is copied beside the
/// layout and moved in whole, so a copy cut short (a full disk, an interrupt) is never taken for the version and its
/// original workers are not removed for it; a version missing a file of the copy is copied again.
fn keep_in_place(versions: &Versions, prefix: &Path) -> Result<String, String> {
    let bin = prefix.join("bin");
    let libexec = prefix.join("libexec").join("superfluid");
    let old = version_of(&bin.join("superfluid"))?;
    let dest = versions.version_dir(&old);
    if holds_in_place(&dest, &bin, &libexec) {
        return Ok(old);
    }
    let staging = versions.dir.join(".staging").join(format!("kept-{old}"));
    let _ = std::fs::remove_dir_all(&staging);
    let copied = (|| {
        std::fs::create_dir_all(staging.join("bin")).map_err(|e| format!("{}: {e}", staging.display()))?;
        for name in LINKED {
            let src = bin.join(name);
            if src.is_file() {
                std::fs::copy(&src, staging.join("bin").join(name)).map_err(|e| format!("{}: {e}", src.display()))?;
            }
        }
        if libexec.is_dir() {
            copy_tree(&libexec, &staging.join("libexec").join("superfluid"))?;
        }
        let _ = std::fs::remove_dir_all(&dest);
        std::fs::rename(&staging, &dest).map_err(|e| format!("{} -> {}: {e}", staging.display(), dest.display()))
    })();
    if copied.is_err() {
        let _ = std::fs::remove_dir_all(&staging);
    }
    copied.map(|()| old)
}

/// Whether `dest` holds every command and worker of the in-place copy in `bin` and `libexec`.
fn holds_in_place(dest: &Path, bin: &Path, libexec: &Path) -> bool {
    let commands = LINKED.iter().filter(|name| bin.join(name).is_file()).all(|name| dest.join("bin").join(name).is_file());
    let workers = std::fs::read_dir(libexec)
        .map(|rd| rd.flatten().all(|e| dest.join("libexec").join("superfluid").join(e.file_name()).exists()))
        .unwrap_or(true);
    dest.join("bin").join("superfluid").is_file() && commands && workers
}

/// The install script's in-place copies become links into the layout (see `Versions::link` for a running server).
fn migrate(versions: &Versions, prefix: &Path, report: &mut Report) -> Result<(), String> {
    for note in versions.link(&prefix.join("bin"), true)? {
        report.say(note);
    }
    report.say(format!("the copy the install script placed in {}/bin is kept under {} as the version to go back to", prefix.display(), versions.dir.display()));
    Ok(())
}

/// `from` takes the place of `dest`, set aside until `from` is in place; a failed move leaves nothing at `dest` and
/// brings the copy back, and if that fails too both failures are reported.
fn replace_tree(from: &Path, dest: &Path, aside: &Path, mover: impl Fn(&Path, &Path) -> Result<(), String>) -> Result<(), String> {
    let _ = std::fs::remove_dir_all(aside);
    let had = dest.exists();
    if had {
        std::fs::rename(dest, aside).map_err(|e| format!("{}: {e}", dest.display()))?;
    }
    match mover(from, dest) {
        Ok(()) => {
            let _ = std::fs::remove_dir_all(aside);
            Ok(())
        }
        Err(e) => {
            let _ = std::fs::remove_dir_all(dest);
            if had {
                if let Err(back) = std::fs::rename(aside, dest) {
                    return Err(format!("{e}; and {} could not be put back from {}: {back}", dest.display(), aside.display()));
                }
            }
            Err(e)
        }
    }
}

/// The older versions removed, once the new one is current: one that cannot be removed is said, not an error, since
/// the update itself is done; the next prune tries it again.
fn prune_older(versions: &Versions, report: &mut Report) {
    match versions.prune() {
        Ok(gone) if !gone.is_empty() => report.say(format!("removed {}", gone.join(", "))),
        Ok(_) => {}
        Err(e) => report.say(format!("an older version was not removed ({e}); the next update tries again")),
    }
}

/// `self update`: the newest release that fits, or the one named.
pub fn update(home: &Path, catalog: &Catalog, exe: &Path, opts: &Options) -> Result<Report, String> {
    let mut report = Report::default();
    let installed = installed_as(exe);
    let (versions, migrating) = match &installed {
        Installed::Managed { versions, .. } => (Versions { dir: versions.clone() }, None),
        Installed::InPlace { prefix } => (Versions::of(home), Some(prefix.clone())),
        Installed::Other(p) => return update_by_manager(p, opts),
    };
    let target = target().ok_or_else(|| format!("no release is published for {} {}", std::env::consts::OS, std::env::consts::ARCH))?;
    // Taken before anything is read or decided, so an update queued behind another sees the layout it left.
    let _one_at_a_time = match opts.dry_run {
        true => None,
        false => {
            std::fs::create_dir_all(&versions.dir).map_err(|e| format!("{}: {e}", versions.dir.display()))?;
            Some(crate::pulls::Lock::take(&versions.dir, "self", "update of superfluid")?)
        }
    };
    let engine = engine_here(catalog);
    let compat = compat_fetcher(15);
    let found = fetch_releases(opts.source.as_deref().unwrap_or(&listing_source()), target, 30)?;
    let chosen = match &opts.version {
        Some(want) => {
            let want = want.trim_start_matches('v');
            let r = found.iter().find(|r| r.version == want).ok_or_else(|| {
                format!("no release {want} for {target} (the newest is {})", found.first().map(|r| r.version.as_str()).unwrap_or("none"))
            })?;
            if !fits(r, &engine, &compat) {
                return Err(format!("{want} does not declare support for the engine here ({}); `superfluid runtimes --json` shows what this build requires", engine.describe()));
            }
            r
        }
        None => newest(&found, &engine, None, &compat).ok_or_else(|| {
            format!("no release fits: {}, and the newest release for {target} is {}", engine.describe(), found.first().map(|r| r.version.as_str()).unwrap_or("none"))
        })?,
    };
    let v = chosen.version.clone();
    let current = versions.current();
    if migrating.is_none() && current.as_deref() == Some(v.as_str()) {
        report.say(format!("superfluid {v} is current, and the newest release that fits ({})", engine.describe()));
        return Ok(report);
    }
    // Without a version named an update only moves forward: a build newer than every release stays.
    let here = current.clone().unwrap_or_else(|| running().to_string());
    if opts.version.is_none() && migrating.is_none() && release_order(&v) < release_order(&here) {
        report.say(format!("superfluid {here} is current; the newest release that fits is {v} ({}), and `--version {v}` goes to it", engine.describe()));
        return Ok(report);
    }
    let on_disk = versions.binary(&v).is_file();
    report.say(format!(
        "{} -> {v} (published {}; {}){}",
        current.as_deref().unwrap_or(running()),
        chosen.published,
        engine.describe(),
        if on_disk { ", already installed here" } else { "" }
    ));
    if opts.dry_run {
        report.say("dry run: nothing fetched or changed");
        return Ok(report);
    }
    // The in-place copy goes under the layout first, as the version to go back to.
    let kept = match &migrating {
        Some(prefix) => Some(keep_in_place(&versions, prefix)?),
        None => None,
    };
    let on_disk = on_disk || versions.binary(&v).is_file();
    if !on_disk {
        place(&versions, chosen, &mut report)?;
    }
    if let Err(e) = probe(&versions, &v, home, &engine) {
        if !on_disk {
            let _ = std::fs::remove_dir_all(versions.version_dir(&v));
        }
        return Err(format!("{v} was not made current: {e}"));
    }
    versions.set_current(&v)?;
    if let Some(old) = kept.filter(|old| *old != v) {
        std::fs::write(versions.dir.join("previous"), format!("{old}\n")).map_err(|e| format!("{}: {e}", versions.dir.display()))?;
    }
    report.changed = true;
    report.say(format!("superfluid {v} is current ({})", versions.dir.join("current").display()));
    if let Some(prev) = versions.previous() {
        report.say(format!("{prev} stays installed: `superfluid self use {prev}` goes back to it"));
    }
    // Pruned before the links are made, so a removed version's `superfluid-<v>` goes with it.
    prune_older(&versions, &mut report);
    if let Some(prefix) = &migrating {
        migrate(&versions, prefix, &mut report)?;
    } else if let Some(prefix) = versions.prefix() {
        for note in versions.link(&prefix, false)? {
            report.say(note);
        }
    }
    report.say("a running server keeps the version it started with; starting it again uses the new one");
    Ok(report)
}

/// `self use <v>`.
pub fn use_version(home: &Path, catalog: &Catalog, exe: &Path, v: &str) -> Result<Report, String> {
    let versions = match installed_as(exe) {
        Installed::Managed { versions, .. } => Versions { dir: versions },
        _ => Versions::of(home),
    };
    let v = v.trim_start_matches('v');
    if !is_version(v) {
        return Err(format!("{v:?} is not a version (see `superfluid self list`)"));
    }
    let mut report = Report::default();
    std::fs::create_dir_all(&versions.dir).map_err(|e| format!("{}: {e}", versions.dir.display()))?;
    let _one_at_a_time = crate::pulls::Lock::take(&versions.dir, "self", "switch of superfluid")?;
    if versions.current().as_deref() == Some(v) {
        report.say(format!("superfluid {v} is current already"));
        return Ok(report);
    }
    probe(&versions, v, home, &engine_here(catalog))?;
    versions.set_current(v)?;
    report.changed = true;
    report.say(format!("superfluid {v} is current"));
    if let Some(prefix) = versions.prefix() {
        for note in versions.link(&prefix, false)? {
            report.say(note);
        }
    }
    Ok(report)
}

/// `self install --from <dir> [--prefix <dir>]`: an unpacked release placed
/// into the layout and made current; the install script's last step.
pub fn install_from(home: &Path, catalog: &Catalog, from: &Path, prefix: Option<&Path>) -> Result<Report, String> {
    let versions = Versions::of(home);
    let mut report = Report::default();
    std::fs::create_dir_all(&versions.dir).map_err(|e| format!("{}: {e}", versions.dir.display()))?;
    let _one_at_a_time = crate::pulls::Lock::take(&versions.dir, "self", "install of superfluid")?;
    let v = version_of(&from.join("bin").join("superfluid"))?;
    let engine = engine_here(catalog);
    let dest = versions.version_dir(&v);
    if dest == from {
        probe(&versions, &v, home, &engine).map_err(|e| format!("{v} was not made current: {e}"))?;
    } else if versions.binary(&v).is_file() && probe(&versions, &v, home, &engine).is_ok() {
        // An installed version is kept as it is; a copy of it that works is not replaced.
        report.say(format!("superfluid {v} is installed here already and works; the copy given was not used"));
    } else {
        // Proved where it is, then set in place of a copy that does not work.
        probe_binary(&from.join("bin").join("superfluid"), &v, home, &engine).map_err(|e| format!("{v} was not made current: {e}"))?;
        replace_tree(from, &dest, &versions.dir.join(format!(".replaced-{v}")), move_tree)?;
    }
    // The install script's earlier copy under the prefix is kept as the version to go back to.
    let kept = match prefix.and_then(|p| match installed_as(&p.join("superfluid")) {
        Installed::InPlace { prefix: root } => Some(root),
        _ => None,
    }) {
        Some(root) => Some(keep_in_place(&versions, &root)?),
        None => None,
    };
    versions.set_current(&v)?;
    if let Some(old) = kept.filter(|old| *old != v) {
        std::fs::write(versions.dir.join("previous"), format!("{old}\n")).map_err(|e| format!("{}: {e}", versions.dir.display()))?;
        report.say(format!("the copy that was in the prefix is kept as {old}: `superfluid self use {old}` goes back to it"));
    }
    report.changed = true;
    report.say(format!("superfluid {v} is current ({})", versions.dir.join("current").display()));
    prune_older(&versions, &mut report);
    if let Some(prefix) = prefix.map(Path::to_path_buf).or_else(|| versions.prefix()) {
        for note in versions.link(&prefix, true)? {
            report.say(note);
        }
        report.say(format!("{} links to it", prefix.join("superfluid").display()));
    }
    Ok(report)
}

/// `self list`.
pub fn list(home: &Path, exe: &Path) -> String {
    let (versions, note) = match installed_as(exe) {
        Installed::Managed { versions, .. } => (Versions { dir: versions }, None),
        Installed::InPlace { prefix } => (Versions::of(home), Some(format!("this superfluid is the install script's copy in {}/bin; `superfluid self update` moves it under {}", prefix.display(), home.join("versions").display()))),
        Installed::Other(p) => (Versions::of(home), Some(not_ours(&p))),
    };
    let mut out = String::new();
    let here = versions.on_disk();
    if here.is_empty() {
        out.push_str(&format!("no versions in {}\n", versions.dir.display()));
    } else {
        out.push_str(&format!("versions in {}:\n", versions.dir.display()));
        let (current, previous) = (versions.current(), versions.previous());
        for v in &here {
            let mut marks = Vec::new();
            if Some(v) == current.as_ref() {
                marks.push("current".to_string());
            }
            if Some(v) == previous.as_ref() {
                marks.push(format!("previous (`superfluid self use {v}` goes back)"));
            }
            if versions.version_dir(v).join("keep").exists() {
                marks.push("kept (a `keep` file)".into());
            }
            out.push_str(&format!("  {v}  {}\n", marks.join(", ")));
        }
    }
    out.push_str(&format!("running: {}\n", running()));
    if let Some(cache) = Check::read(home) {
        out.push_str(&format!("{}\n", cache.describe()));
    }
    if let Some(n) = note {
        out.push_str(&format!("{n}\n"));
    }
    out
}


/// `$SUPERFLUID_HOME/update-check.json`: the last read, the newest release that fit, and the version announced.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Check {
    pub checked_at: u64,
    pub newest: Option<String>,
    pub published: Option<String>,
    pub notified: Option<String>,
}

impl Check {
    fn path(home: &Path) -> PathBuf {
        home.join("update-check.json")
    }

    pub fn read(home: &Path) -> Option<Check> {
        let v: Value = serde_json::from_str(&std::fs::read_to_string(Self::path(home)).ok()?).ok()?;
        Some(Check {
            checked_at: v["checked_at"].as_u64().unwrap_or(0),
            newest: v["newest"].as_str().map(str::to_string),
            published: v["published"].as_str().map(str::to_string),
            notified: v["notified"].as_str().map(str::to_string),
        })
    }

    fn write(&self, home: &Path) -> Result<(), String> {
        std::fs::create_dir_all(home).map_err(|e| format!("{}: {e}", home.display()))?;
        let v = json!({"checked_at": self.checked_at, "newest": self.newest, "published": self.published, "notified": self.notified});
        std::fs::write(Self::path(home), format!("{v:#}\n")).map_err(|e| format!("{}: {e}", Self::path(home).display()))
    }

    pub fn due(&self) -> bool {
        now_secs().saturating_sub(self.checked_at) >= CHECK_EVERY.as_secs()
    }

    /// The newest release known, when it is newer than this one.
    pub fn newer(&self) -> Option<&str> {
        self.newest.as_deref().filter(|n| release_order(n) > release_order(running()))
    }

    pub fn describe(&self) -> String {
        let ago = now_secs().saturating_sub(self.checked_at);
        let when = if ago < 3600 { format!("{}m ago", ago / 60) } else if ago < 86_400 { format!("{}h ago", ago / 3600) } else { format!("{}d ago", ago / 86_400) };
        match self.newer() {
            Some(n) => format!("newest release: {n} (published {}; checked {when}): `superfluid self update` installs it", self.published.as_deref().unwrap_or("?")),
            None => format!("newest release that fits: {} (checked {when})", self.newest.as_deref().unwrap_or("none known")),
        }
    }
}

/// Read the listing now and record the newest release that fits here and is past the hold-off.
pub fn check_now(home: &Path, catalog: &Catalog, hold_off: Option<i64>, source: &str) -> Result<Check, String> {
    let target = target().ok_or("no release is published for this platform")?;
    let found = fetch_releases(source, target, 5)?;
    let engine = engine_here(catalog);
    let compat = compat_fetcher(5);
    let fit = newest(&found, &engine, hold_off, &compat);
    let previous = Check::read(home).unwrap_or_default();
    let check = Check {
        checked_at: now_secs(),
        newest: fit.map(|r| r.version.clone()),
        published: fit.map(|r| r.published.clone()),
        notified: previous.notified,
    };
    check.write(home)?;
    Ok(check)
}

/// The one line `serve` prints when a newer release is out, once per release; `command` installs it.
fn announce(home: &Path, mut check: Check, command: &str) -> Option<String> {
    let newer = check.newer()?.to_string();
    if check.notified.as_deref() == Some(newer.as_str()) {
        return None;
    }
    check.notified = Some(newer.clone());
    let _ = check.write(home);
    Some(format!("superfluid {newer} is available (this is {}): `{command}` installs it; {NO_CHECK_ENV}=1 silences this", running()))
}

/// What `serve` runs once the server is up: one listing read a day at most, one line per new release.
pub fn check_in_background(home: PathBuf, offline: bool) {
    if offline || std::env::var_os(NO_CHECK_ENV).is_some_and(|v| !v.is_empty() && v != "0") {
        return;
    }
    std::thread::Builder::new()
        .name("update-check".into())
        .spawn(move || loop {
            if let Some(line) = tick(&home, &Catalog::from_env(), &listing_source()) {
                eprintln!("superfluid: {line}");
            }
            // Hourly, so a server that stays up learns of a later release, and a check another process made is not repeated.
            std::thread::sleep(Duration::from_secs(60 * 60));
        })
        .ok();
}

/// One round: the cache when not yet due, else the listing; the line to print for a release not yet announced.
pub fn tick(home: &Path, catalog: &Catalog, source: &str) -> Option<String> {
    let command = update_command(&std::env::current_exe().unwrap_or_default());
    match Check::read(home).filter(|c| !c.due()) {
        Some(cached) => announce(home, cached, &command),
        None => announce(home, check_now(home, catalog, Some(HOLD_OFF_DAYS), source).ok()?, &command),
    }
}


fn usage() -> ! {
    eprint!("{HELP}");
    std::process::exit(2);
}

/// `superfluid self <action> ...`; the exit code.
pub fn run(args: &[String]) -> i32 {
    let home = crate::runtimes::default_home();
    let exe = std::env::current_exe().unwrap_or_default();
    let catalog = Catalog::from_env();
    let args = crate::cli::split_equals(args, |f| Some(matches!(f, "--version" | "--from" | "--prefix")));
    let print = |r: Result<Report, String>| -> i32 {
        match r {
            Ok(report) => {
                for line in report.lines {
                    println!("superfluid: {line}");
                }
                0
            }
            Err(e) => {
                eprintln!("superfluid: {e}");
                1
            }
        }
    };
    match args.first().map(String::as_str) {
        Some("update") => {
            let mut opts = Options::default();
            let mut it = args[1..].iter();
            while let Some(a) = it.next() {
                match a.as_str() {
                    "--version" => opts.version = it.next().cloned().or_else(|| usage()),
                    "--dry-run" => opts.dry_run = true,
                    "--yes" | "-y" => opts.yes = true,
                    _ => usage(),
                }
            }
            match update(&home, &catalog, &exe, &opts) {
                Ok(Report { hand_off: Some(mut cmd), .. }) => {
                    use std::os::unix::process::CommandExt;
                    let _ = std::io::stdout().flush();
                    // Only returns when the command could not be run.
                    let e = cmd.exec();
                    eprintln!("superfluid: running {}: {e}", cmd.get_program().to_string_lossy());
                    1
                }
                r => print(r),
            }
        }
        Some("check") if args.len() == 1 => match check_now(&home, &catalog, Some(HOLD_OFF_DAYS), &listing_source()) {
            Ok(check) => {
                println!("superfluid: {}", check.describe());
                0
            }
            Err(e) => {
                eprintln!("superfluid: {e}");
                1
            }
        },
        Some("list") if args.len() == 1 => {
            let _ = std::io::stdout().write_all(list(&home, &exe).as_bytes());
            0
        }
        Some("use") if args.len() == 2 => print(use_version(&home, &catalog, &exe, &args[1])),
        Some("install") => {
            let (mut from, mut prefix) = (None, None);
            let mut it = args[1..].iter();
            while let Some(a) = it.next() {
                match a.as_str() {
                    "--from" => from = it.next().map(PathBuf::from).or_else(|| usage()),
                    "--prefix" => prefix = it.next().map(PathBuf::from).or_else(|| usage()),
                    _ => usage(),
                }
            }
            let Some(from) = from else { usage() };
            print(install_from(&home, &catalog, &from, prefix.as_deref()))
        }
        _ => usage(),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::os::unix::fs::PermissionsExt;
    use std::process::Stdio;
    use superfluid_adapter_kit::install::sha256_of;

    fn scratch(tag: &str) -> PathBuf {
        let d = std::env::temp_dir().join(format!("superfluid-self-{tag}-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&d);
        std::fs::create_dir_all(&d).unwrap();
        d
    }

    /// A release tree whose `superfluid` answers `--version` and `runtimes --json` as a real one would.
    fn release_tree(dir: &Path, v: &str) -> PathBuf {
        let bin = dir.join("bin");
        std::fs::create_dir_all(&bin).unwrap();
        std::fs::create_dir_all(dir.join("libexec").join("superfluid")).unwrap();
        let script = format!(
            "#!/bin/sh\ncase \"$1\" in\n  --version) echo \"superfluid {v}\";;\n  runtimes) echo '[{{\"id\":\"basert\",\"ready\":true}}]';;\n  *) exit 2;;\nesac\n"
        );
        for name in LINKED {
            let p = bin.join(name);
            std::fs::write(&p, &script).unwrap();
            std::fs::set_permissions(&p, std::fs::Permissions::from_mode(0o755)).unwrap();
        }
        std::fs::write(dir.join("libexec").join("superfluid").join("superfluid-worker-toy"), "#!/bin/sh\n").unwrap();
        dir.to_path_buf()
    }

    /// A listing with one release per version, its assets as local files.
    fn listing(dir: &Path, versions: &[(&str, &str, Option<u32>)]) -> PathBuf {
        let target = target().unwrap();
        let mut rs = Vec::new();
        for (v, published, abi) in versions {
            let name = format!("superfluid-{target}");
            let tree = dir.join(format!("tree-{v}")).join(&name);
            release_tree(&tree, v);
            let tar = dir.join(format!("{name}-{v}.tar.gz"));
            let st = Command::new("tar").args(["-C"]).arg(tree.parent().unwrap()).arg("-czf").arg(&tar).arg(&name).status().unwrap();
            assert!(st.success());
            let sum = sha256_of(&tar).unwrap();
            let sha = dir.join(format!("{name}-{v}.tar.gz.sha256"));
            std::fs::write(&sha, format!("{sum}  {name}.tar.gz\n")).unwrap();
            let compat = dir.join(format!("{name}-{v}.compat.json"));
            std::fs::write(&compat, json!({"runtimes": {"basert": {"abi": abi, "unnumbered_minor": abi.map(|_| "0.3")}}}).to_string()).unwrap();
            let mut assets = vec![
                json!({"name": format!("{name}.tar.gz"), "browser_download_url": tar, "size": std::fs::metadata(&tar).unwrap().len()}),
                json!({"name": format!("{name}.tar.gz.sha256"), "browser_download_url": sha}),
                json!({"name": format!("{name}.compat.json"), "browser_download_url": compat}),
            ];
            if let Some(n) = abi {
                assets.push(json!({"name": format!("superfluid-basert-abi-{n}.txt"), "browser_download_url": "x"}));
            }
            rs.push(json!({"tag_name": format!("v{v}"), "draft": false, "prerelease": false, "published_at": format!("{published}T12:00:00Z"), "assets": assets}));
        }
        rs.push(json!({"tag_name": "v9.9.9", "draft": true, "prerelease": false, "published_at": "2026-01-01T00:00:00Z", "assets": []}));
        let p = dir.join("releases.json");
        std::fs::write(&p, Value::Array(rs).to_string()).unwrap();
        p
    }

    fn no_compat(_: &str) -> Option<Value> {
        None
    }

    #[test]
    fn a_listing_is_read_newest_first_and_a_release_fits_by_the_engine_it_declares() {
        let dir = scratch("listing");
        let p = listing(&dir, &[("0.1.3", "2026-10-01", Some(1)), ("0.2.0", "2026-10-20", Some(2)), ("0.1.2", "2026-09-01", None)]);
        let found = releases(&serde_json::from_str(&std::fs::read_to_string(&p).unwrap()).unwrap(), target().unwrap());
        assert_eq!(found.iter().map(|r| r.version.as_str()).collect::<Vec<_>>(), ["0.2.0", "0.1.3", "0.1.2"], "newest first, the draft left out");
        assert_eq!((found[0].abi, found[1].abi, found[2].abi), (Some(2), Some(1), None));
        assert_eq!(found[1].published, "2026-10-01");
        let odd = json!([{"tag_name": "v", "assets": []}, {"tag_name": "v../..", "assets": []}, {"tag_name": "vnext", "assets": []}]);
        assert_eq!(odd.as_array().unwrap().iter().filter_map(|r| release_of(r, "x.tar.gz", target().unwrap())).count(), 0, "a tag that is no version names no directory");
        assert!(["0.1.3", "0.2.0-rc.1", "1.0.0+build.5"].iter().all(|v| is_version(v)));
        let mut order = ["0.2.0-rc.1", "0.1.9", "0.2.0", "0.2.0-rc.10", "0.2.1-alpha", "0.2.0-beta", "0.2.0-rc.2", "0.2.0-rc", "0.10.0+build.5"];
        order.sort_by_key(|v| std::cmp::Reverse(release_order(v)));
        assert_eq!(order, ["0.10.0+build.5", "0.2.1-alpha", "0.2.0", "0.2.0-rc.10", "0.2.0-rc.2", "0.2.0-rc.1", "0.2.0-rc", "0.2.0-beta", "0.1.9"]);
        assert!(["", ".", "..", "../0.1.3", "0.1.3/..", "v0.1.3"].iter().all(|v| !is_version(v)));
        let compat = |url: &str| get_json(url, 1).ok();
        assert_eq!(newest(&found, &Engine::None, None, &no_compat).map(|r| r.version.as_str()), Some("0.2.0"));
        assert_eq!(newest(&found, &Engine::Abi(1), None, &no_compat).map(|r| r.version.as_str()), Some("0.1.3"), "by the marker alone");
        assert_eq!(newest(&found, &Engine::Abi(3), None, &compat), None);
        assert_eq!(newest(&found, &Engine::Unnumbered("0.3".into()), None, &compat).map(|r| r.version.as_str()), Some("0.2.0"), "compat.json names the line");
        assert_eq!(newest(&found, &Engine::Unnumbered("0.2".into()), None, &compat), None);
        assert_eq!(newest(&found, &Engine::None, Some(100_000), &no_compat), None);
        assert_eq!(age_days("2000-01-01").map(|d| d > 9000), Some(true));
        assert_eq!(days_from_civil(1970, 1, 1), 0);
        assert_eq!(days_from_civil(2000, 3, 1), 11017);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn where_an_executable_came_from_decides_who_updates_it() {
        let dir = scratch("installed");
        let managed = dir.join("home").join("versions").join("0.1.3").join("bin").join("superfluid");
        std::fs::create_dir_all(managed.parent().unwrap()).unwrap();
        std::fs::write(&managed, "").unwrap();
        assert_eq!(installed_as(&managed), Installed::Managed { versions: std::fs::canonicalize(dir.join("home").join("versions")).unwrap(), version: "0.1.3".into() });
        let in_place = dir.join("local").join("bin").join("superfluid");
        std::fs::create_dir_all(in_place.parent().unwrap()).unwrap();
        std::fs::create_dir_all(dir.join("local").join("libexec").join("superfluid")).unwrap();
        std::fs::write(&in_place, "").unwrap();
        assert_eq!(installed_as(&in_place), Installed::InPlace { prefix: std::fs::canonicalize(dir.join("local")).unwrap() });
        let other = dir.join("Cellar").join("superfluid").join("0.1.3").join("bin").join("superfluid");
        std::fs::create_dir_all(other.parent().unwrap()).unwrap();
        std::fs::write(&other, "").unwrap();
        assert!(matches!(installed_as(&other), Installed::Other(_)));
        assert!(not_ours(&other).contains("brew upgrade superfluid"));
        // A package keeps the release's layout, and its `installed-by` file says whose it is.
        let packaged = release_tree(&dir.join("site-packages").join("superfluid_cli").join("release"), "0.1.3").join("bin").join("superfluid");
        assert!(matches!(installed_as(&packaged), Installed::InPlace { .. }), "without the file it looks like the install script's copy");
        std::fs::write(dir.join("site-packages").join("superfluid_cli").join("release").join(INSTALLED_BY), "pip: pip install --upgrade superfluid-cli\n").unwrap();
        assert!(matches!(installed_as(&packaged), Installed::Other(_)));
        let packaged = std::fs::canonicalize(&packaged).unwrap();
        assert_eq!(not_ours(&packaged), format!("{} was installed by pip; `pip install --upgrade superfluid-cli` updates it", packaged.display()));
        assert_eq!(update_command(&packaged), "pip install --upgrade superfluid-cli");
        assert_eq!(update_command(&in_place), "superfluid self update");
        let home = dir.join("home");
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        let refused = update(&home, &catalog, &packaged, &Options::default()).unwrap_err();
        assert!(refused.contains("installed by pip"), "{refused}");
        assert!(list(&home, &packaged).contains("`pip install --upgrade superfluid-cli` updates it"));
        assert!(running_from(std::env::current_exe().unwrap().parent().unwrap()) || true, "other processes may or may not run from here");
        assert!(!running_from(&dir.join("nowhere")));
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn an_update_places_the_release_beside_the_old_one_flips_current_and_keeps_one_back() {
        let dir = scratch("update");
        let home = dir.join("home");
        let prefix = dir.join("local");
        let p = listing(&dir, &[("0.1.3", "2026-10-01", Some(1)), ("0.1.4", "2026-10-10", Some(1)), ("0.1.5", "2026-10-12", Some(1))]);
        let from = |version: Option<&str>, dry_run: bool| Options { version: version.map(str::to_string), dry_run, source: Some(p.to_string_lossy().to_string()), ..Options::default() };
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        let unpacked = release_tree(&dir.join("unpacked").join("superfluid-x"), "0.1.3");
        let r = install_from(&home, &catalog, &unpacked, Some(&prefix.join("bin"))).unwrap();
        assert!(r.changed, "{:?}", r.lines);
        let versions = Versions::of(&home);
        assert_eq!(versions.current().as_deref(), Some("0.1.3"));
        assert_eq!(std::fs::read_link(prefix.join("bin").join("superfluid")).unwrap(), versions.dir.join("current").join("bin").join("superfluid"));
        assert!(prefix.join("bin").join("superfluid-0.1.3").exists() && prefix.join("bin").join("superfluid-workerd").exists());
        assert!(!unpacked.exists(), "moved, not copied");
        let exe = versions.version_dir("0.1.3").join("bin").join("superfluid");
        let r = update(&home, &catalog, &exe, &from(None, true)).unwrap();
        assert!(r.lines[0].starts_with("0.1.3 -> 0.1.5 (published 2026-10-12;") && !r.changed, "{:?}", r.lines);
        assert_eq!(versions.on_disk(), ["0.1.3"]);
        let r = update(&home, &catalog, &exe, &from(None, false)).unwrap();
        assert!(r.changed, "{:?}", r.lines);
        assert_eq!(versions.current().as_deref(), Some("0.1.5"));
        assert_eq!(versions.previous().as_deref(), Some("0.1.3"));
        assert_eq!(versions.on_disk(), ["0.1.5", "0.1.3"]);
        assert!(r.lines.iter().any(|l| l == "0.1.3 stays installed: `superfluid self use 0.1.3` goes back to it"), "{:?}", r.lines);
        assert!(prefix.join("bin").join("superfluid-0.1.5").exists());
        assert!(!versions.dir.join(".staging").join("0.1.5").exists());
        let r = update(&home, &catalog, &versions.version_dir("0.1.5").join("bin").join("superfluid"), &from(None, false)).unwrap();
        assert!(!r.changed && r.lines[0].starts_with("superfluid 0.1.5 is current"), "{:?}", r.lines);
        release_tree(&versions.version_dir("0.9.0"), "0.9.0");
        versions.set_current("0.9.0").unwrap();
        let r = update(&home, &catalog, &exe, &from(None, false)).unwrap();
        assert!(!r.changed && r.lines[0].starts_with("superfluid 0.9.0 is current; the newest release that fits is 0.1.5"), "{:?}", r.lines);
        versions.set_current("0.1.5").unwrap();
        std::fs::remove_dir_all(versions.version_dir("0.9.0")).unwrap();
        std::fs::write(versions.dir.join("previous"), "0.1.3\n").unwrap();
        let r = update(&home, &catalog, &exe, &from(Some("v0.1.3"), false)).unwrap();
        assert!(r.changed && versions.current().as_deref() == Some("0.1.3") && versions.previous().as_deref() == Some("0.1.5"), "{:?}", r.lines);
        let r = update(&home, &catalog, &exe, &from(Some("0.1.4"), false)).unwrap();
        assert_eq!((versions.current().as_deref(), versions.previous().as_deref()), (Some("0.1.4"), Some("0.1.3")));
        assert_eq!(versions.on_disk(), ["0.1.4", "0.1.3"], "0.1.5 was neither current nor previous: {:?}", r.lines);
        assert!(prefix.join("bin").join("superfluid-0.1.5").symlink_metadata().is_err(), "its link went with it, not left dangling");
        std::fs::write(versions.version_dir("0.1.3").join("keep"), "").unwrap();
        let r = use_version(&home, &catalog, &exe, "0.1.3").unwrap();
        assert!(r.changed && versions.current().as_deref() == Some("0.1.3"));
        assert!(use_version(&home, &catalog, &exe, "..").unwrap_err().contains("is not a version"));
        assert_eq!(list(&home, &exe).lines().filter(|l| l.contains("current") || l.contains("previous")).count(), 2);
        let unreachable = Options { source: Some("/nonexistent/releases.json".into()), ..Options::default() };
        assert!(update(&home, &catalog, &exe, &unreachable).unwrap_err().contains("releases.json"), "the listing is needed for an update");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn an_installed_version_is_kept_and_only_a_proved_copy_replaces_a_broken_one() {
        let dir = scratch("reinstall");
        let home = dir.join("home");
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        let versions = Versions::of(&home);
        let r = install_from(&home, &catalog, &release_tree(&dir.join("first").join("superfluid-x"), "0.1.3"), None).unwrap();
        assert!(r.changed);
        std::fs::write(versions.version_dir("0.1.3").join("mine"), "").unwrap();
        let r = install_from(&home, &catalog, &release_tree(&dir.join("second").join("superfluid-x"), "0.1.3"), None).unwrap();
        assert!(r.lines.iter().any(|l| l.contains("installed here already and works")), "{:?}", r.lines);
        assert!(versions.version_dir("0.1.3").join("mine").exists() && versions.current().as_deref() == Some("0.1.3"));
        let bad = release_tree(&dir.join("bad").join("superfluid-x"), "0.1.3");
        std::fs::write(bad.join("bin").join("superfluid"), "#!/bin/sh\nexit 1\n").unwrap();
        let e = install_from(&home, &catalog, &bad, None).unwrap_err();
        assert!(e.contains("did not say its version"), "refused before anything is touched: {e}");
        assert!(versions.version_dir("0.1.3").join("mine").exists() && versions.current().as_deref() == Some("0.1.3"));
        let wrong = release_tree(&dir.join("wrong").join("superfluid-x"), "0.1.3");
        std::fs::write(wrong.join("bin").join("superfluid"), "#!/bin/sh\n[ \"$1\" = --version ] && echo 'superfluid 0.1.3' && exit 0\nexit 1\n").unwrap();
        let r = install_from(&home, &catalog, &wrong, None).unwrap();
        assert!(r.lines.iter().any(|l| l.contains("the copy given was not used")), "{:?}", r.lines);
        assert!(versions.version_dir("0.1.3").join("mine").exists() && versions.current().as_deref() == Some("0.1.3"));
        std::fs::write(versions.binary("0.1.3"), "#!/bin/sh\nexit 1\n").unwrap();
        let e = install_from(&home, &catalog, &wrong, None).unwrap_err();
        assert!(e.contains("was not made current") && e.contains("runtimes --json failed"), "{e}");
        assert!(versions.version_dir("0.1.3").join("mine").exists(), "a copy that fails the probe replaces nothing");
        let good = release_tree(&dir.join("good").join("superfluid-x"), "0.1.3");
        let r = install_from(&home, &catalog, &good, None).unwrap();
        assert!(r.changed && !versions.version_dir("0.1.3").join("mine").exists() && version_of(&versions.binary("0.1.3")).is_ok(), "{:?}", r.lines);
        assert!(!versions.dir.join(".replaced-0.1.3").exists());
        let _ = std::fs::remove_dir_all(&dir);
    }

    const SLEEP_ENV: &str = "SUPERFLUID_SELF_TEST_SLEEP";

    /// This test binary copied under a prefix and told to sleep: a server running from the install script's layout.
    #[test]
    fn sleeps_when_asked_to() {
        if std::env::var_os(SLEEP_ENV).is_some() {
            std::thread::sleep(Duration::from_secs(60));
        }
    }

    #[test]
    fn a_replacement_that_fails_leaves_the_copy_set_aside_back_in_place() {
        let dir = scratch("replace");
        let (from, dest, aside) = (dir.join("from"), dir.join("dest"), dir.join(".replaced"));
        std::fs::create_dir_all(&from).unwrap();
        std::fs::create_dir_all(&dest).unwrap();
        std::fs::write(dest.join("mine"), "").unwrap();
        let half = |from: &Path, dest: &Path| -> Result<(), String> {
            std::fs::create_dir_all(dest).unwrap();
            std::fs::write(dest.join("partial"), "").unwrap();
            Err(format!("{} -> {}: no space", from.display(), dest.display()))
        };
        let e = replace_tree(&from, &dest, &aside, half).unwrap_err();
        assert!(e.contains("no space") && !e.contains("could not be put back"), "{e}");
        assert!(dest.join("mine").exists() && !dest.join("partial").exists(), "the copy set aside is back, whole");
        assert!(!aside.exists());
        let whole = |from: &Path, dest: &Path| -> Result<(), String> { copy_tree(from, dest) };
        std::fs::write(from.join("new"), "").unwrap();
        replace_tree(&from, &dest, &aside, whole).unwrap();
        assert!(dest.join("new").exists() && !dest.join("mine").exists() && !aside.exists());
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// Killed and waited for on every way out of a test.
    struct Sleeper(std::process::Child);

    impl Drop for Sleeper {
        fn drop(&mut self) {
            let _ = self.0.kill();
            let _ = self.0.wait();
        }
    }

    /// This test binary copied to `exe` and run from there, asleep: a server running from the install script's layout.
    /// A copy of this test binary rather than a system one: macOS kills a platform binary run from elsewhere. Started
    /// as `when_not_busy` starts a program: on Linux a child another test forks while the copy is still open for
    /// writing holds that write until it execs, and the copy cannot be run until then (ETXTBSY).
    fn sleeper_at(exe: &Path) -> Sleeper {
        std::fs::copy(std::env::current_exe().unwrap(), exe).unwrap();
        let mut cmd = Command::new(exe);
        cmd.args(["selfupdate::tests::sleeps_when_asked_to", "--exact", "--quiet"])
            .env(SLEEP_ENV, "1")
            .stdout(Stdio::null())
            .stderr(Stdio::null());
        Sleeper(crate::exec::when_not_busy(|| cmd.spawn()).unwrap())
    }

    /// Whether a process is seen running from `dir` within five seconds.
    fn seen_running_from(dir: &Path) -> bool {
        (0..50).any(|_| {
            std::thread::sleep(Duration::from_millis(100));
            running_from(dir)
        })
    }

    #[test]
    fn a_server_still_running_from_the_install_scripts_copy_keeps_its_workerd_until_it_stops() {
        let dir = scratch("legacy-running");
        let (home, prefix) = (dir.join("home"), dir.join("local"));
        let p = listing(&dir, &[("0.1.3", "2026-10-01", None)]);
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        release_tree(&prefix, "0.1.2");
        let bin = prefix.join("bin");
        let mut sleeper = sleeper_at(&bin.join("superfluid-workerd"));
        if !seen_running_from(&bin) {
            eprintln!("SKIP: this platform does not report the sleeper's executable");
            return;
        }
        let exe = bin.join("superfluid");
        let opts = Options { source: Some(p.to_string_lossy().to_string()), ..Options::default() };
        let r = update(&home, &catalog, &exe, &opts).unwrap();
        let versions = Versions::of(&home);
        assert_eq!(versions.current().as_deref(), Some("0.1.3"), "{:?}", r.lines);
        assert!(std::fs::symlink_metadata(&exe).unwrap().file_type().is_symlink(), "the command moved");
        assert!(bin.join("superfluid-workerd").symlink_metadata().unwrap().file_type().is_file(), "the running server's workerd stayed a file: {:?}", r.lines);
        assert!(bin.join("superfluid-noded").symlink_metadata().unwrap().file_type().is_file());
        assert!(prefix.join("libexec").join("superfluid").join("superfluid-worker-toy").exists(), "and its workers");
        assert!(versions.dir.join("migrating").exists());
        assert!(r.lines.iter().any(|l| l.contains("still runs from the copy")), "{:?}", r.lines);
        assert_eq!(versions.previous().as_deref(), Some("0.1.2"));
        versions.link(&bin, false).unwrap();
        assert!(bin.join("superfluid-workerd").symlink_metadata().unwrap().file_type().is_file());
        drop(std::mem::replace(&mut sleeper, Sleeper(Command::new("true").spawn().unwrap())));
        let notes = versions.link(&bin, false).unwrap();
        assert!(bin.join("superfluid-workerd").symlink_metadata().unwrap().file_type().is_symlink(), "{notes:?}");
        assert!(!prefix.join("libexec").join("superfluid").join("superfluid-worker-toy").exists());
        assert!(!versions.dir.join("migrating").exists());
        assert!(notes.iter().any(|n| n.contains("now links into")), "{notes:?}");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn a_server_whose_own_command_became_a_link_still_holds_the_install_scripts_copy() {
        let dir = scratch("legacy-server");
        let (home, prefix) = (dir.join("home"), dir.join("local"));
        let versions = Versions::of(&home);
        release_tree(&versions.version_dir("0.1.3"), "0.1.3");
        versions.set_current("0.1.3").unwrap();
        release_tree(&prefix, "0.1.2");
        let bin = prefix.join("bin");
        let toy = prefix.join("libexec").join("superfluid").join("superfluid-worker-toy");
        let mut sleeper = sleeper_at(&bin.join("superfluid"));
        if !seen_running_from(&bin) {
            eprintln!("SKIP: this platform does not report the sleeper's executable");
            return;
        }
        let notes = versions.link(&bin, true).unwrap();
        assert!(bin.join("superfluid").symlink_metadata().unwrap().file_type().is_symlink(), "the command moved: {notes:?}");
        assert!(bin.join("superfluid-workerd").symlink_metadata().unwrap().file_type().is_file() && toy.exists(), "{notes:?}");
        // macOS gives the path of an executable a link was renamed over only while that name still leads somewhere: with
        // the link dangling it gives none, and the server is known by the note alone.
        std::fs::remove_file(versions.binary("0.1.3")).unwrap();
        let notes = versions.link(&bin, false).unwrap();
        assert!(bin.join("superfluid-workerd").symlink_metadata().unwrap().file_type().is_file(), "the server's workerd stayed a file: {notes:?}");
        assert!(toy.exists() && versions.dir.join("migrating").exists(), "and its workers: {notes:?}");
        assert!(notes.iter().any(|n| n.contains("still runs from the copy")), "{notes:?}");
        drop(std::mem::replace(&mut sleeper, Sleeper(Command::new("true").spawn().unwrap())));
        // A process that took a recorded id later is not the one recorded.
        let note = std::fs::read_to_string(versions.dir.join("migrating")).unwrap();
        std::fs::write(versions.dir.join("migrating"), format!("{note}{} 1\n", std::process::id())).unwrap();
        let notes = versions.link(&bin, false).unwrap();
        assert!(bin.join("superfluid-workerd").symlink_metadata().unwrap().file_type().is_symlink(), "{notes:?}");
        assert!(!toy.exists() && !versions.dir.join("migrating").exists(), "{notes:?}");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn the_install_script_over_an_earlier_copy_keeps_that_copy_to_go_back_to() {
        let dir = scratch("script-over-legacy");
        let (home, prefix) = (dir.join("home"), dir.join("local"));
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        release_tree(&prefix, "0.1.2");
        let tree = release_tree(&dir.join("unpacked").join("superfluid-x"), "0.1.3");
        let r = install_from(&home, &catalog, &tree, Some(&prefix.join("bin"))).unwrap();
        let versions = Versions::of(&home);
        assert_eq!((versions.current().as_deref(), versions.previous().as_deref()), (Some("0.1.3"), Some("0.1.2")), "{:?}", r.lines);
        assert_eq!(version_of(&versions.binary("0.1.2")).unwrap(), "0.1.2");
        for name in LINKED {
            assert!(prefix.join("bin").join(name).symlink_metadata().unwrap().file_type().is_symlink(), "{name}");
        }
        assert!(!prefix.join("libexec").join("superfluid").join("superfluid-worker-toy").exists());
        assert!(r.lines.iter().any(|l| l.contains("kept as 0.1.2")), "{:?}", r.lines);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn a_half_finished_copy_of_the_install_scripts_copy_is_copied_again_not_taken_for_it() {
        let dir = scratch("half-kept");
        let (home, prefix) = (dir.join("home"), dir.join("local"));
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        let versions = Versions::of(&home);
        release_tree(&prefix, "0.1.2");
        // What a copy cut short leaves: the command and nothing beside it.
        std::fs::create_dir_all(versions.version_dir("0.1.2").join("bin")).unwrap();
        std::fs::copy(prefix.join("bin").join("superfluid"), versions.binary("0.1.2")).unwrap();
        let e = use_version(&home, &catalog, &versions.binary("0.1.2"), "0.1.2").unwrap_err();
        assert!(e.contains("no superfluid-workerd"), "{e}");
        let tree = release_tree(&dir.join("unpacked").join("superfluid-x"), "0.1.3");
        let r = install_from(&home, &catalog, &tree, Some(&prefix.join("bin"))).unwrap();
        assert_eq!(versions.previous().as_deref(), Some("0.1.2"), "{:?}", r.lines);
        assert!(versions.version_dir("0.1.2").join("bin").join("superfluid-workerd").is_file(), "{:?}", r.lines);
        assert!(versions.version_dir("0.1.2").join("libexec").join("superfluid").join("superfluid-worker-toy").exists(), "the workers came along before the originals went");
        assert!(!prefix.join("libexec").join("superfluid").join("superfluid-worker-toy").exists());
        assert!(!versions.dir.join(".staging").join("kept-0.1.2").exists());
        assert!(use_version(&home, &catalog, &versions.binary("0.1.3"), "0.1.2").unwrap().changed);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn a_download_that_does_not_check_out_leaves_nothing_behind() {
        let dir = scratch("bad-download");
        let home = dir.join("home");
        let p = listing(&dir, &[("0.1.3", "2026-10-01", None)]);
        std::fs::write(dir.join(format!("superfluid-{}-0.1.3.tar.gz.sha256", target().unwrap())), format!("{}  x\n", "0".repeat(64))).unwrap();
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        let versions = Versions::of(&home);
        release_tree(&versions.version_dir("0.1.2"), "0.1.2");
        versions.set_current("0.1.2").unwrap();
        let opts = Options { source: Some(p.to_string_lossy().to_string()), ..Options::default() };
        let e = update(&home, &catalog, &versions.binary("0.1.2"), &opts).unwrap_err();
        assert!(!versions.dir.join(".staging").join("0.1.3").exists(), "{e}");
        assert!(!versions.version_dir("0.1.3").exists() && versions.current().as_deref() == Some("0.1.2"), "{e}");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn an_older_version_that_cannot_be_removed_does_not_fail_the_install() {
        let dir = scratch("prune-fails");
        let home = dir.join("home");
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        let versions = Versions::of(&home);
        release_tree(&versions.version_dir("0.1.0"), "0.1.0");
        release_tree(&versions.version_dir("0.1.1"), "0.1.1");
        versions.set_current("0.1.1").unwrap();
        let stuck = versions.version_dir("0.1.0").join("bin");
        std::fs::set_permissions(&stuck, std::fs::Permissions::from_mode(0o555)).unwrap();
        let r = install_from(&home, &catalog, &release_tree(&dir.join("unpacked").join("superfluid-x"), "0.1.2"), None);
        std::fs::set_permissions(&stuck, std::fs::Permissions::from_mode(0o755)).unwrap();
        let r = r.unwrap();
        assert!(r.changed && versions.current().as_deref() == Some("0.1.2"), "{:?}", r.lines);
        assert!(r.lines.iter().any(|l| l.starts_with("an older version was not removed (")), "{:?}", r.lines);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn a_switch_waits_for_an_update_that_holds_the_lock() {
        let dir = scratch("lock");
        let home = dir.join("home");
        let versions = Versions::of(&home);
        release_tree(&versions.version_dir("0.1.3"), "0.1.3");
        release_tree(&versions.version_dir("0.1.4"), "0.1.4");
        versions.set_current("0.1.4").unwrap();
        let held = crate::pulls::Lock::take(&versions.dir, "self", "update of superfluid").unwrap();
        let exe = versions.binary("0.1.4");
        let (home2, exe2) = (home.clone(), exe.clone());
        let switching = std::thread::spawn(move || {
            let catalog = Catalog::new(home2.clone(), None, home2.join("superfluid-workerd"));
            use_version(&home2, &catalog, &exe2, "0.1.3").map(|r| r.changed)
        });
        std::thread::sleep(Duration::from_millis(300));
        assert!(!switching.is_finished(), "the switch does not run while the lock is held");
        assert_eq!(versions.current().as_deref(), Some("0.1.4"));
        drop(held);
        assert_eq!(switching.join().unwrap(), Ok(true));
        assert_eq!(versions.current().as_deref(), Some("0.1.3"));
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn the_check_goes_on_from_the_cache_and_asks_again_when_due() {
        let dir = scratch("tick");
        let home = dir.join("home");
        std::fs::create_dir_all(&home).unwrap();
        let p = listing(&dir, &[("99.0.0", "2026-01-01", None)]);
        let source = p.to_string_lossy().to_string();
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        let first = tick(&home, &catalog, &source).unwrap();
        assert!(first.starts_with("superfluid 99.0.0 is available"), "{first}");
        assert_eq!(tick(&home, &catalog, "/nonexistent/releases.json"), None, "not due: the cache answers, nothing is read, and the release was announced already");
        let stale = Check { checked_at: 1, ..Check::read(&home).unwrap() };
        stale.write(&home).unwrap();
        assert_eq!(tick(&home, &catalog, "/nonexistent/releases.json"), None, "due, but the listing is unreachable: nothing, no panic");
        assert_eq!(Check::read(&home).unwrap().checked_at, 1, "an unreachable listing leaves the cache as it was");
        let p = listing(&dir.join("later"), &[("99.0.0", "2026-01-01", None), ("99.5.0", "2026-01-02", None)]);
        let later = tick(&home, &catalog, &p.to_string_lossy()).unwrap();
        assert!(later.starts_with("superfluid 99.5.0 is available"), "a release published since is announced on the next due check: {later}");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn a_release_that_does_not_start_or_drive_the_engine_is_not_made_current() {
        let dir = scratch("probe");
        let home = dir.join("home");
        let versions = Versions::of(&home);
        let tree = release_tree(&versions.version_dir("0.5.0"), "0.5.0");
        std::fs::write(
            tree.join("bin").join("superfluid"),
            "#!/bin/sh\nif [ \"$1\" = runtimes ]; then echo '[{\"id\":\"basert\",\"ready\":\"libbaseRT states ABI 2\"}]'; else echo 'superfluid 0.5.0'; fi\n",
        )
        .unwrap();
        assert!(probe(&versions, "0.5.0", &home, &Engine::None).is_ok(), "no engine in use: starting is enough");
        let e = probe(&versions, "0.5.0", &home, &Engine::Abi(1)).unwrap_err();
        assert!(e.contains("cannot drive the engine here: libbaseRT states ABI 2"), "{e}");
        std::fs::write(tree.join("bin").join("superfluid"), "#!/bin/sh\necho 'superfluid ..'\n").unwrap();
        assert!(probe(&versions, "0.5.0", &home, &Engine::None).unwrap_err().contains("did not say its version"));
        std::fs::write(tree.join("bin").join("superfluid"), "#!/bin/sh\necho 'superfluid 0.4.9'\n").unwrap();
        assert!(probe(&versions, "0.5.0", &home, &Engine::None).unwrap_err().contains("says it is 0.4.9"));
        // A copy that hangs is killed, so the lock it runs under is let go.
        std::fs::write(tree.join("bin").join("superfluid"), "#!/bin/sh\nexec sleep 30\n").unwrap();
        let began = std::time::Instant::now();
        let e = output_within(Command::new(versions.binary("0.5.0")).arg("--version"), Duration::from_secs(1)).unwrap_err();
        assert!(e.contains("did not answer within 1s") && began.elapsed() < Duration::from_secs(10), "{e}");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn the_in_place_install_is_migrated_into_the_layout() {
        let dir = scratch("migrate");
        let (home, prefix) = (dir.join("home"), dir.join("local"));
        let p = listing(&dir, &[("0.1.3", "2026-10-01", None)]);
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        release_tree(&prefix, "0.1.2");
        let exe = prefix.join("bin").join("superfluid");
        assert!(matches!(installed_as(&exe), Installed::InPlace { .. }));
        let opts = Options { source: Some(p.to_string_lossy().to_string()), ..Options::default() };
        let r = update(&home, &catalog, &exe, &opts).unwrap();
        let versions = Versions::of(&home);
        assert_eq!(versions.current().as_deref(), Some("0.1.3"), "{:?}", r.lines);
        assert!(std::fs::symlink_metadata(&exe).unwrap().file_type().is_symlink(), "the copy became a link");
        assert_eq!(std::fs::read_link(prefix.join("bin").join("superfluid-noded")).unwrap(), versions.dir.join("current").join("bin").join("superfluid-noded"));
        assert!(!prefix.join("libexec").join("superfluid").join("superfluid-worker-toy").exists(), "the old workers are gone");
        assert_eq!(versions.previous().as_deref(), Some("0.1.2"), "{:?}", r.lines);
        assert_eq!(version_of(&versions.binary("0.1.2")).unwrap(), "0.1.2");
        assert!(versions.version_dir("0.1.2").join("libexec").join("superfluid").join("superfluid-worker-toy").exists(), "with its workers");
        assert_eq!(versions.on_disk(), ["0.1.3", "0.1.2"]);
        assert_eq!(versions.prefix().as_deref(), Some(std::fs::canonicalize(prefix.join("bin")).unwrap().as_path()));
        assert!(r.lines.iter().any(|l| l.contains("now links into")), "{:?}", r.lines);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn the_daily_check_records_the_newest_release_and_announces_it_once() {
        let dir = scratch("check");
        let home = dir.join("home");
        std::fs::create_dir_all(&home).unwrap();
        let p = listing(&dir, &[("99.0.0", "2026-01-01", None), ("99.1.0", "2099-01-01", None)]);
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        let c = check_now(&home, &catalog, Some(HOLD_OFF_DAYS), &p.to_string_lossy()).unwrap();
        assert_eq!(c.newest.as_deref(), Some("99.0.0"), "99.1.0 is inside the hold-off");
        assert!(!c.due());
        assert_eq!(Check::read(&home), Some(c.clone()));
        let line = announce(&home, c.clone(), "superfluid self update").unwrap();
        assert!(line.starts_with("superfluid 99.0.0 is available (this is ") && line.contains("`superfluid self update`"), "{line}");
        assert_eq!(announce(&home, Check::read(&home).unwrap(), "superfluid self update"), None, "announced once");
        let again = Check { notified: None, ..c.clone() };
        assert!(announce(&home, again, "brew upgrade superfluid").unwrap().contains("`brew upgrade superfluid` installs it"));
        assert!(Check::read(&home).unwrap().describe().starts_with("newest release: 99.0.0 (published 2026-01-01;"));
        let stale = Check { checked_at: 1, ..Check::default() };
        assert!(stale.due());
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// A script at `path` that appends its arguments and the first PATH entry to `log`.
    fn logging_script(path: &Path, log: &Path) {
        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
        std::fs::write(path, format!("#!/bin/sh\necho \"$*|${{PATH%%:*}}\" >> {}\n", log.display())).unwrap();
        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).unwrap();
    }

    /// A packaged release at `root` (`<root>/bin/superfluid`) whose `installed-by` says `named`, by its real path.
    fn packaged(root: &Path, named: Option<&str>) -> PathBuf {
        release_tree(root, "0.1.5");
        if let Some(line) = named {
            std::fs::write(root.join(INSTALLED_BY), format!("{line}\n")).unwrap();
        }
        std::fs::canonicalize(root.join("bin").join("superfluid")).unwrap()
    }

    #[test]
    fn each_package_manager_is_run_from_the_installation_that_owns_the_copy_or_named() {
        let dir = scratch("delegate");
        // Homebrew: the brew of the Cellar, unless pinned.
        let brew_copy = packaged(&dir.join("brew/Cellar/superfluid/0.1.5/libexec"), Some("Homebrew: brew upgrade superfluid"));
        assert!(matches!(delegate(&brew_copy), Some(Delegate::Name { ref why, .. }) if why.starts_with("there is no ")));
        logging_script(&dir.join("brew/bin/brew"), &dir.join("log"));
        let brew = std::fs::canonicalize(dir.join("brew/bin/brew")).unwrap();
        assert_eq!(
            delegate(&brew_copy),
            Some(Delegate::Run {
                manager: "Homebrew".into(),
                command: "brew upgrade superfluid".into(),
                argv: vec![brew.display().to_string(), "upgrade".into(), "superfluid".into()],
                path_first: None,
            })
        );
        std::fs::create_dir_all(dir.join("brew/var/homebrew/pinned")).unwrap();
        std::fs::write(dir.join("brew/var/homebrew/pinned/superfluid"), "").unwrap();
        assert!(matches!(delegate(&brew_copy), Some(Delegate::Name { ref why, .. }) if why.contains("`brew unpin superfluid` first")));
        // npm: a global folder's own npm, its bin first on PATH; a project's dependency is named.
        let npm_line = Some("npm: npm install --global @basecompute/superfluid@latest");
        let global = packaged(&dir.join("node/lib/node_modules/@basecompute/superfluid-darwin-arm64/release"), npm_line);
        logging_script(&dir.join("node/bin/npm"), &dir.join("log"));
        let bin = std::fs::canonicalize(dir.join("node/bin")).unwrap();
        match delegate(&global) {
            Some(Delegate::Run { argv, path_first, .. }) => {
                let prefix = std::fs::canonicalize(dir.join("node")).unwrap().display().to_string();
                assert_eq!(argv[1..], ["install", "--global", "--prefix", &prefix, "@basecompute/superfluid@latest"]);
                assert_eq!(path_first, Some(bin));
            }
            other => panic!("{other:?}"),
        }
        let project = packaged(&dir.join("app/node_modules/@basecompute/superfluid-darwin-arm64/release"), npm_line);
        assert!(matches!(delegate(&project), Some(Delegate::Name { ref why, .. }) if why.contains("update it in that project")));
        // pip is named, with its environment's python; pipx and uv are told apart by their venvs.
        let pip_line = Some("pip: pip install --upgrade superfluid-cli");
        let env = dir.join("venv");
        let pip_copy = packaged(&env.join("lib/python3.12/site-packages/superfluid_cli/release"), pip_line);
        logging_script(&env.join("bin/python"), &dir.join("log"));
        let python = std::fs::canonicalize(env.join("bin/python")).unwrap();
        assert!(matches!(delegate(&pip_copy), Some(Delegate::Name { ref command, .. })
            if *command == format!("{} -m pip install --upgrade superfluid-cli", python.display())));
        let pipx = packaged(&dir.join(".local/pipx/venvs/superfluid-cli/lib/python3.12/site-packages/superfluid_cli/release"), pip_line);
        let d = delegate(&pipx).unwrap();
        assert_eq!((d.manager(), d.command()), ("pipx", "pipx upgrade superfluid-cli"));
        let uv = packaged(&dir.join(".local/share/uv/tools/superfluid-cli/lib/python3.12/site-packages/superfluid_cli/release"), pip_line);
        let d = delegate(&uv).unwrap();
        assert_eq!((d.manager(), d.command()), ("uv", "uv tool upgrade superfluid-cli"));
        // A manager superfluid does not run is named with the file's own command.
        let conda = packaged(&dir.join("conda/release"), Some("conda: conda update superfluid"));
        assert!(matches!(delegate(&conda), Some(Delegate::Name { ref command, .. }) if command == "conda update superfluid"));
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn the_superfluid_basert_installed_is_left_to_basert() {
        let dir = scratch("basert-owned");
        // basert's layout: <dir>/basert beside <dir>/superfluid, which an older basert marked with its stamp alone.
        let copy = packaged(&dir.join("superfluid"), None);
        assert!(matches!(installed_as(&copy), Installed::InPlace { .. }), "without basert's marks it is the install script's");
        std::fs::write(dir.join("superfluid").join(BASERT_STAMP), "v0.1.5\n").unwrap();
        assert!(matches!(installed_as(&copy), Installed::Other(_)));
        // No basert beside it: the one on PATH, when there is one.
        let d = delegate(&copy).unwrap();
        assert_eq!((d.manager(), d.command()), ("basert", "basert superfluid install"));
        logging_script(&dir.join("basert"), &dir.join("log"));
        std::fs::write(dir.join("superfluid").join(INSTALLED_BY), "basert: basert superfluid install\n").unwrap();
        let basert = std::fs::canonicalize(dir.join("basert")).unwrap();
        assert_eq!(
            delegate(&copy),
            Some(Delegate::Run {
                manager: "basert".into(),
                command: "basert superfluid install".into(),
                argv: vec![basert.display().to_string(), "superfluid".into(), "install".into()],
                path_first: None,
            })
        );
        assert_eq!(update_command(&copy), "basert superfluid install");
        let home = dir.join("home");
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        // A version is basert's to pick.
        let opts = Options { version: Some("0.1.4".into()), yes: true, ..Options::default() };
        let refused = update(&home, &catalog, &copy, &opts).unwrap_err();
        assert!(refused.contains("is basert's, which picks the release that serves its engine"), "{refused}");
        // With --yes, basert is handed this process, not run beside it: it refuses while anything runs from the copy.
        // Nothing was moved under ~/.superfluid.
        let opts = Options { yes: true, ..Options::default() };
        let mut hand_off = update(&home, &catalog, &copy, &opts).unwrap().hand_off.expect("basert is handed off to");
        assert!(!dir.join("log").exists());
        assert!(crate::exec::when_not_busy(|| hand_off.status()).unwrap().success());
        assert!(std::fs::read_to_string(dir.join("log")).unwrap().starts_with("superfluid install|"));
        assert!(!home.join("versions").exists());
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn a_package_managers_update_is_asked_for_dry_run_or_run_with_yes() {
        let dir = scratch("by-manager");
        let copy = packaged(&dir.join("brew/Cellar/superfluid/0.1.5/libexec"), Some("Homebrew: brew upgrade superfluid"));
        logging_script(&dir.join("brew/bin/brew"), &dir.join("log"));
        let home = dir.join("home");
        let catalog = Catalog::new(home.clone(), None, home.join("superfluid-workerd"));
        // Tests run without a terminal: without --yes the command is named, not run.
        let refused = update(&home, &catalog, &copy, &Options::default()).unwrap_err();
        assert!(refused.contains("run `brew upgrade superfluid`, or `superfluid self update --yes`"), "{refused}");
        let dry = update(&home, &catalog, &copy, &Options { dry_run: true, yes: true, ..Options::default() }).unwrap();
        assert!(dry.lines[0].contains("`self update` would run ") && dry.lines[0].ends_with("brew/bin/brew upgrade superfluid"), "{:?}", dry.lines);
        let pinned = Options { version: Some("0.1.4".into()), yes: true, ..Options::default() };
        assert!(update(&home, &catalog, &copy, &pinned).unwrap_err().contains("which chooses its version"));
        assert!(!dir.join("log").exists());
        let done = update(&home, &catalog, &copy, &Options { yes: true, ..Options::default() }).unwrap();
        assert!(done.changed && done.hand_off.is_none());
        assert!(std::fs::read_to_string(dir.join("log")).unwrap().starts_with("upgrade superfluid|"));
        let _ = std::fs::remove_dir_all(&dir);
    }
}