@loadmill/droid-cua 2.43.0 → 2.44.0

package/build/src/commands/help.js

@@ -19,6 +19,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  droid-cua --target web --instructions <file> [options]' });
     addOutput({ type: 'info', text: '  droid-cua --target desktop --instructions <file> [options]' });
     addOutput({ type: 'info', text: '  droid-cua --device-source lambdatest --instructions <file> [options]' });
+    addOutput({ type: 'info', text: '  droid-cua ios-device check [--udid <udid>] [--ios-team <TEAMID>] [--fix]' });
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Options:' });
     addOutput({ type: 'info', text: '  --target <kind>        Target kind: mobile (default), web, or desktop' });
@@ -27,8 +28,9 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  --desktop-window <id>  Select a window within --desktop-app' });
     addOutput({ type: 'info', text: '  --desktop-input <mode> Physical pointer (default); accessibility requires --desktop-app' });
     addOutput({ type: 'info', text: '  --list-desktop-apps    List running desktop apps and windows' });
-    addOutput({ type: 'info', text: '  --avd <name>           Device name (Android device ID/serial or iOS Simulator)' });
+    addOutput({ type: 'info', text: '  --avd <name>           Device name (Android device ID/serial, iOS Simulator, or ios-device:<udid|auto>)' });
     addOutput({ type: 'info', text: '  --platform <platform>  Force platform: android or ios' });
+    addOutput({ type: 'info', text: '  --ios-team <TEAMID>    Apple team that signs the helper app on a USB iPhone' });
     addOutput({ type: 'info', text: '  --device-source <src>  Mobile source: local (default) or lambdatest' });
     addOutput({ type: 'info', text: '  --device-name <name>   LambdaTest real device name' });
     addOutput({ type: 'info', text: '  --os-version <version> LambdaTest OS version' });
@@ -55,7 +57,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  --record               Record screenshots during execution' });
     addOutput({ type: 'info', text: '  --explain              Explain non-obvious decisions and completion evidence' });
     addOutput({ type: 'info', text: '  --report [path]        Save a self-contained HTML report locally' });
-    addOutput({ type: 'info', text: '  --network-proxy        Forward local mobile traffic through 127.0.0.1:8765 without capture' });
+    addOutput({ type: 'info', text: '  --network-proxy        Forward local mobile traffic through port 8765 without capture (all Mac addresses for iPhones and Android phones)' });
     addOutput({ type: 'info', text: '  --capture-network      Capture local mobile or browser test traffic to one JSONL log per test' });
     addOutput({ type: 'info', text: '  --no-cloud-report      Skip uploading the HTML report and screenshots to Loadmill' });
     addOutput({ type: 'info', text: '  --report-metadata <path> Write uploaded Loadmill report metadata as JSON' });
@@ -77,7 +79,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Platform Support:' });
     addOutput({ type: 'info', text: '  Android: Uses ADB to communicate with Android devices (physical or emulator)' });
-    addOutput({ type: 'info', text: '  iOS:     Uses Appium + XCUITest for iOS Simulator automation' });
+    addOutput({ type: 'info', text: '  iOS:     Uses Appium + XCUITest for iOS Simulators and iPhones connected by USB' });
     addOutput({ type: 'info', text: '  LambdaTest: Uses real cloud devices for headless mobile runs' });
     addOutput({ type: 'info', text: '  Web:     Uses Playwright with installed Google Chrome or Microsoft Edge for browser execution' });
     addOutput({ type: 'info', text: '  Desktop: Controls the primary display or a selected application on macOS and Windows' });
@@ -94,11 +96,20 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  3. XCUITest driver: appium driver install xcuitest' });
     addOutput({ type: 'info', text: '  Note: Appium server is auto-started when iOS platform is detected' });
     addOutput({ type: 'info', text: '' });
