@revyl/verify 0.0.0-stage → 0.1.0

package/dist/computer-session.d.ts

@@ -0,0 +1,37 @@
+import { RevylClient } from './api/client.js';
+import type { ResolvedComputerTarget } from './config.js';
+import { type ComputerProcess, type ExecOptions, type ExecResult, type FileStat, type OperationOptions, type Session, type SessionOptions, type StepResult } from './session.js';
+export declare class ComputerSession implements Session {
+    private readonly client;
+    private readonly options;
+    readonly platform: "mac";
+    readonly target: string;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    readonly viewerUrl: string;
+    readonly steps: StepResult[];
+    private readonly lifetime;
+    private closePromise;
+    private constructor();
+    static start(client: RevylClient, target: ResolvedComputerTarget, options: SessionOptions): Promise<ComputerSession>;
+    get closed(): boolean;
+    instruction(): Promise<never>;
+    validation(): Promise<never>;
+    screenshot(options?: {
+        path?: string;
+    }): Promise<Uint8Array>;
+    exec(argv: string[], options?: ExecOptions): Promise<ExecResult>;
+    readFile(path: string, options?: OperationOptions): Promise<Buffer>;
+    writeFile(path: string, data: string | Uint8Array, options?: OperationOptions): Promise<void>;
+    stat(path: string, options?: OperationOptions): Promise<FileStat>;
+    processes(options?: OperationOptions): Promise<ComputerProcess[]>;
+    terminate(processId: string, options?: OperationOptions): Promise<void>;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    private operation;
+    private request;
+    private report;
+    private assertOpen;
+    private unavailable;
+    private log;
+}
+export declare function computerOperationId(sessionId: string, requestId: string): string;

package/dist/computer-session.js

