@autifyhq/aximo-cli 0.6.0 → 0.7.0

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

@@ -0,0 +1,130 @@
+import { execFile } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { getAximoDir } from "../commands/device/paths.js";
+import { getAppiumHome } from "./appium-server.js";
+import { envFlag } from "./env-flags.js";
+/**
+ * iOS 17+/18+ device automation goes through Appium's XCUITest driver, which can
+ * only reach WebDriverAgent on the device through a RemoteXPC/CoreDevice tunnel.
+ * The driver ships a `tunnel-creation` script that must run as root (it creates a
+ * `utun` interface) and exposes a tunnel registry server on a fixed local port.
+ * Older iOS and self-managed setups can opt out with AXIMO_IOS_SKIP_TUNNEL.
+ */
+export const DEFAULT_TUNNEL_REGISTRY_PORT = 42314;
+/**
+ * True when the tunnel registry server answers its HTTP API on `port`. A raw
+ * TCP connect is not enough — an unrelated listener on the port would be
+ * mistaken for the tunnel and surface much later as an opaque XCUITest error.
+ */
+export async function isTunnelHealthy(port = DEFAULT_TUNNEL_REGISTRY_PORT, host = "127.0.0.1", timeoutMs = 1500) {
+    try {
+        const res = await fetch(`http://${host}:${port}/remotexpc/tunnels`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return false;
+        await res.json();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Single-quote a value for safe embedding in a POSIX shell script. */
+function shQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * A self-contained shell script that launches the driver's `tunnel-creation` as a
+ * detached background daemon. Run as root via the macOS auth prompt; it returns
+ * immediately while the tunnel keeps running (health-checked via the registry port).
+ */
+export function buildTunnelScript(opts) {
+    return [
+        "#!/bin/sh",
+        `export APPIUM_HOME=${shQuote(opts.appiumHome)}`,
+        'export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"',
+        `nohup ${shQuote(opts.nodePath)} ${shQuote(opts.appiumBin)} driver run xcuitest tunnel-creation > ${shQuote(opts.logFile)} 2>&1 &`,
+        "",
+    ].join("\n");
+}
+function resolveAppiumBin() {
+    return createRequire(import.meta.url).resolve("appium");
+}
+const osascriptElevate = (scriptPath) => new Promise((resolve, reject) => {
+    // The path goes in via argv + `quoted form of` so no caller-controlled string
+    // is ever spliced into the AppleScript source or the elevated shell command
+    // (AXIMO_HOME may contain quotes/spaces).
+    const appleScript = "on run argv\n" +
+        '  do shell script "/bin/sh " & quoted form of item 1 of argv with administrator privileges\n' +
+        "end run";
+    execFile("osascript", ["-e", appleScript, scriptPath], (error, _stdout, stderr) => {
+        if (error) {
+            reject(new Error(stderr?.toString().trim() || error.message));
+            return;
+        }
+        resolve();
+    });
+});
+const defaultWriteScript = (path, content, dir) => {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, content, { mode: 0o700 });
+};
+async function pollHealthy(isHealthy, port, timeoutMs, logFile) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await isHealthy(port))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    throw new Error(`iOS device tunnel did not become ready within ${timeoutMs}ms. ` +
+        `Check ${logFile} for the daemon's output. A partially-started daemon may still ` +
+        "be running; stop it before retrying: sudo pkill -f tunnel-creation");
+}
+/**
+ * Ensure the RemoteXPC tunnel is running so XCUITest can reach WebDriverAgent.
+ * Reuses an already-running tunnel (no prompt); otherwise elevates once via the
+ * macOS auth dialog to start it. No-op when AXIMO_IOS_SKIP_TUNNEL is set.
+ */
+export async function ensureIosTunnel(options = {}) {
+    const env = options.env ?? process.env;
+    const port = options.port ?? DEFAULT_TUNNEL_REGISTRY_PORT;
+    const isHealthy = options.isHealthy ?? ((p) => isTunnelHealthy(p));
+    const log = options.log ?? ((m) => console.error(m));
+    if (envFlag(env, "AXIMO_IOS_SKIP_TUNNEL")) {
+        return { reused: false, started: false, skipped: true, port };
+    }
+    // A healthy tunnel is reused as-is — this is what makes the prompt appear at
+    // most once per boot rather than once per `connect`.
+    if (await isHealthy(port)) {
+        return { reused: true, started: false, skipped: false, port };
+    }
+    const appiumHome = options.appiumHome ?? getAppiumHome();
+    const nodePath = options.nodePath ?? process.execPath;
+    const appiumBin = options.appiumBin ?? resolveAppiumBin();
+    const dir = options.dir ?? join(getAximoDir(), "ios-tunnel");
+    const scriptPath = join(dir, "tunnel.sh");
+    const logFile = join(dir, "tunnel.log");
+    const writeScript = options.writeScript ?? defaultWriteScript;
+    writeScript(scriptPath, buildTunnelScript({ appiumHome, nodePath, appiumBin, logFile }), dir);
+    log("Starting the iOS device tunnel (needs admin). Approve the macOS password / Touch ID prompt…");
+    const elevate = options.elevate ?? osascriptElevate;
+    try {
+        await elevate(scriptPath);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        const declined = /User canceled|-128/i.test(detail);
+        const lead = declined
+            ? "Admin approval was declined, so the iOS device tunnel wasn't started."
+            : `Could not start the iOS device tunnel: ${detail}.`;
+        throw new Error(`${lead} It is required for iOS 17+ to reach WebDriverAgent. Approve the macOS prompt and ` +
+            `retry, or start it yourself: sudo APPIUM_HOME=${shQuote(appiumHome)} ${shQuote(nodePath)} ` +
+            `${shQuote(appiumBin)} driver run xcuitest tunnel-creation`);
+    }
+    await pollHealthy(isHealthy, port, options.readyTimeoutMs ?? 45_000, logFile);
+    log(`iOS device tunnel is up (registry on port ${port}).`);
+    return { reused: false, started: true, skipped: false, port };
+}

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

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

