use anyhow::{Context, bail};
use std::io::{BufRead, Write};
use std::path::{Path, PathBuf};
use std::process::Stdio;
use std::time::{Duration, Instant};
use crate::cli::harness::{AttachEntry, HarnessId, HarnessRegistry, HarnessState, HarnessStatus};
use crate::daemon::InstalledDaemon;
use crate::domain::ControlStateDir;
const NPM_INSTALL_TIMEOUT: Duration = Duration::from_secs(180);
const NPM_INSTALL_POLL: Duration = Duration::from_millis(200);
const INITIALIZE_VERIFY_TIMEOUT: Duration = Duration::from_secs(10);
const INITIALIZE_REQUEST: &str = r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"symforge-update-verify","version":"1"}}}"#;
fn platform_package_for(os: &str, arch: &str) -> Option<&'static str> {
match (os, arch) {
("windows", "x86_64") => Some("symforge-windows-x64"),
("linux", "x86_64") => Some("symforge-linux-x64"),
("macos", "aarch64") => Some("symforge-macos-arm64"),
("macos", "x86_64") => Some("symforge-macos-x64"),
_ => None,
}
}
fn npm_executable_for_os(os: &str) -> &'static str {
if os == "windows" { "npm.cmd" } else { "npm" }
}
fn symforge_launcher() -> &'static str {
if std::env::consts::OS == "windows" {
"symforge.cmd"
} else {
"symforge"
}
}
fn install_specs(os: &str, arch: &str) -> Vec<String> {
let mut specs = vec!["symforge@latest".to_string()];
if let Some(pkg) = platform_package_for(os, arch) {
specs.push(format!("{pkg}@latest"));
}
specs
}
fn staging_install_args(staging: &Path, specs: &[String]) -> Vec<String> {
let mut args = vec![
"install".to_string(),
"--prefix".to_string(),
staging.display().to_string(),
"--no-save".to_string(),
];
args.extend(specs.iter().cloned());
args
}
fn native_binary_name(os: &str) -> &'static str {
if os == "windows" {
"symforge.exe"
} else {
"symforge"
}
}
fn global_modules_dir(prefix: &Path, os: &str) -> PathBuf {
if os == "windows" {
prefix.join("node_modules")
} else {
prefix.join("lib").join("node_modules")
}
}
fn native_binary_in(modules: &Path, platform_package: &str, os: &str) -> PathBuf {
modules
.join(platform_package)
.join("bin")
.join(native_binary_name(os))
}
fn update_staging_dir(npm_prefix: &Path) -> PathBuf {
npm_prefix.join(".symforge-update-staging")
}
fn platform_package_dirs(modules: &Path, platform_package: &str) -> [PathBuf; 2] {
[
modules
.join("symforge")
.join("node_modules")
.join(platform_package),
modules.join(platform_package),
]
}
fn live_platform_packages(modules: &Path, platform_package: &str) -> Vec<PathBuf> {
let [nested, top] = platform_package_dirs(modules, platform_package);
match (nested.is_dir(), top.is_dir()) {
(true, true) => vec![nested, top],
(true, false) => vec![nested],
(false, _) => vec![top],
}
}
fn parse_symforge_version(text: &str) -> Option<String> {
text.lines().find_map(|line| {
line.split_whitespace()
.map(str::trim)
.find(|tok| tok.contains('.') && tok.chars().next().is_some_and(|c| c.is_ascii_digit()))
.map(str::to_string)
})
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum InstalledProbe {
Version(String),
LauncherFailed(String),
Unprobeable,
}
fn probe_version(program: impl AsRef<std::ffi::OsStr>) -> InstalledProbe {
let output = match crate::process_util::hidden_command(program)
.arg("--version")
.stdin(Stdio::null())
.output()
{
Ok(output) => output,
Err(_) => return InstalledProbe::Unprobeable,
};
if let Some(version) = parse_symforge_version(&String::from_utf8_lossy(&output.stdout)) {
return InstalledProbe::Version(version);
}
let stderr = String::from_utf8_lossy(&output.stderr);
let detail = stderr
.lines()
.map(str::trim)
.find(|line| !line.is_empty())
.unwrap_or("launcher produced no version output")
.to_string();
InstalledProbe::LauncherFailed(detail)
}
fn clear_dead_sidecar_record() -> Option<String> {
use crate::sidecar::port_file::{
SidecarLiveness, cleanup_files, cleanup_stale_descriptors, read_sidecar_status,
};
let control_state_dir: ControlStateDir = crate::version_registry::resolve_home()?;
let project_root = std::env::current_dir().ok();
let status = read_sidecar_status(&control_state_dir, "127.0.0.1", project_root.as_deref());
cleanup_stale_descriptors(&control_state_dir, "127.0.0.1");
if !matches!(status.liveness, SidecarLiveness::Dead) {
return None;
}
cleanup_files(&control_state_dir);
let after = read_sidecar_status(&control_state_dir, "127.0.0.1", project_root.as_deref());
if matches!(after.liveness, SidecarLiveness::NoSidecar) {
Some("cleared a stale sidecar record".to_string())
} else {
Some(format!(
"skipped: clearing a stale sidecar record (it still reads as {})",
after.liveness.as_str()
))
}
}
fn remove_orphan_durable_bin() -> Vec<String> {
let Some(control_state_dir) = crate::version_registry::resolve_home() else {
return Vec::new();
};
remove_orphan_durable_bin_at(&control_state_dir)
}
fn remove_orphan_durable_bin_at(control_state_dir: &crate::domain::ControlStateDir) -> Vec<String> {
let bin = control_state_dir.as_path().join("bin");
let self_exe = std::env::current_exe()
.ok()
.and_then(|p| std::fs::canonicalize(p).ok());
let mut removed = Vec::new();
let mut failed = Vec::new();
for name in [
"symforge.exe",
"symforge",
"symforge.version",
"symforge-desktop.cmd",
] {
let path = bin.join(name);
if !path.exists() {
continue;
}
if let Some(self_exe) = &self_exe
&& std::fs::canonicalize(&path).ok().as_ref() == Some(self_exe)
{
continue;
}
match std::fs::remove_file(&path) {
Ok(()) => removed.push(name.to_string()),
Err(error) => failed.push(format!(
"skipped: removing retired durable-install leftover {}: {error}",
path.display()
)),
}
}
let mut lines = Vec::new();
if !removed.is_empty() {
lines.push(format!(
"removed retired durable-install leftover(s) from {}: {}",
bin.display(),
removed.join(", ")
));
}
lines.extend(failed);
lines
}
#[derive(Debug, Clone)]
pub(crate) struct HarnessScan {
statuses: Vec<HarnessStatus>,
grok_config_present: bool,
already_current: Vec<HarnessId>,
http_attached: Vec<HarnessId>,
}
fn plan_reregistration(scan: &HarnessScan, swapped: bool) -> (Vec<HarnessId>, Vec<String>) {
let mut targets = Vec::new();
let mut skipped = Vec::new();
for status in &scan.statuses {
match &status.state {
HarnessState::PresentCurrent | HarnessState::PresentStale(_)
if status.id == HarnessId::KiloCode =>
{
skipped.push(format!(
"skipped: {} (its config is project-local; run `symforge init --client kilo-code` inside that project)",
status.id.display_name()
));
}
HarnessState::PresentCurrent | HarnessState::PresentStale(_)
if !swapped && scan.already_current.contains(&status.id) =>
{
skipped.push(format!(
"unchanged: {} (it already runs the updated binary)",
status.id.display_name()
));
}
HarnessState::PresentCurrent | HarnessState::PresentStale(_)
if scan.http_attached.contains(&status.id) =>
{
skipped.push(format!(
"skipped: {} (it attaches over HTTP; there is no binary path to repoint)",
status.id.display_name()
));
}
HarnessState::PresentCurrent | HarnessState::PresentStale(_) => {
targets.push(status.id);
}
HarnessState::Malformed(_) => skipped.push(format!(
"skipped: {} (its config {} does not parse; left untouched)",
status.id.display_name(),
status.config_path.display()
)),
HarnessState::NotInstalled | HarnessState::Absent => {}
}
}
if scan.grok_config_present {
skipped.push(
"skipped: Grok (the harness scan does not cover it; run `symforge init --client grok` if Grok uses SymForge)"
.to_string(),
);
}
(targets, skipped)
}
#[derive(Debug, Default)]
struct UpdateSummary {
old_version: String,
new_version: String,
swap: SwapState,
reregistered: Vec<&'static str>,
daemon: Option<Result<InstalledDaemon, String>>,
initialize: Option<Result<(), String>>,
notes: Vec<String>,
}
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
enum SwapState {
#[default]
NotRun,
UpToDate,
StagedIsInstalled,
Started,
Swapped,
RolledBack,
}
impl UpdateSummary {
fn render(&self) -> String {
let version = match self.swap {
SwapState::Swapped => format!("{} -> {}", self.old_version, self.new_version),
SwapState::UpToDate => {
format!("{} (already the latest; swap skipped)", self.old_version)
}
SwapState::StagedIsInstalled => format!(
"{} (the registry was unreachable and npm staged this same version; swap skipped)",
self.old_version
),
SwapState::Started => format!(
"{} -> {} INCOMPLETE (some files are new, and the previous ones could not all be restored; see the error)",
self.old_version, self.new_version
),
SwapState::RolledBack => format!(
"{} (the swap to {} was undone after a failure)",
self.old_version, self.new_version
),
SwapState::NotRun => format!("{} (unchanged)", self.old_version),
};
let reregistered = if self.reregistered.is_empty() {
"none".to_string()
} else {
self.reregistered.join(", ")
};
let daemon = match &self.daemon {
Some(Ok(InstalledDaemon::Running {
port,
started: true,
})) => format!("yes (port {port})"),
Some(Ok(InstalledDaemon::Running {
port,
started: false,
})) => format!("no, the running daemon already runs this binary (port {port})"),
Some(Ok(InstalledDaemon::Skipped(why))) => format!("no, skipped ({why})"),
Some(Err(error)) => format!("no ({error})"),
None => "no (not attempted)".to_string(),
};
let initialize = match &self.initialize {
Some(Ok(())) => "yes".to_string(),
Some(Err(error)) => format!("no ({error})"),
None => "no (not attempted)".to_string(),
};
let mut out = format!(
"symforge update summary:\n version: {version}\n re-registered: {reregistered}\n daemon restarted: {daemon}\n binary answers initialize: {initialize}"
);
for note in &self.notes {
out.push_str("\n ");
out.push_str(note);
}
out
}
}
fn probe_label(probe: &InstalledProbe) -> String {
match probe {
InstalledProbe::Version(version) => version.clone(),
InstalledProbe::LauncherFailed(_) | InstalledProbe::Unprobeable => "unknown".to_string(),
}
}
pub(crate) trait UpdateOps {
fn sweep_stale_staging(&mut self) -> Vec<String>;
fn stop_daemon(&mut self) -> anyhow::Result<String>;
fn stage_install(&mut self, program: &str, specs: &[String]) -> anyhow::Result<bool>;
fn staged_version(&mut self) -> InstalledProbe;
fn swap_staged_into_place(&mut self) -> anyhow::Result<Vec<String>>;
fn roll_back(&mut self) -> anyhow::Result<()>;
fn wrapper_version(&mut self) -> Option<String>;
fn installed_version(&mut self) -> InstalledProbe;
fn latest_version(&mut self) -> Option<String>;
fn prune_registry(&mut self) -> Vec<String>;
fn harness_scan(&mut self) -> HarnessScan;
fn reregister(&mut self, harness: HarnessId) -> anyhow::Result<()>;
fn reconcile_durable(&mut self, reregistered: bool) -> Vec<String>;
fn shadow_report(&mut self) -> Option<crate::path_shadow::ShadowReport>;
fn live_version(&mut self) -> InstalledProbe;
fn restart_daemon(&mut self, version: &str) -> anyhow::Result<InstalledDaemon>;
fn verify_initialize(&mut self) -> anyhow::Result<()>;
}
struct RealUpdateOps {
npm_prefix: PathBuf,
live_modules: PathBuf,
staging: PathBuf,
platform_package: &'static str,
live_packages: Vec<PathBuf>,
live_binary: PathBuf,
staged_binary: PathBuf,
home: PathBuf,
journal: Vec<(PathBuf, Option<PathBuf>)>,
}
impl RealUpdateOps {
fn new(os: &str, platform_package: &'static str, npm_prefix: PathBuf, home: PathBuf) -> Self {
let live_modules = global_modules_dir(&npm_prefix, os);
let staging = update_staging_dir(&npm_prefix);
let live_packages = live_platform_packages(&live_modules, platform_package);
Self {
live_binary: live_packages[0].join("bin").join(native_binary_name(os)),
staged_binary: native_binary_in(&staging.join("node_modules"), platform_package, os),
live_packages,
npm_prefix,
live_modules,
staging,
platform_package,
home,
journal: Vec::new(),
}
}
fn runs_live_binary(&self, command: &str) -> bool {
let command = Path::new(command);
if crate::path_shadow::same_file(command, &self.live_binary) {
return true;
}
let is_script = command
.extension()
.is_some_and(|extension| extension.eq_ignore_ascii_case("cmd"));
is_script
&& std::fs::read_to_string(command).is_ok_and(|script| {
let binary = self.live_binary.display().to_string();
if cfg!(windows) {
script.to_lowercase().contains(&binary.to_lowercase())
} else {
script.contains(&binary)
}
})
}
}
impl UpdateOps for RealUpdateOps {
fn sweep_stale_staging(&mut self) -> Vec<String> {
sweep_stale_dir(&stale_staging_dir(&self.npm_prefix))
}
fn stop_daemon(&mut self) -> anyhow::Result<String> {
use crate::daemon::DaemonStopOutcome;
let outcome = tokio::runtime::Builder::new_current_thread()
.enable_io()
.enable_time()
.build()
.context("building a runtime for the daemon stop")?
.block_on(crate::daemon::stop_running_daemon_for_update())?;
Ok(match outcome {
DaemonStopOutcome::NotRunning => "no running daemon to stop".to_string(),
DaemonStopOutcome::Stopped { pid } => format!("stopped the daemon (pid {pid})"),
DaemonStopOutcome::StopTimedOut { pid } => format!(
"skipped: stopping the daemon (pid {pid} did not exit in time; the restart replaces it)"
),
DaemonStopOutcome::SkippedSafety => "skipped: stopping the daemon (its record failed \
the ownership check and it was left running)"
.to_string(),
})
}
fn stage_install(&mut self, program: &str, specs: &[String]) -> anyhow::Result<bool> {
match std::fs::remove_dir_all(&self.staging) {
Ok(()) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => {
return Err(error).with_context(|| {
format!("clearing the staging directory {}", self.staging.display())
});
}
}
let args = staging_install_args(&self.staging, specs);
let args: Vec<&str> = args.iter().map(String::as_str).collect();
let mut child = crate::process_util::hidden_command(program)
.args(&args)
.stdin(Stdio::inherit())
.stdout(Stdio::inherit())
.stderr(Stdio::inherit())
.spawn()
.with_context(|| format!("failed to start `{}`", invocation_text(program, &args)))?;
wait_or_kill(
&mut child,
Instant::now() + NPM_INSTALL_TIMEOUT,
NPM_INSTALL_POLL,
)
}
fn staged_version(&mut self) -> InstalledProbe {
probe_version(&self.staged_binary)
}
fn swap_staged_into_place(&mut self) -> anyhow::Result<Vec<String>> {
let staged_modules = self.staging.join("node_modules");
let aside = stale_staging_dir(&self.npm_prefix);
let staged_platform = staged_modules.join(self.platform_package);
let last = self.live_packages.len() - 1;
for (index, live) in self.live_packages.iter().enumerate() {
overlay_package(
&staged_platform,
live,
&aside,
index < last,
&mut self.journal,
)
.with_context(|| format!("swapping the staged files into {}", live.display()))?;
}
let live_wrapper = self.live_modules.join("symforge");
overlay_package(
&staged_modules.join("symforge"),
&live_wrapper,
&aside,
false,
&mut self.journal,
)
.with_context(|| format!("swapping the staged files into {}", live_wrapper.display()))?;
Ok(match std::fs::remove_dir_all(&self.staging) {
Ok(()) => Vec::new(),
Err(error) => vec![format!(
"skipped: removing the staging directory {}: {error}",
self.staging.display()
)],
})
}
fn roll_back(&mut self) -> anyhow::Result<()> {
let aside = stale_staging_dir(&self.npm_prefix);
let mut failed = Vec::new();
let journal = std::mem::take(&mut self.journal);
for (live, previous) in journal.iter().rev() {
let Some(previous) = previous else { continue };
if let Err(error) =
put_in_place(previous, live, &aside, |src, dst| std::fs::rename(src, dst))
{
failed.push(format!(
"{} (from {}): {error}",
live.display(),
previous.display()
));
}
}
for (live, previous) in &journal {
if previous.is_some()
&& !live.exists()
&& !failed
.iter()
.any(|f| f.starts_with(&live.display().to_string()))
{
failed.push(format!("{} is missing after the restore", live.display()));
}
}
if failed.is_empty() {
return Ok(());
}
bail!(
"could not restore {} file(s); the previous version's files are kept in {}. Put \
each back by hand, then rerun `symforge update`:\n {}",
failed.len(),
aside.display(),
failed.join("\n ")
)
}
fn wrapper_version(&mut self) -> Option<String> {
let manifest =
std::fs::read_to_string(self.live_modules.join("symforge").join("package.json"))
.ok()?;
serde_json::from_str::<serde_json::Value>(&manifest).ok()?["version"]
.as_str()
.map(str::to_string)
}
fn installed_version(&mut self) -> InstalledProbe {
probe_version(symforge_launcher())
}
fn latest_version(&mut self) -> Option<String> {
crate::cli::version::latest_npm_version()
}
fn prune_registry(&mut self) -> Vec<String> {
let mut lines: Vec<String> = clear_dead_sidecar_record().into_iter().collect();
let Some(home) = crate::version_registry::resolve_home() else {
return lines;
};
let pruned = crate::version_registry::prune_missing_entries(&home);
if pruned > 0 {
lines.push(format!(
"pruned {pruned} stale version-registry entr{}",
if pruned == 1 { "y" } else { "ies" }
));
}
lines
}
fn harness_scan(&mut self) -> HarnessScan {
let registry = HarnessRegistry::known_with(&self.home, &self.home);
let statuses = registry.scan(&AttachEntry::new("", None));
let mut already_current = Vec::new();
let mut http_attached = Vec::new();
for status in &statuses {
if !matches!(
status.state,
HarnessState::PresentCurrent | HarnessState::PresentStale(_)
) {
continue;
}
match crate::cli::harness::registered_command(status) {
Some(command) if self.runs_live_binary(&command) => {
already_current.push(status.id);
}
Some(_) => {}
None => http_attached.push(status.id),
}
}
HarnessScan {
statuses,
grok_config_present: self.home.join(".grok").join("config.toml").exists(),
already_current,
http_attached,
}
}
fn reregister(&mut self, harness: HarnessId) -> anyhow::Result<()> {
let status = crate::process_util::hidden_command(&self.live_binary)
.args(["init", "--client", harness.slug()])
.current_dir(&self.home)
.env_remove(crate::discovery::WORKSPACE_ROOT_ENV)
.stdin(Stdio::null())
.stdout(Stdio::inherit())
.stderr(Stdio::inherit())
.status()
.with_context(|| {
format!(
"starting `{} init --client {}`",
self.live_binary.display(),
harness.slug()
)
})?;
anyhow::ensure!(
status.success(),
"`symforge init --client {}` exited with {status}",
harness.slug()
);
Ok(())
}
fn reconcile_durable(&mut self, reregistered: bool) -> Vec<String> {
if reregistered {
remove_orphan_durable_bin()
} else {
Vec::new()
}
}
fn shadow_report(&mut self) -> Option<crate::path_shadow::ShadowReport> {
let installed = npm_installed_launcher_path()?;
crate::path_shadow::detect_shadow(&installed)
}
fn live_version(&mut self) -> InstalledProbe {
probe_version(&self.live_binary)
}
fn restart_daemon(&mut self, version: &str) -> anyhow::Result<InstalledDaemon> {
tokio::runtime::Builder::new_current_thread()
.enable_io()
.enable_time()
.build()
.context("building a runtime for the daemon restart")?
.block_on(crate::daemon::ensure_installed_daemon_running(
&self.live_binary,
version,
))
}
fn verify_initialize(&mut self) -> anyhow::Result<()> {
verify_initialize_at(&self.live_binary, &self.home, INITIALIZE_VERIFY_TIMEOUT)
}
}
fn verify_initialize_at(binary: &Path, cwd: &Path, timeout: Duration) -> anyhow::Result<()> {
let mut child = crate::process_util::hidden_command(binary)
.current_dir(cwd)
.env_remove(crate::discovery::WORKSPACE_ROOT_ENV)
.stdin(Stdio::piped())
.stdout(Stdio::piped())
.stderr(Stdio::null())
.spawn()
.with_context(|| format!("starting {} as a stdio MCP server", binary.display()))?;
let (Some(mut stdin), Some(stdout)) = (child.stdin.take(), child.stdout.take()) else {
child
.kill()
.context("stopping the `initialize` probe server")?;
bail!("stdio pipes were not attached to the probe server");
};
let (lines_tx, lines_rx) = std::sync::mpsc::channel();
std::thread::spawn(move || {
for line in std::io::BufReader::new(stdout).lines() {
let Ok(line) = line else { break };
if lines_tx.send(line).is_err() {
break;
}
}
});
let answered = writeln!(stdin, "{INITIALIZE_REQUEST}")
.and_then(|()| stdin.flush())
.context("writing `initialize` to the probe server")
.and_then(|()| {
let deadline = Instant::now() + timeout;
loop {
let remaining = deadline.saturating_duration_since(Instant::now());
match lines_rx.recv_timeout(remaining) {
Ok(line) if is_initialize_result(&line) => break Ok(()),
Ok(_) => {}
Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
break Err(anyhow::anyhow!(
"no `initialize` result within {}s",
timeout.as_secs()
));
}
Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
break Err(anyhow::anyhow!(
"the server closed stdout before answering `initialize`"
));
}
}
}
});
drop(stdin);
child
.kill()
.context("stopping the `initialize` probe server")?;
child
.wait()
.context("reaping the `initialize` probe server")?;
answered
}
fn is_initialize_result(line: &str) -> bool {
serde_json::from_str::<serde_json::Value>(line)
.is_ok_and(|message| message["id"] == 1 && message["result"]["protocolVersion"].is_string())
}
trait Waitable {
fn try_wait(&mut self) -> std::io::Result<Option<std::process::ExitStatus>>;
fn kill(&mut self) -> std::io::Result<()>;
}
impl Waitable for std::process::Child {
fn try_wait(&mut self) -> std::io::Result<Option<std::process::ExitStatus>> {
std::process::Child::try_wait(self)
}
fn kill(&mut self) -> std::io::Result<()> {
std::process::Child::kill(self)
}
}
fn wait_or_kill<C: Waitable>(
child: &mut C,
deadline: Instant,
poll: Duration,
) -> anyhow::Result<bool> {
loop {
if let Some(status) = child.try_wait()? {
return Ok(status.success());
}
if Instant::now() >= deadline {
child.kill().context("killing the timed-out npm install")?;
child.try_wait().context("reaping the killed npm install")?;
return Ok(false);
}
std::thread::sleep(poll);
}
}
fn stale_staging_dir(npm_prefix: &std::path::Path) -> std::path::PathBuf {
npm_prefix.join(".symforge-update-stale")
}
fn sweep_stale_dir(dir: &std::path::Path) -> Vec<String> {
let entries = match std::fs::read_dir(dir) {
Ok(entries) => entries,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Vec::new(),
Err(error) => return vec![format!("skipped: sweeping {}: {error}", dir.display())],
};
let mut removed = 0usize;
let mut kept = 0usize;
for entry in entries {
match entry.map(|entry| std::fs::remove_file(entry.path())) {
Ok(Ok(())) => removed += 1,
Ok(Err(_)) | Err(_) => kept += 1,
}
}
let mut lines = Vec::new();
if removed > 0 {
lines.push(format!(
"swept {removed} stale staged binar{} from {}",
if removed == 1 { "y" } else { "ies" },
dir.display()
));
}
if kept > 0 {
lines.push(format!(
"skipped: {kept} leftover(s) in {} could not be removed (likely still running from an open session; a later update removes them)",
dir.display()
));
}
lines
}
fn overlay_package(
staged: &Path,
live: &Path,
aside_dir: &Path,
keep_staged: bool,
journal: &mut Vec<(PathBuf, Option<PathBuf>)>,
) -> anyhow::Result<()> {
std::fs::create_dir_all(live).with_context(|| format!("creating {}", live.display()))?;
for entry in
std::fs::read_dir(staged).with_context(|| format!("reading {}", staged.display()))?
{
let entry = entry.with_context(|| format!("reading {}", staged.display()))?;
let mut from = entry.path();
let to = live.join(entry.file_name());
if entry
.file_type()
.with_context(|| format!("inspecting {}", from.display()))?
.is_dir()
{
overlay_package(&from, &to, aside_dir, keep_staged, journal)?;
continue;
}
if keep_staged {
let copy = aside_dir.join(format!(
"{}.new-{}",
entry.file_name().to_string_lossy(),
stage_suffix()
));
std::fs::create_dir_all(aside_dir)
.and_then(|()| std::fs::copy(&from, ©))
.with_context(|| format!("copying {} to {}", from.display(), copy.display()))?;
from = copy;
}
replace_file(&from, &to, aside_dir, journal, |src, dst| {
std::fs::rename(src, dst)
})
.with_context(|| format!("moving {} to {}", from.display(), to.display()))?;
}
Ok(())
}
fn replace_file(
src: &Path,
dst: &Path,
aside_dir: &Path,
journal: &mut Vec<(PathBuf, Option<PathBuf>)>,
rename: impl Fn(&Path, &Path) -> std::io::Result<()>,
) -> std::io::Result<()> {
let previous = if dst.exists() {
std::fs::create_dir_all(aside_dir)?;
let previous = aside_path(aside_dir, dst);
if std::fs::hard_link(dst, &previous).is_err() {
std::fs::copy(dst, &previous)?;
}
Some(previous)
} else {
None
};
journal.push((dst.to_path_buf(), previous));
put_in_place(src, dst, aside_dir, rename)
}
fn put_in_place(
src: &Path,
dst: &Path,
aside_dir: &Path,
rename: impl Fn(&Path, &Path) -> std::io::Result<()>,
) -> std::io::Result<()> {
let refused = match rename(src, dst) {
Ok(()) => return Ok(()),
Err(error) => error,
};
if refused.kind() != std::io::ErrorKind::PermissionDenied || !dst.exists() {
return Err(refused);
}
std::fs::create_dir_all(aside_dir)?;
let aside = aside_path(aside_dir, dst);
move_path_aside(dst, &aside)?;
if let Err(error) = rename(src, dst) {
return match move_path_aside(&aside, dst) {
Ok(()) => Err(error),
Err(restore) => Err(std::io::Error::other(format!(
"{error}; moving the previous file back also failed ({restore}), it is at {}",
aside.display()
))),
};
}
Ok(())
}
fn aside_path(aside_dir: &Path, file: &Path) -> PathBuf {
let name = file
.file_name()
.map(|name| name.to_string_lossy().into_owned())
.unwrap_or_default();
aside_dir.join(format!("{name}.old-{}", stage_suffix()))
}
fn stage_suffix() -> String {
static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
let nanos = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_nanos())
.unwrap_or(0);
let count = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
format!("{}-{nanos}-{count}", std::process::id())
}
#[cfg(windows)]
fn move_path_aside(src: &std::path::Path, dst: &std::path::Path) -> std::io::Result<()> {
match std::fs::rename(src, dst) {
Ok(()) => Ok(()),
Err(_) => windows_native::move_file_replace_existing(src, dst),
}
}
#[cfg(not(windows))]
fn move_path_aside(src: &std::path::Path, dst: &std::path::Path) -> std::io::Result<()> {
std::fs::rename(src, dst)
}
fn npm_global_prefix() -> Option<std::path::PathBuf> {
let program = npm_executable_for_os(std::env::consts::OS);
let output = crate::process_util::hidden_command(program)
.args(["prefix", "-g"])
.stdin(Stdio::null())
.output()
.ok()?;
if !output.status.success() {
return None;
}
resolve_prefix(String::from_utf8_lossy(&output.stdout).trim())
}
fn resolve_prefix(raw: &str) -> Option<PathBuf> {
if raw.is_empty() {
return None;
}
dunce::canonicalize(raw)
.ok()
.filter(|prefix| prefix.is_dir())
}
fn lock_update(npm_prefix: &Path) -> anyhow::Result<std::fs::File> {
let path = npm_prefix.join(".symforge-update.lock");
let file = std::fs::OpenOptions::new()
.create(true)
.truncate(false)
.write(true)
.open(&path)
.with_context(|| format!("opening the update lock {}", path.display()))?;
match file.try_lock() {
Ok(()) => Ok(file),
Err(std::fs::TryLockError::WouldBlock) => {
bail!("symforge update: another `symforge update` is already running")
}
Err(std::fs::TryLockError::Error(error)) => {
Err(error).with_context(|| format!("locking {}", path.display()))
}
}
}
fn npm_installed_launcher_path() -> Option<std::path::PathBuf> {
Some(launcher_path_in_prefix(
&npm_global_prefix()?,
std::env::consts::OS,
))
}
fn launcher_path_in_prefix(prefix: &std::path::Path, os: &str) -> std::path::PathBuf {
if os == "windows" {
prefix.join("symforge.cmd")
} else {
prefix.join("bin").join("symforge")
}
}
pub fn run_update() -> anyhow::Result<()> {
let os = std::env::consts::OS;
let arch = std::env::consts::ARCH;
let platform_package = platform_package_for(os, arch).with_context(|| {
format!("symforge update: no npm platform package ships a binary for {os}-{arch}")
})?;
let npm_prefix = npm_global_prefix().context(
"symforge update: could not resolve the npm global prefix (`npm prefix -g` failed or \
named no existing directory); is npm on PATH?",
)?;
let home = dirs::home_dir().context("cannot determine home directory")?;
let _lock = lock_update(&npm_prefix)?;
let mut ops = RealUpdateOps::new(os, platform_package, npm_prefix, home);
orchestrate_update(os, arch, &mut ops)
}
pub(crate) fn orchestrate_update(
os: &str,
arch: &str,
ops: &mut impl UpdateOps,
) -> anyhow::Result<()> {
let mut summary = UpdateSummary::default();
let result = update_steps(os, arch, ops, &mut summary);
eprintln!("{}", summary.render());
result
}
fn update_steps(
os: &str,
arch: &str,
ops: &mut impl UpdateOps,
summary: &mut UpdateSummary,
) -> anyhow::Result<()> {
summary.notes.extend(ops.prune_registry());
let latest = ops.latest_version();
if latest.is_none() {
summary.notes.push(
"skipped: confirming the latest published version (the npm registry was unreachable)"
.to_string(),
);
}
let before = ops.live_version();
summary.old_version = probe_label(&before);
let wrapper = ops.wrapper_version();
let behind = |version: &str| {
latest
.as_deref()
.is_some_and(|latest| crate::cli::version::is_newer_version(latest, version))
};
let current = latest.is_some()
&& matches!(&before, InstalledProbe::Version(v) if !behind(v))
&& wrapper.as_deref().is_some_and(|w| !behind(w));
if current {
summary.swap = SwapState::UpToDate;
eprintln!(
"symforge update: {} is not behind the latest published version; skipping the swap.",
summary.old_version
);
} else {
let program = npm_executable_for_os(os);
let specs = install_specs(os, arch);
let plain_cmd = format!("npm install -g {}", specs.join(" "));
eprintln!(
"symforge update: installing {} into a staging directory; running sessions are not touched.",
specs.join(" ")
);
if !ops.stage_install(program, &specs)? {
bail!(
"symforge update failed: the staging install (`{program} install ... {}`) exited \
unsuccessfully or timed out. The live install was NOT touched and running sessions \
are unaffected. Retry, or install from a plain shell:\n {plain_cmd}\n\
(The version registry was already pruned.)",
specs.join(" ")
);
}
let untouched = "The live install was NOT touched.";
match ops.staged_version() {
InstalledProbe::Version(staged) => {
if let Some(latest) = &latest
&& &staged != latest
{
bail!(
"symforge update failed: the staged binary reports {staged}, not the latest \
published {latest}. {untouched}"
);
}
if let InstalledProbe::Version(live) = &before
&& crate::cli::version::is_newer_version(live, &staged)
{
bail!(
"symforge update failed: the staged binary reports {staged}, older than the \
installed {live}; update does not downgrade. {untouched}"
);
}
summary.new_version = staged;
}
InstalledProbe::LauncherFailed(detail) => bail!(
"symforge update failed: the staged binary did not report a version:\n {detail}\n{untouched}"
),
InstalledProbe::Unprobeable => {
bail!("symforge update failed: the staged binary could not be run. {untouched}")
}
}
let staged_is_installed = latest.is_none()
&& matches!(&before, InstalledProbe::Version(v) if *v == summary.new_version)
&& wrapper.as_deref() == Some(summary.new_version.as_str());
if staged_is_installed {
summary.swap = SwapState::StagedIsInstalled;
eprintln!(
"symforge update: npm staged the installed {}; skipping the swap.",
summary.new_version
);
} else {
summary.notes.push(match ops.stop_daemon() {
Ok(line) => line,
Err(error) => format!("skipped: stopping the daemon: {error:#}"),
});
summary.swap = SwapState::Started;
match ops.swap_staged_into_place() {
Ok(lines) => summary.notes.extend(lines),
Err(error) => {
return Err(roll_back(
ops,
summary,
error.context(
"symforge update failed while swapping the staged files into place",
),
));
}
}
summary.swap = SwapState::Swapped;
}
}
let swapped = summary.swap == SwapState::Swapped;
if let Err(error) = verify_live(ops, summary, swapped) {
summary.notes.push(
"skipped: harness re-registration (the binary at the install path failed verification)"
.to_string(),
);
if !swapped {
return Err(error.context("symforge update failed"));
}
if matches!(summary.daemon, Some(Ok(InstalledDaemon::Running { .. }))) {
summary.notes.push(match ops.stop_daemon() {
Ok(line) => format!("{line} before restoring the previous version"),
Err(error) => {
format!("skipped: stopping the new daemon before restoring: {error:#}")
}
});
}
return Err(roll_back(ops, summary, error));
}
summary.notes.extend(ops.sweep_stale_staging());
let running = env!("CARGO_PKG_VERSION");
let pkg = platform_package_for(os, arch).unwrap_or("symforge-<os>-<arch>");
let launcher_problem = match ops.installed_version() {
InstalledProbe::LauncherFailed(detail) => Some(anyhow::anyhow!(
"symforge update incomplete: the freshly-installed `symforge` launcher could not \
resolve a native binary. Launcher reported:\n {detail}\n\
This is usually a stale/missing platform package or a WSL Windows-prefix bleed. Rerun \
`symforge update`; on WSL, ensure your Linux npm prefix bin is on PATH ahead of \
/usr/local and /mnt."
)),
InstalledProbe::Unprobeable => {
summary.notes.push(
"skipped: verifying `symforge --version` through the launcher on PATH (it could not \
be run; the npm prefix bin may not be on PATH)"
.to_string(),
);
None
}
InstalledProbe::Version(installed) => {
let (stale, target) = match &latest {
Some(l) => (
crate::cli::version::is_newer_version(l, &installed),
l.clone(),
),
None => (
crate::cli::version::is_newer_version(running, &installed),
running.to_string(),
),
};
stale.then(|| {
anyhow::anyhow!(
"symforge update incomplete: `symforge --version` still reports {installed}, \
behind {target}. The resolved `symforge` is not the one just installed. Likely causes:\n \
- a stale platform package {pkg} the launcher resolves first — rerun `symforge update`\n \
- a PATH-shadowing install — run `which -a symforge`; a root /usr/local copy can win over your npm prefix\n \
- on WSL, a Windows npm prefix bleeding in via /mnt — put your Linux npm prefix bin ahead of /usr/local and /mnt on PATH"
)
})
}
};
if let Some(report) = ops.shadow_report() {
eprintln!("{}", crate::path_shadow::format_shadow_warning(&report));
}
let (targets, skipped) = plan_reregistration(&ops.harness_scan(), swapped);
summary.notes.extend(skipped);
let mut all_reregistered = true;
for harness in targets {
match ops.reregister(harness) {
Ok(()) => summary.reregistered.push(harness.display_name()),
Err(error) => {
all_reregistered = false;
summary.notes.push(format!(
"skipped: re-registering {}: {error:#}",
harness.display_name()
));
}
}
}
if !all_reregistered {
summary.notes.push(
"skipped: removing retired durable-install leftovers (a re-registration failed)"
.to_string(),
);
}
summary
.notes
.extend(ops.reconcile_durable(all_reregistered));
match launcher_problem {
Some(error) => Err(error),
None => Ok(()),
}
}
fn verify_live(
ops: &mut impl UpdateOps,
summary: &mut UpdateSummary,
swapped: bool,
) -> anyhow::Result<()> {
summary.new_version = match ops.live_version() {
InstalledProbe::Version(version) => version,
InstalledProbe::LauncherFailed(detail) => bail!(
"symforge update incomplete: the binary at the install path did not report a version:\n {detail}"
),
InstalledProbe::Unprobeable => {
bail!("symforge update incomplete: the binary at the install path could not be run")
}
};
match ops.restart_daemon(&summary.new_version) {
Ok(daemon) => summary.daemon = Some(Ok(daemon)),
Err(error) => {
summary.daemon = Some(Err(format!("{error:#}")));
if swapped {
return Err(error.context("the daemon did not start from the new binary"));
}
}
}
if let Err(error) = ops.verify_initialize() {
summary.initialize = Some(Err(format!("{error:#}")));
return Err(error.context(
"the binary at the install path did not answer a harness `initialize`; new sessions \
will fail until this is fixed",
));
}
summary.initialize = Some(Ok(()));
Ok(())
}
fn roll_back(
ops: &mut impl UpdateOps,
summary: &mut UpdateSummary,
error: anyhow::Error,
) -> anyhow::Error {
match ops.roll_back() {
Ok(()) => {
summary.swap = SwapState::RolledBack;
error.context(format!(
"symforge update failed; the previous version ({}) was restored. The daemon starts \
again with the next session. Rerun `symforge update` to retry",
summary.old_version
))
}
Err(restore) => error.context(format!(
"symforge update failed, and restoring the previous version failed too: {restore:#}"
)),
}
}
fn invocation_text(program: &str, args: &[&str]) -> String {
let mut parts = Vec::with_capacity(args.len() + 1);
parts.push(program.to_string());
parts.extend(args.iter().map(|arg| (*arg).to_string()));
parts.join(" ")
}
#[cfg(windows)]
mod windows_native {
fn to_wide(path: &std::path::Path) -> Vec<u16> {
use std::os::windows::ffi::OsStrExt;
path.as_os_str()
.encode_wide()
.chain(std::iter::once(0))
.collect()
}
#[allow(unsafe_code)]
pub(super) fn move_file_replace_existing(
src: &std::path::Path,
dst: &std::path::Path,
) -> std::io::Result<()> {
use windows::Win32::Storage::FileSystem::{MOVEFILE_REPLACE_EXISTING, MoveFileExW};
let src_w = to_wide(src);
let dst_w = to_wide(dst);
unsafe {
MoveFileExW(
windows::core::PCWSTR(src_w.as_ptr()),
windows::core::PCWSTR(dst_w.as_ptr()),
MOVEFILE_REPLACE_EXISTING,
)
}
.map_err(|e| std::io::Error::other(e.to_string()))
}
}
#[cfg(test)]
mod tests {
use super::*;
struct FakeOps {
events: Vec<String>,
latest: Option<String>,
live: Vec<InstalledProbe>,
stage_result: bool,
staged: InstalledProbe,
stop: Result<String, String>,
installed: InstalledProbe,
wrapper: Option<String>,
swap_fails: bool,
roll_back: Result<(), String>,
daemon: Result<InstalledDaemon, String>,
initialize: Result<(), String>,
scan: Vec<(HarnessId, HarnessState)>,
reregister_fails: Vec<HarnessId>,
reconciled_with: Option<bool>,
shadow: Option<crate::path_shadow::ShadowReport>,
}
impl Default for FakeOps {
fn default() -> Self {
Self {
events: Vec::new(),
latest: Some("7.15.4".to_string()),
live: vec![
InstalledProbe::Version("7.15.3".to_string()),
InstalledProbe::Version("7.15.4".to_string()),
],
stage_result: true,
staged: InstalledProbe::Version("7.15.4".to_string()),
stop: Ok("stopped the daemon (pid 7)".to_string()),
installed: InstalledProbe::Version("7.15.4".to_string()),
wrapper: Some("7.15.3".to_string()),
swap_fails: false,
roll_back: Ok(()),
daemon: Ok(InstalledDaemon::Running {
port: 4242,
started: true,
}),
initialize: Ok(()),
scan: vec![
(HarnessId::ClaudeCode, HarnessState::PresentCurrent),
(HarnessId::Cursor, HarnessState::NotInstalled),
],
reregister_fails: Vec::new(),
reconciled_with: None,
shadow: None,
}
}
}
impl FakeOps {
fn happened(&self, event: &str) -> bool {
self.events.iter().any(|e| e == event)
}
fn position(&self, event: &str) -> usize {
self.events
.iter()
.position(|e| e == event)
.unwrap_or_else(|| panic!("{event} never happened: {:?}", self.events))
}
}
impl UpdateOps for FakeOps {
fn sweep_stale_staging(&mut self) -> Vec<String> {
self.events.push("sweep".into());
Vec::new()
}
fn stop_daemon(&mut self) -> anyhow::Result<String> {
self.events.push("stop-daemon".into());
self.stop.clone().map_err(|e| anyhow::anyhow!(e))
}
fn stage_install(&mut self, program: &str, specs: &[String]) -> anyhow::Result<bool> {
self.events
.push(format!("stage {program} {}", specs.join(" ")));
Ok(self.stage_result)
}
fn staged_version(&mut self) -> InstalledProbe {
self.staged.clone()
}
fn swap_staged_into_place(&mut self) -> anyhow::Result<Vec<String>> {
self.events.push("swap".into());
if self.swap_fails {
bail!("moving package.json: the process cannot access the file");
}
Ok(Vec::new())
}
fn roll_back(&mut self) -> anyhow::Result<()> {
self.events.push("rollback".into());
self.roll_back.clone().map_err(|e| anyhow::anyhow!(e))
}
fn wrapper_version(&mut self) -> Option<String> {
self.wrapper.clone()
}
fn installed_version(&mut self) -> InstalledProbe {
self.installed.clone()
}
fn latest_version(&mut self) -> Option<String> {
self.latest.clone()
}
fn prune_registry(&mut self) -> Vec<String> {
self.events.push("prune".into());
Vec::new()
}
fn harness_scan(&mut self) -> HarnessScan {
scan_of(&self.scan)
}
fn reregister(&mut self, harness: HarnessId) -> anyhow::Result<()> {
self.events.push(format!("reregister {}", harness.slug()));
if self.reregister_fails.contains(&harness) {
bail!("init exited with 1");
}
Ok(())
}
fn reconcile_durable(&mut self, reregistered: bool) -> Vec<String> {
self.reconciled_with = Some(reregistered);
Vec::new()
}
fn shadow_report(&mut self) -> Option<crate::path_shadow::ShadowReport> {
self.events.push("shadow".into());
self.shadow.clone()
}
fn live_version(&mut self) -> InstalledProbe {
self.events.push("live-probe".into());
if self.live.len() > 1 {
self.live.remove(0)
} else {
self.live[0].clone()
}
}
fn restart_daemon(&mut self, version: &str) -> anyhow::Result<InstalledDaemon> {
self.events.push(format!("daemon {version}"));
self.daemon.clone().map_err(|e| anyhow::anyhow!(e))
}
fn verify_initialize(&mut self) -> anyhow::Result<()> {
self.events.push("initialize".into());
self.initialize.clone().map_err(|e| anyhow::anyhow!(e))
}
}
fn scan_of(states: &[(HarnessId, HarnessState)]) -> HarnessScan {
HarnessScan {
statuses: states
.iter()
.map(|(id, state)| HarnessStatus {
id: *id,
config_path: PathBuf::from(format!("/home/you/{}.json", id.slug())),
format: crate::cli::harness::HarnessFormat::Json,
state: state.clone(),
})
.collect(),
grok_config_present: false,
already_current: Vec::new(),
http_attached: Vec::new(),
}
}
#[test]
fn npm_executable_is_npm_cmd_on_windows_else_npm() {
assert_eq!(npm_executable_for_os("windows"), "npm.cmd");
assert_eq!(npm_executable_for_os("linux"), "npm");
assert_eq!(npm_executable_for_os("macos"), "npm");
}
#[test]
fn install_specs_force_the_os_native_platform_package() {
assert_eq!(
install_specs("windows", "x86_64"),
vec!["symforge@latest", "symforge-windows-x64@latest"]
);
assert_eq!(
install_specs("linux", "x86_64"),
vec!["symforge@latest", "symforge-linux-x64@latest"]
);
assert_eq!(
install_specs("macos", "aarch64"),
vec!["symforge@latest", "symforge-macos-arm64@latest"]
);
}
#[test]
fn install_specs_falls_back_to_wrapper_only_for_unknown_target() {
assert_eq!(install_specs("linux", "riscv64"), vec!["symforge@latest"]);
assert_eq!(install_specs("plan9", "x86_64"), vec!["symforge@latest"]);
}
#[test]
fn parse_symforge_version_scans_all_lines_past_leading_banner() {
assert_eq!(
parse_symforge_version("symforge 7.15.4\nUpdate available: 7.16.0"),
Some("7.15.4".to_string())
);
assert_eq!(
parse_symforge_version("(node:1) ExperimentalWarning: blah\nsymforge 7.15.4"),
Some("7.15.4".to_string())
);
assert_eq!(parse_symforge_version("no version here"), None);
assert_eq!(parse_symforge_version(""), None);
}
#[test]
fn orchestrate_update_runs_full_sequence_on_success() {
let mut ops = FakeOps::default();
orchestrate_update("linux", "x86_64", &mut ops).expect("update should succeed");
let stage = ops.position("stage npm symforge@latest symforge-linux-x64@latest");
let stop = ops.position("stop-daemon");
let swap = ops.position("swap");
let daemon = ops.position("daemon 7.15.4");
let initialize = ops.position("initialize");
let reregister = ops.position("reregister claude");
assert!(ops.position("prune") < stage, "cruft is pruned first");
assert!(
stage < stop && stop + 1 == swap,
"the daemon stops only once the staged binary is verified, right before the swap: {:?}",
ops.events
);
assert!(swap < daemon && daemon < initialize && initialize < reregister);
assert_eq!(ops.reconciled_with, Some(true));
let stops: Vec<_> = ops
.events
.iter()
.filter(|e| e.contains("stop") || e.contains("kill"))
.collect();
assert_eq!(stops, vec!["stop-daemon"], "{:?}", ops.events);
}
#[test]
fn orchestrate_update_warns_but_succeeds_when_a_same_version_shadow_wins() {
let mut ops = FakeOps {
shadow: Some(crate::path_shadow::ShadowReport {
our_path: PathBuf::from("/home/you/.npm-global/bin/symforge"),
our_version: Some("7.15.4".to_string()),
shadow_path: PathBuf::from("/usr/local/bin/symforge"),
shadow_version: Some("7.15.4".to_string()),
kind: crate::path_shadow::ShadowKind::RootSystem,
}),
..Default::default()
};
orchestrate_update("linux", "x86_64", &mut ops)
.expect("a same-version shadow is advisory, not fatal");
assert!(ops.position("swap") < ops.position("shadow"));
assert!(ops.happened("reregister claude"));
}
#[test]
fn launcher_path_in_prefix_maps_per_os_layout() {
assert_eq!(
launcher_path_in_prefix(std::path::Path::new("C:/npm-prefix"), "windows"),
std::path::Path::new("C:/npm-prefix").join("symforge.cmd")
);
assert_eq!(
launcher_path_in_prefix(std::path::Path::new("/home/you/.npm-global"), "linux"),
std::path::Path::new("/home/you/.npm-global/bin/symforge")
);
}
#[test]
fn orchestrate_update_uses_npm_cmd_and_windows_package_on_windows() {
let mut ops = FakeOps::default();
orchestrate_update("windows", "x86_64", &mut ops).expect("update should succeed");
assert!(ops.happened("stage npm.cmd symforge@latest symforge-windows-x64@latest"));
}
#[test]
fn orchestrate_update_reports_failed_npm_without_reregistering() {
let mut ops = FakeOps {
stage_result: false,
..Default::default()
};
let err = orchestrate_update("windows", "x86_64", &mut ops)
.expect_err("a failed staging install is reported");
let msg = err.to_string();
assert!(msg.contains("NOT touched"), "{msg}");
assert!(
msg.contains("npm install -g symforge@latest symforge-windows-x64@latest"),
"{msg}"
);
assert!(ops.happened("prune"), "prune runs even when staging fails");
assert!(!ops.happened("swap") && !ops.happened("stop-daemon"));
assert!(!ops.events.iter().any(|e| e.starts_with("daemon")));
assert!(!ops.events.iter().any(|e| e.starts_with("reregister")));
assert_eq!(ops.reconciled_with, None);
}
#[test]
fn orchestrate_update_prunes_registry_before_install_on_success() {
let mut ops = FakeOps::default();
orchestrate_update("linux", "x86_64", &mut ops).expect("update should succeed");
let prunes = ops.events.iter().filter(|e| *e == "prune").count();
assert_eq!(prunes, 1, "prune runs exactly once");
assert!(
ops.position("prune")
< ops.position("stage npm symforge@latest symforge-linux-x64@latest"),
"prune precedes the npm swap"
);
}
#[test]
fn orchestrate_update_fails_loudly_when_resolved_version_stays_stale() {
let mut ops = FakeOps {
installed: InstalledProbe::Version("7.15.2".to_string()),
..Default::default()
};
let err = orchestrate_update("linux", "x86_64", &mut ops)
.expect_err("stale resolved version must fail loudly");
let msg = err.to_string();
assert!(msg.contains("incomplete"), "{msg}");
assert!(msg.contains("7.15.2") && msg.contains("7.15.4"), "{msg}");
assert!(msg.contains("PATH-shadowing"), "{msg}");
assert!(
ops.happened("reregister claude"),
"the PATH launcher is not what harnesses spawn; it must not block them: {:?}",
ops.events
);
}
#[test]
fn orchestrate_update_bails_on_launcher_failure_surfacing_stderr() {
let mut ops = FakeOps {
installed: InstalledProbe::LauncherFailed(
"symforge: platform package symforge-linux-x64 not found".to_string(),
),
..Default::default()
};
let err = orchestrate_update("linux", "x86_64", &mut ops)
.expect_err("a launcher that cannot resolve a binary must fail loudly");
let msg = err.to_string();
assert!(msg.contains("could not resolve a native binary"), "{msg}");
assert!(msg.contains("symforge-linux-x64 not found"), "{msg}");
assert!(ops.happened("daemon 7.15.4") && ops.happened("reregister claude"));
}
#[test]
fn orchestrate_update_floors_against_running_version_when_registry_offline() {
let mut ops = FakeOps {
latest: None,
live: vec![
InstalledProbe::Unprobeable,
InstalledProbe::Version("0.0.1".to_string()),
],
staged: InstalledProbe::Version("0.0.1".to_string()),
installed: InstalledProbe::Version("0.0.1".to_string()),
..Default::default()
};
let err = orchestrate_update("linux", "x86_64", &mut ops)
.expect_err("a binary older than the running update binary must fail even offline");
assert!(err.to_string().contains("incomplete"), "{err:?}");
}
#[test]
fn orchestrate_update_warns_but_succeeds_when_probe_is_unavailable() {
let mut ops = FakeOps {
installed: InstalledProbe::Unprobeable,
..Default::default()
};
orchestrate_update("linux", "x86_64", &mut ops)
.expect("an unprobeable launcher must not fail an otherwise-verified update");
assert!(ops.happened("reregister claude"));
assert_eq!(ops.reconciled_with, Some(true));
}
#[test]
fn orchestrate_update_does_not_remove_orphan_when_reregistration_fails() {
let mut ops = FakeOps {
reregister_fails: vec![HarnessId::ClaudeCode],
..Default::default()
};
orchestrate_update("linux", "x86_64", &mut ops).expect("update should still succeed");
assert_eq!(
ops.reconciled_with,
Some(false),
"failed re-registration must prevent orphan removal"
);
}
#[test]
fn install_invocation_uses_no_shell_wrappers() {
let args = staging_install_args(
Path::new("C:/npm/.symforge-update-staging"),
&install_specs("windows", "x86_64"),
);
let text = invocation_text(
npm_executable_for_os("windows"),
&args.iter().map(String::as_str).collect::<Vec<_>>(),
)
.to_ascii_lowercase();
assert!(!text.contains("powershell"));
assert!(!text.contains("cmd /c"));
assert!(!text.contains("executionpolicy"));
}
#[test]
fn a_failed_daemon_stop_is_reported_and_the_restart_still_runs() {
let mut ops = FakeOps {
stop: Err("reading daemon port file: access denied".to_string()),
..Default::default()
};
orchestrate_update("linux", "x86_64", &mut ops).expect("update should succeed");
assert!(ops.position("swap") < ops.position("daemon 7.15.4"));
}
#[test]
fn orchestrate_update_skips_the_swap_when_the_live_binary_is_latest_but_still_verifies() {
let mut ops = FakeOps {
live: vec![InstalledProbe::Version("7.15.4".to_string())],
wrapper: Some("7.15.4".to_string()),
..Default::default()
};
orchestrate_update("windows", "x86_64", &mut ops).expect("an up-to-date update succeeds");
assert!(
!ops.events.iter().any(|e| e.starts_with("stage")),
"{:?}",
ops.events
);
assert!(!ops.happened("swap"));
assert!(
!ops.happened("stop-daemon"),
"nothing is stopped when nothing is swapped"
);
assert!(
ops.happened("daemon 7.15.4"),
"post-verify still restarts/ensures the daemon"
);
assert!(
ops.happened("initialize"),
"post-verify still replays initialize"
);
}
#[test]
fn orchestrate_update_never_short_circuits_without_a_registry_answer() {
let mut ops = FakeOps {
latest: None,
live: vec![InstalledProbe::Version(
env!("CARGO_PKG_VERSION").to_string(),
)],
staged: InstalledProbe::Version(env!("CARGO_PKG_VERSION").to_string()),
installed: InstalledProbe::Version(env!("CARGO_PKG_VERSION").to_string()),
..Default::default()
};
orchestrate_update("linux", "x86_64", &mut ops).expect("update should succeed");
assert!(ops.happened("swap"), "equal-to-unknown is not up to date");
}
#[test]
fn a_staged_binary_behind_the_registry_aborts_before_the_swap() {
let mut ops = FakeOps {
staged: InstalledProbe::Version("7.15.2".to_string()),
..Default::default()
};
let err = orchestrate_update("linux", "x86_64", &mut ops)
.expect_err("a stale staged binary must not be swapped in");
assert!(err.to_string().contains("7.15.2"), "{err}");
assert!(!ops.happened("swap") && !ops.happened("stop-daemon"));
}
#[test]
fn a_silent_new_binary_fails_the_update_loudly_and_skips_reregistration() {
let mut ops = FakeOps {
initialize: Err("no `initialize` result within 10s".to_string()),
..Default::default()
};
let err = orchestrate_update("linux", "x86_64", &mut ops)
.expect_err("an unanswered initialize must fail the update");
assert!(format!("{err:#}").contains("initialize"), "{err:#}");
assert!(!ops.events.iter().any(|e| e.starts_with("reregister")));
assert_eq!(ops.reconciled_with, None);
assert!(
ops.position("initialize") < ops.position("rollback"),
"{:?}",
ops.events
);
assert_eq!(
ops.events.iter().filter(|e| *e == "stop-daemon").count(),
2,
"the daemon started from the new binary is stopped before the restore: {:?}",
ops.events
);
assert!(format!("{err:#}").contains("was restored"), "{err:#}");
}
#[test]
fn a_daemon_restart_failure_is_reported_not_swallowed() {
let mut ops = FakeOps {
live: vec![InstalledProbe::Version("7.15.4".to_string())],
wrapper: Some("7.15.4".to_string()),
daemon: Err("auto-spawn disabled".to_string()),
..Default::default()
};
let mut summary = UpdateSummary::default();
update_steps("linux", "x86_64", &mut ops, &mut summary).expect("update should succeed");
assert!(ops.happened("initialize"));
assert_eq!(summary.daemon, Some(Err("auto-spawn disabled".to_string())));
}
#[test]
fn a_daemon_that_will_not_start_after_a_swap_rolls_the_swap_back() {
let mut ops = FakeOps {
daemon: Err("timed out waiting for symforge daemon to become ready".to_string()),
..Default::default()
};
let mut summary = UpdateSummary::default();
let err = update_steps("linux", "x86_64", &mut ops, &mut summary)
.expect_err("a daemon that will not start from the new binary fails the update");
assert!(ops.position("daemon 7.15.4") < ops.position("rollback"));
assert!(!ops.happened("initialize") && !ops.happened("reregister claude"));
assert_eq!(summary.swap, SwapState::RolledBack);
assert!(
format!("{err:#}").contains("did not start from the new binary"),
"{err:#}"
);
}
#[test]
fn a_daemon_restart_refused_by_policy_after_a_swap_keeps_the_new_binary() {
let mut ops = FakeOps {
daemon: Ok(InstalledDaemon::Skipped(
"SYMFORGE_DAEMON_AUTOSPAWN is off".to_string(),
)),
..Default::default()
};
let mut summary = UpdateSummary::default();
update_steps("linux", "x86_64", &mut ops, &mut summary)
.expect("a policy refusal is not a broken binary");
assert!(!ops.happened("rollback"), "{:?}", ops.events);
assert!(ops.happened("initialize") && ops.happened("reregister claude"));
assert_eq!(summary.swap, SwapState::Swapped);
assert!(
summary
.render()
.contains("daemon restarted: no, skipped (SYMFORGE_DAEMON_AUTOSPAWN is off)"),
"{}",
summary.render()
);
}
#[test]
fn offline_a_staged_copy_of_what_is_installed_is_not_swapped() {
let running = env!("CARGO_PKG_VERSION").to_string();
let mut ops = FakeOps {
latest: None,
live: vec![InstalledProbe::Version(running.clone())],
wrapper: Some(running.clone()),
staged: InstalledProbe::Version(running.clone()),
installed: InstalledProbe::Version(running),
..Default::default()
};
let mut summary = UpdateSummary::default();
update_steps("linux", "x86_64", &mut ops, &mut summary)
.expect("nothing to do is a success");
assert!(
!ops.happened("stop-daemon") && !ops.happened("swap"),
"{:?}",
ops.events
);
assert!(ops.happened("initialize"));
assert!(
summary
.render()
.contains("npm staged this same version; swap skipped"),
"{}",
summary.render()
);
}
#[test]
fn a_failed_swap_is_rolled_back_and_a_failed_rollback_is_never_reported_unchanged() {
let mut ops = FakeOps {
swap_fails: true,
..Default::default()
};
let mut summary = UpdateSummary::default();
update_steps("linux", "x86_64", &mut ops, &mut summary).expect_err("the swap failed");
assert!(ops.position("swap") < ops.position("rollback"));
assert_eq!(summary.swap, SwapState::RolledBack);
assert!(!ops.events.iter().any(|e| e.starts_with("daemon ")));
let mut ops = FakeOps {
swap_fails: true,
roll_back: Err(
"could not restore 1 file(s); the previous version's files are kept in \
/npm/.symforge-update-stale"
.to_string(),
),
..Default::default()
};
let mut summary = UpdateSummary::default();
let err =
update_steps("linux", "x86_64", &mut ops, &mut summary).expect_err("the swap failed");
assert_eq!(summary.swap, SwapState::Started);
let text = summary.render();
assert!(
text.contains("7.15.3 -> 7.15.4 INCOMPLETE") && !text.contains("unchanged"),
"{text}"
);
assert!(
format!("{err:#}").contains("/npm/.symforge-update-stale"),
"the error names where the previous files are: {err:#}"
);
}
#[test]
fn the_previous_versions_kept_by_a_swap_are_swept_only_after_verification() {
let mut ops = FakeOps::default();
orchestrate_update("linux", "x86_64", &mut ops).expect("update should succeed");
assert!(ops.position("initialize") < ops.position("sweep"));
let mut ops = FakeOps {
initialize: Err("no `initialize` result within 10s".to_string()),
..Default::default()
};
orchestrate_update("linux", "x86_64", &mut ops).expect_err("verification failed");
assert!(
!ops.happened("sweep"),
"the kept copies are what the rollback restores: {:?}",
ops.events
);
}
#[test]
fn a_wrapper_behind_the_registry_is_swapped_even_when_the_binary_is_current() {
let mut ops = FakeOps {
live: vec![InstalledProbe::Version("7.15.4".to_string())],
wrapper: Some("7.15.3".to_string()),
..Default::default()
};
orchestrate_update("linux", "x86_64", &mut ops).expect("update should succeed");
assert!(ops.happened("swap"), "{:?}", ops.events);
}
#[test]
fn a_live_binary_ahead_of_the_registry_is_never_replaced() {
let mut ops = FakeOps {
live: vec![InstalledProbe::Version("7.16.0".to_string())],
wrapper: Some("7.16.0".to_string()),
..Default::default()
};
orchestrate_update("linux", "x86_64", &mut ops).expect("nothing to do is a success");
assert!(!ops.events.iter().any(|e| e.starts_with("stage")));
assert!(!ops.happened("swap"));
}
#[test]
fn a_staged_binary_older_than_the_live_one_is_refused_when_the_registry_is_unreachable() {
let mut ops = FakeOps {
latest: None,
live: vec![InstalledProbe::Version("7.15.4".to_string())],
staged: InstalledProbe::Version("7.15.3".to_string()),
..Default::default()
};
let err = orchestrate_update("linux", "x86_64", &mut ops)
.expect_err("an older staged binary must not replace a newer live one");
assert!(err.to_string().contains("does not downgrade"), "{err}");
assert!(!ops.happened("swap") && !ops.happened("stop-daemon"));
}
#[test]
fn plan_reregistration_leaves_current_and_http_attached_harnesses_alone() {
let mut scan = scan_of(&[
(HarnessId::ClaudeCode, HarnessState::PresentCurrent),
(HarnessId::Codex, HarnessState::PresentCurrent),
(
HarnessId::Cursor,
HarnessState::PresentStale(crate::cli::harness::StaleFields::Url),
),
]);
scan.already_current = vec![HarnessId::ClaudeCode];
scan.http_attached = vec![HarnessId::Cursor];
let (targets, notes) = plan_reregistration(&scan, false);
assert_eq!(targets, vec![HarnessId::Codex]);
let text = notes.join("\n");
assert!(text.contains("unchanged: Claude Code"), "{text}");
assert!(text.contains("Cursor (it attaches over HTTP"), "{text}");
let (targets, _) = plan_reregistration(&scan, true);
assert_eq!(targets, vec![HarnessId::ClaudeCode, HarnessId::Codex]);
}
#[test]
fn plan_reregistration_touches_only_harnesses_that_already_use_symforge() {
let mut scan = scan_of(&[
(HarnessId::ClaudeCode, HarnessState::PresentCurrent),
(
HarnessId::Codex,
HarnessState::PresentStale(crate::cli::harness::StaleFields::Url),
),
(HarnessId::Gemini, HarnessState::NotInstalled),
(HarnessId::Cursor, HarnessState::Absent),
(
HarnessId::ClaudeDesktop,
HarnessState::Malformed("expected `=`, found `sk-secret`".to_string()),
),
(HarnessId::KiloCode, HarnessState::PresentCurrent),
]);
scan.grok_config_present = true;
let (targets, skipped) = plan_reregistration(&scan, true);
assert_eq!(targets, vec![HarnessId::ClaudeCode, HarnessId::Codex]);
let text = skipped.join("\n");
assert!(
text.contains("Claude Desktop") && text.contains("does not parse"),
"{text}"
);
assert!(
!text.contains("sk-secret"),
"a parse error can quote a credential and must not be echoed: {text}"
);
assert!(
text.contains("Kilo Code") && text.contains("project-local"),
"{text}"
);
assert!(text.contains("Grok"), "{text}");
assert!(
!text.contains("Gemini") && !text.contains("Cursor"),
"{text}"
);
}
#[test]
fn summary_renders_versions_harnesses_daemon_initialize_and_skips() {
let summary = UpdateSummary {
old_version: "11.2.0".to_string(),
new_version: "11.3.0".to_string(),
swap: SwapState::Swapped,
reregistered: vec!["Claude Code", "Codex"],
daemon: Some(Ok(InstalledDaemon::Running {
port: 51234,
started: true,
})),
initialize: Some(Ok(())),
notes: vec!["skipped: re-registering Cursor: init exited with 1".to_string()],
};
assert_eq!(
summary.render(),
"symforge update summary:\n version: 11.2.0 -> 11.3.0\n re-registered: Claude Code, Codex\n \
daemon restarted: yes (port 51234)\n binary answers initialize: yes\n \
skipped: re-registering Cursor: init exited with 1"
);
let up_to_date = UpdateSummary {
old_version: "11.3.0".to_string(),
new_version: "11.3.0".to_string(),
swap: SwapState::UpToDate,
daemon: Some(Err("auto-spawn disabled".to_string())),
..Default::default()
};
let text = up_to_date.render();
assert!(
text.contains("11.3.0 (already the latest; swap skipped)"),
"{text}"
);
assert!(text.contains("re-registered: none"), "{text}");
assert!(
text.contains("daemon restarted: no (auto-spawn disabled)"),
"{text}"
);
assert!(
text.contains("binary answers initialize: no (not attempted)"),
"{text}"
);
let failed = UpdateSummary {
old_version: "11.2.0".to_string(),
notes: vec!["skipped: 1 leftover(s) in C:/npm/.symforge-update-stale".to_string()],
..Default::default()
};
let text = failed.render();
assert!(text.contains("version: 11.2.0 (unchanged)"), "{text}");
assert!(
text.contains("daemon restarted: no (not attempted)"),
"{text}"
);
assert!(text.contains("skipped: 1 leftover(s)"), "{text}");
}
#[test]
fn initialize_result_requires_the_replayed_id_and_a_protocol_version() {
assert!(is_initialize_result(
r#"{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{}}}"#
));
assert!(!is_initialize_result(
r#"{"jsonrpc":"2.0","id":1,"error":{"code":-32600,"message":"bad"}}"#
));
assert!(!is_initialize_result(
r#"{"jsonrpc":"2.0","method":"notifications/message"}"#
));
assert!(!is_initialize_result("not json"));
}
#[test]
fn verify_initialize_fails_fast_when_the_binary_cannot_start() {
let tmp = tempfile::tempdir().unwrap();
let err = verify_initialize_at(
&tmp.path().join("missing-symforge"),
tmp.path(),
Duration::from_secs(1),
)
.expect_err("a missing binary cannot answer");
assert!(format!("{err:#}").contains("stdio MCP server"), "{err:#}");
}
#[test]
fn staging_install_is_local_to_the_staging_prefix_and_never_global() {
let staging = Path::new("/npm/.symforge-update-staging");
let args = staging_install_args(staging, &install_specs("linux", "x86_64"));
assert_eq!(
args,
vec![
"install",
"--prefix",
&staging.display().to_string(),
"--no-save",
"symforge@latest",
"symforge-linux-x64@latest",
]
);
assert!(
!args.iter().any(|a| a == "-g" || a == "--global"),
"{args:?}"
);
}
#[test]
fn install_layout_maps_the_live_and_staged_binary_per_os() {
let prefix = Path::new("/p");
assert_eq!(
native_binary_in(
&global_modules_dir(prefix, "windows"),
"symforge-windows-x64",
"windows"
),
prefix.join("node_modules/symforge-windows-x64/bin/symforge.exe")
);
assert_eq!(
native_binary_in(
&global_modules_dir(prefix, "linux"),
"symforge-linux-x64",
"linux"
),
prefix.join("lib/node_modules/symforge-linux-x64/bin/symforge")
);
let staging = update_staging_dir(prefix);
assert_eq!(staging, prefix.join(".symforge-update-staging"));
assert!(!staging.starts_with(global_modules_dir(prefix, "windows")));
}
struct NeverExits {
kills: usize,
}
impl Waitable for NeverExits {
fn try_wait(&mut self) -> std::io::Result<Option<std::process::ExitStatus>> {
Ok(None)
}
fn kill(&mut self) -> std::io::Result<()> {
self.kills += 1;
Ok(())
}
}
#[test]
fn wait_or_kill_times_out_kills_the_child_and_returns_false() {
let mut child = NeverExits { kills: 0 };
let result = wait_or_kill(
&mut child,
std::time::Instant::now(),
std::time::Duration::from_millis(1),
)
.expect("a timeout is Ok(false), not an error");
assert!(!result, "a timed-out swap must return Ok(false)");
assert_eq!(child.kills, 1, "the hung child must be killed exactly once");
}
#[test]
fn stale_staging_dir_is_the_global_prefix_sibling_not_inside_a_wrapper() {
let prefix = std::path::Path::new("C:/Users/me/AppData/Roaming/npm");
let dir = stale_staging_dir(prefix);
assert_eq!(
dir,
std::path::Path::new("C:/Users/me/AppData/Roaming/npm/.symforge-update-stale"),
"staging dir is the global prefix's .symforge-update-stale"
);
assert!(
!dir.starts_with("C:/Users/me/AppData/Roaming/npm/node_modules"),
"staging dir must be a global-prefix sibling, outside node_modules: {dir:?}"
);
}
#[test]
fn sweep_stale_dir_removes_leftovers_skips_unremovable_and_tolerates_missing() {
let tmp = tempfile::tempdir().unwrap();
let dir = tmp.path();
std::fs::write(dir.join("symforge.exe.old-1"), b"a").unwrap();
std::fs::write(dir.join("symforge.exe.old-2"), b"b").unwrap();
std::fs::create_dir(dir.join("locked-like-subdir")).unwrap();
let lines = sweep_stale_dir(dir);
assert!(!dir.join("symforge.exe.old-1").exists());
assert!(!dir.join("symforge.exe.old-2").exists());
assert!(dir.join("locked-like-subdir").exists());
assert_eq!(lines.len(), 2, "{lines:?}");
assert!(lines[0].contains("swept 2"), "{lines:?}");
assert!(lines[1].starts_with("skipped: 1 leftover"), "{lines:?}");
assert!(sweep_stale_dir(&dir.join("nope")).is_empty());
}
fn spawn_holder_at(path: &Path) -> std::process::Child {
#[cfg(windows)]
let (source, args): (&str, &[&str]) =
(r"C:\Windows\System32\PING.EXE", &["-n", "60", "127.0.0.1"]);
#[cfg(not(windows))]
let (source, args): (&str, &[&str]) = ("/bin/sleep", &["60"]);
std::fs::copy(source, path).expect("copy holder binary");
crate::process_util::hidden_command(path)
.args(args)
.stdout(Stdio::null())
.stderr(Stdio::null())
.spawn()
.expect("spawn holder")
}
#[test]
fn the_swap_replaces_a_running_binary_without_stopping_its_process() {
let tmp = tempfile::tempdir().unwrap();
let staged = tmp.path().join("staging/node_modules/pkg");
let live = tmp.path().join("node_modules/pkg");
let aside = tmp.path().join(".symforge-update-stale");
std::fs::create_dir_all(staged.join("bin")).unwrap();
std::fs::create_dir_all(live.join("bin")).unwrap();
let live_binary = live
.join("bin")
.join(native_binary_name(std::env::consts::OS));
std::fs::write(
staged
.join("bin")
.join(native_binary_name(std::env::consts::OS)),
b"new-binary",
)
.unwrap();
std::fs::write(staged.join("package.json"), b"{\"version\":\"2\"}").unwrap();
std::fs::write(live.join("package.json"), b"{\"version\":\"1\"}").unwrap();
std::fs::write(live.join("only-in-old.txt"), b"kept").unwrap();
let mut holder = spawn_holder_at(&live_binary);
let old_bytes = std::fs::read(&live_binary).unwrap();
let stop = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let probing = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let prober = {
let (stop, probing) = (
std::sync::Arc::clone(&stop),
std::sync::Arc::clone(&probing),
);
let path = live_binary.clone();
std::thread::spawn(move || {
let (mut checks, mut misses) = (0u64, 0u64);
loop {
checks += 1;
if std::fs::metadata(&path).is_err() {
misses += 1;
}
probing.store(true, std::sync::atomic::Ordering::Release);
if stop.load(std::sync::atomic::Ordering::Acquire) {
break;
}
}
(checks, misses)
})
};
while !probing.load(std::sync::atomic::Ordering::Acquire) {
std::thread::yield_now();
}
let mut journal = Vec::new();
let swapped = overlay_package(&staged, &live, &aside, false, &mut journal);
stop.store(true, std::sync::atomic::Ordering::Release);
let (checks, misses) = prober.join().unwrap();
let still_running = holder.try_wait().unwrap().is_none();
holder.kill().unwrap();
holder.wait().unwrap();
swapped.expect("the overlay succeeds over a running binary");
assert!(still_running, "the running session must survive the swap");
assert_eq!(std::fs::read(&live_binary).unwrap(), b"new-binary");
assert_eq!(
std::fs::read(live.join("package.json")).unwrap(),
b"{\"version\":\"2\"}"
);
assert!(live.join("only-in-old.txt").exists());
assert!(checks > 0);
let kept = journal
.iter()
.find(|(path, _)| *path == live_binary)
.and_then(|(_, previous)| previous.clone())
.expect("the binary's previous version is kept");
assert_eq!(std::fs::read(&kept).unwrap(), old_bytes);
if cfg!(windows) {
for entry in std::fs::read_dir(&aside).unwrap().flatten() {
let bytes = std::fs::read(entry.path()).unwrap();
assert!(
bytes == old_bytes || bytes == b"{\"version\":\"1\"}",
"{entry:?}"
);
}
} else {
assert_eq!(misses, 0, "the path was absent in {misses}/{checks} probes");
}
}
#[test]
fn replace_file_moves_the_old_file_back_when_the_new_one_cannot_follow() {
let tmp = tempfile::tempdir().unwrap();
let src = tmp.path().join("staged.bin");
let dst = tmp.path().join("symforge.bin");
let aside = tmp.path().join("aside");
std::fs::write(&src, b"new").unwrap();
std::fs::write(&dst, b"old").unwrap();
let err = put_in_place(&src, &dst, &aside, |from, to| {
if from == src.as_path() {
Err(std::io::Error::from(std::io::ErrorKind::PermissionDenied))
} else {
std::fs::rename(from, to)
}
})
.expect_err("the staged file never landed");
assert_eq!(err.kind(), std::io::ErrorKind::PermissionDenied);
assert_eq!(
std::fs::read(&dst).unwrap(),
b"old",
"the old file is back in place"
);
assert_eq!(std::fs::read_dir(&aside).unwrap().count(), 0);
assert_eq!(std::fs::read(&src).unwrap(), b"new");
}
#[test]
fn replace_file_does_not_touch_the_target_for_other_errors() {
let tmp = tempfile::tempdir().unwrap();
let dst = tmp.path().join("symforge.bin");
std::fs::write(&dst, b"old").unwrap();
let err = put_in_place(
&tmp.path().join("missing"),
&dst,
&tmp.path().join("aside"),
|a, b| std::fs::rename(a, b),
)
.expect_err("a missing staged file is an error");
assert_eq!(err.kind(), std::io::ErrorKind::NotFound);
assert_eq!(std::fs::read(&dst).unwrap(), b"old");
assert!(!tmp.path().join("aside").exists());
}
#[test]
fn replace_file_keeps_the_previous_file_for_a_rollback() {
let tmp = tempfile::tempdir().unwrap();
let aside = tmp.path().join("aside");
let rename = |from: &Path, to: &Path| std::fs::rename(from, to);
let (src, dst) = (
tmp.path().join("staged.bin"),
tmp.path().join("symforge.bin"),
);
std::fs::write(&src, b"new").unwrap();
std::fs::write(&dst, b"old").unwrap();
let mut journal = Vec::new();
replace_file(&src, &dst, &aside, &mut journal, rename).unwrap();
let previous = journal[0]
.1
.clone()
.expect("the replaced file keeps a copy");
assert_eq!(journal[0].0, dst);
assert_eq!(std::fs::read(&dst).unwrap(), b"new");
assert_eq!(std::fs::read(&previous).unwrap(), b"old");
let fresh_src = tmp.path().join("staged-2.bin");
std::fs::write(&fresh_src, b"new").unwrap();
replace_file(
&fresh_src,
&tmp.path().join("fresh.bin"),
&aside,
&mut journal,
rename,
)
.unwrap();
assert_eq!(journal[1].1, None, "a new file has no previous version");
}
#[test]
fn a_replacement_that_fails_midway_is_still_journaled_for_the_rollback() {
let tmp = tempfile::tempdir().unwrap();
let aside = tmp.path().join("aside");
let (src, dst) = (
tmp.path().join("staged.bin"),
tmp.path().join("symforge.bin"),
);
std::fs::write(&src, b"new").unwrap();
std::fs::write(&dst, b"old").unwrap();
let mut journal = Vec::new();
replace_file(&src, &dst, &aside, &mut journal, |from, to| {
if from == src.as_path() {
Err(std::io::Error::from(std::io::ErrorKind::PermissionDenied))
} else {
std::fs::rename(from, to)
}
})
.expect_err("the staged file never landed");
assert_eq!(journal.len(), 1, "a failed move must still be journaled");
let previous = journal[0].1.as_ref().expect("the previous copy was kept");
assert_eq!(std::fs::read(previous).unwrap(), b"old");
}
fn link_dir(target: &Path, link: &Path) {
#[cfg(unix)]
std::os::unix::fs::symlink(target, link).expect("symlink");
#[cfg(windows)]
if std::os::windows::fs::symlink_dir(target, link).is_err() {
let status = crate::process_util::hidden_command("cmd")
.args(["/C", "mklink", "/J"])
.arg(link)
.arg(target)
.stdout(Stdio::null())
.status()
.expect("run mklink");
assert!(status.success(), "mklink /J failed");
}
}
#[test]
fn a_linked_npm_prefix_resolves_to_its_real_directory() {
let tmp = tempfile::tempdir().unwrap();
let real = tmp.path().join("nvm").join("v22.20.0");
std::fs::create_dir_all(&real).unwrap();
let link = tmp.path().join("nodejs");
link_dir(&real, &link);
assert_eq!(
resolve_prefix(&link.display().to_string()),
Some(dunce::canonicalize(&real).unwrap()),
"harness registrations and the daemon name the real path, so update must too"
);
assert_eq!(resolve_prefix(""), None);
assert_eq!(
resolve_prefix(&tmp.path().join("missing").display().to_string()),
None
);
}
fn write_file(path: &Path, body: &str) {
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, body).unwrap();
}
const TEST_PACKAGE: &str = "symforge-test-x64";
fn fake_install() -> (tempfile::TempDir, PathBuf) {
let os = std::env::consts::OS;
let prefix = tempfile::tempdir().unwrap();
let modules = global_modules_dir(prefix.path(), os);
let staged = update_staging_dir(prefix.path()).join("node_modules");
write_file(
&staged
.join(TEST_PACKAGE)
.join("bin")
.join(native_binary_name(os)),
"new-binary",
);
write_file(
&staged.join("symforge").join("package.json"),
r#"{"version":"2.0.0"}"#,
);
write_file(
&modules.join("symforge").join("package.json"),
r#"{"version":"1.0.0"}"#,
);
(prefix, modules)
}
fn installed_binary(package_dir: &Path) -> PathBuf {
package_dir
.join("bin")
.join(native_binary_name(std::env::consts::OS))
}
#[test]
fn the_swap_updates_the_nested_platform_package_the_launcher_resolves_first() {
let (prefix, modules) = fake_install();
let [nested, top] = platform_package_dirs(&modules, TEST_PACKAGE);
write_file(&installed_binary(&nested), "old-binary");
let mut ops = RealUpdateOps::new(
std::env::consts::OS,
TEST_PACKAGE,
prefix.path().to_path_buf(),
prefix.path().to_path_buf(),
);
assert_eq!(ops.live_binary, installed_binary(&nested));
ops.swap_staged_into_place().unwrap();
assert_eq!(
std::fs::read_to_string(installed_binary(&nested)).unwrap(),
"new-binary"
);
assert!(
!top.exists(),
"no top-level copy is invented beside the nested one"
);
assert_eq!(ops.wrapper_version().as_deref(), Some("2.0.0"));
}
#[test]
fn the_swap_updates_every_installed_copy_of_the_platform_package() {
let (prefix, modules) = fake_install();
let dirs = platform_package_dirs(&modules, TEST_PACKAGE);
for dir in &dirs {
write_file(&installed_binary(dir), "old-binary");
}
let mut ops = RealUpdateOps::new(
std::env::consts::OS,
TEST_PACKAGE,
prefix.path().to_path_buf(),
prefix.path().to_path_buf(),
);
ops.swap_staged_into_place().unwrap();
for dir in &dirs {
assert_eq!(
std::fs::read_to_string(installed_binary(dir)).unwrap(),
"new-binary",
"{}",
dir.display()
);
}
}
#[test]
fn roll_back_restores_every_file_the_swap_replaced() {
let (prefix, modules) = fake_install();
let top = modules.join(TEST_PACKAGE);
write_file(&installed_binary(&top), "old-binary");
let mut ops = RealUpdateOps::new(
std::env::consts::OS,
TEST_PACKAGE,
prefix.path().to_path_buf(),
prefix.path().to_path_buf(),
);
ops.swap_staged_into_place().unwrap();
assert_eq!(ops.wrapper_version().as_deref(), Some("2.0.0"));
ops.roll_back().expect("every previous file is restored");
assert_eq!(
std::fs::read_to_string(installed_binary(&top)).unwrap(),
"old-binary"
);
assert_eq!(ops.wrapper_version().as_deref(), Some("1.0.0"));
}
#[test]
fn harness_scan_leaves_a_harness_that_already_runs_the_live_binary_alone() {
let (prefix, modules) = fake_install();
write_file(&installed_binary(&modules.join(TEST_PACKAGE)), "old-binary");
let home = tempfile::tempdir().unwrap();
let mut ops = RealUpdateOps::new(
std::env::consts::OS,
TEST_PACKAGE,
prefix.path().to_path_buf(),
home.path().to_path_buf(),
);
let entry = |server: serde_json::Value| {
serde_json::json!({ "mcpServers": { "symforge": server } }).to_string()
};
write_file(
&home.path().join(".claude.json"),
&entry(serde_json::json!({ "command": ops.live_binary.display().to_string() })),
);
write_file(
&home.path().join(".cursor").join("mcp.json"),
&entry(serde_json::json!({ "command": "/elsewhere/symforge" })),
);
write_file(
&home.path().join(".gemini").join("settings.json"),
&entry(serde_json::json!({ "url": "http://127.0.0.1:8787/mcp" })),
);
let scan = ops.harness_scan();
assert_eq!(scan.already_current, vec![HarnessId::ClaudeCode]);
assert_eq!(scan.http_attached, vec![HarnessId::Gemini]);
assert_eq!(plan_reregistration(&scan, false).0, vec![HarnessId::Cursor]);
}
#[test]
fn a_second_update_is_refused_while_the_first_holds_the_lock() {
let prefix = tempfile::tempdir().unwrap();
let held = lock_update(prefix.path()).expect("the first update takes the lock");
let err = lock_update(prefix.path()).expect_err("a second update must not run");
assert!(err.to_string().contains("already running"), "{err}");
drop(held);
lock_update(prefix.path()).expect("the lock is free once the first update ends");
}
#[test]
#[cfg(windows)]
fn move_file_replace_existing_ffi_moves_a_plain_file() {
let tmp = tempfile::tempdir().unwrap();
let src = tmp.path().join("src.bin");
let dst = tmp.path().join("staged.old-42");
std::fs::write(&src, b"payload").unwrap();
windows_native::move_file_replace_existing(&src, &dst).expect("FFI move succeeds");
assert!(!src.exists(), "the source path is freed after the move");
assert_eq!(std::fs::read(&dst).unwrap(), b"payload");
}
#[test]
#[cfg(windows)]
fn move_path_aside_frees_the_source_path() {
let tmp = tempfile::tempdir().unwrap();
let src = tmp.path().join("symforge.exe");
let staged = tmp
.path()
.join(".symforge-update-stale")
.join("symforge.exe.old-1");
std::fs::create_dir_all(staged.parent().unwrap()).unwrap();
std::fs::write(&src, b"binary").unwrap();
move_path_aside(&src, &staged).expect("move aside succeeds");
assert!(!src.exists(), "the install path is freed for npm");
assert!(staged.exists());
}
static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
struct SymforgeHomeGuard {
prev: Option<std::ffi::OsString>,
}
impl SymforgeHomeGuard {
#[allow(unsafe_code)] fn set(value: &std::path::Path) -> Self {
let prev = std::env::var_os("SYMFORGE_HOME");
unsafe { std::env::set_var("SYMFORGE_HOME", value) };
Self { prev }
}
}
impl Drop for SymforgeHomeGuard {
#[allow(unsafe_code)] fn drop(&mut self) {
match &self.prev {
Some(prev) => unsafe { std::env::set_var("SYMFORGE_HOME", prev) },
None => unsafe { std::env::remove_var("SYMFORGE_HOME") },
}
}
}
#[test]
fn remove_orphan_durable_bin_cleans_under_symforge_home_and_spares_self_exe() {
let _g = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let home = tempfile::TempDir::new().unwrap();
let bin = home.path().join("bin");
std::fs::create_dir_all(&bin).unwrap();
let leftover = bin.join("symforge.exe");
std::fs::write(&leftover, b"old-7.14.4-binary").unwrap();
let bystander = bin.join("notes.txt");
std::fs::write(&bystander, b"keep me").unwrap();
let _home_guard = SymforgeHomeGuard::set(home.path());
let self_exe = std::env::current_exe().unwrap();
assert!(self_exe.exists(), "precondition: running exe exists");
let summary = remove_orphan_durable_bin_at(&crate::domain::ControlStateDir::new(
home.path().to_path_buf(),
));
assert!(
!leftover.exists(),
"the retired durable leftover under $SYMFORGE_HOME/bin must be removed"
);
assert_eq!(summary.len(), 1, "exactly one summary line: {summary:?}");
assert!(
summary[0].contains("symforge.exe"),
"summary names what was removed: {summary:?}"
);
assert!(bystander.exists(), "an unwatched file must be left alone");
assert!(
self_exe.exists(),
"the binary backing the running process must never be deleted"
);
}
#[test]
fn remove_orphan_durable_bin_skips_the_running_binary_when_it_lives_in_the_bin_dir() {
let _g = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let self_exe = match std::env::current_exe()
.ok()
.and_then(|p| std::fs::canonicalize(p).ok())
{
Some(p) => p,
None => return, };
let home = tempfile::TempDir::new().unwrap();
let bin = home.path().join("bin");
std::fs::create_dir_all(&bin).unwrap();
let watched = bin.join("symforge.exe");
if make_symlink(&self_exe, &watched).is_err() {
return;
}
let resolves_to_self =
std::fs::canonicalize(&watched).ok().as_deref() == Some(self_exe.as_path());
if !resolves_to_self {
return;
}
let _home_guard = SymforgeHomeGuard::set(home.path());
let summary = remove_orphan_durable_bin();
assert!(
watched.exists() || std::fs::symlink_metadata(&watched).is_ok(),
"the entry resolving to the running binary must NOT be removed"
);
assert!(self_exe.exists(), "the running binary itself must survive");
assert!(
summary.is_empty(),
"nothing should be reported removed: {summary:?}"
);
}
#[cfg(unix)]
fn make_symlink(src: &std::path::Path, dst: &std::path::Path) -> std::io::Result<()> {
std::os::unix::fs::symlink(src, dst)
}
#[cfg(windows)]
fn make_symlink(src: &std::path::Path, dst: &std::path::Path) -> std::io::Result<()> {
std::os::windows::fs::symlink_file(src, dst)
}
}