@leera.io/qa-runner 1.0.0

package/dist/src/cli/main.js

@@ -0,0 +1,59 @@
+import { ExitCode, ExitError } from '../errors.js';
+import { processIo } from './output.js';
+const COMMANDS = {
+    start: async () => (await import('./commands/start.js')).command,
+    connect: async () => (await import('./commands/connect.js')).command,
+    ci: async () => (await import('./commands/ci.js')).command,
+    builds: async () => (await import('./commands/builds.js')).command,
+    doctor: async () => (await import('./commands/doctor.js')).command,
+    setup: async () => (await import('./commands/setup.js')).command,
+    service: async () => (await import('./commands/service.js')).command,
+    config: async () => (await import('./commands/config.js')).command,
+    version: async () => (await import('./commands/version.js')).command,
+    update: async () => (await import('./commands/update.js')).command,
+};
+async function helpText() {
+    const lines = ['Usage: leera-qa-runner <command> [options]', '', 'Commands:'];
+    for (const [name, load] of Object.entries(COMMANDS)) {
+        lines.push(`  ${name.padEnd(10)} ${(await load()).summary}`);
+    }
+    lines.push('', "Run 'leera-qa-runner <command> --help' for a command's options.");
+    return lines.join('\n');
+}
+/** Runs the CLI and returns the exit code. */
+export async function main(argv, io = processIo()) {
+    const [name, ...rest] = argv;
+    try {
+        if (!name || name === 'help' || name === '--help' || name === '-h') {
+            io.stdout(await helpText());
+            return name ? ExitCode.ok : ExitCode.usage;
+        }
+        if (name === '--version' || name === '-v')
+            return await (await COMMANDS.version()).run([], io);
+        const load = COMMANDS[name];
+        if (!load) {
+            io.stderr(`unknown command '${name}'\n\n${await helpText()}`);
+            return ExitCode.usage;
+        }
+        const command = await load();
+        if (rest.includes('--help') || rest.includes('-h')) {
+            io.stdout(command.usage);
+            return ExitCode.ok;
+        }
+        return await command.run(rest, io);
+    }
+    catch (error) {
+        if (error instanceof ExitError) {
+            io.stderr(`error: ${error.message}`);
+            return error.code;
+        }
+        // node:util parseArgs reports unknown or malformed options with these codes.
+        const code = error.code;
+        if (typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS')) {
+            io.stderr(`error: ${error.message}`);
+            return ExitCode.usage;
+        }
+        io.stderr(`error: ${error instanceof Error ? error.message : String(error)}`);
+        return ExitCode.error;
+    }
+}

package/dist/src/cli/output.js

