@leera.io/qa-runner 1.1.0 → 1.4.0

package/README.md

@@ -197,7 +197,8 @@ ready and `4` when something marked `[fail]` needs fixing, with the command that
 The runner advertises phones (`android`, `android-real`), running emulators and emulators that
 exist but are off (`android`, `android-emulator`); an emulator is booted when a job needs it and
 stays booted. Each job installs the build, clears the app's data, records an MP4 when asked
-(runs over 3 minutes need `ffmpeg` on `PATH`) and captures the app's logcat warnings, errors and
+(runs over 3 minutes are joined with ffmpeg, which the runner downloads when none is installed)
+and captures the app's logcat warnings, errors and
 crashes per step. The same devices serve **device sessions**, in which an AI agent explores the
 app over MCP before writing a script. Details: [Android](https://github.com/leera-app/leera-qa-runner/blob/main/docs/test-runners.md#android),
 [device sessions](https://github.com/leera-app/leera-qa-runner/blob/main/docs/qa-automation-authoring.md#device-sessions).

package/dist/src/builds/download.js

@@ -11,9 +11,10 @@ export class BuildIntegrityError extends Error {
  */
 export async function obtainBuild(options) {
     const { cache, build } = options;
+    const what = options.what ?? `build ${build.id}`;
     const expected = build.sha256.toLowerCase();
     if (!SHA256_RE.test(expected))
-        throw new BuildIntegrityError(`build ${build.id} has no valid sha256`);
+        throw new BuildIntegrityError(`${what} has no valid sha256`);
     const release = cache.pin(expected);
     try {
         const cached = cache.get(expected);
@@ -21,11 +22,11 @@ export async function obtainBuild(options) {
             return { path: cached, sha256: expected, fromCache: true, release };
         const info = await options.getUrl();
         if (info.sha256.toLowerCase() !== expected) {
-            throw new BuildIntegrityError(`the server offered build ${build.id} with digest ${info.sha256}, not ${expected}`);
+            throw new BuildIntegrityError(`the server offered ${what} with digest ${info.sha256}, not ${expected}`);
         }
         const url = new URL(info.url);
         if (url.protocol !== 'https:' && url.protocol !== 'http:')
-            throw new Error(`refusing to download a build from ${url.protocol} URL`);
+            throw new Error(`refusing to download ${what} from a ${url.protocol} URL`);
         const temp = cache.tempPath(info.file_name);
         try {
             const response = await (options.fetchImpl ?? fetch)(url, {
@@ -33,22 +34,22 @@ export async function obtainBuild(options) {
                 signal: AbortSignal.timeout(options.timeoutMs ?? 30 * 60_000),
             });
             if (!response.ok || !response.body)
-                throw new Error(`the build download failed with HTTP ${response.status}`);
+                throw new Error(`the download of ${what} failed with HTTP ${response.status}`);
             const hash = createHash('sha256');
             let received = 0;
             const limit = info.size_bytes;
             await writeResponseBody(response.body, temp, (chunk) => {
                 received += chunk.length;
                 if (received > limit)
-                    throw new BuildIntegrityError(`the build download is larger than the expected ${limit} bytes`);
+                    throw new BuildIntegrityError(`the download of ${what} is larger than the expected ${limit} bytes`);
                 hash.update(chunk);
                 options.onProgress?.(received, limit);
             });
             if (received !== limit)
-                throw new BuildIntegrityError(`the build download has ${received} bytes, expected ${limit}`);
+                throw new BuildIntegrityError(`the download of ${what} has ${received} bytes, expected ${limit}`);
             const digest = hash.digest('hex');
             if (digest !== expected)
-                throw new BuildIntegrityError(`the downloaded build's sha256 ${digest} does not match ${expected}`);
+                throw new BuildIntegrityError(`the sha256 ${digest} of the downloaded ${what} does not match ${expected}`);
             const path = cache.put(expected, info.file_name || build.file_name, temp);
             cache.prune();
             return { path, sha256: expected, fromCache: false, release };

package/dist/src/capabilities.js

@@ -1,6 +1,6 @@
 import { hostname } from 'node:os';
 import { registryAvailability } from './drivers/registry.js';
-import { findFfmpeg } from './devices/screen-record.js';
+import { ffmpegAvailable } from './devices/ffmpeg.js';
 import { playwrightVersion } from './version.js';
 export const PROTOCOL_VERSION = 2;
 export function osName(platform) {
@@ -53,11 +53,15 @@ export function deriveLabels(devices) {
 }
 /**
  * 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).
+ * (contracts §H3). Web and Electron record webm (Playwright, contracts §K); mobile records mp4.
+ * Tauri, native macOS and Windows apps record mp4 with ffmpeg, which the runner downloads when
+ * none is installed (contracts §L, §M); native apps also carry the Appium log on failed steps.
  * `data_refs` = this runner fills test data, API URL and job placeholders on every platform
  * (contracts §Q); the server gives such scripts only to runners labelled `data-refs`.
+ * `credential_otp` = this runner types the account's fixed one-time code (`{{credential.otp}}`);
+ * the server gives such scripts only to runners labelled `credential-otp`.
+ * `test_files` = this runner downloads or generates a job's test files and hands them to the app
+ * (contracts §S); the server gives such scripts only to runners labelled `test-files`.
  */
 export function featuresFor(platforms, options = {}) {
     const features = [];
@@ -73,13 +77,14 @@ export function featuresFor(platforms, options = {}) {
     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');
     }
-    features.push('data_refs');
+    if (options.ffmpeg && platforms.some((platform) => platform === 'tauri' || platform === 'macos' || platform === 'windows') && !features.includes('video_mp4')) {
+        features.push('video_mp4');
+    }
+    features.push('data_refs', 'credential_otp', 'test_files');
     return features;
 }
-export function buildCapabilities(devices, host, extraTools = {}, options = { ffmpeg: findFfmpeg() !== null }) {
+export function buildCapabilities(devices, host, extraTools = {}, options = { ffmpeg: ffmpegAvailable() }) {
     const platforms = [...new Set(devices.map((device) => device.platform))];
     const tools = { node: host.node };
     const playwright = playwrightVersion();

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

@@ -7,11 +7,12 @@ 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 { downloadFfmpeg, ffmpegBuild, ffmpegCheckDetail, findFfmpeg } from '../../devices/ffmpeg.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]
+const usage = `Usage: leera-qa-runner setup browsers|android|ios|electron|tauri|macos|windows|ffmpeg [options]
 
 Installs what a platform needs. This version supports:
   browsers            Chromium for web jobs (into the runner home unless PLAYWRIGHT_BROWSERS_PATH is set)
@@ -30,6 +31,10 @@ Installs what a platform needs. This version supports:
   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
+  ffmpeg              Downloads the ffmpeg video recording uses (Tauri, Windows and macOS apps,
+                      real iPhones, Android cases over 3 minutes) into the runner home, checked by
+                      sha256. Jobs download it themselves when it is missing; an ffmpeg on the
+                      PATH is used instead
 
 Options for android:
   --install-sdk       Install platform-tools, emulator, build-tools and a system image with the
@@ -90,6 +95,9 @@ export function setupTauri(io, paths, lookup = {}) {
             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',
+            '',
+            `Video: ${ffmpegCheckDetail(io.env, io.platform).detail}. Recording the screen needs Screen Recording`,
+            'permission for the app that runs the runner (System Settings → Privacy & Security → Screen Recording).',
         ].join('\n'));
         return settings.macosPlugin ? ExitCode.ok : ExitCode.environmentNotReady;
     }
@@ -132,11 +140,40 @@ export function setupTauri(io, paths, lookup = {}) {
             '  2. leera-qa-runner config set tauri.native_driver_path C:\\path\\to\\msedgedriver.exe',
         ].join('\n'));
     }
+    io.stdout(`Video: ${ffmpegCheckDetail(io.env, io.platform).detail}.`);
     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;
 }
+/**
+ * `setup ffmpeg`: downloads the pinned ffmpeg build video recording uses into the runner home,
+ * or reports the one already there (on PATH or downloaded). Exit 4 when this OS and CPU have no
+ * build to download, 1 when the download fails.
+ */
+export async function setupFfmpeg(io, paths, options = {}) {
+    const found = findFfmpeg(io.env, io.platform, undefined, paths);
+    if (found) {
+        io.stdout(`ffmpeg: ${found}`);
+        return ExitCode.ok;
+    }
+    const arch = options.arch ?? process.arch;
+    const build = options.build ?? ffmpegBuild(io.platform, arch);
+    if (!build) {
+        io.stderr(`There is no ffmpeg build to download for ${io.platform} ${arch}: install ffmpeg on the PATH to record video.`);
+        return ExitCode.environmentNotReady;
+    }
+    io.stdout(`Downloading ffmpeg (${Math.round(build.size / 1_000_000)} MB) from ${build.url} ...`);
+    try {
+        ensureHome(paths);
+        io.stdout(`ffmpeg: ${await downloadFfmpeg(paths, { ...options, platform: io.platform, arch })}`);
+        return ExitCode.ok;
+    }
+    catch (error) {
+        io.stderr(`ffmpeg could not be downloaded: ${error instanceof Error ? error.message : String(error)}`);
+        return ExitCode.error;
+    }
+}
 export const command = {
-    summary: 'Install platform tools (browsers, android, ios, electron, tauri, macos, windows)',
+    summary: 'Install platform tools (browsers, android, ios, electron, tauri, macos, windows, ffmpeg)',
     usage,
     async run(args, io) {
         const { positionals, values } = parseArgs({
@@ -185,6 +222,8 @@ export const command = {
             return setupMacos(io, homePaths(io.env));
         if (what === 'windows')
             return setupWindows(io, homePaths(io.env), { install: values.install ?? false });
+        if (what === 'ffmpeg')
+            return setupFfmpeg(io, homePaths(io.env));
         if (what === 'all') {
             throw usageError(`'setup all' is not available in this runner version; set up one platform at a time`, usage);
         }

package/dist/src/client.js

@@ -110,6 +110,10 @@ export class RunnerClient {
             ...(owner.jobId !== undefined ? { job_id: owner.jobId } : { session_id: owner.sessionId }),
         }));
     }
+    /** A short-lived download URL for a stored test file of a running job (contracts §S). */
+    async testFileDownloadUrl(testFileId, jobId) {
+        return this.expect(await this.json('/api/v1/qa/runner/files/download-url', { test_file_id: testFileId, job_id: jobId }));
+    }
     json(path, body) {
         return this.request(path, {
             method: 'POST',

package/dist/src/devices/android/adb.js

@@ -245,6 +245,14 @@ export class Adb {
     async pidof(serial, pkg) {
         return parsePidof(await this.shell(serial, ['pidof', assertPackage(pkg)], 10_000).catch(() => ''));
     }
+    /** Copies a file of this machine to the device (no shell: the remote path is one argv item). */
+    async push(serial, local, remote, timeoutMs = 300_000) {
+        await this.run(['-s', assertSerial(serial), 'push', local, remote], timeoutMs);
+    }
+    /** Asks the device to add a file it holds to its media index, so photo pickers list it. */
+    async scanMedia(serial, remote) {
+        await this.shell(serial, mediaScanArgs(remote), 15_000);
+    }
     /** Drops adb's connection to a device so it reconnects (the fix for one stuck `offline`). */
     async reconnect(serial) {
         await this.run(['-s', assertSerial(serial), 'reconnect'], 15_000).catch(() => undefined);
@@ -253,3 +261,17 @@ export class Adb {
         await this.run(['-s', assertSerial(serial), 'emu', 'kill'], 15_000).catch(() => undefined);
     }
 }
+/** The Download folder on the device, where the system file picker finds added files. */
+export const DEVICE_DOWNLOADS = '/sdcard/Download';
+/** Quotes one word for the device's shell. */
+export function deviceShellQuote(text) {
+    return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * `am broadcast` of MEDIA_SCANNER_SCAN_FILE for a file on the device; the file URI is
+ * percent-encoded and quoted, since `adb shell` hands its words to the device's shell.
+ */
+export function mediaScanArgs(remote) {
+    const uri = `file://${encodeURI(remote)}`;
+    return ['am', 'broadcast', '-a', 'android.intent.action.MEDIA_SCANNER_SCAN_FILE', '-d', deviceShellQuote(uri)];
+}

package/dist/src/devices/ffmpeg.js

@@ -0,0 +1,135 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { chmodSync, createReadStream, createWriteStream, existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+import { writeResponseBody } from '../download.js';
+import { homePaths } from '../home.js';
+import { findOnPath } from './desktop.js';
+/**
+ * The ffmpeg video recording needs (contracts §L, §M): whole-screen capture for Tauri, Windows
+ * and macOS app jobs, and what Appium uses for real iPhones and for Android cases over 3 minutes.
+ * An ffmpeg on PATH is used as it is. Otherwise the runner downloads a static build once into its
+ * home, checked by size and sha256: the `ffmpeg-static` project's GitHub release, which carries
+ * the builds of johnvansickle.com (Linux), gyan.dev (Windows) and a macOS build, all GPL. The
+ * runner does not ship ffmpeg itself.
+ */
+export const FFMPEG_RELEASE = 'b6.1.1';
+const RELEASE_URL = `https://github.com/eugeneware/ffmpeg-static/releases/download/${FFMPEG_RELEASE}`;
+/** How long a job waits for the first download on a machine. */
+export const FFMPEG_JOB_DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
+/** Pinned builds by `<platform>-<arch>` (sizes and digests from the GitHub release). */
+export const FFMPEG_BUILDS = {
+    'darwin-arm64': { url: `${RELEASE_URL}/ffmpeg-darwin-arm64.gz`, sha256: '8923876afa8db5585022d7860ec7e589af192f441c56793971276d450ed3bbfa', size: 19_246_198 },
+    'darwin-x64': { url: `${RELEASE_URL}/ffmpeg-darwin-x64.gz`, sha256: '929b375c1182d956c51f7ac25e0b2b0411fb01f6f407aa15c9758efeb4242106', size: 25_296_431 },
+    'linux-arm64': { url: `${RELEASE_URL}/ffmpeg-linux-arm64.gz`, sha256: '754a678672298bc68156adff58aa7385a592c2b30b1d0ae8750c45c915c4bac0', size: 25_568_691 },
+    'linux-x64': { url: `${RELEASE_URL}/ffmpeg-linux-x64.gz`, sha256: 'bfe8a8fc511530457b528c48d77b5737527b504a3797a9bc4866aeca69c2dffa', size: 29_354_986 },
+    'win32-x64': { url: `${RELEASE_URL}/ffmpeg-win32-x64.gz`, sha256: '8883a3dffbd0a16cf4ef95206ea05283f78908dbfb118f73c83f4951dcc06d77', size: 29_581_307 },
+};
+/** The pinned build for this OS and CPU (Windows on Arm runs the x64 one), or null. */
+export function ffmpegBuild(platform = process.platform, arch = process.arch) {
+    const key = platform === 'win32' && arch === 'arm64' ? 'win32-x64' : `${platform}-${arch}`;
+    return FFMPEG_BUILDS[key] ?? null;
+}
+function executableName(platform) {
+    return platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg';
+}
+/** Where the downloaded ffmpeg lives: one directory per pinned release, so an update fetches its own. */
+export function managedFfmpegDir(paths) {
+    return join(paths.ffmpeg, FFMPEG_RELEASE);
+}
+export function managedFfmpegPath(paths, platform = process.platform) {
+    return join(managedFfmpegDir(paths), executableName(platform));
+}
+/** ffmpeg on PATH, else the one the runner downloaded; null when there is neither. */
+export function findFfmpeg(env = process.env, platform = process.platform, exists, paths = homePaths(env)) {
+    const onPath = findOnPath(executableName(platform), env, exists);
+    if (onPath)
+        return onPath;
+    const managed = managedFfmpegPath(paths, platform);
+    return (exists ?? existsSync)(managed) ? managed : null;
+}
+/** Whether jobs can record with ffmpeg: one is there, or this OS and CPU have a build to download. */
+export function ffmpegAvailable(env = process.env, platform = process.platform, arch = process.arch) {
+    return findFfmpeg(env, platform) !== null || ffmpegBuild(platform, arch) !== null;
+}
+const downloads = new Map();
+/**
+ * Downloads the pinned build for this machine into the runner home and returns its path; one
+ * already there is kept. Callers at the same time share one download. Throws when this OS and CPU
+ * have no build, or the download fails or does not match its pin.
+ */
+export function downloadFfmpeg(paths, options = {}) {
+    const target = managedFfmpegPath(paths, options.platform ?? process.platform);
+    const pending = downloads.get(target);
+    if (pending)
+        return pending;
+    const download = fetchBuild(target, options).finally(() => downloads.delete(target));
+    downloads.set(target, download);
+    return download;
+}
+async function fetchBuild(target, options) {
+    if (existsSync(target))
+        return target;
+    const platform = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    const build = options.build ?? ffmpegBuild(platform, arch);
+    if (!build)
+        throw new Error(`there is no ffmpeg build to download for ${platform} ${arch}; install ffmpeg on the PATH`);
+    const dir = dirname(target);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tag = `${process.pid}-${randomBytes(4).toString('hex')}`;
+    const gzip = join(dir, `.download-${tag}.gz`);
+    const unpacked = join(dir, `.download-${tag}`);
+    try {
+        options.log?.info('downloading ffmpeg for video recording', { url: build.url, bytes: build.size });
+        const response = await (options.fetch ?? fetch)(build.url, { redirect: 'follow', signal: AbortSignal.timeout(options.timeoutMs ?? 10 * 60_000) });
+        if (!response.ok || !response.body)
+            throw new Error(`the ffmpeg download failed with HTTP ${response.status}`);
+        const hash = createHash('sha256');
+        const size = await writeResponseBody(response.body, gzip, (chunk) => hash.update(chunk));
+        const digest = hash.digest('hex');
+        if (size !== build.size || digest !== build.sha256) {
+            throw new Error(`the ffmpeg download does not match its pin (${size} bytes, sha256 ${digest})`);
+        }
+        await pipeline(createReadStream(gzip), createGunzip(), createWriteStream(unpacked, { mode: 0o755 }));
+        if (platform !== 'win32')
+            chmodSync(unpacked, 0o755);
+        renameSync(unpacked, target);
+        options.log?.info('ffmpeg downloaded', { path: target });
+        return target;
+    }
+    finally {
+        rmSync(gzip, { force: true });
+        rmSync(unpacked, { force: true });
+    }
+}
+/**
+ * The ffmpeg to record with: one on PATH or already downloaded, else the pinned build, downloaded
+ * now (the first video job on a machine waits for it). Null, with a warning, when there is none.
+ */
+export async function ensureFfmpeg(options = {}) {
+    const env = options.env ?? process.env;
+    const paths = options.paths ?? homePaths(env);
+    const platform = options.platform ?? process.platform;
+    const found = findFfmpeg(env, platform, undefined, paths);
+    if (found)
+        return found;
+    try {
+        return await downloadFfmpeg(paths, { timeoutMs: FFMPEG_JOB_DOWNLOAD_TIMEOUT_MS, ...options, platform });
+    }
+    catch (error) {
+        options.log?.warn('video is not recorded: ffmpeg could not be downloaded', { error: error instanceof Error ? error.message : String(error) });
+        return null;
+    }
+}
+/** The doctor line for video on a platform that records with ffmpeg. */
+export function ffmpegCheckDetail(env, platform, arch = process.arch) {
+    const found = findFfmpeg(env, platform);
+    if (found)
+        return { ok: true, detail: `ffmpeg ${found}` };
+    if (ffmpegBuild(platform, arch)) {
+        return { ok: true, detail: 'ffmpeg is downloaded on the first job with video (or now with `leera-qa-runner setup ffmpeg`)' };
+    }
+    return { ok: false, detail: `ffmpeg is not installed and there is no build to download for ${platform} ${arch}; jobs record no video` };
+}

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

@@ -3,6 +3,7 @@ import { existsSync, mkdtempSync, renameSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
+import { findFfmpeg } from '../ffmpeg.js';
 import { assertSimUdid } from './simctl.js';
 /**
  * Records a simulator's screen with `simctl io recordVideo` (H.264). simctl always writes a
@@ -27,17 +28,17 @@ export function majorBrand(header) {
 }
 /**
  * Rewrites a QuickTime recording as an MP4 container in place, with `avconvert` (macOS) or else
- * ffmpeg when present. Returns how, or null when neither worked (the QuickTime file is kept;
- * browsers and the server still accept it as video/mp4).
+ * ffmpeg (on PATH or the runner's download) when present. Returns how, or null when neither
+ * worked (the QuickTime file is kept; browsers and the server still accept it as video/mp4).
  */
-export function remuxToMp4(file, run = runQuiet) {
+export function remuxToMp4(file, run = runQuiet, ffmpeg = findFfmpeg() ?? 'ffmpeg') {
     const temp = `${file}.remux.mp4`;
-    for (const [tool, argv] of [
-        ['avconvert', avconvertRemuxArgv(file, temp)],
-        ['ffmpeg', ffmpegRemuxArgv(file, temp)],
+    for (const [tool, command, argv] of [
+        ['avconvert', 'avconvert', avconvertRemuxArgv(file, temp)],
+        ['ffmpeg', ffmpeg, ffmpegRemuxArgv(file, temp)],
     ]) {
         rmSync(temp, { force: true });
-        if (run(tool, [...argv]) && existsSync(temp) && statSync(temp).size > 0) {
+        if (run(command, [...argv]) && existsSync(temp) && statSync(temp).size > 0) {
             renameSync(temp, file);
             return tool;
         }

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

@@ -53,6 +53,21 @@ export function simctlBootstatusArgv(udid) {
 export function simctlShutdownArgv(udid) {
     return ['simctl', 'shutdown', assertSimUdid(udid)];
 }
+/** Adds photos and videos to the simulator's Photos library. */
+export function simctlAddMediaArgv(udid, paths) {
+    return ['simctl', 'addmedia', assertSimUdid(udid), ...paths];
+}
+/** The app's data container on the simulator (its `Documents` folder is inside). */
+export function simctlDataContainerArgv(udid, bundleId) {
+    return ['simctl', 'get_app_container', assertSimUdid(udid), assertBundleId(bundleId), 'data'];
+}
+/** File types `simctl addmedia` puts into the Photos library. */
+export const SIMULATOR_MEDIA_EXTENSIONS = ['jpg', 'jpeg', 'png', 'heic', 'gif', 'mp4', 'mov', 'm4v'];
+/** Whether a file goes to the Photos library (by its extension). */
+export function isSimulatorMedia(fileName) {
+    const ext = fileName.toLowerCase().split('.').pop() ?? '';
+    return fileName.includes('.') && SIMULATOR_MEDIA_EXTENSIONS.includes(ext);
+}
 /** An executable name that is safe inside a log predicate string. */
 export const PROCESS_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9 ._+-]{0,99}$/;
 /**
@@ -178,6 +193,18 @@ export class Simctl {
     async shutdown(udid) {
         await this.run(simctlShutdownArgv(udid), 60_000).catch(() => undefined);
     }
+    async addMedia(udid, paths) {
+        await this.run(simctlAddMediaArgv(udid, paths), 120_000);
+    }
+    /** The app's data container, or null when the app is not installed on the simulator. */
+    async dataContainer(udid, bundleId) {
+        try {
+            return (await this.run(simctlDataContainerArgv(udid, bundleId), 20_000)).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
     async executableName(udid, bundleId) {
         try {
             return parseAppinfoExecutable(await this.run(simctlAppinfoArgv(udid, bundleId), 20_000));

package/dist/src/devices/macos.js

@@ -8,7 +8,7 @@ import { ensureHome } from '../home.js';
 import { runTool } from './android/adb.js';
 import { appiumDriverListArgv } from './android/setup.js';
 import { developerDir, isCommandLineToolsOnly, xcodeInfo } from './ios/wda.js';
-import { findFfmpeg } from './screen-record.js';
+import { ffmpegCheckDetail } from './ffmpeg.js';
 /**
  * Native macOS apps (contracts §M): Appium's Mac2 driver, which builds and runs
  * WebDriverAgentMac (an XCTest UI-testing bundle) with Xcode on the first session. XCTest needs
@@ -110,8 +110,8 @@ export const ACCESSIBILITY_STEPS = [
     '     when macOS asks.',
     '  3. The first session enables Automation Mode; macOS may ask for an administrator password on this',
     '     screen. Keep the Mac logged in and unlocked while jobs run (a locked screen blocks UI testing).',
-    '  4. Optional: install ffmpeg (`brew install ffmpeg`) and allow Screen Recording for the same app to',
-    '     record job videos.',
+    '  4. For job videos: System Settings → Privacy & Security → Screen Recording: allow the same app. The',
+    '     runner downloads the ffmpeg it records with on the first job with video.',
 ];
 /** Whether this Mac can run macOS app jobs now: Xcode, Appium with Mac2, no recorded Accessibility refusal. */
 export async function macosReadiness(paths, platform = process.platform) {
@@ -172,10 +172,10 @@ export async function macosChecks(env, paths, platform = process.platform) {
     else if (mode) {
         checks.push({ id: 'macos.automation_mode', title: 'macOS apps: Automation Mode', status: 'ok', detail: mode.enabled ? 'enabled' : 'enabled on demand without authentication' });
     }
-    const ffmpeg = findFfmpeg(env, platform);
-    checks.push(ffmpeg
-        ? { id: 'macos.video', title: 'macOS apps: video', status: 'ok', detail: `ffmpeg ${ffmpeg} (needs Screen Recording permission)` }
-        : { id: 'macos.video', title: 'macOS apps: video', status: 'warn', detail: 'ffmpeg is not installed; jobs record no video', fix: 'brew install ffmpeg' });
+    const video = ffmpegCheckDetail(env, platform);
+    checks.push(video.ok
+        ? { id: 'macos.video', title: 'macOS apps: video', status: 'ok', detail: `${video.detail} (needs Screen Recording permission)` }
+        : { id: 'macos.video', title: 'macOS apps: video', status: 'warn', detail: video.detail, fix: 'brew install ffmpeg' });
     return checks;
 }
 /**
@@ -240,8 +240,7 @@ export async function setupMacos(io, paths) {
         io.stdout('');
         io.stdout('Automation Mode is disabled and asks for an administrator password when a session enables it: be at the Mac for the first job.');
     }
-    if (!findFfmpeg(io.env, io.platform))
-        io.stdout('ffmpeg is not installed: macOS app jobs record no video.');
+    io.stdout(`Video: ${ffmpegCheckDetail(io.env, io.platform).detail}.`);
     io.stdout('');
     io.stdout(ok ? 'macOS apps are set up. Check with `leera-qa-runner doctor --platform macos`.' : 'macOS setup is incomplete; see the messages above.');
     return ok ? ExitCode.ok : ExitCode.environmentNotReady;

package/dist/src/devices/mp4.js

@@ -0,0 +1,80 @@
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+/** The boxes that follow each other in [from, to); stops at the first that does not fit. */
+function* boxes(read, from, to) {
+    let at = from;
+    while (at + 8 <= to) {
+        const head = read(at, 8);
+        if (!head)
+            return;
+        let size = head.readUInt32BE(0);
+        let header = 8;
+        if (size === 1) {
+            const large = read(at + 8, 8);
+            if (!large)
+                return;
+            size = Number(large.readBigUInt64BE(0));
+            header = 16;
+        }
+        else if (size === 0) {
+            size = to - at;
+        }
+        if (size < header || at + size > to)
+            return;
+        yield { type: head.toString('latin1', 4, 8), start: at + header, end: at + size };
+        at += size;
+    }
+}
+/**
+ * An MP4's length in seconds, from its movie header (`moov/mvhd`), as players and `ffmpeg -i`
+ * report it; null for a file that is not an MP4 (a webm), has no header (a recording cut short) or
+ * gives no length.
+ */
+export function mp4Seconds(file) {
+    let fd;
+    try {
+        fd = openSync(file, 'r');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const size = fstatSync(fd).size;
+        const read = (at, length) => {
+            if (at + length > size)
+                return null;
+            const buffer = Buffer.alloc(length);
+            return readSync(fd, buffer, 0, length, at) === length ? buffer : null;
+        };
+        const top = boxes(read, 0, size);
+        const first = top.next();
+        if (first.done || first.value.type !== 'ftyp')
+            return null;
+        for (const box of top) {
+            if (box.type !== 'moov')
+                continue;
+            for (const child of boxes(read, box.start, box.end)) {
+                if (child.type !== 'mvhd')
+                    continue;
+                // version 0: 32-bit times, timescale at 12 and duration at 16; version 1: 64-bit, at 20 and 24.
+                const header = read(child.start, Math.min(32, child.end - child.start));
+                const v1 = header?.[0] === 1;
+                if (!header || header.length < (v1 ? 32 : 20))
+                    return null;
+                const timescale = header.readUInt32BE(v1 ? 20 : 12);
+                const duration = v1 ? header.readBigUInt64BE(24) : BigInt(header.readUInt32BE(16));
+                const unknown = v1 ? 0xffffffffffffffffn : 0xffffffffn;
+                if (timescale === 0 || duration === 0n || duration === unknown)
+                    return null;
+                return Number(duration) / timescale;
+            }
+            return null;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeSync(fd);
+    }
+}