feat(run-ios): allow passing UDID inside --device option (#2375)

* feat: allow passing UDID inside `--device` option

* chore: explain device name condition

packages/cli-platform-apple/src/commands/runCommand/createRun.ts

@@ -300,9 +300,36 @@ const createRun =
         );
       }
     } else if (args.device) {
-      const physicalDevices = devices.filter(({type}) => type !== 'simulator');
-      const device = matchingDevice(physicalDevices, args.device);
-      if (device) {
+      let device = matchingDevice(devices, args.device);
+
+      if (!device) {
+        const deviceByUdid = devices.find((d) => d.udid === args.device);
+        if (!deviceByUdid) {
+          return logger.error(
+            `Could not find a physical device with name or unique device identifier: "${chalk.bold(
+              args.device,
+            )}". ${printFoundDevices(devices, 'device')}`,
+          );
+        }
+
+        device = deviceByUdid;
+
+        if (deviceByUdid.type === 'simulator') {
+          return logger.error(
+            `The device with udid: "${chalk.bold(
+              args.device,
+            )}" is a simulator. If you want to run on a simulator, use the "--simulator" flag instead.`,
+          );
+        }
+      }
+
+      if (device && device.type === 'simulator') {
+        return logger.error(
+          "`--device` flag is intended for physical devices. If you're trying to run on a simulator, use `--simulator` instead.",
+        );
+      }
+
+      if (device && device.type === 'device') {
         return runOnDevice(
           device,
           platformName,

packages/cli-platform-apple/src/commands/runCommand/matchingDevice.ts

@@ -1,11 +1,12 @@
 import {logger} from '@react-native-community/cli-tools';
 import chalk from 'chalk';
-import {Device} from '../../types';
+import {Device, DeviceType} from '../../types';
 
 export function matchingDevice(
   devices: Array<Device>,
   deviceName: string | true | undefined,
 ) {
+  // The condition specifically checks if the value is `true`, not just truthy to allow for `--device` flag without a value
   if (deviceName === true) {
     const firstIOSDevice = devices.find((d) => d.type === 'device')!;
     if (firstIOSDevice) {
@@ -20,18 +21,10 @@ export function matchingDevice(
       return undefined;
     }
   }
-  const deviceByName = devices.find(
+  return devices.find(
     (device) =>
       device.name === deviceName || formattedDeviceName(device) === deviceName,
   );
-  if (!deviceByName) {
-    logger.error(
-      `Could not find a device named: "${chalk.bold(
-        String(deviceName),
-      )}". ${printFoundDevices(devices)}`,
-    );
-  }
-  return deviceByName;
 }
 
 export function formattedDeviceName(simulator: Device) {
@@ -40,9 +33,15 @@ export function formattedDeviceName(simulator: Device) {
     : simulator.name;
 }
 
-export function printFoundDevices(devices: Array<Device>) {
+export function printFoundDevices(devices: Array<Device>, type?: DeviceType) {
+  let filteredDevice = [...devices];
+
+  if (type) {
+    filteredDevice = filteredDevice.filter((device) => device.type === type);
+  }
+
   return [
     'Available devices:',
-    ...devices.map((device) => `  - ${device.name} (${device.udid})`),
+    ...filteredDevice.map(({name, udid}) => `  - ${name} (${udid})`),
   ].join('\n');
 }

packages/cli-platform-apple/src/commands/runCommand/runOptions.ts

@@ -45,7 +45,7 @@ export const getRunOptions = ({platformName}: BuilderCommand) => {
     !isMac && {
       name: '--device [string]', // here we're intentionally using [] over <> to make passed value optional to allow users to run only on physical devices
       description:
-        'Explicitly set the device to use by name. If the value is not provided,' +
+        'Explicitly set the device to use by name or by unique device identifier . If the value is not provided,' +
         'the app will run on the first available physical device.',
     },
     ...getBuildOptions({platformName}),

packages/cli-platform-apple/src/types.ts

@@ -12,10 +12,12 @@ export interface Device {
   version?: string;
   sdk?: string;
   availabilityError?: string;
-  type?: 'simulator' | 'device' | 'catalyst';
+  type?: DeviceType;
   lastBootedAt?: string;
 }
 
+export type DeviceType = 'simulator' | 'device' | 'catalyst';
+
 export interface IosInfo {
   name: string;
   schemes?: string[];