@expo/simulator-launcher 27.5.0 → 27.7.0

package/README.md

@@ -1,8 +1,8 @@
 # @expo/simulator-launcher
 
-Warm iOS Simulators before an EAS job arrives. Requires macOS.
-The image installs vm-tools and writes its startup script at
-`/usr/local/share/vm-tools/startup.sh`:
+Prepare iOS Simulators and native tools, cache Expo Go and Appium files, and claim prepared sessions. Requires macOS.
+
+Start the launcher with the devices you want to prepare:
 
 ```sh
 export EXPO_SIMULATOR_STARTUP=1
@@ -21,26 +21,47 @@ exec bunx @expo/simulator-launcher@latest start
 - `prepare-tools`: continue the consumed claim after adoption. Keep global Argent, reuse the default
   agent-device runner or prepare a runner for the selected device. Appium waits for old XCTest cleanup.
 - `stop`: permanently end warmup for this boot and wait for all owned resources to be cleaned up.
+- `warmup`: populate Simulator and native tool caches. With `EXPO_SIMULATOR_STARTUP=1`,
+  calls `prefetch`, boots the selected Simulators, installs Expo Go unless disabled, and waits
+  for Argent and agent-device on the default device. It then drains owned processes and shuts
+  down the selected Simulators. Prepared files and native build caches remain available.
+  Incomplete preparation or cleanup fails. The preparation deadline is ten minutes; cleanup
+  can take longer. Requires a fresh macOS boot before `start` has run. A repeat, or `start`
+  after `warmup`, requires another boot. It does not start an Appium session or prepare an
+  agent-device runner on secondary devices.
+- `prefetch`: cache the selected Expo Go archive for reuse. With `APPIUM_VERSION` and `XCUITEST_VERSION`, prepare Appium, XCUITest and WebDriverAgent files. It does not fetch serve-sim, agent-device or Argent. Progress goes to stderr; the command stops at the first failure.
+
+Consumers use the launcher version recorded by `start` for session commands (`LAUNCHER_VERSION`
+below). Run these in another process:
 
 ```sh
