visor-ai 0.2.1

package/dist/cli.js

@@ -0,0 +1,610 @@
+import { DEFAULT_SERVER_URL, getAdapter } from './adapters.js';
+import { DEFAULT_STARTUP_TIMEOUT_SECONDS, isAppiumReachable, startManagedAppium, statusManagedAppium, stopManagedAppium } from './appiumLifecycle.js';
+import { makeError } from './errors.js';
+import { writeReports } from './report.js';
+import { determinismCheck, runScenario } from './runner.js';
+import { errorMessage, makeId, utcNowIso } from './utils.js';
+import { parseAndValidate } from './validator.js';
+const ACTION_COMMANDS = new Set([
+    'tap',
+    'navigate',
+    'act',
+    'screenshot',
+    'wait',
+    'source'
+]);
+const ALL_COMMANDS = new Set([
+    ...ACTION_COMMANDS,
+    'validate',
+    'run',
+    'benchmark',
+    'report',
+    'start',
+    'status',
+    'stop'
+]);
+const GLOBAL_SPEC = {
+    platform: 'string',
+    device: 'string',
+    timeout: 'number',
+    output: 'string',
+    format: 'string',
+    seed: 'number',
+    'server-url': 'string',
+    'app-id': 'string',
+    'appium-cmd': 'string',
+    'startup-timeout': 'number',
+    'no-auto-start-appium': 'boolean',
+    attach: 'boolean',
+    mock: 'boolean',
+    verbose: 'boolean'
+};
+const ACTION_SPEC = {
+    ...GLOBAL_SPEC,
+    target: 'string',
+    x: 'number',
+    y: 'number',
+    normalized: 'boolean',
+    to: 'string',
+    name: 'string',
+    value: 'string',
+    label: 'string',
+    ms: 'number',
+    path: 'string'
+};
+const COMMAND_SPECS = {
+    validate: { format: 'string' },
+    run: {
+        platform: 'string',
+        device: 'string',
+        timeout: 'number',
+        output: 'string',
+        format: 'string',
+        'server-url': 'string',
+        'app-id': 'string',
+        'appium-cmd': 'string',
+        'startup-timeout': 'number',
+        'no-auto-start-appium': 'boolean',
+        attach: 'boolean',
+        mock: 'boolean'
+    },
+    benchmark: {
+        runs: 'number',
+        threshold: 'number',
+        platform: 'string',
+        device: 'string',
+        timeout: 'number',
+        output: 'string',
+        format: 'string',
+        'server-url': 'string',
+        'app-id': 'string',
+        'appium-cmd': 'string',
+        'startup-timeout': 'number',
+        'no-auto-start-appium': 'boolean',
+        attach: 'boolean',
+        mock: 'boolean'
+    },
+    report: { format: 'string' },
+    start: {
+        'server-url': 'string',
+        'appium-cmd': 'string',
+        'startup-timeout': 'number',
+        format: 'string'
+    },
+    status: {
+        'server-url': 'string',
+        format: 'string'
+    },
+    stop: {
+        'server-url': 'string',
+        force: 'boolean',
+        format: 'string'
+    },
+    tap: ACTION_SPEC,
+    navigate: ACTION_SPEC,
+    act: ACTION_SPEC,
+    screenshot: ACTION_SPEC,
+    wait: ACTION_SPEC,
+    source: ACTION_SPEC
+};
+function helpText() {
+    return [
+        'Visor TypeScript CLI',
+        '',
+        'Usage:',
+        '  visor <command> [options]',
+        '  visor --help',
+        '',
+        'Commands:',
+        '  validate <scenario>',
+        '  run <scenario> [--mock] [--output <dir>]',
+        '  benchmark <scenario> [--runs <n>] [--threshold <percent>]',
+        '  report [path]',
+        '  start [--server-url <url>]',
+        '  status [--server-url <url>]',
+        '  stop [--server-url <url>] [--force]',
+        '  tap|navigate|act|screenshot|wait|source',
+        '',
+        'Examples:',
+        '  visor validate scenarios/checkout-smoke.json',
+        '  visor run scenarios/checkout-smoke.json --mock --output artifacts-test',
+        '  node dist/main.js status'
+    ].join('\n');
+}
+function envelopeOk(commandId, startedAt, artifacts = [], nextAction = '') {
+    return {
+        status: 'ok',
+        command_id: commandId,
+        started_at: startedAt,
+        ended_at: utcNowIso(),
+        artifacts,
+        next_action: nextAction,
+        data: {}
+    };
+}
+function envelopeFail(commandId, startedAt, code, message, cause, nextStep) {
+    return {
+        status: 'fail',
+        command_id: commandId,
+        started_at: startedAt,
+        ended_at: utcNowIso(),
+        artifacts: [],
+        next_action: nextStep,
+        error: makeError(code, message, cause, nextStep),
+        data: {}
+    };
+}
+function parseOptions(tokens, spec) {
+    const options = {};
+    const positionals = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (!token.startsWith('--')) {
+            positionals.push(token);
+            continue;
+        }
+        const optionName = token.slice(2);
+        const optionType = spec[optionName];
+        if (!optionType) {
+            throw new Error(`Unknown option '--${optionName}'`);
+        }
+        if (optionType === 'boolean') {
+            options[optionName] = true;
+            continue;
+        }
+        const rawValue = tokens[index + 1];
+        if (rawValue === undefined || rawValue.startsWith('--')) {
+            throw new Error(`Option '--${optionName}' requires a value`);
+        }
+        options[optionName] = optionType === 'number' ? Number(rawValue) : rawValue;
+        index += 1;
+    }
+    return { options, positionals };
+}
+function parseCommand(argv) {
+    const commandIndex = argv.findIndex((token) => ALL_COMMANDS.has(token));
+    if (commandIndex === -1) {
+        throw new Error('Missing command');
+    }
+    const globalTokens = argv.slice(0, commandIndex);
+    const command = argv[commandIndex];
+    const commandTokens = argv.slice(commandIndex + 1);
+    const globalParsed = parseOptions(globalTokens, GLOBAL_SPEC);
+    const commandParsed = parseOptions(commandTokens, COMMAND_SPECS[command] ?? {});
+    return {
+        command,
+        options: {
+            ...globalParsed.options,
+            ...commandParsed.options
+        },
+        positionals: [...globalParsed.positionals, ...commandParsed.positionals]
+    };
+}
+function warningIssues(issues) {
+    return issues.filter((issue) => issue.severity === 'warning');
+}
+function resolvedRuntime(options, scenario) {
+    const platform = String(options.platform ?? scenario.meta.platform);
+    const defaultDevice = platform === 'android' ? 'emulator-5554' : 'iPhone 17 Pro';
+    scenario.meta.platform = platform;
+    return {
+        platform,
+        device: String(options.device ?? defaultDevice),
+        timeout: typeof options.timeout === 'number'
+            ? options.timeout
+            : typeof scenario.config.timeoutMs === 'number'
+                ? scenario.config.timeoutMs
+                : 2500,
+        output_dir: String(options.output ?? scenario.config.artifactsDir ?? 'artifacts'),
+        server_url: String(options['server-url'] ?? DEFAULT_SERVER_URL),
+        use_mock: Boolean(options.mock),
+        app_id: typeof options['app-id'] === 'string' ? options['app-id'] : undefined,
+        attach_to_running: Boolean(options.attach),
+        auto_start_appium: !Boolean(options['no-auto-start-appium']),
+        appium_cmd: typeof options['appium-cmd'] === 'string' ? options['appium-cmd'] : undefined,
+        startup_timeout: typeof options['startup-timeout'] === 'number'
+            ? options['startup-timeout']
+            : DEFAULT_STARTUP_TIMEOUT_SECONDS
+    };
+}
+async function ensureNonMockRuntime(options) {
+    if (await isAppiumReachable(options.server_url, 2000)) {
+        return {
+            serverUrl: options.server_url,
+            started: false
+        };
+    }
+    if (!options.auto_start_appium) {
+        throw new Error(`Cannot reach Appium server at ${options.server_url}. Start Appium and ensure ${options.platform} target '${options.device}' is booted.`);
+    }
+    return startManagedAppium(options.server_url, options.appium_cmd, options.startup_timeout);
+}
+async function stopAutoStartedAppium(runtimeState) {
+    if (!runtimeState || !runtimeState.started || typeof runtimeState.serverUrl !== 'string') {
+        return;
+    }
+    try {
+        await stopManagedAppium(runtimeState.serverUrl, false);
+    }
+    catch {
+        await stopManagedAppium(runtimeState.serverUrl, true);
+    }
+}
+function actionArgs(command, options) {
+    const commonIgnored = new Set([
+        'platform',
+        'device',
+        'format',
+        'output',
+        'timeout',
+        'verbose',
+        'server-url',
+        'mock',
+        'seed',
+        'app-id',
+        'attach',
+        'appium-cmd',
+        'startup-timeout',
+        'no-auto-start-appium'
+    ]);
+    const args = Object.entries(options).reduce((acc, [key, value]) => {
+        if (!commonIgnored.has(key) && value !== undefined) {
+            acc[key] = value;
+        }
+        return acc;
+    }, {});
+    if (command === 'source' && args.label === undefined) {
+        args.label = 'source';
+    }
+    return args;
+}
+function cmdHelp() {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    const response = envelopeOk(commandId, startedAt, [], 'validate');
+    response.data = {
+        usageText: helpText(),
+        commands: Array.from(ALL_COMMANDS),
+        examples: [
+            'visor validate scenarios/checkout-smoke.json',
+            'visor run scenarios/checkout-smoke.json --mock --output artifacts-test',
+            'node dist/main.js status'
+        ]
+    };
+    return { code: 0, response };
+}
+export async function cmdValidate(parsed) {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    const scenarioPath = parsed.positionals[0];
+    try {
+        if (!scenarioPath) {
+            throw new Error('validate requires a scenario path');
+        }
+        const { scenario, issues } = parseAndValidate(scenarioPath);
+        const response = envelopeOk(commandId, startedAt, [], 'run');
+        response.data = {
+            valid: scenario !== null,
+            issues
+        };
+        return {
+            code: scenario ? 0 : 1,
+            response
+        };
+    }
+    catch (error) {
+        const response = envelopeFail(commandId, startedAt, 'INPUT_ERROR', 'Validation failed', errorMessage(error), 'Fix scenario JSON and rerun validate');
+        return { code: 1, response };
+    }
+}
+export async function cmdRun(parsed) {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    const scenarioPath = parsed.positionals[0];
+    const { scenario, issues } = parseAndValidate(String(scenarioPath ?? ''));
+    if (!scenario) {
+        const response = envelopeFail(commandId, startedAt, 'INPUT_ERROR', 'Scenario validation failed', 'One or more schema violations', 'Run `visor validate <file>` and resolve errors');
+        response.data = { issues };
+        return { code: 1, response };
+    }
+    const runtime = resolvedRuntime(parsed.options, scenario);
+    let runtimeState;
+    let cleanupError;
+    try {
+        if (!runtime.use_mock) {
+            runtimeState = await ensureNonMockRuntime(runtime);
+        }
+        const adapter = await getAdapter(runtime.platform, runtime.server_url, runtime.device, runtime.use_mock, runtime.app_id, runtime.attach_to_running);
+        const result = await runScenario(scenario, adapter, runtime.device, runtime.timeout, runtime.output_dir);
+        const outputs = writeReports(result, runtime.output_dir);
+        await stopAutoStartedAppium(runtimeState);
+        if (result.status === 'fail' && result.error) {
+            const response = envelopeFail(commandId, startedAt, result.error.code, result.error.message, result.error.likely_cause, result.error.next_step);
+            response.artifacts = Object.values(outputs);
+            response.data = {
+                run: result,
+                warnings: warningIssues(issues)
+            };
+            return { code: 2, response };
+        }
+        const response = envelopeOk(commandId, startedAt, Object.values(outputs), 'report');
+        response.data = {
+            run: result,
+            warnings: warningIssues(issues)
+        };
+        return { code: 0, response };
+    }
+    catch (error) {
+        const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', 'Failed to initialize platform target', errorMessage(error), 'For local non-mock runs: install Node deps, run `visor start` (or remove --no-auto-start-appium), boot target emulator/simulator, and retry.');
+        return { code: 1, response };
+    }
+    finally {
+        try {
+            await stopAutoStartedAppium(runtimeState);
+        }
+        catch (error) {
+            cleanupError = error;
+        }
+    }
+}
+export async function cmdBenchmark(parsed) {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    const scenarioPath = parsed.positionals[0];
+    const { scenario, issues } = parseAndValidate(String(scenarioPath ?? ''));
+    if (!scenario) {
+        const response = envelopeFail(commandId, startedAt, 'INPUT_ERROR', 'Scenario validation failed', 'Invalid scenario', 'Fix schema errors before benchmark');
+        response.data = { issues };
+        return { code: 1, response };
+    }
+    const runtime = resolvedRuntime(parsed.options, scenario);
+    const runs = typeof parsed.options.runs === 'number' ? parsed.options.runs : 20;
+    const threshold = typeof parsed.options.threshold === 'number' ? parsed.options.threshold : 95;
+    const signatures = [];
+    const runIds = [];
+    let failures = 0;
+    let runtimeState;
+    let cleanupError;
+    if (!runtime.use_mock) {
+        try {
+            runtimeState = await ensureNonMockRuntime(runtime);
+        }
+        catch (error) {
+            const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', 'Failed benchmark preflight for non-mock runtime', errorMessage(error), 'Start Appium (or allow auto-start), verify local device target, then rerun benchmark');
+            return { code: 1, response };
+        }
+    }
+    try {
+        for (let index = 0; index < runs; index += 1) {
+            try {
+                const adapter = await getAdapter(runtime.platform, runtime.server_url, runtime.device, runtime.use_mock, runtime.app_id, runtime.attach_to_running);
+                const result = await runScenario(scenario, adapter, runtime.device, runtime.timeout, runtime.output_dir);
+                writeReports(result, runtime.output_dir);
+                signatures.push(result.determinism_signature);
+                runIds.push(result.run_id);
+                if (result.status !== 'ok') {
+                    failures += 1;
+                }
+            }
+            catch {
+                failures += 1;
+            }
+        }
+    }
+    finally {
+        try {
+            await stopAutoStartedAppium(runtimeState);
+        }
+        catch (error) {
+            cleanupError = error;
+        }
+    }
+    const score = determinismCheck(signatures);
+    const passGate = score >= threshold && failures === 0;
+    if (cleanupError) {
+        const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', 'Benchmark completed but failed to stop auto-started Appium', errorMessage(cleanupError), 'Inspect .visor/appium logs and stop Appium manually');
+        response.data = {
+            runs,
+            threshold,
+            determinismScore: score,
+            pass: false,
+            failures,
+            runIds
+        };
+        return { code: 1, response };
+    }
+    const response = envelopeOk(commandId, startedAt, [], 'report');
+    response.data = {
+        runs,
+        threshold,
+        determinismScore: score,
+        pass: passGate,
+        failures,
+        runIds,
+        warnings: warningIssues(issues)
+    };
+    return { code: passGate ? 0 : 3, response };
+}
+export async function cmdReport(parsed) {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    const reportPath = parsed.positionals[0] ?? 'artifacts';
+    const response = envelopeOk(commandId, startedAt, [], 'none');
+    response.data = {
+        message: `Use output under ${reportPath}/<run-id>/summary.txt|summary.json|junit.xml|report.html`,
+        path: reportPath,
+        format: parsed.options.format ?? 'json'
+    };
+    return { code: 0, response };
+}
+export async function cmdAction(command, parsed) {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    const options = {
+        platform: String(parsed.options.platform ?? 'android'),
+        device: typeof parsed.options.device === 'string' ? parsed.options.device : undefined,
+        server_url: String(parsed.options['server-url'] ?? DEFAULT_SERVER_URL),
+        use_mock: Boolean(parsed.options.mock),
+        app_id: typeof parsed.options['app-id'] === 'string' ? parsed.options['app-id'] : undefined,
+        attach_to_running: Boolean(parsed.options.attach),
+        auto_start_appium: !Boolean(parsed.options['no-auto-start-appium']),
+        appium_cmd: typeof parsed.options['appium-cmd'] === 'string' ? parsed.options['appium-cmd'] : undefined,
+        startup_timeout: typeof parsed.options['startup-timeout'] === 'number'
+            ? parsed.options['startup-timeout']
+            : DEFAULT_STARTUP_TIMEOUT_SECONDS
+    };
+    let runtimeState;
+    let cleanupError;
+    let payload = {};
+    let artifacts = [];
+    let actionError;
+    let adapter;
+    try {
+        if (!options.use_mock) {
+            runtimeState = await ensureNonMockRuntime({
+                platform: options.platform,
+                device: options.device ?? (options.platform === 'android' ? 'emulator-5554' : 'iPhone 17 Pro'),
+                timeout: undefined,
+                output_dir: 'artifacts',
+                server_url: options.server_url,
+                use_mock: options.use_mock,
+                app_id: options.app_id,
+                attach_to_running: options.attach_to_running,
+                auto_start_appium: options.auto_start_appium,
+                appium_cmd: options.appium_cmd,
+                startup_timeout: options.startup_timeout
+            });
+        }
+        adapter = await getAdapter(options.platform, options.server_url, options.device, options.use_mock, options.app_id, options.attach_to_running);
+        payload = await adapter[command](actionArgs(command, parsed.options));
+        const actionPayload = payload.args;
+        if (actionPayload && typeof actionPayload === 'object' && !Array.isArray(actionPayload)) {
+            const maybePath = actionPayload.path;
+            if (typeof maybePath === 'string') {
+                artifacts = [maybePath];
+            }
+        }
+    }
+    catch (error) {
+        actionError = error;
+    }
+    finally {
+        if (adapter) {
+            await adapter.close();
+        }
+        try {
+            await stopAutoStartedAppium(runtimeState);
+        }
+        catch (error) {
+            cleanupError = error;
+        }
+    }
+    if (actionError) {
+        const cause = cleanupError
+            ? `${errorMessage(actionError)}; additionally failed to stop auto-started Appium: ${errorMessage(cleanupError)}`
+            : errorMessage(actionError);
+        const response = envelopeFail(commandId, startedAt, 'ACTION_ERROR', `${command} failed`, cause, 'Check command args and retry');
+        response.data = payload;
+        return { code: 1, response };
+    }
+    if (cleanupError) {
+        const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', `${command} completed but failed to stop auto-started Appium`, errorMessage(cleanupError), 'Inspect .visor/appium logs and stop Appium manually');
+        response.data = payload;
+        return { code: 1, response };
+    }
+    const response = envelopeOk(commandId, startedAt, artifacts, 'run');
+    response.data = payload;
+    return { code: 0, response };
+}
+export async function cmdStart(parsed) {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    try {
+        const status = await startManagedAppium(String(parsed.options['server-url'] ?? DEFAULT_SERVER_URL), typeof parsed.options['appium-cmd'] === 'string' ? parsed.options['appium-cmd'] : undefined, typeof parsed.options['startup-timeout'] === 'number'
+            ? parsed.options['startup-timeout']
+            : DEFAULT_STARTUP_TIMEOUT_SECONDS);
+        const response = envelopeOk(commandId, startedAt, [], 'run');
+        response.data = status;
+        return { code: 0, response };
+    }
+    catch (error) {
+        const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', 'Failed to start Appium', errorMessage(error), 'Install Node deps, check --appium-cmd, and inspect .visor/appium/*.log');
+        return { code: 1, response };
+    }
+}
+export async function cmdStatus(parsed) {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    const status = await statusManagedAppium(String(parsed.options['server-url'] ?? DEFAULT_SERVER_URL));
+    const response = envelopeOk(commandId, startedAt, [], Boolean(status.reachable) ? 'run' : 'start');
+    response.data = status;
+    return { code: 0, response };
+}
+export async function cmdStop(parsed) {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    try {
+        const result = await stopManagedAppium(String(parsed.options['server-url'] ?? DEFAULT_SERVER_URL), Boolean(parsed.options.force));
+        const response = envelopeOk(commandId, startedAt, [], 'none');
+        response.data = result;
+        return { code: 0, response };
+    }
+    catch (error) {
+        const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', 'Failed to stop managed Appium', errorMessage(error), 'Retry with --force or check process state manually');
+        return { code: 1, response };
+    }
+}
+export async function executeCommand(argv) {
+    if (argv.length === 0 ||
+        argv[0] === 'help' ||
+        argv.includes('--help') ||
+        argv.includes('-h')) {
+        return cmdHelp();
+    }
+    const parsed = parseCommand(argv);
+    if (parsed.command === 'validate') {
+        return cmdValidate(parsed);
+    }
+    if (parsed.command === 'run') {
+        return cmdRun(parsed);
+    }
+    if (parsed.command === 'benchmark') {
+        return cmdBenchmark(parsed);
+    }
+    if (parsed.command === 'report') {
+        return cmdReport(parsed);
+    }
+    if (parsed.command === 'start') {
+        return cmdStart(parsed);
+    }
+    if (parsed.command === 'status') {
+        return cmdStatus(parsed);
+    }
+    if (parsed.command === 'stop') {
+        return cmdStop(parsed);
+    }
+    if (ACTION_COMMANDS.has(parsed.command)) {
+        return cmdAction(parsed.command, parsed);
+    }
+    throw new Error(`Unsupported command '${parsed.command}'`);
+}

package/dist/errors.js

@@ -0,0 +1,8 @@
+export function makeError(code, message, likelyCause, nextStep) {
+    return {
+        code,
+        message,
+        likely_cause: likelyCause,
+        next_step: nextStep
+    };
+}

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './adapters.js';
+export * from './appiumLifecycle.js';
+export * from './cli.js';
+export * from './errors.js';
+export * from './report.js';
+export * from './runner.js';
+export * from './types.js';
+export * from './utils.js';
+export * from './validator.js';

package/dist/main.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { executeCommand } from './cli.js';
+import { makeError } from './errors.js';
+import { makeId, utcNowIso } from './utils.js';
+function isHelpData(value) {
+    return Boolean(value &&
+        typeof value === 'object' &&
+        'usageText' in value &&
+        typeof value.usageText === 'string');
+}
+async function main(argv = process.argv.slice(2)) {
+    try {
+        const result = await executeCommand(argv);
+        if (isHelpData(result.response.data)) {
+            console.log(result.response.data.usageText);
+        }
+        else {
+            console.log(JSON.stringify(result.response, null, 2));
+        }
+        return result.code;
+    }
+    catch (error) {
+        const startedAt = utcNowIso();
+        const response = {
+            status: 'fail',
+            command_id: makeId('cmd'),
+            started_at: startedAt,
+            ended_at: utcNowIso(),
+            artifacts: [],
+            next_action: 'Inspect CLI arguments and retry',
+            error: makeError('SYSTEM_ERROR', 'Unhandled CLI failure', error instanceof Error ? error.message : String(error), 'Inspect CLI arguments and retry'),
+            data: {}
+        };
+        console.log(JSON.stringify(response, null, 2));
+        return 1;
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    void main().then((code) => {
+        process.exitCode = code;
+    });
+}
+export { main };