feat: add ios runner prepare command

thymikee · thymikee · commit 7c065bcacbda · 2026-06-02T09:55:17.000-07:00
diff --git a/src/client-types.ts b/src/client-types.ts
@@ -478,6 +478,11 @@ export type ReactNativeCommandOptions = ClientCommandBaseOptions & {
   action: 'dismiss-overlay';
 };
 
+export type PrepareCommandOptions = ClientCommandBaseOptions & {
+  action: 'ios-runner';
+  timeoutMs?: number;
+};
+
 export type AgentDeviceCommandClient = {
   wait: (options: WaitCommandOptions) => Promise<WaitCommandResult>;
   alert: (options?: AlertCommandOptions) => Promise<AlertCommandResult>;
@@ -489,6 +494,7 @@ export type AgentDeviceCommandClient = {
   keyboard: (options?: KeyboardCommandOptions) => Promise<KeyboardCommandResult>;
   clipboard: (options: ClipboardCommandOptions) => Promise<ClipboardCommandResult>;
   reactNative: (options: ReactNativeCommandOptions) => Promise<CommandRequestResult>;
+  prepare: (options: PrepareCommandOptions) => Promise<CommandRequestResult>;
 };
 
 type SelectorSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'scope' | 'raw'>;
diff --git a/src/client.ts b/src/client.ts
@@ -96,6 +96,7 @@ export function createAgentDeviceClient(
       keyboard: async (options = {}) => await executeCommand('keyboard', options),
       clipboard: async (options) => await executeCommand('clipboard', options),
       reactNative: async (options) => await executeCommand('react-native', options),
+      prepare: async (options) => await executeCommand('prepare', options),
     },
     devices: {
       list: async (options = {}) => {
diff --git a/src/command-catalog.ts b/src/command-catalog.ts
@@ -26,6 +26,7 @@ export const PUBLIC_COMMANDS = {
   network: 'network',
   open: 'open',
   perf: 'perf',
+  prepare: 'prepare',
   press: 'press',
   push: 'push',
   record: 'record',
@@ -141,6 +142,7 @@ const CAPABILITY_EXEMPT_CLI_COMMANDS = commandSet(
   LOCAL_CLI_COMMANDS.reactDevtools,
   LOCAL_CLI_COMMANDS.session,
   PUBLIC_COMMANDS.appState,
+  PUBLIC_COMMANDS.prepare,
   PUBLIC_COMMANDS.batch,
   PUBLIC_COMMANDS.devices,
   PUBLIC_COMMANDS.gesture,
@@ -156,6 +158,7 @@ export const DAEMON_COMMAND_GROUPS = {
     PUBLIC_COMMANDS.apps,
   ),
   state: commandSet(PUBLIC_COMMANDS.boot, PUBLIC_COMMANDS.appState),
+  prepare: commandSet(PUBLIC_COMMANDS.prepare),
   observability: commandSet(PUBLIC_COMMANDS.perf, PUBLIC_COMMANDS.logs, PUBLIC_COMMANDS.network),
   replay: commandSet(PUBLIC_COMMANDS.replay, PUBLIC_COMMANDS.test),
   snapshot: commandSet(
@@ -249,6 +252,7 @@ export const DAEMON_COMMAND_GROUPS = {
     PUBLIC_COMMANDS.network,
     PUBLIC_COMMANDS.open,
     PUBLIC_COMMANDS.perf,
+    PUBLIC_COMMANDS.prepare,
     PUBLIC_COMMANDS.push,
     PUBLIC_COMMANDS.reinstall,
     PUBLIC_COMMANDS.replay,
diff --git a/src/commands/cli-grammar/apps.ts b/src/commands/cli-grammar/apps.ts
@@ -29,6 +29,11 @@ export const appCliReaders = {
     ...commonInputFromFlags(flags),
     headless: flags.headless,
   }),
+  prepare: (positionals, flags) => ({
+    ...commonInputFromFlags(flags),
+    action: requiredString(positionals[0], 'prepare requires subcommand'),
+    timeoutMs: flags.timeoutMs,
+  }),
   open: (positionals, flags) => ({
     ...commonInputFromFlags(flags),
     app: positionals[0],
@@ -72,6 +77,9 @@ export const appCliReaders = {
 export const appDaemonWriters = {
   devices: direct(PUBLIC_COMMANDS.devices),
   boot: direct(PUBLIC_COMMANDS.boot),
+  prepare: direct(PUBLIC_COMMANDS.prepare, (input) => [
+    requiredDaemonString(input.action, 'prepare requires subcommand'),
+  ]),
   apps: direct(PUBLIC_COMMANDS.apps),
   open: direct(PUBLIC_COMMANDS.open, openPositionals),
   close: direct(PUBLIC_COMMANDS.close, (input) => optionalString(input.app)),
diff --git a/src/commands/cli-output.ts b/src/commands/cli-output.ts
@@ -82,6 +82,7 @@ const cliOutputFormatters: Partial<Record<CommandName, CliOutputFormatter>> = {
   is: resultOutput(isCliOutput),
   find: resultOutput(findCliOutput),
   perf: resultOutput(perfCliOutput),
+  prepare: messageOutput,
   logs: resultOutput(logsCliOutput),
   network: resultOutput(networkCliOutput),
   record: resultOutput(recordCliOutput),
diff --git a/src/commands/client-command-contracts.ts b/src/commands/client-command-contracts.ts
@@ -62,6 +62,7 @@ export const clientCommandDefinitions = [
   defineExecutableCommand(metadata('react-native'), (client, input) =>
     client.command.reactNative(input),
   ),
+  defineExecutableCommand(metadata('prepare'), (client, input) => client.command.prepare(input)),
   defineExecutableCommand(metadata('replay'), (client, input) => client.replay.run(input)),
   defineExecutableCommand(metadata('test'), (client, input) => client.replay.test(input)),
   defineExecutableCommand(metadata('perf'), (client, input) => client.observability.perf(input)),
diff --git a/src/commands/client-command-metadata.ts b/src/commands/client-command-metadata.ts
@@ -36,12 +36,17 @@ const NETWORK_INCLUDE_VALUES = ['summary', 'headers', 'body', 'all'] as const;
 const START_STOP_VALUES = ['start', 'stop'] as const;
 const REACT_NATIVE_ACTION_VALUES = ['dismiss-overlay'] as const;
 const METRO_ACTION_VALUES = ['prepare', 'reload'] as const;
+const PREPARE_ACTION_VALUES = ['ios-runner'] as const;
 
 export const clientCommandMetadata = [
   defineClientCommandMetadata('devices', {}),
   defineClientCommandMetadata('boot', {
     headless: booleanField('Boot without showing simulator UI when supported.'),
   }),
+  defineClientCommandMetadata('prepare', {
+    action: requiredField(enumField(PREPARE_ACTION_VALUES)),
+    timeoutMs: integerField('Maximum wall-clock time for the prepare command.'),
+  }),
   defineClientCommandMetadata('apps', {
     appsFilter: enumField(['user-installed', 'all']),
   }),
diff --git a/src/commands/command-descriptions.ts b/src/commands/command-descriptions.ts
@@ -4,6 +4,7 @@ const COMMAND_DESCRIPTIONS = {
   apps: 'List installed apps.',
   session: 'List active sessions.',
   open: 'Open an app, deep link, URL, or platform surface.',
+  prepare: 'Prepare platform helper infrastructure.',
   close: 'Close an app or end the active session.',
   install: 'Install an app binary.',
   reinstall: 'Reinstall an app binary.',
diff --git a/src/daemon-client.ts b/src/daemon-client.ts
@@ -194,7 +194,10 @@ export async function sendToDaemon(req: Omit<DaemonRequest, 'token'>): Promise<D
 
 function resolveDaemonRequestTimeoutMs(req: Omit<DaemonRequest, 'token'>): number | undefined {
   if (req.command === PUBLIC_COMMANDS.test) return undefined;
-  if (req.command === PUBLIC_COMMANDS.replay && typeof req.flags?.timeoutMs === 'number') {
+  if (
+    (req.command === PUBLIC_COMMANDS.replay || req.command === PUBLIC_COMMANDS.prepare) &&
+    typeof req.flags?.timeoutMs === 'number'
+  ) {
     return req.flags.timeoutMs;
   }
   return REQUEST_TIMEOUT_MS;
diff --git a/src/daemon/handlers/__tests__/session.test.ts b/src/daemon/handlers/__tests__/session.test.ts
@@ -18,6 +18,7 @@ vi.mock('../../../platforms/ios/runner-client.ts', async (importOriginal) => {
   return {
     ...actual,
     prewarmIosRunnerSession: vi.fn(),
+    runIosRunnerCommand: vi.fn(async () => ({ currentUptimeMs: 42 })),
     stopIosRunnerSession: vi.fn(async () => {}),
   };
 });
@@ -96,6 +97,7 @@ import { ensureDeviceReady } from '../../device-ready.ts';
 import { applyRuntimeHintsToApp, clearRuntimeHintsFromApp } from '../../runtime-hints.ts';
 import {
   prewarmIosRunnerSession,
+  runIosRunnerCommand,
   stopIosRunnerSession,
 } from '../../../platforms/ios/runner-client.ts';
 import { runMacOsAlertAction } from '../../../platforms/ios/macos-helper.ts';
@@ -118,6 +120,7 @@ const mockEnsureDeviceReady = vi.mocked(ensureDeviceReady);
 const mockApplyRuntimeHints = vi.mocked(applyRuntimeHintsToApp);
 const mockClearRuntimeHints = vi.mocked(clearRuntimeHintsFromApp);
 const mockPrewarmIosRunnerSession = vi.mocked(prewarmIosRunnerSession);
+const mockRunIosRunnerCommand = vi.mocked(runIosRunnerCommand);
 const mockStopIosRunner = vi.mocked(stopIosRunnerSession);
 const mockDismissMacOsAlert = vi.mocked(runMacOsAlertAction);
 const mockSettleSimulator = vi.mocked(settleIosSimulator);
@@ -148,6 +151,8 @@ beforeEach(() => {
   mockClearRuntimeHints.mockReset();
   mockClearRuntimeHints.mockResolvedValue(undefined);
   mockPrewarmIosRunnerSession.mockReset();
+  mockRunIosRunnerCommand.mockReset();
+  mockRunIosRunnerCommand.mockResolvedValue({ currentUptimeMs: 42 });
   mockStopIosRunner.mockReset();
   mockStopIosRunner.mockResolvedValue(undefined);
   mockDismissMacOsAlert.mockReset();
@@ -2094,6 +2099,118 @@ test('open iOS URL without app bundle id skips runner prewarm', async () => {
   expect(mockPrewarmIosRunnerSession).not.toHaveBeenCalled();
 });
 
+test('prepare ios-runner starts the XCTest runner on an explicit iOS selector', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'prepare-ios-runner';
+  mockResolveTargetDevice.mockResolvedValue({
+    platform: 'ios',
+    id: 'sim-1',
+    name: 'iPhone 17 Pro',
+    kind: 'simulator',
+    booted: true,
+  });
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'prepare',
+      positionals: ['ios-runner'],
+      flags: { platform: 'ios', udid: 'sim-1', timeoutMs: 240000 },
+      meta: { requestId: 'prepare-request' },
+    },
+    sessionName,
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response).toBeTruthy();
+  expect(response?.ok).toBe(true);
+  expect(mockEnsureDeviceReady).toHaveBeenCalledWith(
+    expect.objectContaining({ platform: 'ios', id: 'sim-1' }),
+  );
+  expect(mockRunIosRunnerCommand).toHaveBeenCalledTimes(1);
+  expect(mockRunIosRunnerCommand).toHaveBeenCalledWith(
+    expect.objectContaining({ platform: 'ios', id: 'sim-1' }),
+    { command: 'uptime' },
+    expect.objectContaining({
+      logPath: expect.stringMatching(/daemon\.log$/),
+      requestId: 'prepare-request',
+    }),
+  );
+  expect((response as any).data).toMatchObject({
+    action: 'ios-runner',
+    platform: 'ios',
+    deviceId: 'sim-1',
+    deviceName: 'iPhone 17 Pro',
+    kind: 'simulator',
+    runner: { currentUptimeMs: 42 },
+    message: 'Prepared iOS runner: iPhone 17 Pro',
+  });
+  expect(sessionStore.get(sessionName)).toBeUndefined();
+});
+
+test('prepare ios-runner rejects non-iOS devices', async () => {
+  const sessionStore = makeSessionStore();
+  mockResolveTargetDevice.mockResolvedValue({
+    platform: 'android',
+    id: 'emulator-5554',
+    name: 'Pixel 9 Pro XL',
+    kind: 'emulator',
+    booted: true,
+  });
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'prepare-android',
+      command: 'prepare',
+      positionals: ['ios-runner'],
+      flags: { platform: 'android', serial: 'emulator-5554' },
+    },
+    sessionName: 'prepare-android',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response).toBeTruthy();
+  expect(response?.ok).toBe(false);
+  if (response && !response.ok) {
+    expect(response.error.code).toBe('UNSUPPORTED_OPERATION');
+    expect(response.error.message).toBe('prepare ios-runner is only supported on iOS');
+  }
+  expect(mockRunIosRunnerCommand).not.toHaveBeenCalled();
+});
+
+test('prepare requires the ios-runner subcommand', async () => {
+  const sessionStore = makeSessionStore();
+
+  const response = await handleSessionCommands({
+    req: {
+      token: 't',
+      session: 'prepare-invalid',
+      command: 'prepare',
+      positionals: [],
+      flags: { platform: 'ios' },
+    },
+    sessionName: 'prepare-invalid',
+    logPath: path.join(os.tmpdir(), 'daemon.log'),
+    sessionStore,
+    invoke: noopInvoke,
+  });
+
+  expect(response).toBeTruthy();
+  expect(response?.ok).toBe(false);
+  if (response && !response.ok) {
+    expect(response.error.code).toBe('INVALID_ARGS');
+    expect(response.error.message).toBe('prepare requires a subcommand: ios-runner');
+  }
+  expect(mockResolveTargetDevice).not.toHaveBeenCalled();
+  expect(mockRunIosRunnerCommand).not.toHaveBeenCalled();
+});
+
 test('open web URL on iOS device session without active app falls back to Safari', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-device-session';
diff --git a/src/daemon/handlers/session.ts b/src/daemon/handlers/session.ts
@@ -7,6 +7,7 @@ import {
 } from '../../command-catalog.ts';
 import { resolvePayloadInput } from '../../utils/payload-input.ts';
 import type { AndroidAdbExecutor } from '../../platforms/android/adb-executor.ts';
+import { runIosRunnerCommand } from '../../platforms/ios/runner-client.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
 import { normalizePlatformSelector } from '../../utils/device.ts';
 import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
@@ -56,10 +57,81 @@ export const SESSION_COMMAND_HANDLERS = {
   [PUBLIC_COMMANDS.push]: true,
   [PUBLIC_COMMANDS.triggerAppEvent]: true,
   [PUBLIC_COMMANDS.open]: true,
+  [PUBLIC_COMMANDS.prepare]: true,
   [PUBLIC_COMMANDS.batch]: true,
   [PUBLIC_COMMANDS.close]: true,
 } as const satisfies Record<string, true>;
 
+async function handlePrepareCommand(params: {
+  req: DaemonRequest;
+  sessionName: string;
+  logPath: string;
+  sessionStore: SessionStore;
+}): Promise<DaemonResponse> {
+  const { req, sessionName, logPath, sessionStore } = params;
+  const action = req.positionals?.[0] ?? '';
+  if (action !== 'ios-runner') {
+    return errorResponse('INVALID_ARGS', 'prepare requires a subcommand: ios-runner');
+  }
+
+  const session = sessionStore.get(sessionName);
+  const flags = req.flags ?? {};
+  const guard = requireSessionOrExplicitSelector(PUBLIC_COMMANDS.prepare, session, flags);
+  if (guard) return guard;
+
+  const device = await resolveCommandDevice({
+    session,
+    flags,
+    ensureReady: true,
+  });
+  if (device.platform !== 'ios') {
+    return errorResponse('UNSUPPORTED_OPERATION', 'prepare ios-runner is only supported on iOS');
+  }
+
+  const startedAtMs = Date.now();
+  const result = await runIosRunnerCommand(
+    device,
+    { command: 'uptime' },
+    buildPrepareIosRunnerOptions(req, session, logPath),
+  );
+  const durationMs = Math.max(0, Date.now() - startedAtMs);
+  return {
+    ok: true,
+    data: prepareIosRunnerResponseData(action, device, durationMs, result),
+  };
+}
+
+function buildPrepareIosRunnerOptions(
+  req: DaemonRequest,
+  session: SessionState | undefined,
+  logPath: string,
+): Parameters<typeof runIosRunnerCommand>[2] {
+  return {
+    verbose: req.flags?.verbose,
+    logPath,
+    traceLogPath: session?.trace?.outPath,
+    requestId: req.meta?.requestId,
+  };
+}
+
+function prepareIosRunnerResponseData(
+  action: string,
+  device: DeviceInfo,
+  durationMs: number,
+  runner: Awaited<ReturnType<typeof runIosRunnerCommand>>,
+): Record<string, unknown> {
+  return {
+    action,
+    platform: device.platform,
+    deviceId: device.id,
+    deviceName: device.name,
+    kind: device.kind,
+    durationMs,
+    runner,
+    message: `Prepared iOS runner: ${device.name}`,
+  };
+}
+
 // fallow-ignore-next-line complexity
 async function runSessionOrSelectorDispatch(params: {
   req: DaemonRequest;
@@ -253,6 +325,15 @@ export async function handleSessionCommands(params: {
     });
   }
 
+  if (req.command === PUBLIC_COMMANDS.prepare) {
+    return await handlePrepareCommand({
+      req,
+      sessionName,
+      logPath,
+      sessionStore,
+    });
+  }
+
   if (req.command === PUBLIC_COMMANDS.install || req.command === PUBLIC_COMMANDS.reinstall) {
     return await handleAppDeployCommand({
       req,
diff --git a/src/utils/__tests__/args.test.ts b/src/utils/__tests__/args.test.ts
diff --git a/src/utils/cli-command-overrides.ts b/src/utils/cli-command-overrides.ts
diff --git a/src/utils/cli-flags.ts b/src/utils/cli-flags.ts
diff --git a/src/utils/cli-help.ts b/src/utils/cli-help.ts