-# Build-tools reads LAUNCHER_VERSION from the version recorded by start.
-bun x --no-install "@expo/simulator-launcher@$LAUNCHER_VERSION" claim serve-sim
-# After private serve-sim adoption confirms the selected device and native ACK:
-bun x --no-install "@expo/simulator-launcher@$LAUNCHER_VERSION" prepare-tools
-bun x --no-install "@expo/simulator-launcher@$LAUNCHER_VERSION" stop
+bun x "@expo/simulator-launcher@$LAUNCHER_VERSION" claim serve-sim
+# After adoption confirms the selected device and native ACK:
+bun x "@expo/simulator-launcher@$LAUNCHER_VERSION" prepare-tools
+bun x "@expo/simulator-launcher@$LAUNCHER_VERSION" stop
 ```
 
-There is no copied launcher bundle. Build-tools uses the recorded package version for claim/stop;
-Warmup primes Bun’s exact-version cache before ready, with two attempts of up to 30 seconds. Its claim/stop calls use `--no-install`, retrying
-once with the registry only when Bun cannot find that cached binary. Priming failures warn.
-Before start has run,
-stop uses the normal package-manager path and still disables later warmup for this boot.
+To cache files without booting devices:
+
+```sh
+simulator-launcher prefetch
+```
 
-This flow requires the serve-sim release supporting port-based device adoption.
+To also prepare Simulators and native tools (`warmup` already calls `prefetch`):
+
+```sh
+EXPO_SIMULATOR_STARTUP=1 simulator-launcher warmup
+```
+
+Session adoption requires the serve-sim release supporting port-based device adoption.
 
 One durable state file, `/tmp/expo-simulator-startup.json`, holds the lifecycle, launcher version,
 selected device, server credentials, claim and native identity. It is independent of HOME/TMPDIR. A short boot-scoped lock
-serializes updates; an abandoned lock fails closed. This private format requires a fresh VM.
+serializes updates; an abandoned lock fails closed. State is scoped to the current boot.
+`start` uses the supplied runtime package versions and records exact version inputs as
+`serveSimVersion`, `agentDeviceVersion` and `argentVersion` in this state and the claim. Consumers
+compare explicit package requests with these versions before reuse. Tags, ranges and unset inputs
+do not report an exact version. Build-tools also uses `serveSimVersion` for warm adoption and recordings.
 
 ## Environment
 
@@ -50,13 +71,74 @@ serializes updates; an abandoned lock fails closed. This private format requires
   trimmed and must each identify one available device. The first is the default. Unset keeps
   the shortest available iPhone name, as does an empty or blank value. Empty list entries, missing,
   ambiguous or duplicate devices fail clearly.
-- `SERVE_SIM_VERSION`, `AGENT_DEVICE_VERSION`, `ARGENT_VERSION`: each defaults to `latest`.
+- `SERVE_SIM_VERSION`, `AGENT_DEVICE_VERSION`, `ARGENT_VERSION` (`start`/`warmup` only): runtime
+  package selections, each defaulting to `latest`. The launcher passes them to Bun without a separate
+  version lookup. Callers that select exact versions can identify them in state and claims.
+  `prefetch` ignores these settings and never records them in `prepared.json`.
+- `EXPO_GO_SDK_VERSION`: select an SDK for `prefetch` and `start` with an https iOS Simulator archive
+  in the Expo versions API. Unset selects the latest stable SDK; a pin must be `x.y.z` and may select
+  a beta. `start` reuses recorded SDK/archive metadata when it matches the supplied SDK, or when
+  no SDK is supplied. Without matching metadata, startup selects from the API using this variable
+  or the latest stable SDK. Ignored when `EXPO_SIMULATOR_PREINSTALL_EXPO_GO=0`.
+- `APPIUM_VERSION`, `XCUITEST_VERSION` (`prefetch` only): exact versions (`x.y.z`), both or
+  neither. Any other value makes `prefetch` fail.
 - `AGENT_DEVICE_STATE_DIR`, `ARGENT_EVENT_LOG`: tool state/output locations.
 - Agent-device idle timers default to off. Override with `AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS`
   and `AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS` (milliseconds).
 
+## Prepared files
+
+`prefetch` writes `expo-go/` and `appium/` under `~/Library/Caches/expo-simulator-startup/`, and
+removes each one when its step is skipped. Each reader checks the files before it uses them and
+otherwise runs its normal download or install. Keep these directories when reusing prepared files.
+
+- `expo-go/<sha256 of the archive URL>.tar.gz`: `start` uses the recorded URL when its SDK matches
+  the supplied selection, or when no SDK is supplied. It checks the file with `gzip -t` before
+  extraction. A missing or damaged archive is downloaded again from that URL.
+- `appium/`: an Appium home with the pinned xcuitest driver and WebDriverAgent runner.
+  Prefetch checks the runner's bundle metadata and executable before recording it.
+  Build-tools reuses it when the files match the manifest and Appium matches the current
+  resolution of an explicit version request, including ranges and `latest`. Without an override,
+  the prepared version must satisfy the default Appium 3 range. Build-tools does not write or
+  remove this home. These checks do not load the driver or launch WDA; validate reuse with a
+  real Appium session.
+
+### Prepared tool manifest
+
+`prefetch` writes `~/Library/Caches/expo-simulator-startup/prepared.json` after all requested
+steps and temporary-file cleanup succeed. Before refreshing caches, it removes the previous
+manifest. Skipped tools are absent from the new manifest; a failed preparation publishes no new one.
+
+The JSON has a `tools` map:
+
+- `appium.version`, `appium.xcuitest`, `appium.home`: the prepared Appium and XCUITest versions
+  and the absolute Appium home path. This entry is written only after WDA preparation succeeds.
+
+When Expo Go is enabled, `expo-go.sdk` and `expo-go.url` in `tools` record its selected SDK and archive URL.
+The SDK identifies the selected Expo release, not the app's binary version. With every step
+disabled or unset, the manifest is `{"tools":{}}`.
+
+`start` reads only the optional Expo Go selection from this manifest. Missing or invalid Expo Go
+metadata, or metadata for a different supplied SDK, uses normal SDK/archive selection. Legacy
+serve-sim, agent-device and Argent entries are ignored, including malformed entries. Exact CLI
+version inputs are recorded only in the current boot's state and claim.
+
+Build-tools' shared `readPreparedSimulatorToolAsync(tool, schema)` reader selects an entry from
+`tools` using the consumer's schema. Each consumer checks compatibility before reuse. Missing,
+invalid or older metadata is a cache miss and uses normal setup.
+
+Keep the Expo Go archive and the whole Appium home, not only the manifest. Appium's home
+must stay at the recorded path under the same user. Rerun `prefetch` to regenerate the manifest
+when changing versions. Metadata does not prove that a driver loads or WDA launches; validate
+Appium reuse with a real session.
+
 ## Boundaries
 
+Native warmup still runs serve-sim, agent-device and Argent. Bun may cache their packages as a side
+effect; these incidental caches are retained. The caller supplies the requested package selections
+for each boot, and Bun reuses matching files or fetches the requested versions. Native build-cache
+reuse depends on the selected version and device.
+
 - Ready means the default device booted and serve-sim answers. The apsd step and the Expo Go
   preinstall run in the background on every listed device. A claim does not wait for them; stop
   joins them.
@@ -67,13 +149,15 @@ serializes updates; an abandoned lock fails closed. This private format requires
 - Agent-device prestarts on the default device only. A secondary claim prepares its runner after
   adoption and old-runner cleanup finish. One device-independent Argent server is reused for the claimed device.
   Appium waits for unused tools to stop before starting its own WDA.
-- Warmup downloads/extracts the latest stable Expo Go once and reuses it for the second device.
+- Warmup uses the prepared Expo Go selection, or the standalone SDK selection when none exists, once, from the
+  prefetched archive (see
+  [Prepared files](#prepared-files)) or by download, and reuses it for the second device.
   Each initial device gets a preinstall attempt; ordinary failures warn. Claim prevents new
   preinstalls. `prepare-tools` waits for an install still running on the claimed device and
   reports its version, because the job installs its app next. Installs on other devices continue;
   adoption may shut such a device down, and its install then fails with a warning. Terminal stop
   drains them and the download cleanup. Job app installs remain
-  authoritative. Replacements do not preinstall again. The VM image provides ffmpeg.
+  authoritative. Replacements do not preinstall again. `ffmpeg` must be available on PATH.
 - One start attempt and one accepted claim per boot. Failed cleanup never permits another session.
   Stop's caller timeout is not a global cleanup deadline or proof that teardown completed.
   A build-tools claim timeout uses normal startup only after confirmed terminal cleanup.