@autifyhq/aximo-cli 0.6.0 → 0.7.0

package/dist/commands/mobile/install.js

@@ -1,8 +1,12 @@
 import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
 import { extname, resolve } from "node:path";
 import { defineCommand } from "citty";
 import { resolveAndroidSerial, resolveIosUdid } from "../../mobile-control/devices.js";
 import { execBinary } from "../../mobile-control/exec.js";
+import { ensureInstallableIpa } from "../../mobile-control/ios-auto-resign.js";
+import { installIosApp } from "../../mobile-control/ios-devicectl.js";
+import { mobileErrorHint } from "../../mobile-control/mobile-errors.js";
 import { formatError, formatSuccess, printResult } from "../../output.js";
 import { parsePlatformArg } from "./register-core.js";
 function inferPlatform(appPath) {
@@ -15,9 +19,10 @@ function inferPlatform(appPath) {
 }
 /**
  * Install an app on the connected phone: Android `.apk` via `adb install -r`,
- * iOS `.ipa` via `idb install`. The iOS build must be signed for the device.
+ * iOS `.ipa` via devicectl — auto-re-signed for the device first when its
+ * signature doesn't already cover it (disable with AXIMO_IOS_NO_RESIGN).
  */
-export async function runMobileInstall(options, exec = execBinary) {
+export async function runMobileInstall(options, exec = execBinary, ensureInstallable = ensureInstallableIpa, installIos = installIosApp) {
     if (!options.app) {
         return formatError("validation_error", "App path is required (--app <path-to-.apk|.ipa>).", false);
     }
@@ -40,24 +45,50 @@ export async function runMobileInstall(options, exec = execBinary) {
         return formatError("validation_error", err instanceof Error ? err.message : String(err), false);
     }
     try {
-        const { stdout } = platform === "ios"
-            ? await exec("idb", ["install", "--udid", target, appPath])
-            : await exec("adb", ["-s", target, "install", "-r", appPath]);
-        return formatSuccess({
-            platform,
-            ...(platform === "ios" ? { udid: target } : { serial: target }),
-            app: appPath,
-            output: stdout.toString("utf-8").trim(),
+        if (platform === "android") {
+            const { stdout } = await exec("adb", ["-s", target, "install", "-r", appPath]);
+            return formatSuccess({
+                platform,
+                serial: target,
+                app: appPath,
+                output: stdout.toString("utf-8").trim(),
+            });
+        }
+        const ensured = await ensureInstallable({
+            ipaPath: appPath,
+            udid: target,
+            log: (message) => console.error(message),
         });
+        try {
+            const output = await installIos(target, ensured.ipaPath, exec);
+            return formatSuccess({
+                platform,
+                udid: target,
+                app: appPath,
+                output,
+                ...(ensured.resigned
+                    ? {
+                        resigned: true,
+                        originalBundleId: ensured.originalBundleId,
+                        installedBundleId: ensured.installedBundleId,
+                    }
+                    : {}),
+            });
+        }
+        finally {
+            if (ensured.resigned)
+                await rm(ensured.ipaPath, { force: true }).catch(() => { });
+        }
     }
     catch (err) {
-        return formatError("api_error", err instanceof Error ? err.message : String(err), false);
+        const message = err instanceof Error ? err.message : String(err);
+        return formatError("api_error", message, false, mobileErrorHint(message, platform));
     }
 }
 export default defineCommand({
     meta: {
         name: "install",
-        description: "Install an app on the connected phone (.apk via adb, .ipa via idb)",
+        description: "Install an app on the connected phone (.apk via adb, .ipa auto-re-signed + devicectl)",
     },
     args: {
         app: { type: "string", description: "Path to the .apk or .ipa to install", required: true },

package/dist/commands/mobile/install.test.js

@@ -1,4 +1,4 @@
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -74,17 +74,55 @@ describe("runMobileInstall", () => {
         expect(install().args.slice(0, 2)).toEqual(["-s", "R1"]);
         expect(install().args).toEqual(expect.arrayContaining(["install", "-r"]));
     });
-    it("installs an .ipa via `idb install --udid <udid>`", async () => {
-        const { exec, install } = execWith({ out: "Installed" });
-        const res = await runMobileInstall({ app: ipaPath }, exec);
+    it("installs an .ipa via devicectl, auto-resigning when needed", async () => {
+        const { exec } = execWith();
+        const ensureInstallable = vi.fn(async (_opts) => ({
+            ipaPath: join(dir, "app-resigned.ipa"),
+            resigned: true,
+            originalBundleId: "com.example.app",
+            installedBundleId: "com.aximo.resign.team.xctrunner",
+        }));
+        const installIos = vi.fn(async () => "App installed:");
+        const res = await runMobileInstall({ app: ipaPath }, exec, ensureInstallable, installIos);
         expect(res.ok).toBe(true);
         if (res.ok) {
             expect(res.data.platform).toBe("ios");
             expect(res.data.udid).toBe("00008030-ABC");
             expect(res.data.serial).toBeUndefined();
+            expect(res.data.resigned).toBe(true);
+            expect(res.data.originalBundleId).toBe("com.example.app");
+            expect(res.data.installedBundleId).toBe("com.aximo.resign.team.xctrunner");
         }
-        expect(install().file).toBe("idb");
-        expect(install().args).toEqual(["install", "--udid", "00008030-ABC", ipaPath]);
+        expect(vi.mocked(ensureInstallable).mock.calls[0]?.[0]).toMatchObject({
+            ipaPath,
+            udid: "00008030-ABC",
+        });
+        expect(installIos).toHaveBeenCalledWith("00008030-ABC", join(dir, "app-resigned.ipa"), exec);
+    });
+    it("omits resign metadata when the .ipa was already installable", async () => {
+        const { exec } = execWith();
+        const ensureInstallable = vi.fn(async () => ({
+            ipaPath,
+            resigned: false,
+            originalBundleId: "com.example.app",
+            installedBundleId: "com.example.app",
+        }));
+        const installIos = vi.fn(async () => "App installed:");
+        const res = await runMobileInstall({ app: ipaPath }, exec, ensureInstallable, installIos);
+        expect(res.ok).toBe(true);
+        if (res.ok)
+            expect(res.data.resigned).toBeUndefined();
+    });
+    it("maps an iOS resign failure to an error envelope with hint", async () => {
+        const { exec } = execWith();
+        const ensureInstallable = vi.fn(async () => {
+            throw new Error("app.ipa is FairPlay-encrypted (an App Store download)");
+        });
+        const installIos = vi.fn(async () => "");
+        const res = await runMobileInstall({ app: ipaPath }, exec, ensureInstallable, installIos);
+        expect(res.ok).toBe(false);
+        if (!res.ok)
+            expect(res.error.message).toMatch(/FairPlay/);
     });
     it("honors an explicit --platform override", async () => {
         const { exec, install } = execWith();

package/dist/commands/mobile/list.d.ts

@@ -4,6 +4,8 @@ import type { ExecFn } from "../../mobile-control/exec.js";
 export interface MobileListResult {
     androidDevices: AndroidDevice[];
     iosDevices: IosPhysicalDevice[];
+    /** Per-toolchain discovery failures (broken adb/idb) — an empty list alone is ambiguous. */
+    warnings?: string[];
 }
 export declare function runMobileList(exec?: ExecFn): Promise<Envelope<MobileListResult>>;
 declare const _default: import("citty").CommandDef<{}>;

package/dist/commands/mobile/list.js

@@ -1,22 +1,28 @@
 import { defineCommand } from "citty";
 import { formatSuccess, printResult } from "../../output.js";
 import { listAndroidDevices, listIosPhysicalDevices, } from "../../mobile-control/devices.js";
-async function safe(fn, fallback) {
-    try {
-        return await fn();
-    }
-    catch {
-        return fallback;
-    }
-}
 export async function runMobileList(exec) {
+    const warnings = [];
+    const safe = async (label, fn, fallback) => {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            warnings.push(`${label}: ${err instanceof Error ? err.message : String(err)}`);
+            return fallback;
+        }
+    };
     const [allAndroid, iosDevices] = await Promise.all([
-        safe(() => listAndroidDevices(exec), []),
-        safe(() => listIosPhysicalDevices(exec), []),
+        safe("android (adb)", () => listAndroidDevices(exec), []),
+        safe("ios (idb)", () => listIosPhysicalDevices(exec), []),
     ]);
     // Physical phones only: drop emulator serials.
     const androidDevices = allAndroid.filter((d) => !d.serial.startsWith("emulator-"));
-    return formatSuccess({ androidDevices, iosDevices });
+    return formatSuccess({
+        androidDevices,
+        iosDevices,
+        ...(warnings.length > 0 ? { warnings } : {}),
+    });
 }
 export default defineCommand({
     meta: {

package/dist/commands/mobile/unregister.js

@@ -12,15 +12,20 @@ export async function runMobileUnregister(options, deps) {
     const { deviceId } = resolved.config;
     try {
         await request(`/api/devices/user/${deviceId}`, { method: "DELETE" }, deps ?? {});
-        const configPath = getMobileDeviceConfigPath(deviceId);
-        if (existsSync(configPath)) {
-            unlinkSync(configPath);
-        }
-        return formatSuccess({ success: true });
     }
     catch (err) {
-        return handleApiError(err);
+        // 404 = the server row is already gone (deleted via the web UI). Still clear
+        // the local config, otherwise the device can never be unregistered locally.
+        const status = err.status;
+        if (status !== 404) {
+            return handleApiError(err);
+        }
+    }
+    const configPath = getMobileDeviceConfigPath(deviceId);
+    if (existsSync(configPath)) {
+        unlinkSync(configPath);
     }
+    return formatSuccess({ success: true });
 }
 export default defineCommand({
     meta: { name: "unregister", description: "Unregister a local mobile device" },

package/dist/mobile-control/app-install.d.ts

@@ -1,5 +1,7 @@
 import { type ClientDeps } from "../client.js";
 import { type ExecFn } from "./exec.js";
+import { ensureInstallableIpa } from "./ios-auto-resign.js";
+import { installIosApp } from "./ios-devicectl.js";
 export interface InstallUploadedAppOptions {
     /** Aximo upload id of the app under test. */
     uploadId: string;
@@ -9,13 +11,24 @@ export interface InstallUploadedAppOptions {
     exec?: ExecFn;
     /** Client overrides (apiKey/baseUrl/fetchImpl) — used in tests. */
     deps?: ClientDeps;
+    /** Progress reporting for the (potentially slow) resign path. */
+    log?: (message: string) => void;
+    /** Injectable for tests. */
+    ensureInstallable?: typeof ensureInstallableIpa;
+    installIos?: typeof installIosApp;
+}
+export interface InstallUploadedAppResult {
+    output: string;
+    /** iOS only: set when the app was auto-re-signed for this device. */
+    originalBundleId?: string;
+    installedBundleId?: string;
 }
 /**
  * Download the app under test from Aximo (authenticated via the org API key, which
  * redirects to short-lived storage) and install it on the connected device —
- * Android `.apk` via `adb install -r`, iOS `.ipa` via `idb install`. The app binary
- * never crosses the control tunnel; only the opaque upload id does.
+ * Android `.apk` via `adb install -r`, iOS `.ipa` via devicectl, auto-re-signed for
+ * the device first when its signature doesn't already cover it (what AWS Device
+ * Farm does server-side). The app binary never crosses the control tunnel; only
+ * the opaque upload id does.
  */
-export declare function installUploadedApp(opts: InstallUploadedAppOptions): Promise<{
-    output: string;
-}>;
+export declare function installUploadedApp(opts: InstallUploadedAppOptions): Promise<InstallUploadedAppResult>;

package/dist/mobile-control/app-install.js

@@ -4,25 +4,52 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { requestToFile } from "../client.js";
 import { execBinary } from "./exec.js";
+import { ensureInstallableIpa } from "./ios-auto-resign.js";
+import { installIosApp } from "./ios-devicectl.js";
+import { withMobileHint } from "./mobile-errors.js";
 /**
  * Download the app under test from Aximo (authenticated via the org API key, which
  * redirects to short-lived storage) and install it on the connected device —
- * Android `.apk` via `adb install -r`, iOS `.ipa` via `idb install`. The app binary
- * never crosses the control tunnel; only the opaque upload id does.
+ * Android `.apk` via `adb install -r`, iOS `.ipa` via devicectl, auto-re-signed for
+ * the device first when its signature doesn't already cover it (what AWS Device
+ * Farm does server-side). The app binary never crosses the control tunnel; only
+ * the opaque upload id does.
  */
 export async function installUploadedApp(opts) {
     const exec = opts.exec ?? execBinary;
     const ext = opts.platform === "ios" ? ".ipa" : ".apk";
     const tmpPath = join(tmpdir(), `aximo-install-${randomBytes(8).toString("hex")}${ext}`);
+    let resignedPath;
     try {
         // Stream the (authenticated) download straight to disk — apps can be large.
         await requestToFile(`/api/devices/apps/${encodeURIComponent(opts.uploadId)}/download`, tmpPath, opts.deps ?? {});
-        const { stdout } = opts.platform === "ios"
-            ? await exec("idb", ["install", "--udid", opts.target, tmpPath])
-            : await exec("adb", ["-s", opts.target, "install", "-r", tmpPath]);
-        return { output: stdout.toString("utf-8").trim() };
+        if (opts.platform === "android") {
+            const { stdout } = await exec("adb", ["-s", opts.target, "install", "-r", tmpPath]);
+            return { output: stdout.toString("utf-8").trim() };
+        }
+        const ensured = await (opts.ensureInstallable ?? ensureInstallableIpa)({
+            ipaPath: tmpPath,
+            udid: opts.target,
+            ...(opts.log ? { log: opts.log } : {}),
+        });
+        if (ensured.resigned)
+            resignedPath = ensured.ipaPath;
+        const output = await (opts.installIos ?? installIosApp)(opts.target, ensured.ipaPath, exec);
+        return ensured.resigned
+            ? {
+                output,
+                originalBundleId: ensured.originalBundleId,
+                installedBundleId: ensured.installedBundleId,
+            }
+            : { output };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(withMobileHint(message, opts.platform));
     }
     finally {
         await rm(tmpPath, { force: true }).catch(() => { });
+        if (resignedPath)
+            await rm(resignedPath, { force: true }).catch(() => { });
     }
 }

package/dist/mobile-control/app-install.test.js

@@ -49,20 +49,55 @@ describe("installUploadedApp", () => {
         expect(call?.args.slice(0, 4)).toEqual(["-s", "R1", "install", "-r"]);
         expect(call?.args[4]).toMatch(/\.apk$/);
     });
-    it("installs an iOS app via idb", async () => {
-        const { exec, calls } = captureExec();
+    it("auto-resigns when needed and installs an iOS app via devicectl", async () => {
+        const { exec } = captureExec();
         const { impl } = fakeFetch(true);
-        await installUploadedApp({
+        const ensureInstallable = vi.fn(async (opts) => ({
+            ipaPath: opts.ipaPath.replace(/\.ipa$/, "-resigned.ipa"),
+            resigned: true,
+            originalBundleId: "com.example.app",
+            installedBundleId: "com.aximo.resign.team.xctrunner",
+        }));
+        const installIos = vi.fn(async () => "App installed:");
+        const res = await installUploadedApp({
             uploadId: "up-9",
             platform: "ios",
             target: "00008030-ABC",
             exec,
             deps: { ...DEPS, fetchImpl: impl },
+            ensureInstallable,
+            installIos,
         });
-        const call = calls()[0];
-        expect(call?.file).toBe("idb");
-        expect(call?.args.slice(0, 3)).toEqual(["install", "--udid", "00008030-ABC"]);
-        expect(call?.args[3]).toMatch(/\.ipa$/);
+        expect(vi.mocked(ensureInstallable).mock.calls[0]?.[0]).toMatchObject({
+            udid: "00008030-ABC",
+        });
+        expect(installIos).toHaveBeenCalledWith("00008030-ABC", expect.stringMatching(/-resigned\.ipa$/), exec);
+        expect(res).toEqual({
+            output: "App installed:",
+            originalBundleId: "com.example.app",
+            installedBundleId: "com.aximo.resign.team.xctrunner",
+        });
+    });
+    it("installs an already-installable iOS app without resign metadata", async () => {
+        const { exec } = captureExec();
+        const { impl } = fakeFetch(true);
+        const ensureInstallable = vi.fn(async (opts) => ({
+            ipaPath: opts.ipaPath,
+            resigned: false,
+            originalBundleId: "com.example.app",
+            installedBundleId: "com.example.app",
+        }));
+        const installIos = vi.fn(async () => "App installed:");
+        const res = await installUploadedApp({
+            uploadId: "up-9",
+            platform: "ios",
+            target: "00008030-ABC",
+            exec,
+            deps: { ...DEPS, fetchImpl: impl },
+            ensureInstallable,
+            installIos,
+        });
+        expect(res).toEqual({ output: "App installed:" });
     });
     it("throws when the authenticated download fails", async () => {
         const { exec } = captureExec();

package/dist/mobile-control/appium-controller.d.ts

@@ -6,6 +6,12 @@ export interface AppiumControllerOptions {
     platform: "ios" | "android";
     target: string;
     iosSigning?: IosSigningConfig;
+    /**
+     * Local port XCUITest forwards to WebDriverAgent; unique-per-session avoids
+     * collisions. A provider is resolved just before session creation so the port
+     * isn't picked long before it is bound.
+     */
+    wdaLocalPort?: number | (() => Promise<number>);
     transport?: WebDriverTransport;
 }
 export declare class AppiumController implements MobileController {
@@ -13,6 +19,8 @@ export declare class AppiumController implements MobileController {
     private readonly platform;
     private readonly target;
     private readonly iosSigning;
+    private readonly wdaLocalPort;
+    private resolvedWdaPort;
     private sessionReady;
     private scaling;
     constructor(opts: AppiumControllerOptions);

package/dist/mobile-control/appium-controller.js

@@ -1,3 +1,4 @@
+import { enrichIosSessionError } from "./ios-session-error.js";
 import { iosSigningCapabilities } from "./ios-signing.js";
 import { fetchTransport, WebDriverSession } from "./webdriver.js";
 const ANDROID_KEY_CODES = {
@@ -26,12 +27,15 @@ export class AppiumController {
     platform;
     target;
     iosSigning;
+    wdaLocalPort;
+    resolvedWdaPort;
     sessionReady = null;
     scaling = null;
     constructor(opts) {
         this.platform = opts.platform;
         this.target = opts.target;
         this.iosSigning = opts.iosSigning;
+        this.wdaLocalPort = opts.wdaLocalPort;
         const transport = opts.transport ?? fetchTransport(opts.endpoint);
         this.session = new WebDriverSession(transport);
     }
@@ -51,17 +55,28 @@ export class AppiumController {
             "appium:automationName": "XCUITest",
             "appium:udid": this.target,
             "appium:newCommandTimeout": 0,
+            // Unique local->device WDA port so a second connected phone doesn't collide on 8100.
+            ...(this.resolvedWdaPort ? { "appium:wdaLocalPort": this.resolvedWdaPort } : {}),
             // WDA code-signing caps for physical iPhones (empty unless a team id is set).
             ...(this.iosSigning ? iosSigningCapabilities(this.iosSigning) : {}),
         };
     }
     ensureSession() {
         if (!this.sessionReady) {
-            this.sessionReady = this.session
-                .createSession(this.capabilities())
-                .then(() => undefined)
-                .catch((err) => {
+            this.sessionReady = (async () => {
+                this.resolvedWdaPort =
+                    typeof this.wdaLocalPort === "function" ? await this.wdaLocalPort() : this.wdaLocalPort;
+                await this.session.createSession(this.capabilities());
+            })().catch(async (err) => {
                 this.sessionReady = null;
+                // A retry must re-pick a free port — the one resolved here may be taken by then.
+                this.resolvedWdaPort = undefined;
+                // XCUITest reports session-start failures generically ("xcodebuild failed
+                // with code 65"); enrich with the real reason from the WDA .xcresult and
+                // an actionable hint so the user isn't left with an opaque error.
+                if (this.platform === "ios") {
+                    throw await enrichIosSessionError(err, this.iosSigning?.derivedDataPath);
+                }
                 throw err;
             });
         }

package/dist/mobile-control/bundle-id-map.d.ts

@@ -0,0 +1,9 @@
+import type { MobileController } from "./controller.js";
+/**
+ * Re-signing can remap an app's bundle id (free teams can't always register the
+ * original id), but the Aximo backend keeps launching apps by their ORIGINAL id
+ * from the upload metadata. This wrapper translates launch targets through the
+ * original→installed map that app installs populate, so remapping stays
+ * invisible to the cloud side.
+ */
+export declare function withBundleIdTranslation(controller: MobileController, map: ReadonlyMap<string, string>): MobileController;

package/dist/mobile-control/bundle-id-map.js

@@ -0,0 +1,27 @@
+/**
+ * Re-signing can remap an app's bundle id (free teams can't always register the
+ * original id), but the Aximo backend keeps launching apps by their ORIGINAL id
+ * from the upload metadata. This wrapper translates launch targets through the
+ * original→installed map that app installs populate, so remapping stays
+ * invisible to the cloud side.
+ */
+export function withBundleIdTranslation(controller, map) {
+    const wrapped = {
+        screenshot: () => controller.screenshot(),
+        tap: (x, y) => controller.tap(x, y),
+        doubleTap: (x, y) => controller.doubleTap(x, y),
+        longPress: (x, y, durationMs) => controller.longPress(x, y, durationMs),
+        swipe: (x1, y1, x2, y2, durationMs) => controller.swipe(x1, y1, x2, y2, durationMs),
+        typeText: (text) => controller.typeText(text),
+        pressKey: (key) => controller.pressKey(key),
+        launchApp: (app) => controller.launchApp(map.get(app) ?? app),
+        findElement: (text) => controller.findElement(text),
+        clearText: () => controller.clearText(),
+        hideKeyboard: () => controller.hideKeyboard(),
+        close: () => controller.close(),
+    };
+    if (controller.getDeviceTime) {
+        wrapped.getDeviceTime = () => controller.getDeviceTime?.() ?? Promise.resolve(null);
+    }
+    return wrapped;
+}

package/dist/mobile-control/devices.d.ts

@@ -16,8 +16,11 @@ export interface IosPhysicalDevice {
 /** Resolve an iOS udid: explicit (validated), else the single connected device. */
 export declare function resolveIosUdid(preferred: string | undefined, exec?: ExecFn): Promise<string>;
 /**
- * List physically-connected iOS devices via `idb list-targets --json` (one JSON
- * object per line). Only entries whose `type` is `device` are returned. Returns
- * an empty list when idb is not installed; a real idb failure is surfaced.
+ * List physically-connected iOS devices by MERGING devicectl and idb results
+ * (deduped by udid, devicectl wins). devicectl (CoreDevice) only sees iOS 17+
+ * devices, so an early-return on its results would make an iOS ≤16 phone vanish
+ * whenever a newer one is also attached — idb covers the older devices. idb is
+ * optional: not-installed means "no extra devices"; a real idb failure is only
+ * surfaced when devicectl found nothing (otherwise discovery still works).
  */
 export declare function listIosPhysicalDevices(exec?: ExecFn): Promise<IosPhysicalDevice[]>;

package/dist/mobile-control/devices.js

@@ -1,4 +1,5 @@
 import { execBinary } from "./exec.js";
+import { listIosDevicesViaDevicectl } from "./ios-devicectl.js";
 /** Parse `adb devices -l` into serial + state (+ model when present). */
 export async function listAndroidDevices(exec = execBinary) {
     const { stdout } = await exec("adb", ["devices", "-l"]);
@@ -77,7 +78,7 @@ export async function resolveIosUdid(preferred, exec = execBinary) {
         return devices[0].udid;
     if (devices.length === 0) {
         throw new Error("No connected iOS devices found. Connect an iPhone/iPad over USB, unlock it, and " +
-            "trust this computer. Verify with `idb list-targets` (or `aximo mobile doctor` if idb is missing).");
+            "trust this computer. Verify with `xcrun devicectl list devices` (or `aximo mobile doctor`).");
     }
     throw new Error(`Multiple iOS devices found; pass --udid. Available: ${devices
         .map((d) => `${d.name} (${d.udid})`)
@@ -90,11 +91,32 @@ function isCommandNotFound(err) {
     return err instanceof Error && /\bENOENT\b/.test(err.message);
 }
 /**
- * List physically-connected iOS devices via `idb list-targets --json` (one JSON
- * object per line). Only entries whose `type` is `device` are returned. Returns
- * an empty list when idb is not installed; a real idb failure is surfaced.
+ * List physically-connected iOS devices by MERGING devicectl and idb results
+ * (deduped by udid, devicectl wins). devicectl (CoreDevice) only sees iOS 17+
+ * devices, so an early-return on its results would make an iOS ≤16 phone vanish
+ * whenever a newer one is also attached — idb covers the older devices. idb is
+ * optional: not-installed means "no extra devices"; a real idb failure is only
+ * surfaced when devicectl found nothing (otherwise discovery still works).
  */
 export async function listIosPhysicalDevices(exec = execBinary) {
+    const byUdid = new Map();
+    for (const d of await listIosDevicesViaDevicectl(exec)) {
+        byUdid.set(d.udid, { udid: d.udid, name: d.name ?? d.model ?? d.udid, state: "connected" });
+    }
+    try {
+        for (const d of await listIosViaIdb(exec)) {
+            if (!byUdid.has(d.udid))
+                byUdid.set(d.udid, d);
+        }
+    }
+    catch (err) {
+        if (byUdid.size === 0)
+            throw err;
+    }
+    return [...byUdid.values()];
+}
+/** `idb list-targets --json` (one JSON object per line), physical devices only. */
+async function listIosViaIdb(exec) {
     let stdout;
     try {
         ({ stdout } = await exec("idb", ["list-targets", "--json"]));

package/dist/mobile-control/env-flags.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Boolean env-var toggle: set and not an explicit "off" value. Plain truthiness
+ * would treat AXIMO_IOS_SKIP_TUNNEL=0 or =false as enabled, which surprises users.
+ */
+export declare function envFlag(env: NodeJS.ProcessEnv, name: string): boolean;

package/dist/mobile-control/env-flags.js

@@ -0,0 +1,10 @@
+/**
+ * Boolean env-var toggle: set and not an explicit "off" value. Plain truthiness
+ * would treat AXIMO_IOS_SKIP_TUNNEL=0 or =false as enabled, which surprises users.
+ */
+export function envFlag(env, name) {
+    const value = env[name]?.trim().toLowerCase();
+    if (!value)
+        return false;
+    return !["0", "false", "no", "off"].includes(value);
+}

package/dist/mobile-control/env-flags.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mobile-control/env-flags.test.js

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { envFlag } from "./env-flags.js";
+describe("envFlag", () => {
+    it("is false when unset or empty", () => {
+        expect(envFlag({}, "X")).toBe(false);
+        expect(envFlag({ X: "" }, "X")).toBe(false);
+        expect(envFlag({ X: "  " }, "X")).toBe(false);
+    });
+    it("is true for ordinary truthy values", () => {
+        expect(envFlag({ X: "1" }, "X")).toBe(true);
+        expect(envFlag({ X: "true" }, "X")).toBe(true);
+        expect(envFlag({ X: "yes" }, "X")).toBe(true);
+    });
+    it("treats explicit off-values as false", () => {
+        expect(envFlag({ X: "0" }, "X")).toBe(false);
+        expect(envFlag({ X: "false" }, "X")).toBe(false);
+        expect(envFlag({ X: "FALSE" }, "X")).toBe(false);
+        expect(envFlag({ X: "no" }, "X")).toBe(false);
+        expect(envFlag({ X: "off" }, "X")).toBe(false);
+    });
+});