@leera.io/qa-runner 1.0.0

package/dist/src/cli/commands/service.js

@@ -0,0 +1,165 @@
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { parseArgs } from 'node:util';
+import { loadFileConfig, saveFileConfig } from '../../config.js';
+import { accessibilityMarker } from '../../devices/macos.js';
+import { ExitCode } from '../../errors.js';
+import { ensureHome, homePaths, readJsonFile } from '../../home.js';
+import { applyPlan, backendFor, CAPTURED_ENV, serviceSpec, } from '../../service/index.js';
+import { usageError } from '../output.js';
+const usage = `Usage: leera-qa-runner service <install|uninstall|start|stop|restart|status|logs> [-f]
+
+Runs the runner in the background for the logged-in user, starting at login:
+  macOS    a LaunchAgent (~/Library/LaunchAgents/io.leera.qa-runner.plist)
+  Windows  a scheduled task at logon (leera-qa-runner)
+  Linux    a systemd user unit (leera-qa-runner.service)
+
+  service logs [-f]   Print the runner log; -f keeps following it
+`;
+const ACTIONS = ['install', 'uninstall', 'start', 'stop', 'restart', 'status'];
+/** Last `lines` lines of a file, read from the end. */
+export function tail(path, lines) {
+    const size = statSync(path).size;
+    const chunk = Math.min(size, 256 * 1024);
+    const buffer = Buffer.alloc(chunk);
+    const fd = openSync(path, 'r');
+    try {
+        readSync(fd, buffer, 0, chunk, size - chunk);
+    }
+    finally {
+        closeSync(fd);
+    }
+    const text = buffer.toString('utf8').split('\n');
+    if (text.at(-1) === '')
+        text.pop();
+    return text.slice(-lines).join('\n');
+}
+async function follow(io, path) {
+    let position = existsSync(path) ? statSync(path).size : 0;
+    for (;;) {
+        await sleep(1_000);
+        if (!existsSync(path))
+            continue;
+        const size = statSync(path).size;
+        if (size < position)
+            position = 0; // rotated
+        if (size === position)
+            continue;
+        const buffer = Buffer.alloc(size - position);
+        const fd = openSync(path, 'r');
+        try {
+            readSync(fd, buffer, 0, buffer.length, position);
+        }
+        finally {
+            closeSync(fd);
+        }
+        position = size;
+        io.stdout(buffer.toString('utf8').replace(/\n$/, ''));
+    }
+}
+function processAlive(pid) {
+    if (typeof pid !== 'number')
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const command = {
+    summary: 'Install and control the background service',
+    usage,
+    async run(args, io) {
+        const { values, positionals } = parseArgs({
+            args,
+            strict: true,
+            allowPositionals: true,
+            options: { follow: { type: 'boolean', short: 'f' }, lines: { type: 'string', short: 'n' } },
+        });
+        const [action, ...extra] = positionals;
+        if (!action || extra.length > 0)
+            throw usageError('say what to do', usage);
+        const paths = homePaths(io.env);
+        if (action === 'logs') {
+            const lines = values.lines ? Number(values.lines) : 100;
+            if (!Number.isInteger(lines) || lines <= 0)
+                throw usageError('--lines must be a positive whole number');
+            if (existsSync(paths.log))
+                io.stdout(tail(paths.log, lines));
+            else
+                io.stdout(`No log yet at ${paths.log}.`);
+            if (values.follow)
+                await follow(io, paths.log);
+            return ExitCode.ok;
+        }
+        if (!ACTIONS.includes(action))
+            throw usageError(`unknown service action '${action}'`, usage);
+        const backend = backendFor(io.platform);
+        if (!backend)
+            throw usageError(`background services are not supported on ${io.platform}; run \`leera-qa-runner start\``);
+        const spec = serviceSpec(io.env, paths.root, paths.logs);
+        if (action === 'install') {
+            const { file, token } = loadFileConfig(paths);
+            if (!file?.url || !token) {
+                throw usageError('connect first: `leera-qa-runner connect --url <server>`');
+            }
+            // Services start without the login shell; keep the variables jobs rely on.
+            const env = { ...(file.env ?? {}) };
+            for (const name of CAPTURED_ENV) {
+                const value = io.env[name];
+                if (value)
+                    env[name] = value;
+            }
+            ensureHome(paths);
+            saveFileConfig(paths, { ...file, env });
+        }
+        const plan = backend.plan(action, spec);
+        const result = await applyPlan(plan);
+        if (action === 'status' && result.ok) {
+            for (const output of result.outputs) {
+                const text = `${output.result.stdout}${output.result.stderr}`.trim();
+                if (text)
+                    io.stdout(text);
+            }
+        }
+        if (!result.ok && result.failed) {
+            const text = `${result.failed.result.stdout}${result.failed.result.stderr}`.trim();
+            if (action === 'status') {
+                io.stdout('The service is not installed or not loaded.');
+            }
+            else {
+                io.stderr(`\`${result.failed.argv.join(' ')}\` failed (exit ${result.failed.result.code})${text ? `: ${text}` : ''}`);
+                return ExitCode.error;
+            }
+        }
+        if (action === 'status') {
+            const state = readJsonFile(paths.state);
+            if (state) {
+                const alive = processAlive(state.pid) && state.stopped !== true;
+                io.stdout('');
+                io.stdout(`Runner process: ${alive ? `running (pid ${String(state.pid)})` : 'not running'}`);
+                io.stdout(`Runner id: ${String(state.runner_id ?? 'not registered')}  version: ${String(state.version ?? '?')}`);
+                const jobs = Array.isArray(state.jobs) ? state.jobs : [];
+                io.stdout(`Jobs running: ${alive ? jobs.length : 0}`);
+            }
+            if (io.platform === 'darwin' && existsSync(accessibilityMarker(paths))) {
+                io.stdout('');
+                io.stdout(`macOS apps: not advertised — macOS refused UI testing (${accessibilityMarker(paths)}); grant the permission, then run \`leera-qa-runner setup macos\``);
+            }
+            return result.ok ? ExitCode.ok : ExitCode.error;
+        }
+        for (const note of plan.notes ?? [])
+            io.stdout(note);
+        const done = {
+            install: `Installed and started the service (${backend.definitionPath(spec)}).`,
+            uninstall: 'Removed the service.',
+            start: 'Started the service.',
+            stop: 'Stopped the service.',
+            restart: 'Restarted the service.',
+        };
+        io.stdout(done[action] ?? 'Done.');
+        return ExitCode.ok;
+    },
+};

package/dist/src/cli/commands/setup.js

@@ -0,0 +1,193 @@
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { ExitCode } from '../../errors.js';
+import { ensureHome, homePaths } from '../../home.js';
+import { usageError } from '../output.js';
+import { setupAndroid } from '../../devices/android/setup.js';
+import { displayNeed, findOnPath, XVFB_DISPLAY } from '../../devices/desktop.js';
+import { setupIos } from '../../devices/ios/setup.js';
+import { setupMacos } from '../../devices/macos.js';
+import { setupWindows } from '../../devices/windows.js';
+import { findNativeDriver, findTauriDriver, loadTauriSettings, MSEDGEDRIVER_URL, TAURI_DRIVER_INSTALL, TAURI_DRIVER_VERSION, WEBKIT_DRIVER_INSTALL, } from '../../devices/tauri.js';
+const usage = `Usage: leera-qa-runner setup browsers|android|ios|electron|tauri|macos|windows [options]
+
+Installs what a platform needs. This version supports:
+  browsers            Chromium for web jobs (into the runner home unless PLAYWRIGHT_BROWSERS_PATH is set)
+  android             Prepares Appium's home with the bundled UiAutomator2 driver, checks the
+                      Android SDK and lists devices and emulators
+  ios                 (macOS) Checks Xcode, prepares Appium's home with the bundled XCUITest driver,
+                      prebuilds WebDriverAgent for simulators and lists simulators and devices
+  electron            Nothing to install: Electron apps run with the bundled Playwright (Linux
+                      runners without a display need Xvfb)
+  tauri               Checks tauri-driver and the native WebDriver (Linux: WebKitWebDriver,
+                      Windows: msedgedriver) and prints how to install what is missing; on
+                      macOS explains the embedded WebDriver plugin (installs nothing)
+  macos               (macOS) Checks Xcode, prepares Appium's home with the bundled Mac2 driver and
+                      prints the Accessibility and Automation permission steps (changes no
+                      system settings)
+  windows             (Windows) Prepares Appium's home with the bundled Windows driver, downloads
+                      WinAppDriver 1.2.1 (checked by sha256) into the runner home and prints the
+                      install and Developer Mode steps
+
+Options for android:
+  --install-sdk       Install platform-tools, emulator, build-tools and a system image with the
+                      SDK's sdkmanager, and create an emulator when none exists
+  --image ID          System image for --install-sdk (default for this computer's CPU)
+  --avd NAME          Name of the emulator --install-sdk creates (default leera_pixel)
+
+Options for ios:
+  --rebuild           Build WebDriverAgent again even when it is already built
+
+Options for windows:
+  --install           Also install WinAppDriver with msiexec /qn (run from an elevated shell)
+`;
+/** The argv that installs Chromium with the Playwright version the runner uses. */
+export function browserInstallArgv(execPath = process.execPath) {
+    const require = createRequire(import.meta.url);
+    // cli.js is not in the package's exports map, so it is found next to package.json.
+    const cli = join(dirname(require.resolve('playwright-core/package.json')), 'cli.js');
+    return [execPath, cli, 'install', 'chromium'];
+}
+export async function installBrowsers(io, paths) {
+    const browsersPath = io.env.PLAYWRIGHT_BROWSERS_PATH?.trim() || paths.browsers;
+    ensureHome(paths);
+    const argv = browserInstallArgv();
+    io.stdout(`Installing Chromium into ${browsersPath} ...`);
+    const code = await new Promise((resolve) => {
+        const child = spawn(argv[0], argv.slice(1), {
+            stdio: ['ignore', 'inherit', 'inherit'],
+            env: { ...io.env, PLAYWRIGHT_BROWSERS_PATH: browsersPath },
+        });
+        child.on('error', () => resolve(ExitCode.error));
+        child.on('close', (exit) => resolve(exit ?? ExitCode.error));
+    });
+    if (code !== 0) {
+        io.stderr('Chromium could not be installed; see the output above.');
+        return ExitCode.error;
+    }
+    if (io.platform === 'linux') {
+        io.stdout(`Chromium needs system libraries on Linux. If jobs fail to launch the browser, run as an administrator:\n  sudo ${argv[0]} ${argv[1]} install-deps chromium`);
+    }
+    io.stdout('Chromium is installed.');
+    return ExitCode.ok;
+}
+/**
+ * `setup tauri` (contracts §L): checks what Tauri jobs need and prints the commands that install
+ * it; runs nothing with elevated rights. Exit 0 when ready, 4 when something is missing.
+ */
+export function setupTauri(io, paths, lookup = {}) {
+    const settings = loadTauriSettings(io.env, paths);
+    const options = { platform: io.platform, env: io.env, ...lookup };
+    if (io.platform === 'darwin') {
+        io.stdout([
+            'macOS has no tauri-driver: WKWebView offers no WebDriver, so a plain Tauri build cannot be tested on a Mac.',
+            'A Mac runs Tauri jobs only for builds that embed the WebDriver plugin (a debug or feature-gated build, never',
+            'production). The runner starts such a build with TAURI_WEBDRIVER_PORT set and attaches to that port; a build',
+            'without the plugin is reported blocked ("Tauri on macOS needs a build with the embedded WebDriver plugin").',
+            '',
+            settings.macosPlugin
+                ? 'tauri.macos_plugin is on: this runner advertises a Tauri device.'
+                : 'When your builds embed the plugin, turn it on:\n  leera-qa-runner config set tauri.macos_plugin true',
+        ].join('\n'));
+        return settings.macosPlugin ? ExitCode.ok : ExitCode.environmentNotReady;
+    }
+    if (io.platform !== 'linux' && io.platform !== 'win32') {
+        io.stderr(`Tauri jobs do not run on ${io.platform}.`);
+        return ExitCode.environmentNotReady;
+    }
+    let ready = true;
+    const driver = findTauriDriver(settings, options);
+    if (driver)
+        io.stdout(`tauri-driver: ${driver}`);
+    else {
+        ready = false;
+        io.stdout(`tauri-driver ${TAURI_DRIVER_VERSION} is not installed. Install Rust (https://rustup.rs), then run:\n  ${TAURI_DRIVER_INSTALL}\n(or point the runner at it: leera-qa-runner config set tauri.driver_path /path/to/tauri-driver)`);
+    }
+    const native = findNativeDriver(settings, options);
+    if (io.platform === 'linux') {
+        if (native)
+            io.stdout(`WebKitWebDriver: ${native}`);
+        else {
+            ready = false;
+            io.stdout(`WebKitWebDriver is not installed. Run as an administrator:\n  ${WEBKIT_DRIVER_INSTALL}`);
+        }
+        const display = displayNeed('linux', io.env, (name) => findOnPath(name, io.env, options.exists));
+        if (display.kind === 'xvfb')
+            io.stdout(`No DISPLAY: jobs start ${display.xvfb} ${XVFB_DISPLAY}.`);
+        if (display.kind === 'missing') {
+            io.stdout('This Linux machine has no DISPLAY; install Xvfb (for example `sudo apt-get install xvfb`) so jobs can open windows.');
+        }
+    }
+    else if (native) {
+        io.stdout(`msedgedriver: ${native}`);
+    }
+    else {
+        ready = false;
+        io.stdout([
+            'msedgedriver.exe was not found. Tauri on Windows drives WebView2 through Microsoft Edge WebDriver:',
+            `  1. Download the msedgedriver whose version matches your WebView2 Runtime from ${MSEDGEDRIVER_URL}`,
+            '     (or run `cargo install --git https://github.com/chippers/msedgedriver-tool` and `msedgedriver-tool`).',
+            '  2. leera-qa-runner config set tauri.native_driver_path C:\\path\\to\\msedgedriver.exe',
+        ].join('\n'));
+    }
+    io.stdout(ready ? 'Tauri is ready.' : 'Tauri is not ready: install what is listed above, then run `leera-qa-runner doctor --platform tauri`.');
+    return ready ? ExitCode.ok : ExitCode.environmentNotReady;
+}
+export const command = {
+    summary: 'Install platform tools (browsers, android, ios, electron, tauri, macos, windows)',
+    usage,
+    async run(args, io) {
+        const { positionals, values } = parseArgs({
+            args,
+            strict: true,
+            allowPositionals: true,
+            options: {
+                'install-sdk': { type: 'boolean' },
+                image: { type: 'string' },
+                avd: { type: 'string' },
+                rebuild: { type: 'boolean' },
+                install: { type: 'boolean' },
+            },
+        });
+        const [what, ...extra] = positionals;
+        if (!what || extra.length > 0)
+            throw usageError('say what to set up', usage);
+        if (what !== 'android' && (values['install-sdk'] || values.image || values.avd)) {
+            throw usageError('--install-sdk, --image and --avd only apply to setup android', usage);
+        }
+        if (what !== 'ios' && values.rebuild)
+            throw usageError('--rebuild only applies to setup ios', usage);
+        if (what !== 'windows' && values.install)
+            throw usageError('--install only applies to setup windows', usage);
+        if (what === 'browsers')
+            return installBrowsers(io, homePaths(io.env));
+        if (what === 'ios')
+            return setupIos(io, homePaths(io.env), { rebuild: values.rebuild ?? false });
+        if (what === 'android') {
+            return setupAndroid(io, homePaths(io.env), {
+                installSdk: values['install-sdk'] ?? false,
+                ...(values.image ? { image: values.image } : {}),
+                ...(values.avd ? { avd: values.avd } : {}),
+            });
+        }
+        if (what === 'electron') {
+            io.stdout('Nothing to set up for Electron: apps run with the Playwright bundled with this runner.');
+            if (io.platform === 'linux' && !io.env.DISPLAY?.trim()) {
+                io.stdout('This Linux machine has no DISPLAY; install Xvfb (for example `sudo apt-get install xvfb`) so jobs can open windows.');
+            }
+            return ExitCode.ok;
+        }
+        if (what === 'tauri')
+            return setupTauri(io, homePaths(io.env));
+        if (what === 'macos')
+            return setupMacos(io, homePaths(io.env));
+        if (what === 'windows')
+            return setupWindows(io, homePaths(io.env), { install: values.install ?? false });
+        if (what === 'all') {
+            throw usageError(`'setup all' is not available in this runner version; set up one platform at a time`, usage);
+        }
+        throw usageError(`unknown setup target '${what}'`, usage);
+    },
+};

package/dist/src/cli/commands/start.js

@@ -0,0 +1,94 @@
+import { parseArgs } from 'node:util';
+import { splitList } from '../../config.js';
+import { stopSharedAppiumServer } from '../../drivers/android-appium.js';
+import { ExitCode } from '../../errors.js';
+import { homePaths } from '../../home.js';
+import { createLogger } from '../../log.js';
+import { createRunner } from '../../runner.js';
+import { usageError } from '../output.js';
+const usage = `Usage: leera-qa-runner start [options]
+
+Registers with the server and runs queued jobs until stopped.
+
+Options:
+  --once              Exit after the first job
+  --service           Run as the background service (logs go to the runner home)
+  --headed            Show browser windows
+  --labels a,b        Use exactly these labels instead of the detected ones
+  --concurrency N     Browser jobs at once (default 1)
+  --run-id N          Only take jobs from this test run
+`;
+export function parseStartFlags(args) {
+    const { values } = parseArgs({
+        args,
+        strict: true,
+        allowPositionals: false,
+        options: {
+            once: { type: 'boolean' },
+            service: { type: 'boolean' },
+            headed: { type: 'boolean' },
+            labels: { type: 'string' },
+            concurrency: { type: 'string' },
+            'run-id': { type: 'string' },
+            // Set by service definitions when the home directory is not the default.
+            home: { type: 'string' },
+        },
+    });
+    const flags = {};
+    if (values.once)
+        flags.once = true;
+    if (values.service)
+        flags.service = true;
+    if (values.headed)
+        flags.headed = true;
+    if (values.labels !== undefined)
+        flags.labels = splitList(values.labels);
+    if (values.concurrency !== undefined)
+        flags.concurrency = positive(values.concurrency, '--concurrency');
+    if (values['run-id'] !== undefined)
+        flags.runId = positive(values['run-id'], '--run-id');
+    return flags;
+}
+function positive(raw, name) {
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0)
+        throw usageError(`${name} must be a positive whole number`, usage);
+    return value;
+}
+export const command = {
+    summary: 'Run queued jobs until stopped',
+    usage,
+    async run(args, io) {
+        const flags = parseStartFlags(args);
+        const paths = homePaths(io.env);
+        const log = createLogger(flags.service
+            ? { console: 'off', file: paths.log }
+            : { console: io.interactive ? 'pretty' : 'json' });
+        const { runner, shared } = await createRunner({ flags, env: io.env, log, writeState: true });
+        let signal = null;
+        const onSignal = (received) => {
+            if (signal === 'SIGINT' && received === 'SIGINT') {
+                log.warn('interrupted twice, exiting now');
+                process.exit(ExitCode.interrupted);
+            }
+            signal = received;
+            runner.stop();
+        };
+        process.on('SIGINT', onSignal);
+        process.on('SIGTERM', onSignal);
+        try {
+            await runner.run();
+        }
+        catch (error) {
+            log.error('runner stopped', { error: error instanceof Error ? error.message : String(error) });
+            throw error;
+        }
+        finally {
+            process.off('SIGINT', onSignal);
+            process.off('SIGTERM', onSignal);
+            await shared.browsers.close();
+            await stopSharedAppiumServer();
+        }
+        return signal === 'SIGINT' ? ExitCode.interrupted : ExitCode.ok;
+    },
+};

