hex/docs/plans/swift-app-handoff.md

136 lines
7.5 KiB
Markdown

# Swift App Handoff
## Decision
There is no Swift-to-Rust data migration, but the old apps update straight
into the new one (Kit, 2026-11-02: "gotta get everyone over"). 2.3.1 and Swift
Hex both run Sparkle 2.9.4 with the same EdDSA key, so their feeds offer the
released `Hex.app` and **Install Update** replaces the old app with it. See
[Legacy Update](#legacy-update).
- Do not import Swift settings, history, audio, models, or other data.
- Nothing installs without the user's Install Update click, and nothing is
deleted. Once setup is ready and the listener starts, `anomaly.hex` asks a
running old Hex (the retired bundle IDs below) to quit, so the two never
answer the same shortcut.
- Do not adopt the Swift bundle identifier.
- Do not move or copy existing Rust settings, models, or history.
- Narrow TCC exception: when `anomaly.hex` shows an untrusted Accessibility,
Screen Recording, or System Audio Recording permission row (or the user clicks
`"Still grey? Fix it"`), it may run `tccutil reset` against retired Hex bundle
identifiers (`com.kitlangton.hex2`, `com.kitlangton.Hex`, `com.kitlangton.Hex.debug`)
so System Settings does not list duplicate **Hex** rows that shadow the new grant.
- New Rust users complete ordinary setup and download their selected local model.
## Separate Identities
The Rust app is called **Hex**, packaged as **Hex.app**, with
bundle identifier `com.kitlangton.hex2` and executable `hex`. Its Application Support
root is `hex`. The supported platform remains Apple silicon with
macOS 15 or newer. The new bundle identity requires fresh macOS permission grants;
changing the display name alone does not change signing ownership.
Kit's personal Developer ID Application certificate (team `QC99C9JE59`) is approved
for this app. Explicitly provide `HEX_TEAM_ID` and the matching
`HEX_NOTARY_PROFILE` before release; an Anomaly signing account is not required.
Swift retains its own bundle identity, sandbox data, and S3 update feed. Intel
and macOS 14 users can continue using Swift without an incompatible-install nag.
On case-insensitive volumes, the two app filenames can conflict. Finder may ask
whether to replace an existing app during manual installation; that remains the
user's choice, not an automated migration. The development installer refuses to
replace a destination whose bundle identifier is not the Rust identifier.
Users should quit the old app before dictating in the new one to avoid running
two global hotkey listeners.
## Legacy Update
Sparkle 2.9.4 installs the new app over 2.3.1 (`HEX.app` or `Hex.app`) and Swift
Hex because:
- **It finds the app.** The ZIP's `Hex.app` matches the old app's file name or
its `CFBundleName` plus `.app`
([SUInstaller.m](https://github.com/sparkle-project/Sparkle/blob/2.9.4/Autoupdate/SUInstaller.m)).
- **The key passes.** The old app has `SUPublicEDKey`, so Sparkle refuses an
update without one; `app/Info.plist` keeps the same key, and the ZIP is signed
with its private half. A passing EdDSA check is enough when the team differs
([SUUpdateValidator.m](https://github.com/sparkle-project/Sparkle/blob/2.9.4/Sparkle/SUUpdateValidator.m)).
- **It is not a downgrade.** The new `CFBundleVersion` (30300 and up) exceeds
2.3.1's 20301 and Swift's 92.
- **The swap is not atomic.** The team differs, so Sparkle moves the old app
aside and the new one in, then opens it.
Each feed gets one item whose enclosure is the release's
`Hex-<version>-macos-arm64.zip`, with `sparkle:edSignature` from the old key,
`sparkle:version` the new `CFBundleVersion`, `sparkle:minimumSystemVersion`
15.0, and `sparkle:hardwareRequirements` arm64. Macs that cannot run the new
Hex keep their last compatible release. The new Hex starts fresh: new
permissions, model, and shortcut.
## Legacy Notice (superseded)
Swift 0.8.5/build 92 already ships a dismissible link to the Rust app. This Rust
release does not publish another Swift build or change its S3 feed. The optional
feed-only notice below remains a separate future action.
Prefer a [website-only Sparkle update](https://sparkle-project.org/documentation/publishing/#downloading-from-a-web-site),
not another custom Swift popup or bridge build. The shipping `v0.8.5` source pins
Sparkle 2.9.4, which supports both the informational item and platform gates.
After the new signed app and download page are live, add one item to the existing
Swift S3 appcast while preserving every existing release and artifact:
- `link`: `https://github.com/anomalyco/hex`, the public download page.
- `sparkle:version`: reserve 93 if still unused; it must exceed installed build 92.
- `sparkle:shortVersionString`: the public Rust release advertised when the notice
is published; do not copy a stale version from this plan.
- `sparkle:minimumSystemVersion`: 15.0.0.
- `sparkle:hardwareRequirements`: arm64.
- `sparkle:minimumUpdateVersion`: 92.
- Embedded release notes explain separate installation, new permissions and
model setup, no settings/history transfer, and the same-name app-file collision.
- Omit `enclosure` entirely, including delta enclosures. Without a download URL,
Sparkle treats the item as informational. No Rust installer goes in this feed.
The standard button is **Learn More...**, which opens the page and closes the
window. **Skip This Version** persists a dismissal. **Remind Me Later**, closing
the window, or opening the website does not permanently dismiss the notice.
Manual Check for Updates can show a skipped notice again. This is not a guaranteed
one-time custom modal, and appcast text cannot rename the standard buttons.
OS and architecture gates work without an enclosure in Sparkle 2.9.4. Older
Sparkle versions may ignore the architecture/minimum-update gates; unsupported
users may still reach an informational page, but never an automatic install.
Keep requirements explicit on that page and retain Swift build 92 for compatible
legacy updates. Do not mark the notice critical or redirect the old feed.
Before publication, verify the actual distributed Swift bundle, automatic and
manual checks, skip/remind behavior, and supported/unsupported Mac configurations.
The announcement is only a proposal until the new signed artifact is available
and these behaviors are validated.
## Releases
Prepare and publish Rust through `scripts/release-app.sh`, with identity checks
from `scripts/validate-app.sh`. Publish immutable artifacts before the R2 feed.
The manual DMG contains `Hex.app`; the Sparkle ZIP keeps the old Rust `HEX.app`
archive name. Sparkle 2.9.4 uses case-sensitive filenames or matching bundle IDs
to discover an update, so changing both at once would hide the update payload
from 2.0.x installations. Both artifacts contain the same signed, stapled app.
Validate the approved signing identity and installation behavior before publishing.
Do not assume permissions or login-item registrations survive the identity change.
Publish the legacy informational feed item independently after the new artifact
is available. A Swift rebuild is unnecessary unless the stock Sparkle UI proves
insufficient. No transition archive, cross-feed payload, preference importer, or
migration rollback is needed.
## GitHub Handoff
Keep the old Swift repository's history, issues, and releases. A prominent README
notice and repository website link can direct users to `anomalyco/hex`; archive
the old repository only after the handoff is complete and explicitly approved.
Do not overwrite its history with Rust source. An actual repository transfer is
a separate decision because `anomalyco/hex` already exists; GitHub does not merge
the two repositories' stars, issues, and histories automatically.