feat: Allow iOS device lookup by UUID

packages/platform-ios/README.md

@@ -68,13 +68,15 @@ Creates an iOS simulator device configuration.
 - `deviceName` - Name of the iOS simulator (e.g., 'iPhone 16 Pro Max')
 - `osVersion` - iOS version (e.g., '18.0')
 
-### `applePhysicalDevice(deviceName)`
+### `applePhysicalDevice(deviceNameOrId)`
 
 Creates a physical Apple device configuration.
 
 **Parameters:**
 
-- `deviceName` - Name of the physical device (e.g., 'iPhone (Your Name)')
+- `deviceNameOrId` - Name, CoreDevice identifier, or hardware UDID of the
+  physical device (e.g., 'iPhone (Your Name)' or
+  '6954F636-D116-52FA-9D00-8298BBB63705')
 
 ## Requirements
 

packages/platform-ios/src/__tests__/launch-options.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
   getDeviceConnectionHost,
   getDeviceCtlLaunchArgs,
+  isMatchingDevice,
 } from '../xcrun/devicectl.js';
 import { getSimctlChildEnvironment } from '../xcrun/simctl.js';
 
@@ -62,4 +63,31 @@ describe('Apple app launch options', () => {
       })
     ).toBe('fd12:3456:789a::1');
   });
+
+  it('matches physical devices by name, CoreDevice identifier, or hardware UDID', () => {
+    const device = {
+      identifier: '6954F636-D116-52FA-9D00-8298BBB63705',
+      deviceProperties: {
+        name: 'G22RJQXC3V',
+        osVersionNumber: '26.0',
+      },
+      hardwareProperties: {
+        marketingName: 'iPhone',
+        productType: 'iPhone17,1',
+        udid: '00008140-001600222422201C',
+      },
+    };
+    const matchesName = isMatchingDevice(device, 'G22RJQXC3V');
+    const matchesIdentifier = isMatchingDevice(
+      device,
+      '6954F636-D116-52FA-9D00-8298BBB63705'
+    );
+    const matchesUdid = isMatchingDevice(device, '00008140-001600222422201C');
+    const matchesUnknownName = isMatchingDevice(device, 'Unknown iPhone');
+
+    expect(matchesName).toBe(true);
+    expect(matchesIdentifier).toBe(true);
+    expect(matchesUdid).toBe(true);
+    expect(matchesUnknownName).toBe(false);
+  });
 });

packages/platform-ios/src/xcrun/devicectl.ts

@@ -331,17 +331,32 @@ export const stopApp = async (
   ]);
 };
 
+export const isMatchingDevice = (
+  device: AppleDeviceInfo,
+  identifier: string
+): boolean => {
+  return (
+    device.deviceProperties.name === identifier ||
+    device.identifier === identifier ||
+    device.hardwareProperties.udid === identifier
+  );
+};
+
 export const getDevice = async (
-  name: string
+  identifier: string
 ): Promise<AppleDeviceInfo | null> => {
   const devices = await listDevices();
-  return (
-    devices.find((device) => device.deviceProperties.name === name) ?? null
-  );
+  const matchingDevice = devices.find((device) => {
+    return isMatchingDevice(device, identifier);
+  });
+
+  return matchingDevice ?? null;
 };
 
-export const getDeviceId = async (name: string): Promise<string | null> => {
-  const device = await getDevice(name);
+export const getDeviceId = async (
+  identifier: string
+): Promise<string | null> => {
+  const device = await getDevice(identifier);
   return device?.identifier ?? null;
 };