package/dist/mobile-control/ios-tunnel.test.js

@@ -0,0 +1,115 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildTunnelScript, DEFAULT_TUNNEL_REGISTRY_PORT, ensureIosTunnel } from "./ios-tunnel.js";
+describe("buildTunnelScript", () => {
+    it("backgrounds tunnel-creation as a detached daemon with APPIUM_HOME set", () => {
+        const script = buildTunnelScript({
+            appiumHome: "/home/u/.aximo/appium-home",
+            nodePath: "/usr/bin/node",
+            appiumBin: "/cli/node_modules/appium/index.js",
+            logFile: "/home/u/.aximo/ios-tunnel/tunnel.log",
+        });
+        expect(script).toContain("export APPIUM_HOME='/home/u/.aximo/appium-home'");
+        expect(script).toContain("nohup '/usr/bin/node' '/cli/node_modules/appium/index.js' driver run xcuitest tunnel-creation");
+        expect(script).toContain("> '/home/u/.aximo/ios-tunnel/tunnel.log' 2>&1 &");
+    });
+    it("escapes single quotes in paths", () => {
+        const script = buildTunnelScript({
+            appiumHome: "/home/o'brien/.aximo",
+            nodePath: "/usr/bin/node",
+            appiumBin: "/a/index.js",
+            logFile: "/l.log",
+        });
+        expect(script).toContain("export APPIUM_HOME='/home/o'\\''brien/.aximo'");
+    });
+});
+describe("ensureIosTunnel", () => {
+    const stubs = () => ({
+        elevate: vi.fn(async () => { }),
+        writeScript: vi.fn(),
+        log: vi.fn(),
+    });
+    it("reuses a healthy tunnel without prompting", async () => {
+        const s = stubs();
+        const result = await ensureIosTunnel({
+            isHealthy: async () => true,
+            ...s,
+            env: {},
+        });
+        expect(result).toEqual({
+            reused: true,
+            started: false,
+            skipped: false,
+            port: DEFAULT_TUNNEL_REGISTRY_PORT,
+        });
+        expect(s.elevate).not.toHaveBeenCalled();
+        expect(s.writeScript).not.toHaveBeenCalled();
+    });
+    it("is a no-op when AXIMO_IOS_SKIP_TUNNEL is set", async () => {
+        const s = stubs();
+        const isHealthy = vi.fn(async () => false);
+        const result = await ensureIosTunnel({
+            isHealthy,
+            ...s,
+            env: { AXIMO_IOS_SKIP_TUNNEL: "1" },
+        });
+        expect(result.skipped).toBe(true);
+        expect(isHealthy).not.toHaveBeenCalled();
+        expect(s.elevate).not.toHaveBeenCalled();
+    });
+    it('does not skip for AXIMO_IOS_SKIP_TUNNEL="0"', async () => {
+        const s = stubs();
+        const result = await ensureIosTunnel({
+            isHealthy: async () => true,
+            ...s,
+            env: { AXIMO_IOS_SKIP_TUNNEL: "0" },
+        });
+        expect(result.skipped).toBe(false);
+        expect(result.reused).toBe(true);
+    });
+    it("points at the tunnel log when the daemon never becomes healthy", async () => {
+        const s = stubs();
+        await expect(ensureIosTunnel({
+            isHealthy: async () => false,
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            dir: "/tun",
+            readyTimeoutMs: 1,
+            ...s,
+            env: {},
+        })).rejects.toThrow(/tunnel\.log.*pkill -f tunnel-creation/s);
+    });
+    it("elevates and starts the tunnel when none is running", async () => {
+        const s = stubs();
+        const isHealthy = vi
+            .fn()
+            .mockResolvedValueOnce(false) // pre-check
+            .mockResolvedValue(true); // poll after elevate
+        const result = await ensureIosTunnel({
+            isHealthy,
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            dir: "/tun",
+            readyTimeoutMs: 2000,
+            ...s,
+            env: {},
+        });
+        expect(result.started).toBe(true);
+        expect(s.writeScript).toHaveBeenCalledOnce();
+        expect(s.elevate).toHaveBeenCalledWith("/tun/tunnel.sh");
+    });
+    it("throws actionable guidance when the admin prompt is declined", async () => {
+        const s = stubs();
+        s.elevate.mockRejectedValueOnce(new Error("User canceled."));
+        await expect(ensureIosTunnel({
+            isHealthy: async () => false,
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            dir: "/tun",
+            ...s,
+            env: {},
+        })).rejects.toThrow(/Admin approval was declined.*driver run xcuitest tunnel-creation/s);
+    });
+});

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

