appium-ios-remotexpc 5.2.0 → 5.2.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [5.2.1](https://github.com/appium/appium-ios-remotexpc/compare/v5.2.0...v5.2.1) (2026-06-24)
+
+### Miscellaneous Chores
+
+* refactor tunnels creation and pairing scripts ([#247](https://github.com/appium/appium-ios-remotexpc/issues/247)) ([c614312](https://github.com/appium/appium-ios-remotexpc/commit/c614312dde31ce4019707ff3f079b57362a761ee))
+
 ## [5.2.0](https://github.com/appium/appium-ios-remotexpc/compare/v5.1.6...v5.2.0) (2026-06-22)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-remotexpc",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",
   "type": "module",

package/scripts/lib/constants.mjs

@@ -0,0 +1,4 @@
+export const DEFAULT_APPLETV_PAIRING_DISCOVERY_TIMEOUT_MS =
+  Number(process.env.APPLETV_DISCOVERY_TIMEOUT) || 10_000;
+export const DEFAULT_WIRELESS_APPLETV_DISCOVERY_TIMEOUT_MS = 10_000;
+export const DEFAULT_TUNNEL_REGISTRY_PORT = 42314;

package/scripts/lib/options.mjs

@@ -0,0 +1,56 @@
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {number}
+ */
+export function parsePositiveIntegerOption(value, label) {
+  return parseIntegerOption(
+    value,
+    label,
+    (num) => num > 0,
+    'a positive integer in milliseconds',
+  );
+}
+
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {number}
+ */
+export function parseNonNegativeIntegerOption(value, label) {
+  return parseIntegerOption(
+    value,
+    label,
+    (num) => num >= 0,
+    'a non-negative integer (0 = unlimited)',
+  );
+}
+
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {number}
+ */
+export function parsePortOption(value, label) {
+  return parseIntegerOption(
+    value,
+    label,
+    (num) => num > 0 && num <= 65535,
+    'an integer between 1 and 65535',
+  );
+}
+
+/**
+ * @param {string} value
+ * @param {string} label
+ * @param {(num: number) => boolean} isValid
+ * @param {string} expectation
+ * @returns {number}
+ */
+function parseIntegerOption(value, label, isValid, expectation) {
+  const num = Number.parseInt(value, 10);
+  if (!Number.isFinite(num) || !isValid(num)) {
+    throw new Error(`Invalid ${label}: ${value}. Expected ${expectation}.`);
+  }
+  return num;
+}

package/scripts/lib/progress.mjs

@@ -0,0 +1,53 @@
+/**
+ * Logs a timeout-based progress bar while an operation without native progress callbacks is running.
+ *
+ * @param {{log: {info: (message: string) => void}, label: string, startedAt: number, timeoutMs: number, barWidth: number, intervalMs: number}} opts
+ * @returns {{succeed: (message?: string) => void, fail: (message?: string) => void}}
+ */
+export function startTimeoutProgressLogger({
+  log,
+  label,
+  startedAt,
+  timeoutMs,
+  barWidth,
+  intervalMs,
+}) {
+  /** @type {NodeJS.Timeout | null} */
+  let timer = null;
+  let isStopped = false;
+
+  const logProgress = (status, isComplete = false) => {
+    const elapsedMs = performance.now() - startedAt;
+    const boundedElapsedMs = Math.min(elapsedMs, timeoutMs);
+    const progress = isComplete ? 1 : boundedElapsedMs / timeoutMs;
+    const filledWidth = Math.round(progress * barWidth);
+    const emptyWidth = barWidth - filledWidth;
+    const bar = `${'#'.repeat(filledWidth)}${'-'.repeat(emptyWidth)}`;
+    log.info(
+      `${label}: [${bar}]${status && status !== 'waiting' ? ` - ${status}` : ''}`,
+    );
+  };
+
+  const stop = (status, isComplete = false) => {
+    if (isStopped) {
+      return;
+    }
+    isStopped = true;
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+    logProgress(status, isComplete);
+  };
+
+  logProgress('waiting');
+  timer = setInterval(() => {
+    logProgress('waiting');
+  }, intervalMs);
+  timer.unref?.();
+
+  return {
+    succeed: (message = 'done') => stop(message, true),
+    fail: (message = 'failed') => stop(message),
+  };
+}

package/scripts/lib/root.mjs

@@ -0,0 +1,36 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Ensures a helper script is run with elevated privileges.
+ *
+ * @param {string} relativeScriptPath
+ */
+export async function assertRoot(relativeScriptPath) {
+  if (process.platform === 'win32') {
+    await assertWindowsAdmin(relativeScriptPath);
+    return;
+  }
+
+  if (typeof process.getuid !== 'function') {
+    return;
+  }
+  if (process.getuid() !== 0) {
+    throw new Error(`This script must be run as root/admin (e.g. sudo node "${relativeScriptPath}").`);
+  }
+}
+
+/**
+ * @param {string} relativeScriptPath
+ */
+async function assertWindowsAdmin(relativeScriptPath) {
+  try {
+    await execFileAsync('net', ['session']);
+  } catch {
+    throw new Error(
+      `This script must be run as Administrator (e.g. from an elevated terminal: node "${relativeScriptPath}").`,
+    );
+  }
+}

package/scripts/lib/timers.mjs

@@ -0,0 +1,7 @@
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/scripts/lib/tunnel-registry.mjs

@@ -0,0 +1,81 @@
+import { discoverServices, servicesToCatalog } from 'appium-ios-remotexpc';
+
+/**
+ * @returns {import('appium-ios-remotexpc').TunnelRegistry}
+ */
+export function createEmptyTunnelRegistry() {
+  return {
+    tunnels: {},
+    metadata: {
+      lastUpdated: new Date().toISOString(),
+      totalTunnels: 0,
+      activeTunnels: 0,
+    },
+  };
+}
+
+/**
+ * @param {string} udid
+ * @param {import('appium-ios-remotexpc').TunnelRegistryEntry} entry
+ * @param {{info: (message: string) => void}} log
+ */
+export async function refreshServiceCatalog(udid, entry, log) {
+  log.info(`Refreshing RSD service catalog for ${udid}...`);
+  const services = await discoverServices(udid, entry.address, entry.rsdPort);
+  const now = Date.now();
+  return {
+    ...entry,
+    services: servicesToCatalog(services),
+    catalogUpdatedAt: now,
+    lastUpdated: now,
+  };
+}
+
+/**
+ * @template T
+ * @param {object} opts
+ * @param {import('appium-ios-remotexpc').TunnelRegistryServer | null} opts.registryServer
+ * @param {T} opts.result
+ * @param {(result: T) => string} opts.getUdid
+ * @param {(result: T, existing: import('appium-ios-remotexpc').TunnelRegistryEntry | undefined, now: number) => import('appium-ios-remotexpc').TunnelRegistryEntry} opts.buildEntry
+ * @param {{info: (message: string) => void, warn: (message: string) => void}} opts.log
+ * @returns {Promise<boolean>}
+ */
+export async function publishDiscoveredTunnelEntry({
+  registryServer,
+  result,
+  getUdid,
+  buildEntry,
+  log,
+}) {
+  if (!registryServer) {
+    throw new Error('Registry server is not started');
+  }
+
+  const udid = getUdid(result);
+  const rsdPort = result.tunnel.RsdPort;
+  if (typeof rsdPort !== 'number' || rsdPort <= 0) {
+    log.warn(
+      `Skipping registry entry for ${udid}: no valid RSD port (got ${String(rsdPort)})`,
+    );
+    return false;
+  }
+
+  registryServer.markTunnelPending(udid);
+  log.info(
+    `Discovering RSD services for ${udid} at ${result.tunnel.Address}:${rsdPort}...`,
+  );
+
+  const services = await discoverServices(udid, result.tunnel.Address, rsdPort);
+  const now = Date.now();
+  const registry = registryServer.getRegistry();
+  const entry = buildEntry(result, registry.tunnels[udid], now);
+  entry.services = servicesToCatalog(services);
+  entry.catalogUpdatedAt = now;
+
+  registryServer.upsertReadyEntry(udid, entry);
+  log.info(
+    `Published tunnel catalog for ${udid} (${Object.keys(entry.services).length} services)`,
+  );
+  return true;
+}

package/scripts/pair-appletv.mjs

@@ -6,74 +6,20 @@
  *   npm run pair-appletv -- [options]
  */
 
-import { logger } from '@appium/support';
+import { logger, util } from '@appium/support';
 import { Command } from 'commander';
 import {
   AppleTVPairingService,
   UserInputService,
 } from 'appium-ios-remotexpc';
-import { DEFAULT_PAIRING_CONFIG } from '../build/src/lib/apple-tv/constants.js';
+import { DEFAULT_APPLETV_PAIRING_DISCOVERY_TIMEOUT_MS } from './lib/constants.mjs';
+import { parsePositiveIntegerOption } from './lib/options.mjs';
+import { startTimeoutProgressLogger } from './lib/progress.mjs';
 
 const log = logger.getLogger('AppleTVPairing');
 const APPLETV_PAIRING_DISCOVERY_PROGRESS_INTERVAL_MS = 1000;
 const APPLETV_PAIRING_DISCOVERY_PROGRESS_BAR_WIDTH = 24;
 
-function parsePositiveInteger(value) {
-  const count = Number.parseInt(value, 10);
-  if (!Number.isFinite(count) || count <= 0) {
-    throw new Error(
-      `Invalid timeout: ${value}. Expected a positive integer in milliseconds.`,
-    );
-  }
-  return count;
-}
-
-function startTimeoutProgressLogger({
-  label,
-  startedAt,
-  timeoutMs,
-  barWidth,
-  intervalMs,
-}) {
-  let timer = null;
-  let isStopped = false;
-
-  const logProgress = (status, isComplete = false) => {
-    const elapsedMs = performance.now() - startedAt;
-    const boundedElapsedMs = Math.min(elapsedMs, timeoutMs);
-    const progress = isComplete ? 1 : boundedElapsedMs / timeoutMs;
-    const filledWidth = Math.round(progress * barWidth);
-    const emptyWidth = barWidth - filledWidth;
-    const bar = `${'#'.repeat(filledWidth)}${'-'.repeat(emptyWidth)}`;
-    log.info(
-      `${label}: [${bar}]${status && status !== 'waiting' ? ` - ${status}` : ''}`,
-    );
-  };
-
-  const stop = (status, isComplete = false) => {
-    if (isStopped) {
-      return;
-    }
-    isStopped = true;
-    if (timer) {
-      clearInterval(timer);
-      timer = null;
-    }
-    logProgress(status, isComplete);
-  };
-
-  logProgress('waiting');
-  timer = setInterval(() => {
-    logProgress('waiting');
-  }, intervalMs);
-  timer.unref?.();
-
-  return {
-    succeed: (message = 'done') => stop(message, true),
-    fail: (message = 'failed') => stop(message),
-  };
-}
-
 function discoverAppleTVPairingDevices(pairingService, timeoutMs) {
   const startedAt = performance.now();
   const promise = pairingService.discoverDevices({ timeoutMs });
@@ -82,6 +28,7 @@ function discoverAppleTVPairingDevices(pairingService, timeoutMs) {
 
 async function waitForAppleTVPairingDiscovery(discovery, timeoutMs) {
   const progress = startTimeoutProgressLogger({
+    log,
     label: 'Waiting for Apple TV pairing discovery',
     startedAt: discovery.startedAt,
     timeoutMs,
@@ -92,7 +39,7 @@ async function waitForAppleTVPairingDiscovery(discovery, timeoutMs) {
   try {
     const devices = await discovery.promise;
     progress.succeed(
-      `Apple TV pairing discovery completed: ${devices.length} device(s) found`,
+      `Apple TV pairing discovery completed: ${util.pluralize('device', devices.length, true)} found`,
     );
     return devices;
   } catch (err) {
@@ -101,6 +48,44 @@ async function waitForAppleTVPairingDiscovery(discovery, timeoutMs) {
   }
 }
 
+async function discoverAndPairWithProgress(
+  pairingService,
+  deviceSelector,
+  discoveryTimeoutMs,
+) {
+  const discovery = discoverAppleTVPairingDevices(
+    pairingService,
+    discoveryTimeoutMs,
+  );
+  const devices = await waitForAppleTVPairingDiscovery(
+    discovery,
+    discoveryTimeoutMs,
+  );
+  return await pairingService.discoverAndPair(deviceSelector, {
+    devices,
+    discoveryTimeoutMs,
+  });
+}
+
+/**
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isNoAppleTVPairingDevicesFoundError(err) {
+  return (
+    err instanceof Error &&
+    (err.message === getNoAppleTVPairingDevicesMessage() ||
+      ('code' in err && err.code === 'NO_DEVICES'))
+  );
+}
+
+/**
+ * @returns {string}
+ */
+function getNoAppleTVPairingDevicesMessage() {
+  return 'No Apple TV pairing devices found. Please ensure your Apple TV is on the same network and in pairing mode.';
+}
+
 async function main() {
   const program = new Command();
   program
@@ -113,31 +98,26 @@ async function main() {
     .option(
       '--discovery-timeout <ms>',
       'Apple TV pairing discovery timeout in milliseconds',
-      parsePositiveInteger,
+      (value) => parsePositiveIntegerOption(value, 'discovery timeout'),
     );
 
   program.parse(process.argv);
   const options = program.opts();
   const discoveryTimeoutMs =
-    options.discoveryTimeout ?? DEFAULT_PAIRING_CONFIG.discoveryTimeout;
+    options.discoveryTimeout ?? DEFAULT_APPLETV_PAIRING_DISCOVERY_TIMEOUT_MS;
 
   const userInput = new UserInputService();
   const pairingService = new AppleTVPairingService(userInput);
-  const discovery = discoverAppleTVPairingDevices(
+  const result = await discoverAndPairWithProgress(
     pairingService,
+    options.device,
     discoveryTimeoutMs,
   );
-  const devices = await waitForAppleTVPairingDiscovery(
-    discovery,
-    discoveryTimeoutMs,
-  );
-  const result = await pairingService.discoverAndPair(options.device, {
-    devices,
-    discoveryTimeoutMs,
-  });
 
   if (result.success) {
     log.info(`Pairing successful! Record saved to: ${result.pairingFile}`);
+  } else if (isNoAppleTVPairingDevicesFoundError(result.error)) {
+    log.info(getNoAppleTVPairingDevicesMessage());
   } else {
     throw result.error ?? new Error('Pairing failed');
   }

package/scripts/start-appletv-tunnel.mjs

@@ -11,15 +11,31 @@ import {
   AppleTVTunnelService,
   TunnelManager,
   TunnelReadinessCoordinator,
-  discoverServices,
-  servicesToCatalog,
   startTunnelRegistryServer,
   watchTunnelRegistryOnDead,
 } from 'appium-ios-remotexpc';
-import { DEFAULT_TUNNEL_REGISTRY_PORT } from '../build/src/lib/tunnel/tunnel-registry-server.js';
+import {
+  parseNonNegativeIntegerOption,
+  parsePortOption,
+  parsePositiveIntegerOption,
+} from './lib/options.mjs';
+import { sleep } from './lib/timers.mjs';
+import {
+  createEmptyTunnelRegistry,
+  publishDiscoveredTunnelEntry as publishTunnelRegistryEntry,
+  refreshServiceCatalog,
+} from './lib/tunnel-registry.mjs';
+import { DEFAULT_TUNNEL_REGISTRY_PORT, DEFAULT_WIRELESS_APPLETV_DISCOVERY_TIMEOUT_MS } from './lib/constants.mjs';
+import { assertRoot } from './lib/root.mjs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { startTimeoutProgressLogger } from './lib/progress.mjs';
 
 const log = logger.getLogger('WiFiTunnel');
 
+const APPLETV_TUNNEL_DISCOVERY_PROGRESS_INTERVAL_MS = 1000;
+const APPLETV_TUNNEL_DISCOVERY_PROGRESS_BAR_WIDTH = 24;
+
 /** @type {import('appium-ios-remotexpc').TunnelRegistryServer | null} */
 let registryServer = null;
 
@@ -48,6 +64,54 @@ function stopLifecycleWatch(udid) {
   }
 }
 
+/**
+ *
+ * @param {import('appium-ios-remotexpc').AppleTVTunnelService} tunnelService
+ * @param {number} timeoutMs
+ * @returns {Promise<number, Promise<AppleTVDevice[]>>}
+ */
+function startDevicesDiscovery(tunnelService, timeoutMs) {
+  const startedAt = performance.now();
+  const promise = tunnelService.discoverDevices({ timeoutMs });
+  return { startedAt, promise };
+}
+
+/**
+ *
+ * @param {Promise<AppleTVDevice[]>} discovery
+ * @param {number} timeoutMs
+ * @returns {Promise<AppleTVDevice[]>}
+ */
+async function waitForDevicesDiscovery(discovery, timeoutMs) {
+  const progress = startTimeoutProgressLogger({
+    log,
+    label: 'Waiting for wireless Apple TV devices discovery',
+    startedAt: discovery.startedAt,
+    timeoutMs,
+    barWidth: APPLETV_TUNNEL_DISCOVERY_PROGRESS_BAR_WIDTH,
+    intervalMs: APPLETV_TUNNEL_DISCOVERY_PROGRESS_INTERVAL_MS,
+  });
+
+  try {
+    const devices = await discovery.promise;
+    progress.succeed(
+      `Wireless Apple TV devices discovery completed: ${util.pluralize('device', devices.length, true)} found`,
+    );
+    return devices;
+  } catch (err) {
+    progress.fail('Wireless Apple TV devices discovery failed');
+    throw err;
+  }
+}
+
+/**
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isNoDevicesFoundError(err) {
+  return err instanceof Error && ('code' in err && err.code === 'NO_DEVICES') || err.message?.includes('No devices found');
+}
+
 function registerEstablishedTunnel(result) {
   const udid = result.device.identifier;
   stopLifecycleWatch(udid);
@@ -63,36 +127,6 @@ function registerEstablishedTunnel(result) {
 }
 let tunnelService = null;
 
-function parsePort(value) {
-  const port = Number.parseInt(value, 10);
-  if (!Number.isFinite(port) || port <= 0 || port > 65535) {
-    throw new Error(
-      `Invalid port: ${value}. Expected an integer between 1 and 65535.`,
-    );
-  }
-  return port;
-}
-
-function parseNonNegativeInteger(value) {
-  const count = Number.parseInt(value, 10);
-  if (!Number.isFinite(count) || count < 0) {
-    throw new Error(
-      `Invalid retry count: ${value}. Expected a non-negative integer (0 = unlimited).`,
-    );
-  }
-  return count;
-}
-
-function parsePositiveInteger(value) {
-  const count = Number.parseInt(value, 10);
-  if (!Number.isFinite(count) || count <= 0) {
-    throw new Error(
-      `Invalid timeout: ${value}. Expected a positive integer in milliseconds.`,
-    );
-  }
-  return count;
-}
-
 /**
  * @param {object} registry
  * @param {AppleTvEstablishedTunnel[]} successfulResults
@@ -166,25 +200,27 @@ function setupCleanupHandlers() {
 
   process.on('SIGINT', async () => {
     await cleanup('SIGINT (Ctrl+C)');
-    process.exit(0);
+    process.exit(process.exitCode || 0);
   });
   process.on('SIGTERM', async () => {
     await cleanup('SIGTERM');
-    process.exit(0);
+    process.exit(process.exitCode || 0);
   });
   process.on('SIGHUP', async () => {
     await cleanup('SIGHUP');
-    process.exit(0);
+    process.exit(process.exitCode || 0);
   });
 
   process.on('uncaughtException', async (error) => {
     log.error('Uncaught Exception:', error);
     await cleanup('Uncaught Exception');
+    process.exit(process.exitCode || 1);
   });
 
   process.on('unhandledRejection', async (reason, promise) => {
     log.error('Unhandled Rejection at:', promise, 'reason:', reason);
     await cleanup('Unhandled Rejection');
+    process.exit(process.exitCode || 1);
   });
 }
 
@@ -220,21 +256,8 @@ async function establishOneTunnel(startResult) {
   return result;
 }
 
-async function refreshServiceCatalog(udid, entry) {
-  log.info(`Refreshing RSD service catalog for ${udid}...`);
-  const services = await discoverServices(udid, entry.address, entry.rsdPort);
-  const now = Date.now();
-  return {
-    ...entry,
-    services: servicesToCatalog(services),
-    catalogUpdatedAt: now,
-    lastUpdated: now,
-  };
-}
-
-function buildAppleTvTunnelEntryBase(result, existing) {
+function buildAppleTvTunnelEntry(result, existing, now) {
   const udid = result.device.identifier;
-  const now = Date.now();
   const entry = {
     udid,
     deviceId: 0,
@@ -250,44 +273,13 @@ function buildAppleTvTunnelEntryBase(result, existing) {
 }
 
 async function publishDiscoveredTunnelEntry(result) {
-  if (!registryServer) {
-    throw new Error('Registry server is not started');
-  }
-
-  const udid = result.device.identifier;
-  const rsdPort = result.tunnel.RsdPort;
-  if (typeof rsdPort !== 'number' || rsdPort <= 0) {
-    log.warn(
-      `Skipping registry entry for ${udid}: no valid RSD port (got ${String(rsdPort)})`,
-    );
-    return false;
-  }
-
-  registryServer.markTunnelPending(udid);
-  log.info(
-    `Discovering RSD services for ${udid} at ${result.tunnel.Address}:${rsdPort}...`,
-  );
-
-  const services = await discoverServices(
-    udid,
-    result.tunnel.Address,
-    rsdPort,
-  );
-  const now = Date.now();
-  const registry = registryServer.getRegistry();
-  const entry = buildAppleTvTunnelEntryBase(result, registry.tunnels[udid]);
-  entry.services = servicesToCatalog(services);
-  entry.catalogUpdatedAt = now;
-
-  registryServer.upsertReadyEntry(udid, entry);
-  log.info(
-    `Published tunnel catalog for ${udid} (${Object.keys(entry.services).length} services)`,
-  );
-  return true;
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return await publishTunnelRegistryEntry({
+    registryServer,
+    result,
+    getUdid: (r) => r.device.identifier,
+    buildEntry: buildAppleTvTunnelEntry,
+    log,
+  });
 }
 
 async function runAppleTvReconnectAttempts({
@@ -382,17 +374,17 @@ async function main() {
     .option(
       '--tunnel-registry-port <port>',
       `Port for tunnel registry API (default: ${DEFAULT_TUNNEL_REGISTRY_PORT})`,
-      parsePort,
+      (value) => parsePortOption(value, 'tunnel registry port'),
     )
     .option(
       '--reconnect-retries <count>',
       'Reconnect retries after unexpected tunnel drop (0 = unlimited)',
-      parseNonNegativeInteger,
+      (value) => parseNonNegativeIntegerOption(value, 'retry count'),
     )
     .option(
       '--discovery-timeout <ms>',
       'Apple TV discovery timeout in milliseconds',
-      parsePositiveInteger,
+      (value) => parsePositiveIntegerOption(value, 'discovery timeout'),
     );
 
   program.parse(process.argv);
@@ -401,6 +393,8 @@ async function main() {
   const registryPort =
     options.tunnelRegistryPort ?? DEFAULT_TUNNEL_REGISTRY_PORT;
 
+  await assertRoot(path.join('scripts', path.basename(fileURLToPath(import.meta.url))));
+
   if (deviceIdentifier) {
     log.info(`Targeting a single Apple TV: ${deviceIdentifier}`);
   } else {
@@ -413,18 +407,12 @@ async function main() {
 
   try {
     const readiness = new TunnelReadinessCoordinator();
-    const registry = {
-      tunnels: {},
-      metadata: {
-        lastUpdated: new Date().toISOString(),
-        totalTunnels: 0,
-        activeTunnels: 0,
-      },
-    };
+    const registry = createEmptyTunnelRegistry();
 
     registryServer = await startTunnelRegistryServer(registry, registryPort, {
       readiness,
-      refreshServices: refreshServiceCatalog,
+      refreshServices: async (udid, entry) =>
+        await refreshServiceCatalog(udid, entry, log),
     });
 
     const reconnectTunnelByUdid = createAppleTvReconnectTunnelByUdid({
@@ -460,11 +448,27 @@ async function main() {
         },
       );
     } else {
-      const devices = await tunnelService.discoverDevices({
-        timeoutMs: options.discoveryTimeout,
-      });
+      const discoveryTimeoutMs = options.discoveryTimeout ?? DEFAULT_WIRELESS_APPLETV_DISCOVERY_TIMEOUT_MS;
+      const discovery = startDevicesDiscovery(
+        tunnelService,
+        discoveryTimeoutMs,
+      );
+      /** @type {AppleTVDevice[]} */
+      let devices = [];
+      try {
+        devices = await waitForDevicesDiscovery(
+          discovery,
+          discoveryTimeoutMs,
+        );
+      } catch (err) {
+        if (isNoDevicesFoundError(err)) {
+          log.info('No wireless Apple TV devices found');
+          process.exit(process.exitCode || 0);
+        }
+        throw err;
+      }
       log.info(
-        `Discovered ${devices.length} Apple TV device(s); establishing tunnels...`,
+        `Discovered ${util.pluralize('Apple TV device', devices.length, true)}; establishing ${util.pluralize('tunnel', devices.length)}...`,
       );
 
       for (let i = 0; i < devices.length; i++) {
@@ -536,8 +540,12 @@ async function main() {
       );
     }
 
-    log.info('\n✅ Apple TV tunnel(s) ready.');
-    log.info('\nPress Ctrl+C to close tunnel(s) and exit.');
+    log.info(
+      `\n✅ ${registryPublished.length} Apple TV ${util.pluralize('tunnel', registryPublished.length)} ready.`,
+    );
+    log.info(
+      `\nPress Ctrl+C to close ${util.pluralize('tunnel', registryPublished.length)} and exit.`,
+    );
 
     process.stdin.resume();
   } catch (error) {

package/scripts/tunnel-creation.mjs

@@ -3,21 +3,31 @@
  * Create lockdown + CoreDeviceProxy tunnels for connected USB devices and expose the tunnel registry API.
  */
 
-import { logger } from '@appium/support';
+import { logger, util } from '@appium/support';
 import { Command } from 'commander';
-
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
 import {
   TunnelManager,
   TunnelReadinessCoordinator,
   createLockdownServiceByUDID,
   createUsbmux,
-  discoverServices,
-  servicesToCatalog,
   startCoreDeviceProxyTcp,
   startTunnelRegistryServer,
   watchTunnelRegistryOnDead,
 } from 'appium-ios-remotexpc';
-import { DEFAULT_TUNNEL_REGISTRY_PORT } from '../build/src/lib/tunnel/tunnel-registry-server.js';
+import {
+  parseNonNegativeIntegerOption,
+  parsePortOption,
+} from './lib/options.mjs';
+import { sleep } from './lib/timers.mjs';
+import {
+  createEmptyTunnelRegistry,
+  publishDiscoveredTunnelEntry as publishTunnelRegistryEntry,
+  refreshServiceCatalog,
+} from './lib/tunnel-registry.mjs';
+import { DEFAULT_TUNNEL_REGISTRY_PORT } from './lib/constants.mjs';
+import { assertRoot } from './lib/root.mjs';
 
 const log = logger.getLogger('TunnelCreation');
 
@@ -94,41 +104,8 @@ function dedupeDevicesByUdid(devices) {
   return [...byUdid.values()];
 }
 
-function parsePort(value) {
-  const port = Number.parseInt(value, 10);
-  if (!Number.isFinite(port) || port <= 0 || port > 65535) {
-    throw new Error(
-      `Invalid port: ${value}. Expected an integer between 1 and 65535.`,
-    );
-  }
-  return port;
-}
-
-function parseNonNegativeInteger(value) {
-  const count = Number.parseInt(value, 10);
-  if (!Number.isFinite(count) || count < 0) {
-    throw new Error(
-      `Invalid retry count: ${value}. Expected a non-negative integer (0 = unlimited).`,
-    );
-  }
-  return count;
-}
-
-async function refreshServiceCatalog(udid, entry) {
-  log.info(`Refreshing RSD service catalog for ${udid}...`);
-  const services = await discoverServices(udid, entry.address, entry.rsdPort);
-  const now = Date.now();
-  return {
-    ...entry,
-    services: servicesToCatalog(services),
-    catalogUpdatedAt: now,
-    lastUpdated: now,
-  };
-}
-
-function buildTunnelEntryBase(result, existing) {
+function buildTunnelEntry(result, existing, now) {
   const udid = result.device.Properties.SerialNumber;
-  const now = Date.now();
   const entry = {
     udid,
     deviceId: result.device.DeviceID,
@@ -144,40 +121,13 @@ function buildTunnelEntryBase(result, existing) {
 }
 
 async function publishDiscoveredTunnelEntry(result) {
-  if (!registryServer) {
-    throw new Error('Registry server is not started');
-  }
-
-  const udid = result.device.Properties.SerialNumber;
-  const rsdPort = result.tunnel.RsdPort;
-  if (typeof rsdPort !== 'number' || rsdPort <= 0) {
-    log.warn(
-      `Skipping registry entry for ${udid}: no valid RSD port (got ${String(rsdPort)})`,
-    );
-    return false;
-  }
-
-  registryServer.markTunnelPending(udid);
-  log.info(
-    `Discovering RSD services for ${udid} at ${result.tunnel.Address}:${rsdPort}...`,
-  );
-
-  const services = await discoverServices(
-    udid,
-    result.tunnel.Address,
-    rsdPort,
-  );
-  const now = Date.now();
-  const registry = registryServer.getRegistry();
-  const entry = buildTunnelEntryBase(result, registry.tunnels[udid]);
-  entry.services = servicesToCatalog(services);
-  entry.catalogUpdatedAt = now;
-
-  registryServer.upsertReadyEntry(udid, entry);
-  log.info(
-    `Published tunnel catalog for ${udid} (${Object.keys(entry.services).length} services)`,
-  );
-  return true;
+  return await publishTunnelRegistryEntry({
+    registryServer,
+    result,
+    getUdid: (r) => r.device.Properties.SerialNumber,
+    buildEntry: buildTunnelEntry,
+    log,
+  });
 }
 
 const registryWatcherStops = [];
@@ -222,10 +172,6 @@ function attachTunnelRegistryLifecycleWatch(registry, successful, callbacks = {}
   );
 }
 
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 async function runReconnectAttempts({
   udid,
   maxRetries,
@@ -328,25 +274,27 @@ function setupCleanupHandlers() {
 
   process.on('SIGINT', async () => {
     await cleanup('SIGINT (Ctrl+C)');
-    process.exit(0);
+    process.exit(process.exitCode || 0);
   });
   process.on('SIGTERM', async () => {
     await cleanup('SIGTERM');
-    process.exit(0);
+    process.exit(process.exitCode || 0);
   });
   process.on('SIGHUP', async () => {
     await cleanup('SIGHUP');
-    process.exit(0);
+    process.exit(process.exitCode || 0);
   });
 
   process.on('uncaughtException', async (error) => {
     log.error('Uncaught Exception:', error);
     await cleanup('Uncaught Exception');
+    process.exit(process.exitCode || 1);
   });
 
   process.on('unhandledRejection', async (reason, promise) => {
     log.error('Unhandled Rejection at:', promise, 'reason:', reason);
     await cleanup('Unhandled Rejection');
+    process.exit(process.exitCode || 1);
   });
 }
 
@@ -433,18 +381,20 @@ async function main() {
     .option(
       '--tunnel-registry-port <port>',
       `Port for tunnel registry API (default: ${DEFAULT_TUNNEL_REGISTRY_PORT})`,
-      parsePort,
+      (value) => parsePortOption(value, 'tunnel registry port'),
     )
     .option(
       '--reconnect-retries <count>',
       'Reconnect retries after unexpected tunnel drop (0 = unlimited)',
-      parseNonNegativeInteger,
+      (value) => parseNonNegativeIntegerOption(value, 'retry count'),
     );
 
   program.parse(process.argv);
   const options = program.opts();
   const specificUdid = options.udid ?? program.args[0] ?? undefined;
 
+  await assertRoot(path.join('scripts', path.basename(fileURLToPath(import.meta.url))));
+
   if (specificUdid) {
     log.info(
       `Starting tunnel creation test for specific UDID: ${specificUdid}`,
@@ -476,7 +426,7 @@ async function main() {
       process.exit(0);
     }
 
-    log.info(`Found ${devices.length} connected device(s):`);
+    log.info(`Found ${util.pluralize('connected device', devices.length, true)}:`);
     devices.forEach((device, index) => {
       log.info(`  ${index + 1}. UDID: ${device.Properties.SerialNumber}`);
       log.info(`     Device ID: ${device.DeviceID}`);
@@ -506,25 +456,19 @@ async function main() {
     devicesToProcess = dedupeDevicesByUdid(devicesToProcess);
     if (devicesToProcess.length < beforeDedupe) {
       log.info(
-        `Deduped ${beforeDedupe} usbmux entries to ${devicesToProcess.length} device(s) (USB preferred over Network)`,
+        `Deduped ${util.pluralize('usbmux entry', beforeDedupe, true)} to ${util.pluralize('device', devicesToProcess.length, true)} (USB preferred over Network)`,
       );
     }
 
-    log.info(`\nProcessing ${devicesToProcess.length} device(s)...`);
+    log.info(`\nProcessing ${util.pluralize('device', devicesToProcess.length, true)}...`);
 
     const readiness = new TunnelReadinessCoordinator();
-    const registry = {
-      tunnels: {},
-      metadata: {
-        lastUpdated: new Date().toISOString(),
-        totalTunnels: 0,
-        activeTunnels: 0,
-      },
-    };
+    const registry = createEmptyTunnelRegistry();
 
     registryServer = await startTunnelRegistryServer(registry, registryPort, {
       readiness,
-      refreshServices: refreshServiceCatalog,
+      refreshServices: async (udid, entry) =>
+        await refreshServiceCatalog(udid, entry, log),
     });
 
     const reconnectRetries = options.reconnectRetries;
@@ -560,19 +504,19 @@ async function main() {
       }
 
       if (devicesToProcess.length > 1) {
-        await new Promise((resolve) => setTimeout(resolve, 1000));
+        await sleep(1000);
       }
     }
 
     log.info('\n=== TUNNEL CREATION SUMMARY ===');
     const failed = results.filter((r) => !r.success);
 
-    log.info(`Total devices processed: ${results.length}`);
-    log.info(`Successful tunnels: ${successful.length}`);
-    log.info(`Failed tunnels: ${failed.length}`);
+    log.info(`Total ${util.pluralize('device', results.length, true)} processed`);
+    log.info(`Successful ${util.pluralize('tunnel', successful.length, true)}`);
+    log.info(`Failed ${util.pluralize('tunnel', failed.length, true)}`);
 
     if (successful.length > 0) {
-      log.info('\n✅ Successful tunnels:');
+      log.info(`\n✅ Successful ${util.pluralize('tunnel', successful.length)}:`);
       log.info('\n📁 Tunnel registry API:');
       log.info('   The tunnel registry is now available through the API at:');
       log.info(`   http://localhost:${registryPort}/remotexpc/tunnels`);