Skip to content

Commit 22d9e8d

Browse files
committed
fix(metro): reject host delimiters and clarify launch URL help
1 parent 4f3cdd6 commit 22d9e8d

5 files changed

Lines changed: 34 additions & 8 deletions

File tree

‎packages/host-kit/src/runtime-transport-hints.test.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,3 +91,19 @@ test('server URLs retain mounts and normalize entries, default ports, and IPv6',
9191
),
9292
);
9393
});
94+
95+
test('rejects host delimiters before they become server URL components', () => {
96+
fc.assert(
97+
fc.property(
98+
fc.constantFrom('localhost', '127.0.0.1', 'metro.example.test'),
99+
fc.constantFrom('?', '/', '#', '\\', '@', ' ', '\n'),
100+
fc.integer({ min: 1, max: 65535 }),
101+
(host, delimiter, port) => {
102+
assert.throws(
103+
() => resolveRuntimeServerUrl({ metroHost: `${host}${delimiter}x`, metroPort: port }),
104+
(error: unknown) => error instanceof AppError && error.code === 'INVALID_ARGS',
105+
);
106+
},
107+
),
108+
);
109+
});

‎packages/host-kit/src/runtime-transport-hints.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ export function resolveRuntimeTransportHints(
1313
): ResolvedRuntimeTransport | undefined {
1414
if (!runtime) return undefined;
1515

16-
let host = trimRuntimeValue(runtime.metroHost);
16+
let host = normalizeMetroHost(runtime.metroHost);
1717
let port = normalizePort(runtime.metroPort);
1818
let scheme: 'http' | 'https' = 'http';
1919
const bundleUrl = trimRuntimeValue(runtime.bundleUrl);
@@ -68,6 +68,17 @@ export function resolveRuntimeServerUrl(runtime: SessionRuntimeHints | undefined
6868
return url;
6969
}
7070

71+
function normalizeMetroHost(value: string | undefined): string | undefined {
72+
const host = trimRuntimeValue(value);
73+
if (host && /[/\\?#@\s]/.test(host)) {
74+
throw new AppError(
75+
'INVALID_ARGS',
76+
`Invalid runtime Metro host: ${host}. Use a hostname or IP address.`,
77+
);
78+
}
79+
return host;
80+
}
81+
7182
function normalizePort(value: number | undefined): number | undefined {
7283
if (!Number.isInteger(value)) return undefined;
7384
if ((value as number) <= 0 || (value as number) > 65_535) return undefined;

‎src/commands/management/app.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,9 @@ const openCommandMetadata = defineFieldCommandMetadata(
7474
},
7575
),
7676
bundleUrl: stringField('Session-scoped bundle URL hint applied to the opened app.'),
77-
launchUrl: stringField('Session-scoped launch URL hint applied to the opened app.'),
77+
launchUrl: stringField(
78+
'Launch URL for the opened app; does not select the server used by metro reload.',
79+
),
7880
},
7981
);
8082

