@leera.io/qa-runner 1.0.0

package/dist/src/devices/tauri.js

@@ -0,0 +1,189 @@
+import { accessSync, constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readJsonFile } from '../home.js';
+import { displayNeed, findOnPath, NO_DISPLAY, XVFB_DISPLAY } from './desktop.js';
+/**
+ * Where Tauri jobs run (contracts §L): `tauri-driver` 2.0.6 with the platform's native
+ * WebDriver (WebKitWebDriver on Linux, msedgedriver on Windows), or on macOS an app build that
+ * embeds the WebDriver plugin (`tauri.macos_plugin`). There is no tauri-driver backend on macOS.
+ */
+export const TAURI_DRIVER_VERSION = '2.0.6';
+export const TAURI_DRIVER_INSTALL = `cargo install tauri-driver --version ${TAURI_DRIVER_VERSION} --locked`;
+export const WEBKIT_DRIVER_INSTALL = 'sudo apt install webkit2gtk-driver';
+export const MSEDGEDRIVER_URL = 'https://developer.microsoft.com/microsoft-edge/tools/webdriver/';
+/** The exact message a macOS job or session is blocked with when the app exposes no plugin port. */
+export const MACOS_PLUGIN_BLOCKED = 'Tauri on macOS needs a build with the embedded WebDriver plugin';
+function pick(...values) {
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return null;
+}
+function truthy(value) {
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    return ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase());
+}
+/** Environment wins over the config file. */
+export function tauriSettings(env, file) {
+    return {
+        driverPath: pick(env.RUNNER_TAURI_DRIVER, file?.tauri?.driver_path),
+        nativeDriverPath: pick(env.RUNNER_TAURI_NATIVE_DRIVER, file?.tauri?.native_driver_path),
+        macosPlugin: truthy(env.RUNNER_TAURI_MACOS_PLUGIN) ?? file?.tauri?.macos_plugin === true,
+    };
+}
+/** Reads the settings from the runner home's config file (unreadable config = defaults). */
+export function loadTauriSettings(env, paths) {
+    let file = null;
+    try {
+        file = readJsonFile(paths.config);
+    }
+    catch {
+        file = null;
+    }
+    return tauriSettings(env, file);
+}
+function lookup(options) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const exists = options.exists;
+    const find = (name) => findOnPath(name, env, exists);
+    return { platform, env, exists, find, home: options.home ?? homedir() };
+}
+/** `tauri-driver`: configured path, then `~/.cargo/bin`, then PATH. */
+export function findTauriDriver(settings, options = {}) {
+    const { platform, find, exists, home } = lookup(options);
+    const name = platform === 'win32' ? 'tauri-driver.exe' : 'tauri-driver';
+    if (settings.driverPath)
+        return settings.driverPath;
+    const cargo = join(home, '.cargo', 'bin', name);
+    if ((exists ?? defaultExists)(cargo))
+        return cargo;
+    return find(name);
+}
+/** The native WebDriver tauri-driver talks to: configured path, then PATH. Null on macOS. */
+export function findNativeDriver(settings, options = {}) {
+    const { platform, find } = lookup(options);
+    if (settings.nativeDriverPath)
+        return settings.nativeDriverPath;
+    if (platform === 'win32')
+        return find('msedgedriver.exe');
+    if (platform === 'linux')
+        return find('WebKitWebDriver');
+    return null;
+}
+function defaultExists(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Which backend this host runs Tauri jobs with, or why it cannot. */
+export function tauriBackend(settings, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform === 'darwin') {
+        if (settings.macosPlugin)
+            return { kind: 'macos-plugin' };
+        return {
+            kind: 'unavailable',
+            reasons: [
+                'macOS has no tauri-driver; Tauri jobs run here only with builds that embed the WebDriver plugin (set tauri.macos_plugin true)',
+            ],
+        };
+    }
+    if (platform !== 'linux' && platform !== 'win32')
+        return { kind: 'unavailable', reasons: [`Tauri jobs do not run on ${platform}`] };
+    const reasons = [];
+    const driver = findTauriDriver(settings, options);
+    if (!driver)
+        reasons.push(`tauri-driver was not found (install it with \`${TAURI_DRIVER_INSTALL}\` or set tauri.driver_path)`);
+    const nativeDriver = findNativeDriver(settings, options);
+    if (!nativeDriver) {
+        reasons.push(platform === 'linux'
+            ? `WebKitWebDriver was not found (install it with \`${WEBKIT_DRIVER_INSTALL}\`)`
+            : 'msedgedriver.exe was not found (download the version matching WebView2 and set tauri.native_driver_path)');
+    }
+    if (!driver || !nativeDriver)
+        return { kind: 'unavailable', reasons };
+    return { kind: 'driver', driver, nativeDriver, os: platform === 'linux' ? 'linux' : 'windows' };
+}
+/**
+ * tauri-driver's argv for one job: its own port, the native driver's port and, on Windows (or
+ * when configured), the native driver's path.
+ */
+export function tauriDriverArgv(options) {
+    for (const port of [options.port, options.nativePort]) {
+        if (!Number.isInteger(port) || port <= 0 || port > 65_535)
+            throw new Error(`invalid port ${port}`);
+    }
+    const argv = ['--port', String(options.port), '--native-port', String(options.nativePort)];
+    if (options.nativeDriver && (options.os === 'windows' || options.configuredNative))
+        argv.push('--native-driver', options.nativeDriver);
+    return argv;
+}
+/** W3C capabilities for a tauri-driver session: tauri-driver maps `tauri:options` to the native driver's. */
+export function tauriCapabilities(application, args) {
+    return { 'tauri:options': { application, args } };
+}
+/** `doctor` checks for Tauri on this host. */
+export function tauriChecks(settings, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const checks = [];
+    if (platform === 'darwin') {
+        checks.push(settings.macosPlugin
+            ? {
+                id: 'tauri.macos_plugin',
+                title: 'Tauri: macOS WebDriver plugin',
+                status: 'ok',
+                detail: 'enabled: builds must embed the WebDriver plugin; plain builds are blocked',
+            }
+            : {
+                id: 'tauri.macos_plugin',
+                title: 'Tauri: macOS WebDriver plugin',
+                status: 'fail',
+                detail: 'macOS has no tauri-driver; this Mac runs Tauri jobs only for builds that embed the WebDriver plugin',
+                fix: 'leera-qa-runner config set tauri.macos_plugin true (only when your builds embed the plugin)',
+            });
+        return checks;
+    }
+    if (platform !== 'linux' && platform !== 'win32') {
+        checks.push({ id: 'tauri.host', title: 'Tauri', status: 'fail', detail: `Tauri jobs do not run on ${platform}` });
+        return checks;
+    }
+    const driver = findTauriDriver(settings, options);
+    checks.push(driver
+        ? { id: 'tauri.driver', title: 'Tauri: tauri-driver', status: 'ok', detail: driver }
+        : { id: 'tauri.driver', title: 'Tauri: tauri-driver', status: 'fail', detail: 'tauri-driver was not found', fix: TAURI_DRIVER_INSTALL });
+    const native = findNativeDriver(settings, options);
+    if (platform === 'linux') {
+        checks.push(native
+            ? { id: 'tauri.native_driver', title: 'Tauri: WebKitWebDriver', status: 'ok', detail: native }
+            : { id: 'tauri.native_driver', title: 'Tauri: WebKitWebDriver', status: 'fail', detail: 'WebKitWebDriver was not found', fix: WEBKIT_DRIVER_INSTALL });
+        const need = displayNeed(platform, env, (name) => findOnPath(name, env, options.exists));
+        if (need.kind === 'existing')
+            checks.push({ id: 'tauri.display', title: 'Tauri: display', status: 'ok', detail: `DISPLAY ${need.display}` });
+        else if (need.kind === 'xvfb')
+            checks.push({ id: 'tauri.display', title: 'Tauri: display', status: 'ok', detail: `no DISPLAY; jobs start ${need.xvfb} ${XVFB_DISPLAY}` });
+        else if (need.kind === 'missing')
+            checks.push({ id: 'tauri.display', title: 'Tauri: display', status: 'warn', detail: NO_DISPLAY, fix: 'sudo apt-get install xvfb' });
+    }
+    else {
+        checks.push(native
+            ? { id: 'tauri.native_driver', title: 'Tauri: msedgedriver', status: 'ok', detail: native }
+            : {
+                id: 'tauri.native_driver',
+                title: 'Tauri: msedgedriver',
+                status: 'fail',
+                detail: 'msedgedriver.exe was not found',
+                fix: `download the msedgedriver matching your WebView2 Runtime from ${MSEDGEDRIVER_URL}, then leera-qa-runner config set tauri.native_driver_path C:\\path\\to\\msedgedriver.exe`,
+            });
+    }
+    return checks;
+}

