@autifyhq/aximo-cli 0.5.0 → 0.7.0

package/dist/mobile-control/ios-wda-diagnostics.js

@@ -0,0 +1,138 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { execBinary } from "./exec.js";
+/**
+ * When an XCUITest session fails to start, the Appium/WebDriver error is usually
+ * generic ("xcodebuild failed with code 65"). The real reason — an untrusted
+ * developer cert, a taken WDA bundle id, a locked device — lives in the WDA test
+ * run's `.xcresult` bundle. We read the newest one and surface its error
+ * summaries so the CLI can show the user what actually went wrong.
+ */
+/** Newest `Test-*.xcresult` under a DerivedData dir's Logs/Test, or null. */
+function newestXcresultIn(derivedDataPath) {
+    const testLogs = join(derivedDataPath, "Logs", "Test");
+    if (!existsSync(testLogs))
+        return null;
+    let newest = null;
+    for (const entry of safeReaddir(testLogs)) {
+        if (!entry.endsWith(".xcresult"))
+            continue;
+        const path = join(testLogs, entry);
+        const mtimeMs = safeMtime(path);
+        if (mtimeMs !== null && (!newest || mtimeMs > newest.mtimeMs)) {
+            newest = { path, mtimeMs };
+        }
+    }
+    return newest?.path ?? null;
+}
+/** Candidate WDA DerivedData dirs, newest first: the managed cache, then Xcode's default. */
+function candidateDerivedDataDirs(managed) {
+    const dirs = [];
+    if (managed)
+        dirs.push(managed);
+    const defaultRoot = join(homedir(), "Library", "Developer", "Xcode", "DerivedData");
+    const xcodeDirs = safeReaddir(defaultRoot)
+        .filter((entry) => entry.startsWith("WebDriverAgent-"))
+        .map((entry) => join(defaultRoot, entry))
+        .sort((a, b) => (safeMtime(b) ?? 0) - (safeMtime(a) ?? 0));
+    dirs.push(...xcodeDirs);
+    return dirs;
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function safeMtime(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/** Recursively collect messages under error/testFailure summary arrays (xcresulttool JSON). */
+function collectSummaryMessages(node, out) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectSummaryMessages(item, out);
+        return;
+    }
+    if (!node || typeof node !== "object")
+        return;
+    const obj = node;
+    for (const key of ["errorSummaries", "testFailureSummaries"]) {
+        const summaries = obj[key];
+        for (const summary of summaries?._values ?? []) {
+            const message = extractMessageString(summary?.["message"]);
+            if (message)
+                out.push(message);
+        }
+    }
+    for (const value of Object.values(obj))
+        collectSummaryMessages(value, out);
+}
+/** A message field is `{ _value: "..." }` in the legacy format, or a bare string in newer ones. */
+function extractMessageString(message) {
+    if (typeof message === "string")
+        return message.trim() || null;
+    if (message && typeof message === "object") {
+        const value = message._value;
+        if (typeof value === "string")
+            return value.trim() || null;
+    }
+    return null;
+}
+/**
+ * Extract the concise failure reason from the newest WDA `.xcresult`, e.g.
+ * "The application could not be launched because the Developer App Certificate
+ * is not trusted." Returns null when nothing usable is found (best-effort).
+ */
+export async function readWdaFailureReason(options = {}) {
+    const xcresult = (options.findXcresult ?? defaultFindXcresult)(options.derivedDataPath);
+    if (!xcresult)
+        return null;
+    const exec = options.exec ?? execBinary;
+    const json = await runXcresultTool(xcresult, exec);
+    if (!json)
+        return null;
+    const messages = [];
+    collectSummaryMessages(json, messages);
+    if (messages.length === 0)
+        return null;
+    // Prefer the shortest non-trivial message: the concise human reason rather
+    // than the giant nested "Underlying Error: …" chain that repeats it.
+    const deduped = [...new Set(messages)].filter((m) => m.length >= 15);
+    if (deduped.length === 0)
+        return null;
+    deduped.sort((a, b) => a.length - b.length);
+    return deduped[0].slice(0, 400);
+}
+function defaultFindXcresult(managed) {
+    for (const dir of candidateDerivedDataDirs(managed)) {
+        const found = newestXcresultIn(dir);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** `xcresulttool get` output as JSON. `--legacy` is required on Xcode 16+; older Xcode rejects it. */
+async function runXcresultTool(xcresult, exec) {
+    for (const args of [
+        ["xcresulttool", "get", "--legacy", "--path", xcresult, "--format", "json"],
+        ["xcresulttool", "get", "--path", xcresult, "--format", "json"],
+    ]) {
+        try {
+            const { stdout } = await exec("xcrun", args);
+            return JSON.parse(stdout.toString("utf-8"));
+        }
+        catch {
+            // try the next arg form, then give up
+        }
+    }
+    return null;
+}

package/dist/mobile-control/ios-wda-diagnostics.test.d.ts

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

package/dist/mobile-control/ios-wda-diagnostics.test.js

@@ -0,0 +1,77 @@
+import { describe, expect, it, vi } from "vitest";
+import { readWdaFailureReason } from "./ios-wda-diagnostics.js";
+// Shape mirrors `xcrun xcresulttool get --legacy --format json` for a failed WDA
+// launch (developer cert not trusted) — the exact case seen on a real device.
+const LEGACY_XCRESULT = {
+    actions: {
+        _values: [
+            {
+                actionResult: {
+                    issues: {
+                        errorSummaries: {
+                            _values: [
+                                {
+                                    issueType: { _value: "Uncategorized" },
+                                    message: {
+                                        _value: "The application could not be launched because the Developer App Certificate is not trusted.",
+                                    },
+                                },
+                                {
+                                    issueType: { _value: "Uncategorized" },
+                                    message: {
+                                        _value: "WebDriverAgentRunner-Runner encountered an error (Failed to install or launch the test runner. (Underlying Error: The application could not be launched because the Developer App Certificate is not trusted. Verify that the Developer App certificate ...))",
+                                    },
+                                },
+                            ],
+                        },
+                    },
+                },
+            },
+        ],
+    },
+};
+function execReturning(json) {
+    return vi.fn(async () => ({ stdout: Buffer.from(JSON.stringify(json), "utf-8"), stderr: "" }));
+}
+describe("readWdaFailureReason", () => {
+    it("returns null when no xcresult is found", async () => {
+        const reason = await readWdaFailureReason({ findXcresult: () => null });
+        expect(reason).toBeNull();
+    });
+    it("extracts the concise reason (shortest error summary) from the xcresult", async () => {
+        const reason = await readWdaFailureReason({
+            findXcresult: () => "/dd/Logs/Test/Test.xcresult",
+            exec: execReturning(LEGACY_XCRESULT),
+        });
+        expect(reason).toBe("The application could not be launched because the Developer App Certificate is not trusted.");
+    });
+    it("handles the newer bare-string message format", async () => {
+        const reason = await readWdaFailureReason({
+            findXcresult: () => "/dd/Logs/Test/Test.xcresult",
+            exec: execReturning({
+                issues: {
+                    testFailureSummaries: { _values: [{ message: "Unable to launch WebDriverAgent" }] },
+                },
+            }),
+        });
+        expect(reason).toBe("Unable to launch WebDriverAgent");
+    });
+    it("returns null when xcresulttool fails on both arg forms", async () => {
+        const exec = vi.fn(async () => {
+            throw new Error("xcresulttool: unknown option --legacy");
+        });
+        const reason = await readWdaFailureReason({
+            findXcresult: () => "/dd/Logs/Test/Test.xcresult",
+            exec,
+        });
+        expect(reason).toBeNull();
+        expect(exec).toHaveBeenCalledTimes(2); // tried --legacy, then without
+    });
+    it("ignores trivially short messages", async () => {
+        const reason = await readWdaFailureReason({
+            findXcresult: () => "/dd/Logs/Test/Test.xcresult",
+            exec: execReturning({ errorSummaries: { _values: [{ message: { _value: "oops" } }] } }),
+        });
+        expect(reason).toBeNull();
+    });
+});

package/dist/mobile-control/ios-wda-preinstall.d.ts

@@ -0,0 +1,64 @@
+import { type ExecFn } from "./exec.js";
+import { installAppViaDevicectl } from "./ios-devicectl.js";
+import { mintProfileViaWdaRig } from "./ios-mint.js";
+import { listProvisioningProfiles } from "./ios-profiles.js";
+import { resignIpa } from "./ios-resign.js";
+import type { IosSigningConfig } from "./ios-signing.js";
+/**
+ * Preinstalled WebDriverAgent: skip xcodebuild entirely on iOS 17+.
+ *
+ * The Appium project publishes a prebuilt real-device WDA runner for every
+ * WebDriverAgent release (built without embedded XCTest frameworks and without
+ * a provisioning profile). Downloading the version matching the bundled driver,
+ * re-signing it with the local identity, and installing it via devicectl gives
+ * the `appium:usePreinstalledWDA` session path: no Xcode build, no ~8.5 GB iOS
+ * platform download, first session in seconds. Verified on-device — see
+ * docs/ios-resign-e2e-verification.md.
+ *
+ * The downloaded release zip is cached per version under
+ * $AXIMO_HOME/ios-wda/prebuilt/<version>/; the re-sign + install run per
+ * connect (XCTest runner bundles cannot be versioned, so a fresh install is the
+ * reliable baseline, and both steps take seconds).
+ */
+export declare function readBundledWdaVersion(appiumHome?: string): string | null;
+export interface PreinstallWdaOptions {
+    udid: string;
+    /** Signing identity SHA-1 hash (ios-identity). */
+    identityHash: string;
+    /** Profile covering `<wdaBundleId>.xctrunner` on this device (ios-profiles). */
+    profilePath: string;
+    /** Base WDA bundle id; the runner installs as `<wdaBundleId>.xctrunner`. */
+    wdaBundleId: string;
+    exec?: ExecFn;
+    fetchImpl?: typeof fetch;
+    cacheDir?: string;
+    log?: (message: string) => void;
+    /** Injectable for tests. */
+    resign?: typeof resignIpa;
+    install?: typeof installAppViaDevicectl;
+    wdaVersion?: string | null;
+}
+/** Download (cached), re-sign, and install the prebuilt WDA runner. */
+export declare function preinstallWda(options: PreinstallWdaOptions): Promise<{
+    runnerBundleId: string;
+    wdaVersion: string;
+}>;
+export interface PreinstalledWdaStrategyOptions {
+    udid: string;
+    /** Device iOS major version; the driver only supports this path on 17+. */
+    iosMajor: number | null;
+    env?: NodeJS.ProcessEnv;
+    log?: (message: string) => void;
+    now?: number;
+    listProfiles?: typeof listProvisioningProfiles;
+    mint?: typeof mintProfileViaWdaRig;
+    preinstall?: typeof preinstallWda;
+}
+/**
+ * Try to set up the preinstalled-WDA session path: find (or mint) a runner
+ * profile, download+re-sign+install the prebuilt runner, and return the signing
+ * config flipped to `usePreinstalledWDA`. Returns null — with the reason logged —
+ * whenever any ingredient is missing, so the caller falls back to the classic
+ * xcodebuild flow. Opt out entirely with AXIMO_IOS_NO_PREINSTALLED_WDA.
+ */
+export declare function resolvePreinstalledWdaStrategy(signing: IosSigningConfig, options: PreinstalledWdaStrategyOptions): Promise<IosSigningConfig | null>;

package/dist/mobile-control/ios-wda-preinstall.js

@@ -0,0 +1,162 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getAximoDir } from "../commands/device/paths.js";
+import { getAppiumHome } from "./appium-server.js";
+import { envFlag } from "./env-flags.js";
+import { execBinary } from "./exec.js";
+import { installAppViaDevicectl } from "./ios-devicectl.js";
+import { mintProfileViaWdaRig } from "./ios-mint.js";
+import { listProvisioningProfiles, selectProfile } from "./ios-profiles.js";
+import { resignIpa } from "./ios-resign.js";
+/**
+ * Preinstalled WebDriverAgent: skip xcodebuild entirely on iOS 17+.
+ *
+ * The Appium project publishes a prebuilt real-device WDA runner for every
+ * WebDriverAgent release (built without embedded XCTest frameworks and without
+ * a provisioning profile). Downloading the version matching the bundled driver,
+ * re-signing it with the local identity, and installing it via devicectl gives
+ * the `appium:usePreinstalledWDA` session path: no Xcode build, no ~8.5 GB iOS
+ * platform download, first session in seconds. Verified on-device — see
+ * docs/ios-resign-e2e-verification.md.
+ *
+ * The downloaded release zip is cached per version under
+ * $AXIMO_HOME/ios-wda/prebuilt/<version>/; the re-sign + install run per
+ * connect (XCTest runner bundles cannot be versioned, so a fresh install is the
+ * reliable baseline, and both steps take seconds).
+ */
+export function readBundledWdaVersion(appiumHome = getAppiumHome()) {
+    const candidates = [
+        join(appiumHome, "node_modules", "appium-xcuitest-driver", "node_modules", "appium-webdriveragent", "package.json"),
+        join(appiumHome, "node_modules", "appium-webdriveragent", "package.json"),
+    ];
+    for (const pkgPath of candidates) {
+        try {
+            const version = JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+            if (version)
+                return version;
+        }
+        catch {
+            // try the next location
+        }
+    }
+    return null;
+}
+function releaseUrl(version) {
+    return `https://github.com/appium/WebDriverAgent/releases/download/v${version}/WebDriverAgentRunner-Runner.zip`;
+}
+const RUNNER_APP = "WebDriverAgentRunner-Runner.app";
+/** Download (cached), re-sign, and install the prebuilt WDA runner. */
+export async function preinstallWda(options) {
+    const exec = options.exec ?? execBinary;
+    const log = options.log ?? (() => { });
+    const version = options.wdaVersion !== undefined ? options.wdaVersion : readBundledWdaVersion();
+    if (!version) {
+        throw new Error("Could not determine the bundled WebDriverAgent version. Run `aximo mobile setup --platform ios`.");
+    }
+    const cacheDir = options.cacheDir ?? join(getAximoDir(), "ios-wda", "prebuilt", version);
+    const zipPath = join(cacheDir, "WebDriverAgentRunner-Runner.zip");
+    if (!existsSync(zipPath)) {
+        log(`Downloading prebuilt WebDriverAgent v${version}…`);
+        const fetchImpl = options.fetchImpl ?? fetch;
+        const response = await fetchImpl(releaseUrl(version));
+        if (!response.ok) {
+            throw new Error(`No prebuilt WebDriverAgent for v${version} (HTTP ${response.status} from GitHub releases).`);
+        }
+        mkdirSync(cacheDir, { recursive: true });
+        writeFileSync(zipPath, Buffer.from(await response.arrayBuffer()));
+    }
+    const scratch = mkdtempSync(join(tmpdir(), "aximo-wda-preinstall-"));
+    try {
+        // Wrap the bare .app into Payload/ so it can go through the same resign path
+        // as any other IPA (ditto ships with macOS and handles both directions).
+        const payloadRoot = join(scratch, "wrap");
+        const extractDir = join(payloadRoot, "Payload");
+        mkdirSync(extractDir, { recursive: true });
+        await exec("ditto", ["-x", "-k", zipPath, extractDir]);
+        if (!existsSync(join(extractDir, RUNNER_APP))) {
+            throw new Error(`Prebuilt WDA zip did not contain ${RUNNER_APP} — re-download or report.`);
+        }
+        const wrappedIpa = join(scratch, "wda.ipa");
+        await exec("ditto", ["-c", "-k", payloadRoot, wrappedIpa]);
+        const runnerBundleId = `${options.wdaBundleId}.xctrunner`;
+        const resignedIpa = join(scratch, "wda-resigned.ipa");
+        log(`Signing WebDriverAgent as ${runnerBundleId}…`);
+        await (options.resign ?? resignIpa)({
+            ipaPath: wrappedIpa,
+            outPath: resignedIpa,
+            identityHash: options.identityHash,
+            profilePath: options.profilePath,
+            bundleId: runnerBundleId,
+            exec,
+        });
+        log("Installing WebDriverAgent on the device…");
+        await (options.install ?? installAppViaDevicectl)(options.udid, resignedIpa, exec);
+        return { runnerBundleId, wdaVersion: version };
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/**
+ * Try to set up the preinstalled-WDA session path: find (or mint) a runner
+ * profile, download+re-sign+install the prebuilt runner, and return the signing
+ * config flipped to `usePreinstalledWDA`. Returns null — with the reason logged —
+ * whenever any ingredient is missing, so the caller falls back to the classic
+ * xcodebuild flow. Opt out entirely with AXIMO_IOS_NO_PREINSTALLED_WDA.
+ */
+export async function resolvePreinstalledWdaStrategy(signing, options) {
+    const env = options.env ?? process.env;
+    const log = options.log ?? (() => { });
+    if (envFlag(env, "AXIMO_IOS_NO_PREINSTALLED_WDA"))
+        return null;
+    if (options.iosMajor === null || options.iosMajor < 17)
+        return null;
+    if (!signing.teamId || !signing.identityHash)
+        return null;
+    const runnerAppId = `${signing.wdaBundleId}.xctrunner`;
+    const listProfiles = options.listProfiles ?? listProvisioningProfiles;
+    const criteria = {
+        bundleId: runnerAppId,
+        udid: options.udid,
+        teamId: signing.teamId,
+        ...(options.now !== undefined ? { now: options.now } : {}),
+    };
+    let profile = selectProfile(await listProfiles(), criteria);
+    if (!profile) {
+        log("No WebDriverAgent provisioning profile for this device — minting one via Xcode " +
+            "automatic signing (first run; takes a minute or two)…");
+        try {
+            await (options.mint ?? mintProfileViaWdaRig)({
+                teamId: signing.teamId,
+                bundleId: signing.wdaBundleId,
+                udid: options.udid,
+                signingId: signing.signingId,
+            });
+        }
+        catch (err) {
+            log(`Profile minting failed: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+        profile = selectProfile(await listProfiles(), criteria);
+        if (!profile) {
+            log("Minted profile not found on disk — falling back to the Xcode build flow.");
+            return null;
+        }
+    }
+    try {
+        await (options.preinstall ?? preinstallWda)({
+            udid: options.udid,
+            identityHash: signing.identityHash,
+            profilePath: profile.path,
+            wdaBundleId: signing.wdaBundleId,
+            log,
+        });
+    }
+    catch (err) {
+        log(`Preinstalled WebDriverAgent unavailable (${err instanceof Error ? err.message : String(err)}); ` +
+            "falling back to the Xcode build flow.");
+        return null;
+    }
+    return { ...signing, usePreinstalledWDA: true };
+}

package/dist/mobile-control/ios-wda-preinstall.test.d.ts

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

package/dist/mobile-control/ios-wda-preinstall.test.js

@@ -0,0 +1,107 @@
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { preinstallWda, readBundledWdaVersion } from "./ios-wda-preinstall.js";
+describe("readBundledWdaVersion", () => {
+    let home;
+    beforeEach(() => {
+        home = mkdtempSync(join(tmpdir(), "aximo-wda-home-"));
+    });
+    afterEach(() => {
+        rmSync(home, { recursive: true, force: true });
+    });
+    it("reads the nested driver copy first, then the hoisted one", () => {
+        const hoisted = join(home, "node_modules/appium-webdriveragent");
+        mkdirSync(hoisted, { recursive: true });
+        writeFileSync(join(hoisted, "package.json"), JSON.stringify({ version: "14.0.0" }));
+        expect(readBundledWdaVersion(home)).toBe("14.0.0");
+        const nested = join(home, "node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent");
+        mkdirSync(nested, { recursive: true });
+        writeFileSync(join(nested, "package.json"), JSON.stringify({ version: "15.0.0" }));
+        expect(readBundledWdaVersion(home)).toBe("15.0.0");
+    });
+    it("returns null when no package is present", () => {
+        expect(readBundledWdaVersion(home)).toBeNull();
+    });
+});
+describe("preinstallWda", () => {
+    let cacheDir;
+    beforeEach(() => {
+        cacheDir = mkdtempSync(join(tmpdir(), "aximo-wda-cache-"));
+    });
+    afterEach(() => {
+        rmSync(cacheDir, { recursive: true, force: true });
+    });
+    /** ditto fake: -x -k extract creates the runner app; -c -k creates the archive. */
+    const dittoExec = async (file, args) => {
+        if (file === "ditto" && args[0] === "-x") {
+            const dest = args[3];
+            if (dest)
+                mkdirSync(join(dest, "WebDriverAgentRunner-Runner.app"), { recursive: true });
+        }
+        if (file === "ditto" && args[0] === "-c") {
+            const out = args[3];
+            if (out)
+                writeFileSync(out, "zip");
+        }
+        return { stdout: Buffer.from(""), stderr: "" };
+    };
+    function makeOptions() {
+        return {
+            udid: "UDID-1",
+            identityHash: "A".repeat(40),
+            profilePath: "/profiles/wda.mobileprovision",
+            wdaBundleId: "com.aximo.wda.testteam99",
+            exec: dittoExec,
+            cacheDir,
+            wdaVersion: "15.0.0",
+            fetchImpl: vi.fn(async (_input) => new Response(new ArrayBuffer(8), { status: 200 })),
+            resign: vi.fn(async () => { }),
+            install: vi.fn(async () => ""),
+        };
+    }
+    it("downloads once, re-signs with the .xctrunner id, and installs", async () => {
+        const opts = makeOptions();
+        const result = await preinstallWda(opts);
+        expect(result).toEqual({
+            runnerBundleId: "com.aximo.wda.testteam99.xctrunner",
+            wdaVersion: "15.0.0",
+        });
+        expect(opts.fetchImpl).toHaveBeenCalledOnce();
+        expect(vi.mocked(opts.fetchImpl).mock.calls[0]?.[0]).toContain("/releases/download/v15.0.0/WebDriverAgentRunner-Runner.zip");
+        expect(existsSync(join(cacheDir, "WebDriverAgentRunner-Runner.zip"))).toBe(true);
+        expect(opts.resign).toHaveBeenCalledWith(expect.objectContaining({
+            identityHash: "A".repeat(40),
+            profilePath: "/profiles/wda.mobileprovision",
+            bundleId: "com.aximo.wda.testteam99.xctrunner",
+        }));
+        expect(opts.install).toHaveBeenCalledWith("UDID-1", expect.stringContaining("wda-resigned"), dittoExec);
+        // Second run: cache hit, no new download.
+        await preinstallWda(opts);
+        expect(opts.fetchImpl).toHaveBeenCalledOnce();
+    });
+    it("throws a clear error when the release asset is missing (404)", async () => {
+        const opts = {
+            ...makeOptions(),
+            fetchImpl: vi.fn(async () => new Response("nope", { status: 404 })),
+        };
+        await expect(preinstallWda(opts)).rejects.toThrow(/No prebuilt WebDriverAgent for v15\.0\.0/);
+    });
+    it("throws when the WDA version cannot be determined", async () => {
+        const opts = { ...makeOptions(), wdaVersion: null };
+        await expect(preinstallWda(opts)).rejects.toThrow(/aximo mobile setup/);
+    });
+    it("fails loudly when the zip has an unexpected layout", async () => {
+        const badDitto = async (file, args) => {
+            if (file === "ditto" && args[0] === "-x") {
+                const dest = args[3];
+                if (dest)
+                    mkdirSync(join(dest, "SomethingElse.app"), { recursive: true });
+            }
+            return { stdout: Buffer.from(""), stderr: "" };
+        };
+        const opts = { ...makeOptions(), exec: badDitto };
+        await expect(preinstallWda(opts)).rejects.toThrow(/did not contain/);
+    });
+});

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

@@ -0,0 +1,12 @@
+/**
+ * Map raw device-control / install failure signatures (from Appium's XCUITest
+ * driver, xcodebuild, idb, and adb) to actionable, human-readable hints. These
+ * cover the failures a real BYOD setup actually hits — untrusted developer certs,
+ * taken WDA bundle ids, missing Xcode platforms, unsigned .ipas, a downed tunnel,
+ * and the common adb install errors — so the JSON error envelope tells the user
+ * what to do next instead of surfacing an opaque toolchain error.
+ */
+/** Return an actionable hint for a known failure signature, or undefined. */
+export declare function mobileErrorHint(message: string, platform: "ios" | "android"): string | undefined;
+/** Append the matched hint to a raw error message (for contexts without an envelope). */
+export declare function withMobileHint(message: string, platform: "ios" | "android"): string;

package/dist/mobile-control/mobile-errors.js

@@ -0,0 +1,91 @@
+/**
+ * Map raw device-control / install failure signatures (from Appium's XCUITest
+ * driver, xcodebuild, idb, and adb) to actionable, human-readable hints. These
+ * cover the failures a real BYOD setup actually hits — untrusted developer certs,
+ * taken WDA bundle ids, missing Xcode platforms, unsigned .ipas, a downed tunnel,
+ * and the common adb install errors — so the JSON error envelope tells the user
+ * what to do next instead of surfacing an opaque toolchain error.
+ */
+const IOS_RULES = [
+    {
+        test: /not been explicitly trusted|Developer App Certificate is not trusted/i,
+        hint: "Trust the developer certificate on the device: Settings → General → VPN & Device Management → tap your 'Apple Development' profile → Trust (the phone needs internet). Note: re-minting a provisioning profile resets this trust, so it can recur weekly on free Apple teams.",
+    },
+    {
+        test: /cannot be registered to your development team|Failed Registering Bundle Identifier/i,
+        hint: "This WebDriverAgent bundle id is already taken. Set AXIMO_IOS_WDA_BUNDLE_ID to a unique id you own, e.g. com.<you>.WebDriverAgentRunner.",
+    },
+    {
+        test: /No profiles for|requires a development team|Signing for .* requires a development team|No signing certificate/i,
+        hint: "Add your Apple ID to Xcode (Settings → Accounts) so a development identity and profiles can be created; the CLI discovers them automatically. AXIMO_IOS_TEAM_ID is only needed to pick between multiple teams. Verify with `aximo mobile doctor`.",
+    },
+    {
+        test: /no accounts|No Apple ID accounts/i,
+        hint: "Sign into Xcode with your Apple ID (Xcode → Settings → Accounts) — profile minting requires an Xcode-managed account.",
+    },
+    {
+        test: /FairPlay-encrypted/i,
+        hint: "App Store downloads can't be re-signed. Use a development/ad-hoc build — the same .ipa you upload to a device farm works.",
+    },
+    {
+        test: /is not installed\. Please download and install the platform|iOS [\d.]+ is not installed|Unable to find a destination matching/i,
+        hint: "Install the matching iOS platform components: `xcodebuild -downloadPlatform iOS` (or Xcode → Settings → Components).",
+    },
+    {
+        test: /Developer Mode disabled|Developer Mode is not enabled/i,
+        hint: "Enable Developer Mode on the device: Settings → Privacy & Security → Developer Mode → On, then restart.",
+    },
+    {
+        // WDA now runs on a dynamic wdaLocalPort, so match any refused port, plus the
+        // driver's RemoteXPC/tunnel-registry error family.
+        test: /Connection refused to port \d+|Tunnel registry port not found|RemoteXPC|tunnel is not available/i,
+        hint: "The iOS device tunnel isn't reachable. `aximo mobile connect` starts it (needs admin); confirm with `aximo mobile doctor`. Set AXIMO_IOS_SKIP_TUNNEL only if you manage it yourself.",
+    },
+    {
+        // "is locked" (not "is unlocked") plus XCUITest's "could not be, unlocked" phrasing.
+        test: /(device|screen).{0,30}\bis locked|could not be,? unlocked|passcode/i,
+        hint: "Unlock the iPhone and keep it unlocked while connecting.",
+    },
+    {
+        // App-under-test install failures (signature/provisioning mismatch).
+        test: /ApplicationVerificationFailed|code signature.*no longer supported|MismatchedApplicationIdentifierEntitlement|valid provisioning profile|0xe800801c|0xe8008015|0xe8008029/i,
+        hint: "The .ipa isn't signed for THIS device. The CLI re-signs automatically when a signing identity is available — run `aximo mobile doctor` to check, and make sure AXIMO_IOS_NO_RESIGN isn't set. App Store apps can't be sideloaded.",
+    },
+    {
+        // Generic WDA build/launch failure — used only when nothing more specific matched.
+        test: /Unable to launch WebDriverAgent|xcodebuild failed with code|WebDriverAgentRunner-Runner encountered an error/i,
+        hint: "WebDriverAgent failed to build/launch. Usual causes: the developer cert isn't trusted on the device, the WDA bundle id is taken (set AXIMO_IOS_WDA_BUNDLE_ID), or no Team ID is set. Run `aximo mobile doctor` and check Settings → VPN & Device Management on the phone.",
+    },
+];
+const ANDROID_RULES = [
+    {
+        test: /INSTALL_FAILED_UPDATE_INCOMPATIBLE|signatures do not match/i,
+        hint: "A version signed with a different key is already installed. Uninstall it first: `adb uninstall <package>`.",
+    },
+    {
+        test: /INSTALL_FAILED_INSUFFICIENT_STORAGE/i,
+        hint: "The device is out of storage. Free up space and retry.",
+    },
+    {
+        test: /INSTALL_FAILED_OLDER_SDK|requires a newer sdk/i,
+        hint: "The app targets a newer Android version than the device runs. Use a compatible build or device.",
+    },
+    {
+        test: /no devices\/emulators found|device (unauthorized|offline)/i,
+        hint: "Reconnect the phone over USB, unlock it, and accept the RSA debugging prompt. Verify with `adb devices`.",
+    },
+];
+/** Return an actionable hint for a known failure signature, or undefined. */
+export function mobileErrorHint(message, platform) {
+    const rules = platform === "ios" ? IOS_RULES : ANDROID_RULES;
+    for (const rule of rules) {
+        if (rule.test.test(message))
+            return rule.hint;
+    }
+    return undefined;
+}
+/** Append the matched hint to a raw error message (for contexts without an envelope). */
+export function withMobileHint(message, platform) {
+    const hint = mobileErrorHint(message, platform);
+    return hint ? `${message} — ${hint}` : message;
+}

package/dist/mobile-control/mobile-errors.test.d.ts

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