[build-tools] Let serve-sim start the iOS Simulator for web preview

.changeset/serve-sim-pr-4601.md

@@ -0,0 +1,5 @@
+---
+'@expo/build-tools': minor
+---
+
+Let serve-sim start the iOS Simulator for web-preview sessions.

packages/build-tools/resources/egress-guard/README.md

@@ -71,6 +71,17 @@ by a coverage report from `lsof`, listing any process without the library. Both
 `packages/worker/package.sh` for the iOS worker tarball and by the
 `test-egress-guard` EAS workflow, not committed.
 
+For serve-sim-owned iOS session startup, build-tools passes the guard through
+`SERVE_SIM_ADDITIONAL_DYLIBS` and its configuration and proxy variables through
+inherited `SIMCTL_CHILD_` variables. It shuts down an already booted selected
+device so every process inherits the guard. Serve-sim boots that device while
+build-tools prepares the app. After serve-sim's control endpoint is available,
+build-tools runs the packaged guard self-check before requesting installation
+and launch through the authenticated host API. Preview readiness and application
+startup both complete before reporting the remote session live. Build-tools keeps
+the event relay and egress cleanup without rewriting launchd's dylib list after
+serve-sim adds its capability loader.
+
 Failure semantics: a missing library, a failed `launchctl setenv`, or a failed
 self-check fails the session, since a `--egress local` session without the
 guard would silently leak. Only an unwritable event log is a warning, because

packages/build-tools/src/steps/functions/__tests__/remoteSessionLocalEgress.test.ts

@@ -29,8 +29,8 @@ jest.mock('../../../utils/processes');
 jest.mock('../../../utils/turtleFetch');
 jest.mock('../../utils/deviceSessionHost');
 jest.mock('../../utils/agentDeviceArtifacts');
