feat: add iOS runner prepare command (#673)

* feat: add ios runner prepare command

* fix: shorten snapshot request timeout

* fix: refine prepare and snapshot timeouts

* test: cover prepare ios runner provider scenario

Author: thymikee

src/client-types.ts

@@ -306,6 +306,7 @@ export type CaptureSnapshotOptions = AgentDeviceRequestOverrides &
     scope?: string;
     raw?: boolean;
     forceFull?: boolean;
+    timeoutMs?: number;
   };
 
 export type CaptureSnapshotResult = {
@@ -478,6 +479,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 +495,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'>;

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 = {}) => {

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',
@@ -129,6 +130,7 @@ const MCP_UNEXPOSED_CLI_COMMANDS = commandSet(
   LOCAL_CLI_COMMANDS.disconnect,
   LOCAL_CLI_COMMANDS.mcp,
   LOCAL_CLI_COMMANDS.reactDevtools,
+  PUBLIC_COMMANDS.prepare,
 );
 
 const CAPABILITY_EXEMPT_CLI_COMMANDS = commandSet(
@@ -141,6 +143,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,
@@ -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,

src/commands/__tests__/command-surface-metadata.test.ts

@@ -19,3 +19,7 @@ test('MCP exposed command names have metadata and executable command definitions
     assert.ok(executableNames.has(name), `${name} must have an executable command definition`);
   }
 });
+
+test('CI-only prepare command stays out of MCP tool surface', () => {
+  assert.equal(listMcpExposedCommandNames().includes('prepare'), false);
+});

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)),

src/commands/cli-grammar/capture.ts

@@ -39,6 +39,7 @@ export const captureCliReaders = {
     scope: flags.snapshotScope,
     raw: flags.snapshotRaw,
     forceFull: flags.snapshotForceFull,
+    timeoutMs: flags.timeoutMs,
   }),
   screenshot: (positionals, flags) => ({
     ...commonInputFromFlags(flags),

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),

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)),

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']),
   }),
@@ -100,6 +105,7 @@ export const clientCommandMetadata = [
     scope: stringField(),
     raw: booleanField(),
     forceFull: booleanField(),
+    timeoutMs: integerField('Maximum wall-clock time for the snapshot command.'),
   }),
   defineClientCommandMetadata('screenshot', {
     path: stringField('Output path.'),

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.',