Emerson Beta — a Sparkle channel that runs on the Claude CLI

23 of 25 tasks done

Date: 2026-10-07
Status: 0.1.0 published 2026-10-10 (LochLustra e853953); tester checks pending
Goal: Give a remote tester an Emerson build that runs model calls through his own claude login and updates itself through Sparkle, the way Code Raven's beta does. The App Store / TestFlight build stays sandboxed, API-only, and free of Sparkle.

Why the TestFlight build can't do this

• TestFlight builds are Release builds. LLMTransport.current returns .api whenever DEBUG is off (Emerson/Services/ClaudeCLITransport.swift:16-24), and the CLI transport and its Settings picker are compiled only under #if DEBUG.
• Release builds sign with Emerson.entitlements, which turns the App Sandbox on. A sandboxed app cannot launch claude.
• The tester's banner, "LLMClient.LLMError error 8", is missingAPIKey. Swift numbers the cases that carry a payload first, which puts missingAPIKey at 8; this was confirmed by compiling the enum. LLMError has no LocalizedError conformance, so macOS prints the raw code.

Shape of the solution

A second app target, Emerson Beta, built from the same source folder:

A build configuration cannot do this job. Sparkle arrives as a Swift package, and Xcode links a package into every configuration of the target that depends on it. App Store review rejects self-updating apps, so Sparkle has to live in a target the App Store build never touches.

Compile flags

• CLAUDE_CLI gates the CLI transport. One flag replaces DEBUG at every CLI site, so the question "can this build launch claude?" has one answer in one place.
• EMERSON_BETA gates Sparkle and the beta's data folder.
• DEBUG keeps gating Persona Lab and the other developer panels, which stay out of the beta's Release build.

Phase 1 — Target and build settings

• Duplicate the Emerson target as Emerson Beta. Point it at the same synchronized root group (Emerson/), which Xcode 16 allows a second target to share.
• Build settings for the beta target:

  • PRODUCT_BUNDLE_IDENTIFIER = com.lochlustra.Emerson.beta
  • PRODUCT_NAME = Emerson Beta
  • CODE_SIGN_ENTITLEMENTS = Emerson/Emerson-Beta.entitlements
  • ENABLE_HARDENED_RUNTIME = YES (notarization requires it)
  • INFOPLIST_FILE = Emerson/Emerson-Beta-Info.plist, merged with the generated plist (GENERATE_INFOPLIST_FILE stays YES)
  • The compile flags from the table above
• Emerson/Emerson-Beta.entitlements: com.apple.security.app-sandbox = false and nothing else.

  • It leaves out keychain-access-groups. Without restricted entitlements, a Developer ID export needs no provisioning profile. Code Raven's export needs -allowProvisioningUpdates only because of its iCloud entitlement.
  • Consequence: the beta keeps its API key (if one is ever entered) in its own Keychain item and does not see the App Store build's key.
• Emerson/Emerson-Beta-Info.plist: SUFeedURL, SUPublicEDKey, SUEnableAutomaticChecks = YES.
• Exclude SparkleUpdater.swift, Emerson-Beta-Info.plist, and Emerson-Beta.entitlements from the main target through the synchronized group's membership exceptions. The Swift file is also wrapped in #if EMERSON_BETA, so a missed exception still compiles to nothing.
• Add a shared scheme Emerson Beta: Run uses Debug, Archive uses Release. Tests stay on the Emerson scheme.
• Add CLAUDE_CLI to the main target's Debug configuration.

Phase 2 — Code gates

• CLI transport. Change #if DEBUG to #if CLAUDE_CLI at:

  • ClaudeCLITransport.swift: the LLMTransport.current body and the ClaudeCLITransport enum. The XCTest guard inside current stays under DEBUG.
  • LLMClient.swift: the branches in send and stream.
  • SettingsView.swift: the transport picker section. Its title drops "developer build only" when EMERSON_BETA is set.
  • Update the doc comment on LLMTransport. "Developer and tester builds" becomes literally true.
• Separate data folder. In AppStorageLocation.swift:

  • folderName becomes "Emerson Beta" under EMERSON_BETA.
  • legacyStoreURLs returns [] under EMERSON_BETA. The beta never adopts the Atticus-era store or default.store. Adoption only copies and leaves the source in place, but a beta on Sarah's Mac has no business taking a copy of her writing and migrating it.
