feat(updater): perry/updater subsystem — auto-update for desktop apps

[TheHypnoo]

What and why

Perry doesn't have a built-in updater, which means apps shipping to desktop users either roll their own download + replace + relaunch flow or just don't ship updates at all. This adds a perry/updater module that handles the boring and security-critical parts: manifest fetch, semver compare, hash + Ed25519 signature verification, atomic install with rollback, and detached relaunch.

The design mostly follows Tauri's updater (small, opinionated, doesn't try to own the whole release pipeline). I also looked at Wails — similar shape but more bring-your-own — and Electron's autoUpdater, which is Squirrel-based and much heavier than what Perry needs. Tauri's manifest + Ed25519-over-the-digest + staged-file-then-rename approach was the closest fit, so the wire format and the trust model here are mostly a port of that.

What landed

crates/perry-updater is a single crate with two internal modules:

• core — pure cross-platform helpers: semver compare (via the semver crate), SHA-256 file hashing, Ed25519 verification (via ed25519-dalek), and the sentinel write/read/clear used to detect crash-loops. The signed payload is the raw 32-byte SHA-256 digest of the binary, not the hex string and not the file bytes themselves — that's documented at the top of the .d.ts so signing tools and the verifier don't drift apart later.
• desktop — per-OS exe path resolution (walks up to the .app bundle on macOS, honors \$APPIMAGE on Linux, falls back to a canonicalized current_exe() otherwise), atomic install with `.prev` backup, and detached relaunch (setsid via pre_exec on Unix, DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP on Windows).

The split into core/desktop modules is because they really do have different audit surfaces — core is pure logic with no I/O on the executable, desktop touches files and processes — but they live in the same crate. There's no good reason to have two crates for what amounts to ~800 lines of Rust.

The download itself stays in TS, using the existing fetch().arrayBuffer() + fs.writeFileSync + fs.renameSync. Pulling the network into Rust would mean either standing up a second async runtime or duplicating reqwest, and Perry's existing fetch is already wired and tested.

Why no mobile

iOS apps go through App Store / TestFlight, Android through Play Store or sideloaded APKs. The OS owns the install pipeline on both — replacing your own binary at runtime is structurally impossible (and would get the app pulled even if it weren't). So this is unapologetically desktop-only. The crate still compiles on mobile targets because the cfg(target_os) arms in desktop route everything that isn't macOS / Windows to the unix branch — that way cross-platform user code doesn't have to ifdef around the import.

What I changed elsewhere

A few primitives were missing and got added alongside the updater:

• js_fs_chmod_sync in perry-runtime — needed for the install step on Unix to make sure the new binary is +x. POSIX-only effective; no-op success on Windows where mode bits don't apply.
• js_child_process_spawn_detached in perry-runtime — a real detached spawn (different from the existing spawn_background, which keeps the child in a registry). Useful well beyond the updater for any CLI that launches a daemon or helper.
• js_crypto_ed25519_verify in perry-stdlib, gated by the existing crypto feature. Raw verify primitive parallel to the X25519 stuff already in crypto_e2e.rs. Also usable directly from user code that just wants Ed25519 sigverify without the full updater.
• New PERRY_UPDATER_TABLE in perry-codegen/src/lower_call.rs (12 entries, one per FFI symbol) plus a dispatch arm at module == \"perry/updater\" mirroring the existing perry/system / perry/i18n shapes. New chmodSync arm in the fs block. \"perry/updater\" added to NATIVE_MODULES in perry-hir/src/ir.rs so imports resolve.

TS surface

• types/perry/updater/index.d.ts — flat ambient, the primitives the codegen routes through.
• packages/perry-updater/ (npm: @perry/updater) — high-level wrapper. Entry points are checkForUpdate({manifestUrl, publicKey, currentVersion}) returning an Update object with download(onProgress?) and installAndRelaunch(), plus initUpdater() for the boot-time crash-loop detection.

Manifest schema is JSON, schema-versioned, one entry per <os>-<arch>:

```json
{
"schemaVersion": 1,
"version": "1.4.0",
"pubDate": "2026-04-27T10:00:00Z",
"notes": "...",
"platforms": {
"darwin-aarch64": { "url": "...", "sha256": "...", "signature": "...", "size": 12345 },
"windows-x86_64": { ... },
"linux-x86_64": { ... }
}
}
```

What's deliberately not here

• UI primitives (a modal with ProgressView + a "Restart Now" button). I think that belongs inside perry/ui proper rather than a separate @perry/updater-ui package, so it's a follow-up PR.
• An end-to-end self-update test in CI. The unit tests cover all the building blocks (semver compare, hash mismatch, signature roundtrip with tampering, install + rollback, sentinel idempotency, env-var path resolution), but the full install → relaunch → boot-with-sentinel-check loop only exists as a manual smoke test right now.
• Notarization / code-signing during install. Binaries are expected to arrive already signed; the updater doesn't try to be a notarization tool.
• Privileged install for system-wide /Applications or Program Files. This PR only handles user-writable locations (~/Applications, ~/.local/bin, %LOCALAPPDATA%). UAC / SMJobBless is a separate concern.
• Delta updates (bsdiff), multi-channel (stable/beta), staged rollouts.

Tests

9 unit tests in the new crate (core::tests::* and desktop::tests::*) covering semver edge cases including prerelease and invalid input, SHA-256 mismatch detection, Ed25519 roundtrip with file tampering, install + rollback, missing-backup rejection, sentinel idempotent clear, and PERRY_APP_ID-driven path resolution.

I also ran an end-to-end smoke test against a real Perry binary on macOS to verify the codegen wiring — compareVersions, getExePath, getSentinelPath, and sentinel write/read/clear all work through the FFI dispatch and round-trip the expected values.

Honest test coverage

I built and tested this on macOS. Linux and Windows paths are gated behind cfg(target_os) and didn't even compile on my host. The design matches well-documented OS semantics on all three platforms (POSIX rename(2) atomicity on the same filesystem, NTFS rename-while-open when the file is opened with FILE_SHARE_DELETE — which the PE loader does since Vista — and the kernel keeping mmap'd inodes alive on Linux), but I haven't run the install + relaunch path end-to-end on Linux or Windows. CI will catch compile errors; the runtime behavior on non-Mac is a calculated bet on documented OS semantics that should be smoke-tested before anyone relies on this in production.

