Skip to content

Commit 50ff4c3

Browse files
fix(mobile): ensure a compatible native client before verification (#11862)
1 parent 6ecc15f commit 50ff4c3

6 files changed

Lines changed: 469 additions & 18 deletions

File tree

‎.agents/skills/ios-debugger-agent/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ Avoid generic Mac window automation for switching among Simulator windows. Expli
3131

3232
## Choose build or launch
3333

34+
For T3 Code Mobile, run `node scripts/mobile-native-client.ts ensure ios <simulator-udid>` from the checkout on the simulator host first. It checks the local Expo native fingerprint against the installed client and builds/installs when stale, missing, or unknown. Then launch with the intended Metro bundle. Authorized verification includes native builds and installs; do not stop because the existing client is old. Use `check` instead of `ensure` only when the user explicitly prohibits rebuilding or requests a read-only check.
35+
3436
- Use `build_run_sim` when native source, native dependencies, entitlements, or project configuration changed.
3537
- Use `test_sim` for the smallest relevant native test target or test cases; do not run an entire workspace test matrix routinely.
3638
- Use `launch_app_sim` when a compatible app is already installed and no native rebuild is needed.

‎.agents/skills/test-t3-mobile/SKILL.md‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -15,24 +15,28 @@ Inspect the host and the affected code before launching processes:
1515

1616
- On macOS with Xcode, prefer one representative iOS Simulator when the change is cross-platform so the user can watch through serve-sim. Load and follow [`ios-debugger-agent`](../ios-debugger-agent/SKILL.md), and load [`ios-simulator-browser`](../ios-simulator-browser/SKILL.md) when live streaming is available.
1717
- On macOS, Linux, or Windows with the Android SDK, use one Android Emulator when Android is the affected surface or iOS tooling is unavailable.
18-
- When the change is platform-specific, test that platform. When neither platform is viable, report the missing SDK, emulator, or dev-client prerequisite rather than claiming verification.
18+
- When the change is platform-specific, test that platform. When neither platform is viable, report the missing SDK or emulator prerequisite rather than claiming verification. A missing development client is a build step, not a blocker.
1919

2020
Do not treat unavailable iOS tooling as a blocker when Android is a valid representative target.
2121

22-
## Choose the lightest valid launch path
22+
## Ensure a compatible native client
2323

24-
- For JavaScript, TypeScript, or asset-only changes, reuse a compatible installed development client and start Metro. Do not rebuild native code merely to load a new bundle.
25-
- For native source, native dependencies, entitlements, config plugins, or generated project changes, rebuild the affected platform.
26-
- Use `vp run ios:dev` or `vp run android:dev` only when an Expo clean prebuild is actually required; both commands regenerate the native project.
27-
- If the user requested no native rebuild and no compatible app is installed, reuse an existing compatible `.app` or `.apk` artifact when available. Otherwise report the missing dev client instead of silently rebuilding.
24+
Authorized mobile verification includes building and installing a development client. A missing, stale, or unknown native client is not a reason to skip verification or leave a PR in draft. Build and install it, then continue. Respect an explicit user instruction not to rebuild; otherwise do not ask for separate permission.
2825

29-
The development identity on both platforms is:
26+
Run this from the checkout being tested, on the machine that hosts the selected simulator or emulator. Select and boot one explicit iOS UDID or Android emulator serial first:
3027

31-
- App: `T3 Code Dev`
32-
- Bundle/package identifier: `com.t3tools.t3code.dev`
33-
- URL scheme: `t3code-dev`
28+
```bash
29+
node scripts/mobile-native-client.ts ensure ios <simulator-udid>
30+
node scripts/mobile-native-client.ts ensure android <emulator-serial>
31+
```
32+
33+
`ensure` compares the checkout's local Expo development fingerprint and the installed app's binary contents against the last successful build record. It reuses a matching client; otherwise it runs a clean prebuild, builds and installs the development app, and records the successful result. It does not start Metro. Start Metro below after it succeeds. On hosts with an `agent-job` requirement, run the entire `ensure` command through that queue.
34+
35+
For a read-only decision, use `check` in place of `ensure`. Exit 0 means compatible, 2 means build required, and 1 means an operational error. An app installed outside this helper is initially unknown and gets rebuilt once. Records are local to the simulator host under `~/.cache/t3code/native-clients` and work across checkouts. Do not copy records between machines or write them manually.
36+
37+
A JavaScript-only diff, bundle identifier, app version, or recent install date does not prove native compatibility. Always check the whole checkout. Expo fingerprints are computed locally with `APP_VARIANT=development`; no EAS credentials or cloud build are required. Generated `ios/` and `android/` directories are excluded by `.fingerprintignore`, so edit native source modules or config plugins rather than generated output.
3438

35-
Bundle or package presence proves the correct variant, not native compatibility. Reuse it only when the current changes did not alter its Expo SDK, native dependencies, config plugins, entitlements, generated project, or native source.
39+
The development identity is `T3 Code Dev`, bundle/package `com.t3tools.t3code.dev`, scheme `t3code-dev`. If a build fails, investigate the build error and fix the local prerequisites. Report the concrete failure if it cannot be resolved, not “no compatible client.”
3640

3741
## Start one disposable T3 environment
3842

@@ -98,21 +102,19 @@ Use `ios-debugger-agent` to select one UDID and set these XcodeBuildMCP session
98102
- Simulator ID: the selected UDID
99103
- Bundle ID: `com.t3tools.t3code.dev`
100104

101-
Check the installed client with:
105+
After `ensure` succeeds, open the Metro URL:
102106

103107
```bash
104-
xcrun simctl get_app_container <simulator-udid> com.t3tools.t3code.dev app
105108
xcrun simctl openurl <simulator-udid> <printed-dev-client-url>
106109
```
107110

108111
Accept the iOS confirmation prompt and dismiss the developer menu when it obscures the app.
109112

110113
### Android launch
111114

112-
Select one running emulator serial from `adb devices` and check the installed client:
115+
Use the emulator serial already checked by `ensure`:
113116

114117
```bash
115-
adb -s <emulator-serial> shell pm path com.t3tools.t3code.dev
116118
adb -s <emulator-serial> reverse tcp:<metro-port> tcp:<metro-port>
117119
adb -s <emulator-serial> shell am start -W \
118120
-a android.intent.action.VIEW \

‎AGENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,8 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
110110
- The server is event-sourced and its async flows emit typed receipts. Wait on receipts and worker drains, never on sleeps or polling. A test that needs a timeout to pass is wrong.
111111
- Upon request, user-visible frontend changes should get one integrated pass in a real client: `test-t3-app` for web, `test-t3-mobile` for mobile. The primary agent does this once after integrating. Subagents do not launch their own dev servers. Ask permission before doing computer use or spinning up browsers.
112112

113+
For authorized mobile verification, a missing or outdated native client is a build step, not a blocker. Run `node scripts/mobile-native-client.ts ensure <ios|android> <device-id>` on the simulator host before starting Metro. It checks the local Expo fingerprint and builds/installs when needed. See `test-t3-mobile` for the full workflow.
114+
113115
## Pull requests
114116

115117
- Never make a PR unless the developer explicitly asks you to do so.

‎apps/mobile/README.md‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,22 @@ repository-root `.env` or `.env.local`, not an `apps/mobile/.env` file. See
2222

2323
## Development
2424

25-
Start Metro for the dev client:
25+
For simulator/emulator development, select and boot a device, then ensure its native client matches
26+
this checkout before starting Metro:
27+
28+
```bash
29+
node ../../scripts/mobile-native-client.ts ensure ios <simulator-udid>
30+
# Or: node ../../scripts/mobile-native-client.ts ensure android <emulator-serial>
31+
vp run dev:client
32+
```
33+
34+
The helper compares a local Expo fingerprint and the installed binary with its last successful
35+
build record. It builds and installs missing, stale, or unverified clients and reuses matching ones.
36+
Use `check` instead of `ensure` for a read-only decision: exit 0 means compatible, 2 means a build is
37+
needed, and 1 means an operational error. Run it on the simulator host; no EAS login is required.
38+
An externally installed client is unverified until the helper builds it once.
39+
40+
Start Metro for an already verified dev client:
2641

2742
```bash
2843
vp run dev:client

‎knip.jsonc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
"vitest": { "entry": [".github/**/*.test.cjs"] },
1414
},
1515
"scripts": {
16-
// Knip loads its preprocessor through a CLI option, not a source import.
17-
"entry": ["knip-schemas.ts"],
16+
// Knip loads its preprocessor through a CLI option; native verification runs directly.
17+
"entry": ["knip-schemas.ts", "mobile-native-client.ts"],
1818
},
1919
"apps/server": {
2020
// Vite+ pack entries and the launcher used by installed background services.

0 commit comments

Comments
 (0)