@@ -195,9 +197,9 @@ export const openCommandFacet = defineCommandFacet({
195197
text: {
196198
summary: 'Open an app, deep link or URL, save replays',
197199
cliDetail:
198-
'Use --platform to bind URL/deep-link opens to the target platform. For iOS simulator initial stdout/stderr, put --launch-console <path> on this open command, for example agent-device open "Agent Device Tester" --platform ios --launch-console artifacts/launch-console.log. Expo Go/dev-client shells accept host + URL, for example agent-device open "Expo Go" exp://127.0.0.1:8081 --platform ios. macOS also supports --surface app|frontmost-app|desktop|menubar. --metro-host/--metro-port/--bundle-url/--launch-url set this session\'s Metro/debug runtime hints as part of open itself (recorded as the session\'s dev-server binding and applied to bare React Native dev-server prefs; on an iOS simulator without --launch-url, an expo-dev-client whose single exp+<slug> scheme the open can confirm is launched through its expo-development-client URL instead, without writing unused React Native prefs; when the scheme check is inconclusive the plain launch is kept), so a fresh session has them before its first reload instead of needing a throwaway reload-first call just to seed hints; a later plain metro reload in the same session reuses whichever of these were set. A fresh open without these flags clears any leftover binding from a previous same-name session; close also clears it. On an iOS simulator, when --launch-url raises an "Open in <App>?" prompt that keeps open from seeing the app, open accepts it if the URL scheme belongs to the session app (data.launchConfirmation: "accepted"); if the scheme belongs to another installed app, the prompt stays on screen and open fails with details.reason launch_confirmation_foreign_app; if no single installed app owns the scheme, the prompt stays on screen and open returns as usual. The prompt is read whenever open cannot see the app afterwards, including on a slow host where the app\'s target discovery fails on its own deadline. When an accept leaves the app provably not running, open hands the same URL over once more and reads again; still not running, it fails with details.reason launch_confirmation_unanswered. A recognized prompt still visible after a failed accept also fails with this reason, even if the app is running behind it; answer it with alert accept or alert dismiss. A simulator openurl that CoreSimulator never answers fails within 20s with details.reason ios-simulator-openurl-timeout. Only the English prompt title with Cancel and Open buttons is recognized, so on a Simulator set to another language the prompt stays on screen. A prompt that appears after open has already seen the app is not answered; use alert accept. A device another session is holding refuses at once; add --wait <ms> to block up to that budget for it and only then fail with DEVICE_IN_USE naming the owning session.',
200+
'Use --platform to bind URL/deep-link opens to the target platform. For iOS simulator initial stdout/stderr, put --launch-console <path> on this open command, for example agent-device open "Agent Device Tester" --platform ios --launch-console artifacts/launch-console.log. Expo Go/dev-client shells accept host + URL, for example agent-device open "Expo Go" exp://127.0.0.1:8081 --platform ios. macOS also supports --surface app|frontmost-app|desktop|menubar. --metro-host/--metro-port/--bundle-url choose the app\'s Metro server and save that address for later metro reload calls in the same session. A fresh open without Metro hints clears an older same-name binding; close also clears it. --launch-url supplies the app\'s launch URL; it does not select the reload server. On an iOS simulator without --launch-url, open connects a detected Expo development client through its expo-development-client URL. The app must declare a single exp+<slug> scheme that no other installed app owns. If detection is inconclusive, the app opens normally. Bare React Native apps receive their server settings before launch. On an iOS simulator, when --launch-url raises an "Open in <App>?" prompt that keeps open from seeing the app, open accepts it if the URL scheme belongs to the session app (data.launchConfirmation: "accepted"); if the scheme belongs to another installed app, the prompt stays on screen and open fails with details.reason launch_confirmation_foreign_app; if no single installed app owns the scheme, the prompt stays on screen and open returns as usual. The prompt is read whenever open cannot see the app afterwards, including on a slow host where the app\'s target discovery fails on its own deadline. When an accept leaves the app provably not running, open hands the same URL over once more and reads again; still not running, it fails with details.reason launch_confirmation_unanswered. A recognized prompt still visible after a failed accept also fails with this reason, even if the app is running behind it; answer it with alert accept or alert dismiss. A simulator openurl that CoreSimulator never answers fails within 20s with details.reason ios-simulator-openurl-timeout. Only the English prompt title with Cancel and Open buttons is recognized, so on a Simulator set to another language the prompt stays on screen. A prompt that appears after open has already seen the app is not answered; use alert accept. A device another session is holding refuses at once; add --wait <ms> to block up to that budget for it and only then fail with DEVICE_IN_USE naming the owning session.',
199201
mcpDetail:
200-
"Metro and debug runtime hints given here are recorded as the session's dev-server binding, so a later reload reuses them; a fresh open without them clears any binding left by a previous same-name session.",
202+
"metroHost, metroPort, and bundleUrl choose the app's Metro server and save its address for later reloads. launchUrl selects the app's launch URL and does not select the reload server. A fresh open without Metro hints clears an older same-name binding; close also clears it.",
201203
},
202204
metadata: openCommandMetadata,
203205
run: (client, input) => client.apps.open(toAppOpenOptions(input)),

‎src/commands/schema/cli-help-command-usage.test.ts‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -379,9 +379,6 @@ test('open command usage documents metro session-hint setter flags', async () =>
379379
assert.match(help, /--metro-port <port>/);
380380
assert.match(help, /--bundle-url <url>/);
381381
assert.match(help, /--launch-url <url>/);
382-
assert.match(help, /before its first reload/);
383-
assert.match(help, /plain metro reload in the same session reuses/);
384-
assert.match(help, /clears any leftover binding/);
385382
});
386383

387384
test('command usage shows no command flags when unsupported', async () => {

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -967,7 +967,7 @@ agent-device open "React Navigation Example" --platform ios --device "iPhone 17
967967
```
968968
969969
- Use different simulators and sessions for each worktree. One simulator cannot run two copies of the same bundle id at the same time.
970-
- On iOS simulators, `open` writes React Native's per-simulator debug server settings before launching, so `rn-a` can use port `8081` while `rn-b` uses port `8082`. An expo-dev-client ignores those settings, so `open` skips writing them and, when the app registers a single `exp+<slug>` URL scheme, `open` launches it through `exp+<slug>://expo-development-client/?url=<server>` instead of a plain launch. An explicit `--launch-url`, or a scheme check that cannot confirm a single `exp+<slug>` scheme, keeps the plain launch, and a dev build that boots straight into its embedded bundle still needs a native rebuild. Each session also remembers its dev server for a flagless `metro reload --session <name>`; see [Metro reload](#metro-reload).
970+
- On iOS simulators, `open` writes React Native's per-simulator debug server settings before launching, so `rn-a` can use port `8081` while `rn-b` uses port `8082`. An expo-dev-client ignores those settings, so `open` skips writing them and, when the app registers a single `exp+<slug>` URL scheme, `open` launches it through `exp+<slug>://expo-development-client/?url=<server>` instead of a plain launch. `--launch-url` takes precedence over automatic Expo connection and does not choose the server used by `metro reload`. If the scheme check is inconclusive, the app opens normally. A dev build that boots straight into its embedded bundle still needs a native rebuild. Each session also remembers its dev server for a flagless `metro reload --session <name>`; see [Metro reload](#metro-reload).
971971
- This covers JavaScript and Metro-resolved workspace changes. Rebuild/reinstall the app when native code, native dependencies, bundle identifiers, entitlements, or generated native project files change.
972972
- Close every manually opened session when done:
973973

0 commit comments

Comments
 (0)