@leera.io/qa-runner 1.0.0

package/dist/src/service/launchd.js

@@ -0,0 +1,85 @@
+import { join } from 'node:path';
+import { SERVICE_LABEL } from './names.js';
+function escapeXml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/**
+ * A LaunchAgent, not a daemon: simulators, app windows, permissions and the signing
+ * keychain live in the user's GUI session.
+ */
+export function launchdPlist(spec) {
+    const args = spec.argv.map((arg) => `    <string>${escapeXml(arg)}</string>`).join('\n');
+    const env = Object.entries(spec.env)
+        .map(([key, value]) => `    <key>${escapeXml(key)}</key>\n    <string>${escapeXml(value)}</string>`)
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env}
+  </dict>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(spec.home)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(join(spec.logDir, 'service.out.log'))}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(join(spec.logDir, 'service.err.log'))}</string>
+</dict>
+</plist>
+`;
+}
+export function launchdBackend(uid) {
+    const domain = `gui/${uid}`;
+    const target = `${domain}/${SERVICE_LABEL}`;
+    const definitionPath = (spec) => join(spec.userHome, 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+    return {
+        kind: 'launchd',
+        definitionPath,
+        plan(action, spec) {
+            const plist = definitionPath(spec);
+            switch (action) {
+                case 'install':
+                    return {
+                        writes: [{ path: plist, contents: launchdPlist(spec) }],
+                        commands: [
+                            { argv: ['launchctl', 'bootout', target], ignoreFailure: true },
+                            { argv: ['launchctl', 'bootstrap', domain, plist] },
+                        ],
+                    };
+                case 'uninstall':
+                    return { commands: [{ argv: ['launchctl', 'bootout', target], ignoreFailure: true }], removes: [plist] };
+                case 'start':
+                    return {
+                        commands: [
+                            // Loading an already loaded agent fails harmlessly; kickstart then starts it.
+                            { argv: ['launchctl', 'bootstrap', domain, plist], ignoreFailure: true },
+                            { argv: ['launchctl', 'kickstart', target] },
+                        ],
+                    };
+                case 'stop':
+                    // KeepAlive would restart a killed process, so stopping unloads the agent.
+                    return { commands: [{ argv: ['launchctl', 'bootout', target] }] };
+                case 'restart':
+                    return { commands: [{ argv: ['launchctl', 'kickstart', '-k', target] }] };
+                case 'status':
+                    return { commands: [{ argv: ['launchctl', 'print', target] }] };
+            }
+        },
+    };
+}

package/dist/src/service/names.js

@@ -0,0 +1,2 @@
+export const SERVICE_LABEL = 'io.leera.qa-runner';
+export const SERVICE_NAME = 'leera-qa-runner';

package/dist/src/service/schtasks.js

@@ -0,0 +1,128 @@
+import { join } from 'node:path';
+import { SERVICE_NAME } from './names.js';
+function escapeXml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/** Quotes one argument the way CommandLineToArgvW reads it back. */
+export function windowsQuote(arg) {
+    if (arg !== '' && !/[\s"]/.test(arg))
+        return arg;
+    let out = '"';
+    let backslashes = 0;
+    for (const char of arg) {
+        if (char === '\\') {
+            backslashes++;
+        }
+        else if (char === '"') {
+            out += `${'\\'.repeat(backslashes * 2 + 1)}"`;
+            backslashes = 0;
+        }
+        else {
+            out += '\\'.repeat(backslashes) + char;
+            backslashes = 0;
+        }
+    }
+    return `${out}${'\\'.repeat(backslashes * 2)}"`;
+}
+/**
+ * A task that starts at logon in the user's interactive session with limited rights
+ * (the XML form of `schtasks /SC ONLOGON /IT /RL LIMITED`), restarts on failure and
+ * has no time limit — settings the plain `schtasks` flags cannot express.
+ */
+export function scheduledTaskXml(spec, user) {
+    const [command, ...args] = spec.argv;
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>QA test runner</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${escapeXml(user)}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${escapeXml(user)}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>999</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${escapeXml(command ?? '')}</Command>
+      <Arguments>${escapeXml(args.map(windowsQuote).join(' '))}</Arguments>
+      <WorkingDirectory>${escapeXml(spec.home)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+/** schtasks reads task XML as UTF-16 with a byte order mark. */
+export function utf16le(text) {
+    return Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(text.replace(/\r?\n/g, '\r\n'), 'utf16le')]);
+}
+export function schtasksBackend(user) {
+    const definitionPath = (spec) => join(spec.home, 'service', `${SERVICE_NAME}.xml`);
+    return {
+        kind: 'schtasks',
+        definitionPath,
+        plan(action, spec) {
+            const xml = definitionPath(spec);
+            switch (action) {
+                case 'install':
+                    return {
+                        writes: [{ path: xml, contents: utf16le(scheduledTaskXml(spec, user)) }],
+                        commands: [
+                            { argv: ['schtasks', '/Create', '/TN', SERVICE_NAME, '/XML', xml, '/F'] },
+                            { argv: ['schtasks', '/Run', '/TN', SERVICE_NAME] },
+                        ],
+                    };
+                case 'uninstall':
+                    return {
+                        commands: [
+                            { argv: ['schtasks', '/End', '/TN', SERVICE_NAME], ignoreFailure: true },
+                            { argv: ['schtasks', '/Delete', '/TN', SERVICE_NAME, '/F'] },
+                        ],
+                        removes: [xml],
+                    };
+                case 'start':
+                    return { commands: [{ argv: ['schtasks', '/Run', '/TN', SERVICE_NAME] }] };
+                case 'stop':
+                    return { commands: [{ argv: ['schtasks', '/End', '/TN', SERVICE_NAME] }] };
+                case 'restart':
+                    return {
+                        commands: [
+                            { argv: ['schtasks', '/End', '/TN', SERVICE_NAME], ignoreFailure: true },
+                            { argv: ['schtasks', '/Run', '/TN', SERVICE_NAME] },
+                        ],
+                    };
+                case 'status':
+                    return { commands: [{ argv: ['schtasks', '/Query', '/TN', SERVICE_NAME, '/V', '/FO', 'LIST'] }] };
+            }
+        },
+    };
+}

