@leera.io/qa-runner 1.0.0

package/dist/src/log.js

@@ -0,0 +1,69 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+const ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
+export const LOG_MAX_BYTES = 20 * 1024 * 1024;
+export const LOG_MAX_FILES = 5;
+/** Moves `file` to `file.1`, `file.1` to `file.2`, … keeping at most `maxFiles` old files. */
+export function rotate(file, maxFiles) {
+    const oldest = `${file}.${maxFiles}`;
+    if (existsSync(oldest))
+        rmSync(oldest, { force: true });
+    for (let i = maxFiles - 1; i >= 1; i--) {
+        const from = `${file}.${i}`;
+        if (existsSync(from))
+            renameSync(from, `${file}.${i + 1}`);
+    }
+    if (existsSync(file))
+        renameSync(file, `${file}.1`);
+}
+export function createLogger(options = {}) {
+    const mode = options.console ?? 'json';
+    const threshold = ORDER[options.level ?? 'info'];
+    const maxBytes = options.maxBytes ?? LOG_MAX_BYTES;
+    const maxFiles = options.maxFiles ?? LOG_MAX_FILES;
+    const stdout = options.stdout ?? ((line) => console.log(line));
+    const stderr = options.stderr ?? ((line) => console.error(line));
+    let fileBroken = false;
+    if (options.file)
+        mkdirSync(dirname(options.file), { recursive: true, mode: 0o700 });
+    const write = (level, message, fields = {}) => {
+        if (ORDER[level] < threshold)
+            return;
+        const line = JSON.stringify({ time: new Date().toISOString(), level, message, ...fields });
+        if (mode === 'json') {
+            if (level === 'error')
+                stderr(line);
+            else
+                stdout(line);
+        }
+        else if (mode === 'pretty') {
+            const extra = Object.entries(fields)
+                .map(([key, value]) => `${key}=${typeof value === 'string' ? value : JSON.stringify(value)}`)
+                .join(' ');
+            const text = `${new Date().toLocaleTimeString()} ${level.toUpperCase().padEnd(5)} ${message}${extra ? ` ${extra}` : ''}`;
+            if (level === 'error' || level === 'warn')
+                stderr(text);
+            else
+                stdout(text);
+        }
+        if (options.file && !fileBroken) {
+            try {
+                if (existsSync(options.file) && statSync(options.file).size >= maxBytes)
+                    rotate(options.file, maxFiles);
+                appendFileSync(options.file, `${line}\n`, { mode: 0o600 });
+            }
+            catch (error) {
+                fileBroken = true;
+                stderr(`could not write the log file ${options.file}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    };
+    return {
+        debug: (message, fields) => write('debug', message, fields),
+        info: (message, fields) => write('info', message, fields),
+        warn: (message, fields) => write('warn', message, fields),
+        error: (message, fields) => write('error', message, fields),
+    };
+}
+/** A logger that drops everything; for tests. */
+export const silentLogger = { debug() { }, info() { }, warn() { }, error() { } };

package/dist/src/runner.js

@@ -0,0 +1,498 @@
+import { readFile, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { buildCapabilities, detect, hostInfo } from './capabilities.js';
+import { ApiError, RunnerClient } from './client.js';
+import { loadFileConfig, resolveConfig } from './config.js';
+import { DeviceManager, INVENTORY_REFRESH_MS } from './devices/manager.js';
+import { BROWSER_DEVICE_ID, isPlatform } from './devices/types.js';
+import { createRegistry } from './drivers/registry.js';
+import { BrowserPool } from './drivers/web-playwright.js';
+import { ExitCode, ExitError, messageOf } from './errors.js';
+import { createDriver, executeClaimedJob, jobContext, sessionContext } from './executor.js';
+import { homePaths, readJsonFile, writePrivateFile } from './home.js';
+import { redactor } from './template.js';
+import { runSession } from './session/loop.js';
+import { isSessionClaim } from './types.js';
+import { localDay } from './update/check.js';
+import { compareVersions, RUNNER_VERSION } from './version.js';
+const MAX_BACKOFF_MS = 60_000;
+/** The server's limit for a video upload. */
+const MAX_VIDEO_BYTES = 50 * 1024 * 1024;
+/** Registration is idempotent; repeating it keeps metadata (devices, version) fresh. */
+const REREGISTER_MS = 5 * 60_000;
+/** Device lists flap while an emulator boots; wait this long after the last change before registering again. */
+const REREGISTER_DEBOUNCE_MS = 3_000;
+/** Registers, claims jobs while devices have free slots, runs them and reports back. */
+export class Runner {
+    config;
+    deps;
+    stopping = false;
+    wake = new Set();
+    running = new Map();
+    registration = null;
+    startedAt = new Date().toISOString();
+    stopController = new AbortController();
+    /** When the advertised devices last changed and have not been registered yet. */
+    devicesChangedAt = null;
+    /** The newest version the server reported; cached in state.json for `update --check`. */
+    latestVersion = null;
+    /** The local day the update notice was last logged (kept across restarts in state.json). */
+    updateNoticeDay = null;
+    constructor(config, deps) {
+        this.config = config;
+        this.deps = deps;
+        if (deps.statePath) {
+            try {
+                const previous = readJsonFile(deps.statePath);
+                if (typeof previous?.latest_version === 'string')
+                    this.latestVersion = previous.latest_version;
+                if (typeof previous?.update_notice_day === 'string')
+                    this.updateNoticeDay = previous.update_notice_day;
+            }
+            catch {
+                // A damaged state file is rewritten on the next registration.
+            }
+        }
+    }
+    /** Remembers the server's latest version and logs, once per day, when it is newer than this runner. */
+    noteLatestVersion(latest, current) {
+        if (!latest?.trim())
+            return;
+        this.latestVersion = latest.trim();
+        if (compareVersions(this.latestVersion, current) <= 0)
+            return;
+        const today = (this.deps.today ?? localDay)();
+        if (this.updateNoticeDay === today)
+            return;
+        this.updateNoticeDay = today;
+        this.deps.log.info('an update is available: run `leera-qa-runner update`', { version: current, latest_version: this.latestVersion });
+    }
+    get isStopping() {
+        return this.stopping;
+    }
+    /** Stops claiming; running jobs stop after their current action. */
+    stop() {
+        if (this.stopping)
+            return;
+        this.stopping = true;
+        this.stopController.abort();
+        this.deps.log.info('stopping after the current step');
+        for (const wake of this.wake)
+            wake();
+    }
+    async run() {
+        const { client, devices, log } = this.deps;
+        let registration = await this.register();
+        if (!registration)
+            return;
+        let registeredAt = Date.now();
+        const active = new Set();
+        let claimedOnce = false;
+        const debounceMs = this.deps.reregisterDebounceMs ?? REREGISTER_DEBOUNCE_MS;
+        devices.startRefresh(this.deps.inventory ?? (async () => (await detect(this.deps.registry, this.deps.host)).devices), () => {
+            this.devicesChangedAt = Date.now();
+            log.info('devices changed', { devices: devices.capabilityDevices().map((device) => device.id) });
+        }, (error) => log.warn('device inventory refresh failed', { error: messageOf(error) }), this.deps.inventoryRefreshMs ?? INVENTORY_REFRESH_MS);
+        try {
+            while (!this.stopping && !(this.config.once && claimedOnce)) {
+                const changedAt = this.devicesChangedAt;
+                const changed = changedAt !== null && Date.now() - changedAt >= debounceMs;
+                if (changed || Date.now() - registeredAt > REREGISTER_MS) {
+                    this.devicesChangedAt = null;
+                    const again = await this.register();
+                    if (!again)
+                        break;
+                    registration = again;
+                    registeredAt = Date.now();
+                }
+                const accept = devices.accept();
+                if (accept.length === 0) {
+                    // Every slot is busy: wait for a job to finish (or a stop).
+                    await this.pause(registration.poll_seconds * 1_000, active);
+                    continue;
+                }
+                let claim;
+                try {
+                    claim = await client.claim(registration.runner_id, { accept, runId: this.config.runId });
+                }
+                catch (error) {
+                    if (error instanceof ApiError && (error.status === 401 || error.status === 403))
+                        throw tokenRejected(error);
+                    if (error instanceof ApiError && error.status === 400) {
+                        const again = await this.register();
+                        if (!again)
+                            break;
+                        registration = again;
+                        registeredAt = Date.now();
+                        continue;
+                    }
+                    log.warn('claim failed', { error: messageOf(error) });
+                    await this.pause(registration.poll_seconds * 2_000);
+                    continue;
+                }
+                if (!claim) {
+                    await this.pause(registration.poll_seconds * 1_000);
+                    continue;
+                }
+                const started = isSessionClaim(claim)
+                    ? await this.startSession(claim, registration)
+                    : await this.startJob(claim);
+                if (started === 'unknown') {
+                    await this.pause(registration.poll_seconds * 1_000);
+                    continue;
+                }
+                claimedOnce = true;
+                if (!started)
+                    continue;
+                const tracked = started.task.finally(() => {
+                    active.delete(tracked);
+                    this.writeState();
+                    for (const wake of this.wake)
+                        wake();
+                });
+                active.add(tracked);
+            }
+        }
+        finally {
+            devices.stopRefresh();
+            await Promise.allSettled([...active]);
+            this.writeState(true);
+        }
+    }
+    /** Leases the job's device and starts it; null when it could not start (already reported). */
+    async startJob(job) {
+        const { client, devices, log } = this.deps;
+        const kind = job.kind ?? 'test';
+        if (kind !== 'test') {
+            log.warn('ignoring a claim this runner version cannot handle', { kind });
+            return 'unknown';
+        }
+        const platform = job.platform ?? 'web';
+        const lease = isPlatform(platform) ? devices.lease(platform, job.device?.id, { holder: `job:${job.job.id}` }) : null;
+        if (!lease) {
+            await client
+                .complete({ job_id: job.job.id, error: `this runner has no free ${platform} device for the job` })
+                .catch((error) => log.error('could not report the failure', { job_id: job.job.id, error: messageOf(error) }));
+            return null;
+        }
+        const task = this.runJob(job, lease)
+            .catch((error) => log.error('job crashed', { job_id: job.job.id, error: messageOf(error) }))
+            .finally(() => lease.release());
+        return { task };
+    }
+    /** Leases the session's device and runs the session loop; null when no device was free (session ended). */
+    async startSession(claim, registration) {
+        const { client, devices, log, registry, shared } = this.deps;
+        const session = claim.session;
+        const lease = isPlatform(session.platform)
+            ? devices.lease(session.platform, session.device?.id, { holder: `session:${session.id}` })
+            : null;
+        if (!lease) {
+            await client
+                .endSession(session.id, `this runner has no free ${session.platform} device for the session`)
+                .catch((error) => log.error('could not end the session', { session_id: session.id, error: messageOf(error) }));
+            return null;
+        }
+        const config = this.config;
+        this.running.set(-session.id, {
+            id: session.id,
+            kind: 'session',
+            platform: session.platform,
+            device_id: lease.device.id,
+            started_at: new Date().toISOString(),
+        });
+        this.writeState();
+        const task = runSession(session, {
+            client,
+            runnerId: registration.runner_id,
+            log,
+            shouldStop: () => this.stopping,
+            stopSignal: this.stopController.signal,
+            createDriver: () => {
+                const ctx = sessionContext(session, {
+                    lease,
+                    app: this.appSettings(),
+                    buildDownloadUrl: (buildId) => client.buildDownloadUrl(buildId, { sessionId: session.id }),
+                    actionTimeoutMs: config.actionTimeoutMs,
+                    jobTimeoutMs: config.jobTimeoutMs,
+                    headless: config.headless,
+                    ...(config.proxy ? { proxy: config.proxy } : {}),
+                    redact: redactor([session.credential?.password]),
+                    log,
+                });
+                return createDriver(registry, ctx, shared);
+            },
+        })
+            .then(() => undefined)
+            .catch((error) => log.error('session crashed', { session_id: session.id, error: messageOf(error) }))
+            .finally(() => {
+            this.running.delete(-session.id);
+            lease.release();
+        });
+        return { task };
+    }
+    /** App-platform settings every job and session context gets (runner home, local installs, SDK path). */
+    appSettings() {
+        return {
+            ...(this.deps.paths ? { paths: this.deps.paths } : {}),
+            allowLocalPaths: this.config.allowLocalPaths,
+            ...(this.config.androidSdkPath ? { androidSdkPath: this.config.androidSdkPath } : {}),
+        };
+    }
+    async register() {
+        const { client, devices, host, log } = this.deps;
+        const body = {
+            name: this.config.name,
+            labels: this.config.labels,
+            version: this.deps.version ?? RUNNER_VERSION,
+            os: host.os,
+            arch: host.arch,
+            hostname: host.hostname,
+            ephemeral: this.deps.ephemeral ?? false,
+            ...(this.deps.ephemeral && this.config.runId != null ? { run_id: this.config.runId } : {}),
+            capabilities: buildCapabilities(devices.capabilityDevices(), host),
+        };
+        let delay = 2_000;
+        while (!this.stopping) {
+            try {
+                const registration = await client.register(body);
+                if (this.registration?.runner_id !== registration.runner_id) {
+                    log.info('registered', {
+                        runner_id: registration.runner_id,
+                        pool_id: registration.pool_id,
+                        labels: registration.labels ?? this.config.labels,
+                    });
+                }
+                this.noteLatestVersion(registration.latest_version, body.version);
+                this.registration = registration;
+                this.writeState();
+                return registration;
+            }
+            catch (error) {
+                if (error instanceof ApiError && (error.status === 401 || error.status === 403))
+                    throw tokenRejected(error);
+                if (error instanceof ApiError && error.status === 426)
+                    throw new ExitError(ExitCode.versionRefused, error.message);
+                if (error instanceof ApiError && error.status === 400) {
+                    throw new ExitError(ExitCode.error, `the server refused the registration: ${error.message}`);
+                }
+                log.warn('request failed, retrying', { error: messageOf(error), retry_in_ms: delay });
+                await this.pause(delay);
+                delay = Math.min(delay * 2, MAX_BACKOFF_MS);
+            }
+        }
+        return null;
+    }
+    /** Sleeps for `ms`, returning early on stop or when any of `tasks` settles. */
+    pause(ms, tasks) {
+        if (this.stopping)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                this.wake.delete(done);
+                resolve();
+            };
+            const timer = setTimeout(done, ms);
+            this.wake.add(done);
+            if (tasks && tasks.size > 0)
+                void Promise.race(tasks).then(done, done);
+        });
+    }
+    async runJob(job, lease) {
+        const { client, log, registry, shared } = this.deps;
+        const config = this.config;
+        const jobId = job.job.id;
+        const platform = lease.device.platform;
+        const redact = redactor([job.credential?.password]);
+        let cancelled = false;
+        this.running.set(jobId, { id: jobId, kind: 'test', platform, device_id: lease.device.id, started_at: new Date().toISOString() });
+        this.writeState();
+        log.info('job started', { job_id: jobId, item_id: job.item.id, attempt: job.job.attempt, platform, device: lease.device.id });
+        const heartbeat = setInterval(() => {
+            client
+                .heartbeat(jobId)
+                .then((keepGoing) => {
+                if (!keepGoing)
+                    cancelled = true;
+            })
+                .catch((error) => log.warn('heartbeat failed', { job_id: jobId, error: redact(messageOf(error)) }));
+        }, job.job.heartbeat_seconds * 1_000);
+        let videoPath;
+        try {
+            const ctx = jobContext(job, {
+                lease,
+                app: this.appSettings(),
+                buildDownloadUrl: (buildId) => client.buildDownloadUrl(buildId, { jobId }),
+                actionTimeoutMs: config.actionTimeoutMs,
+                jobTimeoutMs: config.jobTimeoutMs,
+                headless: config.headless,
+                ...(config.proxy ? { proxy: config.proxy } : {}),
+                redact,
+                log,
+            });
+            const report = await executeClaimedJob(registry, ctx, shared, () => cancelled || this.stopping);
+            videoPath = report.videoPath;
+            if (cancelled) {
+                log.info('job cancelled', { job_id: jobId });
+                this.jobFinished(job, 'cancelled', 'the job was cancelled', [], report.elapsedSecs);
+                return;
+            }
+            if (report.stopped) {
+                await client.complete({ job_id: jobId, error: 'the runner shut down before the job finished' });
+                this.jobFinished(job, 'error', 'the runner shut down before the job finished', [], report.elapsedSecs);
+                return;
+            }
+            const stepResults = [];
+            for (const step of report.steps) {
+                const attachments = [];
+                for (const shot of step.screenshots) {
+                    try {
+                        attachments.push(await client.uploadEvidence(jobId, shot.name, shot.png));
+                    }
+                    catch (error) {
+                        log.warn('evidence upload failed', { job_id: jobId, error: redact(messageOf(error)) });
+                    }
+                }
+                stepResults.push({
+                    index: step.index,
+                    result: step.result,
+                    ...(step.note ? { note: step.note } : {}),
+                    ...(attachments.length > 0 ? { attachments } : {}),
+                    ...(step.debug ? { debug: step.debug } : {}),
+                });
+            }
+            const passed = report.steps.filter((step) => step.result === 'passed').length;
+            const notes = [
+                `Automated run on ${job.environment.name} by runner ${config.name}: ${passed} of ${job.item.steps.length} steps passed.`,
+            ];
+            const evidence = [];
+            const mode = job.capture?.video ?? 'off';
+            const troubled = report.steps.some((step) => step.result !== 'passed');
+            if (videoPath && (mode === 'always' || (mode === 'on_failure' && troubled))) {
+                const size = (await stat(videoPath)).size;
+                if (size > MAX_VIDEO_BYTES) {
+                    notes.push(`The video was not kept: it is ${Math.round(size / (1024 * 1024))} MB, over the 50 MB limit.`);
+                }
+                else {
+                    try {
+                        const mp4 = videoPath.toLowerCase().endsWith('.mp4');
+                        evidence.push(await client.uploadEvidence(jobId, mp4 ? 'case-video.mp4' : 'case-video.webm', await readFile(videoPath), mp4 ? 'video/mp4' : 'video/webm'));
+                    }
+                    catch (error) {
+                        log.warn('video upload failed', { job_id: jobId, error: redact(messageOf(error)) });
+                        notes.push('The video could not be uploaded.');
+                    }
+                }
+            }
+            const outcome = await client.complete({
+                job_id: jobId,
+                step_results: stepResults,
+                elapsed_secs: report.elapsedSecs,
+                notes: notes.join(' '),
+                ...(evidence.length > 0 ? { evidence } : {}),
+            });
+            log.info('job finished', { job_id: jobId, item_result: outcome.item_result, elapsed_secs: report.elapsedSecs });
+            this.jobFinished(job, outcome.item_result, notes.join(' '), report.steps.filter((step) => step.result !== 'passed' && step.note).map((step) => redact(step.note)), report.elapsedSecs);
+        }
+        catch (error) {
+            const reason = redact(messageOf(error));
+            log.error('job could not run', { job_id: jobId, error: reason });
+            await client
+                .complete({ job_id: jobId, error: reason })
+                .catch((e) => log.error('could not report the failure', { job_id: jobId, error: redact(messageOf(e)) }));
+            this.jobFinished(job, 'error', reason, [reason], 0);
+        }
+        finally {
+            clearInterval(heartbeat);
+            this.running.delete(jobId);
+            // Each job records into its own temporary directory.
+            if (videoPath)
+                await rm(dirname(videoPath), { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+    jobFinished(job, result, notes, failures, elapsedSecs) {
+        try {
+            this.deps.onJobFinished?.({
+                job_id: job.job.id,
+                attempt: job.job.attempt,
+                item_id: job.item.id,
+                title: job.item.title,
+                result,
+                notes,
+                failures,
+                elapsed_secs: elapsedSecs,
+            });
+        }
+        catch (error) {
+            this.deps.log.warn('job listener failed', { error: messageOf(error) });
+        }
+    }
+    writeState(stopped = false) {
+        const path = this.deps.statePath;
+        if (!path)
+            return;
+        const state = {
+            pid: process.pid,
+            version: this.deps.version ?? RUNNER_VERSION,
+            name: this.config.name,
+            url: this.config.url,
+            started_at: this.startedAt,
+            updated_at: new Date().toISOString(),
+            stopped,
+            runner_id: this.registration?.runner_id ?? null,
+            pool_id: this.registration?.pool_id ?? null,
+            labels: this.registration?.labels ?? this.config.labels,
+            jobs: [...this.running.values()].filter((entry) => entry.kind === 'test'),
+            sessions: [...this.running.values()].filter((entry) => entry.kind === 'session'),
+            devices: this.deps.devices.busy(),
+            latest_version: this.latestVersion,
+            update_notice_day: this.updateNoticeDay,
+        };
+        try {
+            writePrivateFile(path, `${JSON.stringify(state, null, 2)}\n`);
+        }
+        catch (error) {
+            this.deps.log.warn('could not write the state file', { path, error: messageOf(error) });
+        }
+    }
+}
+function tokenRejected(error) {
+    return new ExitError(ExitCode.tokenRejected, `the server rejected the runner token (${error.status} ${error.message}); create a new token and run \`leera-qa-runner config set-token\``);
+}
+/** Everything `start` and the Docker entry need: config, detected devices, client, runner. */
+export async function createRunner(options) {
+    const env = options.env ?? process.env;
+    const paths = homePaths(env);
+    const home = options.useHome === false ? { file: null, token: null, fixedPermissions: false } : loadFileConfig(paths);
+    if (home.fixedPermissions)
+        options.log.warn('the token file was readable by others; its permissions were set to 0600', { path: paths.token });
+    const registry = options.registry ?? createRegistry();
+    const host = hostInfo();
+    const detection = await detect(registry, host);
+    for (const [platform, reasons] of Object.entries(detection.unavailable)) {
+        options.log.warn('platform unavailable', { platform, reasons });
+    }
+    const config = resolveConfig({
+        ...(options.flags ? { flags: options.flags } : {}),
+        env,
+        file: home.file,
+        fileToken: home.token,
+        detectedLabels: detection.labels,
+    });
+    const devices = new DeviceManager(detection.devices, (device) => device.id === BROWSER_DEVICE_ID ? config.concurrency.web : 1);
+    const shared = {
+        browsers: new BrowserPool({ headless: config.headless, ...(config.proxy ? { proxy: config.proxy } : {}) }),
+    };
+    const runner = new Runner(config, {
+        client: new RunnerClient(config.url, config.token),
+        registry,
+        devices,
+        host,
+        shared,
+        log: options.log,
+        ...(options.useHome === false ? {} : { paths }),
+        ...(options.writeState ? { statePath: paths.state } : {}),
+    });
+    return { runner, config, shared };
+}

package/dist/src/service/index.js

@@ -0,0 +1,64 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { PACKAGE_ROOT } from '../version.js';
+import { launchdBackend } from './launchd.js';
+import { schtasksBackend } from './schtasks.js';
+import { systemdBackend } from './systemd.js';
+export { SERVICE_LABEL, SERVICE_NAME } from './names.js';
+/** Environment variables `service install` copies into the config, since services start without a login shell. */
+export const CAPTURED_ENV = ['PATH', 'JAVA_HOME', 'ANDROID_HOME', 'ANDROID_SDK_ROOT', 'PLAYWRIGHT_BROWSERS_PATH', 'HTTPS_PROXY', 'HTTP_PROXY', 'NO_PROXY'];
+/** The argv a service starts: the bundle launcher when present (so updates take effect), else node + cli.js. */
+export function serviceArgv(env, execPath = process.execPath, cliPath = join(PACKAGE_ROOT, 'dist', 'src', 'cli.js')) {
+    const launcher = env.LEERA_RUNNER_LAUNCHER?.trim();
+    const base = launcher ? [launcher] : [execPath, cliPath];
+    const home = env.LEERA_RUNNER_HOME?.trim();
+    return [...base, 'start', '--service', ...(home ? ['--home', home] : [])];
+}
+export function serviceSpec(env, home, logDir) {
+    const serviceEnv = {};
+    if (env.PATH)
+        serviceEnv.PATH = env.PATH;
+    return { argv: serviceArgv(env), env: serviceEnv, home, logDir, userHome: homedir() };
+}
+export function backendFor(platform) {
+    if (platform === 'darwin')
+        return launchdBackend(process.getuid?.() ?? 501);
+    if (platform === 'win32')
+        return schtasksBackend(process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${process.env.USERNAME ?? ''}` : (process.env.USERNAME ?? ''));
+    if (platform === 'linux')
+        return systemdBackend();
+    return null;
+}
+/** Runs a fixed argv without a shell. */
+export const execArgv = (argv) => new Promise((resolve) => {
+    const [command, ...args] = argv;
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => (stdout += chunk));
+    child.stderr.on('data', (chunk) => (stderr += chunk));
+    child.on('error', (error) => resolve({ code: 127, stdout, stderr: stderr + error.message }));
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+});
+export async function applyPlan(plan, exec = execArgv) {
+    for (const write of plan.writes ?? []) {
+        await mkdir(dirname(write.path), { recursive: true });
+        await writeFile(write.path, write.contents);
+    }
+    const outputs = [];
+    for (const command of plan.commands) {
+        const result = await exec(command.argv);
+        outputs.push({ argv: command.argv, result });
+        if (result.code !== 0 && !command.ignoreFailure) {
+            return { ok: false, outputs, failed: { argv: command.argv, result } };
+        }
+    }
+    for (const path of plan.removes ?? []) {
+        if (existsSync(path))
+            await rm(path, { force: true });
+    }
+    return { ok: true, outputs };
+}