@leera.io/qa-runner 1.0.0

package/dist/src/doctor.js

@@ -0,0 +1,394 @@
+import { accessSync, chmodSync, constants, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { bundledDrivers } from './appium/drivers.js';
+import { bundledAppium } from './appium/server.js';
+import { Adb, resolveAndroidSdk, runTool } from './devices/android/adb.js';
+import { iosChecks } from './devices/ios/setup.js';
+import { electronChecks } from './devices/desktop.js';
+import { electronSupported } from './drivers/electron-playwright.js';
+import { loadTauriSettings, tauriChecks } from './devices/tauri.js';
+import { macosChecks } from './devices/macos.js';
+import { windowsChecks } from './devices/windows.js';
+import { detect, hostInfo } from './capabilities.js';
+import { RunnerClient } from './client.js';
+import { loadFileConfig, TOKEN_PREFIX } from './config.js';
+import { messageOf } from './errors.js';
+import { ensureHome, isTooOpen, readJsonFile } from './home.js';
+import { compareVersions, playwrightVersion, RUNNER_VERSION } from './version.js';
+export const MIN_NODE = '22.12.0';
+export async function runDoctor(options) {
+    const { env, paths, fix = false } = options;
+    const checks = [];
+    const host = hostInfo();
+    checks.push(compareVersions(host.node, MIN_NODE) >= 0
+        ? { id: 'node', title: 'Node.js', status: 'ok', detail: `Node.js ${host.node}` }
+        : {
+            id: 'node',
+            title: 'Node.js',
+            status: 'fail',
+            detail: `Node.js ${host.node} is too old; ${MIN_NODE} or newer is needed`,
+            fix: 'Install Node.js 22.12 or newer, or use the installer, which bundles Node.js',
+        });
+    // Home directory
+    const homeCheck = { id: 'home', title: 'Runner home', status: 'ok', detail: paths.root };
+    try {
+        if (!existsSync(paths.root)) {
+            if (fix) {
+                ensureHome(paths);
+                homeCheck.fixed = true;
+                homeCheck.detail = `${paths.root} (created)`;
+            }
+            else {
+                homeCheck.status = 'warn';
+                homeCheck.detail = `${paths.root} does not exist yet`;
+                homeCheck.fix = 'leera-qa-runner connect --url <server>';
+            }
+        }
+        else {
+            accessSync(paths.root, constants.W_OK);
+            if (isTooOpen(paths.root)) {
+                if (fix) {
+                    chmodSync(paths.root, 0o700);
+                    homeCheck.fixed = true;
+                }
+                else {
+                    homeCheck.status = 'warn';
+                    homeCheck.detail = `${paths.root} is readable by other users`;
+                    homeCheck.fix = 'leera-qa-runner doctor --fix';
+                }
+            }
+        }
+    }
+    catch (error) {
+        homeCheck.status = 'fail';
+        homeCheck.detail = `${paths.root} is not writable: ${messageOf(error)}`;
+    }
+    checks.push(homeCheck);
+    // Configuration and token
+    let fileUrl;
+    let fileToken = null;
+    try {
+        const tokenWasOpen = existsSync(paths.token) && isTooOpen(paths.token);
+        if (tokenWasOpen && !fix) {
+            checks.push({
+                id: 'token_permissions',
+                title: 'Token file permissions',
+                status: 'warn',
+                detail: `${paths.token} is readable by other users; it is narrowed to 0600 on the next start`,
+                fix: 'leera-qa-runner doctor --fix',
+            });
+        }
+        const loaded = loadFileConfig(paths); // narrows the token file's permissions when they are too wide
+        if (tokenWasOpen && fix) {
+            checks.push({ id: 'token_permissions', title: 'Token file permissions', status: 'ok', detail: 'set to 0600', fixed: true });
+        }
+        fileUrl = loaded.file?.url;
+        fileToken = loaded.token;
+    }
+    catch (error) {
+        checks.push({ id: 'config', title: 'Configuration file', status: 'fail', detail: messageOf(error) });
+    }
+    const url = env.RUNNER_URL?.trim() || env.LEERA_URL?.trim() || fileUrl;
+    const token = env.RUNNER_TOKEN?.trim() || env.LEERA_RUNNER_TOKEN?.trim() || fileToken || undefined;
+    checks.push(url
+        ? { id: 'url', title: 'Server URL', status: 'ok', detail: url }
+        : { id: 'url', title: 'Server URL', status: 'fail', detail: 'no server URL configured', fix: 'leera-qa-runner connect --url <server>' });
+    if (!token) {
+        checks.push({ id: 'token', title: 'Runner token', status: 'fail', detail: 'no runner token configured', fix: 'leera-qa-runner config set-token' });
+    }
+    else if (!token.startsWith(TOKEN_PREFIX)) {
+        checks.push({
+            id: 'token',
+            title: 'Runner token',
+            status: 'fail',
+            detail: `the token is not a runner pool token (${TOKEN_PREFIX}…)`,
+            fix: 'leera-qa-runner config set-token',
+        });
+    }
+    else if (url && !options.offline) {
+        try {
+            const answer = await new RunnerClient(url, token).checkToken();
+            if (answer.result === 'accepted') {
+                checks.push({ id: 'server', title: 'Server and token', status: 'ok', detail: `${url} accepted the token` });
+            }
+            else if (answer.result === 'rejected') {
+                checks.push({
+                    id: 'server',
+                    title: 'Server and token',
+                    status: 'fail',
+                    detail: `${url} rejected the token (HTTP ${answer.status})`,
+                    fix: 'Create a new runner token in the workspace, then run `leera-qa-runner config set-token`',
+                });
+            }
+            else {
+                checks.push({
+                    id: 'server',
+                    title: 'Server and token',
+                    status: 'warn',
+                    detail: `${url} answered HTTP ${answer.status}${answer.message ? ` (${answer.message})` : ''}; is this the right server URL?`,
+                });
+            }
+        }
+        catch (error) {
+            checks.push({
+                id: 'server',
+                title: 'Server and token',
+                status: 'fail',
+                detail: `could not reach ${url}: ${messageOf(error)}`,
+                fix: 'Check the URL, the network and any proxy settings',
+            });
+        }
+    }
+    else {
+        checks.push({ id: 'token', title: 'Runner token', status: 'ok', detail: 'configured' });
+    }
+    // Platforms
+    let detection = await detect(options.registry, host);
+    for (const factory of options.registry.values()) {
+        if (options.platform && factory.platform !== options.platform)
+            continue;
+        // Only a Mac can run iOS jobs; elsewhere iOS is not a problem to fix unless asked about.
+        if (factory.platform === 'ios' && !options.platform && host.os !== 'macos')
+            continue;
+        // Native macOS and Windows apps only run on their own OS.
+        if (factory.platform === 'macos' && !options.platform && host.os !== 'macos')
+            continue;
+        if (factory.platform === 'windows' && !options.platform && host.os !== 'windows')
+            continue;
+        // Tauri needs tools most runners do not have; it is only a problem when asked about.
+        if (factory.platform === 'tauri' && !options.platform && detection.unavailable.tauri)
+            continue;
+        const reasons = detection.unavailable[factory.platform];
+        if (factory.platform === 'web') {
+            const version = playwrightVersion();
+            if (reasons && fix && options.installBrowsers) {
+                const installed = await options.installBrowsers();
+                if (installed) {
+                    detection = await detect(options.registry, host);
+                    checks.push({ id: 'web.chromium', title: 'Web: Chromium', status: 'ok', detail: 'installed', fixed: true });
+                    continue;
+                }
+            }
+            checks.push(reasons
+                ? { id: 'web.chromium', title: 'Web: Chromium', status: 'fail', detail: reasons.join('; '), fix: 'leera-qa-runner setup browsers' }
+                : { id: 'web.chromium', title: 'Web: Chromium', status: 'ok', detail: `Playwright ${version ?? 'unknown'}` });
+        }
+        else {
+            checks.push(reasons
+                ? { id: `${factory.platform}`, title: factory.platform, status: 'fail', detail: reasons.join('; ') }
+                : { id: `${factory.platform}`, title: factory.platform, status: 'ok', detail: 'ready' });
+        }
+    }
+    if (options.registry.has('android') && (!options.platform || options.platform === 'android')) {
+        checks.push(...(await androidChecks(env, paths)));
+    }
+    // iOS is only checked on a Mac (or when asked for): other hosts cannot run it at all.
+    if (options.registry.has('ios') && (options.platform === 'ios' || (!options.platform && process.platform === 'darwin'))) {
+        checks.push(...(await iosChecks(env, paths)));
+    }
+    if (options.registry.has('electron') && (!options.platform || options.platform === 'electron')) {
+        checks.push(...electronChecks({ playwright: playwrightVersion(), electronSupported: electronSupported(), env }));
+    }
+    if (options.registry.has('tauri') && (options.platform === 'tauri' || (!options.platform && !detection.unavailable.tauri))) {
+        checks.push(...tauriChecks(loadTauriSettings(env, paths), { env }));
+    }
+    if (options.registry.has('macos') && (options.platform === 'macos' || (!options.platform && process.platform === 'darwin'))) {
+        checks.push(...(await macosChecks(env, paths)));
+    }
+    if (options.registry.has('windows') && (options.platform === 'windows' || (!options.platform && process.platform === 'win32'))) {
+        checks.push(...(await windowsChecks(env, paths)));
+    }
+    const devices = detection.devices.filter((device) => !options.platform || device.platform === options.platform);
+    return {
+        ok: checks.every((check) => check.status !== 'fail'),
+        version: RUNNER_VERSION,
+        host,
+        home: paths.root,
+        platforms: [...new Set(devices.map((device) => device.platform))],
+        labels: detection.labels,
+        devices,
+        checks,
+    };
+}
+export function formatDoctor(report) {
+    const mark = { ok: '[ok]  ', warn: '[warn]', fail: '[fail]' };
+    const lines = [`leera-qa-runner ${report.version} on ${report.host.os} ${report.host.arch} (${report.host.hostname})`, ''];
+    for (const check of report.checks) {
+        lines.push(`${mark[check.status]} ${check.title}: ${check.detail}${check.fixed ? ' (fixed)' : ''}`);
+        if (check.fix && check.status !== 'ok')
+            lines.push(`       fix: ${check.fix}`);
+    }
+    lines.push('');
+    lines.push(`Devices: ${report.devices.length === 0 ? 'none' : report.devices.map((d) => `${d.name} (${d.platform})`).join(', ')}`);
+    lines.push(`Labels: ${report.labels.length === 0 ? 'none' : report.labels.join(', ')}`);
+    lines.push(report.ok ? 'Ready.' : 'Not ready: fix the items marked [fail].');
+    return lines.join('\n');
+}
+/** Finds `java`: `JAVA_HOME/bin/java`, else whatever is on PATH. */
+export function javaCandidates(env, platform = process.platform) {
+    const exe = platform === 'win32' ? 'java.exe' : 'java';
+    const out = [];
+    if (env.JAVA_HOME?.trim())
+        out.push(join(env.JAVA_HOME.trim(), 'bin', exe));
+    out.push(exe);
+    return out;
+}
+/** Parses the version out of `java -version` output (`openjdk version "17.0.20"` → 17). */
+export function javaMajor(output) {
+    const match = /version "(\d+)(?:\.(\d+))?/.exec(output);
+    if (!match)
+        return null;
+    const first = Number(match[1]);
+    return first === 1 && match[2] ? Number(match[2]) : first;
+}
+/**
+ * Android requirements (plan §7.4): SDK + adb, emulator, build-tools (`apksigner`), Java,
+ * the bundled Appium and UiAutomator2 driver, KVM on Linux, and devices that have not
+ * authorised this computer.
+ */
+export async function androidChecks(env, paths, deps = {}) {
+    const run = deps.run ?? (async (file, args) => {
+        const { stdout, stderr } = await runTool(file, args, { timeoutMs: 20_000 });
+        return `${stdout}${stderr}`;
+    });
+    const exists = deps.exists ?? existsSync;
+    const platform = deps.platform ?? process.platform;
+    const checks = [];
+    const setup = 'leera-qa-runner setup android';
+    const appium = bundledAppium();
+    const drivers = bundledDrivers(platform).filter((d) => d.platforms.includes('android'));
+    if (!appium) {
+        checks.push({
+            id: 'android.appium',
+            title: 'Android: Appium',
+            status: 'fail',
+            detail: 'Appium is not installed with this runner (optional dependencies were omitted)',
+            fix: 'Reinstall the runner with the installer, or `npm install -g @leera.io/qa-runner` without --omit=optional',
+        });
+    }
+    else if (drivers.length === 0) {
+        checks.push({ id: 'android.appium', title: 'Android: Appium', status: 'fail', detail: 'the UiAutomator2 driver is not installed with this runner' });
+    }
+    else {
+        checks.push({
+            id: 'android.appium',
+            title: 'Android: Appium',
+            status: 'ok',
+            detail: `Appium ${appium.version}, ${drivers.map((d) => `${d.name} ${d.version}`).join(', ')}; home ${join(paths.root, 'appium')}`,
+        });
+    }
+    let configured = null;
+    try {
+        configured = readJsonFile(paths.config)?.android?.sdk_path?.trim() || null;
+    }
+    catch {
+        configured = null;
+    }
+    const sdk = resolveAndroidSdk({ env, platform, exists, ...(configured ? { configured } : {}) });
+    if (!sdk) {
+        checks.push({
+            id: 'android.sdk',
+            title: 'Android: SDK',
+            status: 'fail',
+            detail: 'no Android SDK with platform-tools was found (config android.sdk_path, ANDROID_HOME, ANDROID_SDK_ROOT, default location)',
+            fix: `Install Android Studio or the command-line tools, set ANDROID_HOME, then run \`${setup}\``,
+        });
+        return checks;
+    }
+    checks.push({ id: 'android.sdk', title: 'Android: SDK', status: 'ok', detail: `${sdk.root} (from ${sdk.source})` });
+    try {
+        const out = await run(sdk.adb, ['version']);
+        const version = /Android Debug Bridge version ([\d.]+)/.exec(out)?.[1] ?? 'unknown';
+        checks.push({ id: 'android.adb', title: 'Android: adb', status: 'ok', detail: `adb ${version}` });
+    }
+    catch (error) {
+        checks.push({ id: 'android.adb', title: 'Android: adb', status: 'fail', detail: `adb does not run: ${messageOf(error)}`, fix: 'Reinstall platform-tools with sdkmanager' });
+    }
+    checks.push(sdk.emulator
+        ? { id: 'android.emulator', title: 'Android: emulator', status: 'ok', detail: sdk.emulator }
+        : {
+            id: 'android.emulator',
+            title: 'Android: emulator',
+            status: 'warn',
+            detail: 'the emulator package is not installed; only USB devices can be used',
+            fix: 'sdkmanager --install emulator',
+        });
+    const apksigner = sdk.buildTools ? join(sdk.buildTools, platform === 'win32' ? 'apksigner.bat' : 'apksigner') : null;
+    checks.push(apksigner && exists(apksigner)
+        ? { id: 'android.build_tools', title: 'Android: build-tools', status: 'ok', detail: sdk.buildTools }
+        : {
+            id: 'android.build_tools',
+            title: 'Android: build-tools',
+            status: 'warn',
+            detail: 'no build-tools with apksigner were found; UiAutomator2 needs them to check app signatures',
+            fix: 'sdkmanager --install "build-tools;35.0.0"',
+        });
+    let javaDetail = null;
+    for (const java of javaCandidates(env, platform)) {
+        try {
+            const major = javaMajor(await run(java, ['-version']));
+            if (major !== null) {
+                javaDetail = `Java ${major} (${java})`;
+                break;
+            }
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    checks.push(javaDetail
+        ? { id: 'android.java', title: 'Android: Java', status: 'ok', detail: javaDetail }
+        : {
+            id: 'android.java',
+            title: 'Android: Java',
+            status: 'warn',
+            detail: 'Java was not found; UiAutomator2 uses it for app signature checks',
+            fix: 'Install a JDK (17 or newer) and set JAVA_HOME',
+        });
+    if (platform === 'linux') {
+        const kvm = (deps.canAccess ?? ((path) => {
+            try {
+                accessSync(path, constants.R_OK | constants.W_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }))('/dev/kvm');
+        checks.push(kvm
+            ? { id: 'android.kvm', title: 'Android: KVM', status: 'ok', detail: '/dev/kvm is usable' }
+            : {
+                id: 'android.kvm',
+                title: 'Android: KVM',
+                status: 'warn',
+                detail: '/dev/kvm is missing or not accessible; emulators will be very slow or not start',
+                fix: 'Enable virtualization and add this user to the kvm group',
+            });
+    }
+    try {
+        const devices = await new Adb(sdk.adb).devices();
+        const unauthorized = devices.filter((d) => d.state === 'unauthorized').map((d) => d.serial);
+        const ready = devices.filter((d) => d.state === 'device').map((d) => d.serial);
+        if (unauthorized.length > 0) {
+            checks.push({
+                id: 'android.devices',
+                title: 'Android: devices',
+                status: 'warn',
+                detail: `not authorised: ${unauthorized.join(', ')}`,
+                fix: 'Unlock the phone and accept the "Allow USB debugging" prompt',
+            });
+        }
+        else {
+            checks.push({
+                id: 'android.devices',
+                title: 'Android: devices',
+                status: 'ok',
+                detail: ready.length > 0 ? `connected: ${ready.join(', ')}` : 'no device connected (AVDs are booted on demand)',
+            });
+        }
+    }
+    catch (error) {
+        checks.push({ id: 'android.devices', title: 'Android: devices', status: 'warn', detail: `adb could not list devices: ${messageOf(error)}` });
+    }
+    return checks;
+}

package/dist/src/download.js

@@ -0,0 +1,39 @@
+import { closeSync, openSync, writeSync } from 'node:fs';
+/**
+ * Writes an HTTP response body to `path` (mode 0600), calling `onChunk` before each chunk is written
+ * (throw from it to abort). Returns the number of bytes written.
+ *
+ * The body is read chunk by chunk and written synchronously instead of piped through
+ * `Readable.fromWeb` into a write stream: with the undici bundled in Node 24.21, a server that closes
+ * the connection after the body (HTTP/1.0 style, e.g. `python3 -m http.server` or some proxies) while
+ * the body stream is paused by write-stream backpressure crashes the process with an uncaught
+ * `assert(!this.paused)` in `Parser.finish` (fixed upstream in undici's client-h1). Draining the body
+ * promptly keeps the parser from being paused when the socket ends.
+ */
+export async function writeResponseBody(body, path, onChunk) {
+    const reader = body.getReader();
+    const fd = openSync(path, 'w', 0o600);
+    let written = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value || value.length === 0)
+                continue;
+            onChunk?.(value);
+            let offset = 0;
+            while (offset < value.length)
+                offset += writeSync(fd, value, offset, value.length - offset);
+            written += value.length;
+        }
+        return written;
+    }
+    catch (error) {
+        await reader.cancel().catch(() => undefined);
+        throw error;
+    }
+    finally {
+        closeSync(fd);
+    }
+}