@@ -0,0 +1,39 @@
+import { type ExecFn } from "./exec.js";
+import type { IosSigningConfig } from "./ios-signing.js";
+/** Managed DerivedData cache: $AXIMO_HOME/ios-wda/<udid>/derived-data. */
+export declare function getWdaDerivedDataPath(udid?: string): string;
+/** Locate the built WDA runner's embedded provisioning profile, if present. */
+export declare function findEmbeddedProvisioning(derivedDataPath: string): string | null;
+/** Extract `ExpirationDate` from a mobileprovision (decoded via `security cms`). */
+export declare function readProvisioningExpiry(profilePath: string, exec?: ExecFn): Promise<Date | null>;
+/** Everything that, when changed, makes a cached WDA build unusable or unsafe to reuse. */
+export interface WdaCacheKey {
+    driverVersion: string | null;
+    xcodeVersion: string | null;
+    teamId: string | null;
+    wdaBundleId: string | null;
+}
+export interface ResolveWdaCachingOptions {
+    env?: NodeJS.ProcessEnv;
+    exec?: ExecFn;
+    /** Device UDID; keys the managed cache directory per device. */
+    udid?: string;
+    /** Override the default managed DerivedData directory. */
+    cacheDir?: string;
+    /** Locate the embedded profile (injectable for tests). */
+    findProfile?: (derivedDataPath: string) => string | null;
+    /** Read the installed XCUITest driver version (injectable for tests). */
+    readDriverVersion?: () => string | null;
+    now?: number;
+    minRemainingMs?: number;
+}
+/**
+ * Enrich a signing config with WDA-cache settings: point `derivedDataPath` at the
+ * managed per-device cache and enable `usePrebuiltWDA` only when a cached build
+ * exists that (a) was built with the same driver/Xcode/signing config and (b) has
+ * a provisioning profile that is still comfortably valid. A mismatched cache is
+ * deleted so the driver does a clean rebuild. Set AXIMO_IOS_NO_WDA_CACHE to
+ * disable caching entirely. A user-supplied AXIMO_IOS_DERIVED_DATA_PATH is
+ * treated as user-managed: reused on profile validity alone, never wiped.
+ */
+export declare function resolveWdaCaching(signing: IosSigningConfig, options?: ResolveWdaCachingOptions): Promise<IosSigningConfig>;

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

