appium-ios-remotexpc 5.2.0 → 5.2.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [5.2.2](https://github.com/appium/appium-ios-remotexpc/compare/v5.2.1...v5.2.2) (2026-06-24)
+
+### Miscellaneous Chores
+
+* Add scripts to typescript checks ([#253](https://github.com/appium/appium-ios-remotexpc/issues/253)) ([f06a206](https://github.com/appium/appium-ios-remotexpc/commit/f06a2060a41f834ca049cb31d9f453c12d9fc013))
+
+## [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.2",
   "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,61 @@
+/**
+ * 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;
+
+  /**
+   * @param {string} status
+   * @param {boolean} isComplete
+   */
+  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}` : ''}`,
+    );
+  };
+
+  /**
+   * @param {string} status
+   * @param {boolean} isComplete
+   */
+  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 & { tunnel: { Address: string, RsdPort?: number } }} 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,82 +6,40 @@
  *   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),
-  };
-}
-
+/**
+ * @param {import('appium-ios-remotexpc').AppleTVPairingService} pairingService
+ * @param {number} timeoutMs
+ * @returns {{ startedAt: number, promise: Promise<AppleTVDevice[]> }}
+ */
 function discoverAppleTVPairingDevices(pairingService, timeoutMs) {
   const startedAt = performance.now();
   const promise = pairingService.discoverDevices({ timeoutMs });
   return { startedAt, promise };
 }
 
+/**
+ *
+ * @param {{ startedAt: number, promise: Promise<AppleTVDevice[]> }} discovery
+ * @param {number} timeoutMs
+ * @returns {Promise<AppleTVDevice[]>}
+ */
 async function waitForAppleTVPairingDiscovery(discovery, timeoutMs) {
   const progress = startTimeoutProgressLogger({
+    log,
     label: 'Waiting for Apple TV pairing discovery',
     startedAt: discovery.startedAt,
     timeoutMs,
@@ -92,7 +50,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 +59,50 @@ async function waitForAppleTVPairingDiscovery(discovery, timeoutMs) {
   }
 }
 
+/**
+ * @param {import('appium-ios-remotexpc').AppleTVPairingService} pairingService
+ * @param {string} deviceSelector
+ * @param {number} discoveryTimeoutMs
+ * @returns {Promise<{ success: boolean, deviceId: string, pairingFile?: string, error?: Error | null }>}
+ */
+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,34 +115,33 @@ 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');
   }
 }
 
 await main();
+
+/**
+ * @typedef {import('appium-ios-remotexpc').AppleTVDevice} AppleTVDevice
+ */

package/scripts/start-appletv-tunnel.mjs

@@ -11,18 +11,35 @@ 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;
 
+/** @type {(() => void)[]} */
 const registryWatcherStops = [];
 /** @type {Map<string, Promise<void>>} */
 const reconnectingByUdid = new Map();
@@ -32,6 +49,10 @@ const establishedTunnelsByUdid = new Map();
 /** @type {Map<string, () => void>} */
 const lifecycleWatchStopByUdid = new Map();
 