@@ -0,0 +1,322 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { responseDetail, sessionViewerUrl } from './api/client.js';
+import { trackSession, untrackSession } from './cleanup.js';
+import { VerifyError, isVerifyError } from './errors.js';
+import { pngSize } from './session.js';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const STATES = new Set(['starting', 'active', 'closing', 'stopped', 'failed', 'owner_lost']);
+const MAX_OUTPUT_BYTES = 1_048_576;
+const MAC_AVAILABILITY = 'Mac computers are not yet available in Revyl production. Early access works only on Revyl staging for enabled organizations. See https://github.com/RevylAI/verify/blob/main/packages/verify/docs/computers.md#availability-and-errors';
+const ERROR_CODES = new Set(['computer_not_enabled', 'run_closed', 'inaccessible', 'invalid_handle', 'operation_not_found', 'owner_unavailable', 'invalid_request', 'unauthenticated', 'forbidden', 'runtime_unavailable', 'start_failed', 'computer_limit', 'request_conflict', 'run_conflict', 'evidence_conflict', 'evidence_unavailable', 'authentication_unavailable', 'operation_limit', 'screen_starting', 'screen_unavailable']);
+export class ComputerSession {
+    client;
+    options;
+    platform = 'mac';
+    target;
+    id = randomUUID();
+    viewerUrl;
+    steps = [];
+    lifetime = new AbortController();
+    closePromise;
+    constructor(client, target, options) {
+        this.client = client;
+        this.options = options;
+        this.target = target.name;
+        this.viewerUrl = sessionViewerUrl(this.id, 'computer');
+    }
+    static async start(client, target, options) {
+        if (target.platform !== 'mac')
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'Linux computers are planned, but are not available in Verify yet.');
+        const session = new ComputerSession(client, target, options);
+        const signal = AbortSignal.any([AbortSignal.timeout(target.startTimeout), session.lifetime.signal]);
+        trackSession(session);
+        try {
+            session.log(`starting mac computer ${session.viewerUrl}. ${MAC_AVAILABILITY}`);
+            let report = session.report(await session.request('POST', '', { computer_session_id: session.id, os: 'macos' }, signal));
+            for (;;) {
+                if (report.state === 'active')
+                    break;
+                if (report.state !== 'starting')
+                    throw new VerifyError('SESSION_START_FAILED', `The ${session.target} computer ended before it was ready (${report.state}). See ${session.viewerUrl}`);
+                await delay(2_000, undefined, { signal });
+                report = session.report(await session.request('GET', '/report', undefined, signal));
+            }
+            session.log('ready');
+            return session;
+        }
+        catch (error) {
+            const timedOut = signal.aborted;
+            if (isVerifyError(error) && ['AUTH_REJECTED', 'NOT_AVAILABLE_ON_PLATFORM', 'INVALID_ARGUMENT'].includes(error.code)) {
+                session.lifetime.abort();
+                untrackSession(session);
+            }
+            else {
+                await session.close().catch(() => undefined);
+            }
+            if (timedOut)
+                throw new VerifyError('TIMEOUT', `The ${session.target} computer was not ready within ${target.startTimeout} ms. A possible cause is that no Mac computer could be assigned. ${MAC_AVAILABILITY}. Inspect ${session.viewerUrl}`);
+            throw error;
+        }
+    }
+    get closed() {
+        return this.closePromise !== undefined;
+    }
+    instruction() {
+        return this.unavailable('instruction');
+    }
+    validation() {
+        return this.unavailable('validation');
+    }
+    async screenshot(options = {}) {
+        this.assertOpen();
+        const response = await this.request('GET', '/screen/screenshot', undefined, this.lifetime.signal);
+        const raw = parseComputerJson(response);
+        const bytes = decodeBytes(raw?.png, 128 * MAX_OUTPUT_BYTES);
+        const size = pngSize(bytes);
+        if (!size || size.width > 4095 || size.height > 4095 || size.width !== raw.width || size.height !== raw.height)
+            throw invalidResponse();
+        if (options.path) {
+            const path = resolve(options.path);
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, bytes);
+        }
+        return bytes;
+    }
+    async exec(argv, options = {}) {
+        const stdin = options.stdin === undefined ? Buffer.alloc(0) : inputBytes(options.stdin);
+        if (!Array.isArray(argv) || argv.length < 1 || argv.length > 64 || !argv[0] || argv.some((arg) => typeof arg !== 'string' || arg.includes('\0')) || argv.reduce((sum, arg) => sum + Buffer.byteLength(arg), 0) + stdin.length > 16_384) {
+            throw new VerifyError('INVALID_ARGUMENT', 'exec() takes 1-64 string arguments without NUL bytes; argv and stdin together must fit in 16384 bytes.');
+        }
+        const result = await this.operation({ kind: 'exec', argv, stdin: stdin.toString('base64'), timeout_ms: operationTimeout(options) }, options.check === false);
+        if (result.kind !== 'exec' || !Number.isInteger(result.exit_code) || result.exit_code < -255 || result.exit_code > 255)
+            throw invalidResponse();
+        const stdout = decodeBytes(result.stdout ?? '', MAX_OUTPUT_BYTES);
+        const stderr = decodeBytes(result.stderr ?? '', MAX_OUTPUT_BYTES);
+        if (stdout.length + stderr.length > MAX_OUTPUT_BYTES)
+            throw invalidResponse();
+        return { exitCode: result.exit_code, stdout: stdout.toString('utf8'), stderr: stderr.toString('utf8') };
+    }
+    async readFile(path, options = {}) {
+        const result = await this.operation({ kind: 'file_read', path: guestPath(path), timeout_ms: operationTimeout(options) });
+        if (result.kind !== 'file_read')
+            throw invalidResponse();
+        return decodeBytes(result.data, MAX_OUTPUT_BYTES);
+    }
+    async writeFile(path, data, options = {}) {
+        const bytes = inputBytes(data);
+        if (bytes.length > 65_536)
+            throw new VerifyError('INVALID_ARGUMENT', 'writeFile() takes at most 65536 bytes.');
+        const result = await this.operation({ kind: 'file_write', path: guestPath(path), data: bytes.toString('base64'), timeout_ms: operationTimeout(options) });
+        if (result.kind !== 'file_write' || result.byte_count !== bytes.length)
+            throw invalidResponse();
+    }
+    async stat(path, options = {}) {
+        const result = await this.operation({ kind: 'file_stat', path: guestPath(path), timeout_ms: operationTimeout(options) });
+        if (result.kind !== 'file_stat' || !['file', 'directory'].includes(result.file_kind) || !Number.isSafeInteger(result.size_bytes) || result.size_bytes < 0)
+            throw invalidResponse();
+        return { kind: result.file_kind, size: result.size_bytes };
+    }
+    async processes(options = {}) {
+        const result = await this.operation({ kind: 'process_list', timeout_ms: operationTimeout(options) });
+        if (result.kind !== 'process_list' || !Array.isArray(result.processes) || result.processes.length > 64)
+            throw invalidResponse();
+        const ids = new Set();
+        return result.processes.map((process) => {
+            if (!process || process.handle?.computer_session_id !== this.id || !UUID.test(process.handle.handle_id) || !['running', 'exited'].includes(process.state) || (process.exit_code != null && (!Number.isInteger(process.exit_code) || process.exit_code < -255 || process.exit_code > 255)) || (process.state === 'running' && process.exit_code != null) || ids.has(process.handle.handle_id))
+                throw invalidResponse();
+            ids.add(process.handle.handle_id);
+            return { id: process.handle.handle_id, state: process.state, ...(process.exit_code != null ? { exitCode: process.exit_code } : {}) };
+        });
+    }
+    async terminate(processId, options = {}) {
+        if (typeof processId !== 'string' || !UUID.test(processId))
+            throw new VerifyError('INVALID_ARGUMENT', 'terminate() takes a process handle id from processes(), not an OS PID.');
+        const result = await this.operation({ kind: 'process_terminate', handle: { computer_session_id: this.id, handle_id: processId }, timeout_ms: operationTimeout(options) });
+        if (result.kind !== 'process_terminate' || result.termination !== 'confirmed')
+            throw invalidResponse();
+    }
+    close() {
+        this.closePromise ??= (async () => {
+            this.lifetime.abort();
+            try {
+                const report = this.report(await this.request('POST', '/stop', undefined, AbortSignal.timeout(310_000)));
+                if (report.release !== 'confirmed') {
+                    throw new VerifyError('ACTION_UNCERTAIN', `Computer stop was requested, but physical release is unconfirmed. Inspect ${this.viewerUrl}`);
+                }
+                if (!['stopped', 'failed', 'owner_lost'].includes(report.state))
+                    throw invalidResponse();
+                this.log('closed');
+            }
+            catch (error) {
+                if (isVerifyError(error) && error.code === 'ACTION_UNCERTAIN') {
+                    const message = `${error.message} A possible cause is that no Mac computer could be assigned. ${MAC_AVAILABILITY}`;
+                    this.log(`close failed (ACTION_UNCERTAIN); ${message}`);
+                    throw new VerifyError('ACTION_UNCERTAIN', message, { cause: error });
+                }
+                this.log(`close failed (${isVerifyError(error) ? error.code : 'API_ERROR'}); inspect ${this.viewerUrl}`);
+                throw error;
+            }
+            finally {
+                untrackSession(this);
+            }
+        })();
+        return this.closePromise;
+    }
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+    async operation(command, allowNonzero = false) {
+        this.assertOpen();
+        const requestId = randomUUID();
+        const operationId = computerOperationId(this.id, requestId);
+        const signal = AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(310_000)]);
+        try {
+            let response = await this.request('POST', '/operations', { computer_session_id: this.id, request_id: requestId, command }, signal);
+            for (;;) {
+                if (response.status !== 202) {
+                    const body = parseComputerJson(response);
+                    if (body?.computer_session_id !== this.id || body.operation_id !== operationId || !['recorded', 'pending', 'failed'].includes(body.evidence) || !body.execution)
+                        throw invalidResponse();
+                    const execution = body.execution;
+                    if (execution.outcome === 'succeeded' || (execution.outcome === 'failed' && execution.error_code === 'exec_nonzero' && allowNonzero)) {
+                        const result = execution.result;
+                        if (!result || result.kind !== command.kind || (execution.outcome === 'succeeded' && result.kind === 'exec' && result.exit_code !== 0) || (execution.outcome === 'failed' && result.kind === 'exec' && result.exit_code === 0))
+                            throw invalidResponse();
+                        if (body.evidence !== 'recorded')
+                            this.log(`operation ${operationId}: execution observed, report evidence ${body.evidence}`);
+                        return result;
+                    }
+                    if (execution.outcome === 'failed') {
+                        if (execution.error_code === 'exec_nonzero' && (execution.result?.kind !== 'exec' || !Number.isInteger(execution.result.exit_code) || execution.result.exit_code === 0 || command.kind !== 'exec'))
+                            throw invalidResponse();
+                        const code = { exec_nonzero: 'COMMAND_FAILED', not_found: 'NOT_FOUND', access_denied: 'ACCESS_DENIED' }[execution.error_code];
+                        if (!code)
+                            throw invalidResponse();
+                        throw new VerifyError(code, `Computer ${command.kind} failed (${execution.error_code}${execution.result ? `, exit code ${execution.result.exit_code}` : ''}). See ${this.viewerUrl}`);
+                    }
+                    if (execution.outcome === 'timed_out') {
+                        if (execution.termination === 'unknown')
+                            throw new VerifyError('ACTION_UNCERTAIN', `Computer ${command.kind} timed out; termination is unconfirmed. Verify will not repeat it. See ${this.viewerUrl}`);
+                        if (execution.termination !== 'confirmed')
+                            throw invalidResponse();
+                        throw new VerifyError('TIMEOUT', `Computer ${command.kind} timed out; termination was confirmed. See ${this.viewerUrl}`);
+                    }
+                    if (execution.outcome !== 'unknown')
+                        throw invalidResponse();
+                    throw new VerifyError('ACTION_UNCERTAIN', `Computer ${command.kind} outcome is unconfirmed. Verify will not repeat it. Inspect operation ${operationId} at ${this.viewerUrl}`);
+                }
+                if (parseComputerJson(response) !== null)
+                    throw invalidResponse();
+                await delay(2_000, undefined, { signal });
+                response = await this.request('GET', `/operations/${operationId}`, undefined, signal);
+            }
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw new VerifyError('ACTION_UNCERTAIN', `Computer operation ${operationId} stopped being observed; its outcome is unconfirmed. See ${this.viewerUrl}`);
+            throw error;
+        }
+    }
+    async request(method, suffix, body, signal) {
+        const path = `/api/v1/computer-runs${suffix === '' ? '' : `/${this.id}${suffix}`}`;
+        let response;
+        try {
+            response = await this.client.send(method, path, { body, signal, timeoutMs: suffix === '/stop' || suffix.startsWith('/operations') ? 310_000 : 30_000, retry: method === 'GET', headers: suffix === '/operations' ? { Prefer: 'respond-async' } : undefined });
+        }
+        catch (error) {
+            if (method === 'POST' || suffix.startsWith('/operations/'))
+                throw new VerifyError('ACTION_UNCERTAIN', `Computer request outcome is unconfirmed. Verify will not repeat it. See ${this.viewerUrl}`);
+            if (isVerifyError(error))
+                throw new VerifyError(error.code, `Could not read the computer state. See ${this.viewerUrl}`);
+            throw error;
+        }
+        if (response.status >= 200 && response.status < 300)
+            return response;
+        const detail = responseDetail(response);
+        if (detail === 'computer_not_enabled' || (method === 'POST' && suffix === '' && response.status === 503 && detail === 'runtime_unavailable')) {
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `Revyl refused the computer request (${detail}). ${MAC_AVAILABILITY}. Ask support@revyl.ai about staging organization enablement. See ${this.viewerUrl}`);
+        }
+        let code = 'API_ERROR';
+        if (detail === 'run_closed')
+            code = 'SESSION_ENDED';
+        else if (detail === 'inaccessible' || detail === 'invalid_handle')
+            code = 'NOT_FOUND';
+        else if (detail === 'operation_not_found' || detail === 'owner_unavailable')
+            code = 'ACTION_UNCERTAIN';
+        else if (detail === 'invalid_request' || response.status === 422)
+            code = 'INVALID_ARGUMENT';
+        else if (response.status === 401 || response.status === 403)
+            code = 'AUTH_REJECTED';
+        else if (detail === 'runtime_unavailable' || detail === 'start_failed' || detail === 'computer_limit')
+            code = 'SESSION_START_FAILED';
+        else if (response.status === 409 || detail === 'operation_limit')
+            code = 'SESSION_BUSY';
+        else if (suffix.startsWith('/operations/') && response.status >= 500)
+            code = 'ACTION_UNCERTAIN';
+        else if (method === 'POST' && (response.status >= 500 || response.status < 400))
+            code = 'ACTION_UNCERTAIN';
+        const reason = detail && ERROR_CODES.has(detail) ? detail : `HTTP ${response.status}`;
+        throw new VerifyError(code, `Revyl refused the computer request (${reason}). See ${this.viewerUrl}`);
+    }
+    report(response) {
+        const report = parseComputerJson(response);
+        if (!report || report.computer_session_id !== this.id || !STATES.has(report.state))
+            throw invalidResponse();
+        return report;
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new VerifyError('SESSION_ENDED', `The ${this.target} computer was closed.`);
+    }
+    unavailable(method) {
+        return Promise.reject(new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `${method}() is not available on mac computers; use exec() and file operations. See ${this.viewerUrl}`));
+    }
+    log(line) {
+        this.options.log?.(`${this.target}: ${line}`);
+    }
+}
+export function computerOperationId(sessionId, requestId) {
+    const hash = createHash('sha1').update(Buffer.from(sessionId.replaceAll('-', ''), 'hex')).update(requestId).digest();
+    hash[6] = (hash[6] & 0x0f) | 0x50;
+    hash[8] = (hash[8] & 0x3f) | 0x80;
+    const hex = hash.subarray(0, 16).toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function operationTimeout(options) {
+    const timeout = options.timeout ?? 30_000;
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > 300_000)
+        throw new VerifyError('INVALID_ARGUMENT', 'Computer operation timeout must be an integer from 1 to 300000 ms.');
+    return timeout;
+}
+function guestPath(path) {
+    if (typeof path !== 'string' || !path || Buffer.byteLength(path) > 1024 || path.split('/').some((part) => ['', '.', '..'].includes(part)) || /[\x00-\x1f\x7f\\:]/.test(path))
+        throw new VerifyError('INVALID_ARGUMENT', 'Computer paths must be workspace-relative, without empty, dot, parent, backslash, colon, or control-character components.');
+    return path;
+}
+function inputBytes(value) {
+    if (typeof value !== 'string' && !(value instanceof Uint8Array))
+        throw new VerifyError('INVALID_ARGUMENT', 'Computer input must be a string or Uint8Array.');
+    return Buffer.from(value);
+}
+function decodeBytes(value, maxBytes) {
+    if (typeof value !== 'string' || value.length > Math.ceil(maxBytes / 3) * 4 || value.length % 4 !== 0 || !/^[a-zA-Z0-9+/_-]*={0,2}$/.test(value))
+        throw invalidResponse();
+    const bytes = Buffer.from(value, 'base64');
+    if (bytes.length > maxBytes || bytes.toString('base64') !== value.replaceAll('-', '+').replaceAll('_', '/'))
+        throw invalidResponse();
+    return bytes;
+}
+function invalidResponse() {
+    return new VerifyError('API_ERROR', 'Revyl returned an invalid computer response.');
+}
+function parseComputerJson(response) {
+    try {
+        return JSON.parse(new TextDecoder().decode(response.body));
+    }
+    catch {
+        throw invalidResponse();
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,88 @@
+import type { ComputerPlatform, MobilePlatform } from './api/types.js';
+export interface WebAppConfig {
+    /** The Revyl web app this target belongs to. */
+    appId: string;
+    /** A public HTTPS URL to open, such as a preview deployment. Registered as a build each time a session opens. */
+    url?: string;
+    /** An exact Revyl build to open instead of a URL. */
+    buildId?: string;
+    /** Revyl branch to register the URL on, or to take the newest build from. */
+    branch?: string;
+}
+export interface WebTargetConfig {
+    platform: 'web';
+    app: WebAppConfig;
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+    };
+    /** A test-only sign-in route Revyl opens before the session starts. See docs/web.md. */
+    signIn?: {
+        path: string;
+        secret: string;
+        persona?: string;
+    };
+    startTimeout?: number;
+    idleTimeoutSeconds?: number;
+}
+export interface MobileAppConfig {
+    /** A Revyl app; the session installs its newest build. */
+    appId?: string;
+    /** An exact Revyl build to install. */
+    buildId?: string;
+    /** A downloadable .apk, .app.zip or .ipa to install. */
+    artifactUrl?: string;
+    /** An app already on the device to launch instead of installing one, such as a system app. */
+    bundleId?: string;
+}
+export interface MobileTargetConfig {
+    platform: MobilePlatform;
+    app: MobileAppConfig;
+    device?: {
+        model?: string;
+        osVersion?: string;
+    };
+    startTimeout?: number;
+    idleTimeoutSeconds?: number;
+}
+/** A Revyl computer: a cloud macOS machine that runs commands and files instead of agent steps. See docs/computers.md. */
+export interface ComputerTargetConfig {
+    platform: ComputerPlatform;
+    startTimeout?: number;
+}
+export type TargetConfig = WebTargetConfig | MobileTargetConfig | ComputerTargetConfig;
+export interface VerifyConfig {
+    /** Named targets that open() takes by name, such as open('web'). */
+    targets: Record<string, TargetConfig>;
+    /** Milliseconds one instruction or validation may run. Defaults to 180000. */
+    stepTimeout?: number;
+}
+type Resolved<T> = T & {
+    name: string;
+    startTimeout: number;
+};
+export type ResolvedDeviceTarget = Resolved<(WebTargetConfig | MobileTargetConfig) & {
+    idleTimeoutSeconds: number;
+}>;
+export type ResolvedComputerTarget = Resolved<ComputerTargetConfig & ({
+    platform: 'mac';
+} | {
+    platform: 'linux';
+})>;
+export type ResolvedTarget = ResolvedDeviceTarget | ResolvedComputerTarget;
+export interface ResolvedConfig {
+    configFile: string;
+    targets: Record<string, ResolvedTarget>;
+    stepTimeout: number;
+}
+export declare const CONFIG_FILE_NAMES: string[];
+export declare const DEFAULT_STEP_TIMEOUT_MS = 180000;
+export declare function defineConfig(config: VerifyConfig): VerifyConfig;
+/** The nearest verify.config file in the folder or any folder above it. */
+export declare function findConfigFile(startDir: string): string | undefined;
+export declare function loadConfig(cwd: string, explicitPath?: string): Promise<ResolvedConfig>;
+export declare function validateConfig(raw: unknown, configFile: string): ResolvedConfig;
+/** Validates a target passed straight to open(); it is named after its platform. */
+export declare function validateTarget(raw: unknown): ResolvedTarget;
+export {};

package/dist/config.js

@@ -0,0 +1,212 @@
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { createJiti } from 'jiti';
+import { VerifyError } from './errors.js';
+import { PACKAGE_NAME } from './version.js';
+export const CONFIG_FILE_NAMES = ['verify.config.ts', 'verify.config.mts', 'verify.config.js', 'verify.config.mjs'];
+export const DEFAULT_STEP_TIMEOUT_MS = 180_000;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const WEB_URL = /^https:\/\/[^/?#@\s]+(\/[^?#\s]*)?$/;
+const TARGET_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+const PLATFORMS = ['web', 'ios', 'android', 'mac', 'linux'];
+export function defineConfig(config) {
+    return config;
+}
+/** The nearest verify.config file in the folder or any folder above it. */
+export function findConfigFile(startDir) {
+    for (let dir = resolve(startDir);; dir = dirname(dir)) {
+        for (const name of CONFIG_FILE_NAMES) {
+            const candidate = resolve(dir, name);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        if (dirname(dir) === dir)
+            return undefined;
+    }
+}
+export async function loadConfig(cwd, explicitPath) {
+    const configFile = explicitPath ? resolve(cwd, explicitPath) : findConfigFile(cwd);
+    if (!configFile || !existsSync(configFile)) {
+        throw new VerifyError('CONFIG_NOT_FOUND', explicitPath
+            ? `Config file not found: ${explicitPath}`
+            : `No verify.config.ts in ${cwd} or any folder above it. Run 'npx ${PACKAGE_NAME} init' to create one, or pass a target object to open().`);
+    }
+    const jiti = createJiti(import.meta.url, { moduleCache: false, interopDefault: true });
+    let loaded;
+    try {
+        loaded = await jiti.import(configFile, { default: true });
+    }
+    catch (error) {
+        throw new VerifyError('CONFIG_INVALID', `Could not load ${configFile}: ${error.message}`, { cause: error });
+    }
+    return validateConfig(loaded, configFile);
+}
+export function validateConfig(raw, configFile) {
+    const fail = (path, problem) => {
+        throw new VerifyError('CONFIG_INVALID', `${configFile}: ${path} ${problem}`);
+    };
+    const config = asRecord(raw, 'the default export', fail);
+    rejectUnknownKeys(config, ['targets', 'stepTimeout'], '', fail);
+    const rawTargets = asRecord(config.targets, 'targets', fail);
+    const names = Object.keys(rawTargets);
+    if (names.length === 0)
+        fail('targets', 'must name at least one target, such as { web: { platform: \'web\', ... } }.');
+    const targets = {};
+    for (const name of names) {
+        if (!TARGET_NAME.test(name))
+            fail(`targets.${name}`, 'must be named with 1-64 letters, digits, dots, dashes, or underscores.');
+        targets[name] = parseTarget(rawTargets[name], name, `targets.${name}`, fail);
+    }
+    return {
+        configFile,
+        targets,
+        stepTimeout: integer(config.stepTimeout, 'stepTimeout', 1_000, 3_600_000, DEFAULT_STEP_TIMEOUT_MS, fail),
+    };
+}
+/** Validates a target passed straight to open(); it is named after its platform. */
+export function validateTarget(raw) {
+    const fail = (path, problem) => {
+        throw new VerifyError('INVALID_ARGUMENT', `open(): ${path} ${problem}`);
+    };
+    const platform = asRecord(raw, 'target', fail).platform;
+    return parseTarget(raw, typeof platform === 'string' ? platform : 'target', 'target', fail);
+}
+function parseTarget(raw, name, path, fail) {
+    const target = asRecord(raw, path, fail);
+    const platform = target.platform;
+    if (typeof platform !== 'string' || !PLATFORMS.includes(platform)) {
+        fail(`${path}.platform`, "must be 'web', 'ios', 'android', 'mac', or 'linux'.");
+    }
+    const startTimeout = integer(target.startTimeout, `${path}.startTimeout`, 10_000, 1_800_000, 600_000, fail);
+    if (platform === 'mac' || platform === 'linux') {
+        rejectUnknownKeys(target, ['platform', 'startTimeout'], path, fail);
+        return { name, startTimeout, platform };
+    }
+    const common = {
+        name,
+        startTimeout,
+        idleTimeoutSeconds: integer(target.idleTimeoutSeconds, `${path}.idleTimeoutSeconds`, 60, 3_600, 600, fail),
+    };
+    const app = asRecord(target.app, `${path}.app`, fail);
+    if (platform === 'web') {
+        rejectUnknownKeys(target, ['platform', 'app', 'viewport', 'signIn', 'startTimeout', 'idleTimeoutSeconds'], path, fail);
+        rejectUnknownKeys(app, ['appId', 'url', 'buildId', 'branch'], `${path}.app`, fail);
+        uuid(app.appId, `${path}.app.appId`, true, fail);
+        uuid(app.buildId, `${path}.app.buildId`, false, fail);
+        if (app.url !== undefined && (typeof app.url !== 'string' || app.url.length > 2048 || !WEB_URL.test(app.url))) {
+            fail(`${path}.app.url`, 'must be a public HTTPS URL without credentials, query, or fragment. Revyl cannot reach localhost.');
+        }
+        if (app.url !== undefined && app.buildId !== undefined)
+            fail(`${path}.app`, 'takes url or buildId, not both.');
+        optionalString(app.branch, `${path}.app.branch`, 255, fail);
+        if (app.branch !== undefined && app.buildId !== undefined)
+            fail(`${path}.app`, 'takes branch or buildId, not both.');
+        let viewport;
+        if (target.viewport !== undefined) {
+            const raw = asRecord(target.viewport, `${path}.viewport`, fail);
+            rejectUnknownKeys(raw, ['width', 'height', 'deviceScaleFactor'], `${path}.viewport`, fail);
+            viewport = {
+                width: integer(raw.width, `${path}.viewport.width`, 320, 3840, undefined, fail),
+                height: integer(raw.height, `${path}.viewport.height`, 240, 2160, undefined, fail),
+            };
+            if (raw.deviceScaleFactor !== undefined) {
+                const factor = raw.deviceScaleFactor;
+                if (typeof factor !== 'number' || !(factor >= 1 && factor <= 3))
+                    fail(`${path}.viewport.deviceScaleFactor`, 'must be from 1 to 3.');
+                viewport.deviceScaleFactor = factor;
+            }
+        }
+        let signIn;
+        if (target.signIn !== undefined) {
+            const raw = asRecord(target.signIn, `${path}.signIn`, fail);
+            rejectUnknownKeys(raw, ['path', 'secret', 'persona'], `${path}.signIn`, fail);
+            if (typeof raw.path !== 'string' || !/^\/(?!\/)[^?#\\\s]{0,511}$/.test(raw.path)) {
+                fail(`${path}.signIn.path`, 'must be a path starting with one / and no query, fragment, or whitespace.');
+            }
+            if (typeof raw.secret !== 'string' || raw.secret.trim() === '') {
+                fail(`${path}.signIn.secret`, 'must name an organization secret launch variable (its name, never its value).');
+            }
+            if (raw.persona !== undefined && (typeof raw.persona !== 'string' || !/^[a-z0-9_-]{1,32}$/.test(raw.persona))) {
+                fail(`${path}.signIn.persona`, 'must match [a-z0-9_-]{1,32}.');
+            }
+            signIn = { path: raw.path, secret: raw.secret, ...(raw.persona ? { persona: raw.persona } : {}) };
+        }
+        return {
+            ...common,
+            platform: 'web',
+            app: {
+                appId: app.appId,
+                ...(app.url !== undefined ? { url: app.url } : {}),
+                ...(app.buildId !== undefined ? { buildId: app.buildId } : {}),
+                ...(app.branch !== undefined ? { branch: app.branch } : {}),
+            },
+            ...(viewport ? { viewport } : {}),
+            ...(signIn ? { signIn } : {}),
+        };
+    }
+    rejectUnknownKeys(target, ['platform', 'app', 'device', 'startTimeout', 'idleTimeoutSeconds'], path, fail);
+    rejectUnknownKeys(app, ['appId', 'buildId', 'artifactUrl', 'bundleId'], `${path}.app`, fail);
+    uuid(app.appId, `${path}.app.appId`, false, fail);
+    uuid(app.buildId, `${path}.app.buildId`, false, fail);
+    optionalString(app.bundleId, `${path}.app.bundleId`, 255, fail);
+    if (app.artifactUrl !== undefined && (typeof app.artifactUrl !== 'string' || !/^https:\/\//.test(app.artifactUrl))) {
+        fail(`${path}.app.artifactUrl`, 'must be an HTTPS URL.');
+    }
+    const sources = [app.appId, app.buildId, app.artifactUrl, app.bundleId].filter((value) => value !== undefined).length;
+    if (sources !== 1) {
+        fail(`${path}.app`, 'takes exactly one of appId, buildId, or artifactUrl to install an app, or bundleId to open one already on the device.');
+    }
+    let device;
+    if (target.device !== undefined) {
+        const raw = asRecord(target.device, `${path}.device`, fail);
+        rejectUnknownKeys(raw, ['model', 'osVersion'], `${path}.device`, fail);
+        optionalString(raw.model, `${path}.device.model`, 128, fail);
+        optionalString(raw.osVersion, `${path}.device.osVersion`, 64, fail);
+        device = {
+            ...(raw.model !== undefined ? { model: raw.model } : {}),
+            ...(raw.osVersion !== undefined ? { osVersion: raw.osVersion } : {}),
+        };
+    }
+    return {
+        ...common,
+        platform: platform,
+        app: {
+            ...(app.appId !== undefined ? { appId: app.appId } : {}),
+            ...(app.buildId !== undefined ? { buildId: app.buildId } : {}),
+            ...(app.artifactUrl !== undefined ? { artifactUrl: app.artifactUrl } : {}),
+            ...(app.bundleId !== undefined ? { bundleId: app.bundleId } : {}),
+        },
+        ...(device ? { device } : {}),
+    };
+}
+function asRecord(raw, path, fail) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        fail(path, 'must be an object.');
+    return raw;
+}
+function rejectUnknownKeys(record, allowed, path, fail) {
+    for (const key of Object.keys(record)) {
+        if (!allowed.includes(key))
+            fail(path ? `${path}.${key}` : key, `is not a known option. Known: ${allowed.join(', ')}.`);
+    }
+}
+function integer(raw, path, min, max, fallback, fail) {
+    if (raw === undefined && fallback !== undefined)
+        return fallback;
+    if (typeof raw !== 'number' || !Number.isInteger(raw) || raw < min || raw > max)
+        fail(path, `must be an integer from ${min} to ${max}.`);
+    return raw;
+}
+function uuid(raw, path, required, fail) {
+    if (raw === undefined && !required)
+        return;
+    if (typeof raw !== 'string' || !UUID.test(raw)) {
+        fail(path, `${required ? 'is required and ' : ''}must be a Revyl id (a UUID); copy it from the app's page in Revyl.`);
+    }
+}
+function optionalString(raw, path, maxLength, fail) {
+    if (raw === undefined)
+        return;
+    if (typeof raw !== 'string' || raw.trim() === '' || raw.length > maxLength)
+        fail(path, `must be a non-empty string of at most ${maxLength} characters.`);
+}