@leera.io/qa-runner 1.0.0

package/dist/src/builds/install.js

@@ -0,0 +1,75 @@
+import { existsSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { BuildCache } from './cache.js';
+import { obtainBuild } from './download.js';
+/** `~/.leera-qa-runner/cache/builds`. */
+export function buildCacheDir(paths) {
+    return join(paths.root, 'cache', 'builds');
+}
+const caches = new Map();
+/** One cache object per directory per process, so pins are shared between jobs. */
+export function buildCacheFor(paths, maxBytes) {
+    const dir = buildCacheDir(paths);
+    let cache = caches.get(dir);
+    if (!cache) {
+        cache = new BuildCache(dir, maxBytes);
+        caches.set(dir, cache);
+    }
+    return cache;
+}
+export class AppNotAvailable extends Error {
+}
+/** Builds `ci --build PATH` hashed on this machine, by sha256 (jobs name them with `install: runner-local`). */
+const localBuilds = new Map();
+export function registerLocalBuild(sha256, path) {
+    localBuilds.set(sha256.toLowerCase(), path);
+}
+export function unregisterLocalBuild(sha256) {
+    localBuilds.delete(sha256.toLowerCase());
+}
+/**
+ * Where the app comes from for a job or session:
+ * - `build`: the uploaded build, from the cache or downloaded and verified;
+ * - `installed`: nothing to install, the app must already be on the device;
+ * - `path`: a file on this machine, only when the runner allows local paths;
+ * - `runner-local`: a build `ci --build` hashed on this machine (matched by sha256).
+ */
+export async function resolveAppFile(options) {
+    const { app } = options;
+    switch (app.install) {
+        case 'installed':
+            return { path: null, release: () => undefined };
+        case 'build': {
+            if (!app.build)
+                throw new AppNotAvailable('the environment installs a build, but the job names none (was it deleted?)');
+            const build = app.build;
+            const downloaded = await obtainBuild({
+                cache: buildCacheFor(options.paths),
+                build,
+                getUrl: () => options.getUrl(build.id),
+            });
+            return { path: downloaded.path, release: downloaded.release };
+        }
+        case 'path': {
+            if (!options.allowLocalPaths) {
+                throw new AppNotAvailable('this runner does not install apps from local paths (set builds.allow_local_paths to true)');
+            }
+            const path = app.path ?? '';
+            if (!isAbsolute(path) || !existsSync(path) || !statSync(path).isFile()) {
+                throw new AppNotAvailable(`the app file ${path || '(none)'} does not exist on this runner`);
+            }
+            return { path, release: () => undefined };
+        }
+        case 'runner-local': {
+            // The CI command registered the file; the server pinned the job to this runner.
+            const sha256 = (app.build?.sha256 ?? app.sha256 ?? '').toLowerCase();
+            const path = localBuilds.get(sha256);
+            if (!path || !existsSync(path)) {
+                throw new AppNotAvailable(`the CI build ${sha256 || '(no sha256)'} is not on this runner`);
+            }
+            return { path, release: () => undefined };
+        }
+        default:
+            throw new AppNotAvailable(`unknown app install mode '${app.install}'`);
+    }
+}

package/dist/src/builds/ios-app.js

@@ -0,0 +1,99 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { buildKind, unquarantineArgv, unzip } from './unpack.js';
+/**
+ * iOS builds (contracts §I): `.ipa` for real devices, a zipped `.app` built with
+ * `-sdk iphonesimulator` for simulators. The runner decides from the device kind.
+ */
+export const IPA_ON_SIMULATOR = 'this build is an .ipa; simulators need a zipped .app built with -sdk iphonesimulator';
+export const SIMULATOR_APP_ON_DEVICE = 'this build is a simulator .app; real devices need an .ipa signed for your team';
+/** Whether a build file can be installed on a simulator or a real device, from its name. */
+export function iosBuildDecision(fileName, deviceKind) {
+    const kind = buildKind(fileName);
+    if (kind === 'ipa')
+        return deviceKind === 'simulator' ? { ok: false, message: IPA_ON_SIMULATOR } : { ok: true, kind: 'ipa' };
+    if (kind === 'app_zip' || kind === 'zip') {
+        return deviceKind === 'real' ? { ok: false, message: SIMULATOR_APP_ON_DEVICE } : { ok: true, kind: 'app_zip' };
+    }
+    return { ok: false, message: `'${basename(fileName)}' is not an iOS build; upload an .ipa (real devices) or a zipped .app (simulators)` };
+}
+/** Whether an unpacked `.app` was built for the simulator or for devices, from `CFBundleSupportedPlatforms`. */
+export function appPlatformFromPlatforms(platforms) {
+    if (!Array.isArray(platforms))
+        return null;
+    if (platforms.includes('iPhoneSimulator'))
+        return 'simulator';
+    if (platforms.includes('iPhoneOS'))
+        return 'device';
+    return null;
+}
+export function plutilPlatformsArgv(appDir) {
+    return ['plutil', '-extract', 'CFBundleSupportedPlatforms', 'json', '-o', '-', join(appDir, 'Info.plist')];
+}
+export function plutilExecutableArgv(appDir) {
+    return ['plutil', '-extract', 'CFBundleExecutable', 'raw', '-o', '-', join(appDir, 'Info.plist')];
+}
+function plutil(argv) {
+    const result = spawnSync(argv[0], argv.slice(1), { encoding: 'utf8', timeout: 20_000 });
+    return result.status === 0 ? result.stdout.trim() : null;
+}
+export function appPlatform(appDir) {
+    const out = plutil(plutilPlatformsArgv(appDir));
+    if (!out)
+        return null;
+    try {
+        return appPlatformFromPlatforms(JSON.parse(out));
+    }
+    catch {
+        return null;
+    }
+}
+/** The app's executable (its process name in the device log). */
+export function appExecutable(appDir) {
+    return plutil(plutilExecutableArgv(appDir)) || null;
+}
+/** The first `*.app` directory at the top of `dir` or one level below it (zips often wrap it in a folder). */
+export function findAppBundle(dir, list = readdirSync, isDir = defaultIsDir) {
+    const top = list(dir).filter((name) => !name.startsWith('__MACOSX'));
+    const direct = top.find((name) => name.endsWith('.app') && isDir(join(dir, name)));
+    if (direct)
+        return join(dir, direct);
+    for (const name of top) {
+        const path = join(dir, name);
+        if (!isDir(path))
+            continue;
+        const nested = list(path).find((child) => child.endsWith('.app') && isDir(join(path, child)));
+        if (nested)
+            return join(path, nested);
+    }
+    return null;
+}
+function defaultIsDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Unzips a simulator build into a private temp directory and returns its `.app`. */
+export function unpackAppZip(zip) {
+    const dir = mkdtempSync(join(tmpdir(), 'qa-ios-app-'));
+    const cleanup = () => rmSync(dir, { recursive: true, force: true });
+    try {
+        unzip(zip, dir);
+        const app = findAppBundle(dir);
+        if (!app || !existsSync(join(app, 'Info.plist')))
+            throw new Error('the zip holds no .app bundle');
+        // The user's own build: macOS would otherwise refuse to run a quarantined download.
+        const [cmd, ...args] = unquarantineArgv(app);
+        spawnSync(cmd, args, { stdio: 'ignore', timeout: 60_000 });
+        return { app, cleanup };
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
+}

package/dist/src/builds/unpack.js

@@ -0,0 +1,347 @@
+import { spawnSync } from 'node:child_process';
+import { accessSync, chmodSync, closeSync, constants, mkdirSync, mkdtempSync, openSync, readdirSync, readSync, realpathSync, rmSync, statSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, sep, win32 } from 'node:path';
+/** What a build file is, from its name. */
+export function buildKind(fileName) {
+    const lower = fileName.toLowerCase();
+    if (lower.endsWith('.apk'))
+        return 'apk';
+    if (lower.endsWith('.aab'))
+        return 'aab';
+    if (lower.endsWith('.ipa'))
+        return 'ipa';
+    if (lower.endsWith('.app.zip'))
+        return 'app_zip';
+    if (lower.endsWith('.zip'))
+        return 'zip';
+    if (lower.endsWith('.dmg'))
+        return 'dmg';
+    if (lower.endsWith('.appimage'))
+        return 'appimage';
+    if (lower.endsWith('.exe'))
+        return 'exe';
+    return 'unknown';
+}
+/**
+ * Windows' own bsdtar, which reads zips. Named by path because a GNU tar earlier on PATH (Git for
+ * Windows puts one there) cannot read zips and takes `C:` in a path for a remote host.
+ */
+export function windowsTar(env = process.env) {
+    return win32.join(env.SystemRoot ?? 'C:\\Windows', 'System32', 'tar.exe');
+}
+/** The fixed argv that extracts a zip into `dest` on this OS (bsdtar on macOS/Windows, unzip on Linux). */
+export function unzipArgv(archive, dest, platform = process.platform, env = process.env) {
+    if (platform === 'linux')
+        return ['unzip', '-q', '-o', archive, '-d', dest];
+    return [platform === 'win32' ? windowsTar(env) : 'tar', '-xf', archive, '-C', dest];
+}
+/** `hdiutil attach` argv for a read-only, hidden mount at `mountPoint` (macOS). */
+export function hdiutilAttachArgv(dmg, mountPoint) {
+    return ['hdiutil', 'attach', '-nobrowse', '-readonly', '-noautoopen', '-mountpoint', mountPoint, dmg];
+}
+export function hdiutilDetachArgv(mountPoint) {
+    return ['hdiutil', 'detach', '-force', mountPoint];
+}
+/** Removes the quarantine flag from the user's own build so macOS lets it launch (documented). */
+export function unquarantineArgv(path) {
+    return ['xattr', '-dr', 'com.apple.quarantine', path];
+}
+function run(argv, timeoutMs = 300_000) {
+    const result = spawnSync(argv[0], argv.slice(1), { stdio: ['ignore', 'ignore', 'pipe'], timeout: timeoutMs, windowsHide: true });
+    if (result.error)
+        throw new Error(`${argv[0]} could not run: ${result.error.message}`);
+    if (result.status !== 0) {
+        throw new Error(`${argv[0]} failed (exit ${result.status}): ${result.stderr?.toString('utf8').trim().split('\n').pop() ?? ''}`);
+    }
+}
+export function unzip(archive, dest) {
+    mkdirSync(dest, { recursive: true, mode: 0o700 });
+    run(unzipArgv(archive, dest));
+}
+/**
+ * The file a platform installs from a build. Android installs `.apk` files as they are;
+ * app bundles (`.aab`) need signing keys the runner does not have.
+ */
+export function androidInstallable(fileName) {
+    const kind = buildKind(fileName);
+    if (kind === 'apk')
+        return;
+    if (kind === 'aab')
+        throw new Error('Android App Bundles (.aab) cannot be installed directly; upload an .apk build');
+    throw new Error(`'${fileName}' is not an Android build; upload an .apk`);
+}
+export function desktopOs(platform = process.platform) {
+    if (platform === 'darwin')
+        return 'macos';
+    if (platform === 'win32')
+        return 'windows';
+    return 'linux';
+}
+/**
+ * The fixed argv that extracts a desktop zip: `ditto -x -k` on macOS (keeps the symlinks and
+ * permissions of `.app` frameworks), System32 `tar.exe -xf` on Windows 10+ (bsdtar), `unzip` on Linux.
+ */
+export function desktopUnzipArgv(archive, dest, os = desktopOs(), env = process.env) {
+    if (os === 'macos')
+        return ['ditto', '-x', '-k', archive, dest];
+    if (os === 'windows')
+        return [windowsTar(env), '-xf', archive, '-C', dest];
+    return ['unzip', '-q', '-o', archive, '-d', dest];
+}
+/** Copies an `.app` bundle with its symlinks, permissions and signature intact (macOS). */
+export function dittoCopyArgv(source, dest) {
+    return ['ditto', source, dest];
+}
+export class DesktopBuildError extends Error {
+}
+/** The build kinds an Electron job accepts, from the file name. */
+export function desktopBuildKind(fileName) {
+    const kind = buildKind(fileName);
+    if (kind === 'zip' || kind === 'app_zip')
+        return 'zip';
+    if (kind === 'dmg' || kind === 'appimage' || kind === 'exe')
+        return kind;
+    throw new DesktopBuildError(`'${basename(fileName)}' is not a desktop build; upload a .zip, .dmg, .AppImage or portable .exe`);
+}
+export const nodeDesktopFs = {
+    list: (path) => readdirSync(path).sort((a, b) => a.localeCompare(b)),
+    isDir: (path) => {
+        try {
+            return statSync(path).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    },
+    isFile: (path) => {
+        try {
+            return statSync(path).isFile();
+        }
+        catch {
+            return false;
+        }
+    },
+    isExecutable: (path) => {
+        if (process.platform === 'win32')
+            return true;
+        try {
+            accessSync(path, constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    isElf: (path) => {
+        let fd = null;
+        try {
+            fd = openSync(path, 'r');
+            const header = Buffer.alloc(4);
+            return readSync(fd, header, 0, 4, 0) === 4 && header.equals(ELF_MAGIC);
+        }
+        catch {
+            return false;
+        }
+        finally {
+            if (fd !== null)
+                closeSync(fd);
+        }
+    },
+    realpath: (path) => realpathSync(path),
+};
+const ELF_MAGIC = Buffer.from([0x7f, 0x45, 0x4c, 0x46]);
+/** Helpers Electron and Chromium ship next to the app binary; never the app itself. */
+const LINUX_HELPERS = new Set(['chrome-sandbox', 'chrome_crashpad_handler', 'crashpad_handler']);
+function isWindowsHelper(name) {
+    const lower = name.toLowerCase();
+    return lower.startsWith('uninstall') || /update.*\.exe$/.test(lower);
+}
+/** The entries to search: the root, or the single folder a zip wrapped everything in. */
+function searchRoots(root, fs) {
+    const entries = fs.list(root).filter((name) => !name.startsWith('__MACOSX') && !name.startsWith('.'));
+    const roots = [root];
+    if (entries.length === 1 && fs.isDir(join(root, entries[0])) && !entries[0].endsWith('.app'))
+        roots.push(join(root, entries[0]));
+    return roots;
+}
+/** `Foo.app/Contents/MacOS/<executable>`: the one named like the bundle, else the first executable file. */
+export function bundleExecutable(appDir, fs = nodeDesktopFs) {
+    const macos = join(appDir, 'Contents', 'MacOS');
+    if (!fs.isDir(macos))
+        return null;
+    const files = fs.list(macos).filter((name) => fs.isFile(join(macos, name)) && fs.isExecutable(join(macos, name)));
+    const named = basename(appDir).replace(/\.app$/i, '');
+    const pick = files.find((name) => name === named) ?? files[0];
+    return pick ? join(macos, pick) : null;
+}
+/**
+ * Finds the app's executable in an unpacked desktop build (contracts §K): macOS
+ * `*.app/Contents/MacOS/<executable>`; Windows the first `*.exe` not named `Uninstall*` or
+ * `*Update*.exe`; Linux an `.AppImage` or the first ELF executable. Each is looked for at the
+ * top level, then inside a single folder the archive wrapped the app in.
+ */
+export function detectExecutable(root, os, fs = nodeDesktopFs) {
+    for (const dir of searchRoots(root, fs)) {
+        const names = fs.list(dir);
+        if (os === 'macos') {
+            for (const name of names.filter((n) => n.toLowerCase().endsWith('.app') && fs.isDir(join(dir, n)))) {
+                const executable = bundleExecutable(join(dir, name), fs);
+                if (executable)
+                    return executable;
+            }
+        }
+        else if (os === 'windows') {
+            const exe = names.find((n) => n.toLowerCase().endsWith('.exe') && !isWindowsHelper(n) && fs.isFile(join(dir, n)));
+            if (exe)
+                return join(dir, exe);
+        }
+        else {
+            const appImage = names.find((n) => n.toLowerCase().endsWith('.appimage') && fs.isFile(join(dir, n)));
+            if (appImage)
+                return join(dir, appImage);
+            const elf = names.find((n) => {
+                const path = join(dir, n);
+                return !LINUX_HELPERS.has(n) && !/\.so(\.|$)/.test(n) && fs.isFile(path) && fs.isExecutable(path) && fs.isElf(path);
+            });
+            if (elf)
+                return join(dir, elf);
+        }
+    }
+    return null;
+}
+/**
+ * The environment's "Executable" override (`launch_activity`, contracts §K): a path relative
+ * to the unpacked build root. Absolute paths and `..` are refused; a `.app` names its bundle
+ * executable. The result must stay inside the root after resolving symlinks.
+ */
+export function executableOverride(root, relative, os, fs = nodeDesktopFs) {
+    const trimmed = relative.trim();
+    if (!trimmed)
+        throw new DesktopBuildError('the executable path is empty');
+    const parts = trimmed.split(/[\\/]+/).filter((part) => part !== '' && part !== '.');
+    if (isAbsolute(trimmed) || win32.isAbsolute(trimmed) || /^[A-Za-z]:/.test(trimmed) || trimmed.startsWith('/') || trimmed.startsWith('\\')) {
+        throw new DesktopBuildError(`the executable path '${trimmed}' must be relative to the build`);
+    }
+    if (parts.some((part) => part === '..') || parts.length === 0) {
+        throw new DesktopBuildError(`the executable path '${trimmed}' must stay inside the build (no '..')`);
+    }
+    let path = join(root, ...parts);
+    if (os === 'macos' && path.toLowerCase().endsWith('.app') && fs.isDir(path)) {
+        const inner = bundleExecutable(path, fs);
+        if (!inner)
+            throw new DesktopBuildError(`'${trimmed}' has no executable in Contents/MacOS`);
+        path = inner;
+    }
+    if (!fs.isFile(path))
+        throw new DesktopBuildError(`the executable '${trimmed}' is not in the build`);
+    const realRoot = fs.realpath(root);
+    const real = fs.realpath(path);
+    if (real !== realRoot && !real.startsWith(realRoot.endsWith(sep) ? realRoot : `${realRoot}${sep}`)) {
+        throw new DesktopBuildError(`the executable '${trimmed}' points outside the build`);
+    }
+    if (!fs.isExecutable(path))
+        throw new DesktopBuildError(`'${trimmed}' is not executable`);
+    return path;
+}
+/**
+ * Unpacks a desktop build file into a private temp directory and finds its executable:
+ * `.zip` extracted, `.dmg` mounted read-only and its `.app` copied out, `.AppImage` and
+ * portable `.exe` used in place. On macOS the quarantine flag is removed (the user's own build).
+ */
+export function unpackDesktopBuild(file, override, deps = {}) {
+    const os = deps.os ?? desktopOs();
+    const fs = deps.fs ?? nodeDesktopFs;
+    const runArgv = deps.run ?? ((argv) => run(argv));
+    const remove = deps.remove ?? ((path) => rmSync(path, { recursive: true, force: true }));
+    const kind = desktopBuildKind(file);
+    if (kind === 'appimage' || kind === 'exe') {
+        if (kind === 'appimage' && os !== 'linux')
+            throw new DesktopBuildError('.AppImage builds run on Linux runners only');
+        if (kind === 'exe' && os !== 'windows')
+            throw new DesktopBuildError('.exe builds run on Windows runners only');
+        // The cached copy is private to the runner (0600); it needs the executable bit to start.
+        if (kind === 'appimage')
+            (deps.chmod ?? chmodSync)(file, 0o700);
+        return { executable: file, root: dirname(file), tempDir: null, cleanup: () => undefined };
+    }
+    const dir = (deps.tempDir ?? (() => mkdtempSync(join(tmpdir(), 'qa-desktop-app-'))))();
+    const cleanup = () => remove(dir);
+    try {
+        if (kind === 'zip') {
+            runArgv(desktopUnzipArgv(file, dir, os));
+        }
+        else {
+            if (os !== 'macos')
+                throw new DesktopBuildError('.dmg builds run on macOS runners only');
+            const mount = join(dir, '.mount');
+            mkdirSync(mount, { recursive: true, mode: 0o700 });
+            runArgv(hdiutilAttachArgv(file, mount));
+            try {
+                const app = fs.list(mount).find((name) => name.toLowerCase().endsWith('.app') && fs.isDir(join(mount, name)));
+                if (!app)
+                    throw new DesktopBuildError('the .dmg holds no .app bundle');
+                runArgv(dittoCopyArgv(join(mount, app), join(dir, app)));
+            }
+            finally {
+                try {
+                    runArgv(hdiutilDetachArgv(mount));
+                }
+                catch {
+                    // A busy mount detaches with -force; nothing more to do here.
+                }
+                remove(mount);
+            }
+        }
+        if (os === 'macos') {
+            try {
+                runArgv(unquarantineArgv(dir));
+            }
+            catch {
+                // Not quarantined, or xattr missing: launching tells the real story.
+            }
+        }
+        const executable = override ? executableOverride(dir, override, os, fs) : detectExecutable(dir, os, fs);
+        if (!executable)
+            throw new DesktopBuildError(noExecutableMessage(os));
+        return { executable, root: dir, tempDir: dir, cleanup };
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
+}
+export function noExecutableMessage(os) {
+    if (os === 'macos')
+        return 'the build holds no .app bundle with an executable in Contents/MacOS (set the executable path in the environment)';
+    if (os === 'windows')
+        return 'the build holds no .exe at its top level (set the executable path in the environment)';
+    return 'the build holds no .AppImage or executable at its top level (set the executable path in the environment)';
+}
+/**
+ * An app installed at a path on the runner (`install: path`, contracts §K): the executable, a
+ * `.app` bundle, or a directory to search like an unpacked build.
+ */
+export function localDesktopApp(path, override, os = desktopOs(), fs = nodeDesktopFs) {
+    if (!isAbsolute(path) && !win32.isAbsolute(path))
+        throw new DesktopBuildError(`the app path '${path}' must be absolute`);
+    if (fs.isDir(path)) {
+        if (override)
+            return executableOverride(path, override, os, fs);
+        if (os === 'macos' && path.toLowerCase().replace(/[\\/]+$/, '').endsWith('.app')) {
+            const executable = bundleExecutable(path, fs);
+            if (!executable)
+                throw new DesktopBuildError(`${path} has no executable in Contents/MacOS`);
+            return executable;
+        }
+        const found = detectExecutable(path, os, fs);
+        if (!found)
+            throw new DesktopBuildError(noExecutableMessage(os));
+        return found;
+    }
+    if (!fs.isFile(path))
+        throw new DesktopBuildError(`the app ${path} does not exist on this runner`);
+    if (!fs.isExecutable(path))
+        throw new DesktopBuildError(`the app ${path} is not executable`);
+    return path;
+}

package/dist/src/capabilities.js

@@ -0,0 +1,93 @@
+import { hostname } from 'node:os';
+import { registryAvailability } from './drivers/registry.js';
+import { findFfmpeg } from './devices/screen-record.js';
+import { playwrightVersion } from './version.js';
+export const PROTOCOL_VERSION = 2;
+export function osName(platform) {
+    if (platform === 'darwin')
+        return 'macos';
+    if (platform === 'win32')
+        return 'windows';
+    return platform;
+}
+export function hostInfo() {
+    return { os: osName(process.platform), arch: process.arch, hostname: hostname(), node: process.versions.node };
+}
+/** Asks every driver whether its platform is ready on this host. */
+export async function detect(registry, host) {
+    const devices = [];
+    const labels = new Set();
+    const unavailable = {};
+    for (const [platform, availability] of await registryAvailability(registry, host)) {
+        devices.push(...availability.devices);
+        const usable = availability.devices.filter((device) => device.state === 'available' || device.can_boot);
+        for (const label of [...availability.labels, ...deriveLabels(usable)])
+            labels.add(label);
+        if (!availability.ok)
+            unavailable[platform] = availability.reasons;
+    }
+    return { devices, labels: [...labels], unavailable };
+}
+/**
+ * Labels the server derives from devices too (contracts §C, §H): `web-chromium` for a web
+ * device; the platform name plus `<platform>-<kind>` for mobile devices (`android`,
+ * `android-emulator`, `android-real`, `ios`, `ios-simulator`, `ios-real`); the platform
+ * name for desktop host devices.
+ */
+export function deriveLabels(devices) {
+    const labels = new Set();
+    for (const device of devices) {
+        if (device.platform === 'web') {
+            labels.add('web-chromium');
+        }
+        else if (device.platform === 'android' || device.platform === 'ios') {
+            labels.add(device.platform);
+            if (device.kind !== 'host')
+                labels.add(`${device.platform}-${device.kind}`);
+        }
+        else {
+            labels.add(device.platform);
+        }
+    }
+    return [...labels];
+}
+/**
+ * Protocol features by platform present; `sessions` = this runner handles device sessions
+ * (contracts §H3). Web and Electron record webm (Playwright, contracts §K); mobile records mp4;
+ * Tauri records no video and adds no feature beyond sessions (contracts §L). Native macOS and
+ * Windows apps carry the Appium log on failed steps and record mp4 only with ffmpeg (contracts §M).
+ */
+export function featuresFor(platforms, options = {}) {
+    const features = [];
+    if (platforms.length > 0)
+        features.push('sessions');
+    if (platforms.includes('web') || platforms.includes('electron'))
+        features.push('video_webm', 'step_debug');
+    if (platforms.some((platform) => platform === 'android' || platform === 'ios')) {
+        features.push('video_mp4', 'device_log');
+        if (!features.includes('step_debug'))
+            features.push('step_debug');
+    }
+    if (platforms.some((platform) => platform === 'macos' || platform === 'windows')) {
+        if (!features.includes('step_debug'))
+            features.push('step_debug');
+        if (options.ffmpeg && !features.includes('video_mp4'))
+            features.push('video_mp4');
+    }
+    return features;
+}
+export function buildCapabilities(devices, host, extraTools = {}, options = { ffmpeg: findFfmpeg() !== null }) {
+    const platforms = [...new Set(devices.map((device) => device.platform))];
+    const tools = { node: host.node };
+    const playwright = playwrightVersion();
+    if (playwright)
+        tools.playwright = playwright;
+    Object.assign(tools, extraTools);
+    return {
+        protocol: PROTOCOL_VERSION,
+        features: featuresFor(platforms, options),
+        platforms,
+        tools,
+        devices,
+    };
+}

package/dist/src/ci/builds.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { createReadStream, statSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { ExitCode, ExitError, messageOf } from '../errors.js';
+/** Hashes a build file while streaming it. */
+export async function describeBuildFile(path) {
+    let size;
+    try {
+        const stats = statSync(path);
+        if (!stats.isFile())
+            throw new Error('not a file');
+        size = stats.size;
+    }
+    catch (error) {
+        throw new ExitError(ExitCode.usage, `the build ${path} cannot be read: ${messageOf(error)}`);
+    }
+    const hash = createHash('sha256');
+    await pipeline(createReadStream(path), hash);
+    return { path, file_name: basename(path), sha256: hash.digest('hex'), size_bytes: size };
+}
+const CONTENT_TYPES = {
+    '.apk': 'application/vnd.android.package-archive',
+    '.ipa': 'application/octet-stream',
+    '.zip': 'application/zip',
+    '.dmg': 'application/x-apple-diskimage',
+    '.exe': 'application/vnd.microsoft.portable-executable',
+    '.msi': 'application/x-msi',
+    '.appimage': 'application/octet-stream',
+};
+export function contentTypeFor(fileName) {
+    return CONTENT_TYPES[extname(fileName).toLowerCase()] ?? 'application/octet-stream';
+}
+/** A project flag is an id when it is all digits, otherwise a project key. */
+export function projectSelector(project) {
+    if (!project)
+        return {};
+    return /^\d+$/.test(project) ? { project_id: Number(project) } : { project_key: project };
+}
+/** create → presigned PUT → finish; falls back to the server relay when the PUT fails. */
+export async function uploadBuild(client, options) {
+    const { file, log } = options;
+    const contentType = contentTypeFor(file.file_name);
+    const selector = projectSelector(options.project);
+    const meta = Object.fromEntries(Object.entries(options.meta ?? {}).filter(([, value]) => value));
+    const created = await client.createBuild({
+        ...(selector.project_id !== undefined ? { project: selector.project_id } : {}),
+        ...(selector.project_key !== undefined ? { project_key: selector.project_key } : {}),
+        platform: options.platform,
+        file_name: file.file_name,
+        size_bytes: file.size_bytes,
+        sha256: file.sha256,
+        content_type: contentType,
+        ...meta,
+    });
+    const buildId = created.build.id;
+    log.info('build created', { build_id: buildId, sha256: file.sha256, size_bytes: file.size_bytes });
+    if (!options.relay && created.upload?.url) {
+        try {
+            await client.putPresigned(created.upload, file.path, contentType);
+            return await client.finishBuild(buildId);
+        }
+        catch (error) {
+            log.warn('direct upload failed, sending the build through the server', { build_id: buildId, error: messageOf(error) });
+        }
+    }
+    return client.relayBuild(buildId, file.path, file.file_name, contentType);
+}