@expo/serve-sim 0.1.52 → 0.1.54

package/README.md

@@ -295,11 +295,82 @@ The npm package ships the native capture addon and LiveKit WebRTC framework alon
 
 ```sh
 bun install
-bun run packages/serve-sim/build.ts                    # full production build
-packages/serve-sim/Sources/SimNative/build.sh           # native addon only
-bun run --filter serve-sim dev                          # watch mode
+bun run packages/serve-sim/build.ts                   # full production build
+packages/serve-sim/Sources/SimNative/build.sh         # native addon only
+bun run --filter @expo/serve-sim dev                  # watch mode
+bun run --filter @expo/serve-sim tart-dev             # guest preview at localhost:3200
+bun run --filter @expo/serve-sim tart-test -- <files> # bun test on the guest
 ```
 
+### Tart guest
+
+Run serve-sim **on a [tart](https://github.com/cirruslabs/tart) macOS VM** instead of the host. SSH as Unix user `expo` (not `tart exec` as admin), which matches how EAS-shaped VMs actually run.
+
+Needs the `tart` CLI, a VM with Xcode (default name `tahoe-xcode`), and a built native addon.
+
+```sh
+bun run packages/serve-sim/build.ts
+bun run --filter @expo/serve-sim tart-dev
+# → Preview at http://localhost:3200
+```
+
+`tart-dev` starts the VM if needed, boots an iPhone 17, runs `bun run dev.ts` on the guest, and tunnels guest `:3200` to the host. Host port `3200` must be free. Ctrl-C stops the tunnel and the guest server.
+
+`tart-test` uses the same guest, but runs `bun test` there. It stages package src onto the VM, boots an iPhone, and executes the files you pass over SSH as `expo`. Pass the files; with none it exits instead of running the whole guest suite.
+
+```sh
+bun run --filter @expo/serve-sim tart-test -- src/__tests__/foo.test.ts
+bun run --filter @expo/serve-sim tart -- test src/__tests__/foo.test.ts
+```
+
+First run creates the `expo` user and copies bun onto the guest (`bun run --filter @expo/serve-sim tart -- setup` if you want that step alone).
+
+The VM mounts this checkout at `/Volumes/My Shared Files/serve-sim`. If the VM was started from a different worktree, stop it and rerun from this one.
+
+```sh
+bun run --filter @expo/serve-sim tart -- ssh                 # shell as expo
+```
+
+`tart` also has `up`, `boot`, and `stage` if you need the pieces separately.
+
+Env (all optional): `TART_VM=tahoe-xcode`, `TART_USER=expo`, `TART_SHARE_NAME=serve-sim`, `PORT=3200`.
+
+### EAS preview of a CI package
+
+`--package-version` pins serve-sim only on `--type web-preview-only`. The other session types use the flag for their own package (`agent-device`, `appium`, `argent`) and always run serve-sim at `latest`, so a serve-sim tarball URL breaks them.
+
+The `serve-sim tests` workflow packs `serve-sim.tgz` on every pull request and uploads it as `serve-sim-npm-package`. It packs before the tests run, so the tarball exists even when they fail. `Build @expo/serve-sim release` uploads the same artifact on demand. Copy the download URL from the run, then pass it as `--package-version`. Run these commands from an Expo project directory.
+
+```sh
+npx --yes eas-cli@latest workflow:runs --workflow sim-test.yml --limit 5
+
+npx --yes eas-cli@latest workflow:view <workflow-run-id> --non-interactive --json \
+  | jq -er '.jobs[].artifacts[]? | select(.name == "serve-sim-npm-package") | .downloadUrl'
+```
+
+`--non-interactive` requires the run ID as an argument. Without it, `workflow:view` prompts for a run. Without `--json`, it prints a Log URL for the run on the Expo dashboard, and each job lists its artifacts with a Download URL.
+
+The download URL is signed and expires one hour after `workflow:view` returns it. The worker installs the package minutes after the session starts, so copy a fresh URL for each session. An expired URL fails in the job log, not in your terminal. The URL also appears in that log, so anyone who can read the run can download the artifact until the URL expires.
+
+```sh
+npx --yes eas-cli@latest simulator:start --platform ios --type web-preview-only --non-interactive \
+  --name "serve-sim preview" \
+  --package-version '<download-url>'
+```
+
+EAS runs `npx @expo/serve-sim@<value>`, so the flag takes any npm spec: a version, a tag, or a tarball URL. Quote the URL.
+
+Install and launch an app at start with one of `--build-id`, `--application-archive-url`, or `--expo-go`. `--launch-arg` and `--open-url` need one of those. `--sdk-version` needs `--expo-go`.
+
+```sh
+npx --yes eas-cli@latest simulator:start --platform ios --type web-preview-only --non-interactive \
+  --name "serve-sim preview" \
+  --package-version '<download-url>' \
+  --expo-go
+```
+
+EAS installs and launches the app before serve-sim starts. After the preview is up, drop an `.ipa` on the page to install another app. The page takes an `.ipa` or media, not an `.app` bundle or a build archive, so pass `--build-id` or `--application-archive-url` for those. Stop with `npx --yes eas-cli@latest simulator:stop`.
+
 ## Origin and attribution
 
 `serve-sim` was created and open-sourced by [Evan Bacon](https://github.com/EvanBacon) in the [original serve-sim project](https://github.com/EvanBacon/serve-sim). This repository is an Expo-maintained fork. We are grateful to Evan for creating the project and making it available to the community.