@@ -0,0 +1,157 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+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";
+/**
+ * WebDriverAgent is expensive to rebuild+code-sign every session. Reusing a
+ * persistent DerivedData directory lets Appium's XCUITest driver skip the build
+ * (`usePrebuiltWDA`) — but only while the cached build still matches the
+ * toolchain and signing config it was built with, and its provisioning profile
+ * is still valid. A prebuilt WDA that no longer matches hard-fails the session
+ * (the driver does not fall back to rebuilding), so staleness is detected via a
+ * cache key (driver/Xcode versions, team id, WDA bundle id) and the cache is
+ * wiped for a clean rebuild on any mismatch. The directory is per-device UDID:
+ * free-team profiles only embed the UDIDs known at build time, and concurrent
+ * first sessions on two phones must not race one shared xcodebuild output dir.
+ */
+const DEFAULT_MIN_REMAINING_MS = 24 * 60 * 60 * 1000; // rebuild when <1 day of validity is left
+const CACHE_KEY_FILE = "aximo-cache-key.json";
+/** Managed DerivedData cache: $AXIMO_HOME/ios-wda/<udid>/derived-data. */
+export function getWdaDerivedDataPath(udid) {
+    const root = join(getAximoDir(), "ios-wda");
+    if (!udid)
+        return join(root, "derived-data");
+    const safe = udid.replace(/[^A-Za-z0-9-]/g, "_");
+    return join(root, safe, "derived-data");
+}
+/** Locate the built WDA runner's embedded provisioning profile, if present. */
+export function findEmbeddedProvisioning(derivedDataPath) {
+    const productsDir = join(derivedDataPath, "Build", "Products", "Debug-iphoneos");
+    if (!existsSync(productsDir))
+        return null;
+    let entries;
+    try {
+        entries = readdirSync(productsDir);
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".app"))
+            continue;
+        const profile = join(productsDir, entry, "embedded.mobileprovision");
+        if (existsSync(profile))
+            return profile;
+    }
+    return null;
+}
+/** Extract `ExpirationDate` from a mobileprovision (decoded via `security cms`). */
+export async function readProvisioningExpiry(profilePath, exec = execBinary) {
+    let xml;
+    try {
+        ({ xml } = await exec("security", ["cms", "-D", "-i", profilePath]).then((r) => ({
+            xml: r.stdout.toString("utf-8"),
+        })));
+    }
+    catch {
+        return null;
+    }
+    const match = xml.match(/<key>ExpirationDate<\/key>\s*<date>([^<]+)<\/date>/);
+    if (!match?.[1])
+        return null;
+    const date = new Date(match[1]);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+function readInstalledDriverVersion() {
+    try {
+        const pkgPath = join(getAppiumHome(), "node_modules", "appium-xcuitest-driver", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readXcodeVersion(exec) {
+    try {
+        const result = await exec("xcodebuild", ["-version"]);
+        const firstLine = result.stdout.toString("utf-8").split("\n")[0]?.trim();
+        return firstLine || null;
+    }
+    catch {
+        return null;
+    }
+}
+function readStoredCacheKey(derivedDataPath) {
+    try {
+        return JSON.parse(readFileSync(join(derivedDataPath, CACHE_KEY_FILE), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeCacheKey(derivedDataPath, key) {
+    try {
+        mkdirSync(derivedDataPath, { recursive: true });
+        writeFileSync(join(derivedDataPath, CACHE_KEY_FILE), `${JSON.stringify(key, null, 2)}\n`);
+    }
+    catch {
+        // Best-effort: a missing key file just forces a rebuild next session.
+    }
+}
+function keysEqual(a, b) {
+    return (a.driverVersion === b.driverVersion &&
+        a.xcodeVersion === b.xcodeVersion &&
+        a.teamId === b.teamId &&
+        a.wdaBundleId === b.wdaBundleId);
+}
+/**
+ * Enrich a signing config with WDA-cache settings: point `derivedDataPath` at the
+ * managed per-device cache and enable `usePrebuiltWDA` only when a cached build
+ * exists that (a) was built with the same driver/Xcode/signing config and (b) has
+ * a provisioning profile that is still comfortably valid. A mismatched cache is
+ * deleted so the driver does a clean rebuild. Set AXIMO_IOS_NO_WDA_CACHE to
+ * disable caching entirely. A user-supplied AXIMO_IOS_DERIVED_DATA_PATH is
+ * treated as user-managed: reused on profile validity alone, never wiped.
+ */
+export async function resolveWdaCaching(signing, options = {}) {
+    const env = options.env ?? process.env;
+    if (envFlag(env, "AXIMO_IOS_NO_WDA_CACHE"))
+        return signing;
+    const exec = options.exec ?? execBinary;
+    const findProfile = options.findProfile ?? findEmbeddedProvisioning;
+    const userManaged = signing.derivedDataPath !== undefined;
+    const derivedDataPath = signing.derivedDataPath ?? options.cacheDir ?? getWdaDerivedDataPath(options.udid);
+    const enriched = { ...signing, derivedDataPath };
+    if (!userManaged) {
+        const currentKey = {
+            driverVersion: (options.readDriverVersion ?? readInstalledDriverVersion)(),
+            xcodeVersion: await readXcodeVersion(exec),
+            teamId: signing.teamId ?? null,
+            wdaBundleId: signing.wdaBundleId ?? null,
+        };
+        const storedKey = readStoredCacheKey(derivedDataPath);
+        const hasCachedBuild = findProfile(derivedDataPath) !== null;
+        if (hasCachedBuild && (!storedKey || !keysEqual(storedKey, currentKey))) {
+            // Toolchain or signing config changed since this WDA was built: a prebuilt
+            // reuse would hard-fail (or silently mismatch the driver), so start clean
+            // and let this session rebuild into the emptied cache.
+            rmSync(derivedDataPath, { recursive: true, force: true });
+            writeCacheKey(derivedDataPath, currentKey);
+            return enriched;
+        }
+        writeCacheKey(derivedDataPath, currentKey);
+    }
+    const profilePath = findProfile(derivedDataPath);
+    if (!profilePath)
+        return enriched; // no cached build yet → build (and populate the cache)
+    const expiry = await readProvisioningExpiry(profilePath, exec);
+    const now = options.now ?? Date.now();
+    const minRemainingMs = options.minRemainingMs ?? DEFAULT_MIN_REMAINING_MS;
+    if (expiry && expiry.getTime() - now > minRemainingMs) {
+        enriched.usePrebuiltWDA = true; // valid cache → reuse, skip rebuild+sign
+    }
+    return enriched;
+}

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

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

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

@@ -0,0 +1,128 @@
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { readProvisioningExpiry, resolveWdaCaching } from "./ios-wda-cache.js";
+const BASE = {
+    signingId: "Apple Development",
+    wdaBundleId: "com.example.WebDriverAgentRunner",
+    teamId: "TEAM123456",
+};
+function execReturning(byBinary) {
+    return vi.fn(async (binary) => ({
+        stdout: Buffer.from(byBinary[binary] ?? "", "utf-8"),
+        stderr: "",
+    }));
+}
+const profileXml = (expiration) => `<plist><dict><key>ExpirationDate</key><date>${expiration}</date></dict></plist>`;
+describe("readProvisioningExpiry", () => {
+    it("parses ExpirationDate from a decoded profile", async () => {
+        const exec = execReturning({ security: profileXml("2030-01-02T03:04:05Z") });
+        const date = await readProvisioningExpiry("/p.mobileprovision", exec);
+        expect(date?.toISOString()).toBe("2030-01-02T03:04:05.000Z");
+    });
+    it("returns null when security fails", async () => {
+        const exec = vi.fn(async () => {
+            throw new Error("security: no such file");
+        });
+        expect(await readProvisioningExpiry("/missing", exec)).toBeNull();
+    });
+});
+describe("resolveWdaCaching", () => {
+    const tempDirs = [];
+    const makeCacheDir = () => {
+        const dir = mkdtempSync(join(tmpdir(), "aximo-wda-cache-"));
+        tempDirs.push(dir);
+        return dir;
+    };
+    afterEach(() => {
+        for (const dir of tempDirs.splice(0)) {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    const validExec = execReturning({
+        security: profileXml("2030-01-01T00:00:00Z"),
+        xcodebuild: "Xcode 16.2\nBuild version 16C5032a",
+    });
+    const NOW = Date.parse("2026-01-01T00:00:00Z");
+    const opts = (cacheDir, overrides = {}) => ({
+        env: {},
+        cacheDir,
+        exec: validExec,
+        readDriverVersion: () => "9.0.0",
+        now: NOW,
+        ...overrides,
+    });
+    it("disables caching entirely when AXIMO_IOS_NO_WDA_CACHE is set", async () => {
+        const result = await resolveWdaCaching(BASE, { env: { AXIMO_IOS_NO_WDA_CACHE: "1" } });
+        expect(result).toEqual(BASE);
+        expect(result.derivedDataPath).toBeUndefined();
+    });
+    it('does NOT disable caching for AXIMO_IOS_NO_WDA_CACHE="0"', async () => {
+        const dir = makeCacheDir();
+        const result = await resolveWdaCaching(BASE, opts(dir, { env: { AXIMO_IOS_NO_WDA_CACHE: "0" }, findProfile: () => null }));
+        expect(result.derivedDataPath).toBe(dir);
+    });
+    it("defaults derivedDataPath but omits usePrebuiltWDA when no build is cached", async () => {
+        const dir = makeCacheDir();
+        const result = await resolveWdaCaching(BASE, opts(dir, { findProfile: () => null }));
+        expect(result.derivedDataPath).toBe(dir);
+        expect(result.usePrebuiltWDA).toBeUndefined();
+    });
+    it("reuses a validly-signed cached build only once its cache key is recorded", async () => {
+        const dir = makeCacheDir();
+        const withProfile = opts(dir, { findProfile: () => join(dir, "embedded.mobileprovision") });
+        // First resolve: cached build predates key tracking → wiped, rebuilt, key written.
+        const first = await resolveWdaCaching(BASE, withProfile);
+        expect(first.usePrebuiltWDA).toBeUndefined();
+        // Second resolve: stored key matches → prebuilt reuse.
+        const second = await resolveWdaCaching(BASE, withProfile);
+        expect(second.usePrebuiltWDA).toBe(true);
+    });
+    it("wipes the cache and rebuilds when the toolchain/signing key changes", async () => {
+        const dir = makeCacheDir();
+        const withProfile = (driverVersion) => opts(dir, {
+            findProfile: () => join(dir, "embedded.mobileprovision"),
+            readDriverVersion: () => driverVersion,
+        });
+        await resolveWdaCaching(BASE, withProfile("9.0.0"));
+        expect((await resolveWdaCaching(BASE, withProfile("9.0.0"))).usePrebuiltWDA).toBe(true);
+        const marker = join(dir, "Build");
+        writeFileSync(marker, "stale build output");
+        const afterUpgrade = await resolveWdaCaching(BASE, withProfile("10.0.0"));
+        expect(afterUpgrade.usePrebuiltWDA).toBeUndefined();
+        expect(existsSync(marker)).toBe(false); // stale build dir was wiped
+        // And the new key sticks: next resolve on the new driver version reuses again.
+        expect((await resolveWdaCaching(BASE, withProfile("10.0.0"))).usePrebuiltWDA).toBe(true);
+    });
+    it("rebuilds (no usePrebuiltWDA) when the cached profile is expired", async () => {
+        const dir = makeCacheDir();
+        const withProfile = opts(dir, {
+            findProfile: () => join(dir, "embedded.mobileprovision"),
+            exec: execReturning({
+                security: profileXml("2026-01-01T00:00:00Z"),
+                xcodebuild: "Xcode 16.2",
+            }),
+            now: Date.parse("2026-01-05T00:00:00Z"), // profile already expired
+        });
+        await resolveWdaCaching(BASE, withProfile); // record the key
+        const result = await resolveWdaCaching(BASE, withProfile);
+        expect(result.usePrebuiltWDA).toBeUndefined();
+        expect(result.derivedDataPath).toBe(dir);
+    });
+    it("treats an explicit derivedDataPath as user-managed: reused, never wiped or keyed", async () => {
+        const dir = makeCacheDir();
+        const marker = join(dir, "user-file");
+        writeFileSync(marker, "keep me");
+        const result = await resolveWdaCaching({ ...BASE, derivedDataPath: dir }, {
+            env: {},
+            exec: validExec,
+            now: NOW,
+            findProfile: () => join(dir, "embedded.mobileprovision"),
+        });
+        expect(result.derivedDataPath).toBe(dir);
+        expect(result.usePrebuiltWDA).toBe(true); // validity-only reuse, no key required
+        expect(existsSync(marker)).toBe(true);
+        expect(existsSync(join(dir, "aximo-cache-key.json"))).toBe(false);
+    });
+});

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

@@ -0,0 +1,14 @@
+import { type ExecFn } from "./exec.js";
+export interface ReadWdaFailureReasonOptions {
+    /** Managed DerivedData dir (checked before Xcode's default WebDriverAgent-* dirs). */
+    derivedDataPath?: string;
+    exec?: ExecFn;
+    /** Injectable for tests: locate the newest xcresult across candidate dirs. */
+    findXcresult?: (derivedDataPath?: string) => string | 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 declare function readWdaFailureReason(options?: ReadWdaFailureReasonOptions): Promise<string | null>;