iOS companion: finish getting it onto TestFlight

[arzafran]

Where this stands

The iOS companion is not on TestFlight. No build has ever reached a tester
through CI — ios-testflight.yml existed for weeks and had never run once.

That lane now ships by itself on any push to main that touches the phone app
(#201), and pairing was collapsed from two hand-copied strings to one QR scan
(#202). Both are merged. The lane is wired, verified, and currently skipping every
run because the Apple signing material is not on the repo.

Three things left. Only the first blocks shipping.

---

1. Add the Apple signing secrets (blocking, needs Apple account access)

ios-testflight.yml runs on every ios/** push to main and stops at
preflight with configured=false. It warns and skips rather than failing, so
main stays green and nothing reaches testers. Two consecutive runs have skipped
this way — that is the designed behaviour, not a bug, but it means the companion
is not shipping.

Add under Settings → Secrets and variables → Actions:

secret	what it is
APPLE_IOS_DIST_CERT_BASE64	Apple Distribution cert as .p12, base64. A Developer ID or Apple Development cert cannot sign for TestFlight — the build script rejects them explicitly.
APPLE_IOS_DIST_CERT_PASSWORD	the .p12 export password
APPLE_IOS_APP_PROFILE_BASE64	App Store profile for com.darkroom.programa.spike
APPLE_IOS_WIDGET_PROFILE_BASE64	App Store profile for com.darkroom.programa.spike.widgets
APPSTORE_CONNECT_KEY_ID	App Store Connect → Users and Access → Integrations
APPSTORE_CONNECT_ISSUER_ID	same page
APPSTORE_CONNECT_KEY_P8_BASE64	the .p8 key, base64

Encode each with base64 -i <file> | pbcopy.

Regenerate both provisioning profiles — do not reuse the existing ones.
plans/golden-tumbling-gray.md:490-493 records that the iOS profiles were minted
before the iCloud container was attached to the App ID, so they carry no
containers. scripts/build-ios-testflight.sh also hard-fails when the app profile
has aps-environment != production, which is what happened on the first manual
upload. Mint them with Push Notifications enabled on the App ID.

Verify, in order:

1. gh workflow run ios-testflight.yml -f upload=false → run completes
   successfully with build no longer skipped, and the "Verifying signed
   entitlements" step printing ok aps-environment = production,
   ok get-task-allow = false,
   ok com.apple.developer.icloud-container-environment = Production.
2. Only once that passes: gh workflow run ios-testflight.yml -f upload=false
   again is unnecessary — push any ios/** change to main and confirm the
   upload step runs and the build appears in App Store Connect after processing.

2. Localize the iOS strings

ios/ProgramaSpike/ has no String Catalog and its convention is bare English
literals, so the strings added in #202 (PairConnectView, QRScannerView,
AppStore) are unlocalized. The Mac side of the same feature is localized in
Resources/Localizable.xcstrings (en + ja).

CLAUDE.md's localization rule is repo-wide, so this is a real gap rather than a
target-local style choice. It needs a String Catalog added to the iOS target and
the existing literals migrated — worth its own change, and worth doing before
Japanese testers get a build.

Verify: every user-facing string in ios/ProgramaSpike/ProgramaSpike/*.swift
reaches the UI through String(localized:defaultValue:), with en + ja entries,
and the app builds:
xcodebuild -project ios/ProgramaSpike/ProgramaSpike.xcodeproj -scheme ProgramaSpike -configuration Release -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO build
→ ** BUILD SUCCEEDED **

3. Optional: make the pairing QR an https:// universal link

Today the QR encodes programa-pair://pair?v=1&t=<ticket>&k=<token>, a custom
scheme. It works, but a tester has to open Programa on the phone, find "Scan QR
Code", then scan — three steps.

pingdotgg/t3code encodes a real https:// URL instead
(packages/shared/src/remote.ts:165-170), so any camera app opens it directly:
point, tap, done. Their in-app scanner is a convenience layer rather than the only
route in.

Cost: an apple-app-site-association file on a domain we control. A static file
on an existing site is not "a server we host", so it does not break that
constraint, but it is real setup.

If we do this, the token must move into the URL fragment (#token=), not the
query string — that is exactly why t3code puts it there. A query string reaches
the web origin and its access logs; a fragment does not. This does not apply to
the current custom scheme, which never touches a server, which is why it was left
alone in #202.

Defer until the companion is in testers' hands and we know whether the two extra
taps actually matter.

---

Not in scope, noted so it is not rediscovered

• The bundle id is still com.darkroom.programa.spike. Renaming means a new App
  ID, a new App Store Connect record, and re-attaching the iCloud container.
  Testers only ever see the display name "Programa", so this is not worth doing.
• MARKETING_VERSION in ios/ProgramaSpike/project.yml is 0.1.
• The two pairing-code parsers (Sources/MobileBridge/MobileBridgePairingCode.swift
  and ios/ProgramaSpike/ProgramaSpike/PairingCode.swift) are separate copies kept
  in sync by hand, because the two targets share no module. Both validate v=1 and
  reject anything else. Any format change must land on the phone before the Mac
  starts emitting it, since the companion ships through TestFlight and will lag.

[arzafran]

Runbook for part 1

Part 2 (localization) shipped in #206 — 73 keys, en + ja, verified compiled into both the app and the widget bundles. Part 3 stays deferred, as this issue says, until the companion is actually in testers' hands.

So part 1 is the only thing between here and TestFlight, and it needs Apple account access. Audited the whole lane so this runs once rather than three times.

Do these in order

1. Enable Push Notifications on the App ID — com.darkroom.programa.spike, at developer.apple.com → Identifiers. Do this before minting profiles.

2. Confirm the iCloud container is attached to that App ID: iCloud.com.darkroom.programa.

3. Mint two fresh App Store provisioning profiles. Do not reuse the existing ones — plans/golden-tumbling-gray.md:490-493 records that they were created before the container was attached, so they carry none. One for com.darkroom.programa.spike, one for com.darkroom.programa.spike.widgets.

4. Create the App Store Connect app record for com.darkroom.programa.spike under My Apps. Nothing in this repo creates one, and altool rejects the upload without it. This is the step most likely to be missed — it isn't in the secret table above.

5. Add all seven secrets at once, under Settings → Secrets and variables → Actions. Encode files with base64 -i <file> | pbcopy.

secret	what
APPLE_IOS_DIST_CERT_BASE64	Apple Distribution cert as .p12, base64
APPLE_IOS_DIST_CERT_PASSWORD	the .p12 export password
APPLE_IOS_APP_PROFILE_BASE64	App Store profile from step 3
APPLE_IOS_WIDGET_PROFILE_BASE64	widget App Store profile from step 3
APPSTORE_CONNECT_KEY_ID	ASC → Users and Access → Integrations
APPSTORE_CONNECT_ISSUER_ID	same page
APPSTORE_CONNECT_KEY_P8_BASE64	the .p8, base64 (downloadable only once)

6. Dry run: gh workflow run ios-testflight.yml -f upload=false

Expect a run that no longer skips, and a "Verifying signed entitlements" step printing all three of aps-environment = production, get-task-allow = false, com.apple.developer.icloud-container-environment = Production.

7. Then push any ios/** change to main and the upload runs automatically.

What the audit found

Fixed in #209: preflight gated on only four of the seven secrets. Adding the cert and profile ones but not the API key would have reported "configured", burned ten-plus minutes archiving and verifying, then died on require PROGRAMA_ASC_KEY_ID — a failure that reads like broken signing when signing was fine. It now fails in seconds and names what's missing.

Not a problem, contrary to what I expected: build numbers are already dynamic (GITHUB_RUN_ID + attempt, ios-testflight.yml:170-174), overriding the static CURRENT_PROJECT_VERSION: "1" in project.yml. No duplicate-build rejection on the second upload.

Everything else checks out. ITSAppUsesNonExemptEncryption, NSCameraUsageDescription (needed by the QR scanner), NSLocalNetworkUsageDescription, the iPad orientation keys the build script pre-checks, the 1024 app icon, and PrivacyInfo.xcprivacy are all present and correct.

One thing to watch, not blocking: the widget target has no PrivacyInfo.xcprivacy of its own. That won't block a first TestFlight upload or internal testing, but if the widget touches a required-reason API it can surface as an ITMS warning and matters for external testing or review later.

Prior runs, for context

The lane has never produced a build. Three push runs (most recently 30559370496) completed in ~7s at preflight with configured=false, warned, and exited 0 — working as designed. Two workflow_dispatch runs hard-failed, also as designed.

[arzafran]

Shipped. Build 3057430199401 uploaded to App Store Connect from run 30574301994.

  ok  aps-environment = production
  ok  get-task-allow = false
  ok  com.apple.developer.icloud-container-environment = Production
UPLOAD SUCCEEDED with no errors
Delivery UUID: 6f3f57da-e154-4544-8549-4e294d4c1bc6

Part 1 — secrets added, profiles minted against a new Apple Distribution cert, App Store Connect record in place. The lane now ships on any push to main touching ios/**, with build numbers from the run id so there are no duplicate-version rejections.

Part 2 — done in #206. 73 keys, en + ja, verified compiled into both the app and the widget bundles.

Part 3 — the https:// universal-link QR stays deferred, exactly as this issue proposed: revisit once the companion is in testers' hands and we know whether the two extra taps actually matter. If it happens, the token moves to the URL fragment.

Five script bugs found on the way

None were configuration problems — the portal work was correct from the first attempt. All five were only reachable once real signing secrets existed, which is why they survived until now.

#	fix	bug
1	#211	PlistBuddy cannot read /dev/stdin
2	#212	no per-target provisioning profile specifier
3	#213	icloud-container-environment never declared
4	#213	plutil error text reported as the value
5	#214	plutil -extract keypath dots unescaped

Three share one root cause worth remembering: macOS plist tools print failures to stdout, so the usual || fallback idiom turns an error message into data. That made 4 look like a different bug from 3, and disguised 5 as a missing entitlement when the signed binary had been correct all along — confirmed by pulling the IPA artifact and dumping its signature.

#209 also made the lane fail in seconds rather than after a wasted ten-minute build when only some secrets are present.

Follow-ups, neither blocking

• The widget target has no PrivacyInfo.xcprivacy of its own. Fine for internal testing; worth checking before external testing or review.
• com.apple.developer.icloud-container-environment is declared Production unconditionally, so a local device build also talks to the production CloudKit container. Right default here, but revisit if a dev container is ever wanted.

Setup is written up at docs/ios-testflight-setup.md.