@@ -0,0 +1,67 @@
+import { ExitCode, ExitError } from '../errors.js';
+export function processIo() {
+    return {
+        stdout: (text) => process.stdout.write(text.endsWith('\n') ? text : `${text}\n`),
+        stderr: (text) => process.stderr.write(text.endsWith('\n') ? text : `${text}\n`),
+        env: process.env,
+        stdin: process.stdin,
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        platform: process.platform,
+    };
+}
+export function printJson(io, value) {
+    io.stdout(JSON.stringify(value, null, 2));
+}
+export function usageError(message, usage) {
+    return new ExitError(ExitCode.usage, usage ? `${message}\n\n${usage}` : message);
+}
+/** Reads everything piped to stdin. */
+export async function readStdin(stdin) {
+    const chunks = [];
+    for await (const chunk of stdin)
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+const ENTER = new Set([13, 10, 4]); // CR, LF, Ctrl-D
+const CTRL_C = 3;
+const BACKSPACE = new Set([127, 8]);
+/** Asks for a secret without echoing it. */
+export function promptHidden(io, question) {
+    const stdin = io.stdin;
+    return new Promise((resolve, reject) => {
+        if (!stdin.setRawMode) {
+            reject(usageError('cannot prompt without a terminal; pipe the token and pass --token-stdin'));
+            return;
+        }
+        process.stdout.write(question);
+        let value = '';
+        const finish = () => {
+            stdin.removeListener('data', onData);
+            stdin.setRawMode?.(false);
+            stdin.pause();
+            process.stdout.write('\n');
+        };
+        const onData = (chunk) => {
+            for (const char of chunk.toString()) {
+                const code = char.charCodeAt(0);
+                if (ENTER.has(code)) {
+                    finish();
+                    resolve(value);
+                    return;
+                }
+                if (code === CTRL_C) {
+                    finish();
+                    reject(new ExitError(ExitCode.interrupted, 'interrupted'));
+                    return;
+                }
+                if (BACKSPACE.has(code))
+                    value = value.slice(0, -1);
+                else
+                    value += char;
+            }
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on('data', onData);
+    });
+}

package/dist/src/cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// CLI entry. Environment that must be in place before Playwright loads is set here,
+// then the commands are imported.
+import { existsSync, readdirSync } from 'node:fs';
+import { loadFileConfig } from './config.js';
+import { homePaths } from './home.js';
+function bootstrapEnv(argv) {
+    const homeIndex = argv.indexOf('--home');
+    if (homeIndex >= 0 && argv[homeIndex + 1])
+        process.env.LEERA_RUNNER_HOME = argv[homeIndex + 1];
+    const paths = homePaths(process.env);
+    // A service starts without the login shell's environment; `service install` saved it.
+    if (argv.includes('--service')) {
+        try {
+            const saved = loadFileConfig(paths).file?.env ?? {};
+            for (const [key, value] of Object.entries(saved)) {
+                if (key === 'PATH' || process.env[key] === undefined)
+                    process.env[key] = value;
+            }
+        }
+        catch {
+            // `start` reports an unreadable config itself.
+        }
+    }
+    // Browsers installed by `setup browsers` live in the runner home.
+    if (!process.env.PLAYWRIGHT_BROWSERS_PATH) {
+        try {
+            if (existsSync(paths.browsers) && readdirSync(paths.browsers).length > 0) {
+                process.env.PLAYWRIGHT_BROWSERS_PATH = paths.browsers;
+            }
+        }
+        catch {
+            // Fall back to Playwright's default cache.
+        }
+    }
+}
+const argv = process.argv.slice(2);
+bootstrapEnv(argv);
+const { main } = await import('./cli/main.js');
+process.exitCode = await main(argv);

package/dist/src/client.js

@@ -0,0 +1,146 @@
+export class ApiError extends Error {
+    status;
+    /** The parsed error body (unwrapped from `data` when the server wraps it), when it was JSON. */
+    body;
+    constructor(message, status, body = null) {
+        super(message);
+        this.status = status;
+        const wrapped = body;
+        this.body = wrapped && typeof wrapped === 'object' && wrapped.data && typeof wrapped.data === 'object' ? wrapped.data : body;
+    }
+}
+export class RunnerClient {
+    base;
+    token;
+    constructor(baseUrl, token) {
+        this.base = baseUrl.replace(/\/+$/, '');
+        this.token = token;
+    }
+    async register(body) {
+        return this.expect(await this.json('/api/v1/qa/runner/register', body));
+    }
+    claim(runnerId, options = {}) {
+        return this.json('/api/v1/qa/runner/claim', {
+            runner_id: runnerId,
+            ...(options.runId != null ? { run_id: options.runId } : {}),
+            ...(options.accept ? { accept: options.accept } : {}),
+        });
+    }
+    /**
+     * Checks the token without registering: a claim for runner 0 is refused with 400
+     * ("unknown runner") when the token is valid and 401/403 when it is not.
+     */
+    async checkToken() {
+        try {
+            await this.request('/api/v1/qa/runner/claim', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ runner_id: 0, accept: [] }),
+            }, 15_000);
+            return { result: 'unexpected', status: 200 };
+        }
+        catch (error) {
+            if (!(error instanceof ApiError))
+                throw error;
+            if (error.status === 401 || error.status === 403)
+                return { result: 'rejected', status: error.status, message: error.message };
+            if (error.status === 400)
+                return { result: 'accepted', status: 400 };
+            return { result: 'unexpected', status: error.status, message: error.message };
+        }
+    }
+    async heartbeat(jobId) {
+        const response = await this.json('/api/v1/qa/runner/heartbeat', { job_id: jobId });
+        return response?.continue ?? false;
+    }
+    async uploadEvidence(jobId, name, bytes, contentType = 'image/png') {
+        const form = new FormData();
+        form.append('file', new Blob([new Uint8Array(bytes)], { type: contentType }), name);
+        // A video can take a while to send over a slow uplink.
+        const timeoutMs = contentType.startsWith('video/') ? 10 * 60_000 : 60_000;
+        return this.expect(await this.request(`/api/v1/qa/runner/evidence?job_id=${jobId}`, { method: 'POST', body: form }, timeoutMs));
+    }
+    async complete(body) {
+        return this.expect(await this.json('/api/v1/qa/runner/complete', body));
+    }
+    /**
+     * Long-polls for the session's next command. The server holds the request up to
+     * `waitSeconds` (and extends the session lease meanwhile); 410 means the session ended.
+     */
+    async nextCommand(sessionId, runnerId, waitSeconds, signal) {
+        try {
+            const response = await this.request('/api/v1/qa/runner/sessions/commands/next', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ session_id: sessionId, runner_id: runnerId, wait_seconds: waitSeconds }),
+            }, (waitSeconds + 20) * 1_000, signal);
+            return response?.command ? { kind: 'command', command: response.command } : { kind: 'none' };
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 410) {
+                const body = (error.body ?? {});
+                return { kind: 'gone', status: body.status ?? 'ended', reason: body.reason ?? null };
+            }
+            throw error;
+        }
+    }
+    /** Sends a command's result as multipart: a `result` JSON part and an optional `screenshot` part. */
+    async postCommandResult(sessionId, commandId, result, screenshot) {
+        const form = new FormData();
+        form.append('result', new Blob([JSON.stringify(result)], { type: 'application/json' }), 'result.json');
+        if (screenshot) {
+            const extension = screenshot.contentType === 'image/jpeg' ? 'jpg' : 'png';
+            form.append('screenshot', new Blob([new Uint8Array(screenshot.bytes)], { type: screenshot.contentType }), `command-${commandId}.${extension}`);
+        }
+        await this.request(`/api/v1/qa/runner/sessions/commands/result?session_id=${sessionId}&command_id=${commandId}`, { method: 'POST', body: form }, 60_000);
+    }
+    /** Ends a session; idempotent on the server. */
+    async endSession(sessionId, reason) {
+        await this.json('/api/v1/qa/runner/sessions/end', { session_id: sessionId, ...(reason ? { reason } : {}) });
+    }
+    /** A short-lived download URL for a build of a running job or active session (contracts §H4). */
+    async buildDownloadUrl(buildId, owner) {
+        return this.expect(await this.json('/api/v1/qa/runner/builds/download-url', {
+            build_id: buildId,
+            ...(owner.jobId !== undefined ? { job_id: owner.jobId } : { session_id: owner.sessionId }),
+        }));
+    }
+    json(path, body) {
+        return this.request(path, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    async request(path, init, timeoutMs = 60_000, signal) {
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const response = await fetch(this.base + path, {
+            ...init,
+            headers: { ...init.headers, authorization: `Bearer ${this.token}` },
+            signal: signal ? AbortSignal.any([timeout, signal]) : timeout,
+        });
+        if (response.status === 204)
+            return null;
+        const text = await response.text();
+        let payload = null;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            payload = null;
+        }
+        if (!response.ok) {
+            const message = payload?.message || payload?.error_message || payload?.reason || `HTTP ${response.status}`;
+            throw new ApiError(message, response.status, payload);
+        }
+        // Every endpoint wraps its payload in `data`; tolerate an unwrapped body for the session calls' `{command}`.
+        if (payload && typeof payload === 'object' && !('data' in payload) && 'command' in payload)
+            return payload;
+        return payload?.data ?? null;
+    }
+    expect(value) {
+        if (value === null)
+            throw new ApiError('the server returned no data', 502);
+        return value;
+    }
+}

