ruby_everywhere 0.1.7 → 0.1.9

data/support/shell/src-tauri/src/updater.rs

@@ -0,0 +1,745 @@
+// Self-updater: our own take on the Tauri updater, built for hand-assembled
+// bundles (tauri.conf has bundle.active=false, so tauri-plugin-updater's
+// artifacts don't exist here).
+//
+// Contract (see cli/lib/everywhere/update_manifest.rb — the canonical spec):
+//   GET {updates.url}/{channel}/{os}/{arch}/latest.json?current={version}
+// answered identically by a raw bucket/CDN or a Platform endpoint. An update
+// installs only after the FULL verification chain passes:
+//   sha256 -> minisign signature (public key baked into everywhere.json) ->
+//   codesign --verify --deep --strict -> Info.plist bundle_id + version match.
+//
+// Page JS drives it through bridge events (everywhere:update-check /
+// update-install / update-set-channel in; update-available / -none /
+// -progress / -ready / -error / -channel out); the "Check for Updates…" menu
+// item drives the same flows with native dialogs. `updates.auto` picks the
+// background behaviour: off | check | download | install (silent swap staged
+// in RAM-free renames on quit).
+//
+// Channel: everywhere.yml's updates.channel is the default; a user choice made
+// through the bridge (Everywhere.updates.setChannel) is persisted to the app
+// data dir and overrides it from then on — the server-driven settings page
+// decides who gets to see a "beta" option, the shell just honors the pick.
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Mutex;
+use std::time::Duration;
+
+use tauri::{Emitter, Listener, Manager};
+
+#[derive(Clone, Copy, PartialEq, PartialOrd)]
+pub enum Auto {
+    Off,
+    Check,
+    Download,
+    Install,
+}
+
+pub struct UpdateConfig {
+    pub url: String,
+    pub channel: String,
+    pub public_key: String,
+    pub auto: Auto,
+    pub interval: u64,
+    pub current: semver::Version,
+    pub bundle_id: String,
+}
+
+#[derive(Clone)]
+pub struct Manifest {
+    pub version: String,
+    pub semver: semver::Version,
+    pub url: String,
+    pub sha256: String,
+    pub size_bytes: u64,
+    pub signature: String,
+    pub notes: Option<String>,
+    pub notes_html: Option<String>,
+    pub published_at: Option<String>,
+}
+
+struct Pending {
+    manifest: Manifest,
+    extracted_app: PathBuf,
+}
+
+pub struct UpdaterState {
+    cfg: UpdateConfig,
+    // The live channel. Starts as cfg.channel (which already reflects a
+    // persisted override — see apply_channel_override) and moves when the page
+    // calls setChannel.
+    channel: Mutex<String>,
+    pending: Mutex<Option<Pending>>,
+    busy: AtomicBool,
+}
+
+impl UpdaterState {
+    fn channel(&self) -> String {
+        self.channel.lock().unwrap().clone()
+    }
+}
+
+impl UpdateConfig {
+    // The shell subset of everywhere.yml's updates: section, from the same
+    // raw config JSON the rest of the shell reads. None => updater disabled.
+    pub fn parse(raw_json: &str) -> Option<UpdateConfig> {
+        let value: serde_json::Value = serde_json::from_str(raw_json).ok()?;
+        let updates = value.get("updates")?.as_object()?;
+        let url = updates.get("url")?.as_str()?.trim_end_matches('/').to_string();
+        let public_key = updates.get("public_key")?.as_str()?.to_string();
+
+        if !(url.starts_with("https://")
+            || url.starts_with("http://127.0.0.1")
+            || url.starts_with("http://localhost"))
+        {
+            eprintln!("[updater] refusing non-https updates.url {url}; updater disabled");
+            return None;
+        }
+        let Some(current) = value["version"].as_str().and_then(lenient_semver) else {
+            eprintln!("[updater] no parseable app version in config; updater disabled");
+            return None;
+        };
+
+        Some(UpdateConfig {
+            url,
+            channel: updates.get("channel").and_then(|v| v.as_str()).unwrap_or("stable").to_string(),
+            public_key,
+            auto: match updates.get("auto").and_then(|v| v.as_str()).unwrap_or("check") {
+                "off" => Auto::Off,
+                "download" => Auto::Download,
+                "install" => Auto::Install,
+                _ => Auto::Check,
+            },
+            interval: updates.get("interval").and_then(|v| v.as_u64()).unwrap_or(21_600).max(300),
+            current,
+            bundle_id: value["bundle_id"].as_str().unwrap_or("com.rubyeverywhere.app").to_string(),
+        })
+    }
+}
+
+pub fn enabled(raw_json: &str) -> bool {
+    UpdateConfig::parse(raw_json).is_some()
+}
+
+// Fold the persisted user channel choice (if any) into the raw config value.
+// main.rs calls this before the config is parsed OR injected into pages, so
+// the updater, the menu, and __EVERYWHERE_CONFIG__.updates.channel all agree
+// on the effective channel.
+pub fn apply_channel_override(handle: &tauri::AppHandle, value: &mut serde_json::Value) {
+    if !value["updates"].is_object() {
+        return;
+    }
+    let bundle_id = value["bundle_id"].as_str().unwrap_or("com.rubyeverywhere.app").to_string();
+    let Some(path) = channel_file(handle, &bundle_id) else { return };
+    let Ok(saved) = std::fs::read_to_string(&path) else { return };
+    let saved = saved.trim();
+    if valid_channel(saved) {
+        value["updates"]["channel"] = serde_json::json!(saved);
+    }
+}
+
+pub fn init(app: &tauri::App, raw_json: &str) {
+    let Some(cfg) = UpdateConfig::parse(raw_json) else {
+        return;
+    };
+    let auto = cfg.auto;
+    let interval = cfg.interval;
+    let channel = Mutex::new(cfg.channel.clone());
+    app.manage(UpdaterState { cfg, channel, pending: Mutex::new(None), busy: AtomicBool::new(false) });
+
+    {
+        let handle = app.handle().clone();
+        std::thread::spawn(move || cleanup_stale(&handle));
+    }
+
+    // Bridge: pages emit events (same sanctioned webview->shell path as
+    // everywhere:notify).
+    {
+        let handle = app.handle().clone();
+        app.listen_any("everywhere:update-check", move |_| {
+            let handle = handle.clone();
+            std::thread::spawn(move || explicit_check(&handle));
+        });
+    }
+    {
+        let handle = app.handle().clone();
+        app.listen_any("everywhere:update-install", move |_| {
+            let handle = handle.clone();
+            std::thread::spawn(move || {
+                if let Err(e) = install_flow(&handle) {
+                    emit_error(&handle, &e);
+                }
+            });
+        });
+    }
+    {
+        let handle = app.handle().clone();
+        app.listen_any("everywhere:update-set-channel", move |event| {
+            let payload = event.payload().to_string();
+            let handle = handle.clone();
+            std::thread::spawn(move || set_channel(&handle, &payload));
+        });
+    }
+
+    if auto != Auto::Off {
+        let handle = app.handle().clone();
+        std::thread::spawn(move || {
+            // Let the app boot before the first check.
+            std::thread::sleep(Duration::from_secs(15));
+            loop {
+                background_pass(&handle, auto);
+                std::thread::sleep(Duration::from_secs(interval));
+            }
+        });
+    }
+}
+
+// ---- flows ------------------------------------------------------------------
+
+// Bridge-triggered channel switch (Everywhere.updates.setChannel). Validates,
+// persists the choice so it survives relaunches, retargets the running
+// updater, and always answers: update-channel on success, update-error on a
+// bad request. A staged download from the old channel is discarded — it no
+// longer represents what the user asked to run.
+fn set_channel(handle: &tauri::AppHandle, payload: &str) {
+    let Some(state) = state(handle) else { return };
+    let requested = serde_json::from_str::<serde_json::Value>(payload)
+        .ok()
+        .and_then(|v| v["channel"].as_str().map(str::to_string));
+    let Some(channel) = requested.filter(|c| valid_channel(c)) else {
+        emit_error(handle, "invalid update channel (letters, digits, . _ - only)");
+        return;
+    };
+
+    if let Some(path) = channel_file(handle, &state.cfg.bundle_id) {
+        let write = path
+            .parent()
+            .map(|dir| std::fs::create_dir_all(dir).map_err(|e| e.to_string()))
+            .unwrap_or(Ok(()))
+            .and_then(|()| std::fs::write(&path, &channel).map_err(|e| e.to_string()));
+        if let Err(e) = write {
+            emit_error(handle, &format!("could not save channel choice: {e}"));
+            return;
+        }
+    }
+
+    let changed = {
+        let mut current = state.channel.lock().unwrap();
+        let changed = *current != channel;
+        *current = channel.clone();
+        changed
+    };
+    if changed {
+        *state.pending.lock().unwrap() = None;
+    }
+    println!("[updater] channel set to {channel}");
+    let _ = handle.emit_to("main", "everywhere:update-channel", serde_json::json!({ "channel": channel }));
+}
+
+// Bridge-triggered check: always answers with an event (available/none/error).
+fn explicit_check(handle: &tauri::AppHandle) {
+    let Some(state) = state(handle) else { return };
+    if state.busy.swap(true, Ordering::SeqCst) {
+        return;
+    }
+    match check(&state.cfg, &state.channel()) {
+        Ok(Some(m)) => emit_available(handle, &m),
+        Ok(None) => {
+            let _ = handle.emit_to("main", "everywhere:update-none",
+                serde_json::json!({ "version": state.cfg.current.to_string() }));
+        }
+        Err(e) => emit_error(handle, &e),
+    }
+    state.busy.store(false, Ordering::SeqCst);
+}
+
+// Menu-triggered check: native dialogs, then the shared install flow.
+pub fn interactive_check(handle: &tauri::AppHandle) {
+    use tauri_plugin_dialog::{DialogExt, MessageDialogButtons, MessageDialogKind};
+
+    let Some(state) = state(handle) else { return };
+    if state.busy.swap(true, Ordering::SeqCst) {
+        return;
+    }
+    let outcome = check(&state.cfg, &state.channel());
+    state.busy.store(false, Ordering::SeqCst);
+
+    match outcome {
+        Ok(Some(m)) => {
+            emit_available(handle, &m);
+            let notes = m.notes.clone().map(|n| format!("\n\n{n}")).unwrap_or_default();
+            let install = handle
+                .dialog()
+                .message(format!("Version {} is available (you have {}).{notes}", m.version, state.cfg.current))
+                .title("Update Available")
+                .buttons(MessageDialogButtons::OkCancelCustom(
+                    "Install and Restart".to_string(),
+                    "Later".to_string(),
+                ))
+                .blocking_show();
+            if install {
+                if let Err(e) = install_flow(handle) {
+                    emit_error(handle, &e);
+                    handle.dialog().message(e).title("Update Failed").kind(MessageDialogKind::Error).blocking_show();
+                }
+            }
+        }
+        Ok(None) => {
+            handle
+                .dialog()
+                .message(format!("You're up to date ({}).", state.cfg.current))
+                .title("No Updates")
+                .blocking_show();
+        }
+        Err(e) => {
+            emit_error(handle, &e);
+            handle.dialog().message(e).title("Update Check Failed").kind(MessageDialogKind::Error).blocking_show();
+        }
+    }
+}
+
+// The `updates.auto` background loop body.
+fn background_pass(handle: &tauri::AppHandle, auto: Auto) {
+    let Some(state) = state(handle) else { return };
+    if state.busy.swap(true, Ordering::SeqCst) {
+        return;
+    }
+    let result = (|| -> Result<(), String> {
+        let Some(m) = check(&state.cfg, &state.channel())? else { return Ok(()) };
+        emit_available(handle, &m);
+        if auto >= Auto::Download && !is_staged(&state, &m) {
+            let staged = download_and_stage(handle, &state.cfg, &m)?;
+            *state.pending.lock().unwrap() = Some(Pending { manifest: m.clone(), extracted_app: staged });
+            let _ = handle.emit_to("main", "everywhere:update-ready", serde_json::json!({ "version": m.version }));
+        }
+        Ok(())
+        // auto == Install finishes the job in install_pending_on_exit: the
+        // verified bundle swaps in via two renames when the user quits.
+    })();
+    state.busy.store(false, Ordering::SeqCst);
+    if let Err(e) = result {
+        eprintln!("[updater] background pass failed: {e}");
+        emit_error(handle, &e);
+    }
+}
+
+// Explicit install (bridge update-install event, or the menu dialog): stage if
+// needed, swap, relaunch.
+fn install_flow(handle: &tauri::AppHandle) -> Result<(), String> {
+    let state = state(handle).ok_or("updater not configured")?;
+
+    let pending = state.pending.lock().unwrap().take();
+    let pending = match pending {
+        Some(p) => p,
+        None => {
+            let m = check(&state.cfg, &state.channel())?.ok_or("already up to date")?;
+            emit_available(handle, &m);
+            let staged = download_and_stage(handle, &state.cfg, &m)?;
+            Pending { manifest: m, extracted_app: staged }
+        }
+    };
+
+    let _ = handle.emit_to("main", "everywhere:update-ready",
+        serde_json::json!({ "version": pending.manifest.version }));
+    swap_bundle(&pending.extracted_app, true)?;
+    handle.exit(0);
+    Ok(())
+}
+
+// RunEvent::Exit hook (main.rs): a fully staged+verified silent update swaps
+// in on quit. Renames only — adds no perceptible latency to quit.
+pub fn install_pending_on_exit(app: &tauri::AppHandle) {
+    let Some(state) = app.try_state::<UpdaterState>() else { return };
+    if state.cfg.auto != Auto::Install {
+        return;
+    }
+    let pending = state.pending.lock().unwrap().take();
+    if let Some(pending) = pending {
+        match swap_bundle(&pending.extracted_app, false) {
+            Ok(()) => println!("[updater] installed {} on quit", pending.manifest.version),
+            Err(e) => eprintln!("[updater] install-on-quit failed: {e}"),
+        }
+    }
+}
+
+// ---- check ------------------------------------------------------------------
+
+fn check(cfg: &UpdateConfig, channel: &str) -> Result<Option<Manifest>, String> {
+    let url = format!(
+        "{}/{}/{}/{}/latest.json?current={}",
+        cfg.url, channel, os_name(), arch_name(), cfg.current
+    );
+    println!("[updater] checking {url}");
+
+    let resp = ureq::get(&url)
+        .set("User-Agent", &format!("RubyEverywhere/{} ({})", cfg.current, os_name()))
+        .timeout(Duration::from_secs(30))
+        .call()
+        .map_err(|e| format!("update check failed: {e}"))?;
+    let value: serde_json::Value = resp.into_json().map_err(|e| format!("bad manifest JSON: {e}"))?;
+
+    let manifest = parse_manifest(&value)?;
+    Ok((manifest.semver > cfg.current).then_some(manifest))
+}
+
+fn parse_manifest(v: &serde_json::Value) -> Result<Manifest, String> {
+    let field = |k: &str| v[k].as_str().map(str::to_string).ok_or(format!("manifest missing {k}"));
+    let version = field("version")?;
+    Ok(Manifest {
+        semver: lenient_semver(&version).ok_or(format!("unparseable manifest version {version}"))?,
+        version,
+        url: field("url")?,
+        sha256: field("sha256")?.to_lowercase(),
+        size_bytes: v["size_bytes"].as_u64().unwrap_or(0),
+        signature: field("signature")?,
+        notes: v["notes"].as_str().map(str::to_string),
+        notes_html: v["notes_html"].as_str().map(str::to_string),
+        published_at: v["published_at"].as_str().map(str::to_string),
+    })
+}
+
+// ---- download + verify ------------------------------------------------------
+
+// Fetch, hash-check, signature-check, extract, codesign-check. Returns the
+// path of the verified extracted .app, ready to swap.
+fn download_and_stage(
+    handle: &tauri::AppHandle,
+    cfg: &UpdateConfig,
+    m: &Manifest,
+) -> Result<PathBuf, String> {
+    if !(m.url.starts_with("https://")
+        || m.url.starts_with("http://127.0.0.1")
+        || m.url.starts_with("http://localhost"))
+    {
+        return Err(format!("refusing non-https artifact url {}", m.url));
+    }
+
+    let dir = updates_dir(handle, cfg).join(&m.version);
+    std::fs::create_dir_all(&dir).map_err(|e| format!("cannot create {dir:?}: {e}"))?;
+    let filename = m.url.rsplit('/').next().unwrap_or("update.zip");
+    let zip = dir.join(filename);
+
+    if !(zip.exists() && sha256_file(&zip)? == m.sha256) {
+        download(handle, &m.url, &zip, m.size_bytes)?;
+        let actual = sha256_file(&zip)?;
+        if actual != m.sha256 {
+            let _ = std::fs::remove_file(&zip);
+            return Err(format!("sha256 mismatch: manifest {} vs downloaded {actual}", m.sha256));
+        }
+    }
+
+    verify_signature(&zip, &m.signature, &cfg.public_key)?;
+
+    let extracted = dir.join("extracted");
+    let _ = std::fs::remove_dir_all(&extracted);
+    std::fs::create_dir_all(&extracted).map_err(|e| e.to_string())?;
+    run_ok(Command::new("/usr/bin/ditto").arg("-xk").arg(&zip).arg(&extracted), "ditto extract")?;
+
+    let app_bundle = find_app_bundle(&extracted)?;
+    verify_bundle(&app_bundle, cfg, m)?;
+    println!("[updater] {} staged and verified at {app_bundle:?}", m.version);
+    Ok(app_bundle)
+}
+
+fn download(handle: &tauri::AppHandle, url: &str, dest: &Path, total: u64) -> Result<(), String> {
+    use std::io::{Read, Write};
+
+    let resp = ureq::get(url).timeout(Duration::from_secs(600)).call()
+        .map_err(|e| format!("download failed: {e}"))?;
+    let mut reader = resp.into_reader();
+    let tmp = dest.with_extension("part");
+    let mut file = std::fs::File::create(&tmp).map_err(|e| e.to_string())?;
+
+    let mut buf = vec![0u8; 1 << 16];
+    let mut downloaded: u64 = 0;
+    let mut last_emit: u64 = 0;
+    loop {
+        let n = reader.read(&mut buf).map_err(|e| format!("download interrupted: {e}"))?;
+        if n == 0 {
+            break;
+        }
+        file.write_all(&buf[..n]).map_err(|e| e.to_string())?;
+        downloaded += n as u64;
+        if downloaded - last_emit > 1_000_000 {
+            last_emit = downloaded;
+            let _ = handle.emit_to("main", "everywhere:update-progress",
+                serde_json::json!({ "downloaded": downloaded, "total": total }));
+        }
+    }
+    file.flush().map_err(|e| e.to_string())?;
+    drop(file);
+    std::fs::rename(&tmp, dest).map_err(|e| e.to_string())?;
+    let _ = handle.emit_to("main", "everywhere:update-progress",
+        serde_json::json!({ "downloaded": downloaded, "total": total }));
+    Ok(())
+}
+
+fn verify_signature(path: &Path, signature: &str, public_key: &str) -> Result<(), String> {
+    let pk = minisign_verify::PublicKey::from_base64(public_key)
+        .map_err(|e| format!("bad updates.public_key: {e}"))?;
+    let sig = minisign_verify::Signature::decode(signature)
+        .map_err(|e| format!("bad manifest signature: {e}"))?;
+    let data = std::fs::read(path).map_err(|e| e.to_string())?;
+    pk.verify(&data, &sig, false)
+        .map_err(|_| "signature verification FAILED — artifact does not match the app's signing key".to_string())
+}
+
+fn find_app_bundle(dir: &Path) -> Result<PathBuf, String> {
+    std::fs::read_dir(dir)
+        .map_err(|e| e.to_string())?
+        .filter_map(|e| e.ok())
+        .map(|e| e.path())
+        .find(|p| p.extension().is_some_and(|e| e == "app"))
+        .ok_or("no .app bundle in update archive".to_string())
+}
+
+// The post-extract checks: Apple's signature, then identity — the update must
+// BE this app (bundle id) at the version the manifest claims.
+fn verify_bundle(bundle: &Path, cfg: &UpdateConfig, m: &Manifest) -> Result<(), String> {
+    run_ok(
+        Command::new("/usr/bin/codesign").args(["--verify", "--deep", "--strict"]).arg(bundle),
+        "codesign verification",
+    )?;
+
+    let plist = bundle.join("Contents/Info.plist");
+    let bundle_id = plist_value(&plist, "CFBundleIdentifier")?;
+    if bundle_id != cfg.bundle_id {
+        return Err(format!("update bundle is {bundle_id}, not {} — refusing", cfg.bundle_id));
+    }
+    let version = plist_value(&plist, "CFBundleShortVersionString")?;
+    if version != m.version {
+        return Err(format!("update bundle is version {version}, manifest says {} — refusing", m.version));
+    }
+
+    // Quarantine would make Gatekeeper re-prompt on a file we already verified.
+    let _ = Command::new("/usr/bin/xattr").args(["-dr", "com.apple.quarantine"]).arg(bundle).status();
+    Ok(())
+}
+
+fn plist_value(plist: &Path, key: &str) -> Result<String, String> {
+    let out = Command::new("/usr/libexec/PlistBuddy")
+        .arg("-c")
+        .arg(format!("Print :{key}"))
+        .arg(plist)
+        .output()
+        .map_err(|e| e.to_string())?;
+    if !out.status.success() {
+        return Err(format!("no {key} in {plist:?}"));
+    }
+    Ok(String::from_utf8_lossy(&out.stdout).trim().to_string())
+}
+
+// ---- swap + relaunch --------------------------------------------------------
+
+// Sparkle-style swap of a RUNNING app: stage the new bundle onto the
+// destination volume, then two renames — the running process keeps its open
+// files; the paths just change owners. A detached helper deletes the old
+// bundle (and relaunches) once this process is gone.
+fn swap_bundle(new_app: &Path, relaunch: bool) -> Result<(), String> {
+    let dest = current_app_bundle()?;
+    let parent = dest.parent().ok_or("app bundle has no parent dir")?;
+    let name = dest.file_name().unwrap_or_default().to_string_lossy().to_string();
+
+    if !is_writable(parent) {
+        return Err(format!(
+            "{} isn't writable — move the app to Applications or your home folder, or reinstall manually",
+            parent.display()
+        ));
+    }
+
+    let staged = parent.join(format!(".{name}.update"));
+    let old = parent.join(format!(".{name}.old-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&staged);
+    // ditto (not rename): app_data may be another volume, and renames are only
+    // atomic same-volume.
+    run_ok(Command::new("/usr/bin/ditto").arg(new_app).arg(&staged), "staging copy")?;
+
+    std::fs::rename(&dest, &old).map_err(|e| format!("could not move old bundle aside: {e}"))?;
+    if let Err(e) = std::fs::rename(&staged, &dest) {
+        let _ = std::fs::rename(&old, &dest); // roll back, leave the app intact
+        return Err(format!("could not move update into place: {e}"));
+    }
+
+    let _ = Command::new("/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister")
+        .arg("-f")
+        .arg(&dest)
+        .status();
+
+    // Helper outlives us (own process group): wait for exit, drop the old
+    // bundle, optionally relaunch.
+    let open_cmd = if relaunch { format!("open {}; ", shq(&dest)) } else { String::new() };
+    let script = format!(
+        "while /bin/kill -0 {pid} 2>/dev/null; do sleep 0.2; done; rm -rf {old}; {open_cmd}exit 0",
+        pid = std::process::id(),
+        old = shq(&old),
+    );
+    let mut helper = Command::new("/bin/sh");
+    helper.arg("-c").arg(script);
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::CommandExt;
+        helper.process_group(0);
+    }
+    helper.spawn().map_err(|e| format!("could not spawn relaunch helper: {e}"))?;
+    Ok(())
+}
+
+// current_exe -> <App>.app/Contents/MacOS/<exe> -> <App>.app
+fn current_app_bundle() -> Result<PathBuf, String> {
+    let exe = std::env::current_exe().map_err(|e| e.to_string())?;
+    let bundle = exe.parent().and_then(Path::parent).and_then(Path::parent)
+        .ok_or("not running from an app bundle")?;
+    if bundle.extension().is_some_and(|e| e == "app") {
+        Ok(bundle.to_path_buf())
+    } else {
+        Err("not running from an installed .app (dev build?) — nothing to swap".to_string())
+    }
+}
+
+fn is_writable(dir: &Path) -> bool {
+    let probe = dir.join(format!(".everywhere-w-{}", std::process::id()));
+    match std::fs::File::create(&probe) {
+        Ok(_) => {
+            let _ = std::fs::remove_file(&probe);
+            true
+        }
+        Err(_) => false,
+    }
+}
+
+// ---- housekeeping -----------------------------------------------------------
+
+// Next-boot pruning: version dirs at or below what we now run, orphaned
+// .old-* bundles from a previous swap whose helper died early.
+fn cleanup_stale(handle: &tauri::AppHandle) {
+    let Some(state) = state(handle) else { return };
+    let dir = updates_dir(handle, &state.cfg);
+    if let Ok(entries) = std::fs::read_dir(&dir) {
+        for entry in entries.filter_map(|e| e.ok()) {
+            let name = entry.file_name().to_string_lossy().to_string();
+            if lenient_semver(&name).is_some_and(|v| v <= state.cfg.current) {
+                let _ = std::fs::remove_dir_all(entry.path());
+            }
+        }
+    }
+    if let Ok(bundle) = current_app_bundle() {
+        if let Some(parent) = bundle.parent() {
+            if let Ok(entries) = std::fs::read_dir(parent) {
+                for entry in entries.filter_map(|e| e.ok()) {
+                    let name = entry.file_name().to_string_lossy().to_string();
+                    if name.starts_with('.') && name.contains(".app.old-") {
+                        let _ = std::fs::remove_dir_all(entry.path());
+                    }
+                }
+            }
+        }
+    }
+}
+
+fn is_staged(state: &UpdaterState, m: &Manifest) -> bool {
+    state
+        .pending
+        .lock()
+        .unwrap()
+        .as_ref()
+        .is_some_and(|p| p.manifest.version == m.version && p.extracted_app.exists())
+}
+
+fn updates_dir(handle: &tauri::AppHandle, cfg: &UpdateConfig) -> PathBuf {
+    handle
+        .path()
+        .data_dir()
+        .map(|d| d.join(&cfg.bundle_id))
+        .unwrap_or_else(|_| std::env::temp_dir())
+        .join("updates")
+}
+
+// ---- helpers ----------------------------------------------------------------
+
+fn state(handle: &tauri::AppHandle) -> Option<tauri::State<'_, UpdaterState>> {
+    handle.try_state::<UpdaterState>()
+}
+
+// Where the user's channel choice lives: <data dir>/<bundle_id>/update-channel,
+// a plain-text sibling of the updates/ staging dir.
+fn channel_file(handle: &tauri::AppHandle, bundle_id: &str) -> Option<PathBuf> {
+    handle.path().data_dir().ok().map(|d| d.join(bundle_id).join("update-channel"))
+}
+
+// Channel names become a path segment of the feed URL — keep them boring.
+fn valid_channel(s: &str) -> bool {
+    !s.is_empty()
+        && s.len() <= 64
+        && s.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.'))
+}
+
+// notes = markdown source (also what the native dialog shows); notes_html =
+// pre-rendered HTML for in-app changelog UI. Both ride to the page untouched —
+// the feed is the developer's own signed content.
+fn emit_available(handle: &tauri::AppHandle, m: &Manifest) {
+    let _ = handle.emit_to("main", "everywhere:update-available",
+        serde_json::json!({ "version": m.version, "notes": m.notes,
+                            "notes_html": m.notes_html, "published_at": m.published_at }));
+}
+
+fn emit_error(handle: &tauri::AppHandle, message: &str) {
+    eprintln!("[updater] {message}");
+    let _ = handle.emit_to("main", "everywhere:update-error", serde_json::json!({ "message": message }));
+}
+
+fn sha256_file(path: &Path) -> Result<String, String> {
+    use sha2::{Digest, Sha256};
+    use std::io::Read;
+
+    let mut file = std::fs::File::open(path).map_err(|e| e.to_string())?;
+    let mut hasher = Sha256::new();
+    let mut buf = vec![0u8; 1 << 20];
+    loop {
+        let n = file.read(&mut buf).map_err(|e| e.to_string())?;
+        if n == 0 {
+            break;
+        }
+        hasher.update(&buf[..n]);
+    }
+    Ok(format!("{:x}", hasher.finalize()))
+}
+
+fn run_ok(cmd: &mut Command, what: &str) -> Result<(), String> {
+    let out = cmd.output().map_err(|e| format!("{what} failed to run: {e}"))?;
+    if out.status.success() {
+        Ok(())
+    } else {
+        Err(format!("{what} failed: {}", String::from_utf8_lossy(&out.stderr).trim()))
+    }
+}
+
+// "1.2" -> 1.2.0; strips a leading v. Returns None only when hopeless.
+fn lenient_semver(s: &str) -> Option<semver::Version> {
+    let s = s.trim().trim_start_matches('v');
+    semver::Version::parse(s).ok().or_else(|| {
+        let parts: Vec<&str> = s.split('.').collect();
+        match parts.len() {
+            1 => semver::Version::parse(&format!("{s}.0.0")).ok(),
+            2 => semver::Version::parse(&format!("{s}.0")).ok(),
+            _ => None,
+        }
+    })
+}
+
+fn os_name() -> &'static str {
+    std::env::consts::OS // "macos" | "windows" | "linux" — matches the bucket layout
+}
+
+fn arch_name() -> &'static str {
+    match std::env::consts::ARCH {
+        "aarch64" => "arm64",
+        other => other, // "x86_64" stays as-is
+    }
+}
+
+// Single-quote shell escaping for the helper script.
+fn shq(path: &Path) -> String {
+    format!("'{}'", path.to_string_lossy().replace('\'', r"'\''"))
+}