package/dist/src/cli/commands/update.js

@@ -0,0 +1,189 @@
+import { createInterface } from 'node:readline';
+import { parseArgs } from 'node:util';
+import { ExitCode, ExitError, messageOf } from '../../errors.js';
+import { homePaths } from '../../home.js';
+import { installArchive, packageManagerArgv, recordUpdate, restartServiceIfInstalled, runInherited, DOCKER_IMAGE, } from '../../update/apply.js';
+import { checkForUpdate, detectInstall } from '../../update/check.js';
+import { assetKey, fetchManifest, updateBase } from '../../update/manifest.js';
+import { checkManifestTrust } from '../../update/verify.js';
+import { BUILD_INFO, compareVersions, PACKAGE_ROOT, RUNNER_VERSION } from '../../version.js';
+import { usageError } from '../output.js';
+/** `update --check` exit code when a newer version exists. */
+export const UPDATE_AVAILABLE = 10;
+const usage = `Usage: leera-qa-runner update [--check] [--version X] [--yes]
+
+Updates the runner in the way it was installed:
+  .pkg / .exe / tarball   downloads the release archive, verifies it against the signed
+                          release manifest, unpacks it into ~/.leera-qa-runner/versions/<version>,
+                          switches to it and restarts the background service (no administrator rights)
+  npm / Homebrew / winget runs (or, without --yes, prints) the package manager's upgrade
+  Docker                  pull the new image instead
+
+Options:
+  --check        Only report whether an update is available (exit 0: up to date, 10: update available)
+  --version X    Install this version instead of the latest one
+  --yes, -y      Do not ask for confirmation
+`;
+async function ask(io, question) {
+    io.stdout(question);
+    const rl = createInterface({ input: io.stdin });
+    try {
+        for await (const line of rl)
+            return /^y(es)?$/i.test(line.trim());
+        return false;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function confirmed(io, yes, question) {
+    if (yes)
+        return true;
+    if (!io.interactive)
+        return false;
+    return ask(io, `${question} [y/N]`);
+}
+export function updateCommand(deps = {}) {
+    return {
+        summary: 'Update the runner to the latest release',
+        usage,
+        async run(args, io) {
+            const { values, positionals } = parseArgs({
+                args,
+                strict: true,
+                allowPositionals: true,
+                options: { check: { type: 'boolean' }, version: { type: 'string' }, yes: { type: 'boolean', short: 'y' } },
+            });
+            if (positionals.length > 0)
+                throw usageError(`unexpected argument '${positionals[0]}'`, usage);
+            const requested = values.version?.trim().replace(/^v/, '');
+            if (requested !== undefined && !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(requested)) {
+                throw usageError(`--version must look like 1.2.3, not '${values.version}'`, usage);
+            }
+            if (values.check && requested)
+                throw usageError('--check and --version cannot be combined', usage);
+            const paths = homePaths(io.env);
+            const base = updateBase(io.env);
+            const current = deps.current ?? RUNNER_VERSION;
+            const fetchImpl = deps.fetch ?? fetch;
+            if (values.check) {
+                let check;
+                try {
+                    check = await checkForUpdate({ current, paths, base, fetch: fetchImpl });
+                }
+                catch (error) {
+                    throw new ExitError(ExitCode.error, `could not check for updates: ${messageOf(error)}`);
+                }
+                io.stdout(`Current version: ${check.current}`);
+                io.stdout(`Latest version:  ${check.latest} (${check.source === 'server' ? 'reported by the server' : 'latest release'})`);
+                if (!check.available) {
+                    io.stdout('The runner is up to date.');
+                    return ExitCode.ok;
+                }
+                io.stdout('An update is available: run `leera-qa-runner update`.');
+                return UPDATE_AVAILABLE;
+            }
+            const install = detectInstall({
+                paths,
+                env: io.env,
+                packageRoot: deps.packageRoot ?? PACKAGE_ROOT,
+                buildInfo: deps.buildInfo ?? BUILD_INFO,
+            });
+            if (install.method === 'unknown') {
+                throw new ExitError(ExitCode.error, `cannot tell how this runner was installed (no ${paths.install}); update it the way you installed it, or reinstall with the installer from the releases page`);
+            }
+            if (install.method === 'docker') {
+                io.stdout(`This runner runs in Docker: pull the new image and recreate the container:\n  docker pull ${DOCKER_IMAGE}:${requested ?? 'latest'}`);
+                return ExitCode.ok;
+            }
+            const managerArgv = packageManagerArgv(install.method, requested);
+            if (managerArgv) {
+                if (install.method === 'brew' && requested)
+                    io.stdout('Homebrew installs the cask\'s current version; --version is ignored.');
+                const line = managerArgv.join(' ');
+                if (!(await confirmed(io, values.yes === true, `Run \`${line}\`?`))) {
+                    io.stdout(`To update, run:\n  ${line}\n(or rerun with --yes to run it now)`);
+                    return ExitCode.ok;
+                }
+                io.stdout(`$ ${line}`);
+                const code = await (deps.runPackageManager ?? runInherited)(managerArgv, io.platform);
+                if (code !== 0)
+                    throw new ExitError(ExitCode.error, `\`${line}\` exited with ${code}`);
+                return ExitCode.ok;
+            }
+            // pkg, exe and tar installs update into the runner home.
+            const arch = deps.arch ?? process.arch;
+            const key = assetKey(io.platform, arch);
+            if (!key)
+                throw new ExitError(ExitCode.error, `there is no runner release for ${io.platform}-${arch}`);
+            let fetched;
+            try {
+                fetched = await fetchManifest(base, requested, fetchImpl);
+            }
+            catch (error) {
+                throw new ExitError(ExitCode.error, `could not read the release manifest: ${messageOf(error)}`);
+            }
+            const { manifest } = fetched;
+            if (!requested && compareVersions(manifest.version, current) <= 0) {
+                io.stdout(`The runner is up to date (${current}).`);
+                return ExitCode.ok;
+            }
+            if (requested && manifest.version !== requested) {
+                throw new ExitError(ExitCode.error, `the release manifest for ${requested} describes version ${manifest.version}; refusing to update`);
+            }
+            const buildInfo = deps.buildInfo ?? BUILD_INFO;
+            let trust;
+            try {
+                trust = checkManifestTrust(fetched.bytes, fetched.signature, buildInfo.release_public_key);
+            }
+            catch (error) {
+                throw new ExitError(ExitCode.error, messageOf(error));
+            }
+            if (trust.warning)
+                io.stderr(`warning: ${trust.warning}`);
+            const asset = manifest.assets[key];
+            if (!asset)
+                throw new ExitError(ExitCode.error, `release ${manifest.version} has no archive for ${key}`);
+            if (!(await confirmed(io, values.yes === true, `Update leera-qa-runner ${current} → ${manifest.version}?`))) {
+                if (io.interactive) {
+                    io.stdout('Not updated.');
+                    return ExitCode.ok;
+                }
+                throw usageError('pass --yes to update without a prompt', usage);
+            }
+            io.stdout(`Downloading ${asset.file} (${Math.round(asset.size / (1024 * 1024))} MB)…`);
+            let result;
+            try {
+                result = await installArchive({
+                    paths,
+                    version: manifest.version,
+                    asset,
+                    base,
+                    platform: io.platform,
+                    env: io.env,
+                    fetch: fetchImpl,
+                    ...(deps.exec ? { exec: deps.exec } : {}),
+                    protect: [deps.packageRoot ?? PACKAGE_ROOT],
+                });
+            }
+            catch (error) {
+                throw new ExitError(ExitCode.error, `update failed: ${messageOf(error)}`);
+            }
+            recordUpdate(paths, install.method, manifest.version);
+            io.stdout(`${result.reused ? 'Switched to' : 'Installed'} leera-qa-runner ${manifest.version} in ${result.dir}${trust.signed ? ' (signature verified)' : ''}.`);
+            if (result.removed.length > 0)
+                io.stdout(`Removed old versions: ${result.removed.join(', ')}.`);
+            if (compareVersions(manifest.version, current) < 0) {
+                io.stdout('Note: the launcher only switches to versions newer than the installed bundle; reinstall the older release to downgrade it.');
+            }
+            const restart = await (deps.restartService ?? ((value) => restartServiceIfInstalled(value.platform, value.env, paths, deps.exec)))(io);
+            if (restart.restarted)
+                io.stdout('Restarted the background service.');
+            else if (restart.reason === 'failed') {
+                io.stderr(`warning: the background service could not be restarted (${restart.message}); run \`leera-qa-runner service restart\``);
+            }
+            return ExitCode.ok;
+        },
+    };
+}
+export const command = updateCommand();

package/dist/src/cli/commands/version.js

@@ -0,0 +1,28 @@
+import { parseArgs } from 'node:util';
+import { hostInfo } from '../../capabilities.js';
+import { ExitCode } from '../../errors.js';
+import { BUILD_INFO, playwrightVersion, RUNNER_VERSION } from '../../version.js';
+import { printJson } from '../output.js';
+export const command = {
+    summary: 'Print the runner version',
+    usage: 'Usage: leera-qa-runner version [--json]\n',
+    async run(args, io) {
+        const { values } = parseArgs({ args, strict: true, options: { json: { type: 'boolean' } } });
+        const host = hostInfo();
+        if (values.json) {
+            printJson(io, {
+                version: RUNNER_VERSION,
+                node: host.node,
+                playwright: playwrightVersion(),
+                os: host.os,
+                arch: host.arch,
+                ...(BUILD_INFO.commit ? { commit: BUILD_INFO.commit } : {}),
+                ...(BUILD_INFO.built_at ? { built_at: BUILD_INFO.built_at } : {}),
+            });
+        }
+        else {
+            io.stdout(`leera-qa-runner ${RUNNER_VERSION}`);
+        }
+        return ExitCode.ok;
+    },
+};