-// The agent-device session step boots the Simulator itself; this test covers local egress.
 jest.mock('../startIosSimulator', () => ({
+  ...jest.requireActual('../startIosSimulator'),
   bootIosSimulatorAsync: jest
     .fn()
     .mockResolvedValue({ deviceIdentifier: 'sim', udid: 'sim', displayName: 'iPhone' }),

packages/build-tools/src/steps/functions/__tests__/startWebPreviewRemoteSession.test.ts

@@ -3,6 +3,7 @@ import { BuildRuntimePlatform, type BuildStepContext, type BuildStepEnv } from '
 
 import { createGlobalContextMock } from '../../../__tests__/utils/context';
 import { type CustomBuildContext } from '../../../customBuildContext';
+import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
 import { startDeviceSessionHostAsync } from '../../utils/deviceSessionHost';
 import {
   getDeviceRunSessionIdOrThrow,
@@ -14,6 +15,22 @@ import {
 import { createStartWebPreviewRemoteSessionBuildFunction } from '../startWebPreviewRemoteSession';
 
 jest.mock('../../utils/deviceSessionHost');
+jest.mock('../../../utils/IosSimulatorUtils', () => ({
+  IosSimulatorUtils: {
+    resolveUdidAsync: jest.fn().mockResolvedValue('selected-ios-udid'),
+    getAvailableDevicesAsync: jest
+      .fn()
+      .mockResolvedValue([{ name: 'iPhone 17', udid: 'selected-ios-udid' }]),
+  },
+}));
+jest.mock('../../utils/iosAppArtifact', () => ({
+  ...jest.requireActual('../../utils/iosAppArtifact'),
+  readIosApplicationIdentifierAsync: jest.fn().mockResolvedValue('dev.example.app'),
+}));
+jest.mock('../../utils/localEgressGuard', () => ({
+  resolveLocalEgressServeSimBootEnvironmentAsync: jest.fn().mockResolvedValue(null),
+}));
+
 jest.mock('../../utils/remoteDeviceRunSession', () => ({
   ...jest.requireActual('../../utils/remoteDeviceRunSession'),
   getDeviceRunSessionIdOrThrow: jest.fn(),
@@ -115,14 +132,22 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
     [BuildRuntimePlatform.DARWIN, true],
     [BuildRuntimePlatform.LINUX, false],
   ])('starts the web preview for %s', async (runtimePlatform, selectsXcode) => {
-    await runAsync(runtimePlatform);
+    await runAsync(runtimePlatform, selectsXcode ? { boot_simulator: { value: true } } : {});
 
     expect(selectXcodeDeveloperDirectoryAsync).toHaveBeenCalledTimes(selectsXcode ? 1 : 0);
     expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(ctx, {
       runtimePlatform,
       env,
       logger,
       timeoutMs: 60_000,
+      signal: undefined,
+      ...(selectsXcode
+        ? {
+            iosSimulatorUdid: 'SELECTED-IOS-UDID',
+            installAppPath: undefined,
+            bootEnv: undefined,
+          }
+        : {}),
       packageVersion: '1.2.3',
       launchAppIdentifier: undefined,
       launchArgs: [],
@@ -160,6 +185,9 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
       'launch_app_identifier',
       'launch_args',
       'open_url',
+      'boot_simulator',
+      'device_identifier',
+      'install_app_path',
       'network_capture',
       'network_capture_fields',
       'package_version',
@@ -188,6 +216,28 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
     );
   });
 
+  it('hands the downloaded app and selected device to serve-sim with initial launch options', async () => {
+    await runAsync(BuildRuntimePlatform.DARWIN, {
+      device_identifier: { value: 'chosen-device' },
+      install_app_path: { value: '/tmp/App.app' },
+      launch_args: { value: ['--literal', 'value with spaces'] },
+      open_url: { value: 'example://home' },
+    });
+    expect(
+      jest.mocked(selectXcodeDeveloperDirectoryAsync).mock.invocationCallOrder[0]
+    ).toBeLessThan(jest.mocked(IosSimulatorUtils.resolveUdidAsync).mock.invocationCallOrder[0]);
+    expect(startDeviceSessionHostAsync).toHaveBeenCalledWith(
+      ctx,
+      expect.objectContaining({
+        iosSimulatorUdid: 'SELECTED-IOS-UDID',
+        installAppPath: '/tmp/App.app',
+        launchAppIdentifier: 'dev.example.app',
+        launchArgs: ['--literal', 'value with spaces'],
+        openUrl: 'example://home',
+      })
+    );
+  });
+
   it('hands network capture to the session host', async () => {
     await runAsync(BuildRuntimePlatform.DARWIN, {
       network_capture: { value: true },

packages/build-tools/src/steps/functions/startLocalEgress.ts

@@ -76,11 +76,11 @@ function awaitLocalEgressAcquisitionAsync<T>(
 
 /**
  * Points the device host's system HTTP(S) proxy at the EAS CLI's egress client.
- * Must run before `eas/start_ios_simulator`: the simulator reads the system proxy
- * at boot. Once a simulator boots, `eas/start_ios_simulator` also sets proxy
- * environment variables inside it for clients that read them (gRPC, libcurl)
- * and installs the local egress guard, which refuses connections that ignore
- * both. On Linux it starts the Android emulator relay and fence instead; see
+ * Must run before iOS simulator startup: the simulator reads the system proxy
+ * at boot. Startup supplies proxy variables for gRPC/libcurl and the guard that
+ * refuses connections bypassing the proxy. Serve-sim-owned startup passes this
+ * boot configuration to serve-sim.
+ * On Linux it starts the Android emulator relay and fence instead; see
  * androidLocalEgress.ts. The shared session cleanup releases the resources
  * started here when the session ends, with a job finalizer as a fallback.
  */

packages/build-tools/src/steps/functions/startWebPreviewRemoteSession.ts

@@ -7,6 +7,7 @@ import {
 
 import { CustomBuildContext } from '../../customBuildContext';
 import { startDeviceSessionHostAsync } from '../utils/deviceSessionHost';
+import { resolveIosSessionStartupAsync } from '../utils/iosSimulatorSession';
 import {
   createNetworkCaptureInputProviders,
   parseNetworkCaptureInputs,
@@ -16,11 +17,11 @@ import {
   withLocalEgressSession,
 } from '../utils/localEgressSession';
 import {
+  createIosSessionStartupInputProviders,
   createServeSimLaunchInputProviders,
   describeServeSimLaunch,
   getDeviceRunSessionIdOrThrow,
   getNgrokTunnelDomainOrThrow,
-  parseServeSimLaunchInputs,
   selectXcodeDeveloperDirectoryAsync,
   waitForDeviceRunSessionStoppedAsync,
 } from '../utils/remoteDeviceRunSession';
@@ -37,6 +38,7 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
     __metricsId: 'eas/start_serve_sim_remote_session',
     inputProviders: [
       ...createServeSimLaunchInputProviders(),
+      ...createIosSessionStartupInputProviders(),
       ...createNetworkCaptureInputProviders(),
       BuildStepInput.createProvider({
         id: 'package_version',
@@ -55,14 +57,21 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
       const maxDurationSeconds = inputs.max_duration_seconds?.value as number | undefined;
       const packageVersion = inputs.package_version?.value as string | undefined;
       const { runtimePlatform } = global;
-      const launch = parseServeSimLaunchInputs(
-        {
-          launchAppIdentifier: inputs.launch_app_identifier?.value as string | undefined,
-          launchArgs: inputs.launch_args?.value,
-          openUrl: inputs.open_url?.value as string | undefined,
-        },
-        { runtimePlatform }
-      );
+      if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
+        await selectXcodeDeveloperDirectoryAsync({ env, logger });
+      }
+      const { launch, iosStartup } = await resolveIosSessionStartupAsync({
+        runtimePlatform,
+        bootSimulator: inputs.boot_simulator?.value as boolean | undefined,
+        deviceIdentifier: inputs.device_identifier?.value as string | undefined,
+        installAppPath: inputs.install_app_path?.value as string | undefined,
+        launchAppIdentifier: inputs.launch_app_identifier?.value,
+        launchArgs: inputs.launch_args?.value,
+        openUrl: inputs.open_url?.value,
+        env,
+        logger,
+        signal,
+      });
       const { networkCapture, networkCaptureFields } = parseNetworkCaptureInputs(
         {
           networkCapture: inputs.network_capture?.value,
@@ -77,15 +86,13 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
         logger.info(launchDescription);
       }
 
-      if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
-        await selectXcodeDeveloperDirectoryAsync({ env, logger });
-      }
-
       const sessionHost = await startDeviceSessionHostAsync(ctx, {
+        ...iosStartup,
         runtimePlatform,
         env,
         logger,
         timeoutMs: STARTUP_TIMEOUT_MS,
+        signal,
         packageVersion,
         launchAppIdentifier: launch.launchAppIdentifier,
         launchArgs: launch.launchArgs,