+/**
+ * @param {import('appium-ios-tuntap').TunnelConnection} tunnelConnection
+ * @returns {Promise<void>}
+ */
 async function closeTunnelQuietly(tunnelConnection) {
   try {
     await tunnelConnection.closer();
@@ -40,6 +61,10 @@ async function closeTunnelQuietly(tunnelConnection) {
   }
 }
 
+/**
+ * @param {string} udid
+ * @returns {void}
+ */
 function stopLifecycleWatch(udid) {
   const stop = lifecycleWatchStopByUdid.get(udid);
   if (stop) {
@@ -48,6 +73,58 @@ function stopLifecycleWatch(udid) {
   }
 }
 
+/**
+ *
+ * @param {import('appium-ios-remotexpc').AppleTVTunnelService} tunnelService
+ * @param {number} timeoutMs
+ * @returns {{ startedAt: number, promise: Promise<AppleTVDevice[]> }}
+ */
+function startDevicesDiscovery(tunnelService, timeoutMs) {
+  const startedAt = performance.now();
+  const promise = tunnelService.discoverDevices({ timeoutMs });
+  return { startedAt, promise };
+}
+
+/**
+ *
+ * @param {{ startedAt: number, promise: 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') || /** @type {Error} */ (err).message?.includes('No devices found');
+}
+
+/**
+ * @param {AppleTvEstablishedTunnel} result
+ * @returns {void}
+ */
 function registerEstablishedTunnel(result) {
   const udid = result.device.identifier;
   stopLifecycleWatch(udid);
@@ -61,41 +138,15 @@ function registerEstablishedTunnel(result) {
   }
   establishedTunnelsByUdid.set(udid, 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;
-}
+/** @type {import('appium-ios-remotexpc').AppleTVTunnelService | null} */
+let tunnelService = null;
 
 /**
- * @param {object} registry
+ * @param {import('appium-ios-remotexpc').TunnelRegistry} registry
  * @param {AppleTvEstablishedTunnel[]} successfulResults
+ * @param {object} callbacks
+ * @param {function({ udid: string, address: string }): Promise<void>} [callbacks.onTunnelDead]
  */
 function attachAppleTvTunnelRegistryLifecycleWatch(registry, successfulResults, callbacks = {}) {
   for (const result of successfulResults) {
@@ -129,7 +180,14 @@ function attachAppleTvTunnelRegistryLifecycleWatch(registry, successfulResults,
   );
 }
 
+/**
+ * @returns {void}
+ */
 function setupCleanupHandlers() {
+  /**
+   * @param {string} signal
+   * @returns {Promise<void>}
+   */
   const cleanup = async (signal) => {
     log.warn(`\nCleaning up (${signal})...`);
 
@@ -166,25 +224,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);
   });
 }
 
@@ -194,6 +254,7 @@ function setupCleanupHandlers() {
  */
 async function establishOneTunnel(startResult) {
   const { tcpSocket, psk, device } = startResult;
+  /** @type {{ notify: ((reason: string) => void) | null }} */
   const lifecycle = { notify: null };
 
   const tunnelConnection = await TunnelManager.getTunnelPsk(
@@ -211,6 +272,10 @@ async function establishOneTunnel(startResult) {
       RsdPort: tunnelConnection.RsdPort,
     },
     tunnelConnection,
+    /**
+     * @param {(reason: string) => void} handler
+     * @returns {void}
+     */
     registerOnDead: (handler) => {
       lifecycle.notify = handler;
     },
@@ -220,21 +285,14 @@ 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) {
+/**
+ * @param {AppleTvEstablishedTunnel} result
+ * @param {import('appium-ios-remotexpc').TunnelRegistryEntry | undefined} existing
+ * @param {number} now
+ * @returns {import('appium-ios-remotexpc').TunnelRegistryEntry}
+ */
+function buildAppleTvTunnelEntry(result, existing, now) {
   const udid = result.device.identifier;
-  const now = Date.now();
   const entry = {
     udid,
     deviceId: 0,
@@ -249,47 +307,31 @@ function buildAppleTvTunnelEntryBase(result, existing) {
   return entry;
 }
 
+/**
+ *
+ * @param {AppleTvEstablishedTunnel} result
+ * @returns {Promise<boolean>}
+ */
 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,
+  });
 }
 
+/**
+ *
+ * @param {object} opts
+ * @param {string} opts.udid
+ * @param {number} opts.maxRetries
+ * @param {import('appium-ios-remotexpc').AppleTVTunnelService} opts.tunnelService
+ * @param {function(string): Promise<void>} opts.reconnectTunnelByUdid
+ * @param {number} opts.discoveryTimeoutMs
+ * @returns {Promise<void>}
+ */
 async function runAppleTvReconnectAttempts({
   udid,
   maxRetries,
@@ -335,6 +377,14 @@ async function runAppleTvReconnectAttempts({
   log.error(`Reconnect retries exhausted for ${udid}`);
 }
 
+/**
+ *
+ * @param {object} opts
+ * @param {number} opts.reconnectRetries
+ * @param {import('appium-ios-remotexpc').AppleTVTunnelService} opts.tunnelService
+ * @param {number} opts.discoveryTimeoutMs
+ * @returns {function(string): Promise<void>}
+ */
 function createAppleTvReconnectTunnelByUdid({
   reconnectRetries,
   tunnelService,
@@ -382,17 +432,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 +451,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 +465,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 +506,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 +598,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) {
@@ -557,3 +623,7 @@ await main();
  * @property {import('appium-ios-tuntap').TunnelConnection} tunnelConnection
  * @property {(handler: (reason: string) => void) => void} registerOnDead
  */
+
+/**
+ * @typedef {import('appium-ios-remotexpc').AppleTVDevice} AppleTVDevice
+ */

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');
 
@@ -30,6 +40,10 @@ const establishedTunnelsByUdid = new Map();
 /** @type {Map<string, () => void>} */
 const lifecycleWatchStopByUdid = new Map();
 
+/**
+ * @param {import('appium-ios-tuntap').TunnelConnection} tunnelConnection
+ * @returns {Promise<void>}
+ */
 async function closeTunnelQuietly(tunnelConnection) {
   try {
     await tunnelConnection.closer();
@@ -38,6 +52,10 @@ async function closeTunnelQuietly(tunnelConnection) {
   }
 }
 
+/**
+ * @param {string} udid
+ * @returns {void}
+ */
 function stopLifecycleWatch(udid) {
   const stop = lifecycleWatchStopByUdid.get(udid);
   if (stop) {
@@ -46,6 +64,10 @@ function stopLifecycleWatch(udid) {
   }
 }
 
+/**
+ * @param {TunnelCreationSuccessResult} result
+ * @returns {void}
+ */
 function registerEstablishedTunnel(result) {
   const udid = result.device.Properties.SerialNumber;
   stopLifecycleWatch(udid);
@@ -60,6 +82,11 @@ function registerEstablishedTunnel(result) {
   establishedTunnelsByUdid.set(udid, result);
 }
 
+/**
+ *
+ * @param {string} connectionType
+ * @returns {number}
+ */
 function connectionTypeRank(connectionType) {
   if (connectionType === 'USB') {
     return 0;
@@ -94,48 +121,25 @@ 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) {
+/**
+ *
+ * @param {TunnelCreationSuccessResult} result
+ * @param {import('appium-ios-remotexpc').TunnelRegistryEntry | undefined} existing
+ * @param {number} now
+ * @returns {import('appium-ios-remotexpc').TunnelRegistryEntry}
+ */
+function buildTunnelEntry(result, existing, now) {
   const udid = result.device.Properties.SerialNumber;
-  const now = Date.now();
+  /** @type {import('appium-ios-remotexpc').TunnelRegistryEntry} */
   const entry = {
     udid,
     deviceId: result.device.DeviceID,
     address: result.tunnel.Address,
     rsdPort: result.tunnel.RsdPort,
     services: {},
+    // @ts-expect-error - connectionType is not typed
     connectionType: result.device.Properties.ConnectionType,
+    // @ts-expect-error - productId is not typed
     productId: result.device.Properties.ProductID,
     createdAt: existing?.createdAt ?? now,
     lastUpdated: now,
@@ -143,43 +147,21 @@ function buildTunnelEntryBase(result, existing) {
   return entry;
 }
 
+/**
+ * @param {TunnelCreationSuccessResult} result
+ * @returns {Promise<boolean>}
+ */
 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,
+  });
 }
 
+/** @type {(() => void)[]} */
 const registryWatcherStops = [];
 /** @type {Map<string, Promise<void>>} */
 const reconnectingByUdid = new Map();
@@ -187,8 +169,11 @@ const reconnectingByUdid = new Map();
 /**
  * When the native forwarder exits, drop the UDID from the HTTP registry and tear down state.
  *
- * @param {object} registry
+ * @param {import('appium-ios-remotexpc').TunnelRegistry} registry
  * @param {TunnelCreationSuccessResult[]} successful
+ * @param {object} callbacks
+ * @param {function({ udid: string, address: string }): Promise<void>} [callbacks.onTunnelDead]
+ * @returns {void}
  */
 function attachTunnelRegistryLifecycleWatch(registry, successful, callbacks = {}) {
   for (const result of successful) {
@@ -222,10 +207,15 @@ function attachTunnelRegistryLifecycleWatch(registry, successful, callbacks = {}
   );
 }
 
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
+/**
+ *
+ * @param {object} opts
+ * @param {string} opts.udid
+ * @param {number} opts.maxRetries
+ * @param {import('appium-ios-remotexpc').UsbmuxDevice} opts.device
+ * @param {function(string): Promise<void>} opts.reconnectTunnelByUdid
+ * @returns {Promise<void>}
+ */
 async function runReconnectAttempts({
   udid,
   maxRetries,
@@ -247,6 +237,7 @@ async function runReconnectAttempts({
         registryServer.getRegistry(),
         [result],
         {
+
           onTunnelDead: async ({ udid: droppedUdid }) => {
             await reconnectTunnelByUdid(droppedUdid);
           },
@@ -265,6 +256,12 @@ async function runReconnectAttempts({
   log.error(`Reconnect retries exhausted for ${udid}`);
 }
 
+/**
+ * @param {object} opts
+ * @param {number} opts.reconnectRetries
+ * @param {Map<string, import('appium-ios-remotexpc').UsbmuxDevice>} opts.devicesByUdid
+ * @returns {function(string): Promise<void>}
+ */
 function createReconnectTunnelByUdid({
   reconnectRetries,
   devicesByUdid,
@@ -299,7 +296,14 @@ function createReconnectTunnelByUdid({
   };
 }
 
+/**
+ * @returns {void}
+ */
 function setupCleanupHandlers() {
+  /**
+   * @param {string} signal
+   * @returns {Promise<void>}
+   */
   const cleanup = async (signal) => {
     log.warn(`\nCleaning up (${signal})...`);
 
@@ -328,28 +332,34 @@ 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);
   });
 }
 
+/**
+ * @param {import('appium-ios-remotexpc').UsbmuxDevice} device
+ * @returns {Promise<TunnelCreationSuccessResult>}
+ */
 async function createTunnelForDevice(device) {
   const udid = device.Properties.SerialNumber;
 
@@ -375,6 +385,7 @@ async function createTunnelForDevice(device) {
     log.info('CoreDeviceProxy started successfully');
 
     log.info(`Creating tunnel...`);
+    /** @type {{ notify: ((reason: string) => void) | null }} */
     const lifecycle = { notify: null };
     const tunnelConnection = await TunnelManager.getTunnel(
       socket,
@@ -391,7 +402,9 @@ async function createTunnelForDevice(device) {
     log.info(`   Tunnel Address: ${tunnelConnection.Address}`);
     log.info(`   Tunnel RsdPort: ${tunnelConnection.RsdPort}`);
 
+    /** @type {TunnelCreationSuccessResult} */
     const result = {
+      // @ts-expect-error - device is not typed
       device,
       tunnel: {
         Address: tunnelConnection.Address,
@@ -399,6 +412,10 @@ async function createTunnelForDevice(device) {
       },
       success: true,
       tunnelConnection,
+      /**
+       * @param {(reason: string) => void} handler
+       * @returns {void}
+       */
       registerOnDead: (handler) => {
         lifecycle.notify = handler;
       },
@@ -410,6 +427,7 @@ async function createTunnelForDevice(device) {
     const errorMessage = `Failed to create tunnel for device ${udid}: ${error}`;
     log.error(`❌ ${errorMessage}`);
     return {
+      // @ts-expect-error - device is not typed
       device,
       tunnel: { Address: '', RsdPort: 0 },
       success: false,
@@ -418,6 +436,9 @@ async function createTunnelForDevice(device) {
   }
 }
 
+/**
+ * @returns {Promise<void>}
+ */
 async function main() {
   setupCleanupHandlers();
 
@@ -433,18 +454,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 +499,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 +529,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;
@@ -548,6 +565,10 @@ async function main() {
           registryServer.getRegistry(),
           [result],
           {
+            /**
+             * @param {{ udid: string }} ctx
+             * @returns {Promise<void>}
+             */
             onTunnelDead: async ({ udid }) => {
               await reconnectTunnelByUdid(udid);
             },
@@ -560,19 +581,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`);
@@ -610,8 +631,9 @@ await main();
  * Successful tunnel row (USB lockdown + CoreDeviceProxy) used for the registry and lifecycle watch.
  *
  * @typedef {object} TunnelCreationSuccessResult
- * @property {{ Properties: { SerialNumber: string }, DeviceID: number }} device
+ * @property {{ Properties: { SerialNumber: string, [key: string]: unknown }, DeviceID: number }} device
  * @property {{ Address: string, RsdPort?: number }} tunnel
  * @property {import('appium-ios-tuntap').TunnelConnection} tunnelConnection
  * @property {(handler: (reason: string) => void) => void} registerOnDead
+ * @property {boolean} success
  */