expo-devbox 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brent Vatne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,19 +1,23 @@
 # expo-devbox
 
-Build and test your Expo app's native iOS code on an EAS macOS worker instead of your own machine. You, or your coding agent, edit files locally; `expo-devbox build` syncs them to a worker that stays up for the session, runs an incremental Xcode build, launches the app on the worker's iOS Simulator, and reports what happened.
+A macOS EAS worker for building and testing your Expo app's native iOS code, for you or your coding agent, instead of your own machine. `expo-devbox start` brings up a worker that has your app prebuilt, its pods installed, an iOS Simulator booted, Metro running, and a first build done. Then you, or your agent, copy files over with `expo-devbox sync` and run commands on it with `expo-devbox ssh`.
 
 It is for work that rebuilds native code over and over, such as an agent iterating on an [Expo module](https://docs.expo.dev/modules/overview/), when those rebuilds are too heavy for your machine.
 
+## Set it up with your coding agent
+
+Paste this into your coding agent, in your Expo app:
+
+```text
+Set up expo-devbox (https://www.npmjs.com/package/expo-devbox) in this Expo app. It is a tool I will ask you to use when I want to build and test native iOS code on an EAS macOS worker instead of this machine.
+
+1. Check the requirements: bun 1.3 or later, eas-cli logged in (`eas whoami`), and cloudflared (`brew install cloudflared` if it is missing). If the app has no EAS project ID in its app config, run `eas init`.
+2. Run `bunx expo-devbox init` in the app's root directory.
+3. Read the "Native iOS builds on EAS (expo-devbox)" section that init added to AGENTS.md or CLAUDE.md. If neither file exists, init prints the section instead; add it to the instructions file you read. Then run `bunx expo-devbox help`. Keep building the app the way you do now; use expo-devbox only when I ask you to.
+4. Do not start a session; a session bills EAS macOS minutes while it runs. Tell me what you set up.
 ```
-$ bunx expo-devbox build
-BUILD SUCCEEDED in 5s
-App console output from this launch:
- LOG  [native-crypto] PASS sha384("abc"): cb00753f…
- LOG  [native-crypto] DONE 7/7 passed
-Native log from this launch (system libraries excluded):
-2026-10-24 16:59:04.278 Df myapp[6954:97f5] (Foundation) [native-crypto] module created
-Screenshot copied to .devbox/screenshot.png
-```
+
+**iOS only for now.** Android support, on an EAS Linux worker with the Android Emulator, will be added to this tool shortly.
 
 ## Requirements
 
@@ -29,98 +33,144 @@ In the root of your app:
 bunx expo-devbox init
 ```
 
-`init` does the following:
+`init` writes the workflow to `.eas/workflows/ios-devbox.yml` and adds `.devbox/` to `.gitignore`; the CLI keeps the session's run ID and SSH config there. It also adds a short section for coding agents to `AGENTS.md` or `CLAUDE.md`, or prints it if neither file exists (see [Coding agents](#coding-agents)).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init [--force] [--no-agents]` | Adds the devbox workflow to the app, as in [Set up](#set-up). `--force` replaces an existing workflow; `--no-agents` leaves `AGENTS.md` and `CLAUDE.md` alone. |
+| `start [minutes] [idle-minutes]` | Starts a session and waits until the worker is ready, about 4 minutes. The session ends after `minutes` (default 60) or after `idle-minutes` with no SSH connection (default 15). |
+| `sync` | Copies your files to the worker: what git would track, so `.gitignore` applies. Run it after each change. |
+| `ssh ['command']` | Runs a command in the app's directory on the worker, or opens a shell. If the connection drops while the command runs, it exits 255 and does not run the command again. |
+| `attach [run-id]` | Reconnects to a running session. `sync` and `ssh` also reconnect on their own when the worker's tunnel has moved. |
+| `joblog` | Prints the workflow job's log. |
+| `stop` | Ends the session and waits until EAS confirms that it has ended. |
+
+`expo-devbox help` prints these commands and the steps in [On the worker](#on-the-worker).
+
+## On the worker
 
-- writes the workflow to `.eas/workflows/ios-devbox.yml`,
-- writes `devbox.json`,
-- adds `.devbox/` to `.gitignore`,
-- adds instructions for coding agents to `AGENTS.md` or `CLAUDE.md`. If neither file exists, it prints them instead; see [Coding agents](#coding-agents).
+After each change, run `expo-devbox sync`, then run these with `expo-devbox ssh '<command>'`. The `DEVBOX_*` variables are set in every SSH session.
 
-Then:
+For example:
+
+```
+$ bunx expo-devbox sync
+$ bunx expo-devbox ssh 'set -o pipefail; xcodebuild … build 2>&1 | tee ~/.devbox/build.log | grep -E ": (fatal )?error:|\*\* BUILD" | sort -u'
+** BUILD SUCCEEDED **
+$ bunx expo-devbox ssh 'tail -n 3 ~/.devbox/metro.log'
+ LOG  [native-crypto] PASS sha384("abc"): cb00753f…
+ LOG  [native-crypto] DONE 7/7 passed
+```
+
+**Build.** Prints errors with file and line, then `** BUILD SUCCEEDED **` or `** BUILD FAILED **`, and exits non-zero on failure. The full log is `~/.devbox/build.log`. After the worker's first build, an incremental build takes a few seconds.
 
 ```sh
-bunx expo-devbox start     # start a session: 60 minutes at most, ends after 15 idle minutes
-bunx expo-devbox build     # sync, build, launch, check
-bunx expo-devbox stop      # end the session
+set -o pipefail; xcodebuild -workspace "$DEVBOX_WORKSPACE" -scheme "$DEVBOX_SCHEME" -configuration Debug -destination "id=$DEVBOX_SIMULATOR" -derivedDataPath "$DEVBOX_DERIVED_DATA" build 2>&1 | tee ~/.devbox/build.log | grep -E ": (fatal )?error:|\*\* BUILD" | sort -u
 ```
 
-## Commands
+**Install and launch** the app on the simulator:
 
-| Command | What it does |
-| --- | --- |
-| `start [minutes] [idle-minutes]` | Starts the workflow and waits until SSH works (about a minute). The worker then prepares the project: install, `expo prebuild`, `pod install`, simulator, Metro, and a first build. That takes about three more minutes. |
-| `build` | Syncs your files, builds, launches the app, prints its console and native logs, and copies the screenshot to `.devbox/screenshot.png`. |
-| `build --pods` | Same, after adding or removing native source files or editing a podspec. |
-| `build --prebuild` | Same, after changing `package.json`, the app config or a config plugin. |
-| `ssh [command]` | Runs a command in the project directory on the worker, or opens a shell. |
-| `logs [pattern]` | Searches the app's console output from Metro. |
-| `sync` | Copies your files to the worker without building. |
-| `attach [run-id]` | Reconnects to a running session. `build` reconnects on its own. |
-| `joblog` | Prints the workflow job's log. |
-| `stop` | Cancels the session and waits until EAS confirms that it has ended. |
+```sh
+xcrun simctl install booted "$DEVBOX_APP" && xcrun simctl launch --terminate-running-process booted "$DEVBOX_BUNDLE_ID"
+```
+
+**JavaScript console output and errors**, from Metro:
 
-`build` exits non-zero, and says why, when:
+```sh
+tail -n 50 ~/.devbox/metro.log
+```
 
-- the build fails: it prints the compiler errors with file and line,
-- the app is not running after launch: it prints the exception and the crashing frames,
-- the app does not log a line matching `waitFor`, or logs one matching `failOn`.
+**Native log**: `NSLog`, and `os_log` or `Logger` output from the app's own code, from the last minute. Swift's `print` writes to stdout and does not appear here.
+
+```sh
+xcrun simctl spawn booted log show --last 1m --style compact --predicate "$DEVBOX_LOG_PREDICATE" 2>/dev/null
+```
 
-## devbox.json
+**Check that the app is still running**, and if it crashed, read the exception and crashing frames from the newest crash report:
 
-| Key | Meaning |
+```sh
+pgrep -lf "$DEVBOX_EXECUTABLE.app/$DEVBOX_EXECUTABLE" || echo "The app is not running."
+tail -n +2 "$(ls -t ~/Library/Logs/DiagnosticReports/$DEVBOX_EXECUTABLE*.ips | head -1)" | jq "{exception, termination, frames: [.threads[] | select(.triggered) | .frames[:12][] | {symbol, sourceFile, sourceLine}]}"
+```
+
+**Screenshot**, then copy it to your machine (the second command runs locally):
+
+```sh
+xcrun simctl io booted screenshot ~/.devbox/screenshot.png
+scp -F .devbox/ssh_config devbox:.devbox/screenshot.png .devbox/
+```
+
+**After adding or removing native files, or editing a podspec:**
+
+```sh
+cd ios && pod install
+```
+
+**After changing `package.json`, the app config or a config plugin.** Use your package manager, and skip prebuild if you commit `ios/`:
+
+```sh
+bun install && npx expo prebuild --platform ios --no-install && cd ios && pod install
+```
+
+### The variables
+
+| Variable | Value |
 | --- | --- |
-| `waitFor` | A regular expression for a line your app logs when it is ready, for example when its self-test finishes. `build` waits for it, up to `waitSeconds`, and fails if it never appears. Without it, `build` waits 8 seconds. |
-| `failOn` | A regular expression for a line that means failure. `build` exits non-zero if the app logs it. |
-| `waitSeconds` | How long to wait for `waitFor`. The default is 60. |
-| `scheme` | The Xcode scheme, when it is not named after the `.xcworkspace`. |
+| `DEVBOX_WORKSPACE`, `DEVBOX_SCHEME` | The Xcode workspace (`ios/<name>.xcworkspace`) and scheme. |
+| `DEVBOX_SIMULATOR` | The booted simulator's UDID. |
+| `DEVBOX_DERIVED_DATA` | The DerivedData folder of the worker's first build. Build with it to keep builds incremental. |
+| `DEVBOX_APP`, `DEVBOX_BUNDLE_ID`, `DEVBOX_EXECUTABLE` | The built `.app`, its bundle identifier, and its executable's name. |
+| `DEVBOX_LOG_PREDICATE` | A `log` predicate for messages from the app's own code and `NSLog`, without system libraries' logging. |
 
 ## Coding agents
 
-`init` adds the following to `AGENTS.md` or `CLAUDE.md`. Copy it into your agent's instructions if you use another file:
+`init` adds this to `AGENTS.md` or `CLAUDE.md`. It tells agents to use the devbox only when you ask. Copy it into your agent's instructions if you use another file:
 
 ```markdown
 ## Native iOS builds on EAS (expo-devbox)
 
-Compile and test native iOS code on an EAS macOS worker with `bunx expo-devbox`, not on this machine. Do not run `npx expo run:ios` or `xcodebuild` locally.
+`bunx expo-devbox` gives you a macOS EAS worker to build and test this app's native iOS code instead of this machine. Use it only when the user asks for it, for example "build this on the devbox". Otherwise, build and run the app as you normally would.
 
-1. Start a session once: `bunx expo-devbox start`. It bills EAS macOS minutes until `stop`, its time limit (60 minutes by default), or 15 minutes without a connection.
-2. After each change, run `bunx expo-devbox build`. Add `--pods` after adding or removing native source files or editing a podspec, and `--prebuild` after changing package.json, the app config or a config plugin.
-3. `build` syncs your files, compiles, launches the app on the worker's iOS Simulator, and prints the app's console and native logs. It exits non-zero on a compile error (with file and line), a crash at launch (with the crashing frames), or a failed check from devbox.json. Read the output, fix the code, and build again. The screenshot is `.devbox/screenshot.png`.
-4. `bunx expo-devbox ssh '<command>'` runs a command in the project directory on the worker, for example `xcrun simctl list devices booted`.
-5. When you are done, run `bunx expo-devbox stop`.
-```
+When the user asks for it:
 
-To check results without reading pixels, have your app log a line when its checks pass or fail, and set `waitFor` and `failOn`.
+1. Run `bunx expo-devbox help` and follow its "On the worker" section. It has the command for each step: build, install and launch, logs, crash reports and screenshots.
+2. Start a session with `bunx expo-devbox start`. It returns when the worker is ready, and EAS macOS minutes are billed until the session ends.
+3. After each change, run `bunx expo-devbox sync`, then the commands from the help with `bunx expo-devbox ssh '<command>'`.
+4. When the user is done with the devbox, run `bunx expo-devbox stop`.
+```
 
-In a terminal that supports the [Program Status Protocol](https://mitchellh.com/writing/program-status-osc7501) (OSC 7501), such as Ghostty, `start`, `build` and `stop` report their status: working, done, error, or blocked when the run needs approval. The CLI sends these reports only when its stderr is a terminal, so output that an agent captures never contains them.
+In a terminal that supports the [Program Status Protocol](https://mitchellh.com/writing/program-status-osc7501) (OSC 7501), such as Ghostty, `start`, `attach` and `stop` report their status: working, done, or blocked when the run needs approval on expo.dev; any command that fails reports an error. The CLI sends these reports only when its stderr is a terminal, so output that an agent captures never contains them.
 
 ## How it works
 
 The workflow runs one custom job on `macos-large` in the `development` environment:
 
-1. **SSH.** It starts `sshd` as the build user on `127.0.0.1:2222`. Only the key `~/.ssh/eas_devbox`, created by `start`, can log in. SSH sessions get the toolchain variables (`PATH`, Ruby, nvm) but not the job's EAS environment variables or its `EXPO_TOKEN`. The job itself still has them, and the SSH user is the job user, so do not give a session to someone who should not see the development environment.
-2. **Tunnel.** EAS workers accept no inbound connections, so the worker opens a pinned `cloudflared` [quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/), and Cloudflare relays your connection to it. The job log prints the tunnel host and the worker's SSH host key; the CLI reads them with `eas workflow:logs` and pins the key. Quick tunnels have no uptime guarantee. If the tunnel exits, the worker opens a new one and `build` reconnects.
-3. **Preparation.** It runs `expo prebuild` (skipped when the project commits `ios/`) and `pod install`, and boots an iPhone simulator. It starts Metro with `CI` unset, because with `CI=true` Metro ignores file changes. Then it runs a first Debug build.
+1. **SSH.** It starts `sshd` as the build user on `127.0.0.1:2222`. Only the key `~/.ssh/eas_devbox`, created by `start`, can log in. SSH sessions get the toolchain variables (`PATH`, Ruby, nvm) and the `DEVBOX_*` variables, but not the job's EAS environment variables or its `EXPO_TOKEN`. The job itself still has them, and the SSH user is the job user, so do not give a session to someone who should not see the development environment.
+2. **Tunnel.** EAS workers accept no inbound connections, so the worker opens a pinned `cloudflared` [quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/), and Cloudflare relays your connection to it. The job log prints the tunnel host and the worker's SSH host key; the CLI reads them with `eas workflow:logs` and pins the key. Quick tunnels have no uptime guarantee. If the tunnel exits, the worker opens a new one, and `sync` and `ssh` reconnect.
+3. **Preparation.** It runs `expo prebuild` (skipped when the project commits `ios/`) and `pod install`, and boots an iPhone simulator. It writes the `DEVBOX_*` variables for SSH sessions. It starts Metro with `CI` unset, because with `CI=true` Metro ignores file changes. Then it runs the build command above once, so that later builds are incremental.
 4. **Session.** The job stays up until `minutes` after it started, or until no SSH connection has been open for `idle-minutes`. It restarts Metro if Metro stops responding.
 
 `sync` sends what git would track. Patterns from `.gitignore` are excluded, so local secrets such as `.env.local` stay local and files that the worker generated are not deleted. `.gitignore` lines that start with `!` are not supported.
 
-EAS has built-in workflow SSH (`eas workflow:run --ssh`) that is not available in production yet. When it is, it will replace the SSH and tunnel steps.
+> [!NOTE]
+> SSH support for EAS Workflows is coming soon (`eas workflow:run --ssh` and `eas workflow:ssh`). It will cover about half of what this tool does: the SSH server, the Cloudflare tunnel, finding the worker, and ending idle sessions. The other half stays: preparing the worker (prebuild, pods, simulator, Metro, a first build), syncing your files safely, the variables and commands for building and running the app, and the instructions for coding agents. Steps 1 and 2, and the idle shutdown in step 4, exist because EAS Workflows does not offer SSH yet. When workflow SSH ships, `expo-devbox` will use it.
 
 ## Limits
 
-- iOS only.
+- iOS only. Android support will be added shortly.
 - One app per project root. Monorepos with dependencies outside the app directory are not supported.
-- `build --prebuild` reinstalls dependencies with the package manager whose lockfile is present.
+- The `DEVBOX_*` values assume prebuild's naming, where the scheme, the app and its executable share a name. A project that commits `ios/` with different names can use its own values in the commands.
 - Private npm packages need their token as an EAS environment variable in the `development` environment.
 
 ## Turn off the intro
 
-`expo-devbox` and `expo-devbox init` open with an animated wordmark when you run them in a terminal. Set `EXPO_DEVBOX_INTRO=off` to skip it, or set it to `slider`, `decrypt`, `beams`, `snap` or `slide` to pick one.
+`expo-devbox help` (or `expo-devbox` with no command) and `expo-devbox init` open with an animated wordmark when you run them in a terminal. Set `EXPO_DEVBOX_INTRO=off` to skip it, or set it to `slider`, `decrypt`, `beams`, `snap` or `slide` to pick one.
 
 ## Developing expo-devbox
 
-The CLI is at the root of this repository: `src/` holds the commands and the worker script, `templates/` holds the workflow that `init` writes, and `test/` holds the unit tests.
+The CLI is at the root of this repository: `src/` holds the commands, `templates/` holds the workflow that `init` writes, and `test/` holds the unit tests.
 
 ```sh
 bun install
@@ -131,7 +181,7 @@ bun link && bun install -g .    # put this checkout on your PATH as expo-devbox
 
 ### The example app
 
-[`example/`](example) is the app to test the CLI against, end to end, on a real EAS worker. It has a local Expo module, [`modules/native-crypto`](example/modules/native-crypto). The module wraps CryptoKit SHA-256, SHA-384, SHA-512 and HMAC-SHA256, and `SecRandomCopyBytes`. On launch, [`App.tsx`](example/App.tsx) checks the module against published test vectors (FIPS 180-2 and RFC 4231). It logs a `[native-crypto] PASS` or `FAIL` line for each check, then `[native-crypto] DONE`. [`devbox.json`](example/devbox.json) makes `build` wait for `DONE` and fail on `FAIL`.
+[`example/`](example) is the app to test the CLI against, end to end, on a real EAS worker. It has a local Expo module, [`modules/native-crypto`](example/modules/native-crypto). The module wraps CryptoKit SHA-256, SHA-384, SHA-512 and HMAC-SHA256, and `SecRandomCopyBytes`. On launch, [`App.tsx`](example/App.tsx) checks the module against published test vectors (FIPS 180-2 and RFC 4231). It logs a `[native-crypto] PASS` or `FAIL` line for each check, then `[native-crypto] DONE`, and `NSLog`s `[native-crypto] module created` from Swift.
 
 The example does not depend on `expo-devbox`. Run the linked CLI from the example's directory:
 
@@ -139,23 +189,21 @@ The example does not depend on `expo-devbox`. Run the linked CLI from the exampl
 cd example
 bun install
 expo-devbox start
-expo-devbox build
-expo-devbox stop
 ```
 
 To use your own EAS account, delete `owner` and `extra.eas` from `example/app.json` and run `eas init` in `example/`.
 
-Before a release, run these checks in the example. Edit the app, run `expo-devbox build`, and check the exit code and the message; then revert the edit.
+Before a release, run these checks in the example with the commands from [On the worker](#on-the-worker), and revert each edit afterwards:
 
 | Change | Expected result |
 | --- | --- |
-| None | exit 0, `DONE 7/7 passed`, the `module created` line in the native log |
-| A wrong expected value in `App.tsx` | exit 1, `matching failOn` |
-| A Swift type error | exit 1, the error with file and line |
-| `fatalError()` in the module's `OnCreate` | exit 1, the crash report frames |
-| `build --prebuild` | exit 0 |
+| None: sync, build, install and launch | `** BUILD SUCCEEDED **`; Metro log ends with `DONE 7/7 passed`; the native log has `module created` |
+| A Swift type error | the build prints the error with file and line, `** BUILD FAILED **`, and exits non-zero |
+| `fatalError()` in the module's `OnCreate` | `The app is not running.`; the crash report frames point at `NativeCryptoModule.swift` |
+| A wrong expected value in `App.tsx` | Metro log has a `FAIL` line |
+| Prebuild and pod install, then build | `** BUILD SUCCEEDED **` |
 | `.env.local` present, then `sync` | the file is not on the worker |
-| `expo-devbox ssh 'pkill -9 cloudflared'`, then `build` | `build` reconnects on its own, exit 0 |
+| `expo-devbox ssh 'pkill -9 cloudflared'`, then `expo-devbox ssh 'true'` | the first exits 255 with the dropped-connection message and is not run again; the second reconnects on its own and exits 0 |
 | `stop` | `The devbox session is canceled.` |
 
 After you change `templates/ios-devbox.yml`, run `expo-devbox init --force --no-agents` in `example/` to update its workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-devbox",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Build and test an Expo app's native iOS code on an EAS macOS worker, from your terminal or a coding agent.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -1,30 +1,60 @@
 #!/usr/bin/env bun
 import { init } from './init';
 import { playIntro } from './intro';
-import { attach, build, joblog, logs, shell, start, stop, sync, UserError } from './session';
+import { attach, joblog, shell, start, stop, sync, UserError } from './session';
 import { status } from './status';
 
-const HELP = `Build and test an Expo app's native iOS code on an EAS macOS worker,
-from your terminal or a coding agent.
+const HELP = `A macOS EAS worker for building and testing an Expo app's native iOS code,
+for you or a coding agent. Run these in the app's root directory.
 
-Usage: expo-devbox <command>
+Session:
+  init [--force] [--no-agents]    add the devbox workflow to this app
+  start [minutes] [idle-minutes]  start a session and wait until the worker is ready (about 4 minutes).
+                                  It ends after [minutes] (default 60) or after [idle-minutes] without
+                                  an SSH connection (default 15). EAS macOS minutes are billed until then.
+  sync                            copy your files to the worker (what git would track; .gitignore applies)
+  ssh ['command']                 run a command in the app's directory on the worker, or open a shell
+  attach [run-id]                 reconnect to a running session
+  joblog                          print the workflow job's log
+  stop                            end the session and wait until EAS confirms it ended
 
-  init [--force] [--no-agents]      add the devbox workflow to this Expo app
-  start [minutes] [idle-minutes]    start a session (default 60 and 15); wait until SSH works
-  build [--pods|--prebuild]         sync, build with Xcode, launch, print logs, copy the screenshot
-  ssh [command]                     run a command in the project on the worker, or open a shell
-  logs [pattern]                    search the app's console output
-  sync                              copy local sources to the worker
-  attach [run-id]                   reconnect to a running session
-  joblog                            print the workflow job's log
-  stop                              cancel the session and wait until it has ended
+On the worker:
+  After each change, run expo-devbox sync, then the commands below with expo-devbox ssh '<command>'.
+  The DEVBOX_* variables are set in every SSH session.
+
+  Build. Prints errors with file and line, then ** BUILD SUCCEEDED ** or ** BUILD FAILED **.
+  The full log is ~/.devbox/build.log.
+    set -o pipefail; xcodebuild -workspace "$DEVBOX_WORKSPACE" -scheme "$DEVBOX_SCHEME" -configuration Debug -destination "id=$DEVBOX_SIMULATOR" -derivedDataPath "$DEVBOX_DERIVED_DATA" build 2>&1 | tee ~/.devbox/build.log | grep -E ": (fatal )?error:|\\*\\* BUILD" | sort -u
+
+  Install and launch the app on the simulator:
+    xcrun simctl install booted "$DEVBOX_APP" && xcrun simctl launch --terminate-running-process booted "$DEVBOX_BUNDLE_ID"
+
+  JavaScript console output and errors (Metro):
+    tail -n 50 ~/.devbox/metro.log
+
+  Native log (NSLog, and os_log or Logger output from the app's own code; last minute):
+    xcrun simctl spawn booted log show --last 1m --style compact --predicate "$DEVBOX_LOG_PREDICATE" 2>/dev/null
+
+  Check that the app is still running:
+    pgrep -lf "$DEVBOX_EXECUTABLE.app/$DEVBOX_EXECUTABLE" || echo "The app is not running."
+
+  If it crashed, the exception and crashing frames from the newest crash report:
+    tail -n +2 "$(ls -t ~/Library/Logs/DiagnosticReports/$DEVBOX_EXECUTABLE*.ips | head -1)" | jq "{exception, termination, frames: [.threads[] | select(.triggered) | .frames[:12][] | {symbol, sourceFile, sourceLine}]}"
+
+  Screenshot (then, on your machine: scp -F .devbox/ssh_config devbox:.devbox/screenshot.png .devbox/):
+    xcrun simctl io booted screenshot ~/.devbox/screenshot.png
+
+  After adding or removing native files, or editing a podspec:
+    cd ios && pod install
+
+  After changing package.json, the app config or a config plugin (use your package manager;
+  skip prebuild if you commit ios/):
+    bun install && npx expo prebuild --platform ios --no-install && cd ios && pod install
 
 Requires a logged-in eas-cli and cloudflared (brew install cloudflared).
 Docs: https://www.npmjs.com/package/expo-devbox`;
 
-const commands: Record<string, (args: string[]) => unknown> = {
-  init, start, build, ssh: shell, logs, sync, attach, joblog, stop,
-};
+const commands: Record<string, (args: string[]) => unknown> = { init, start, sync, ssh: shell, attach, joblog, stop };
 
 const [name, ...args] = process.argv.slice(2);
 if (!name || name === 'help' || name === '--help' || name === '-h') {

package/src/init.ts

@@ -1,4 +1,4 @@
-import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
 import { UserError, WORKFLOW } from './session';
@@ -8,13 +8,14 @@ const TEMPLATE = join(import.meta.dir, '..', 'templates', 'ios-devbox.yml');
 /** The section `init` adds to AGENTS.md or CLAUDE.md, and prints when neither exists. */
 export const AGENT_INSTRUCTIONS = `## Native iOS builds on EAS (expo-devbox)
 
-Compile and test native iOS code on an EAS macOS worker with \`bunx expo-devbox\`, not on this machine. Do not run \`npx expo run:ios\` or \`xcodebuild\` locally.
+\`bunx expo-devbox\` gives you a macOS EAS worker to build and test this app's native iOS code instead of this machine. Use it only when the user asks for it, for example "build this on the devbox". Otherwise, build and run the app as you normally would.
 
-1. Start a session once: \`bunx expo-devbox start\`. It bills EAS macOS minutes until \`stop\`, its time limit (60 minutes by default), or 15 minutes without a connection.
-2. After each change, run \`bunx expo-devbox build\`. Add \`--pods\` after adding or removing native source files or editing a podspec, and \`--prebuild\` after changing package.json, the app config or a config plugin.
-3. \`build\` syncs your files, compiles, launches the app on the worker's iOS Simulator, and prints the app's console and native logs. It exits non-zero on a compile error (with file and line), a crash at launch (with the crashing frames), or a failed check from devbox.json. Read the output, fix the code, and build again. The screenshot is \`.devbox/screenshot.png\`.
-4. \`bunx expo-devbox ssh '<command>'\` runs a command in the project directory on the worker, for example \`xcrun simctl list devices booted\`.
-5. When you are done, run \`bunx expo-devbox stop\`.
+When the user asks for it:
+
+1. Run \`bunx expo-devbox help\` and follow its "On the worker" section. It has the command for each step: build, install and launch, logs, crash reports and screenshots.
+2. Start a session with \`bunx expo-devbox start\`. It returns when the worker is ready, and EAS macOS minutes are billed until the session ends.
+3. After each change, run \`bunx expo-devbox sync\`, then the commands from the help with \`bunx expo-devbox ssh '<command>'\`.
+4. When the user is done with the devbox, run \`bunx expo-devbox stop\`.
 `;
 
 export function init(args: string[]) {
@@ -33,11 +34,6 @@ export function init(args: string[]) {
     done.push(`Wrote ${WORKFLOW}.`);
   }
 
-  if (!existsSync('devbox.json')) {
-    writeFileSync('devbox.json', `${JSON.stringify({ waitFor: '', failOn: '' }, null, 2)}\n`);
-    done.push('Wrote devbox.json. Set waitFor and failOn to regular expressions that match lines your app logs, so build waits for them and fails on them.');
-  }
-
   const gitignore = existsSync('.gitignore') ? readFileSync('.gitignore', 'utf8') : '';
   if (!/^\/?\.devbox\/?$/m.test(gitignore)) {
     appendFileSync('.gitignore', `${gitignore && !gitignore.endsWith('\n') ? '\n' : ''}\n# expo-devbox session state\n.devbox/\n`);
@@ -62,6 +58,6 @@ export function init(args: string[]) {
   console.log(`
 Next:
   ${linked ? '' : 'eas init                    link this project to EAS, if it is not linked yet\n  '}brew install cloudflared    the SSH tunnel client
-  bunx expo-devbox start      start a session (EAS macOS minutes are billed while it runs)
-  bunx expo-devbox build      build, launch and check the app on the worker`);
+  bunx expo-devbox help       the commands, and how to build and run the app on the worker
+  bunx expo-devbox start      start a session (EAS macOS minutes are billed while it runs)`);
 }

package/src/session.ts

@@ -1,10 +1,10 @@
 /**
  * The session commands: start a devbox workflow run, connect to its worker
- * over SSH through the Cloudflare tunnel it opens, sync sources, build, and
- * stop it. Run from the project root.
+ * over SSH through the Cloudflare tunnel it opens, sync files, run commands,
+ * and stop it. Run from the app's root directory.
  */
 import { $ } from 'bun';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 
@@ -15,8 +15,9 @@ const STATE = '.devbox';
 const SSH_CONFIG = join(STATE, 'ssh_config');
 const RUN_ID = join(STATE, 'run_id');
 const KEY = join(homedir(), '.ssh', 'eas_devbox');
-const WORKER_SCRIPT = join(import.meta.dir, 'worker-build.ts');
 const ACTIVE = new Set(['NEW', 'WAITING', 'IN_PROGRESS', 'ACTION_REQUIRED']);
+/** ssh's exit code when it could not connect, as opposed to the remote command's own code. */
+const SSH_FAILED = 255;
 
 /** An error whose message is meant for the person or agent running the command. */
 export class UserError extends Error {}
@@ -25,8 +26,6 @@ const fail = (message: string): never => {
 };
 const log = (message: string) => console.error(message);
 const sleep = (seconds: number) => Bun.sleep(seconds * 1000);
-/** Quotes a value for the worker's shell. */
-const quote = (value: string) => `'${value.replaceAll("'", `'\\''`)}'`;
 
 type Run = { status: string; jobs?: { id: string }[] };
 
@@ -43,7 +42,7 @@ async function viewRun(runId: string): Promise<Run | undefined> {
 async function requireActive(runId: string): Promise<Run | undefined> {
   const run = await viewRun(runId);
   if (run && !ACTIVE.has(run.status)) {
-    fail(`The devbox session ended with status ${run.status}. See: eas workflow:view ${runId}`);
+    fail(`The devbox session ended with status ${run.status}. Start a new one with: expo-devbox start`);
   }
   if (run?.status === 'ACTION_REQUIRED') {
     status('blocked', { kind: 'permission', msg: 'The devbox workflow run needs approval on expo.dev' });
@@ -57,14 +56,10 @@ function savedRun(): string {
 }
 
 function requireProject() {
-  if (!existsSync(WORKFLOW)) fail(`${WORKFLOW} is missing. Run expo-devbox init in the project root first.`);
+  if (!existsSync(WORKFLOW)) fail(`${WORKFLOW} is missing. Run expo-devbox init in the app's root directory first.`);
   mkdirSync(STATE, { recursive: true });
 }
 
-function ssh(remoteCommand: string) {
-  return $`ssh -F ${SSH_CONFIG} devbox ${remoteCommand}`;
-}
-
 /**
  * Reads the tunnel host, user and host key from the job log and writes an SSH
  * config for them. The last DEVBOX_SSH_HOST wins, because the worker starts a
@@ -103,7 +98,7 @@ async function connect(runId: string): Promise<void> {
     }
     await sleep(10);
   }
-  fail(`Could not reach the worker for 15 minutes. See: eas workflow:view ${runId}`);
+  fail('Could not reach the worker for 15 minutes. See: expo-devbox joblog');
 }
 
 function writeSshConfig(host: string, user: string, hostKey: string) {
@@ -124,19 +119,30 @@ function writeSshConfig(host: string, user: string, hostKey: string) {
 `);
 }
 
-/** Waits for the worker to finish preparing the project. Reconnects if the worker is unreachable. */
+/**
+ * Reconnects first if the worker is unreachable, for example because its
+ * tunnel moved. A command is never run twice: if the connection drops while
+ * it runs, it may already have done its work.
+ */
+async function ensureConnected() {
+  const probe = await $`ssh -F ${SSH_CONFIG} devbox true`.quiet().nothrow();
+  if (probe.exitCode === SSH_FAILED) await connect(savedRun());
+}
+const droppedMessage = 'The connection to the worker dropped while the command ran. It may have finished on the worker; check before you run it again.';
+
+/** Waits for the worker to prepare the app: install, prebuild, pods, simulator, Metro and a first build. */
 async function waitUntilReady(runId: string) {
+  log('Waiting for the worker to prepare the app (about 3 minutes)...');
+  status('working', { msg: 'The EAS worker is preparing the app' });
   const deadline = Date.now() + 20 * 60_000;
   while (Date.now() < deadline) {
-    const result = await ssh('test -f ~/.devbox/ready').quiet().nothrow();
+    const result = await $`ssh -F ${SSH_CONFIG} devbox ${'test -f ~/.devbox/ready'}`.quiet().nothrow();
     if (result.exitCode === 0) return;
-    if (result.exitCode === 255) {
+    if (result.exitCode === SSH_FAILED) {
       await connect(runId);
       continue;
     }
     await requireActive(runId);
-    log('Waiting for the worker to finish preparing the project...');
-    status('working', { msg: 'The EAS worker is preparing the project' });
     await sleep(15);
   }
   fail('The worker is not ready after 20 minutes. See: expo-devbox joblog');
@@ -149,7 +155,7 @@ export async function start(args: string[]) {
     const previous = readFileSync(RUN_ID, 'utf8').trim();
     const run = await viewRun(previous);
     if (run && ACTIVE.has(run.status)) {
-      fail(`A devbox session is already running (run ${previous}). Use expo-devbox attach or expo-devbox stop.`);
+      fail(`A devbox session is already running (run ${previous}). Use it, or end it with: expo-devbox stop`);
     }
   }
   const [minutes = '60', idleMinutes = '15'] = args;
@@ -163,7 +169,7 @@ export async function start(args: string[]) {
   if (result.exitCode !== 0) fail(`eas workflow:run failed:\n${result.stderr.toString().trim()}`);
   const runId: string = JSON.parse(result.stdout.toString()).id;
   writeFileSync(RUN_ID, runId);
-  log(`Started run ${runId}: ${minutes} minutes at most, ending after ${idleMinutes} idle minutes.`);
+  log(`Started run ${runId}: ${minutes} minutes at most, ending after ${idleMinutes} minutes without an SSH connection.`);
 
   // Cancel the run if this command fails or is interrupted, so it does not bill with nobody connected.
   const cancel = () => $`eas workflow:cancel ${runId} --non-interactive`.quiet().nothrow();
@@ -176,6 +182,7 @@ export async function start(args: string[]) {
   process.once('SIGINT', onInterrupt);
   try {
     await connect(runId);
+    await waitUntilReady(runId);
   } catch (error) {
     log(`Cancelling run ${runId}.`);
     await cancel();
@@ -183,8 +190,8 @@ export async function start(args: string[]) {
   } finally {
     process.removeListener('SIGINT', onInterrupt);
   }
-  log(`The worker is still preparing the project. 'expo-devbox build' waits for it.`);
-  status('done', { msg: 'Connected to the EAS worker' });
+  console.log('The worker is ready. Run expo-devbox help and follow "On the worker" to build and run the app.');
+  status('done', { msg: 'The EAS worker is ready' });
 }
 
 export async function attach(args: string[]) {
@@ -192,7 +199,9 @@ export async function attach(args: string[]) {
   const runId = args[0] ?? savedRun();
   writeFileSync(RUN_ID, runId);
   await connect(runId);
-  status('done', { msg: 'Connected to the EAS worker' });
+  await waitUntilReady(runId);
+  console.log('The worker is ready.');
+  status('done', { msg: 'The EAS worker is ready' });
 }
 
 /**
@@ -209,40 +218,11 @@ export async function sync() {
     .split('\n').filter(Boolean).map(path => `/${path}`);
   const excludes = join(STATE, 'rsync-excludes');
   writeFileSync(excludes, [...gitignore, ...ignored].join('\n') + '\n');
-  await $`rsync -az --delete -e ${`ssh -F ${SSH_CONFIG}`} --exclude .git --exclude node_modules --exclude /.devbox \
-    --exclude /ios/Pods --exclude-from=${excludes} ./ devbox:project/`;
-}
-
-export async function build(args: string[]) {
-  requireProject();
-  const [option] = args;
-  if (option && option !== '--pods' && option !== '--prebuild') fail('Usage: expo-devbox build [--pods|--prebuild]');
-  const runId = savedRun();
-  status('working', { msg: 'Waiting for the EAS worker' });
-  await waitUntilReady(runId);
-  status('working', { msg: 'Syncing sources to the EAS worker' });
-  await sync();
-  await $`scp -q -F ${SSH_CONFIG} ${WORKER_SCRIPT} devbox:.devbox/worker-build.ts`;
-
-  status('working', { msg: option ? `Building on the EAS worker (${option.slice(2)})` : 'Building on the EAS worker' });
-  const screenshot = join(STATE, 'screenshot.png');
-  rmSync(screenshot, { force: true });
-  const result = await ssh(`cd ~/project && bun ~/.devbox/worker-build.ts ${option ?? ''}`).nothrow();
-  if ((await $`scp -q -F ${SSH_CONFIG} devbox:.devbox/screenshot.png ${screenshot}`.quiet().nothrow()).exitCode === 0) {
-    console.log(`Screenshot copied to ${screenshot}`);
-  }
-  const summary = result.stdout.toString().match(/BUILD (SUCCEEDED|FAILED)[^\n]*/)?.[0];
-  if (result.exitCode === 0) {
-    status('done', { msg: summary ?? 'Build succeeded' });
-  } else {
-    status('error', { msg: summary?.startsWith('BUILD FAILED') ? summary : 'The app failed its checks; see the output' });
-  }
-  process.exitCode = result.exitCode;
-}
-
-export async function logs(args: string[]) {
-  requireProject();
-  await ssh(`grep -a -E ${quote(args[0] ?? '.')} ~/.devbox/metro.log | tail -50`).nothrow();
+  await ensureConnected();
+  const { exitCode } = await $`rsync -az --delete -e ${`ssh -F ${SSH_CONFIG}`} \
+    --exclude .git --exclude node_modules --exclude /.devbox --exclude /ios/Pods --exclude-from=${excludes} \
+    ./ devbox:project/`.nothrow();
+  if (exitCode !== 0) fail(`rsync exited ${exitCode}. Run expo-devbox sync again; it only sends what changed.`);
 }
 
 export async function shell(args: string[]) {
@@ -253,13 +233,16 @@ export async function shell(args: string[]) {
     process.exitCode = await child.exited;
     return;
   }
-  process.exitCode = (await ssh(`cd ~/project && ${args.join(' ')}`).nothrow()).exitCode;
+  await ensureConnected();
+  const { exitCode } = await $`ssh -F ${SSH_CONFIG} devbox ${`cd ~/project && ${args.join(' ')}`}`.nothrow();
+  if (exitCode === SSH_FAILED) console.error(droppedMessage);
+  process.exitCode = exitCode;
 }
 
 export async function joblog() {
   requireProject();
   const jobId = (await viewRun(savedRun()))?.jobs?.[0]?.id;
-  if (!jobId) fail('Could not find the job of the devbox run. See: eas workflow:view ' + savedRun());
+  if (!jobId) fail(`Could not find the job of the devbox run. See: eas workflow:view ${savedRun()}`);
   await $`eas workflow:logs ${jobId} --non-interactive`.nothrow();
 }
 

package/templates/ios-devbox.yml

@@ -139,9 +139,26 @@ jobs:
             console.log(d.udid);')
           xcrun simctl boot "$udid"
           xcrun simctl bootstatus "$udid" -b
-          echo "$udid" > ~/.devbox/sim
           xcrun simctl list devices booted
 
+          # Values that the commands in `expo-devbox help` use, set in every SSH
+          # session. Prebuild names the scheme, the app and its executable alike.
+          workspace=$(ls -d ios/*.xcworkspace | head -1)
+          scheme=$(basename "$workspace" .xcworkspace)
+          bundle_id=$(npx expo config --type public --json | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).ios?.bundleIdentifier ?? ""')
+          derived="$HOME/.devbox/DerivedData"
+          cat >> ~/.ssh/environment <<EOF
+          DEVBOX_SIMULATOR=$udid
+          DEVBOX_WORKSPACE=$workspace
+          DEVBOX_SCHEME=$scheme
+          DEVBOX_DERIVED_DATA=$derived
+          DEVBOX_APP=$derived/Build/Products/Debug-iphonesimulator/$scheme.app
+          DEVBOX_BUNDLE_ID=$bundle_id
+          DEVBOX_EXECUTABLE=$scheme
+          DEVBOX_LOG_PREDICATE=process == "$scheme" AND (senderImagePath CONTAINS "/$scheme.app/" OR (senderImagePath ENDSWITH "/Foundation" AND NOT subsystem CONTAINS "."))
+          EOF
+          grep '^DEVBOX_' ~/.ssh/environment
+
       - name: Keep the worker up
         run: |
           dir="$HOME/.devbox"
@@ -150,13 +167,11 @@ jobs:
             env -u CI npx expo start --localhost > "$dir/metro.log" 2>&1 < /dev/null &
           }
           start_metro
-          # The same xcodebuild arguments as `expo-devbox build`, so its first build is incremental.
-          workspace=$(ls -d ios/*.xcworkspace | head -1)
-          scheme=$(node -p 'try { require("./devbox.json").scheme || "" } catch { "" }')
-          xcodebuild -workspace "$workspace" -scheme "${scheme:-$(basename "$workspace" .xcworkspace)}" \
-            -configuration Debug -sdk iphonesimulator -destination "platform=iOS Simulator,id=$(cat "$dir/sim")" \
-            -derivedDataPath "$dir/DerivedData" build > "$dir/xcodebuild.log" 2>&1 \
-            || echo "The warm-up build failed. Run expo-devbox build to see why."
+          # The build command from `expo-devbox help`, so the first build there is incremental.
+          devbox() { grep "^$1=" ~/.ssh/environment | cut -d= -f2-; }
+          xcodebuild -quiet -workspace "$(devbox DEVBOX_WORKSPACE)" -scheme "$(devbox DEVBOX_SCHEME)" -configuration Debug \
+            -destination "id=$(devbox DEVBOX_SIMULATOR)" -derivedDataPath "$(devbox DEVBOX_DERIVED_DATA)" build \
+            > "$dir/warm-up-build.log" 2>&1 || echo "The warm-up build failed. Run the build command from expo-devbox help to see why."
           touch "$dir/ready"
           echo "Devbox ready at ~/project."
 

package/src/worker-build.ts

@@ -1,181 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Runs on the devbox worker, in the project directory. Builds the iOS app with
- * Xcode, installs it on the devbox simulator, launches it, and prints its logs.
- * Exits non-zero when the build fails, the app is not running after launch, or
- * the checks in devbox.json fail. `expo-devbox build` copies this file to the
- * worker, so it must not import anything but Bun and Node built-ins.
- *
- *   worker-build.ts             incremental build
- *   worker-build.ts --pods      run `pod install` first
- *   worker-build.ts --prebuild  install dependencies, run `expo prebuild` and `pod install` first
- */
-import { $ } from 'bun';
-import { appendFileSync, existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { basename, join } from 'node:path';
-
-type Config = { waitFor?: string; failOn?: string; waitSeconds?: number; scheme?: string };
-
-const state = join(homedir(), '.devbox');
-const config: Config = existsSync('devbox.json') ? JSON.parse(readFileSync('devbox.json', 'utf8')) : {};
-const waitSeconds = config.waitSeconds ?? (config.waitFor ? 60 : 8);
-const prepareLog = join(state, 'prepare.log');
-
-/** Runs a setup command with its output in prepare.log, which is printed only if the command fails. */
-async function prepare(label: string, command: () => Promise<{ exitCode: number; stdout: Buffer; stderr: Buffer }>) {
-  console.log(`Running: ${label}`);
-  const result = await command();
-  appendFileSync(prepareLog, `$ ${label}\n${result.stdout}${result.stderr}`);
-  if (result.exitCode !== 0) {
-    console.log(readFileSync(prepareLog, 'utf8').trimEnd().split('\n').slice(-30).join('\n'));
-    console.log(`FAILED: ${label}. Full log: ${prepareLog}`);
-    process.exit(1);
-  }
-}
-const podInstall = () => prepare('pod install', () => $`pod install`.cwd('ios').quiet().nothrow());
-
-writeFileSync(prepareLog, '');
-const flag = process.argv[2];
-if (flag === '--prebuild') {
-  const manager = existsSync('bun.lock') || existsSync('bun.lockb') ? 'bun'
-    : existsSync('pnpm-lock.yaml') ? 'pnpm' : existsSync('yarn.lock') ? 'yarn' : 'npm';
-  await prepare(`${manager} install`, () => $`${manager} install`.quiet().nothrow());
-  if (existsSync(join(state, 'cng'))) {
-    await prepare('expo prebuild', () => $`npx expo prebuild --platform ios --no-install`.quiet().nothrow());
-  }
-  await podInstall();
-} else if (flag === '--pods') {
-  await podInstall();
-} else if (flag) {
-  console.log(`Unknown option ${flag}. Use --pods or --prebuild.`);
-  process.exit(1);
-}
-
-const workspace = readdirSync('ios').find(name => name.endsWith('.xcworkspace'));
-if (!workspace) {
-  console.log('No .xcworkspace in ios/. Run the build again with --prebuild.');
-  process.exit(1);
-}
-const scheme = config.scheme || basename(workspace, '.xcworkspace');
-const udid = readFileSync(join(state, 'sim'), 'utf8').trim();
-const derived = join(state, 'DerivedData');
-const buildLog = join(state, 'xcodebuild.log');
-const screenshot = join(state, 'screenshot.png');
-rmSync(screenshot, { force: true });
-
-const start = Date.now();
-const seconds = () => Math.round((Date.now() - start) / 1000);
-const build = await $`xcodebuild -workspace ${`ios/${workspace}`} -scheme ${scheme} -configuration Debug -sdk iphonesimulator \
-  -destination ${`platform=iOS Simulator,id=${udid}`} -derivedDataPath ${derived} build &> ${buildLog}`.nothrow();
-if (build.exitCode !== 0) {
-  const lines = readFileSync(buildLog, 'utf8').split('\n');
-  const errors = [...new Set(lines.filter(line => /(error|fatal error):/.test(line)))].slice(0, 40);
-  console.log((errors.length ? errors : lines.slice(-30)).join('\n'));
-  console.log(`BUILD FAILED after ${seconds()}s. Full log: ${buildLog}`);
-  process.exit(1);
-}
-console.log(`BUILD SUCCEEDED in ${seconds()}s`);
-
-const metroUp = await fetch('http://localhost:8081/status').then(r => r.ok, () => false);
-if (!metroUp) {
-  console.log('Metro is not running. The worker restarts it within a minute; run the build again then.');
-  process.exit(1);
-}
-
-const products = join(derived, 'Build/Products/Debug-iphonesimulator');
-const app = join(products, readdirSync(products).find(name => name.endsWith('.app'))!);
-const plist = join(app, 'Info.plist');
-const plistValue = async (key: string) => (await $`/usr/libexec/PlistBuddy -c ${`Print :${key}`} ${plist}`.text()).trim();
-const bundleId = await plistValue('CFBundleIdentifier');
-const executable = await plistValue('CFBundleExecutable');
-const metroLog = join(state, 'metro.log');
-const nativeLog = join(state, 'native.log');
-const metroStart = readFileSync(metroLog).length;
-
-await $`xcrun simctl install ${udid} ${app}`;
-// Messages logged by code inside the app bundle, plus NSLog (sent from
-// Foundation, with no subsystem); not the system libraries' own logging.
-// `subsystem == ""` never matches, so "no subsystem" is written as no dot.
-const predicate = `process == "${executable}" AND (senderImagePath CONTAINS "/${executable}.app/" `
-  + `OR (senderImagePath ENDSWITH "/Foundation" AND NOT subsystem CONTAINS "."))`;
-const logStream = Bun.spawn(['xcrun', 'simctl', 'spawn', udid, 'log', 'stream', '--style', 'compact', '--predicate', predicate],
-  { stdout: Bun.file(nativeLog), stderr: 'ignore' });
-await $`xcrun simctl launch --terminate-running-process ${udid} ${bundleId}`.quiet();
-
-const appOutput = () => readFileSync(metroLog).subarray(metroStart).toString()
-  .split('\n').filter(line => /^ (LOG|WARN|ERROR) /.test(line)).join('\n');
-// Simulator apps run as processes of the host.
-const appRunning = async () => (await $`pgrep -f ${`/${executable}.app/${executable}`}`.quiet().nothrow()).exitCode === 0;
-const matches = (pattern: string | undefined) => !!pattern && new RegExp(pattern, 'm').test(appOutput());
-
-for (let i = 0; i < waitSeconds; i += 1) {
-  if (matches(config.waitFor)) break;
-  if (config.waitFor && i > 3 && !(await appRunning())) break;
-  await Bun.sleep(1000);
-}
-if ((await $`xcrun simctl io ${udid} screenshot ${screenshot}`.quiet().nothrow()).exitCode !== 0) {
-  console.log('Could not take a screenshot.');
-}
-logStream.kill();
-await logStream.exited;
-
-console.log('App console output from this launch:');
-console.log(appOutput() || '(none)');
-console.log('Native log from this launch (system libraries excluded):');
-const native = readFileSync(nativeLog, 'utf8').split('\n')
-  .filter(line => line && !/^(Filtering the log data|Timestamp |getpwuid_r |Child process terminated)/.test(line));
-console.log(native.slice(-40).join('\n') || '(none)');
-
-let status = 0;
-if (!(await appRunning())) {
-  console.log('The app is not running. It may have crashed at launch.');
-  await printCrashReport(executable, statSync(plist).mtimeMs);
-  status = 1;
-}
-if (config.waitFor && !matches(config.waitFor)) {
-  console.log(`The app did not log a line matching waitFor (${config.waitFor}).`);
-  status = 1;
-}
-if (matches(config.failOn)) {
-  console.log(`The app logged a line matching failOn (${config.failOn}).`);
-  status = 1;
-}
-process.exit(status);
-
-/**
- * Prints the exception and the crashing thread's frames from the newest crash
- * report written since the build. macOS writes the report a few seconds after
- * the crash, so this waits for it.
- */
-async function printCrashReport(executable: string, since: number) {
-  const dir = join(homedir(), 'Library/Logs/DiagnosticReports');
-  const newest = () => (existsSync(dir) ? readdirSync(dir) : [])
-    .filter(name => name.startsWith(executable) && name.endsWith('.ips'))
-    .map(name => ({ path: join(dir, name), time: statSync(join(dir, name)).mtimeMs }))
-    .filter(report => report.time > since)
-    .sort((a, b) => b.time - a.time)[0];
-  let report = newest();
-  for (let i = 0; !report && i < 10; i += 1) {
-    await Bun.sleep(1000);
-    report = newest();
-  }
-  if (!report) {
-    console.log('No crash report appeared within 10 seconds.');
-    return;
-  }
-  console.log(`Crash report ${report.path}:`);
-  // An .ips file is a JSON header line followed by the JSON report.
-  const text = readFileSync(report.path, 'utf8');
-  try {
-    const crash = JSON.parse(text.slice(text.indexOf('\n') + 1));
-    console.log(`${crash.exception?.type} (${crash.exception?.signal}), ${crash.termination?.indicator ?? ''}`);
-    const thread = crash.threads?.find((t: { triggered?: boolean }) => t.triggered);
-    for (const frame of thread?.frames?.slice(0, 15) ?? []) {
-      const where = frame.sourceFile ? ` (${frame.sourceFile}:${frame.sourceLine})` : '';
-      console.log(`  ${crash.usedImages?.[frame.imageIndex]?.name ?? '?'}  ${frame.symbol ?? '?'}${where}`);
-    }
-  } catch {
-    console.log(text.split('\n').slice(0, 40).join('\n'));
-  }
-}