package/dist/src/service/systemd.js

@@ -0,0 +1,65 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { SERVICE_NAME } from './names.js';
+const UNIT = `${SERVICE_NAME}.service`;
+/** Quotes one word for a unit file: double quotes, with `\`, `"`, `%` and `$` escaped. */
+export function systemdQuote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%').replace(/\$/g, '$$$$')}"`;
+}
+export function systemdUnit(spec) {
+    const env = Object.entries(spec.env)
+        .map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}`)
+        .join('\n');
+    return `[Unit]
+Description=QA test runner
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${spec.argv.map(systemdQuote).join(' ')}
+WorkingDirectory=${systemdQuote(spec.home)}
+${env}
+Restart=always
+RestartSec=10
+KillSignal=SIGTERM
+TimeoutStopSec=60
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function systemdBackend(configHome = process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), '.config')) {
+    const definitionPath = (_spec) => join(configHome, 'systemd', 'user', UNIT);
+    const ctl = (...args) => ['systemctl', '--user', ...args];
+    return {
+        kind: 'systemd',
+        definitionPath,
+        plan(action, spec) {
+            switch (action) {
+                case 'install':
+                    return {
+                        writes: [{ path: definitionPath(spec), contents: systemdUnit(spec) }],
+                        commands: [
+                            { argv: ctl('daemon-reload') },
+                            { argv: ctl('enable', '--now', UNIT) },
+                            // Keeps the user's services running while they are logged out; may need an administrator.
+                            { argv: ['loginctl', 'enable-linger'], ignoreFailure: true },
+                        ],
+                        notes: ['If the runner should keep running after you log out and `loginctl enable-linger` failed, ask an administrator to run `loginctl enable-linger <user>`.'],
+                    };
+                case 'uninstall':
+                    return {
+                        commands: [{ argv: ctl('disable', '--now', UNIT), ignoreFailure: true }, { argv: ctl('daemon-reload'), ignoreFailure: true }],
+                        removes: [definitionPath(spec)],
+                    };
+                case 'start':
+                case 'stop':
+                case 'restart':
+                    return { commands: [{ argv: ctl(action, UNIT) }] };
+                case 'status':
+                    return { commands: [{ argv: ctl('status', '--no-pager', UNIT) }] };
+            }
+        },
+    };
+}

