@leera.io/qa-runner 1.0.0

package/dist/src/devices/ios/setup.js

@@ -0,0 +1,186 @@
+import { spawn } from 'node:child_process';
+import { closeSync, mkdirSync, openSync, rmSync } from 'node:fs';
+import { bundledDrivers } from '../../appium/drivers.js';
+import { appiumHomeDir, seedAppiumHome } from '../../appium/home.js';
+import { bundledAppium } from '../../appium/server.js';
+import { ExitCode, messageOf } from '../../errors.js';
+import { ensureHome } from '../../home.js';
+import { runTool } from '../android/adb.js';
+import { appiumDriverListArgv } from '../android/setup.js';
+import { listIosDevices } from './index.js';
+import { loadIosSettings } from './settings.js';
+import { bundledWda, developerDir, isCommandLineToolsOnly, isWdaSimulatorBuilt, wdaCacheDir, wdaSimulatorBuildArgv, xcodeInfo } from './wda.js';
+const XCODE_FIX = 'Install Xcode from the App Store, open it once, then run `sudo xcode-select -s /Applications/Xcode.app`';
+function spawnLogged(file, args, logFile, env) {
+    return new Promise((resolve) => {
+        const fd = openSync(logFile, 'w', 0o600);
+        const done = (code) => {
+            closeSync(fd);
+            resolve(code);
+        };
+        const child = spawn(file, args, { stdio: ['ignore', fd, fd], env });
+        child.on('error', () => done(1));
+        child.on('close', (code) => done(code ?? 1));
+    });
+}
+/**
+ * `setup ios`: checks for full Xcode, seeds Appium's home with the bundled XCUITest driver,
+ * prebuilds WebDriverAgent for simulators into the runner home, then lists devices.
+ */
+export async function setupIos(io, paths, options = {}) {
+    if (io.platform !== 'darwin') {
+        io.stderr('iOS jobs need a Mac with Xcode; this computer cannot run them.');
+        return ExitCode.environmentNotReady;
+    }
+    ensureHome(paths);
+    let ok = true;
+    // 1. Xcode.
+    const dir = await developerDir();
+    if (!dir || isCommandLineToolsOnly(dir)) {
+        io.stderr(`Full Xcode is needed (found ${dir ?? 'no developer directory'}). ${XCODE_FIX}.`);
+        return ExitCode.environmentNotReady;
+    }
+    const xcode = await xcodeInfo();
+    if (!xcode) {
+        io.stderr(`xcodebuild does not run. Open Xcode once to accept its licence and install its components. ${XCODE_FIX}.`);
+        return ExitCode.environmentNotReady;
+    }
+    io.stdout(`Xcode ${xcode.version}${xcode.build ? ` (${xcode.build})` : ''} at ${dir}`);
+    // 2. Appium and its driver.
+    const appium = bundledAppium();
+    const drivers = bundledDrivers(io.platform);
+    const wdaSources = bundledWda();
+    if (!appium || !drivers.some((d) => d.platforms.includes('ios')) || !wdaSources) {
+        io.stderr('Appium and its XCUITest driver are not installed with this runner. Install the runner with its installer, or with npm without --omit=optional.');
+        return ExitCode.environmentNotReady;
+    }
+    const home = appiumHomeDir(paths);
+    const seeded = seedAppiumHome(home, appium, drivers);
+    io.stdout(`Appium ${appium.version} home: ${home}${seeded.changed ? ' (updated)' : ''}`);
+    try {
+        const argv = appiumDriverListArgv(process.execPath, appium.dir);
+        const { stdout } = await runTool(argv[0], argv.slice(1), { timeoutMs: 120_000, env: { ...io.env, APPIUM_HOME: home } });
+        const listed = JSON.parse(stdout.slice(stdout.indexOf('{')));
+        const found = listed.xcuitest;
+        if (found)
+            io.stdout(`  driver xcuitest ${found.version ?? wdaSources.driverVersion}: installed`);
+        else {
+            ok = false;
+            io.stderr(`  driver xcuitest: Appium does not see it in ${home}`);
+        }
+    }
+    catch (error) {
+        ok = false;
+        io.stderr(`Appium could not list its drivers: ${messageOf(error)}`);
+    }
+    // 3. WebDriverAgent for simulators.
+    const wdaDir = wdaCacheDir(paths, wdaSources.driverVersion, xcode.version);
+    if (isWdaSimulatorBuilt(wdaDir) && !options.rebuild) {
+        io.stdout(`WebDriverAgent for simulators: built (${wdaDir})`);
+    }
+    else {
+        rmSync(wdaDir, { recursive: true, force: true });
+        mkdirSync(wdaDir, { recursive: true, mode: 0o700 });
+        const logFile = `${wdaDir}.build.log`;
+        io.stdout(`Building WebDriverAgent for simulators into ${wdaDir} (this takes a few minutes; log: ${logFile}) ...`);
+        const started = Date.now();
+        const code = await spawnLogged('xcodebuild', wdaSimulatorBuildArgv(wdaSources.project, wdaDir), logFile, io.env);
+        if (code !== 0 || !isWdaSimulatorBuilt(wdaDir)) {
+            ok = false;
+            io.stderr(`WebDriverAgent did not build (xcodebuild exit ${code}); see ${logFile}.`);
+        }
+        else {
+            io.stdout(`WebDriverAgent built in ${Math.round((Date.now() - started) / 1000)} s.`);
+        }
+    }
+    // 4. Devices.
+    const inventory = await listIosDevices();
+    for (const error of inventory.errors)
+        io.stderr(`  ${error}`);
+    if (inventory.devices.length === 0)
+        io.stdout('Devices: none (create a simulator in Xcode > Window > Devices and Simulators)');
+    else {
+        io.stdout('Devices:');
+        for (const device of inventory.devices) {
+            io.stdout(`  ${device.id}  ${device.name}  ${device.kind}${device.os_version ? ` iOS ${device.os_version}` : ''}  ${device.state}${device.can_boot ? ' (booted when a job needs it)' : ''}`);
+        }
+    }
+    for (const reason of inventory.notReady)
+        io.stdout(`  ${reason}`);
+    const settings = loadIosSettings(io.env, paths);
+    for (const problem of settings.problems)
+        io.stderr(`  ${problem}`);
+    if (inventory.devices.some((d) => d.kind === 'real') && !settings.teamId) {
+        io.stdout('  Real devices need your Apple Developer Team ID to sign WebDriverAgent: leera-qa-runner config set ios.team_id <TEAM ID>');
+    }
+    io.stdout(ok ? 'iOS is set up. Check everything with `leera-qa-runner doctor --platform ios`.' : 'iOS setup is incomplete; see the messages above.');
+    return ok ? ExitCode.ok : ExitCode.environmentNotReady;
+}
+/** `doctor` checks for iOS: full Xcode, the driver, the WebDriverAgent build, simulators, real-device readiness and signing. */
+export async function iosChecks(env, paths, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== 'darwin') {
+        return [{ id: 'ios.host', title: 'iOS: host', status: 'warn', detail: 'iOS jobs need a Mac with Xcode' }];
+    }
+    const checks = [];
+    const dir = await developerDir();
+    const xcode = await xcodeInfo();
+    if (!dir || isCommandLineToolsOnly(dir) || !xcode) {
+        checks.push({
+            id: 'ios.xcode',
+            title: 'iOS: Xcode',
+            status: 'fail',
+            detail: dir && isCommandLineToolsOnly(dir) ? `xcode-select points at the Command Line Tools (${dir}); full Xcode is needed` : 'Xcode is not installed or xcodebuild does not run',
+            fix: XCODE_FIX,
+        });
+        return checks;
+    }
+    checks.push({ id: 'ios.xcode', title: 'iOS: Xcode', status: 'ok', detail: `Xcode ${xcode.version} (${dir})` });
+    const wdaSources = bundledWda();
+    if (!bundledAppium() || !wdaSources) {
+        checks.push({ id: 'ios.appium', title: 'iOS: Appium', status: 'fail', detail: 'the XCUITest driver is not installed with this runner' });
+        return checks;
+    }
+    checks.push({ id: 'ios.appium', title: 'iOS: Appium', status: 'ok', detail: `XCUITest driver ${wdaSources.driverVersion}` });
+    const wdaDir = wdaCacheDir(paths, wdaSources.driverVersion, xcode.version);
+    checks.push(isWdaSimulatorBuilt(wdaDir)
+        ? { id: 'ios.wda', title: 'iOS: WebDriverAgent', status: 'ok', detail: `built for simulators (${wdaDir})` }
+        : {
+            id: 'ios.wda',
+            title: 'iOS: WebDriverAgent',
+            status: 'warn',
+            detail: 'not prebuilt for this driver and Xcode; the first simulator job builds it (several minutes)',
+            fix: 'leera-qa-runner setup ios',
+        });
+    const inventory = await listIosDevices();
+    const simulators = inventory.devices.filter((d) => d.kind === 'simulator');
+    const real = inventory.devices.filter((d) => d.kind === 'real');
+    checks.push(simulators.length > 0
+        ? { id: 'ios.simulators', title: 'iOS: simulators', status: 'ok', detail: `${simulators.length} (${[...new Set(simulators.map((d) => `iOS ${d.os_version}`))].join(', ')})` }
+        : {
+            id: 'ios.simulators',
+            title: 'iOS: simulators',
+            status: 'warn',
+            detail: inventory.errors.join('; ') || 'no iOS simulator exists',
+            fix: 'Add an iOS simulator runtime in Xcode > Settings > Components',
+        });
+    const settings = loadIosSettings(env, paths);
+    if (real.length > 0 || inventory.notReady.length > 0) {
+        checks.push(inventory.notReady.length > 0
+            ? { id: 'ios.devices', title: 'iOS: real devices', status: 'warn', detail: inventory.notReady.join('; ') }
+            : { id: 'ios.devices', title: 'iOS: real devices', status: 'ok', detail: real.map((d) => `${d.name} (iOS ${d.os_version ?? '?'})`).join(', ') });
+        checks.push(settings.teamId
+            ? { id: 'ios.signing', title: 'iOS: signing', status: 'ok', detail: `team ${settings.teamId}${settings.wdaBundleId ? `, WebDriverAgent as ${settings.wdaBundleId}` : ''}` }
+            : {
+                id: 'ios.signing',
+                title: 'iOS: signing',
+                status: 'warn',
+                detail: ['real devices need a Team ID to sign WebDriverAgent', ...settings.problems].join('; '),
+                fix: 'leera-qa-runner config set ios.team_id <TEAM ID>',
+            });
+    }
+    else if (settings.problems.length > 0) {
+        checks.push({ id: 'ios.signing', title: 'iOS: signing', status: 'warn', detail: settings.problems.join('; ') });
+    }
+    return checks;
+}

