feat: in-app update check and self-update on macOS, Linux, and Windows #37

Summary

Today users must watch GitHub Releases and reinstall manually. Installed OpenPolySphere should:

1. Check for updates — on startup, at most once per day in the background, and on demand from the UI (“Check for updates”).
2. Offer an update — show current vs available version, short release notes, and actions: Update / Later / Skip this version.
3. Update itself across all supported install methods — without losing user data (settings, models, call history).

Same behavior on every OS; only the install mechanism for the release artifact differs.

Platforms and formats (v0.4.2+)

User data is already outside the bundle/install dir:

• macOS: ~/Library/Application Support/OpenPolySphere/
• Linux (deb/rpm): ~/.local/share/OpenPolySphere/ or $XDG_DATA_HOME
• Windows (installer): %LOCALAPPDATA%\OpenPolySphere\

Updates must not touch models, settings, or the DB in those directories.

Current state

• Product version comes from the release tag (v0.4.2) at package time (Info.plist, artifact names); workspace crates in Cargo.toml are still 0.1.0.
• translator has no version/update API or UI yet.
• Source of truth for new versions: GitHub Releases API (GET /repos/org-event/OpenPolySphere/releases/latest).
• No code signing / notarization on macOS yet — silent installs will stay limited until signing exists.

Proposed phases

1. Versioning and check

• Embed product version at build time (env OPENPOLYSPHERE_VERSION from CI/tag).
• GET /api/version — { "version": "0.4.2", "channel": "stable" }.
• Background check: GitHub Releases, semver compare; cache last check in user data (max once per day).
• Check on server start + button in Settings / About.
• UI: banner or modal “Version X available” + link to release notes.

2. Self-update per platform

• Portable zip (all OSes): download → verify SHA256 from release assets → unpack to temp dir → replace binary/web → restart via launcher.
• Windows installer: download .exe, run /SILENT or /VERYSILENT (Inno), restart when done.
• Linux .deb / .rpm: pkexec / sudo + apt install ./…deb / dnf install ./…rpm, or fallback with a ready terminal command.
• macOS .app: download .zip or mount .dmg, replace /Applications/OpenPolySphere.app (via helper/launcher with permissions); Gatekeeper without signing — explicit warning for now.

3. Reliability and UX

• Do not block the translator during checks (async, timeout).
• Setting to disable automatic checks.
• Log network errors / checksum mismatches.
• Docs: docs/updates.md + site/README notes.

Acceptance criteria

• Installed v0.4.x on each of the three OSes sees a new release within a day or immediately via the button.
• User can update from the app without hunting GitHub (at minimum portable + Windows installer; deb/rpm may use guided one-command install).
• After update, settings, models, and call history are preserved.
• CI: unit tests for semver parsing and correct asset selection by (os, arch).

Out of scope (separate issues)

• Apple notarization and signed updates (Sparkle / tauri-plugin-updater).
• Delta/patch updates, beta channel, rollback.

Related

• Release workflow: .github/workflows/release.yml
• User data paths: crates/translator/src/paths.rs
• Packaging: scripts/package-{macos-app,linux,windows}.*
• Tauri/updater notes: docs/tauri-next.md

Help wanted: phase 1 can land as its own PR; phase 2 — one platform at a time. Architecture feedback welcome.