package/dist/src/devices/types.js

@@ -0,0 +1,6 @@
+/** Every platform the protocol knows; this runner version drives `web` only. */
+export const PLATFORMS = ['web', 'android', 'ios', 'electron', 'tauri', 'windows', 'macos', 'linux'];
+export const BROWSER_DEVICE_ID = 'browser';
+export function isPlatform(value) {
+    return typeof value === 'string' && PLATFORMS.includes(value);
+}

package/dist/src/devices/windows.js

@@ -0,0 +1,362 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream, existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { join, win32 } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { bundledDrivers } from '../appium/drivers.js';
+import { appiumHomeDir, seedAppiumHome } from '../appium/home.js';
+import { bundledAppium, freePort } from '../appium/server.js';
+import { writeResponseBody } from '../download.js';
+import { ExitCode, messageOf } from '../errors.js';
+import { ensureHome, readJsonFile } from '../home.js';
+import { runTool } from './android/adb.js';
+import { findOnPath } from './desktop.js';
+import { findFfmpeg } from './screen-record.js';
+/**
+ * Native Windows apps (contracts §M): Appium's Windows driver in front of WinAppDriver 1.2.1,
+ * which the runner starts itself on a free loopback port. WinAppDriver needs Developer Mode and
+ * an interactive desktop session (not a service session without a desktop).
+ */
+export const WINDOWS_NEEDS_WINDOWS = 'Windows app jobs need a Windows runner';
+export const WINAPPDRIVER_VERSION = '1.2.1';
+/** The official release asset (github.com/microsoft/WinAppDriver, tag v1.2.1). */
+export const WINAPPDRIVER_MSI_URL = 'https://github.com/microsoft/WinAppDriver/releases/download/v1.2.1/WindowsApplicationDriver_1.2.1.msi';
+export const WINAPPDRIVER_MSI_NAME = 'WindowsApplicationDriver_1.2.1.msi';
+export const WINAPPDRIVER_MSI_SHA256 = 'a76a8f4e44b29bad331acf6b6c248fcc65324f502f28826ad2acd5f3c80857fe';
+export const WINAPPDRIVER_MSI_SIZE = 3_932_160;
+export const DEVELOPER_MODE_STEPS = 'Settings → System → For developers (Windows 10: Update & Security → For developers) → turn on Developer Mode';
+export function windowsSettings(env, file) {
+    return { winAppDriverPath: env.RUNNER_WINAPPDRIVER?.trim() || file?.windows?.winappdriver_path?.trim() || null };
+}
+export function loadWindowsSettings(env, paths) {
+    try {
+        return windowsSettings(env, readJsonFile(paths.config));
+    }
+    catch {
+        return windowsSettings(env, null);
+    }
+}
+/** Where WinAppDriver.exe may be: the configured path, then the msi's install folders. */
+export function winAppDriverCandidates(settings, env = process.env) {
+    const out = [];
+    if (settings.winAppDriverPath)
+        out.push(settings.winAppDriverPath);
+    if (env.APPIUM_WAD_PATH?.trim())
+        out.push(env.APPIUM_WAD_PATH.trim());
+    for (const root of [env['ProgramFiles(x86)'], env.ProgramFiles, `${env.SystemDrive || 'C:'}\\Program Files (x86)`]) {
+        if (root?.trim())
+            out.push(win32.join(root.trim(), 'Windows Application Driver', 'WinAppDriver.exe'));
+    }
+    return [...new Set(out)];
+}
+export function findWinAppDriver(settings, env = process.env, exists = existsSync) {
+    return winAppDriverCandidates(settings, env).find((path) => exists(path)) ?? null;
+}
+/** WinAppDriver's fixed argv: listen on loopback only, on `port`. */
+export function winAppDriverArgv(port) {
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535)
+        throw new Error(`invalid port ${port}`);
+    return ['127.0.0.1', String(port)];
+}
+/** `reg query` for the Developer Mode switch (read only). */
+export function developerModeArgv() {
+    return ['query', 'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\AppModelUnlock', '/v', 'AllowDevelopmentWithoutDevLicense'];
+}
+export function parseDeveloperMode(output) {
+    return /AllowDevelopmentWithoutDevLicense\s+REG_DWORD\s+0x0*1\b/i.test(output);
+}
+export async function developerModeOn(run = async (file, args) => (await runTool(file, args, { timeoutMs: 10_000 })).stdout) {
+    try {
+        return parseDeveloperMode(await run('reg', developerModeArgv()));
+    }
+    catch {
+        return false;
+    }
+}
+/** `msiexec /i <msi> /qn /norestart` (only for `setup windows --install`, from an elevated shell). */
+export function msiexecArgv(msi) {
+    if (!msi.toLowerCase().endsWith('.msi'))
+        throw new Error(`'${msi}' is not an .msi file`);
+    return ['/i', msi, '/qn', '/norestart'];
+}
+/** Quotes one argument for a Windows command line (CommandLineToArgvW rules). */
+export function quoteWindowsArg(arg) {
+    if (arg !== '' && !/[\s"]/.test(arg))
+        return arg;
+    let out = '"';
+    let slashes = 0;
+    for (const char of arg) {
+        if (char === '\\') {
+            slashes += 1;
+            continue;
+        }
+        if (char === '"') {
+            out += '\\'.repeat(slashes * 2 + 1);
+        }
+        else {
+            out += '\\'.repeat(slashes);
+        }
+        slashes = 0;
+        out += char;
+    }
+    return `${out}${'\\'.repeat(slashes * 2)}"`;
+}
+/** W3C capabilities for an Appium Windows driver session against the runner's WinAppDriver. */
+export function windowsCapabilities(options) {
+    if (!options.app && !options.topLevelWindow)
+        throw new Error('a Windows session needs an app or a window');
+    if (options.topLevelWindow && !/^0x[0-9a-f]+$/i.test(options.topLevelWindow))
+        throw new Error(`invalid window handle '${options.topLevelWindow}'`);
+    return {
+        platformName: 'Windows',
+        'appium:automationName': 'Windows',
+        ...(options.topLevelWindow ? { 'appium:appTopLevelWindow': options.topLevelWindow } : { 'appium:app': options.app }),
+        ...(options.args && options.args.length > 0 ? { 'appium:appArguments': options.args.map(quoteWindowsArg).join(' ') } : {}),
+        ...(options.workingDir ? { 'appium:appWorkingDir': options.workingDir } : {}),
+        'appium:wadUrl': options.wadUrl,
+        'appium:newCommandTimeout': options.newCommandTimeoutSecs ?? 300,
+        'appium:createSessionTimeout': 60_000,
+        'ms:waitForAppLaunch': 25,
+    };
+}
+/** `Contoso.App_8wekyb3d8bbwe!App` */
+export const AUMID_RE = /^[A-Za-z0-9._-]+_[a-z0-9]{13}![A-Za-z0-9._-]+$/;
+/** What `install: installed` launches: an AUMID as is, an absolute exe, or an exe name found on PATH. */
+export function installedWindowsApp(appId, env = process.env, exists) {
+    const id = appId.trim();
+    if (AUMID_RE.test(id))
+        return id;
+    if (win32.isAbsolute(id) && id.toLowerCase().endsWith('.exe'))
+        return id;
+    if (/^[^\\/:*?"<>|]+\.exe$/i.test(id)) {
+        const found = findOnPath(id, { ...env, PATH: env.PATH ?? env.Path ?? '' }, exists);
+        if (found)
+            return found;
+        throw new Error(`${id} was not found on PATH on this runner`);
+    }
+    throw new Error(`'${id}' is neither an AppUserModelID (Publisher.App_xxxxxxxxxxxxx!App) nor an .exe name`);
+}
+/**
+ * The runner's own WinAppDriver: started on a free loopback port the first time a job needs it
+ * and reused while it answers `/status`.
+ */
+/**
+ * WinAppDriver prints "Press ENTER to exit." and exits (code 0) as soon as a line or end of input
+ * arrives on stdin, so an ignored stdin (NUL) stops it at once: stdin stays an open pipe.
+ */
+export const WINAPPDRIVER_STDIO = ['pipe', 'ignore', 'ignore'];
+export class WinAppDriverProcess {
+    executable;
+    spawnImpl;
+    fetchImpl;
+    child = null;
+    port = 0;
+    exited = null;
+    constructor(executable, spawnImpl = spawn, fetchImpl = fetch) {
+        this.executable = executable;
+        this.spawnImpl = spawnImpl;
+        this.fetchImpl = fetchImpl;
+    }
+    get url() {
+        return `http://127.0.0.1:${this.port}`;
+    }
+    async healthy() {
+        if (!this.port)
+            return false;
+        try {
+            const response = await this.fetchImpl(`${this.url}/status`, { signal: AbortSignal.timeout(2_000) });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    async ensure(timeoutMs = 20_000) {
+        if (this.child && !this.exited && (await this.healthy()))
+            return this.url;
+        this.stop();
+        this.port = await freePort();
+        this.exited = null;
+        const child = this.spawnImpl(this.executable, winAppDriverArgv(this.port), { stdio: WINAPPDRIVER_STDIO, windowsHide: true });
+        this.child = child;
+        // The open stdin pipe is what keeps WinAppDriver running; nothing is ever written to it.
+        child.stdin?.on('error', () => undefined);
+        // A helper must not keep the runner alive: with the child and its pipe referenced, a process
+        // that finished its work (a CI run, a test) never exited. The exit hook below still ends it.
+        child.unref();
+        child.stdin?.unref?.();
+        // Never leave WinAppDriver behind when the runner exits.
+        const killOnExit = () => child.kill();
+        process.once('exit', killOnExit);
+        child.once('exit', (code) => {
+            this.exited = `WinAppDriver exited (code ${code})`;
+            process.removeListener('exit', killOnExit);
+        });
+        child.once('error', (error) => {
+            this.exited = `WinAppDriver could not start: ${error.message}`;
+        });
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            if (this.exited)
+                throw new Error(this.exited);
+            if (await this.healthy())
+                return this.url;
+            if (Date.now() > deadline) {
+                this.stop();
+                throw new Error(`WinAppDriver did not answer on port ${this.port} within ${Math.round(timeoutMs / 1000)} s (is Developer Mode on?)`);
+            }
+            await sleep(250);
+        }
+    }
+    stop() {
+        const child = this.child;
+        this.child = null;
+        if (child && !this.exited)
+            child.kill();
+    }
+}
+let processWad = null;
+/** One WinAppDriver per runner process. */
+export function sharedWinAppDriver(executable) {
+    processWad ??= new WinAppDriverProcess(executable);
+    return processWad;
+}
+export async function windowsReadiness(settings, platform = process.platform, env = process.env) {
+    if (platform !== 'win32')
+        return { ok: false, reasons: [WINDOWS_NEEDS_WINDOWS], winAppDriver: null };
+    const reasons = [];
+    if (!bundledAppium())
+        reasons.push('Appium is not installed with this runner (optional dependencies were omitted)');
+    else if (!bundledDrivers('win32').some((driver) => driver.platforms.includes('windows')))
+        reasons.push('the Appium Windows driver is not installed with this runner');
+    const winAppDriver = findWinAppDriver(settings, env);
+    if (!winAppDriver)
+        reasons.push(`WinAppDriver ${WINAPPDRIVER_VERSION} is not installed (run \`leera-qa-runner setup windows\`)`);
+    if (!(await developerModeOn()))
+        reasons.push(`Developer Mode is off (${DEVELOPER_MODE_STEPS})`);
+    return { ok: reasons.length === 0, reasons, winAppDriver };
+}
+/** `doctor` checks for Windows apps. */
+export async function windowsChecks(env, paths, platform = process.platform) {
+    if (platform !== 'win32')
+        return [{ id: 'windows.host', title: 'Windows apps: host', status: 'warn', detail: WINDOWS_NEEDS_WINDOWS }];
+    const settings = loadWindowsSettings(env, paths);
+    const checks = [];
+    const appium = bundledAppium();
+    const driver = bundledDrivers('win32').find((d) => d.platforms.includes('windows'));
+    checks.push(appium && driver
+        ? { id: 'windows.appium', title: 'Windows apps: Appium', status: 'ok', detail: `Appium ${appium.version}, windows ${driver.version}` }
+        : { id: 'windows.appium', title: 'Windows apps: Appium', status: 'fail', detail: 'Appium or its Windows driver is not installed with this runner', fix: 'Reinstall the runner' });
+    const wad = findWinAppDriver(settings, env);
+    checks.push(wad
+        ? { id: 'windows.winappdriver', title: 'Windows apps: WinAppDriver', status: 'ok', detail: wad }
+        : { id: 'windows.winappdriver', title: 'Windows apps: WinAppDriver', status: 'fail', detail: `WinAppDriver ${WINAPPDRIVER_VERSION} is not installed`, fix: 'leera-qa-runner setup windows' });
+    checks.push((await developerModeOn())
+        ? { id: 'windows.developer_mode', title: 'Windows apps: Developer Mode', status: 'ok', detail: 'on' }
+        : { id: 'windows.developer_mode', title: 'Windows apps: Developer Mode', status: 'fail', detail: 'off (WinAppDriver needs it)', fix: DEVELOPER_MODE_STEPS });
+    const ffmpeg = findFfmpeg(env, platform);
+    checks.push(ffmpeg
+        ? { id: 'windows.video', title: 'Windows apps: video', status: 'ok', detail: `ffmpeg ${ffmpeg}` }
+        : { id: 'windows.video', title: 'Windows apps: video', status: 'warn', detail: 'ffmpeg is not installed; jobs record no video', fix: 'winget install ffmpeg' });
+    return checks;
+}
+export async function sha256File(path) {
+    const hash = createHash('sha256');
+    await pipeline(createReadStream(path), hash);
+    return hash.digest('hex');
+}
+/** Downloads the pinned msi into `dir` (kept when already there with the right digest). */
+export async function downloadWinAppDriverMsi(dir, fetchImpl = fetch) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const target = join(dir, WINAPPDRIVER_MSI_NAME);
+    if (existsSync(target) && (await sha256File(target)) === WINAPPDRIVER_MSI_SHA256)
+        return target;
+    const temp = `${target}.${process.pid}.part`;
+    try {
+        const response = await fetchImpl(WINAPPDRIVER_MSI_URL, { redirect: 'follow', signal: AbortSignal.timeout(10 * 60_000) });
+        if (!response.ok || !response.body)
+            throw new Error(`the download failed with HTTP ${response.status}`);
+        await writeResponseBody(response.body, temp);
+        const digest = await sha256File(temp);
+        if (digest !== WINAPPDRIVER_MSI_SHA256)
+            throw new Error(`the downloaded msi's sha256 ${digest} is not the pinned ${WINAPPDRIVER_MSI_SHA256}`);
+        renameSync(temp, target);
+        return target;
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+/**
+ * `setup windows`: seeds Appium's home with the bundled Windows driver, downloads the pinned
+ * WinAppDriver msi into the runner home and prints the install and Developer Mode steps.
+ * `--install` runs `msiexec /i … /qn` (needs an elevated shell); nothing else is changed.
+ */
+export async function setupWindows(io, paths, options = {}, deps = {}) {
+    if (io.platform !== 'win32') {
+        io.stderr(`${WINDOWS_NEEDS_WINDOWS}; this computer cannot run them.`);
+        return ExitCode.environmentNotReady;
+    }
+    ensureHome(paths);
+    let ok = true;
+    const appium = bundledAppium();
+    const drivers = bundledDrivers('win32');
+    if (!appium || !drivers.some((d) => d.platforms.includes('windows'))) {
+        io.stderr('Appium and its Windows driver are not installed with this runner. Reinstall 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)' : ''}`);
+    const settings = loadWindowsSettings(io.env, paths);
+    let wad = findWinAppDriver(settings, io.env);
+    if (wad) {
+        io.stdout(`WinAppDriver: ${wad}`);
+    }
+    else {
+        let msi = null;
+        try {
+            msi = await downloadWinAppDriverMsi(join(paths.root, 'winappdriver'), deps.fetchImpl);
+            io.stdout(`Downloaded WinAppDriver ${WINAPPDRIVER_VERSION} (sha256 ${WINAPPDRIVER_MSI_SHA256}) to ${msi}`);
+        }
+        catch (error) {
+            ok = false;
+            io.stderr(`WinAppDriver could not be downloaded: ${messageOf(error)}. Download it from ${WINAPPDRIVER_MSI_URL} yourself.`);
+        }
+        if (msi && options.install) {
+            const run = deps.runMsiexec ??
+                ((argv) => new Promise((resolve) => {
+                    const child = spawn('msiexec', argv, { stdio: 'inherit', windowsHide: true });
+                    child.on('error', () => resolve(1));
+                    child.on('close', (code) => resolve(code ?? 1));
+                }));
+            io.stdout('Installing WinAppDriver (msiexec, needs an elevated shell) ...');
+            const code = await run(msiexecArgv(msi));
+            wad = findWinAppDriver(settings, io.env);
+            if (code !== 0 || !wad) {
+                ok = false;
+                io.stderr(`msiexec exited with ${code}; run this shell as Administrator, or install ${msi} by double-clicking it.`);
+            }
+            else {
+                io.stdout(`WinAppDriver installed: ${wad}`);
+            }
+        }
+        else if (msi) {
+            ok = false;
+            io.stdout(`Install it: double-click ${msi}, or from an elevated shell run\n  msiexec ${msiexecArgv(msi).join(' ')}\n(or run \`leera-qa-runner setup windows --install\` as Administrator)`);
+        }
+    }
+    if (!(await developerModeOn())) {
+        ok = false;
+        io.stdout(`Developer Mode is off. WinAppDriver needs it: ${DEVELOPER_MODE_STEPS}.`);
+    }
+    else {
+        io.stdout('Developer Mode: on');
+    }
+    io.stdout('Windows app jobs need an interactive desktop: run the runner in a logged-in session (not as a Windows service without a desktop) and keep the screen unlocked.');
+    if (!findFfmpeg(io.env, io.platform))
+        io.stdout('ffmpeg is not installed: Windows app jobs record no video.');
+    io.stdout(ok ? 'Windows apps are set up. Check with `leera-qa-runner doctor --platform windows`.' : 'Windows setup is incomplete; see the messages above.');
+    return ok ? ExitCode.ok : ExitCode.environmentNotReady;
+}