@loadmill/droid-cua 2.43.0 → 2.44.0

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

@@ -0,0 +1,176 @@
+import net from "node:net";
+import * as appium from "../appium-client.js";
+import { getLockState } from "./devicectl.js";
+import { updateDeviceState } from "./device-state.js";
+import { MESSAGES, describeFailure, firstBlockingFailure, runChecks } from "./readiness.js";
+export const IOS_DEVICE_PREFIX = "ios-device:";
+export const WDA_LAUNCH_TIMEOUT_MS = 15_000;
+export const WDA_RELAUNCH_TIMEOUT_MS = 60_000;
+export const UNLOCK_WAIT_MS = 5 * 60_000;
+export const LOCK_CHECK_INTERVAL_MS = 20_000;
+const UNLOCK_POLL_MS = 2_000;
+let statusListener = null;
+export function setRealDeviceStatusListener(fn) {
+    statusListener = fn || null;
+}
+function announce(log, status, message) {
+    if (statusListener) {
+        statusListener({ status, message });
+    }
+    else {
+        log(message);
+    }
+}
+export function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+    });
+}
+const defaultDeps = {
+    runChecks,
+    createSession: appium.createSession,
+    deleteSession: appium.deleteSession,
+    getLockState,
+    findFreePort,
+    updateDeviceState,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+};
+export function parseIosDeviceToken(name) {
+    if (typeof name !== "string")
+        return null;
+    const trimmed = name.trim();
+    if (!trimmed.toLowerCase().startsWith(IOS_DEVICE_PREFIX))
+        return null;
+    const udid = trimmed.slice(IOS_DEVICE_PREFIX.length).trim();
+    return { udid: udid && udid.toLowerCase() !== "auto" ? udid : null };
+}
+export function realDeviceCapabilities({ udid, bundleIdBase, deviceName, wdaLocalPort, wdaLaunchTimeout = WDA_LAUNCH_TIMEOUT_MS }) {
+    return {
+        platformName: "iOS",
+        "appium:automationName": "XCUITest",
+        "appium:deviceName": deviceName || "iPhone",
+        "appium:udid": udid,
+        "appium:usePreinstalledWDA": true,
+        "appium:updatedWDABundleId": bundleIdBase,
+        "appium:wdaLaunchTimeout": wdaLaunchTimeout,
+        "appium:wdaLocalPort": wdaLocalPort,
+        "appium:noReset": true,
+        "appium:shouldTerminateApp": false,
+    };
+}
+export function isBrokenHelperError(error) {
+    const text = String(error?.message ?? error ?? "");
+    return /Code=41|Not authorized for performing UI testing|local\.pid\.0|attempt to insert nil object/i.test(text);
+}
+function messageForSessionError(error) {
+    const text = String(error?.message ?? error ?? "");
+    if (/Developer Mode is disabled|CoreDeviceError error 10005/i.test(text))
+        return `Developer Mode is off. ${MESSAGES.developerMode}`;
+    if (/is not installed/i.test(text))
+        return "The helper app (WebDriverAgent) isn't on the iPhone. Run droid again to reinstall it.";
+    return `The helper app didn't start on the iPhone: ${text}`;
+}
+export async function createRealDeviceSession({ udid, bundleIdBase, deviceName, log = console.log, deps = {} }) {
+    const { createSession, findFreePort: pickPort } = { ...defaultDeps, ...deps };
+    const wdaLocalPort = await pickPort();
+    try {
+        return await createSession(realDeviceCapabilities({ udid, bundleIdBase, deviceName, wdaLocalPort }));
+    }
+    catch (firstError) {
+        log(`The helper app didn't answer (${String(firstError?.message ?? firstError).slice(0, 160)}).`);
+        announce(log, "allow-automation", `${MESSAGES.allowAutomation}. Relaunching once...`);
+        try {
+            return await createSession(realDeviceCapabilities({ udid, bundleIdBase, deviceName, wdaLocalPort, wdaLaunchTimeout: WDA_RELAUNCH_TIMEOUT_MS }));
+        }
+        catch (error) {
+            throw new Error(messageForSessionError(error));
+        }
+    }
+}
+export async function waitForUnlock({ udid, log = console.log, timeoutMs = UNLOCK_WAIT_MS, intervalMs = UNLOCK_POLL_MS, deps = {} }) {
+    const { getLockState: readLock, sleep, now } = { ...defaultDeps, ...deps };
+    announce(log, "locked", MESSAGES.lockedMidRun);
+    const deadline = now() + timeoutMs;
+    while (now() < deadline) {
+        await sleep(intervalMs);
+        const lock = await readLock(udid).catch(() => null);
+        if (lock && !lock.passcodeRequired) {
+            announce(log, "unlocked", "iPhone unlocked, continuing.");
+            return;
+        }
+    }
+    throw new Error(`The iPhone stayed locked for ${Math.round(timeoutMs / 60_000)} minutes. Unlock it and run again.`);
+}
+export async function startRealDeviceSession({ udid, teamId, log = console.log, deps = {} }) {
+    const d = { ...defaultDeps, ...deps };
+    log(udid ? `Checking iPhone ${udid}...` : "Looking for an iPhone connected by USB...");
+    const readiness = await d.runChecks({ udid, teamId, autoFix: true, onProgress: (p) => log(p.message) });
+    if (!readiness.ready) {
+        const failure = firstBlockingFailure(readiness.results);
+        if (failure.id === "iphone_device_components") {
+            statusListener?.({ status: "device-components", message: failure.summary });
+        }
+        throw new Error(describeFailure(failure));
+    }
+    const { device, bundleIdBase } = readiness.context;
+    log(`Creating Appium session on ${device.name}...`);
+    const session = await createRealDeviceSession({ udid: device.udid, bundleIdBase, deviceName: device.name, log, deps: d });
+    await d.updateDeviceState(device.udid, { lastSuccessAt: new Date().toISOString(), teamId: readiness.context.teamId });
+    return {
+        sessionId: session.sessionId,
+        udid: device.udid,
+        realDevice: true,
+        bundleIdBase,
+        deviceName: device.name,
+        model: device.model,
+        teamId: readiness.context.teamId,
+        lockCheckedAt: d.now(),
+    };
+}
+async function restartSession(session, log, d) {
+    await d.deleteSession(session.sessionId).catch(() => { });
+    const fresh = await createRealDeviceSession({
+        udid: session.udid,
+        bundleIdBase: session.bundleIdBase,
+        deviceName: session.deviceName,
+        log,
+        deps: d,
+    });
+    return fresh.sessionId;
+}
+export async function recoverRealDeviceSession(session, error, { log = console.log, deps = {} } = {}) {
+    const d = { ...defaultDeps, ...deps };
+    const lock = await d.getLockState(session.udid).catch(() => null);
+    if (lock?.passcodeRequired) {
+        await waitForUnlock({ udid: session.udid, log, deps: d });
+    }
+    else if (isBrokenHelperError(error)) {
+        log("The helper app on the iPhone stopped responding. Starting a new session...");
+    }
+    else {
+        return null;
+    }
+    return restartSession(session, log, d);
+}
+export async function recoverIfLocked(session, { log = console.log, deps = {} } = {}) {
+    const d = { ...defaultDeps, ...deps };
+    if (Number.isFinite(session.lockCheckedAt) && d.now() - session.lockCheckedAt < LOCK_CHECK_INTERVAL_MS) {
+        return null;
+    }
+    session.lockCheckedAt = d.now();
+    const lock = await d.getLockState(session.udid).catch(() => null);
+    if (!lock?.passcodeRequired) {
+        return null;
+    }
+    await waitForUnlock({ udid: session.udid, log, deps: d });
+    const sessionId = await restartSession(session, log, d);
+    session.lockCheckedAt = d.now();
+    return sessionId;
+}

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