package/dist/src/config.js

@@ -0,0 +1,260 @@
+import { hostname } from 'node:os';
+import { isAbsolute } from 'node:path';
+import { ExitCode, ExitError } from './errors.js';
+import { ensureHome, readJsonFile, readTokenFile, writePrivateFile } from './home.js';
+export const DEFAULTS = {
+    labels: ['web-chromium'],
+    headless: true,
+    actionTimeoutMs: 15_000,
+    jobTimeoutMs: 15 * 60_000,
+    concurrencyWeb: 1,
+    allowLocalPaths: false,
+};
+export const TOKEN_PREFIX = 'pm_run_';
+export const MAX_CONCURRENCY = 16;
+/**
+ * Precedence: flags > `RUNNER_*` > legacy `LEERA_*` > config file > defaults.
+ * `--labels` / `RUNNER_LABELS` replace the label list exactly; otherwise it is
+ * detected ∪ `labels.extra` − `labels.exclude`.
+ */
+export function resolveConfig(input) {
+    const flags = input.flags ?? {};
+    const env = input.env ?? {};
+    const file = input.file ?? {};
+    const url = pick(flags.url, env.RUNNER_URL, env.LEERA_URL, file.url);
+    if (!url) {
+        throw new ExitError(ExitCode.usage, 'RUNNER_URL is required (or run `leera-qa-runner connect --url <server>` first)');
+    }
+    const token = pick(flags.token, env.RUNNER_TOKEN, env.LEERA_RUNNER_TOKEN, input.fileToken ?? undefined);
+    if (!token) {
+        throw new ExitError(ExitCode.usage, 'RUNNER_TOKEN is required (or run `leera-qa-runner connect` to store one)');
+    }
+    if (!token.startsWith(TOKEN_PREFIX)) {
+        throw new ExitError(ExitCode.usage, `RUNNER_TOKEN must be a runner pool token (${TOKEN_PREFIX}...)`);
+    }
+    let labels;
+    const labelOverride = flags.labels ?? (env.RUNNER_LABELS !== undefined ? splitList(env.RUNNER_LABELS) : undefined);
+    if (labelOverride) {
+        labels = unique(labelOverride);
+    }
+    else {
+        const exclude = new Set(file.labels?.exclude ?? []);
+        labels = unique([...(input.detectedLabels ?? DEFAULTS.labels), ...(file.labels?.extra ?? [])]).filter((label) => !exclude.has(label));
+    }
+    const proxy = pick(env.RUNNER_PROXY, file.proxy);
+    const concurrency = flags.concurrency ?? integer(env.RUNNER_CONCURRENCY, 'RUNNER_CONCURRENCY') ?? file.concurrency?.web ?? DEFAULTS.concurrencyWeb;
+    if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > MAX_CONCURRENCY) {
+        throw new ExitError(ExitCode.usage, `concurrency must be a whole number from 1 to ${MAX_CONCURRENCY}`);
+    }
+    const runId = flags.runId ?? integer(env.RUNNER_RUN_ID, 'RUNNER_RUN_ID') ?? null;
+    return {
+        url,
+        token,
+        name: pick(flags.name, env.RUNNER_NAME, file.name) ?? hostname(),
+        labels,
+        once: flags.once ?? flag(env.RUNNER_ONCE) ?? false,
+        headless: flags.headed ? false : (flag(env.RUNNER_HEADLESS) ?? file.headless ?? DEFAULTS.headless),
+        ...(proxy ? { proxy } : {}),
+        actionTimeoutMs: integer(env.RUNNER_ACTION_TIMEOUT_MS, 'RUNNER_ACTION_TIMEOUT_MS') ?? file.action_timeout_ms ?? DEFAULTS.actionTimeoutMs,
+        jobTimeoutMs: integer(env.RUNNER_JOB_TIMEOUT_MS, 'RUNNER_JOB_TIMEOUT_MS') ?? file.job_timeout_ms ?? DEFAULTS.jobTimeoutMs,
+        concurrency: { web: concurrency },
+        runId,
+        service: flags.service ?? false,
+        allowLocalPaths: flag(env.RUNNER_ALLOW_LOCAL_PATHS) ?? file.builds?.allow_local_paths ?? DEFAULTS.allowLocalPaths,
+        androidSdkPath: pick(file.android?.sdk_path) ?? null,
+    };
+}
+/** Reads config.json and the token file from the home directory. */
+export function loadFileConfig(paths) {
+    let file;
+    try {
+        file = readJsonFile(paths.config);
+    }
+    catch (error) {
+        throw new ExitError(ExitCode.usage, `${paths.config} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const { token, fixedPermissions } = readTokenFile(paths);
+    return { file, token, fixedPermissions };
+}
+export function saveFileConfig(paths, config) {
+    ensureHome(paths);
+    writePrivateFile(paths.config, `${JSON.stringify(config, null, 2)}\n`);
+}
+/** Keys `config get|set|unset` understand, with how to parse a value typed on the command line. */
+export const CONFIG_KEYS = {
+    url: { kind: 'url', help: 'Server URL (RUNNER_URL)' },
+    name: { kind: 'string', help: 'Runner name shown in the workspace (RUNNER_NAME; default: host name)' },
+    'labels.extra': { kind: 'list', help: 'Labels added to the detected ones (comma separated)' },
+    'labels.exclude': { kind: 'list', help: 'Detected labels to leave out (comma separated)' },
+    'concurrency.web': { kind: 'integer', help: 'Browser jobs at once (RUNNER_CONCURRENCY; default 1)' },
+    headless: { kind: 'boolean', help: 'Run browsers without a window (RUNNER_HEADLESS; default true)' },
+    proxy: { kind: 'string', help: 'Proxy server for browsers (RUNNER_PROXY)' },
+    action_timeout_ms: { kind: 'integer', help: 'Per-action timeout (RUNNER_ACTION_TIMEOUT_MS; default 15000)' },
+    job_timeout_ms: { kind: 'integer', help: 'Whole-job timeout (RUNNER_JOB_TIMEOUT_MS; default 900000)' },
+    'builds.allow_local_paths': {
+        kind: 'boolean',
+        help: 'Install apps from a file path on this machine (RUNNER_ALLOW_LOCAL_PATHS; default false)',
+    },
+    'android.sdk_path': { kind: 'path', help: 'Android SDK directory; wins over ANDROID_HOME (absolute path)' },
+    'ios.team_id': { kind: 'string', help: 'Apple Developer Team ID that signs WebDriverAgent for real iOS devices (RUNNER_IOS_TEAM_ID)' },
+    'ios.wda_bundle_id': { kind: 'string', help: 'Bundle id to sign WebDriverAgent under on real iOS devices (RUNNER_IOS_WDA_BUNDLE_ID)' },
+    'ios.signing_id': { kind: 'string', help: 'Code signing identity for WebDriverAgent (RUNNER_IOS_SIGNING_ID; default Apple Development)' },
+    'ios.simulator_boot_timeout_secs': {
+        kind: 'integer',
+        help: 'Seconds one iOS simulator boot may take before it is shut down and tried once more (RUNNER_IOS_BOOT_TIMEOUT_SECS; default 300)',
+    },
+    'tauri.driver_path': { kind: 'path', help: 'tauri-driver executable (RUNNER_TAURI_DRIVER; default ~/.cargo/bin/tauri-driver, then PATH)' },
+    'tauri.native_driver_path': {
+        kind: 'path',
+        help: 'Native WebDriver for tauri-driver: msedgedriver.exe on Windows, WebKitWebDriver on Linux (RUNNER_TAURI_NATIVE_DRIVER; default PATH)',
+    },
+    'tauri.macos_plugin': {
+        kind: 'boolean',
+        help: 'macOS: run Tauri jobs for builds that embed the WebDriver plugin (RUNNER_TAURI_MACOS_PLUGIN; default false)',
+    },
+    'windows.winappdriver_path': {
+        kind: 'path',
+        help: 'WinAppDriver.exe for Windows app jobs (RUNNER_WINAPPDRIVER; default the msi install folder)',
+    },
+};
+/** Returns the value a key holds; `env.NAME` addresses one captured environment variable. */
+export function getConfigValue(config, key) {
+    let node = config;
+    for (const part of key.split('.')) {
+        if (node === null || typeof node !== 'object')
+            return undefined;
+        node = node[part];
+    }
+    return node;
+}
+export function setConfigValue(config, key, raw) {
+    const value = parseConfigValue(key, raw);
+    const next = structuredClone(config);
+    const parts = key.split('.');
+    let node = next;
+    for (const part of parts.slice(0, -1)) {
+        if (node[part] === null || typeof node[part] !== 'object')
+            node[part] = {};
+        node = node[part];
+    }
+    node[parts.at(-1)] = value;
+    return next;
+}
+export function unsetConfigValue(config, key) {
+    checkKey(key);
+    const next = structuredClone(config);
+    const parts = key.split('.');
+    let node = next;
+    for (const part of parts.slice(0, -1)) {
+        const child = node?.[part];
+        node = child !== null && typeof child === 'object' ? child : undefined;
+    }
+    if (node) {
+        delete node[parts.at(-1)];
+        // Drop an emptied parent such as `labels: {}`.
+        if (parts.length === 2 && Object.keys(node).length === 0)
+            delete next[parts[0]];
+    }
+    return next;
+}
+export function checkKey(key) {
+    if (CONFIG_KEYS[key])
+        return;
+    if (/^env\.[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+        return;
+    throw new ExitError(ExitCode.usage, `unknown config key '${key}' (known: ${Object.keys(CONFIG_KEYS).join(', ')}, env.<NAME>)`);
+}
+export function parseConfigValue(key, raw) {
+    checkKey(key);
+    const kind = CONFIG_KEYS[key]?.kind ?? 'string';
+    const text = raw.trim();
+    if (key === 'ios.team_id' && !/^[A-Z0-9]{10}$/.test(text)) {
+        throw new ExitError(ExitCode.usage, `${key} must be a 10-character Apple Team ID such as ABCDE12345`);
+    }
+    if (key === 'ios.wda_bundle_id' && !/^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/.test(text)) {
+        throw new ExitError(ExitCode.usage, `${key} must be a bundle id such as com.example.WebDriverAgentRunner`);
+    }
+    if (key === 'ios.signing_id' && (!text || text.length > 100 || /["\r\n]/.test(text))) {
+        throw new ExitError(ExitCode.usage, `${key} must be a code signing identity name such as "Apple Development"`);
+    }
+    if (key === 'ios.simulator_boot_timeout_secs' && !(/^\d+$/.test(text) && Number(text) >= 30 && Number(text) <= 3600)) {
+        throw new ExitError(ExitCode.usage, `${key} must be a whole number of seconds from 30 to 3600`);
+    }
+    switch (kind) {
+        case 'url': {
+            let url;
+            try {
+                url = new URL(text);
+            }
+            catch {
+                throw new ExitError(ExitCode.usage, `${key} must be a URL such as https://app.example.com`);
+            }
+            if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+                throw new ExitError(ExitCode.usage, `${key} must start with https:// or http://`);
+            }
+            return text.replace(/\/+$/, '');
+        }
+        case 'list':
+            return splitList(text);
+        case 'path': {
+            if (!text)
+                throw new ExitError(ExitCode.usage, `${key} must not be empty`);
+            if (!isAbsolute(text))
+                throw new ExitError(ExitCode.usage, `${key} must be an absolute path`);
+            return text.replace(/(.)[\\/]+$/, '$1');
+        }
+        case 'boolean': {
+            const normalized = text.toLowerCase();
+            if (['1', 'true', 'yes', 'on'].includes(normalized))
+                return true;
+            if (['0', 'false', 'no', 'off'].includes(normalized))
+                return false;
+            throw new ExitError(ExitCode.usage, `${key} must be true or false`);
+        }
+        case 'integer': {
+            const value = Number(text);
+            if (!Number.isInteger(value) || value <= 0)
+                throw new ExitError(ExitCode.usage, `${key} must be a positive whole number`);
+            return value;
+        }
+        default:
+            return raw;
+    }
+}
+export function splitList(value) {
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function pick(...values) {
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+function flag(value) {
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(normalized))
+        return false;
+    // Matches the previous behaviour: anything unrecognised reads as false.
+    return false;
+}
+function integer(raw, name) {
+    const text = raw?.trim();
+    if (!text)
+        return undefined;
+    const value = Number.parseInt(text, 10);
+    if (!Number.isFinite(value) || value <= 0)
+        throw new ExitError(ExitCode.usage, `${name} must be a positive integer`);
+    return value;
+}