feat: Allow iOS device lookup by UUID (#113)

## Description

<!-- Provide a general summary of your changes -->

Allows looking up a physical iOS device not just by name, but also uuid.

## Related Issue

<!--- This project only accepts pull requests related to open issues -->
<!--- If suggesting a new feature or change, please discuss it in an
issue first -->
<!--- If fixing a bug, there should be an issue describing it with steps
to reproduce -->
<!--- Please link to the issue here: -->

/

## Context

<!-- Why this feature was implemented in this particular way? -->
<!-- Is there anything reviewer needs to know before conducting code
review? -->

When running test on AWS DF we just get the UUID in the envs. Right now
i have to do a manual lookup to get the device name which is a bit
cumbersome, and it would be nicer to just pass the uuid :)

## Testing

<!-- Please describe how you tested your changes -->

added a test to the repo

---------

Co-authored-by: Szymon Chmal <szymon@chmal.it>

Author: hannojg

.nx/version-plans/version-plan-1778481764162.md

@@ -0,0 +1,5 @@
+---
+__default__: patch
+---
+
+Harness now lets you target connected physical iOS devices by hardware UDID as well as by device name or CoreDevice identifier, which makes it easier to select the exact device when multiple phones share similar names.

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;
 };
 

website/src/docs/platforms/ios.mdx

@@ -61,6 +61,7 @@ Xcode often installs multiple runtime versions (e.g., iOS 17.0 and iOS 18.0). Si
 ### Physical Devices
 
 To run on a connected physical iOS device, use the `applePhysicalDevice()` helper.
+You can identify the device by name, CoreDevice identifier, or hardware UDID.
 
 ```javascript
 applePlatform({