• Other hard-coded folder names. BackupFolder.swift:61 and PersonaLabStore.swift:18 spell out "Emerson". Both switch to AppStorageLocation.folderName.

  • The BackupFolder change matters. If the beta and the Debug build both write readable copies into ~/Documents/Emerson, each app's pruning runs over the other's version files.
• Readable errors. Conform LLMClient.LLMError to LocalizedError.

  • missingAPIKey reads "No Anthropic API key. Add one in Settings."
  • The server(_, "Claude CLI: …") cases pass the CLI's own text through, which already covers "not logged in".
  • This change helps the TestFlight build too.

Phase 3 — Sparkle

• Add the Sparkle package (https://github.com/sparkle-project/Sparkle, 2.x) and link it to Emerson Beta only.
• Emerson/Services/SparkleUpdater.swift, adapted from Code Raven's:

  • Use @Observable to match LLMClient, in place of ObservableObject.
  • Drop the canImport stub and the print diagnostics.
  • Wrap the whole file in #if EMERSON_BETA.
• Add a Check for Updates… command after the About item (CommandGroup(after: .appInfo)), under EMERSON_BETA.
• Add an Updates section in Settings (automatic checks, check now, version), under EMERSON_BETA.
• Signing key:

  • Run generate_keys --account emerson-beta. A bare generate_keys returns Code Raven's existing key from the login Keychain.
  • Export the private key with generate_keys --account emerson-beta -x <file> and store it alongside Code Raven's backup. Losing it means no update can ever be signed for installed copies again.

Phase 4 — Deploy script

scripts/deploy-beta.sh, adapted from Code Raven's, plus scripts/ExportOptions-Beta.plist (method = developer-id).

• Add .sparkle/, build/, releases/, appcast/ to .gitignore.
• Publishing to lochlustra.com is outward-facing. The script stops before committing the LochLustra site, and Sarah pushes it.

Discoverability

Decided 2026-10-07: the Emerson and Code Raven beta pages are reachable only by direct link.

• vercel.json in the LochLustra site already sends X-Robots-Tag: noindex, nofollow, noarchive for /emerson/beta/, /emerson/beta/*, and the same paths under /coderaven/beta (LochLustra commits 16cd7ab, de151cb). The DMGs, appcast, and README are covered as well as the HTML.
• The download page also carries <meta name="robots" content="noindex, nofollow">.
• No link from the lochlustra.com homepage or any other page, and no sitemap entry.
• DMGs live in Vercel Blob under unguessable URLs. The appcast URL is embedded in the app, so anyone holding the app can find the feed; that is acceptable.
• After the first deploy, confirm curl -sI https://lochlustra.com/emerson/beta/ shows the x-robots-tag header.

Phase 5 — Verification

• xcodebuild both schemes. Run the Emerson test suite (StoreMigrationTests included).
• On an exported App Store archive:

  • codesign -d --entitlements - Emerson.app still shows the sandbox on.
  • Contents/Frameworks contains no Sparkle.framework.
• On the beta DMG: spctl --assess --type open --context context:primary-signature -v passes, and codesign -d --entitlements - shows the sandbox off.
• First launch of the beta on Sarah's Mac:

  • Note the modification time of ~/Library/Application Support/Emerson/store/emerson.store beforehand. Don't open the store.
  • Launch the beta, then confirm Application Support/Emerson Beta/ exists and the Debug store's modification time is unchanged.
  • A throwaway macOS user account is a stricter first test, if wanted.
• Run a critique in the beta on the CLI transport. Switch to the API with no key and confirm the readable error.
• Sparkle round trip: install 0.1.1, publish 0.1.2, and confirm the update installs and relaunches.

Tester setup (one time)

1. Install Claude Code (curl -fsSL https://claude.ai/install.sh | bash), run claude once, and log in.
2. Download the DMG and drag Emerson Beta to Applications.
3. Open it. Settings → Model calls should read "Calls run through the local claude CLI."
4. Keep or delete the TestFlight Emerson. The two apps store data separately and don't see each other's writing.

Decisions (2026-10-08)

1. Display name: "Emerson Beta".
2. Shared credentials: reuse Code Raven's CodeRaven-Notarization profile and CodeRaven-Blob token.
3. Discoverability: direct link only (see Phase 4).
4. Vercel Authentication (Standard Protection) is on for the lochlustra project, so old deployment URLs require a Vercel login.

Implementation notes (2026-10-09)

Where the build differs from the phases below:

• Beta-only files live in EmersonBeta/, a second synchronized folder that only the beta target uses: Info.plist, EmersonBeta.entitlements, and SparkleUpdater.swift (updater, menu command, Settings section). This replaces the Emerson-Beta-* files and membership exceptions in Phase 1. The main target never sees the folder, so no #if is needed inside it.
• The beta keeps keychain-access-groups (its own group, com.lochlustra.Emerson.beta). KeychainService uses the data-protection Keychain, which needs a signed application identifier, so Phase 1 step 3's "nothing else" would have broken API-key storage. Export uses -allowProvisioningUpdates; Xcode registered the App ID and profile on the first build.
• Sparkle resolved to 2.10.0 (requirement: up to next major from 2.8.1). Package.resolved is git-ignored in this repo, so the version isn't pinned.
• Signing key: generated under Keychain account emerson-beta. Public key 0Ju5xQvN6EjBykas+W5sDokcDi3cNkFjFj/jABGyCD8= is in EmersonBeta/Info.plist. Backup at .sparkle/emerson-beta-private-key (git-ignored, mode 600).
• Readable errors apply to every build, TestFlight included. "LLMError error 8" now reads "No Anthropic API key. Add one in Settings → Anthropic API Key."
• Deploy script (scripts/deploy-beta.sh) gates on StoreMigrationTests, fails on a sandboxed or debuggable export, fails on rejected notarization (Code Raven's skips it), and stages the page and appcast without committing. Page template: scripts/beta-page.html.
• First-launch finding. The first-launch "Keep a copy of your writing" sheet ran in the beta on Sarah's Mac and ~/Documents/Emerson was chosen, which is the Debug build's backup folder. The beta's store was empty, so its sync wrote and removed nothing; file times in that folder were unchanged. The beta's backup choice was cleared. The sheet and picker now name Emerson Beta as the folder Documents gets. A beta that does choose another build's folder can't delete that build's files (pruning only touches version folders for its own pieces' IDs), but the copies would mix.

Final review

Pros

• The App Store build changes in two places only: readable error messages, and CLAUDE_CLI replacing DEBUG in the main target's Debug configuration. Its Release build ships the same entitlements and no new frameworks.
• The tester gets automatic updates. TestFlight gave him those before; a hand-sent Debug build would not.
• The beta's separate data folder and the empty legacy list keep the beta away from Sarah's real store.
• One flag (CLAUDE_CLI) states which builds can launch a process.

Cons

• There are now two release pipelines. The API path, which App Store users will depend on, gets less real-world testing from this tester.
• Tester usage counts against his Claude plan limits, and responses depend on whatever Claude Code version he has installed. A CLI release that changes --json-schema, --setting-sources, or the stream-json format breaks the beta until Emerson ships a fix. The Debug build already carries this risk; the beta extends it to someone who can't rebuild.
• Two targets share one folder. A new file meant for one target needs a membership exception or a compile flag, which is easy to forget. The #if EMERSON_BETA wrapper limits the damage to dead code.

Edge cases the plan does not cover

• Schema migrations reach the tester through Sparkle. A migration bug would hit his real writing with no developer at the machine. The pre-migration backups and StoreRecoveryView run in the beta too, but recovering from them remotely means walking him through it.
• Moving his TestFlight writing. If he wrote anything in TestFlight first, it stays in the container. Moving it means exporting and re-importing; the beta won't adopt it.
• claude installed somewhere unusual (an nvm-managed npm global, for example). executableURL() checks four fixed locations. The fix is to add a Settings field for a custom path or to resolve the path through a login shell.

Adjustments worth considering

• Ship the LocalizedError change to TestFlight right away. It's independent of everything else and makes the tester's current build explain itself.
• Before shipping a schema change on the beta channel, add a deploy-script check that runs StoreMigrationTests and refuses to publish on failure.

Confidence: 80/100. The target split, the separate data folder, and the deploy pipeline follow patterns proven in this repo and in Code Raven. Two steps haven't been done in this project and remain unverified: sharing one synchronized root group between two app targets with per-file exceptions, and a Developer ID export without a provisioning profile once keychain-access-groups is dropped. Either could add an hour of Xcode work, but neither changes the design.