@autifyhq/aximo-cli 0.5.0 → 0.7.0

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,34 @@
+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;
+    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;
+    /** 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 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<InstallUploadedAppResult>;

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

@@ -0,0 +1,55 @@
+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";
+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 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 ?? {});
+        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.d.ts

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

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

@@ -0,0 +1,113 @@
+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("auto-resigns when needed and installs an iOS app via devicectl", async () => {
+        const { exec } = captureExec();
+        const { impl } = fakeFetch(true);
+        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,
+        });
+        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();
+        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,26 @@
 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;
+    /**
+     * 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 {
     private readonly session;
     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,5 @@
+import { enrichIosSessionError } from "./ios-session-error.js";
+import { iosSigningCapabilities } from "./ios-signing.js";
 import { fetchTransport, WebDriverSession } from "./webdriver.js";
 const ANDROID_KEY_CODES = {
     enter: 66,
@@ -24,11 +26,16 @@ export class AppiumController {
     session;
     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);
     }
@@ -48,15 +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

@@ -13,9 +13,14 @@ 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.
+ * 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"]);
@@ -62,18 +63,69 @@ 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 `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})`)
+        .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.
+ * 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"]));
     }
-    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/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);
+    });
+});

package/dist/mobile-control/ios-auto-resign.d.ts

@@ -0,0 +1,45 @@
+import { listSigningIdentities } from "./ios-identity.js";
+import { mintProfileViaWdaRig } from "./ios-mint.js";
+import { listProvisioningProfiles } from "./ios-profiles.js";
+import { inspectIpa, resignIpa } from "./ios-resign.js";
+/**
+ * Zero-config auto-resign: make any dev/ad-hoc .ipa installable on the target
+ * device, mirroring what AWS Device Farm does to every upload.
+ *
+ * Decision ladder (first hit wins):
+ *   1. IPA already installs on this device → leave it alone.
+ *   2. A local profile covers the app's own bundle id + this UDID → re-sign,
+ *      keeping the bundle id (wildcard/paid-team and rebuilt-locally cases).
+ *   3. Fall back to the dedicated Aximo resign App ID for this team — reuse its
+ *      profile, or mint one via the Xcode automatic-signing rig (free teams) —
+ *      and re-sign with the bundle id remapped. The caller gets the remapped id
+ *      back so app launches can be translated.
+ *
+ * FairPlay-encrypted (App Store) binaries are rejected with a clear error; the
+ * whole step can be disabled with AXIMO_IOS_NO_RESIGN.
+ */
+export interface AutoResignResult {
+    /** Path to install: the original IPA, or a re-signed temp copy. */
+    ipaPath: string;
+    /** True when `ipaPath` is a temp file the caller should delete after install. */
+    resigned: boolean;
+    originalBundleId: string;
+    /** Bundle id actually installed (differs from original when remapped). */
+    installedBundleId: string;
+}
+/** Stable per-team bundle id used for remapped resigns (minted once, reused). */
+export declare function aximoResignBundleId(teamId: string): string;
+export interface EnsureInstallableOptions {
+    ipaPath: string;
+    udid: string;
+    env?: NodeJS.ProcessEnv;
+    /** Progress reporting (console.error in the CLI; captured in tests). */
+    log?: (message: string) => void;
+    now?: number;
+    inspect?: typeof inspectIpa;
+    listIdentities?: typeof listSigningIdentities;
+    listProfiles?: typeof listProvisioningProfiles;
+    mint?: typeof mintProfileViaWdaRig;
+    resign?: typeof resignIpa;
+}
+export declare function ensureInstallableIpa(options: EnsureInstallableOptions): Promise<AutoResignResult>;