package/dist/src/session/commands.js

@@ -0,0 +1,165 @@
+/**
+ * Local validation of device-session commands (plan §4, §7.5; contracts §H3). The server
+ * validates too; the runner checks again so a malformed command becomes an error result
+ * instead of reaching a driver.
+ */
+/** Commands that only exist in sessions; every other type must be a DSL action of the platform. */
+export const SESSION_TYPES = ['snapshot', 'find', 'source', 'back', 'home', 'end', 'tap', 'type', 'swipe'];
+/** Never executed, whatever the platform says (no shell, scripts or file access in sessions). */
+const FORBIDDEN_TYPES = new Set(['execute_script', 'execute', 'shell', 'eval', 'upload', 'pull_file', 'push_file']);
+export const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
+export const WAIT_FOR_MAX_MS = 60_000;
+export const MIN_TIMEOUT_MS = 100;
+export const MAX_TIMEOUT_MS = 120_000;
+/** Time a driver gets beyond the action timeout to report its own timeout before the loop gives up. */
+export const TIMEOUT_GRACE_MS = 5_000;
+const DIRECTIONS = ['up', 'down', 'left', 'right'];
+const REF = /^[a-z][a-z0-9]{0,15}$/i;
+export class CommandError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function isSessionType(type) {
+    return SESSION_TYPES.includes(type);
+}
+/** Checks a command's shape; `actions` are the DSL action types the session's driver performs. */
+export function validateCommand(raw, actions) {
+    try {
+        return { ok: true, command: check(raw, actions) };
+    }
+    catch (error) {
+        if (error instanceof CommandError)
+            return { ok: false, code: error.code, message: error.message };
+        throw error;
+    }
+}
+function check(raw, actions) {
+    if (!isObject(raw))
+        throw invalid('the command must be an object');
+    const command = raw;
+    if (typeof command.type !== 'string' || command.type.length === 0)
+        throw invalid('command.type is required');
+    const type = command.type;
+    if (FORBIDDEN_TYPES.has(type))
+        throw new CommandError('unsupported', `'${type}' is not allowed in a device session`);
+    if (command.timeout_ms !== undefined && !inRange(command.timeout_ms, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS)) {
+        throw invalid(`command.timeout_ms must be between ${MIN_TIMEOUT_MS} and ${MAX_TIMEOUT_MS}`);
+    }
+    if (command.screenshot !== undefined && typeof command.screenshot !== 'boolean') {
+        throw invalid('command.screenshot must be true or false');
+    }
+    if (command.ref !== undefined && (typeof command.ref !== 'string' || !REF.test(command.ref))) {
+        throw invalid('command.ref must be a ref from a snapshot, such as "e4"');
+    }
+    if (command.target !== undefined)
+        checkTarget(command.target, 'command.target');
+    switch (type) {
+        case 'snapshot':
+            if (command.depth !== undefined && !inRange(command.depth, 1, 1_000))
+                throw invalid('command.depth must be a positive number');
+            if (command.include_hidden !== undefined && typeof command.include_hidden !== 'boolean') {
+                throw invalid('command.include_hidden must be true or false');
+            }
+            checkMaxChars(command);
+            return command;
+        case 'source':
+            checkMaxChars(command);
+            return command;
+        case 'find':
+            if (command.target === undefined)
+                throw invalid("'find' needs a target");
+            return command;
+        case 'back':
+        case 'home':
+        case 'end':
+            return command;
+        case 'tap': {
+            const given = [command.ref !== undefined, command.at !== undefined, command.target !== undefined].filter(Boolean).length;
+            if (given !== 1)
+                throw invalid("'tap' needs exactly one of ref, at or target");
+            if (command.at !== undefined) {
+                const at = command.at;
+                if (!isObject(at) || !inRange(at.x, 0, 100_000) || !inRange(at.y, 0, 100_000)) {
+                    throw invalid("'tap' at needs non-negative x and y");
+                }
+            }
+            return command;
+        }
+        case 'type':
+            if ((command.ref === undefined) === (command.target === undefined))
+                throw invalid("'type' needs exactly one of ref or target");
+            if (typeof command.value !== 'string')
+                throw invalid("'type' needs a string value");
+            if (command.clear !== undefined && typeof command.clear !== 'boolean')
+                throw invalid('command.clear must be true or false');
+            return command;
+        case 'swipe':
+            checkSwipe(command);
+            return command;
+        default:
+            if (!actions.includes(type))
+                throw new CommandError('unsupported', `'${type}' is not an action this session's device supports`);
+            if (command.ref !== undefined && command.target !== undefined)
+                throw invalid(`'${type}' takes a ref or a target, not both`);
+            if (type === 'swipe' || type === 'scroll_to')
+                checkSwipe(command, type === 'scroll_to');
+            return command;
+    }
+}
+function checkSwipe(command, optionalDirection = false) {
+    if (command.ref !== undefined && command.target !== undefined)
+        throw invalid(`'${command.type}' takes a ref or a target, not both`);
+    if (command.direction === undefined && optionalDirection)
+        return;
+    if (!DIRECTIONS.includes(command.direction)) {
+        throw invalid(`'${command.type}' needs a direction: ${DIRECTIONS.join(', ')}`);
+    }
+    if (command.distance !== undefined && !inRange(command.distance, 0.1, 1))
+        throw invalid('command.distance must be between 0.1 and 1');
+}
+function checkMaxChars(command) {
+    if (command.max_chars !== undefined && !inRange(command.max_chars, 1, 1_000_000)) {
+        throw invalid('command.max_chars must be a positive number');
+    }
+}
+function checkTarget(target, at) {
+    if (!isObject(target))
+        throw invalid(`${at} must be an object`);
+    if ('locate' in target)
+        throw invalid(`${at}.locate is not allowed`);
+    if (target.fallbacks !== undefined) {
+        if (!Array.isArray(target.fallbacks) || target.fallbacks.length > 5)
+            throw invalid(`${at}.fallbacks must be a list of at most 5 targets`);
+        target.fallbacks.forEach((fallback, i) => {
+            if (isObject(fallback) && fallback.fallbacks !== undefined)
+                throw invalid(`${at}.fallbacks[${i}] cannot have fallbacks`);
+            checkTarget(fallback, `${at}.fallbacks[${i}]`);
+        });
+    }
+}
+/**
+ * The time a command's action may take: `timeout_ms` or the session default (30 s), at most
+ * the default for ordinary actions and at most 60 s for `wait_for`.
+ */
+export function actionTimeoutMs(command, defaultMs = DEFAULT_COMMAND_TIMEOUT_MS) {
+    const requested = command.timeout_ms ?? defaultMs;
+    const cap = command.type === 'wait_for' ? Math.max(defaultMs, WAIT_FOR_MAX_MS) : defaultMs;
+    return Math.max(MIN_TIMEOUT_MS, Math.min(requested, cap));
+}
+/** The loop's hard limit for one command: the action timeout plus a grace for the driver to give up by itself. */
+export function hardTimeoutMs(command, defaultMs = DEFAULT_COMMAND_TIMEOUT_MS, graceMs = TIMEOUT_GRACE_MS) {
+    const extra = command.type === 'wait' && typeof command.ms === 'number' ? Math.min(command.ms, 30_000) : 0;
+    return actionTimeoutMs(command, defaultMs) + extra + graceMs;
+}
+function invalid(message) {
+    return new CommandError('failed', message);
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function inRange(value, min, max) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= min && value <= max;
+}