+    addOutput({ type: 'info', text: 'iPhone over USB (macOS only):' });
+    addOutput({ type: 'info', text: '  1. Xcode that supports the iPhone\'s iOS, opened once' });
+    addOutput({ type: 'info', text: '  2. Your Apple ID in Xcode, on your company\'s paid Apple Developer team' });
+    addOutput({ type: 'info', text: '     (Developer role with Access to Certificates, Identifiers & Profiles)' });
+    addOutput({ type: 'info', text: '  3. On the iPhone: tap Trust, turn on Developer Mode, set Auto-Lock to Never' });
+    addOutput({ type: 'info', text: '  4. droid-cua ios-device check --fix   (checks the iPhone and installs the helper app)' });
+    addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Examples:' });
     addOutput({ type: 'info', text: '  droid-cua --avd adb:emulator-5554        (Connected Android target by adb serial)' });
     addOutput({ type: 'info', text: '  droid-cua --avd avd:Pixel_8_API_35       (Launch Android AVD then connect)' });
     addOutput({ type: 'info', text: '  droid-cua --avd "iPhone 16"             (iOS Simulator, auto-detected)' });
     addOutput({ type: 'info', text: '  droid-cua --platform ios --avd MySim    (Force iOS platform)' });
+    addOutput({ type: 'info', text: '  droid-cua run tests/login.dcua --avd ios-device:auto   (iPhone connected by USB)' });
+    addOutput({ type: 'info', text: '  droid-cua run tests/login.dcua --avd ios-device:<udid> --ios-team ABCDE12345' });
     addOutput({ type: 'info', text: '  droid-cua run tests/login.dcua admin/refund.dcua --context app/context.md' });
     addOutput({ type: 'info', text: '  droid-cua --instructions tests/login.dcua --context app/context.md' });
     addOutput({ type: 'info', text: '  droid-cua --instructions tests --test-data tests/test-data.md --scenario "Run every checkout test with each buyer account"' });

package/build/src/core/execution-engine.js

@@ -206,6 +206,9 @@ function getInstructionScrollDirection(instruction) {
         return null;
     }
     const normalizedInstruction = instruction.toLowerCase();
+    if ((normalizedInstruction.match(/\bscroll/g) || []).length > 1) {
+        return null;
+    }
     if (normalizedInstruction.includes("scroll down")) {
         return 1;
     }

package/build/src/desktop-shared/ios-real-device.js