package/dist/src/devices/ios/simctl.js

@@ -0,0 +1,201 @@
+import { runTool, ToolError } from '../android/adb.js';
+/** A simulator UDID as CoreSimulator writes it; checked before it goes into any argv. */
+export const UDID_RE = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/;
+export function assertSimUdid(udid) {
+    if (!UDID_RE.test(udid))
+        throw new Error(`'${udid}' is not a simulator UDID`);
+    return udid;
+}
+/** `com.apple.CoreSimulator.SimRuntime.iOS-26-5` → `{platform: 'iOS', version: '26.5'}`. */
+export function parseRuntimeId(runtime) {
+    const match = /SimRuntime\.([A-Za-z]+)-(\d+(?:-\d+)*)$/.exec(runtime);
+    if (!match)
+        return null;
+    return { platform: match[1], version: match[2].split('-').join('.') };
+}
+/** Parses `simctl list devices --json`: the iOS simulators, available or not. */
+export function parseSimctlDevices(json) {
+    const doc = (typeof json === 'string' ? JSON.parse(json) : json);
+    const out = [];
+    for (const [runtime, list] of Object.entries(doc.devices ?? {})) {
+        const parsed = parseRuntimeId(runtime);
+        if (parsed?.platform !== 'iOS' || !Array.isArray(list))
+            continue;
+        for (const raw of list) {
+            const udid = typeof raw.udid === 'string' ? raw.udid : '';
+            const name = typeof raw.name === 'string' ? raw.name : '';
+            if (!UDID_RE.test(udid) || !name)
+                continue;
+            out.push({
+                udid,
+                name,
+                state: typeof raw.state === 'string' ? raw.state : 'Shutdown',
+                runtime,
+                osVersion: parsed.version,
+                deviceType: typeof raw.deviceTypeIdentifier === 'string' ? raw.deviceTypeIdentifier : null,
+                available: raw.isAvailable !== false,
+                lastBootedAt: typeof raw.lastBootedAt === 'string' ? raw.lastBootedAt : null,
+            });
+        }
+    }
+    return out;
+}
+export function simctlListArgv() {
+    return ['simctl', 'list', 'devices', '--json'];
+}
+export function simctlBootArgv(udid) {
+    return ['simctl', 'boot', assertSimUdid(udid)];
+}
+/** Waits until the simulator finished booting (`-b` boots it first when it is shut down). */
+export function simctlBootstatusArgv(udid) {
+    return ['simctl', 'bootstatus', assertSimUdid(udid), '-b'];
+}
+export function simctlShutdownArgv(udid) {
+    return ['simctl', 'shutdown', assertSimUdid(udid)];
+}
+/** An executable name that is safe inside a log predicate string. */
+export const PROCESS_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9 ._+-]{0,99}$/;
+/**
+ * Follows the simulator's unified log for one process, compact style. The predicate is one argv
+ * element (no shell) and the name is validated first.
+ */
+export function simctlLogStreamArgv(udid, processName) {
+    if (!PROCESS_NAME_RE.test(processName))
+        throw new Error(`'${processName}' is not a process name`);
+    return ['simctl', 'spawn', assertSimUdid(udid), 'log', 'stream', '--style', 'compact', '--level', 'default', '--predicate', `process == "${processName}"`];
+}
+/** `simctl appinfo <udid> <bundle id>` (a plist-like dump with `CFBundleExecutable`). */
+export function simctlAppinfoArgv(udid, bundleId) {
+    return ['simctl', 'appinfo', assertSimUdid(udid), assertBundleId(bundleId)];
+}
+/** Reads `CFBundleExecutable = Preferences;` (or `"My App"`) from `simctl appinfo` output. */
+export function parseAppinfoExecutable(output) {
+    const match = /CFBundleExecutable\s*=\s*(?:"([^"]+)"|([^;\s]+))\s*;/.exec(output);
+    return match ? (match[1] ?? match[2] ?? null) : null;
+}
+export const BUNDLE_ID_RE = /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/;
+export function assertBundleId(bundleId) {
+    if (!BUNDLE_ID_RE.test(bundleId) || bundleId.length > 255)
+        throw new Error(`'${bundleId}' is not a valid iOS bundle id`);
+    return bundleId;
+}
+/** Default time a simulator gets to finish booting (config `ios.simulator_boot_timeout_secs`). */
+export const DEFAULT_SIMULATOR_BOOT_TIMEOUT_MS = 300_000;
+/** `simctl bootstatus` did not report the simulator booted within the timeout. */
+export class SimulatorBootTimeout extends Error {
+    udid;
+    timeoutMs;
+    constructor(udid, timeoutMs, detail) {
+        super(`the simulator ${udid} did not finish booting within ${Math.round(timeoutMs / 1000)}s${detail ? ` (${detail})` : ''}`);
+        this.udid = udid;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/** `simctl boot` refuses a simulator that is already booted or booting; that is not a failure. */
+export function isAlreadyBootingError(message) {
+    return /current state:\s*(Booted|Booting)/i.test(message);
+}
+/**
+ * Boots a simulator and waits until it has finished booting. A slow Mac (or a busy CI host) can
+ * leave a first boot stuck, for example "Waiting on BackBoard"; a boot that times out is shut
+ * down and tried again, `retries` times. Errors other than a timeout are not retried; an error from
+ * `simctl boot` alone is logged and the wait (`bootstatus -b`, which boots too) decides.
+ */
+export async function bootSimulator(udid, ops, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_SIMULATOR_BOOT_TIMEOUT_MS;
+    const retries = Math.max(0, options.retries ?? 1);
+    const now = options.now ?? Date.now;
+    const log = options.log ?? (() => undefined);
+    const attempts = [];
+    for (let attempt = 1;; attempt++) {
+        const started = now();
+        log('booting the simulator', { udid, attempt, timeout_ms: timeoutMs });
+        try {
+            try {
+                await ops.boot(udid);
+            }
+            catch (error) {
+                // `bootstatus -b` boots the simulator itself and fails for real when it cannot; `simctl boot`
+                // can also refuse transiently (NSPOSIXErrorDomain code 22), so its error alone is not fatal.
+                const message = error instanceof Error ? error.message : String(error);
+                if (!isAlreadyBootingError(message))
+                    log('simctl boot failed; waiting with bootstatus -b', { udid, attempt, error: message });
+            }
+            await ops.waitForBoot(udid, timeoutMs);
+        }
+        catch (error) {
+            const ms = now() - started;
+            const timedOut = error instanceof SimulatorBootTimeout;
+            attempts.push({ attempt, ms, outcome: timedOut ? 'timeout' : 'error' });
+            if (!timedOut || attempt > retries) {
+                log('the simulator did not boot', { udid, attempt, ms, error: error instanceof Error ? error.message : String(error) });
+                throw error;
+            }
+            log('the simulator boot timed out; shutting it down and trying again', { udid, attempt, ms });
+            await ops.shutdown(udid);
+            continue;
+        }
+        const ms = now() - started;
+        attempts.push({ attempt, ms, outcome: 'booted' });
+        log('the simulator booted', { udid, attempt, ms });
+        return attempts;
+    }
+}
+/** Thin wrapper over `xcrun simctl`. */
+export class Simctl {
+    xcrun;
+    constructor(xcrun = 'xcrun') {
+        this.xcrun = xcrun;
+    }
+    run(args, timeoutMs = 60_000) {
+        return runTool(this.xcrun, args, { timeoutMs }).then((r) => r.stdout);
+    }
+    async list() {
+        return parseSimctlDevices(await this.run(simctlListArgv(), 30_000));
+    }
+    async boot(udid) {
+        await this.run(simctlBootArgv(udid), 120_000);
+    }
+    async waitForBoot(udid, timeoutMs) {
+        const started = Date.now();
+        try {
+            await this.run(simctlBootstatusArgv(udid), timeoutMs);
+        }
+        catch (error) {
+            // execFile kills bootstatus when the timeout passes; its last status line says where it was stuck.
+            const elapsed = Date.now() - started;
+            if (elapsed >= timeoutMs - 1_000 || (error instanceof ToolError && error.code === null)) {
+                const detail = error instanceof Error ? error.message.replace(/^.*? failed: /, '') : '';
+                throw new SimulatorBootTimeout(udid, timeoutMs, detail.slice(0, 200));
+            }
+            throw error;
+        }
+    }
+    /** Boots the simulator and waits for it, retrying once after a timeout. */
+    bootAndWait(udid, options = {}) {
+        return bootSimulator(udid, this, options);
+    }
+    async shutdown(udid) {
+        await this.run(simctlShutdownArgv(udid), 60_000).catch(() => undefined);
+    }
+    async executableName(udid, bundleId) {
+        try {
+            return parseAppinfoExecutable(await this.run(simctlAppinfoArgv(udid, bundleId), 20_000));
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** The Simulator UI app's bundle id (Appium restarts a headless simulator when this runs, or vice versa). */
+export const SIMULATOR_APP_BUNDLE_ID = 'com.apple.iphonesimulator';
+/** True when Simulator.app is running on this Mac (`lsappinfo`, as Appium checks it). */
+export async function simulatorAppRunning() {
+    try {
+        const { stdout } = await runTool('lsappinfo', ['info', '-only', 'pid', SIMULATOR_APP_BUNDLE_ID], { timeoutMs: 10_000 });
+        return /"pid"\s*=\s*\d+/.test(stdout);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/devices/ios/syslog.js

@@ -0,0 +1,185 @@
+import { spawn } from 'node:child_process';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { PROCESS_NAME_RE, simctlLogStreamArgv } from './simctl.js';
+/** Same limits as the Android logcat sink, so step debug looks the same on both platforms. */
+export const SYSLOG_LIMITS = { linesPerStep: 200, crashesPerStep: 10, lineChars: 500, crashChars: 8_000, drain: 50 };
+/** Parses one `log stream --style compact` line: `2026-09-17 10:12:01.123 E  Preferences[1234:5678] [sub:cat] message`. */
+export function parseCompactLogLine(line) {
+    const match = /^(\d{4}-\d\d-\d\d \d\d:\d\d:\d\d\.\d+)\s+([A-Za-z]{1,2})\s+([^[\]]+?)\[(\d+):[0-9a-fx]+\]\s+(.*)$/.exec(line);
+    if (!match)
+        return null;
+    return { time: match[1], type: match[2], process: match[3].trim(), pid: Number(match[4]), message: match[5] };
+}
+/**
+ * Parses a real-device syslog line as Appium's `syslog` log returns it:
+ * `Sep 17 10:12:01 iPhone Preferences(UIKitCore)[123] <Error>: message`.
+ */
+export function parseDeviceSyslogLine(line) {
+    const match = /^(\w{3}\s+\d+\s+\d\d:\d\d:\d\d)\s+\S+\s+([^([\s]+)(?:\([^)]*\))?\[(\d+)\]\s+<(\w+)>:\s?(.*)$/.exec(line);
+    if (!match)
+        return null;
+    const level = match[4].toLowerCase();
+    const type = level === 'error' ? 'E' : level === 'fault' ? 'F' : level === 'notice' ? 'Df' : level === 'debug' ? 'Db' : 'I';
+    return { time: match[1], process: match[2], pid: Number(match[3]), type, message: match[5] };
+}
+export function formatSyslog(line) {
+    return `${line.type}/${line.process}: ${line.message}`;
+}
+/**
+ * Files the app's error and fault log lines, and crash reports, under the step that was
+ * running (the iOS counterpart of `LogcatCollector`).
+ */
+export class SyslogCollector {
+    processName;
+    redact;
+    steps = new Map();
+    current = null;
+    pending = [];
+    constructor(processName, redact = (t) => t) {
+        this.processName = processName;
+        this.redact = redact;
+    }
+    begin(index) {
+        this.current = index;
+    }
+    get step() {
+        return this.current;
+    }
+    drain() {
+        const out = this.pending;
+        this.pending = [];
+        return out.slice(-SYSLOG_LIMITS.drain);
+    }
+    for(index) {
+        const debug = this.steps.get(index);
+        if (!debug || (!debug.device_log?.length && !debug.crashes?.length))
+            return undefined;
+        return debug;
+    }
+    accept(line) {
+        if (!line || line.process !== this.processName)
+            return;
+        if (line.type !== 'E' && line.type !== 'F')
+            return;
+        const text = this.redact(formatSyslog(line)).slice(0, SYSLOG_LIMITS.lineChars);
+        this.pending.push(text);
+        if (this.pending.length > SYSLOG_LIMITS.drain * 2)
+            this.pending.splice(0, this.pending.length - SYSLOG_LIMITS.drain);
+        if (this.current === null)
+            return;
+        const debug = this.entry(this.current);
+        const list = (debug.device_log ??= []);
+        if (list.length < SYSLOG_LIMITS.linesPerStep)
+            list.push(text);
+        else {
+            debug.dropped ??= {};
+            debug.dropped.device_log = (debug.dropped.device_log ?? 0) + 1;
+        }
+    }
+    addCrash(step, report) {
+        const redacted = this.redact(report).slice(0, SYSLOG_LIMITS.crashChars);
+        this.pending.push(redacted.split('\n').slice(0, 3).join(' | ').slice(0, SYSLOG_LIMITS.lineChars));
+        if (step === null)
+            return;
+        const debug = this.entry(step);
+        const list = (debug.crashes ??= []);
+        if (list.length < SYSLOG_LIMITS.crashesPerStep)
+            list.push(redacted);
+        else {
+            debug.dropped ??= {};
+            debug.dropped.crashes = (debug.dropped.crashes ?? 0) + 1;
+        }
+    }
+    entry(index) {
+        let debug = this.steps.get(index);
+        if (!debug) {
+            debug = {};
+            this.steps.set(index, debug);
+        }
+        return debug;
+    }
+}
+/** Where macOS writes crash reports of simulator apps (`<Process>-<date>.ips`). */
+export function diagnosticReportsDir(home = homedir()) {
+    return join(home, 'Library', 'Logs', 'DiagnosticReports');
+}
+/**
+ * Crash reports of one process newer than a point in time; each is returned once. Simulator app
+ * crashes land in the host's DiagnosticReports folder.
+ */
+export class CrashReportWatcher {
+    processName;
+    since;
+    dir;
+    seen = new Set();
+    constructor(processName, since, dir = diagnosticReportsDir()) {
+        this.processName = processName;
+        this.since = since;
+        this.dir = dir;
+    }
+    collect() {
+        let names;
+        try {
+            names = readdirSync(this.dir);
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const name of names) {
+            if (!name.startsWith(`${this.processName}-`) || !/\.(ips|crash)$/.test(name) || this.seen.has(name))
+                continue;
+            const path = join(this.dir, name);
+            try {
+                if (statSync(path).mtimeMs < this.since)
+                    continue;
+                this.seen.add(name);
+                out.push(readFileSync(path, 'utf8').slice(0, SYSLOG_LIMITS.crashChars));
+            }
+            catch {
+                // unreadable report: skip
+            }
+        }
+        return out;
+    }
+}
+/** Follows a simulator's unified log for the app's process with `simctl spawn … log stream`. */
+export class SimulatorLogSink {
+    udid;
+    processName;
+    xcrun;
+    child = null;
+    collector;
+    crashes;
+    constructor(udid, processName, redact, xcrun = 'xcrun') {
+        this.udid = udid;
+        this.processName = processName;
+        this.xcrun = xcrun;
+        if (!PROCESS_NAME_RE.test(processName))
+            throw new Error(`'${processName}' is not a process name`);
+        this.collector = new SyslogCollector(processName, redact);
+        this.crashes = new CrashReportWatcher(processName, Date.now());
+    }
+    start() {
+        if (this.child)
+            return;
+        const child = spawn(this.xcrun, simctlLogStreamArgv(this.udid, this.processName), { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+        child.on('error', () => undefined);
+        this.child = child;
+        if (child.stdout) {
+            createInterface({ input: child.stdout }).on('line', (line) => this.collector.accept(parseCompactLogLine(line)));
+        }
+    }
+    /** Files crash reports written since the last check under the current step. */
+    checkCrashes() {
+        for (const report of this.crashes.collect())
+            this.collector.addCrash(this.collector.step, report);
+    }
+    stop() {
+        this.child?.kill();
+        this.child = null;
+    }
+}

package/dist/src/devices/ios/wda.js

@@ -0,0 +1,108 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { resolvePackage } from '../../appium/drivers.js';
+import { runTool } from '../android/adb.js';
+/**
+ * WebDriverAgent (the XCTest runner Appium's XCUITest driver talks to), prebuilt once per
+ * driver version and Xcode version into `~/.leera-qa-runner/wda/<driver>-<xcode>` so jobs use
+ * `usePrebuiltWDA` + `derivedDataPath` instead of compiling it on every session (contracts §I).
+ */
+export const XCUITEST_PACKAGE = 'appium-xcuitest-driver';
+/** Parses `xcodebuild -version` ("Xcode 26.6\nBuild version 17F113"). */
+export function parseXcodebuildVersion(output) {
+    const version = /^Xcode\s+(\d+(?:\.\d+)*)/m.exec(output);
+    if (!version)
+        return null;
+    const build = /^Build version\s+(\S+)/m.exec(output);
+    return { version: version[1], build: build?.[1] ?? null };
+}
+export async function xcodeInfo() {
+    try {
+        const { stdout } = await runTool('xcodebuild', ['-version'], { timeoutMs: 30_000 });
+        return parseXcodebuildVersion(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/** `xcode-select -p` pointing at the Command Line Tools instead of Xcode.app cannot build or run WDA. */
+export function isCommandLineToolsOnly(developerDir) {
+    return /CommandLineTools\/?$/.test(developerDir.trim());
+}
+export async function developerDir() {
+    try {
+        return (await runTool('xcode-select', ['-p'], { timeoutMs: 10_000 })).stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function safeSegment(value) {
+    return value.replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 40) || 'unknown';
+}
+/** `~/.leera-qa-runner/wda/<xcuitest-driver-version>-<xcode-version>`. */
+export function wdaCacheDir(paths, driverVersion, xcodeVersion) {
+    return join(paths.root, 'wda', `${safeSegment(driverVersion)}-${safeSegment(xcodeVersion)}`);
+}
+/** Where real-device WDA builds go (signed with the team's identity; built by the driver on first use). */
+export function wdaRealDeviceDir(simulatorDir) {
+    return `${simulatorDir}-real`;
+}
+/** The bundled XCUITest driver and the WebDriverAgent project it ships with, or null when not installed. */
+export function bundledWda(resolve) {
+    const driver = resolvePackage(XCUITEST_PACKAGE, resolve);
+    if (!driver)
+        return null;
+    try {
+        const require = createRequire(join(driver.dir, 'package.json'));
+        const agent = dirname(require.resolve('appium-webdriveragent/package.json'));
+        const project = join(agent, 'WebDriverAgent.xcodeproj');
+        return existsSync(project) ? { driverVersion: driver.version, project } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The fixed argv that builds WebDriverAgent for any iOS simulator, unsigned, into `derivedDataPath`. */
+export function wdaSimulatorBuildArgv(project, derivedDataPath) {
+    if (!project.endsWith('WebDriverAgent.xcodeproj'))
+        throw new Error(`'${project}' is not the WebDriverAgent project`);
+    return [
+        'build-for-testing',
+        '-project',
+        project,
+        '-scheme',
+        'WebDriverAgentRunner',
+        '-destination',
+        'generic/platform=iOS Simulator',
+        '-derivedDataPath',
+        derivedDataPath,
+        'CODE_SIGNING_ALLOWED=NO',
+        'GCC_TREAT_WARNINGS_AS_ERRORS=0',
+        'COMPILER_INDEX_STORE_ENABLE=NO',
+    ];
+}
+/** True when `derivedDataPath` holds a simulator WDA build (`*.xctestrun` + the runner app). */
+export function isWdaSimulatorBuilt(derivedDataPath, list = safeList, exists = existsSync) {
+    const products = join(derivedDataPath, 'Build', 'Products');
+    const xctestrun = list(products).some((name) => name.endsWith('.xctestrun') && name.includes('iphonesimulator'));
+    return xctestrun && exists(join(products, 'Debug-iphonesimulator', 'WebDriverAgentRunner-Runner.app'));
+}
+function safeList(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** Where this runner's simulator WDA build is (or would be) and whether it exists. */
+export async function wdaStatus(paths) {
+    const sources = bundledWda();
+    const xcode = await xcodeInfo();
+    if (!sources || !xcode)
+        return { sources, xcode, dir: null, built: false };
+    const dir = wdaCacheDir(paths, sources.driverVersion, xcode.version);
+    return { sources, xcode, dir, built: isWdaSimulatorBuilt(dir) };
+}