@@ -0,0 +1,466 @@
+import { execFile, spawn } from "node:child_process";
+import { X509Certificate, createHash } from "node:crypto";
+import { mkdtemp, readdir, 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 PROVISIONING_BUILD_TIMEOUT_MS = 10 * 60 * 1000;
+const TEAM_FETCH_TIMEOUT_MS = 90 * 1000;
+const XCODE_TEAM_DOMAINS = ["com.apple.dt.Xcode", "com.apple.dt.xcodebuild"];
+const TAIL_LINES = 40;
+export const PROFILE_DIRS = [
+    path.join(os.homedir(), "Library/Developer/Xcode/UserData/Provisioning Profiles"),
+    path.join(os.homedir(), "Library/MobileDevice/Provisioning Profiles"),
+];
+const defaultRunner = (cmd, args) => execFileAsync(cmd, args, { maxBuffer: 64 * 1024 * 1024 });
+let runner = defaultRunner;
+let spawner = spawn;
+export function __setSigningRunner(run = null) {
+    runner = run || defaultRunner;
+}
+export function __setSigningSpawn(fn = null) {
+    spawner = fn || spawn;
+}
+function unescapeXml(text) {
+    return text
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+export function parsePlist(xml) {
+    const tokens = [...xml.matchAll(/<(\/?)(dict|array|key|string|integer|real|date|data|true|false)\s*(\/?)>([^<]*)/g)].map((m) => ({
+        close: m[1] === "/",
+        tag: m[2],
+        empty: m[3] === "/",
+        text: unescapeXml(m[4]),
+    }));
+    let i = 0;
+    function value() {
+        const token = tokens[i++];
+        if (token.tag === "true" || token.tag === "false")
+            return token.tag === "true";
+        if (token.tag === "dict") {
+            const dict = {};
+            if (token.empty)
+                return dict;
+            while (!tokens[i].close) {
+                const key = tokens[i].text;
+                i += 2;
+                dict[key] = value();
+            }
+            i++;
+            return dict;
+        }
+        if (token.tag === "array") {
+            const list = [];
+            if (token.empty)
+                return list;
+            while (!tokens[i].close)
+                list.push(value());
+            i++;
+            return list;
+        }
+        if (token.empty)
+            return token.tag === "data" ? Buffer.alloc(0) : "";
+        i++;
+        if (token.tag === "integer" || token.tag === "real")
+            return Number(token.text);
+        if (token.tag === "date")
+            return new Date(token.text.trim());
+        if (token.tag === "data")
+            return Buffer.from(token.text.replace(/\s+/g, ""), "base64");
+        return token.text;
+    }
+    return tokens.length ? value() : null;
+}
+export function parseFindIdentityOutput(stdout) {
+    const identities = new Map();
+    for (const line of stdout.split("\n")) {
+        const match = line.match(/^\s*\d+\)\s+([0-9A-F]{40})\s+"(.+)"\s*$/);
+        if (!match)
+            continue;
+        const [, sha1, name] = match;
+        if (!/^(Apple Development|iPhone Developer):/.test(name))
+            continue;
+        if (!identities.has(sha1))
+            identities.set(sha1, { name, sha1 });
+    }
+    return [...identities.values()];
+}
+export function teamIdFromSubject(subject) {
+    return subject.match(/(?:^|[\n,/])\s*OU\s*=\s*([A-Z0-9]{10})\b/)?.[1] ?? null;
+}
+function certificatesFromPemOutput(stdout) {
+    return [...stdout.matchAll(/SHA-1 hash: ([0-9A-F]{40})\s*\n(-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----)/g)].map((m) => ({
+        sha1: m[1],
+        certificate: new X509Certificate(m[2]),
+    }));
+}
+export async function listSigningIdentities() {
+    const { stdout } = await runner("security", ["find-identity", "-v", "-p", "codesigning"]);
+    const identities = [];
+    for (const identity of parseFindIdentityOutput(stdout)) {
+        const certs = await runner("security", ["find-certificate", "-a", "-c", identity.name, "-Z", "-p"])
+            .then((r) => certificatesFromPemOutput(r.stdout))
+            .catch(() => []);
+        const cert = certs.find((c) => c.sha1 === identity.sha1)?.certificate;
+        identities.push({
+            ...identity,
+            teamId: cert ? teamIdFromSubject(cert.subject) : null,
+            expiresAt: cert ? new Date(cert.validTo).toISOString() : null,
+        });
+    }
+    return identities;
+}
+async function readDefaultsKey(domain, key) {
+    try {
+        const { stdout } = await runner("/bin/sh", ["-c", `defaults export ${domain} - | plutil -extract ${key} xml1 -o - -`]);
+        return parsePlist(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+export async function listXcodeTeams() {
+    const teams = new Map();
+    for (const domain of XCODE_TEAM_DOMAINS) {
+        const byAccount = (await readDefaultsKey(domain, "IDEProvisioningTeamByIdentifier")) || {};
+        for (const accountTeams of Object.values(byAccount)) {
+            for (const team of Array.isArray(accountTeams) ? accountTeams : []) {
+                if (!team.teamID || teams.has(team.teamID))
+                    continue;
+                teams.set(team.teamID, {
+                    teamId: team.teamID,
+                    teamName: team.teamName ?? null,
+                    teamType: team.teamType ?? null,
+                    isFree: team.isFreeProvisioningTeam === true,
+                });
+            }
+        }
+    }
+    return [...teams.values()];
+}
+export async function listXcodeAccounts() {
+    const lists = (await readDefaultsKey("com.apple.dt.Xcode", "DVTDeveloperAccountManagerAppleIDLists")) || {};
+    return Object.values(lists)
+        .flatMap((accounts) => (Array.isArray(accounts) ? accounts : []))
+        .map((account) => account?.identifier)
+        .filter(Boolean);
+}
+export function teamFetchBuildArgs({ wdaProjectDir, derivedDataPath }) {
+    return [
+        "build-for-testing",
+        "-project",
+        path.join(wdaProjectDir, "WebDriverAgent.xcodeproj"),
+        "-scheme",
+        "WebDriverAgentRunner",
+        "-destination",
+        "generic/platform=iOS",
+        "-derivedDataPath",
+        derivedDataPath,
+        "-allowProvisioningUpdates",
+    ];
+}
+export async function fetchXcodeTeams({ wdaProjectDir, timeoutMs = TEAM_FETCH_TIMEOUT_MS }) {
+    const derivedDataPath = await mkdtemp(path.join(os.tmpdir(), "droid-cua-team-fetch-"));
+    try {
+        await new Promise((resolve) => {
+            const child = spawner("xcodebuild", teamFetchBuildArgs({ wdaProjectDir, derivedDataPath }), { stdio: "ignore" });
+            const timer = setTimeout(() => child.kill("SIGTERM"), timeoutMs);
+            const done = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            child.on("error", done);
+            child.on("close", done);
+        });
+    }
+    finally {
+        await rm(derivedDataPath, { recursive: true, force: true });
+    }
+}
+export async function listTeams() {
+    const [identities, xcodeTeams] = await Promise.all([listSigningIdentities(), listXcodeTeams()]);
+    const teams = new Map(xcodeTeams.map((t) => [t.teamId, { ...t, inXcode: true, identities: [] }]));
+    for (const identity of identities) {
+        if (!identity.teamId)
+            continue;
+        if (!teams.has(identity.teamId)) {
+            teams.set(identity.teamId, { teamId: identity.teamId, teamName: null, teamType: null, isFree: null, inXcode: false, identities: [] });
+        }
+        teams.get(identity.teamId).identities.push(identity);
+    }
+    return [...teams.values()];
+}
+export async function listPaidTeams() {
+    return (await listTeams()).filter((team) => team.isFree === false);
+}
+export function profileFromPlist(plist, filePath) {
+    const entitlements = plist.Entitlements || {};
+    return {
+        path: filePath,
+        uuid: plist.UUID ?? null,
+        name: plist.Name ?? null,
+        teamId: plist.TeamIdentifier?.[0] ?? null,
+        appIdPattern: entitlements["application-identifier"] ?? null,
+        expiresAt: plist.ExpirationDate instanceof Date ? plist.ExpirationDate : null,
+        getTaskAllow: entitlements["get-task-allow"] === true,
+        provisionsAllDevices: plist.ProvisionsAllDevices === true,
+        devices: plist.ProvisionedDevices || [],
+        certificateSha1s: (plist.DeveloperCertificates || []).map((der) => createHash("sha1").update(der).digest("hex").toUpperCase()),
+    };
+}
+export async function loadProfiles({ dirs = PROFILE_DIRS } = {}) {
+    const profiles = [];
+    for (const dir of dirs) {
+        const files = await readdir(dir).catch(() => []);
+        for (const file of files.filter((f) => f.endsWith(".mobileprovision")).sort()) {
+            const filePath = path.join(dir, file);
+            try {
+                const { stdout } = await runner("security", ["cms", "-D", "-i", filePath]);
+                profiles.push(profileFromPlist(parsePlist(stdout), filePath));
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return profiles;
+}
+export function wdaRunnerBundleId(bundleIdBase) {
+    return `${bundleIdBase}.xctrunner`;
+}
+export function appIdCovers(appIdPattern, applicationIdentifier) {
+    if (!appIdPattern)
+        return false;
+    if (appIdPattern.endsWith("*"))
+        return applicationIdentifier.startsWith(appIdPattern.slice(0, -1));
+    return appIdPattern === applicationIdentifier;
+}
+export function profileProblems(profile, { teamId, bundleIdBase, udid, certificateSha1, now = new Date() }) {
+    const problems = [];
+    if (profile.teamId !== teamId)
+        problems.push("team");
+    if (!appIdCovers(profile.appIdPattern, `${teamId}.${wdaRunnerBundleId(bundleIdBase)}`))
+        problems.push("app-id");
+    if (!profile.provisionsAllDevices && !profile.devices.includes(udid))
+        problems.push("device");
+    if (certificateSha1 && !profile.certificateSha1s.includes(certificateSha1))
+        problems.push("certificate");
+    if (!profile.expiresAt || profile.expiresAt <= now)
+        problems.push("expired");
+    if (!profile.getTaskAllow)
+        problems.push("not-development");
+    return problems;
+}
+const PROBLEM_TEXT = {
+    "app-id": "doesn't cover the WDA bundle id",
+    device: "doesn't include this iPhone",
+    certificate: "doesn't contain the signing certificate",
+    expired: "has expired",
+    "not-development": "isn't a development profile",
+};
+function profileSummary(profile) {
+    return {
+        path: profile.path,
+        uuid: profile.uuid,
+        name: profile.name,
+        teamId: profile.teamId,
+        expiresAt: profile.expiresAt.toISOString(),
+        appIdPattern: profile.appIdPattern,
+    };
+}
+export function selectProfile(profiles, criteria) {
+    const teamProfiles = profiles.filter((p) => p.teamId === criteria.teamId);
+    if (!teamProfiles.length) {
+        return { profile: null, reason: `No provisioning profile for team ${criteria.teamId} on this Mac.` };
+    }
+    const checked = teamProfiles.map((profile) => ({ profile, problems: profileProblems(profile, criteria) }));
+    const usable = checked.filter((c) => !c.problems.length).map((c) => c.profile);
+    if (usable.length) {
+        const best = usable.sort((a, b) => b.expiresAt - a.expiresAt)[0];
+        return { profile: profileSummary(best), reason: null };
+    }
+    const closest = checked.sort((a, b) => a.problems.length - b.problems.length)[0];
+    const why = closest.problems.map((p) => PROBLEM_TEXT[p]).join(", ");
+    return {
+        profile: null,
+        reason: `No usable provisioning profile for team ${criteria.teamId}: the closest, "${closest.profile.name}", ${why}.`,
+    };
+}
+export async function findProfile({ teamId, bundleIdBase, udid, certificateSha1, profileDirs = PROFILE_DIRS, now = new Date() }) {
+    const profiles = await loadProfiles({ dirs: profileDirs });
+    return selectProfile(profiles, { teamId, bundleIdBase, udid, certificateSha1, now });
+}
+export function chooseIdentity(identities, profiles, { teamId, bundleIdBase, udid, now = new Date() }) {
+    const teamIdentities = identities
+        .filter((i) => i.teamId === teamId)
+        .sort((a, b) => (b.expiresAt || "").localeCompare(a.expiresAt || ""));
+    if (!teamIdentities.length) {
+        return { identity: null, profile: null, reason: `No Apple Development certificate for team ${teamId} on this Mac.` };
+    }
+    const candidates = teamIdentities.map((identity) => ({
+        identity,
+        ...selectProfile(profiles, { teamId, bundleIdBase, udid, certificateSha1: identity.sha1, now }),
+    }));
+    const withProfile = candidates.filter((c) => c.profile);
+    const count = teamIdentities.length;
+    if (!withProfile.length) {
+        const { identity, reason } = candidates[0];
+        return { identity, profile: null, reason };
+    }
+    const chosen = withProfile[0];
+    let reason;
+    if (count === 1) {
+        reason = `Using "${chosen.identity.name}", the only Apple Development certificate for team ${teamId}.`;
+    }
+    else if (withProfile.length === 1) {
+        reason = `Using "${chosen.identity.name}": of ${count} certificates for team ${teamId}, it is the one a valid provisioning profile contains.`;
+    }
+    else {
+        reason = `Using "${chosen.identity.name}": ${withProfile.length} certificates for team ${teamId} are in a valid provisioning profile; picked the newest.`;
+    }
+    return { identity: chosen.identity, profile: chosen.profile, reason };
+}
+export async function chooseSigning({ teamId, bundleIdBase, udid, profileDirs = PROFILE_DIRS, now = new Date() }) {
+    const [identities, profiles] = await Promise.all([listSigningIdentities(), loadProfiles({ dirs: profileDirs })]);
+    return chooseIdentity(identities, profiles, { teamId, bundleIdBase, udid, now });
+}
+export function provisioningBuildArgs({ teamId, bundleIdBase, udid, wdaProjectDir, derivedDataPath }) {
+    return [
+        "build-for-testing",
+        "-project",
+        path.join(wdaProjectDir, "WebDriverAgent.xcodeproj"),
+        "-scheme",
+        "WebDriverAgentRunner",
+        "-destination",
+        `id=${udid}`,
+        "-derivedDataPath",
+        derivedDataPath,
+        "-allowProvisioningUpdates",
+        "-allowProvisioningDeviceRegistration",
+        `DEVELOPMENT_TEAM=${teamId}`,
+        `PRODUCT_BUNDLE_IDENTIFIER=${bundleIdBase}`,
+        "CODE_SIGN_STYLE=Automatic",
+    ];
+}
+const TEAM_ADMIN_ASK = "Ask your Apple team admin for the Developer role with Access to Certificates, Identifiers & Profiles";
+const CREATE_CERTIFICATE = "Create one in Xcode > Settings > Apple Accounts > select your account > select the team > Manage Certificates > + > Apple Development, or on the Apple Developer website (developer.apple.com > Certificates, Identifiers & Profiles > Certificates). If you don't have permission to create certificates, ask your Apple Developer team admin for one.";
+export function classifyProvisioningBuildFailure(output, { teamId, udid }) {
+    if (/agreed? to the Xcode (and Apple SDKs )?license/i.test(output)) {
+        return { kind: "xcode-license", message: "Open Xcode once and accept its license, then retry." };
+    }
+    if (/Unable to find a destination matching/i.test(output)) {
+        return {
+            kind: "device-unavailable",
+            message: "Xcode can't reach the iPhone. Keep it connected by USB, unlocked and trusted, then retry.",
+        };
+    }
+    if (/Revoke certificate:|private key is not installed in your keychain/i.test(output)) {
+        return {
+            kind: "certificate-key-missing",
+            message: "There's no usable Apple Development certificate for your team on this Mac.",
+            details: `${CREATE_CERTIFICATE} Then retry.`,
+        };
+    }
+    if (/register(ing)? (this |the )?device|device registration|no devices from which to generate|not registered/i.test(output)) {
+        return {
+            kind: "device-registration",
+            message: `Apple didn't let your account register this iPhone (${udid}) with team ${teamId}. ${TEAM_ADMIN_ASK}, or ask them to add the iPhone under Devices.`,
+        };
+    }
+    if (/No Accounts?\b|No account for team|Add a new account in|valid credentials|session has expired|sign in with your Apple ID/i.test(output)) {
+        return {
+            kind: "no-account",
+            message: `Xcode has no signed-in Apple ID for team ${teamId}. Open Xcode > Settings > Apple Accounts, sign in with your work Apple ID, then retry.`,
+        };
+    }
+    if (/does(n't| not) have (the )?(required )?permission|do(n't| not) have (the )?(required )?(permission|access|privileges)|not allowed to (perform|create)|insufficient (permissions|privileges)|team admin/i.test(output)) {
+        return {
+            kind: "team-access",
+            message: `Your Apple ID can't create signing certificates or profiles for team ${teamId}. ${TEAM_ADMIN_ASK}.`,
+        };
+    }
+    if (/No "(iOS|Apple) Development" signing certificate/i.test(output)) {
+        return {
+            kind: "certificate-missing",
+            message: "Xcode was still creating your signing certificate when it signed. Running the build again usually fixes this.",
+            details: `If it keeps failing, make sure there's an Apple Development certificate for your team on this Mac. ${CREATE_CERTIFICATE}`,
+        };
+    }
+    const firstError = output.match(/\berror:\s*(.+)/i)?.[1].trim();
+    return {
+        kind: "unknown",
+        message: "The one-time signing build failed. See the build output for details.",
+        ...(firstError ? { details: `Xcode reported: ${firstError}` } : {}),
+    };
+}
+export function runProvisioningBuild({ teamId, bundleIdBase, udid, wdaProjectDir, derivedDataPath, onOutput = () => { }, timeoutMs = PROVISIONING_BUILD_TIMEOUT_MS, }) {
+    const started = Date.now();
+    const args = provisioningBuildArgs({ teamId, bundleIdBase, udid, wdaProjectDir, derivedDataPath });
+    const tail = [];
+    const errorLines = [];
+    let pending = "";
+    const addLine = (line) => {
+        tail.push(line);
+        if (tail.length > TAIL_LINES)
+            tail.shift();
+        if (/\berror\b/i.test(line) && errorLines.length < 50)
+            errorLines.push(line);
+    };
+    return new Promise((resolve) => {
+        let settled = false;
+        let timedOut = false;
+        const child = spawner("xcodebuild", args, { stdio: ["ignore", "pipe", "pipe"] });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (pending)
+                addLine(pending);
+            const logTail = tail.join("\n");
+            const ok = result.ok;
+            resolve({
+                ok,
+                durationMs: Date.now() - started,
+                logTail,
+                error: ok ? null : result.error || classifyProvisioningBuildFailure(`${errorLines.join("\n")}\n${logTail}`, { teamId, udid }),
+            });
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+        }, timeoutMs);
+        const onData = (chunk) => {
+            const text = chunk.toString();
+            onOutput(text);
+            const lines = (pending + text).split("\n");
+            pending = lines.pop();
+            lines.forEach(addLine);
+        };
+        child.stdout?.on("data", onData);
+        child.stderr?.on("data", onData);
+        child.on("error", (error) => {
+            finish({
+                ok: false,
+                error: error.code === "ENOENT"
+                    ? { kind: "xcode-missing", message: "xcodebuild was not found. Install Xcode and open it once, then retry." }
+                    : { kind: "unknown", message: `Could not start xcodebuild: ${error.message}` },
+            });
+        });
+        child.on("close", (code) => {
+            if (timedOut) {
+                finish({
+                    ok: false,
+                    error: { kind: "timeout", message: `The one-time signing build didn't finish within ${Math.round(timeoutMs / 60000)} minutes.` },
+                });
+                return;
+            }
+            finish({ ok: code === 0 });
+        });
+    });
+}