Two things worth verifying before declaring this production-ready:

1. Windows: compile Perry, fake an install, confirm the running EXE gets replaced and the new one launches. The OS-level support is there but I haven't exercised it.
2. Linux: try this against a real AppImage. The \$APPIMAGE env-var handling follows the AppImage convention but I've only tested with bare ELF binaries.

Test plan

• cargo test -p perry-updater passes on the CI runner
• Cross-platform compile of a tiny Perry binary that imports perry/updater on Linux and Windows
• Manual smoke of install + relaunch on Windows
• Manual smoke against an AppImage on Linux
• At merge time: maintainer bumps version, adds CLAUDE.md entry per CONTRIBUTING.md

[proggeramlug]

Love this! Let’s wait for the tests and then see to merge it!

[proggeramlug]

Thanks for this — the design is well-considered and the README is refreshingly honest about the unverified Win/Linux paths. Tauri-shaped manifest + signed-over-SHA256-digest + sentinel rollback is the right shape for v1, and keeping the download in TS rather than dragging another async runtime into Rust is the right call.

A few things I'd want addressed before merge. Don't worry about rebasing yet — lower_call.rs is in flux locally (we just split it into sub-modules and stood up a perry-dispatch crate that PERRY_UPDATER_TABLE should ultimately live in); we'll handle the merge mechanics when our in-flight work lands.

1. Sentinel restart-counting will misfire on short-lived apps. initUpdater arms a 60s setTimeout to clear the sentinel post-update. If the user legitimately closes the app within that window — CLI tools, quick-launch GUIs, anything a user might run-and-quit — the sentinel survives, and the next legitimate boot bumps the count toward rollback. The threshold of 2 makes a normal close-and-reopen pattern indistinguishable from a crash loop. Two ways out: (a) clear-on-clean-exit hook so a graceful shutdown clears the sentinel regardless of the timer, (b) reframe restartCount as "restarts without graceful shutdown" and only increment when the previous run didn't clear cleanly. (a) is simpler.

2. ed25519-dalek is linked twice. js_crypto_ed25519_verify in perry-stdlib/crypto.rs and perry_updater_verify_signature in perry-updater/core.rs both pull ed25519-dalek and have their own glue. Both end up in libperry_stdlib.a. Pick one home — easiest is to have the updater route through the stdlib primitive (the updater's verify_signature becomes "compute SHA-256 of file, then call into the stdlib verify").

3. Detached-spawn is duplicated. js_child_process_spawn_detached (runtime) and perry_updater_relaunch (updater) have the same setsid / DETACHED_PROCESS|CREATE_NEW_PROCESS_GROUP body. Extract a shared helper — the updater's relaunch should be js_child_process_spawn_detached with the staged exe path.

4. Atomicity claims need a comment about what "atomic" actually means per-OS. "Atomic on the same filesystem on every supported platform" is true for rename(2) between two paths, but on macOS replacing a .app is a directory rename whose live-process safety comes from the running fds keeping their inodes alive after the dirent moves — that's correct, but it's worth a comment in desktop.rs citing the actual mechanism per platform (POSIX rename(2) inode survival, NTFS FILE_SHARE_DELETE on the loader's image-section mapping). Future debuggers will thank you.

Non-blockers but worth thinking about: signing the raw 32-byte SHA-256 with plain Ed25519 (vs Ed25519ph) is the Tauri convention so it's defensible, but a // Note: ... near the verify function explaining the choice would head off the inevitable security-review question.

The unit test coverage is good for what it covers; the missing piece is end-to-end on Windows + a real AppImage on Linux, which you've already flagged. Happy to keep this open while you run those smoke tests.