@autifyhq/aximo-cli 0.5.0 → 0.6.0

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

@@ -0,0 +1,104 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runMobileInstall } from "./install.js";
+const ONE_ANDROID = "List of devices attached\nR1 device\n";
+const ONE_IOS = `${JSON.stringify({ udid: "00008030-ABC", name: "iPhone", type: "device" })}\n`;
+let dir;
+let apkPath;
+let ipaPath;
+let txtPath;
+beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), "aximo-mob-install-"));
+    apkPath = join(dir, "app.apk");
+    ipaPath = join(dir, "app.ipa");
+    txtPath = join(dir, "app.txt");
+    for (const p of [apkPath, ipaPath, txtPath])
+        writeFileSync(p, "x");
+});
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+/** Mock adb/idb: serve device discovery and capture the `install` invocation. */
+function execWith(opts = {}) {
+    let captured = { file: "", args: [] };
+    const exec = async (file, args) => {
+        if (file === "adb" && args[0] === "devices") {
+            return { stdout: Buffer.from(ONE_ANDROID), stderr: "" };
+        }
+        if (file === "idb" && args[0] === "list-targets") {
+            return { stdout: Buffer.from(ONE_IOS), stderr: "" };
+        }
+        if ((file === "adb" || file === "idb") && args.includes("install")) {
+            captured = { file, args };
+            if (opts.throwMsg)
+                throw new Error(opts.throwMsg);
+            return { stdout: Buffer.from(opts.out ?? "Success"), stderr: "" };
+        }
+        throw new Error(`unexpected exec: ${file} ${args.join(" ")}`);
+    };
+    return { exec, install: () => captured };
+}
+describe("runMobileInstall", () => {
+    it("requires --app", async () => {
+        const { exec } = execWith();
+        const res = await runMobileInstall({}, exec);
+        expect(res.ok).toBe(false);
+        if (!res.ok)
+            expect(res.error.code).toBe("validation_error");
+    });
+    it("errors when the app file is missing", async () => {
+        const { exec } = execWith();
+        const res = await runMobileInstall({ app: "definitely-not-here-xyz.apk" }, exec);
+        expect(res.ok).toBe(false);
+        if (!res.ok)
+            expect(res.error.message).toMatch(/not found/i);
+    });
+    it("errors when the platform cannot be inferred", async () => {
+        const { exec } = execWith();
+        const res = await runMobileInstall({ app: txtPath }, exec);
+        expect(res.ok).toBe(false);
+        if (!res.ok)
+            expect(res.error.message).toMatch(/determine platform/i);
+    });
+    it("installs an .apk via `adb -s <serial> install -r`", async () => {
+        const { exec, install } = execWith({ out: "Performing Streamed Install\nSuccess" });
+        const res = await runMobileInstall({ app: apkPath }, exec);
+        expect(res.ok).toBe(true);
+        if (res.ok) {
+            expect(res.data.platform).toBe("android");
+            expect(res.data.serial).toBe("R1");
+            expect(res.data.udid).toBeUndefined();
+            expect(res.data.output).toContain("Success");
+        }
+        expect(install().file).toBe("adb");
+        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);
+        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(install().file).toBe("idb");
+        expect(install().args).toEqual(["install", "--udid", "00008030-ABC", ipaPath]);
+    });
+    it("honors an explicit --platform override", async () => {
+        const { exec, install } = execWith();
+        const res = await runMobileInstall({ app: txtPath, platform: "android" }, exec);
+        expect(res.ok).toBe(true);
+        expect(install().file).toBe("adb");
+    });
+    it("maps an install failure to an error envelope", async () => {
+        const { exec } = execWith({ throwMsg: "adb: failed to install: INSTALL_FAILED_INVALID_APK" });
+        const res = await runMobileInstall({ app: apkPath }, exec);
+        expect(res.ok).toBe(false);
+        if (!res.ok) {
+            expect(res.error.code).toBe("api_error");
+            expect(res.error.message).toMatch(/INSTALL_FAILED/);
+        }
+    });
+});

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

@@ -6,6 +6,7 @@ export interface MobileRegisterCmdOptions {
     name: string;
     platform: string;
     serial?: string | undefined;
+    udid?: string | undefined;
     os?: string | undefined;
 }
 export declare function runMobileRegister(options: MobileRegisterCmdOptions, deps?: ClientDeps, exec?: ExecFn): Promise<Envelope<MobileRegisterResult>>;