package/dist/src/session/execute.js

@@ -0,0 +1,232 @@
+import { Blocked, NotFound, Unsupported } from '../drivers/driver.js';
+import { clampMaxChars, emptyScreen, toSnapshotResult } from '../drivers/snapshot/format.js';
+import { TemplateError } from '../template.js';
+import { actionTimeoutMs, CommandError, DEFAULT_COMMAND_TIMEOUT_MS, hardTimeoutMs, validateCommand, } from './commands.js';
+export const MAX_LOG_LINES = 50;
+export const MAX_LOG_CHARS = 500;
+/** Command fields that are not part of the action a driver performs. */
+const COMMAND_ONLY_FIELDS = new Set(['id', 'seq', 'ref', 'at', 'screenshot', 'depth', 'include_hidden', 'max_chars']);
+class TimedOut extends Error {
+}
+/**
+ * Executes session commands on one driver. Refs resolve only against the last snapshot
+ * this executor produced; anything else is `stale_ref` ("take a new snapshot").
+ */
+export class SessionExecutor {
+    driver;
+    commandTimeoutMs;
+    redact;
+    graceMs;
+    last = null;
+    constructor(driver, options = {}) {
+        this.driver = driver;
+        this.commandTimeoutMs = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+        this.redact = options.redact ?? ((text) => text);
+        this.graceMs = options.timeoutGraceMs;
+    }
+    get lastSnapshot() {
+        return this.last;
+    }
+    /** Takes a snapshot outside any command (after launch) so the first refs exist. */
+    async prime() {
+        this.last = await this.driver.snapshot({});
+    }
+    async execute(raw) {
+        const started = Date.now();
+        const result = {
+            ok: true,
+            error: null,
+            duration_ms: 0,
+            screen: emptyScreen(),
+            snapshot: null,
+            find: null,
+            target_used: null,
+            suggested_target: null,
+            logs: [],
+        };
+        let end = false;
+        const validation = validateCommand(raw, this.driver.capabilities.actions);
+        if (!validation.ok) {
+            result.ok = false;
+            result.error = { code: validation.code, message: validation.message };
+        }
+        else {
+            const command = validation.command;
+            end = command.type === 'end';
+            try {
+                await withTimeout(this.perform(command, result), hardTimeoutMs(command, this.commandTimeoutMs, this.graceMs));
+            }
+            catch (error) {
+                result.ok = false;
+                result.error = { code: classify(error), message: this.redact(firstLine(error)) };
+            }
+        }
+        const wantsScreenshot = raw?.screenshot !== false;
+        result.screen = await this.screen();
+        result.logs = this.logs();
+        const screenshot = wantsScreenshot ? await this.driver.screenshot().catch(() => null) : null;
+        result.duration_ms = Date.now() - started;
+        return { result, screenshot, end };
+    }
+    async perform(command, result) {
+        const actions = this.driver.capabilities.actions;
+        const timeout = actionTimeoutMs(command, this.commandTimeoutMs);
+        switch (command.type) {
+            case 'snapshot': {
+                const snapshot = await this.driver.snapshot({
+                    ...(command.depth !== undefined ? { depth: command.depth } : {}),
+                    ...(command.include_hidden !== undefined ? { includeHidden: command.include_hidden } : {}),
+                    ...(command.max_chars !== undefined ? { maxChars: command.max_chars } : {}),
+                });
+                this.last = snapshot;
+                result.snapshot = toSnapshotResult({ ...snapshot, text: this.redact(snapshot.text) });
+                return;
+            }
+            case 'source': {
+                const source = this.redact(await this.driver.source());
+                const max = clampMaxChars(command.max_chars);
+                result.snapshot = { text: source.slice(0, max), refs: {}, element_count: 0, truncated: source.length > max };
+                return;
+            }
+            case 'find': {
+                const target = command.target;
+                const found = await this.driver.find(target);
+                const known = this.last?.refs ?? {};
+                result.find = { count: found.count, refs: (found.refs ?? []).filter((ref) => ref in known) };
+                result.target_used = target;
+                return;
+            }
+            case 'end':
+                return;
+            case 'back':
+            case 'home': {
+                const hook = command.type === 'back' ? this.driver.back : this.driver.home;
+                if (hook)
+                    await hook.call(this.driver);
+                else if (actions.includes('press'))
+                    await this.driver.run({ type: 'press', key: command.type, timeout_ms: timeout });
+                else
+                    throw new Unsupported(`'${command.type}' is not available on ${this.driver.platform}`);
+                return;
+            }
+            case 'tap': {
+                if (command.at) {
+                    if (!this.driver.tapAt)
+                        throw new Unsupported(`tapping at coordinates is not available on ${this.driver.platform}`);
+                    await this.driver.tapAt(command.at.x, command.at.y);
+                    return;
+                }
+                const type = pick(actions, ['tap', 'click'], 'tap', this.driver.platform);
+                await this.runAction({ type, timeout_ms: timeout }, command, result);
+                return;
+            }
+            case 'type': {
+                const type = pick(actions, ['type', 'fill'], 'type', this.driver.platform);
+                const action = { type, value: command.value ?? '', timeout_ms: timeout };
+                if (type === 'type' && command.clear !== undefined)
+                    action.clear = command.clear;
+                await this.runAction(action, command, result);
+                return;
+            }
+            case 'swipe': {
+                const type = pick(actions, ['swipe'], 'swipe', this.driver.platform);
+                const action = { type, timeout_ms: timeout };
+                if (command.direction)
+                    action.direction = command.direction;
+                if (command.distance !== undefined)
+                    action.distance = command.distance;
+                await this.runAction(action, command, result, true);
+                return;
+            }
+            default: {
+                const action = { type: command.type };
+                for (const [key, value] of Object.entries(command)) {
+                    if (!COMMAND_ONLY_FIELDS.has(key))
+                        action[key] = value;
+                }
+                action.timeout_ms = timeout;
+                await this.runAction(action, command, result, true);
+            }
+        }
+    }
+    /** Resolves `ref` or `target` into the action and runs it. */
+    async runAction(action, command, result, targetOptional = false) {
+        if (command.ref !== undefined) {
+            const ref = this.last?.refs[command.ref];
+            if (!ref) {
+                throw new CommandError('stale_ref', `ref ${command.ref} is not in the last snapshot; take a new snapshot`);
+            }
+            const suggest = ref.suggest;
+            action.target = { ...suggest, locate: ref.locate };
+            result.target_used = suggest;
+            result.suggested_target = suggest;
+        }
+        else if (command.target !== undefined) {
+            action.target = command.target;
+            result.target_used = command.target;
+        }
+        else if (!targetOptional) {
+            throw new CommandError('failed', `'${command.type}' needs a ref or a target`);
+        }
+        await this.driver.run(action);
+    }
+    async screen() {
+        if (!this.driver.screen)
+            return emptyScreen();
+        try {
+            return await this.driver.screen();
+        }
+        catch {
+            return emptyScreen();
+        }
+    }
+    logs() {
+        let lines;
+        try {
+            lines = this.driver.drainLogs?.() ?? [];
+        }
+        catch {
+            return [];
+        }
+        return lines.slice(-MAX_LOG_LINES).map((line) => this.redact(line).slice(0, MAX_LOG_CHARS));
+    }
+}
+function pick(actions, candidates, name, platform) {
+    const found = candidates.find((candidate) => actions.includes(candidate));
+    if (!found)
+        throw new Unsupported(`'${name}' is not available on ${platform}`);
+    return found;
+}
+/** Maps what a driver threw to the result's error code. */
+export function classify(error) {
+    if (error instanceof CommandError)
+        return error.code;
+    if (error instanceof TimedOut)
+        return 'timeout';
+    if (error instanceof Unsupported)
+        return 'unsupported';
+    if (error instanceof NotFound)
+        return 'not_found';
+    const message = error instanceof Error ? error.message : String(error);
+    if (/\bTimeout \d+ms exceeded\b|timed out/i.test(message))
+        return 'timeout';
+    if (error instanceof Blocked || error instanceof TemplateError)
+        return 'failed';
+    return 'failed';
+}
+async function withTimeout(promise, ms) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new TimedOut(`the command timed out after ${Math.round(ms / 1000)} s`)), ms);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function firstLine(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (message.split('\n')[0] ?? '').slice(0, 500);
+}