Make local iOS simulator development reliable

[cameronapak]

What

• Add one-command iOS launch, clean recovery, and environment diagnostics
• Isolate Metro ports and caches across worktrees
• Document the workflow and test its selection, port, and URL behavior in CI

Why

Local upgrades and concurrent checkouts could leave agents connected to the wrong Metro server or stale generated state.

Impact

Developers and agents can run pnpm dev:ios, diagnose with pnpm doctor:ios, and recover with pnpm dev:ios:clean.

Verified

• Unit tests, lint, and typecheck
• Normal and clean launches on iPhone 17 Pro Simulator
• Occupied-port isolation against PR feat(ui): hybridize BibleCard chrome with DOM BibleTextView #195

Confidence Score: 5/5

The PR appears safe to merge.

Summary

The PR adds a worktree-isolated iOS simulator workflow with launch, clean-recovery, and diagnostic commands.

• Selects an available iPhone simulator and unused Metro port.
• Isolates Metro temporary state and connects the development client to the selected server.
• Adds environment diagnostics, automated tests, CI coverage, and contributor documentation.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[pnpm dev:ios] --> B[Discover available iPhones]
  B --> C[Boot selected simulator]
  C --> D{Clean mode?}
  D -- Yes --> E[Regenerate native iOS project]
  D -- No --> F[Select unused Metro port]
  E --> F
  F --> G[Start worktree-isolated Metro]
  G --> H[Build and install development client]
  H --> I[Open client with selected Metro URL]
  J[pnpm doctor:ios] --> K[Check toolchain, app key, simulators, and Metro ports]

Loading

_{Reviews (4) · Last reviewed commit: "fix: improve iOS doctor diagnostics"}