@@ -17,13 +18,17 @@ declare const _default: import("citty").CommandDef<{
     };
     readonly platform: {
         readonly type: "string";
-        readonly description: "Device platform (only `android` is supported today)";
+        readonly description: "Device platform (`android` or `ios`)";
         readonly default: "android";
     };
     readonly serial: {
         readonly type: "string";
         readonly description: "Android adb serial (defaults to the connected one)";
     };
+    readonly udid: {
+        readonly type: "string";
+        readonly description: "iOS device udid (defaults to the connected one)";
+    };
     readonly os: {
         readonly type: "string";
         readonly description: "Optional OS version label";

package/dist/commands/mobile/register.js

@@ -1,19 +1,23 @@
 import { defineCommand } from "citty";
 import {} from "../../client.js";
 import { formatError, printResult } from "../../output.js";
-import { resolveAndroidSerial } from "../../mobile-control/devices.js";
+import { resolveAndroidSerial, resolveIosUdid } from "../../mobile-control/devices.js";
 import { parsePlatformArg, registerMobileDevice, } from "./register-core.js";
 export async function runMobileRegister(options, deps, exec) {
     const platform = parsePlatformArg(options.platform);
-    if (platform !== "android") {
-        return formatError("validation_error", "Only --platform android is supported (iOS local devices are coming in a future release).", false);
+    if (!platform) {
+        return formatError("validation_error", "Invalid --platform; expected `android` or `ios`.", false);
     }
     if (!options.name) {
         return formatError("validation_error", "Device name is required (--name).", false);
     }
+    // Resolve the device target: an adb serial for Android, a udid for iOS.
     let target;
     try {
-        target = await resolveAndroidSerial(options.serial, exec);
+        target =
+            platform === "ios"
+                ? await resolveIosUdid(options.udid, exec)
+                : await resolveAndroidSerial(options.serial, exec);
     }
     catch (err) {
         return formatError("validation_error", err instanceof Error ? err.message : String(err), false);
@@ -28,16 +32,17 @@ export async function runMobileRegister(options, deps, exec) {
 export default defineCommand({
     meta: {
         name: "register",
-        description: "Register a physically-connected Android phone as an Aximo device",
+        description: "Register a physically-connected Android phone or iPhone as an Aximo device",
     },
     args: {
         name: { type: "string", description: "Device name", required: true },
         platform: {
             type: "string",
-            description: "Device platform (only `android` is supported today)",
+            description: "Device platform (`android` or `ios`)",
             default: "android",
         },
         serial: { type: "string", description: "Android adb serial (defaults to the connected one)" },
+        udid: { type: "string", description: "iOS device udid (defaults to the connected one)" },
         os: { type: "string", description: "Optional OS version label" },
     },
     async run({ args }) {
@@ -45,6 +50,7 @@ export default defineCommand({
             name: args.name,
             platform: args.platform,
             serial: args.serial,
+            udid: args.udid,
             os: args.os,
         }));
     },

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

@@ -26,6 +26,20 @@ const oneAndroidDevice = async () => ({
     stdout: Buffer.from("List of devices attached\nR58M12345  device model:Pixel_7\n"),
     stderr: "",
 });
+const oneIosDevice = async (file, args) => {
+    if (file === "idb" && args[0] === "list-targets") {
+        return {
+            stdout: Buffer.from(`${JSON.stringify({
+                udid: "00008030-ABCDEF",
+                name: "Abdul's iPhone",
+                type: "device",
+                state: "connected",
+            })}\n`),
+            stderr: "",
+        };
+    }
+    throw new Error(`unexpected exec: ${file} ${args.join(" ")}`);
+};
 describe("runMobileRegister", () => {
     it("posts the resolved android serial and writes config", async () => {
         let body;
@@ -49,12 +63,29 @@ describe("runMobileRegister", () => {
         expect(saved).toMatchObject({ platform: "android", target: "R58M12345" });
         expect(saved).not.toHaveProperty("category");
     });
-    it("rejects iOS registration as unsupported", async () => {
-        const result = await runMobileRegister({ name: "iPhone", platform: "ios" });
+    it("posts the resolved iOS udid and writes config", async () => {
+        let body;
+        server.use(http.post(`${TEST_BASE_URL}/api/devices/register`, async ({ request }) => {
+            body = (await request.json());
+            return HttpResponse.json({ deviceId: "dev-ios", deviceToken: "tok-ios" }, { status: 201 });
+        }));
+        const result = await runMobileRegister({ name: "iPhone", platform: "ios" }, undefined, oneIosDevice);
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(body).toMatchObject({ name: "iPhone", platform: "ios" });
+        expect(result.data.target).toBe("00008030-ABCDEF");
+        const configPath = join(tempHome, "mobile-devices", "dev-ios.json");
+        expect(existsSync(configPath)).toBe(true);
+        const saved = JSON.parse(readFileSync(configPath, "utf-8"));
+        expect(saved).toMatchObject({ platform: "ios", target: "00008030-ABCDEF" });
+    });
+    it("rejects an unknown platform", async () => {
+        const result = await runMobileRegister({ name: "x", platform: "windows" });
         expect(result.ok).toBe(false);
         if (!result.ok) {
             expect(result.error.code).toBe("validation_error");
-            expect(result.error.message).toContain("Only --platform android is supported");
+            expect(result.error.message).toContain("Invalid --platform");
         }
     });
 });

package/dist/commands/schema.js

@@ -120,25 +120,32 @@ export function getSchema() {
                     arg("available-only", "boolean", ""),
                 ]),
             ]),
-            cmd("mobile", "Register and connect a physically-connected Android phone (via adb)", [], [
-                cmd("list", "List physically-connected phones (adb)"),
-                cmd("register", "Register a physically-connected Android phone as an Aximo device", [
+            cmd("mobile", "Register and connect a physically-connected Android phone (adb) or iPhone (idb/Xcode)", [], [
+                cmd("list", "List physically-connected phones (Android via adb, iOS via idb)"),
+                cmd("register", "Register a physically-connected Android phone or iPhone as an Aximo device", [
                     arg("name", "string", "Device name", true),
-                    arg("platform", "string", "Device platform (only `android` is supported today)"),
+                    arg("platform", "string", "Device platform (`android` or `ios`)"),
                     arg("serial", "string", "Android adb serial (defaults to the connected one)"),
+                    arg("udid", "string", "iOS device udid (defaults to the connected one)"),
                     arg("os", "string", "Optional OS version label"),
                 ]),
+                cmd("install", "Install an app on the connected phone (.apk via adb, .ipa via idb)", [
+                    arg("app", "string", "Path to the .apk or .ipa to install", true),
+                    arg("platform", "string", "android | ios (inferred from the file extension)"),
+                    arg("serial", "string", "Android adb serial (defaults to the connected one)"),
+                    arg("udid", "string", "iOS device udid (defaults to the connected one)"),
+                ]),
                 cmd("unregister", "Unregister a local mobile device", [
                     arg("device-id", "string", "Device ID (defaults to the sole registered local device)"),
                 ]),
-                cmd("connect", "Connect a registered Android phone via a CLI-managed Appium server", [
+                cmd("connect", "Connect a registered phone via a CLI-managed Appium server", [
                     arg("device-id", "string", "Registered device id (required if multiple)"),
                 ]),
                 cmd("setup", "Install the Appium drivers used to drive registered phones", [
-                    arg("platform", "string", "Limit checks to android"),
+                    arg("platform", "string", "Limit to ios | android driver"),
                 ]),
-                cmd("doctor", "Diagnose physical-device tooling (adb authorization, Appium setup)", [
-                    arg("platform", "string", "Limit checks to android"),
+                cmd("doctor", "Diagnose physical-device tooling (adb/idb, Xcode, Appium setup)", [
+                    arg("platform", "string", "Limit checks to ios | android"),
                 ]),
             ]),
             cmd("upload", "Upload commands", [], [

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

@@ -0,0 +1,21 @@
+import { type ClientDeps } from "../client.js";
+import { type ExecFn } from "./exec.js";
+export interface InstallUploadedAppOptions {
+    /** Aximo upload id of the app under test. */
+    uploadId: string;
+    platform: "ios" | "android";
+    /** adb serial (Android) or udid (iOS) of the registered device. */
+    target: string;
+    exec?: ExecFn;
+    /** Client overrides (apiKey/baseUrl/fetchImpl) — used in tests. */
+    deps?: ClientDeps;
+}
+/**
+ * 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.
+ */
+export declare function installUploadedApp(opts: InstallUploadedAppOptions): Promise<{
+    output: string;
+}>;

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

@@ -0,0 +1,28 @@
+import { randomBytes } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { requestToFile } from "../client.js";
+import { execBinary } from "./exec.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.
+ */
+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}`);
+    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() };
+    }
+    finally {
+        await rm(tmpPath, { force: true }).catch(() => { });
+    }
+}

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

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

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

@@ -0,0 +1,78 @@
+import { describe, expect, it, vi } from "vitest";
+import { installUploadedApp } from "./app-install.js";
+const DEPS = { apiKey: "test-key", baseUrl: "https://aximo.test" };
+function fakeFetch(ok, bytes = "apk-bytes") {
+    let seen = "";
+    const impl = vi.fn(async (url) => {
+        seen = url;
+        return {
+            ok,
+            status: ok ? 200 : 403,
+            statusText: ok ? "OK" : "Forbidden",
+            text: async () => (ok ? "" : "forbidden"),
+            body: ok
+                ? new ReadableStream({
+                    start(controller) {
+                        controller.enqueue(new TextEncoder().encode(bytes));
+                        controller.close();
+                    },
+                })
+                : null,
+            headers: { get: () => null },
+        };
+    });
+    return { impl, url: () => seen };
+}
+function captureExec() {
+    const calls = [];
+    const exec = async (file, args) => {
+        calls.push({ file, args });
+        return { stdout: Buffer.from("Success"), stderr: "" };
+    };
+    return { exec, calls: () => calls };
+}
+describe("installUploadedApp", () => {
+    it("fetches the app authenticated by upload id and installs via adb", async () => {
+        const { exec, calls } = captureExec();
+        const { impl, url } = fakeFetch(true);
+        const res = await installUploadedApp({
+            uploadId: "up-123",
+            platform: "android",
+            target: "R1",
+            exec,
+            deps: { ...DEPS, fetchImpl: impl },
+        });
+        expect(res.output).toContain("Success");
+        expect(url()).toBe("https://aximo.test/api/devices/apps/up-123/download");
+        const call = calls()[0];
+        expect(call?.file).toBe("adb");
+        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();
+        const { impl } = fakeFetch(true);
+        await installUploadedApp({
+            uploadId: "up-9",
+            platform: "ios",
+            target: "00008030-ABC",
+            exec,
+            deps: { ...DEPS, fetchImpl: impl },
+        });
+        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$/);
+    });
+    it("throws when the authenticated download fails", async () => {
+        const { exec } = captureExec();
+        const { impl } = fakeFetch(false);
+        await expect(installUploadedApp({
+            uploadId: "missing",
+            platform: "android",
+            target: "R1",
+            exec,
+            deps: { ...DEPS, fetchImpl: impl },
+        })).rejects.toThrow();
+    });
+});

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

@@ -1,15 +1,18 @@
 import type { ActionResult, MobileController } from "./controller.js";
+import { type IosSigningConfig } from "./ios-signing.js";
 import { type WebDriverTransport } from "./webdriver.js";
 export interface AppiumControllerOptions {
     endpoint: string;
     platform: "ios" | "android";
     target: string;
+    iosSigning?: IosSigningConfig;
     transport?: WebDriverTransport;
 }
 export declare class AppiumController implements MobileController {
     private readonly session;
     private readonly platform;
     private readonly target;
+    private readonly iosSigning;
     private sessionReady;
     private scaling;
     constructor(opts: AppiumControllerOptions);

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

@@ -1,3 +1,4 @@
+import { iosSigningCapabilities } from "./ios-signing.js";
 import { fetchTransport, WebDriverSession } from "./webdriver.js";
 const ANDROID_KEY_CODES = {
     enter: 66,
@@ -24,11 +25,13 @@ export class AppiumController {
     session;
     platform;
     target;
+    iosSigning;
     sessionReady = null;
     scaling = null;
     constructor(opts) {
         this.platform = opts.platform;
         this.target = opts.target;
+        this.iosSigning = opts.iosSigning;
         const transport = opts.transport ?? fetchTransport(opts.endpoint);
         this.session = new WebDriverSession(transport);
     }
@@ -48,6 +51,8 @@ export class AppiumController {
             "appium:automationName": "XCUITest",
             "appium:udid": this.target,
             "appium:newCommandTimeout": 0,
+            // WDA code-signing caps for physical iPhones (empty unless a team id is set).
+            ...(this.iosSigning ? iosSigningCapabilities(this.iosSigning) : {}),
         };
     }
     ensureSession() {

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

@@ -13,9 +13,11 @@ export interface IosPhysicalDevice {
     name: string;
     state?: string;
 }
+/** 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 if idb is unavailable.
+ * an empty list when idb is not installed; a real idb failure is surfaced.
  */
 export declare function listIosPhysicalDevices(exec?: ExecFn): Promise<IosPhysicalDevice[]>;

package/dist/mobile-control/devices.js

@@ -62,18 +62,48 @@ export async function resolveAndroidSerial(preferred, exec = execBinary) {
         .map((d) => d.serial)
         .join(", ")}`);
 }
+/** Resolve an iOS udid: explicit (validated), else the single connected device. */
+export async function resolveIosUdid(preferred, exec = execBinary) {
+    const devices = await listIosPhysicalDevices(exec);
+    if (preferred) {
+        const match = devices.find((d) => d.udid === preferred);
+        if (!match) {
+            throw new Error(`No iOS device with udid '${preferred}' is connected. ` +
+                "Connect it over USB, unlock it, and trust this computer.");
+        }
+        return match.udid;
+    }
+    if (devices.length === 1 && devices[0])
+        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).");
+    }
+    throw new Error(`Multiple iOS devices found; pass --udid. Available: ${devices
+        .map((d) => `${d.name} (${d.udid})`)
+        .join(", ")}`);
+}
+/** True when a spawn failed because the binary isn't installed (ENOENT). */
+function isCommandNotFound(err) {
+    if (err?.code === "ENOENT")
+        return true;
+    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 if idb is unavailable.
+ * an empty list when idb is not installed; a real idb failure is surfaced.
  */
 export async function listIosPhysicalDevices(exec = execBinary) {
     let stdout;
     try {
         ({ stdout } = await exec("idb", ["list-targets", "--json"]));
     }
-    catch {
-        return [];
+    catch (err) {
+        // idb not installed → "no iOS devices"; any other idb failure should surface.
+        if (isCommandNotFound(err))
+            return [];
+        throw err;
     }
     const result = [];
     for (const line of stdout.toString("utf-8").split("\n")) {

package/dist/mobile-control/devices.test.js

@@ -1,8 +1,16 @@
 import { describe, expect, it } from "vitest";
-import { listAndroidDevices, resolveAndroidSerial } from "./devices.js";
+import { listAndroidDevices, listIosPhysicalDevices, resolveAndroidSerial, resolveIosUdid, } from "./devices.js";
 function fixed(stdout) {
     return async () => ({ stdout: Buffer.from(stdout), stderr: "" });
 }
+function iosTargets(...devices) {
+    return async () => ({
+        stdout: Buffer.from(devices.map((d) => JSON.stringify(d)).join("\n")),
+        stderr: "",
+    });
+}
+const PHONE = { udid: "00008030-ABC", name: "iPhone", type: "device", state: "connected" };
+const SIM = { udid: "SIM-1", name: "iPhone 15", type: "simulator", state: "Booted" };
 describe("listAndroidDevices / resolveAndroidSerial", () => {
     it("parses adb devices -l output", async () => {
         const exec = fixed("List of devices attached\nR1 device model:Pixel_7\nR2 unauthorized\n");
@@ -33,3 +41,35 @@ describe("listAndroidDevices / resolveAndroidSerial", () => {
         await expect(resolveAndroidSerial("R1", exec)).rejects.toThrow(/offline/i);
     });
 });
+describe("listIosPhysicalDevices / resolveIosUdid", () => {
+    it("returns only physical devices (ignores simulators)", async () => {
+        const devices = await listIosPhysicalDevices(iosTargets(PHONE, SIM));
+        expect(devices).toEqual([{ udid: "00008030-ABC", name: "iPhone", state: "connected" }]);
+    });
+    it("returns an empty list when idb is not installed (ENOENT)", async () => {
+        const exec = async () => {
+            throw new Error("spawn idb ENOENT");
+        };
+        await expect(listIosPhysicalDevices(exec)).resolves.toEqual([]);
+    });
+    it("surfaces a real idb failure instead of masking it as no devices", async () => {
+        const exec = async () => {
+            throw new Error("idb list-targets --json failed: could not connect to companion");
+        };
+        await expect(listIosPhysicalDevices(exec)).rejects.toThrow(/companion/);
+    });
+    it("auto-selects the only connected device", async () => {
+        await expect(resolveIosUdid(undefined, iosTargets(PHONE))).resolves.toBe("00008030-ABC");
+    });
+    it("errors when no devices are connected", async () => {
+        await expect(resolveIosUdid(undefined, iosTargets())).rejects.toThrow(/no connected ios/i);
+    });
+    it("requires --udid when multiple devices are connected", async () => {
+        const second = { ...PHONE, udid: "00008030-DEF", name: "iPad" };
+        await expect(resolveIosUdid(undefined, iosTargets(PHONE, second))).rejects.toThrow(/--udid/);
+    });
+    it("validates an explicitly-passed udid", async () => {
+        await expect(resolveIosUdid("nope", iosTargets(PHONE))).rejects.toThrow(/no ios device/i);
+        await expect(resolveIosUdid("00008030-ABC", iosTargets(PHONE))).resolves.toBe("00008030-ABC");
+    });
+});

package/dist/mobile-control/ios-signing.d.ts

@@ -0,0 +1,28 @@
+/**
+ * iOS WebDriverAgent signing configuration.
+ *
+ * Driving a physical iPhone goes through Appium's XCUITest driver, which builds
+ * and code-signs a WebDriverAgent (WDA) runner onto the device. That build needs
+ * an Apple Developer signing identity. These values are supplied via env vars and
+ * forwarded as XCUITest capabilities. Simulators need no signing, so the caps are
+ * only emitted when a team id is configured.
+ *
+ * The CLI-native `AXIMO_IOS_*` names take precedence; Autify's MobileLink
+ * (mobile-web) names — `XCODE_TEAM_ID` / `XCODE_SIGN_ID` / `WDA_BUNDLE_ID` — are
+ * accepted as fallbacks so an already-configured MobileLink host needs no changes.
+ */
+export interface IosSigningConfig {
+    /** Apple Developer Team ID, forwarded as `appium:xcodeOrgId`. */
+    teamId?: string;
+    /** Code-signing identity; defaults to "Apple Development". */
+    signingId: string;
+    /** WDA bundle id backed by a valid provisioning profile. */
+    wdaBundleId: string;
+    /** Optional prebuilt-WDA DerivedData path to skip per-session WDA rebuilds. */
+    derivedDataPath?: string;
+}
+type Env = Record<string, string | undefined>;
+export declare function resolveIosSigning(env?: Env): IosSigningConfig;
+/** Map signing config to XCUITest capabilities; empty unless a team id is set. */
+export declare function iosSigningCapabilities(config: IosSigningConfig): Record<string, unknown>;
+export {};

package/dist/mobile-control/ios-signing.js

@@ -0,0 +1,38 @@
+const DEFAULT_SIGNING_ID = "Apple Development";
+const DEFAULT_WDA_BUNDLE_ID = "com.facebook.WebDriverAgentRunner";
+export function resolveIosSigning(env = process.env) {
+    // AXIMO_IOS_* is CLI-native; XCODE_*/WDA_BUNDLE_ID mirror MobileLink (mobile-web).
+    const pick = (...keys) => {
+        for (const key of keys) {
+            const value = env[key]?.trim();
+            if (value)
+                return value;
+        }
+        return undefined;
+    };
+    const teamId = pick("AXIMO_IOS_TEAM_ID", "XCODE_TEAM_ID");
+    const derivedDataPath = pick("AXIMO_IOS_DERIVED_DATA_PATH");
+    const config = {
+        signingId: pick("AXIMO_IOS_SIGNING_ID", "XCODE_SIGN_ID") || DEFAULT_SIGNING_ID,
+        wdaBundleId: pick("AXIMO_IOS_WDA_BUNDLE_ID", "WDA_BUNDLE_ID") || DEFAULT_WDA_BUNDLE_ID,
+    };
+    if (teamId)
+        config.teamId = teamId;
+    if (derivedDataPath)
+        config.derivedDataPath = derivedDataPath;
+    return config;
+}
+/** Map signing config to XCUITest capabilities; empty unless a team id is set. */
+export function iosSigningCapabilities(config) {
+    if (!config.teamId)
+        return {};
+    const caps = {
+        "appium:xcodeOrgId": config.teamId,
+        "appium:xcodeSigningId": config.signingId,
+        "appium:updatedWDABundleId": config.wdaBundleId,
+        "appium:allowProvisioningDeviceRegistration": true,
+    };
+    if (config.derivedDataPath)
+        caps["appium:derivedDataPath"] = config.derivedDataPath;
+    return caps;
+}

package/dist/mobile-control/ios-signing.test.d.ts

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