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

7.5 KiB

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.

  • 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).
  • 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).
  • 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, 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.