@@ -0,0 +1,82 @@
+import { iosDeviceLabel, iosDeviceStateHint } from "../cli/ios-device-list.js";
+import { describeFailure } from "../device/ios/real-device/readiness.js";
+import { IOS_DEVICE_PREFIX, parseIosDeviceToken } from "../device/ios/real-device/session.js";
+export const IPHONE_STATUS_EVENT = "ios_device.status";
+const TEAM_ID_PATTERN = /^[A-Z0-9]{10}$/;
+const CAUSE_REMEDIATION = {
+    "command-line-tools-selected": [{ kind: "run_fix", label: "Set Xcode Developer Path", fixId: "ios_set_xcode_developer_path" }],
+    "xcode-license": [{ kind: "run_fix", label: "Accept Xcode License", fixId: "ios_accept_xcode_license" }],
+    "ios-platform-missing": [{ kind: "run_fix", label: "Download iOS Platform", fixId: "ios_download_ios_platform" }],
+};
+const XCODE_CHECK_IDS = ["xcode_devicectl", "ios_platform"];
+export function iphoneDeviceOptions(devices) {
+    return devices
+        .filter((device) => device.transport === "wired" && device.udid)
+        .map((device) => {
+        const hint = iosDeviceStateHint(device);
+        return {
+            name: `${IOS_DEVICE_PREFIX}${device.udid}`,
+            label: iosDeviceLabel(device),
+            platform: "ios",
+            running: true,
+            iosKind: "device",
+            iosUdid: device.udid,
+            ...(hint ? { iosStateHint: hint } : {}),
+        };
+    })
+        .sort((a, b) => a.label.localeCompare(b.label));
+}
+export function isIphoneDeviceName(deviceName) {
+    return parseIosDeviceToken(deviceName) !== null;
+}
+export function toSetupCheckResult(result) {
+    const remediation = result.remediation ?? CAUSE_REMEDIATION[result.cause];
+    return {
+        id: result.id,
+        status: result.status,
+        title: result.title,
+        summary: result.summary,
+        ...(result.details ? { details: result.details } : {}),
+        blocking: result.blocking,
+        checkedAt: result.checkedAt,
+        ...(remediation ? { remediation } : {}),
+        ...(result.kind ? { kind: result.kind } : {}),
+        ...(result.blockedBy ? { blockedBy: result.blockedBy } : {}),
+    };
+}
+export function orderIphoneSetupChecks(deviceResults, toolResults) {
+    const isXcode = (result) => XCODE_CHECK_IDS.includes(result.id);
+    return [...deviceResults.filter(isXcode), ...toolResults, ...deviceResults.filter((result) => !isXcode(result))];
+}
+export function iphoneFixResult(checkId, results) {
+    const result = results.find((entry) => entry.id === checkId);
+    if (result?.status === "pass") {
+        return { ok: true, summary: "Fix completed successfully.", details: result.summary };
+    }
+    return { ok: false, summary: "Fix failed.", details: result ? describeFailure(result) : `Unknown iPhone check: ${checkId}.` };
+}
+export function normalizeTeamId(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim().toUpperCase();
+    return TEAM_ID_PATTERN.test(trimmed) ? trimmed : null;
+}
+export function iphoneTeamOptions(teams) {
+    return teams.map((team) => ({
+        teamId: team.teamId,
+        label: team.teamName ? `${team.teamName} (${team.teamId})` : team.teamId,
+    }));
+}
+export function iphoneConnectOptions(deviceName, teamId) {
+    if (!isIphoneDeviceName(deviceName))
+        return {};
+    const normalized = normalizeTeamId(teamId);
+    return normalized ? { teamId: normalized } : {};
+}
+export function iphoneStatusLogEvent({ status, message }) {
+    return {
+        kind: status === "unlocked" ? "success" : "warning",
+        text: message,
+        payload: { event: IPHONE_STATUS_EVENT, status },
+    };
+}

package/build/src/device/factory.js

@@ -9,6 +9,7 @@ import * as cloudConnection from "./cloud/connection.js";
 import * as cloudActions from "./cloud/actions.js";
 import * as iosConnection from "./ios/connection.js";
 import * as iosActions from "./ios/actions.js";
+import { parseIosDeviceToken } from "./ios/real-device/session.js";
 // Current platform state
 let currentPlatform = null;
 let currentSource = "local";
