@loadmill/droid-cua 2.43.0 → 2.44.0

package/build/src/device/ios/real-device/devicectl.js

@@ -0,0 +1,154 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const DEFAULT_TIMEOUT_MS = 30_000;
+const INSTALL_TIMEOUT_MS = 180_000;
+let runner = execFileAsync;
+export class DevicectlError extends Error {
+    constructor({ kind, message, code = null, domain = null }) {
+        super(message);
+        this.name = "DevicectlError";
+        this.kind = kind;
+        this.code = code;
+        this.domain = domain;
+    }
+}
+export function __setDevicectlRunner(run = null) {
+    runner = run || execFileAsync;
+}
+function errorChain(error) {
+    const chain = [];
+    let current = error;
+    while (current && typeof current === "object" && chain.length < 10) {
+        chain.push(current);
+        const underlying = current.userInfo?.NSUnderlyingError;
+        current = underlying?.error ?? underlying;
+    }
+    return chain;
+}
+function describe(error) {
+    return error.userInfo?.NSLocalizedDescription?.string || "";
+}
+function classify(chain) {
+    const text = chain.map(describe).join("\n");
+    const hasCode = (domain, code) => chain.some((e) => e.domain === domain && e.code === code);
+    if (hasCode("com.apple.dt.CoreDeviceError", 10005) || /Developer Mode is disabled/i.test(text)) {
+        return "developer-mode-disabled";
+    }
+    if (/not been explicitly trusted/i.test(text))
+        return "untrusted-developer";
+    if (/is not installed/i.test(text))
+        return "app-not-installed";
+    if (/device (is|was) locked|could not be, unlocked/i.test(text))
+        return "device-locked";
+    if (/device was not found/i.test(text))
+        return "device-not-found";
+    if (/not paired|unpaired/i.test(text))
+        return "not-paired";
+    return "unknown";
+}
+export function devicectlErrorFromJson(error) {
+    const chain = errorChain(error);
+    const descriptions = [...new Set(chain.map(describe).filter(Boolean))];
+    return new DevicectlError({
+        kind: classify(chain),
+        message: descriptions.join(" ") || `devicectl failed (${error.domain} ${error.code})`,
+        code: error.code ?? null,
+        domain: error.domain ?? null,
+    });
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function runDevicectl(args, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "droid-cua-devicectl-"));
+    const jsonPath = path.join(dir, "output.json");
+    try {
+        let runError = null;
+        try {
+            await runner("xcrun", ["devicectl", ...args, "--json-output", jsonPath], { timeout: timeoutMs });
+        }
+        catch (err) {
+            runError = err;
+        }
+        if (runError?.killed || runError?.code === "ETIMEDOUT") {
+            throw new DevicectlError({
+                kind: "timeout",
+                message: `devicectl ${args.slice(0, 3).join(" ")} timed out after ${Math.round(timeoutMs / 1000)}s`,
+            });
+        }
+        const output = await readJson(jsonPath);
+        if (output?.info?.outcome === "failed" || output?.error) {
+            throw devicectlErrorFromJson(output.error || {});
+        }
+        if (!output || runError) {
+            const detail = runError?.stderr?.trim() || runError?.message || "no JSON output";
+            throw new DevicectlError({ kind: "unknown", message: `devicectl ${args.slice(0, 3).join(" ")} failed: ${detail}` });
+        }
+        return output.result ?? {};
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+export async function listDevices() {
+    const result = await runDevicectl(["list", "devices"]);
+    return (result.devices || []).map((device) => ({
+        udid: device.hardwareProperties?.udid,
+        name: device.deviceProperties?.name,
+        model: device.hardwareProperties?.marketingName,
+        iosVersion: device.deviceProperties?.osVersionNumber,
+        pairingState: device.connectionProperties?.pairingState,
+        tunnelState: device.connectionProperties?.tunnelState,
+        transport: device.connectionProperties?.transportType,
+        developerModeStatus: device.deviceProperties?.developerModeStatus,
+        ddiServicesAvailable: device.deviceProperties?.ddiServicesAvailable === true,
+        identifier: device.identifier,
+    }));
+}
+export async function getLockState(udid) {
+    const result = await runDevicectl(["device", "info", "lockState", "--device", udid]);
+    return {
+        passcodeRequired: result.passcodeRequired === true,
+        unlockedSinceBoot: result.unlockedSinceBoot === true,
+    };
+}
+export async function getDdiServices(udid) {
+    const result = await runDevicectl(["device", "info", "ddiServices", "--device", udid]);
+    return result.ddiMetadata ?? null;
+}
+export async function listApps(udid, { includeAll = false } = {}) {
+    const args = ["device", "info", "apps", "--device", udid];
+    if (includeAll)
+        args.push("--include-all-apps");
+    const result = await runDevicectl(args);
+    return (result.apps || []).map((app) => ({
+        bundleIdentifier: app.bundleIdentifier,
+        name: app.name,
+        version: app.version,
+    }));
+}
+export async function listProcesses(udid) {
+    const result = await runDevicectl(["device", "info", "processes", "--device", udid]);
+    return (result.runningProcesses || []).map((proc) => ({
+        pid: proc.processIdentifier,
+        executable: proc.executable,
+    }));
+}
+export async function installApp(udid, appPath) {
+    const result = await runDevicectl(["device", "install", "app", "--device", udid, appPath], {
+        timeoutMs: INSTALL_TIMEOUT_MS,
+    });
+    return (result.installedApplications || []).map((app) => app.bundleID ?? app.bundleIdentifier);
+}
+export async function terminateProcess(udid, pid) {
+    await runDevicectl(["device", "process", "terminate", "--device", udid, "--pid", String(pid)]);
+}

package/build/src/device/ios/real-device/readiness.js

@@ -0,0 +1,439 @@
+import { execFile } from "node:child_process";
+import { readdir } from "node:fs/promises";
+import { promisify } from "node:util";
+import { DevicectlError, getDdiServices, getLockState, listApps, listDevices } from "./devicectl.js";
+import { didIosVersionChange, readDeviceState, updateDeviceState } from "./device-state.js";
+import { chooseSigning, fetchXcodeTeams, listPaidTeams, listXcodeAccounts, wdaRunnerBundleId } from "./signing.js";
+import { APPIUM_WDA_DIR, ensureSigning, getPinnedWdaVersion, provisionWda, wdaBundleIdBase } from "./wda-provisioning.js";
+const execFileAsync = promisify(execFile);
+const TEAM_FETCH_INTERVAL_MS = 60 * 1000;
+let lastTeamFetchAt = null;
+let teamFetchInFlight = null;
+export function __resetTeamFetchThrottle() {
+    lastTeamFetchAt = null;
+    teamFetchInFlight = null;
+}
+export const MESSAGES = {
+    installXcode: "Install Xcode from the App Store and open it once.",
+    signIntoXcode: "Sign into Xcode with your work Apple ID (Xcode > Settings > Apple Accounts).",
+    askTeamAdmin: "Ask your admin to add you with the Developer role and Access to Certificates, Identifiers & Profiles.",
+    connectUsb: "Connect your iPhone with a USB cable.",
+    trust: "Unlock the iPhone and tap Trust.",
+    developerMode: "Turn on Developer Mode: on the iPhone open Settings > Privacy & Security > Developer Mode, turn it on, let the iPhone restart, then tap Turn On and enter your passcode.",
+    unlock: "Unlock your iPhone.",
+    allowAutomation: "Enter your passcode on the iPhone to allow automation",
+    lockedMidRun: "iPhone locked — unlock to continue",
+};
+const DEVICECTL_MESSAGES = {
+    "developer-mode-disabled": `Developer Mode is off. ${MESSAGES.developerMode}`,
+    "untrusted-developer": "The iPhone doesn't trust the helper app's developer yet. On the iPhone open Settings > General > VPN & Device Management and trust it.",
+    "app-not-installed": "The helper app (WebDriverAgent) isn't installed on the iPhone.",
+    "device-locked": `The iPhone is locked. ${MESSAGES.unlock}`,
+    "device-not-found": `The iPhone isn't connected. ${MESSAGES.connectUsb}`,
+    "not-paired": `The iPhone doesn't trust this Mac yet. ${MESSAGES.trust}`,
+};
+export function messageForError(error) {
+    if (error instanceof DevicectlError && DEVICECTL_MESSAGES[error.kind])
+        return DEVICECTL_MESSAGES[error.kind];
+    if (error instanceof DevicectlError && error.kind === "timeout") {
+        return `${error.message}. Check the USB cable and unlock the iPhone.`;
+    }
+    return error?.message || String(error);
+}
+export function xcodeAdviceForIos(iosVersion) {
+    const major = Number.parseInt(String(iosVersion ?? ""), 10);
+    if (major >= 26)
+        return `Install Xcode ${major} and open it once.`;
+    return `Install an Xcode that supports iOS ${iosVersion} and open it once.`;
+}
+function pass(summary, details) {
+    return { status: "pass", summary, details };
+}
+function fail(summary, details, cause) {
+    return { status: "fail", summary, details, ...(cause ? { cause } : {}) };
+}
+function warn(summary, details) {
+    return { status: "warn", summary, details };
+}
+function teamLabel(team) {
+    return team.teamName ? `${team.teamName} (${team.teamId})` : team.teamId;
+}
+async function xcodeMissing(ctx) {
+    const apps = await ctx.deps.listXcodeApps();
+    if (!apps.length) {
+        return fail("Xcode isn't in your Applications folder.", "Install Xcode from the App Store, or move Xcode into /Applications, then open it once.", "xcode-not-in-applications");
+    }
+    const developerPath = await ctx.deps.xcodeSelectPath();
+    if (developerPath?.includes("/CommandLineTools")) {
+        const app = apps.includes("Xcode.app") ? "Xcode.app" : apps[0];
+        return fail("The Command Line Tools are selected instead of Xcode.", `Run: sudo xcode-select -s /Applications/${app}`, "command-line-tools-selected");
+    }
+    return fail("Xcode isn't installed or isn't the selected developer tool (Command Line Tools alone aren't enough).", `${MESSAGES.installXcode} If Xcode is already installed, run: sudo xcode-select -s /Applications/Xcode.app`);
+}
+function versionParts(version) {
+    return String(version ?? "").split(".").map((part) => Number.parseInt(part, 10) || 0);
+}
+export function matchingIosRuntime(sdkVersion, runtimes) {
+    const [sdkMajor, sdkMinor] = versionParts(sdkVersion);
+    return runtimes.find((runtime) => {
+        const [major, minor] = versionParts(runtime.version);
+        return major === sdkMajor && minor >= sdkMinor;
+    }) ?? null;
+}
+async function listIosRuntimes() {
+    const { stdout } = await execFileAsync("xcrun", ["simctl", "list", "runtimes", "-j"], { timeout: 30_000 });
+    return (JSON.parse(stdout).runtimes ?? []).filter((runtime) => runtime.platform === "iOS" && runtime.isAvailable);
+}
+async function fetchTeamsThrottled(ctx) {
+    if (teamFetchInFlight) {
+        await teamFetchInFlight;
+        return true;
+    }
+    const now = ctx.deps.now();
+    if (lastTeamFetchAt !== null && now - lastTeamFetchAt < TEAM_FETCH_INTERVAL_MS)
+        return false;
+    lastTeamFetchAt = now;
+    teamFetchInFlight = Promise.resolve(ctx.deps.fetchXcodeTeams()).finally(() => {
+        teamFetchInFlight = null;
+    });
+    await teamFetchInFlight;
+    return true;
+}
+export const READINESS_CHECKS = [
+    {
+        id: "xcode_devicectl",
+        title: "Xcode installed",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: [],
+        async detect(ctx) {
+            try {
+                await ctx.deps.findDevicectl();
+            }
+            catch {
+                return await xcodeMissing(ctx);
+            }
+            try {
+                await ctx.deps.checkXcodeLicense();
+            }
+            catch {
+                return fail("The Xcode license hasn't been accepted.", "Run: sudo xcodebuild -license accept", "xcode-license");
+            }
+            return pass("Xcode is installed.");
+        },
+    },
+    {
+        id: "ios_platform",
+        title: "iOS platform installed",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["xcode_devicectl"],
+        async detect(ctx) {
+            const sdkVersion = await ctx.deps.iosSdkVersion();
+            const runtime = matchingIosRuntime(sdkVersion, await ctx.deps.listIosRuntimes());
+            if (runtime)
+                return pass(`The iOS ${runtime.version} platform is installed.`);
+            return fail("The iOS platform isn't installed in Xcode.", `Xcode needs the iOS ${sdkVersion} platform to build the helper app. Install it from Xcode > Settings > Components, or run: xcodebuild -downloadPlatform iOS. It's a large download (about 10 GB).`, "ios-platform-missing");
+        },
+    },
+    {
+        id: "apple_team",
+        title: "Apple team access",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["ios_platform"],
+        async detect(ctx) {
+            let teams = await ctx.deps.listPaidTeams();
+            if (!teams.length) {
+                if (!(await ctx.deps.listXcodeAccounts()).length) {
+                    return fail("No Apple account is signed into Xcode.", MESSAGES.signIntoXcode);
+                }
+                if (await fetchTeamsThrottled(ctx))
+                    teams = await ctx.deps.listPaidTeams();
+            }
+            if (!teams.length) {
+                return fail("Signed into Xcode, but none of your accounts is in a paid Apple Developer team.", MESSAGES.askTeamAdmin);
+            }
+            const list = teams.map(teamLabel).join(", ");
+            if (ctx.teamId) {
+                const team = teams.find((t) => t.teamId === ctx.teamId);
+                if (!team) {
+                    return fail(`Team ${ctx.teamId} isn't one of your paid Apple teams (${list}).`, `Choose one of those teams, or sign into Xcode with an Apple ID that belongs to team ${ctx.teamId}.`);
+                }
+                return pass(`Using team ${teamLabel(team)}.`);
+            }
+            if (teams.length > 1) {
+                return fail(`You belong to several paid Apple teams: ${list}.`, "Choose the team droid should sign the helper app with.");
+            }
+            ctx.teamId = teams[0].teamId;
+            return pass(`Using team ${teamLabel(teams[0])}.`);
+        },
+    },
+    {
+        id: "iphone_connected",
+        title: "iPhone connected",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["xcode_devicectl"],
+        async detect(ctx) {
+            const devices = await ctx.deps.listDevices();
+            const device = ctx.udid
+                ? devices.find((d) => d.udid === ctx.udid)
+                : devices.find((d) => d.transport === "wired");
+            if (!device || device.transport !== "wired") {
+                const summary = ctx.udid ? `iPhone ${device?.name ?? ctx.udid} isn't connected by USB.` : "No iPhone is connected by USB.";
+                return fail(summary, MESSAGES.connectUsb);
+            }
+            ctx.udid = device.udid;
+            ctx.device = device;
+            ctx.previousIosVersion = (await ctx.deps.readDeviceState(device.udid, { dir: ctx.stateDir }))?.lastIosVersion ?? null;
+            ctx.iosVersionChanged = await ctx.deps.didIosVersionChange(device.udid, device.iosVersion, { dir: ctx.stateDir });
+            const changed = ctx.iosVersionChanged ? ` It moved from iOS ${ctx.previousIosVersion}; re-checking everything.` : "";
+            return pass(`${device.name} (${device.model}, iOS ${device.iosVersion}) is connected.${changed}`);
+        },
+    },
+    {
+        id: "iphone_trusted",
+        title: "iPhone trusts this Mac",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["iphone_connected"],
+        async detect(ctx) {
+            if (ctx.device.pairingState === "paired")
+                return pass("The iPhone trusts this Mac.");
+            return fail("The iPhone doesn't trust this Mac yet.", MESSAGES.trust);
+        },
+    },
+    {
+        id: "iphone_developer_mode",
+        title: "Developer Mode",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["iphone_trusted"],
+        async detect(ctx) {
+            ctx.lockState = await ctx.deps.getLockState(ctx.udid);
+            const fresh = (await ctx.deps.listDevices()).find((d) => d.udid === ctx.udid);
+            if (fresh)
+                ctx.device = fresh;
+            if (ctx.device.developerModeStatus === "enabled")
+                return pass("Developer Mode is on.");
+            return fail("Developer Mode is off.", MESSAGES.developerMode);
+        },
+    },
+    {
+        id: "iphone_unlocked",
+        title: "iPhone unlocked",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["iphone_developer_mode"],
+        async detect(ctx) {
+            const lock = ctx.lockState;
+            if (!lock.unlockedSinceBoot)
+                return fail("The iPhone hasn't been unlocked since it restarted.", MESSAGES.unlock);
+            if (lock.passcodeRequired)
+                return fail("The iPhone is locked.", MESSAGES.unlock);
+            return pass("The iPhone is unlocked.");
+        },
+    },
+    {
+        id: "iphone_device_components",
+        title: "Device components",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["iphone_unlocked"],
+        async detect(ctx) {
+            const ddi = await ctx.deps.getDdiServices(ctx.udid);
+            const build = ddi?.buildUpdate ? ` (from Xcode build ${ddi.buildUpdate})` : "";
+            if (ddi?.isUsable === true && ddi.contentIsCompatible !== false) {
+                return pass(`This Mac's device components${build} support the iPhone.`);
+            }
+            const ios = ctx.device.iosVersion;
+            return fail(`Your iPhone is on iOS ${ios}. ${xcodeAdviceForIos(ios)}`, `The device components on this Mac${build} can't drive this iPhone.`);
+        },
+    },
+    {
+        id: "wda_signing",
+        title: "Signing ready",
+        kind: "auto",
+        blocking: true,
+        dependsOn: ["apple_team", "iphone_unlocked"],
+        fixLabel: "Set up signing",
+        async detect(ctx) {
+            ctx.bundleIdBase = wdaBundleIdBase(ctx.teamId);
+            const found = await ctx.deps.chooseSigning({ teamId: ctx.teamId, bundleIdBase: ctx.bundleIdBase, udid: ctx.udid });
+            if (found.profile) {
+                ctx.signing = found;
+                return pass(found.reason);
+            }
+            return fail("Signing for the helper app isn't set up yet.", `${found.reason} droid runs a one-time Xcode build (about a minute) to set it up.`);
+        },
+        async fix(ctx) {
+            await ctx.deps.ensureSigning({ udid: ctx.udid, teamId: ctx.teamId, bundleIdBase: ctx.bundleIdBase, onProgress: ctx.onProgress });
+        },
+    },
+    {
+        id: "wda_installed",
+        title: "Helper app (WebDriverAgent)",
+        kind: "auto",
+        blocking: true,
+        dependsOn: ["wda_signing", "iphone_device_components"],
+        fixLabel: "Install helper app",
+        async detect(ctx) {
+            ctx.wdaVersion = await ctx.deps.getPinnedWdaVersion();
+            const runnerBundleId = wdaRunnerBundleId(ctx.bundleIdBase);
+            const apps = await ctx.deps.listApps(ctx.udid, { includeAll: true });
+            if (!apps.some((app) => app.bundleIdentifier === runnerBundleId)) {
+                return fail("The helper app (WebDriverAgent) isn't on the iPhone.", "droid installs it automatically in a few seconds.");
+            }
+            const recorded = (await ctx.deps.readDeviceState(ctx.udid, { dir: ctx.stateDir }))?.wda;
+            const current = recorded?.version === ctx.wdaVersion
+                && recorded?.identitySha1 === ctx.signing.identity.sha1
+                && recorded?.bundleIdBase === ctx.bundleIdBase
+                && recorded?.iosVersion === ctx.device.iosVersion;
+            if (!current) {
+                return fail("The helper app on the iPhone is out of date.", "Its version, signing or the iPhone's iOS changed since droid installed it. droid reinstalls it automatically in a few seconds.");
+            }
+            return pass(`WebDriverAgent ${ctx.wdaVersion} is installed.`);
+        },
+        async fix(ctx) {
+            const result = await ctx.deps.provisionWda({
+                udid: ctx.udid,
+                teamId: ctx.teamId,
+                bundleIdBase: ctx.bundleIdBase,
+                version: ctx.wdaVersion,
+                onProgress: ctx.onProgress,
+            });
+            await ctx.deps.updateDeviceState(ctx.udid, {
+                wda: {
+                    version: result.version,
+                    identitySha1: result.identity.sha1,
+                    bundleIdBase: result.bundleIdBase,
+                    sha256: result.sha256,
+                    profileUuid: result.profile?.uuid ?? null,
+                    iosVersion: ctx.device.iosVersion,
+                    installedAt: new Date().toISOString(),
+                },
+            }, { dir: ctx.stateDir });
+        },
+    },
+    {
+        id: "iphone_auto_lock",
+        title: "Auto-Lock",
+        kind: "human-undetectable",
+        blocking: false,
+        dependsOn: [],
+        async detect() {
+            return warn("Set Auto-Lock to Never on the iPhone while testing.", "Settings > Display & Brightness > Auto-Lock > Never. droid can't read this setting; if the iPhone locks mid-run, droid pauses until you unlock it.");
+        },
+    },
+    {
+        id: "iphone_dedicated",
+        title: "Dedicated test iPhone",
+        kind: "human-undetectable",
+        blocking: false,
+        dependsOn: [],
+        async detect() {
+            return warn("Use a test-only iPhone if you can.", "droid tests the apps and data already on the phone and never resets it.");
+        },
+    },
+];
+const defaultDeps = {
+    findDevicectl: () => execFileAsync("xcrun", ["--find", "devicectl"], { timeout: 15_000 }),
+    checkXcodeLicense: () => execFileAsync("xcodebuild", ["-license", "check"], { timeout: 15_000 }),
+    iosSdkVersion: () => execFileAsync("xcrun", ["--sdk", "iphoneos", "--show-sdk-version"], { timeout: 15_000 }).then(({ stdout }) => stdout.trim()),
+    listIosRuntimes,
+    listXcodeApps: async () => (await readdir("/Applications").catch(() => [])).filter((name) => /^Xcode.*\.app$/i.test(name)).sort(),
+    xcodeSelectPath: () => execFileAsync("xcode-select", ["-p"], { timeout: 15_000 }).then(({ stdout }) => stdout.trim(), () => null),
+    listPaidTeams,
+    listXcodeAccounts,
+    fetchXcodeTeams: () => fetchXcodeTeams({ wdaProjectDir: APPIUM_WDA_DIR }),
+    now: () => Date.now(),
+    listDevices,
+    getLockState,
+    getDdiServices,
+    listApps,
+    chooseSigning,
+    ensureSigning,
+    provisionWda,
+    getPinnedWdaVersion,
+    readDeviceState,
+    updateDeviceState,
+    didIosVersionChange,
+};
+async function detect(check, ctx) {
+    try {
+        return await check.detect(ctx);
+    }
+    catch (error) {
+        return fail(messageForError(error));
+    }
+}
+async function fixAndDetect(check, ctx) {
+    try {
+        ctx.onProgress({ step: check.id, message: `${check.fixLabel}...` });
+        await check.fix(ctx);
+    }
+    catch (error) {
+        return fail(messageForError(error), error?.details);
+    }
+    return detect(check, ctx);
+}
+function toResult(check, outcome, extra = {}) {
+    return {
+        id: check.id,
+        status: outcome.status,
+        title: check.title,
+        summary: outcome.summary,
+        ...(outcome.details ? { details: outcome.details } : {}),
+        ...(outcome.cause ? { cause: outcome.cause } : {}),
+        blocking: check.blocking,
+        checkedAt: new Date().toISOString(),
+        ...(outcome.status === "fail" && check.fix && !extra.blockedBy
+            ? { remediation: [{ kind: "run_fix", label: check.fixLabel, fixId: check.id }] }
+            : {}),
+        kind: check.kind,
+        ...extra,
+    };
+}
+export function firstBlockingFailure(results) {
+    return results.find((r) => r.blocking && r.status === "fail" && !r.blockedBy) ?? null;
+}
+export function describeFailure(result) {
+    return [`${result.title}: ${result.summary}`, result.details].filter(Boolean).join(" ");
+}
+export async function runChecks({ udid = null, teamId = null, autoFix = false, onProgress = () => { }, stateDir, deps = {} } = {}) {
+    const ctx = { udid, teamId, stateDir, onProgress, deps: { ...defaultDeps, ...deps } };
+    const results = [];
+    for (const check of READINESS_CHECKS) {
+        const blocker = check.dependsOn
+            .map((id) => results.find((r) => r.id === id))
+            .find((r) => r.status !== "pass");
+        if (blocker) {
+            const root = blocker.blockedBy ?? blocker.id;
+            const rootTitle = results.find((r) => r.id === root).title;
+            results.push(toResult(check, { status: "fail", summary: `Not checked yet: waiting for "${rootTitle}".` }, { blockedBy: root }));
+            continue;
+        }
+        let outcome = await detect(check, ctx);
+        if (outcome.status === "fail" && autoFix && check.kind === "auto" && check.fix) {
+            outcome = await fixAndDetect(check, ctx);
+        }
+        results.push(toResult(check, outcome));
+    }
+    const ready = results.every((r) => !r.blocking || r.status === "pass");
+    if (ready) {
+        await ctx.deps.updateDeviceState(ctx.udid, { lastIosVersion: ctx.device.iosVersion }, { dir: stateDir });
+    }
+    return {
+        ready,
+        results,
+        context: {
+            udid: ctx.udid,
+            teamId: ctx.teamId,
+            bundleIdBase: ctx.bundleIdBase ?? null,
+            device: ctx.device ?? null,
+            iosVersionChanged: ctx.iosVersionChanged === true,
+            previousIosVersion: ctx.previousIosVersion ?? null,
+        },
+    };
+}