Automatically install and relaunch macOS updates

[johanntan]

Problem and behavior

On macOS, accepting an update currently opens the verified DMG and leaves the user to quit the app and drag its replacement into Applications. This change prepares and installs the update automatically for writable, Apple developer-signed app bundles, replacing the app at its existing path and relaunching it. Custom folders and renamed bundles are supported. Protected, mounted-image, Gatekeeper-translocated, unsigned and ad-hoc installations keep the manual flow; no administrator authorization is requested.

Implementation

• Download into a private temporary directory and retain Minisign verification before installation.
• Mount the DMG privately and read-only, require exactly one top-level app matching the running bundle identifier, and validate its executable and code signature before and after staging it beside the installed app. Native code requirements enforce an Apple-issued signing chain with the running app's developer Team ID. Preparation runs off the UI thread and checks cancellation between stages.
• Start a detached helper with an explicit ready/commit handshake. After the host exits, recheck the installation identity and replace bundles with same-filesystem renames. Restore the old app if replacement fails; preserve its backup and report the recovery path if restoration or relaunch fails.
• Sweep abandoned stages older than 24 hours on the next automatic update, limited to the same bundle and user with no live host/helper. Preserve recent stages, symlinks, uncertain ownership metadata and recovery backups. Delete successful/canceled helper logs and retain failure logs under ~/Library/Logs/ship-shape-update-*.log.
• Add run_update_check_with_exit_handler so the host can save state and quit normally, and with_macos_relaunch_env to preserve explicit native environment values through Launch Services. The existing update-check entry point keeps its immediate-exit behavior.
• Keep the progress gauge below native completion and defer completion until an active Update/Pulse call returns, avoiding dialog destruction and storage borrowing during nested native event processing.

The README documents integration, signer requirements, manual fallback, recovery, timeouts and testing. The repository demo creates disposable v1/v2 apps and a DMG; automatic installation requires an Apple-issued signing identity, while ad-hoc fixtures use manual fallback. Its shared-source harness is excluded from the published crate package and does not add a production local-file installation API.

Validation

• 64 automated tests pass on macOS, covering replacement, rollback, failed restore/launch, cancellation, timeouts, competing destination changes, bundle identity, signature tampering, ad-hoc signer rejection, quoted paths, stale-stage safety, log deletion/retention and nested progress completion.
• The additional optional signed-release test passes with an existing notarized Paperback app: its own developer team is accepted and a different team is rejected.
• Standalone cargo clippy --all-targets -- -D warnings passes with this crate's declared lint settings and normal published wxDragon dependency. Formatting and whitespace checks pass.
• cargo package --list confirms the demo is excluded and the installer helper assets are included.

The original replacement/relaunch mechanism was exercised end to end with a disposable Paperback copy and the ad-hoc v1/v2 demo. After tightening the signer policy, automatic demo installation requires a developer signing identity and has not been rerun here; the new signer check was verified separately against a notarized release.

Limits and translation

The helper allows 60 seconds for host shutdown. Launch Services success confirms that macOS accepted the request; it does not detect a later application crash. Failed launch preserves the old bundle rather than automatically rolling back an app that may already have started. Recovery backups are not automatically swept.

The new macOS user-facing strings use patois::t and will need catalog translations in consuming apps.

Companion integration: trypsynth/paperback#1004, a draft using the shutdown callback to save application state before replacement and announce the restart to VoiceOver. It is pinned to this PR's reviewed commit and will switch to a published crate dependency after this change is merged and released.

[trypsynth]

Thanks for this, it's careful work. I read all of it, ran the 62 tests on macOS (all pass), and ran the demo end to end: v1 was replaced by v2, relaunched, and nothing was left next to the bundle. A few things before it can go in.

Needs fixing

1. The signature check accepts an app signed by anyone. codesign --verify --deep --strict only checks that the replacement is validly signed, not by whom. An ad-hoc signature passes: the demo's installed app ends up Signature=adhoc, TeamIdentifier=not set. Minisign on the DMG is still the real guard, but please require the replacement to carry the running app's Team ID, or to satisfy the running bundle's designated requirement (codesign -d -r-, then codesign --verify -R=...). If the running app has no Team ID, as with an unsigned dev build, fall back to the manual flow.
2. cargo clippy --all-targets -- -D warnings fails on two lints in the new code: missing backticks in a doc comment at src/ui/progress.rs:71, and a missing ; at src/ui.rs:244. Master is clean. The lints that matter are the ones in this crate's own Cargo.toml, not Paperback's workspace.

Should fix

3. Stale staging directories. .ship-shape-* is created next to the app, so usually in /Applications, and holds a full copy of the app. If the helper dies during its window (logout, power loss), nothing ever removes it. Please sweep stale .ship-shape-* directories next to the bundle on the next update, or on launch.
4. Logs accumulate. Every update leaves a ~/Library/Logs/ship-shape-update-*.log, even a successful one. Remove it on success, or keep only the last few.

Minor

• The demo includes src/platform/macos.rs through #[path] and redefines InstallOutcome to make it compile. That's brittle, and it gets published with the crate unless examples/ is excluded from the package.
• This adds about 20 translatable strings, which is fine, just flagging it for translators.

Done well

• The helper only takes paths as arguments, never as shell source, and passes alert text to osascript as argv.
• It uses atomic renames, restores the old bundle on failure, and only proceeds after an explicit commit.
• It rechecks the bundle's inode before replacing it.
• It skips translocated, symlinked and unwritable bundles.
• The DMG is mounted private and read-only, must contain exactly one app with the same bundle ID, and the executable must sit inside that bundle.
• Cancelling at any stage is clean.
• The progress lifecycle fix and its tests deal with a real re-entrancy problem.
• Windows and Linux keep their existing behaviour.

[johanntan]

Pushed bbbdc57 with the review fixes:

1. Signer identity: both the running app and the replacement must satisfy a native codesign -R requirement for an Apple-issued signing chain and the same developer Team ID. The replacement is checked before and after staging. Hosts with no Team ID, including ad-hoc development builds, use the manual DMG flow.
2. Clippy: fixed the doc-comment backticks and missing semicolon, and checked the crate standalone using its own lint settings and normal published wxDragon dependency. cargo clippy --all-targets -- -D warnings now passes.
3. Abandoned stages: stage metadata records the bundle path and host/helper PIDs. The next automatic update sweeps stages older than 24 hours only for the same bundle and user, with neither process alive. Recent stages, symlinks, uncertain metadata, other apps' stages, and anything containing an old.app recovery backup are preserved. The backup exception is intentional so cleanup cannot remove the only recoverable app after an interrupted swap.
4. Logs: successful installation and canceled preparation remove their helper log; failure logs remain for diagnosis. Tests assert both behaviors.

The repository demo now accepts SHIP_SHAPE_DEMO_SIGNING_ID for an Apple-issued signing identity; without one, its ad-hoc fixtures exercise manual fallback. I kept the shared-source harness to avoid exposing a production API for installing arbitrary local files, but excluded examples/ from the published package and verified the package file list. It remains covered by the all-targets clippy check.

Validation: 64 automated tests pass, plus the optional read-only signed-release test, which accepts an existing notarized Paperback release for its own team and rejects a different team. Formatting and whitespace checks pass. I have not rerun automatic v1-to-v2 demo installation with a developer signing identity; the earlier ad-hoc end-to-end demo no longer qualifies for automatic installation under the new policy.

Translation note: the new macOS user-facing messages use patois::t, including the signer rejection message, and will need catalog translations in consuming apps.