@@ -25,6 +26,9 @@ export function detectPlatform(deviceName) {
     if (process.env.DROID_CUA_PLATFORM === "android") {
         return "android";
     }
+    if (parseIosDeviceToken(deviceName)) {
+        return "ios";
+    }
     // Auto-detect from device name
     if (deviceName) {
         const lower = deviceName.toLowerCase();

package/build/src/device/ios/actions.js

@@ -7,25 +7,55 @@ import * as appium from "./appium-client.js";
 import { buildActionEventMeta } from "../action-event-meta.js";
 import { buildIosAppSwitcherGesture, buildMobileKeypressPayload, getIosTransport, normalizeMobileKeypress } from "../mobile-keypress.js";
 import { actionForErrorLog, buildActionErrorOutput, buildDebugTextField, buildSensitiveDebugFields, buildTypeActionPayload, buildTypeActionText, isSensitiveAction, } from "../sensitive-action.js";
-import { getActiveSession, getDevicePixelRatio } from "./connection.js";
+import { getActiveSession, getDevicePixelRatio, recoverRealDevice } from "./connection.js";
 import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug, truncateForDebug } from "../../utils/desktop-debug.js";
 import { getConfiguredStepDelayMs } from "../../utils/step-delay.js";
 import { resolveScrollGesture } from "../scroll-gesture.js";
-import { closeAppiumKeyboardWithTap } from "../keyboard.js";
+import { KEYBOARD_CLOSE_RESULTS, closeAppiumKeyboardWithTap } from "../keyboard.js";
+export function realDeviceScreenBounds(session) {
+    const size = session?.realDevice ? session.windowSize : null;
+    if (!Number.isFinite(size?.width) || !Number.isFinite(size?.height)) {
+        return {};
+    }
+    return { minX: 0, maxX: Math.round(size.width) - 1, minY: 0, maxY: Math.round(size.height) - 1 };
+}
+function clampToBounds(value, min, max) {
+    return Number.isFinite(min) && Number.isFinite(max) ? Math.min(Math.max(value, min), max) : value;
+}
 export async function closeKeyboard(_deviceId, { dismissalPoint = null, scale = 1 } = {}) {
     const session = getActiveSession();
     if (!session) {
         throw new Error("No active iOS session");
     }
     const dpr = getDevicePixelRatio();
-    const tap = dismissalPoint
-        ? () => appium.tap(session.sessionId, Math.round((dismissalPoint.x / scale) / dpr), Math.round((dismissalPoint.y / scale) / dpr))
+    const tapPoint = dismissalPoint
+        ? { x: Math.round((dismissalPoint.x / scale) / dpr), y: Math.round((dismissalPoint.y / scale) / dpr) }
         : null;
-    return closeAppiumKeyboardWithTap({
-        isKeyboardShown: () => appium.isKeyboardShown(session.sessionId),
-        tap,
+    const keyboardShownReadings = [];
+    const result = await closeAppiumKeyboardWithTap({
+        isKeyboardShown: async () => {
+            const shown = await appium.isKeyboardShown(session.sessionId);
+            keyboardShownReadings.push(shown);
+            return shown;
+        },
+        tap: tapPoint ? () => appium.tap(session.sessionId, tapPoint.x, tapPoint.y) : null,
     });
+    if (result.status === KEYBOARD_CLOSE_RESULTS.FAILED) {
+        const details = {
+            platform: "ios",
+            realDevice: session.realDevice === true,
+            dismissalPoint,
+            tapPoint,
+            unit: "points",
+            keyboardShownBefore: keyboardShownReadings[0] ?? null,
+            keyboardShownAfter: keyboardShownReadings[1] ?? null,
+            error: result.error ?? null,
+        };
+        logger.debug("iOS keyboard close failed", details);
+        emitDesktopDebug("device.keyboard.close_failed", "device", {}, details);
+    }
+    return result;
 }
 /**
  * Handle an action from the CUA model
@@ -100,7 +130,8 @@ export async function handleModelAction(simulatorId, action, scale = 1.0, contex
                     scale,
                     dpr,
                     fallbackStartX: 197,
-                    fallbackStartY: 426
+                    fallbackStartY: 426,
+                    ...realDeviceScreenBounds(session)
                 });
                 addOutput({
                     type: "action",
@@ -117,10 +148,11 @@ export async function handleModelAction(simulatorId, action, scale = 1.0, contex
                     const start = path[0];
                     const end = path[path.length - 1];
                     // Convert to pixels then to logical points
-                    const startX = Math.round((start.x / scale) / dpr);
-                    const startY = Math.round((start.y / scale) / dpr);
-                    const endX = Math.round((end.x / scale) / dpr);
-                    const endY = Math.round((end.y / scale) / dpr);
+                    const { minX, maxX, minY, maxY } = realDeviceScreenBounds(session);
+                    const startX = clampToBounds(Math.round((start.x / scale) / dpr), minX, maxX);
+                    const startY = clampToBounds(Math.round((start.y / scale) / dpr), minY, maxY);
+                    const endX = clampToBounds(Math.round((end.x / scale) / dpr), minX, maxX);
+                    const endY = clampToBounds(Math.round((end.y / scale) / dpr), minY, maxY);
                     addOutput({
                         type: "action",
                         text: `Dragging from (${startX}, ${startY}) to (${endX}, ${endY}) points`,
@@ -213,6 +245,10 @@ export async function handleModelAction(simulatorId, action, scale = 1.0, contex
             }
         });
         addOutput({ type: "info", text: "Full error details have been logged to the debug log." });
+        if (session.realDevice) {
+            await recoverRealDevice(error, { log: (text) => addOutput({ type: "info", text }) })
+                .catch((recoveryError) => addOutput({ type: "error", text: recoveryError.message }));
+        }
         return { success: false, error: outputError.message };
     }
 }

package/build/src/device/ios/appium-server.js

@@ -5,30 +5,19 @@
  * Auto-starts if not running, cleans up on process exit.
  */
 import { spawn } from "child_process";
-import { existsSync, readdirSync } from "fs";
+import { existsSync } from "fs";
+import os from "os";
 import path from "path";
-import { COMMON_NODE_BIN_DIRS, makeNodeCliCommandEnv } from "./node-cli-env.js";
+import { COMMON_NODE_BIN_DIRS, listNvmNodeBinDirs, makeNodeCliCommandEnv } from "./node-cli-env.js";
 let appiumProcess = null;
 let cleanupRegistered = false;
 function getAppiumBaseUrl() {
     return process.env.APPIUM_URL || "http://localhost:4723";
 }
-function collectNvmAppiumCandidates() {
-    const home = process.env.HOME;
-    if (!home)
-        return [];
-    const nvmNodeVersionsDir = path.join(home, ".nvm", "versions", "node");
-    if (!existsSync(nvmNodeVersionsDir))
-        return [];
-    try {
-        return readdirSync(nvmNodeVersionsDir)
-            .map((versionDir) => path.join(nvmNodeVersionsDir, versionDir, "bin", "appium"))
-            .filter((candidate) => existsSync(candidate))
-            .reverse();
-    }
-    catch {
-        return [];
-    }
+export function collectNvmAppiumCandidates(home = os.homedir()) {
+    return listNvmNodeBinDirs(home)
+        .map((binDir) => path.join(binDir, "appium"))
+        .filter((candidate) => existsSync(candidate));
 }
 export function resolveAppiumCommand() {
     const explicit = process.env.DROID_CUA_APPIUM_PATH?.trim() || process.env.APPIUM_PATH?.trim();

package/build/src/device/ios/connection.js

@@ -10,6 +10,7 @@ import { startAppium, setupAppiumCleanup } from "./appium-server.js";
 import * as appium from "./appium-client.js";
 import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug } from "../../utils/desktop-debug.js";
+import { IOS_DEVICE_PREFIX, createRealDeviceSession, parseIosDeviceToken, recoverIfLocked, recoverRealDeviceSession, startRealDeviceSession, } from "./real-device/session.js";
 const execAsync = promisify(exec);
 // Active session state
 let activeSession = null;
@@ -157,6 +158,13 @@ export async function connectToDevice(simulatorName, options = {}) {
     setupAppiumCleanup();
     // Start Appium if not running
     await startAppium({ log });
+    const realDevice = parseIosDeviceToken(simulatorName);
+    if (realDevice) {
+        return connectToRealDevice(realDevice.udid, {
+            log,
+            teamId: resolveRealDeviceTeamId(realDevice.udid, options.teamId),
+        });
+    }
     // If no simulator specified, auto-detect
     if (!simulatorName) {
         const found = await findAnySimulator();
@@ -194,6 +202,22 @@ export async function connectToDevice(simulatorName, options = {}) {
     });
     return simulator.udid;
 }
+export function resolveRealDeviceTeamId(udid, explicitTeamId = null) {
+    const previous = activeSession?.realDevice && activeSession.udid === udid ? activeSession.teamId : null;
+    return explicitTeamId || previous || process.env.DROID_CUA_IOS_TEAM_ID || null;
+}
+async function connectToRealDevice(udid, { log, teamId }) {
+    activeSession = await startRealDeviceSession({ udid, teamId, log });
+    log(`Connected to iPhone "${activeSession.deviceName}" (${activeSession.udid})`);
+    emitDesktopDebug("device.connect", "device", {}, {
+        platform: "ios",
+        stage: "success",
+        realDevice: true,
+        deviceName: activeSession.deviceName,
+        udid: activeSession.udid
+    });
+    return `${IOS_DEVICE_PREFIX}${activeSession.udid}`;
+}
 /**
  * Get device info (screen dimensions and scale)
  * @param {string} simulatorId - The UDID returned from connectToDevice
@@ -216,15 +240,18 @@ export async function getDeviceInfo(simulatorId, options = {}) {
     log(`Device pixel ratio: ${devicePixelRatio}x (${pixelWidth}x${pixelHeight} pixels, ${windowSize.width}x${windowSize.height} points)`);
     // Store the pixel ratio for coordinate conversion
     activeSession.devicePixelRatio = devicePixelRatio;
+    activeSession.windowSize = windowSize;
     // Use pixel dimensions as the "real" resolution (like Android does)
     const targetWidth = 400;
     const scale = pixelWidth > targetWidth ? targetWidth / pixelWidth : 1.0;
     const scaledWidth = Math.round(pixelWidth * scale);
     const scaledHeight = Math.round(pixelHeight * scale);
+    const name = activeSession.realDevice ? activeSession.deviceName : activeSession.simulatorName;
+    const model = activeSession.realDevice ? activeSession.model : activeSession.simulatorName;
     return {
         platform: "ios",
-        device_name: activeSession?.simulatorName || simulatorId,
-        model: activeSession?.simulatorName || simulatorId,
+        device_name: name || simulatorId,
+        model: model || simulatorId,
         device_width: pixelWidth,
         device_height: pixelHeight,
         scaled_width: scaledWidth,
@@ -238,9 +265,24 @@ export async function getDeviceInfo(simulatorId, options = {}) {
  * @param {object} deviceInfo
  * @returns {Promise<string>}
  */
-export async function getScreenshotAsBase64(simulatorId, deviceInfo) {
+export async function getScreenshotAsBase64(simulatorId, deviceInfo, { deps } = {}) {
     await ensureSessionAlive();
-    const rawBase64 = await appium.getScreenshot(activeSession.sessionId);
+    if (activeSession.realDevice) {
+        const sessionId = await recoverIfLocked(activeSession, { deps });
+        if (sessionId) {
+            activeSession.sessionId = sessionId;
+        }
+    }
+    let rawBase64;
+    try {
+        rawBase64 = await appium.getScreenshot(activeSession.sessionId);
+    }
+    catch (error) {
+        if (!await recoverRealDevice(error)) {
+            throw error;
+        }
+        rawBase64 = await appium.getScreenshot(activeSession.sessionId);
+    }
     let buffer = Buffer.from(rawBase64, "base64");
     logger.debug(`iOS screenshot captured: ${buffer.length} bytes before scaling`);
     if (deviceInfo.scale < 1.0) {
@@ -279,14 +321,20 @@ async function ensureSessionAlive() {
             reason: "appium session no longer active"
         });
         console.log("Session died, recreating...");
-        const session = await appium.createSession({
-            platformName: "iOS",
-            "appium:automationName": "XCUITest",
-            "appium:deviceName": activeSession.simulatorName,
-            "appium:udid": activeSession.udid,
-            "appium:noReset": true,
-            "appium:shouldTerminateApp": false,
-        });
+        const session = activeSession.realDevice
+            ? await createRealDeviceSession({
+                udid: activeSession.udid,
+                bundleIdBase: activeSession.bundleIdBase,
+                deviceName: activeSession.deviceName,
+            })
+            : await appium.createSession({
+                platformName: "iOS",
+                "appium:automationName": "XCUITest",
+                "appium:deviceName": activeSession.simulatorName,
+                "appium:udid": activeSession.udid,
+                "appium:noReset": true,
+                "appium:shouldTerminateApp": false,
+            });
         activeSession.sessionId = session.sessionId;
         emitDesktopDebug("reconnect.attempt", "device", {}, {
             platform: "ios",
@@ -295,6 +343,17 @@ async function ensureSessionAlive() {
         });
     }
 }
+export async function recoverRealDevice(error, { log = console.log, deps } = {}) {
+    if (!activeSession?.realDevice) {
+        return false;
+    }
+    const sessionId = await recoverRealDeviceSession(activeSession, error, { log, deps });
+    if (!sessionId) {
+        return false;
+    }
+    activeSession.sessionId = sessionId;
+    return true;
+}
 /**
  * Get the active session (for use by actions module)
  * @returns {object|null}

package/build/src/device/ios/node-cli-env.js

@@ -1,3 +1,5 @@
+import { accessSync, constants as fsConstants, readdirSync } from "fs";
+import os from "os";
 import path from "path";
 export const COMMON_NODE_BIN_DIRS = ["/opt/homebrew/bin", "/usr/local/bin", "/opt/local/bin"];
 function prependPathEntries(entries, originalPath) {
@@ -26,3 +28,56 @@ export function makeNodeCliCommandEnv(command) {
         PATH: prependPathEntries(binDirs, process.env.PATH)
     };
 }
+function parseNodeVersion(name) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(name);
+    return match ? match.slice(1).map(Number) : null;
+}
+function compareVersionsDescending(a, b) {
+    for (let i = 0; i < 3; i += 1) {
+        if (a[i] !== b[i])
+            return b[i] - a[i];
+    }
+    return 0;
+}
+function isExecutable(filePath) {
+    try {
+        accessSync(filePath, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function listNvmNodeBinDirs(home = os.homedir()) {
+    if (!home)
+        return [];
+    const versionsDir = path.join(home, ".nvm", "versions", "node");
+    let names;
+    try {
+        names = readdirSync(versionsDir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .map((name) => ({ name, version: parseNodeVersion(name) }))
+        .filter((entry) => entry.version)
+        .sort((a, b) => compareVersionsDescending(a.version, b.version))
+        .map((entry) => path.join(versionsDir, entry.name, "bin"));
+}
+export function resolveNodeCliCommand(command, { pathEnv = process.env.PATH, commonDirs = COMMON_NODE_BIN_DIRS, home = os.homedir() } = {}) {
+    const pathDirs = pathEnv
+        ?.split(path.delimiter)
+        .map((dir) => dir.trim())
+        .filter(Boolean) ?? [];
+    for (const dir of new Set([...pathDirs, ...commonDirs])) {
+        const candidate = path.join(dir, command);
+        if (isExecutable(candidate))
+            return candidate;
+    }
+    const nvmBinDir = listNvmNodeBinDirs(home).find((dir) => isExecutable(path.join(dir, "node")));
+    if (nvmBinDir && isExecutable(path.join(nvmBinDir, command))) {
+        return path.join(nvmBinDir, command);
+    }
+    return command;
+}

package/build/src/device/ios/real-device/device-state.js

@@ -0,0 +1,40 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_DIR = path.join(os.homedir(), ".droid-cua", "ios-devices");
+function statePath(dir) {
+    return path.join(dir, "state.json");
+}
+async function readAll(dir) {
+    try {
+        return JSON.parse(await readFile(statePath(dir), "utf8")) || {};
+    }
+    catch {
+        return {};
+    }
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export async function readDeviceState(udid, { dir = DEFAULT_DIR } = {}) {
+    const all = await readAll(dir);
+    return all[udid] ?? null;
+}
+export async function updateDeviceState(udid, patch, { dir = DEFAULT_DIR } = {}) {
+    const all = await readAll(dir);
+    const current = all[udid] ?? {};
+    const next = { ...current };
+    for (const [key, value] of Object.entries(patch)) {
+        next[key] = isPlainObject(value) && isPlainObject(current[key]) ? { ...current[key], ...value } : value;
+    }
+    all[udid] = next;
+    await mkdir(dir, { recursive: true });
+    const tempPath = `${statePath(dir)}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tempPath, `${JSON.stringify(all, null, 2)}\n`, "utf8");
+    await rename(tempPath, statePath(dir));
+    return next;
+}
+export async function didIosVersionChange(udid, currentVersion, { dir = DEFAULT_DIR } = {}) {
+    const state = await readDeviceState(udid, { dir });
+    return Boolean(state?.lastIosVersion) && state.lastIosVersion !== currentVersion;
+}