ios_shutdown_simulator

Instructions

Implementation Reference

• src/tools/ios.ts:379-426 (handler)

  The main handler function for the ios_shutdown_simulator tool. It validates the UDID input using Zod schema, checks UDID format, stops any active video recordings for the simulator, executes 'xcrun simctl shutdown' command, handles already shutdown case (exit code 164), and returns structured success 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}`);
    }
  
    // Stop any active recordings for this simulator
    if (activeRecordings.has(udid)) {
      const pid = activeRecordings.get(udid);
      try {
        process.kill(pid!, 'SIGTERM');
        activeRecordings.delete(udid);
      } catch {
        // Process might already be dead
        activeRecordings.delete(udid);
      }
    }
  
    const result = await processExecutor.execute('xcrun', ['simctl', 'shutdown', udid], {
      timeout: 30000, // 30 seconds timeout for shutdown
    });
  
    // Note: simctl shutdown returns exit code 164 if simulator is already shut down
    if (result.exitCode !== 0 && result.exitCode !== 164) {
      throw new Error(`Failed to shutdown iOS simulator: ${result.stderr}`);
    }
  
    const wasAlreadyShutdown = result.exitCode === 164;
  
    return {
      success: true,
      data: {
        udid,
        status: wasAlreadyShutdown ? 'already_shutdown' : 'shutdown',
        message: wasAlreadyShutdown ? 'Simulator was already shut down' : 'Simulator shut down successfully',
        output: result.stdout,
      },
    };
  }

• src/tools/ios.ts:369-427 (registration)

  Registration of the ios_shutdown_simulator tool in the tools Map within createIOSTools function, including name, description, inputSchema (JSON Schema), and handler reference.

  tools.set('ios_shutdown_simulator', {
    name: 'ios_shutdown_simulator',
    description: 'Shutdown 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}`);
      }
  
      // Stop any active recordings for this simulator
      if (activeRecordings.has(udid)) {
        const pid = activeRecordings.get(udid);
        try {
          process.kill(pid!, 'SIGTERM');
          activeRecordings.delete(udid);
        } catch {
          // Process might already be dead
          activeRecordings.delete(udid);
        }
      }
  
      const result = await processExecutor.execute('xcrun', ['simctl', 'shutdown', udid], {
        timeout: 30000, // 30 seconds timeout for shutdown
      });
  
      // Note: simctl shutdown returns exit code 164 if simulator is already shut down
      if (result.exitCode !== 0 && result.exitCode !== 164) {
        throw new Error(`Failed to shutdown iOS simulator: ${result.stderr}`);
      }
  
      const wasAlreadyShutdown = result.exitCode === 164;
  
      return {
        success: true,
        data: {
          udid,
          status: wasAlreadyShutdown ? 'already_shutdown' : 'shutdown',
          message: wasAlreadyShutdown ? 'Simulator was already shut down' : 'Simulator shut down successfully',
          output: result.stdout,
        },
      };
    }
  });

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

  Zod validation schema used internally by the handler for input validation (udid: string min length 1). Shared with other simulator action tools.

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

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

  Helper function to validate iOS Simulator UDID format using UUID v4 regex pattern. Called within the 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);
  };

• src/utils/tool-categories.ts:162-170 (helper)

  Tool metadata registration in TOOL_REGISTRY, specifying category, platform, required tools (XCRUN), safety, and performance expectations.

  'ios_shutdown_simulator': {
    name: 'ios_shutdown_simulator',
    category: ToolCategory.ESSENTIAL,
    platform: 'ios',
    requiredTools: [RequiredTool.XCRUN],
    description: 'Shutdown iOS simulator',
    safeForTesting: false,
    performance: { expectedDuration: 5000, timeout: 30000 }
  },