ios_boot_simulator

Instructions

Implementation Reference

• src/tools/ios.ts:330-365 (handler)

  Handler function that boots the iOS simulator using xcrun simctl boot. Includes platform check, input validation with Zod schema, UDID format validation, handles already booted case (exit code 164), and returns structured response.

  handler: async (args: any) => {
    checkMacOS();
  
    const validation = IosSimulatorActionSchema.safeParse(args);
    if (!validation.success) {
      throw new Error(`Invalid request: ${validation.error.message}`);
    }
  
    const { udid } = validation.data;
  
    // Validate UDID format
    if (!validateUDID(udid)) {
      throw new Error(`Invalid simulator UDID format. UDID must be in format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX: ${udid}`);
    }
  
    const result = await processExecutor.execute('xcrun', ['simctl', 'boot', udid], {
      timeout: 60000, // 1 minute timeout for simulator boot
    });
  
    // Note: simctl boot returns exit code 164 if simulator is already booted, which is not an error
    if (result.exitCode !== 0 && result.exitCode !== 164) {
      throw new Error(`Failed to boot iOS simulator: ${result.stderr}`);
    }
  
    const isAlreadyBooted = result.exitCode === 164;
  
    return {
      success: true,
      data: {
        udid,
        status: isAlreadyBooted ? 'already_booted' : 'booted',
        message: isAlreadyBooted ? 'Simulator was already booted' : 'Simulator booted successfully',
        output: result.stdout,
      },
    };
  }

• src/tools/ios.ts:320-366 (registration)

  Registration of the ios_boot_simulator tool in the createIOSTools factory function, including name, description, JSON input schema, and handler reference.

  tools.set('ios_boot_simulator', {
    name: 'ios_boot_simulator',
    description: 'Boot an iOS simulator',
    inputSchema: {
      type: 'object',
      properties: {
        udid: { type: 'string', minLength: 1, description: 'Simulator UDID' }
      },
      required: ['udid']
    },
    handler: async (args: any) => {
      checkMacOS();
  
      const validation = IosSimulatorActionSchema.safeParse(args);
      if (!validation.success) {
        throw new Error(`Invalid request: ${validation.error.message}`);
      }
  
      const { udid } = validation.data;
  
      // Validate UDID format
      if (!validateUDID(udid)) {
        throw new Error(`Invalid simulator UDID format. UDID must be in format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX: ${udid}`);
      }
  
      const result = await processExecutor.execute('xcrun', ['simctl', 'boot', udid], {
        timeout: 60000, // 1 minute timeout for simulator boot
      });
  
      // Note: simctl boot returns exit code 164 if simulator is already booted, which is not an error
      if (result.exitCode !== 0 && result.exitCode !== 164) {
        throw new Error(`Failed to boot iOS simulator: ${result.stderr}`);
      }
  
      const isAlreadyBooted = result.exitCode === 164;
  
      return {
        success: true,
        data: {
          udid,
          status: isAlreadyBooted ? 'already_booted' : 'booted',
          message: isAlreadyBooted ? 'Simulator was already booted' : 'Simulator booted successfully',
          output: result.stdout,
        },
      };
    }
  });

• src/tools/ios.ts:52-54 (schema)

  Zod schema for validating input parameters (udid) used in the ios_boot_simulator handler and other simulator action tools.

  const IosSimulatorActionSchema = z.object({
    udid: z.string().min(1),
  });

• src/tools/ios.ts:140-144 (helper)

  Helper function to validate that the platform is macOS (darwin), required for iOS tools including ios_boot_simulator.

  const checkMacOS = (): void => {
    if (process.platform !== 'darwin') {
      throw new Error(`iOS development tools only work on macOS. Current platform: ${process.platform}`);
    }
  };

• src/tools/ios.ts:159-162 (helper)

  Helper function to validate iOS simulator UDID format (UUID v4), used in the ios_boot_simulator handler.

  const validateUDID = (udid: string): boolean => {
    const uuidPattern = /^[A-F0-9]{8}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{12}$/i;
    return uuidPattern.test(udid);
  };