visor-ai 0.2.6 → 0.2.8

package/dist/cli.js

@@ -1,11 +1,22 @@
+import fs from 'node:fs';
 import { DEFAULT_SERVER_URL } from './adapters.js';
-import { DaemonRequestTimeoutError, DaemonUnavailableError, runDaemonAction, runDaemonScenario, startVisorDaemon, statusVisorDaemon, stopVisorDaemon } from './daemon.js';
+import { DaemonOperationError, DaemonRequestTimeoutError, DaemonUnavailableError, runDaemonAction, runDaemonDiscover, runDaemonScenario, startVisorDaemon, statusVisorDaemon, stopVisorDaemon } from './daemon.js';
 import { DeviceSelectionError, resolveRunningDevice } from './devices.js';
 import { makeError } from './errors.js';
+import { LocalRuntimeAdapter } from './localRuntime.js';
 import { writeReports } from './report.js';
-import { determinismCheck } from './runner.js';
+import { determinismCheck, runScenario } from './runner.js';
 import { errorMessage, makeId, utcNowIso } from './utils.js';
 import { parseAndValidate } from './validator.js';
+function packageVersion() {
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        return typeof packageJson.version === 'string' ? packageJson.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
 const ACTION_COMMANDS = new Set([
     'tap',
     'navigate',
@@ -19,6 +30,7 @@ const ALL_COMMANDS = new Set([
     ...ACTION_COMMANDS,
     'validate',
     'run',
+    'discover',
     'benchmark',
     'report',
     'start',
@@ -34,6 +46,7 @@ const GLOBAL_SPEC = {
     'server-url': 'string',
     'app-id': 'string',
     attach: 'boolean',
+    'no-map': 'boolean',
     verbose: 'boolean'
 };
 const ACTION_SPEC = {
@@ -58,9 +71,20 @@ const COMMAND_SPECS = {
         timeout: 'number',
         output: 'string',
         format: 'string',
+        runtime: 'string',
+        'server-url': 'string',
+        'app-id': 'string',
+        attach: 'boolean',
+        'no-map': 'boolean'
+    },
+    discover: {
+        device: 'string',
+        timeout: 'number',
+        format: 'string',
         'server-url': 'string',
         'app-id': 'string',
-        attach: 'boolean'
+        attach: 'boolean',
+        'no-map': 'boolean'
     },
     benchmark: {
         runs: 'number',
@@ -71,7 +95,8 @@ const COMMAND_SPECS = {
         format: 'string',
         'server-url': 'string',
         'app-id': 'string',
-        attach: 'boolean'
+        attach: 'boolean',
+        'no-map': 'boolean'
     },
     report: { format: 'string' },
     start: {
@@ -102,12 +127,14 @@ function helpText() {
         '',
         'Usage:',
         '  visor <command> [options]',
-        '  visor --help',
+        '  visor --help | -h',
+        '  visor --version | -v',
         '',
         'Commands:',
         '  validate <scenario>',
-        '  run <scenario> [--output <dir>]',
+        '  run <scenario> [--output <dir>] [--runtime appium|local]',
         '  benchmark <scenario> [--runs <n>] [--threshold <percent>]',
+        '  discover [--app-id <id>]',
         '  report [path]',
         '  start [--server-url <url>] [--appium-cmd <cmd>]',
         '  status [--server-url <url>]',
@@ -116,10 +143,13 @@ function helpText() {
         '',
         'Examples:',
         '  visor validate scenarios/checkout-smoke.json',
+        '  visor run path/to/scenario.json --runtime local --output artifacts-local',
         '  visor start --server-url http://127.0.0.1:4723',
         '  visor run scenarios/checkout-smoke.json --output artifacts-test',
+        '  visor run scenarios/checkout-smoke.json --no-map',
+        '  visor discover --app-id com.example.app',
         '  visor scroll --device emulator-5554 --direction down',
-        '  node dist/main.js status'
+        '  visor status'
     ].join('\n');
 }
 function envelopeOk(commandId, startedAt, artifacts = [], nextAction = '') {
@@ -205,7 +235,10 @@ async function resolvedRuntime(options) {
         output_dir: String(options.output ?? 'artifacts'),
         server_url: String(options['server-url'] ?? DEFAULT_SERVER_URL),
         app_id: typeof options['app-id'] === 'string' ? options['app-id'] : undefined,
-        attach_to_running: Boolean(options.attach)
+        attach_to_running: Boolean(options.attach),
+        map: {
+            enabled: !Boolean(options['no-map'])
+        }
     };
 }
 function actionArgs(command, options) {
@@ -217,8 +250,10 @@ function actionArgs(command, options) {
         'verbose',
         'server-url',
         'seed',
+        'runtime',
         'app-id',
-        'attach'
+        'attach',
+        'no-map'
     ]);
     const args = Object.entries(options).reduce((acc, [key, value]) => {
         if (!commonIgnored.has(key) && value !== undefined) {
@@ -231,6 +266,10 @@ function actionArgs(command, options) {
     }
     return args;
 }
+function unsupportedRuntimeResult(commandId, startedAt, runtime) {
+    const response = envelopeFail(commandId, startedAt, 'INPUT_ERROR', 'Unsupported runtime', `Unsupported runtime '${String(runtime)}'`, 'Use --runtime appium or --runtime local');
+    return { code: 1, response };
+}
 function isTargetInitializationError(error) {
     const message = errorMessage(error);
     return (message.includes('Failed to create WebdriverIO Appium session') ||
@@ -259,14 +298,26 @@ function cmdHelp() {
         commands: Array.from(ALL_COMMANDS),
         examples: [
             'visor validate scenarios/checkout-smoke.json',
+            'visor run path/to/scenario.json --runtime local --output artifacts-local',
             'visor start --server-url http://127.0.0.1:4723',
             'visor run scenarios/checkout-smoke.json --output artifacts-test',
             'visor scroll --device emulator-5554 --direction down',
-            'node dist/main.js status'
+            'visor status'
         ]
     };
     return { code: 0, response };
 }
+function cmdVersion() {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    const version = packageVersion();
+    const response = envelopeOk(commandId, startedAt, [], 'none');
+    response.data = {
+        version,
+        versionText: version
+    };
+    return { code: 0, response };
+}
 export async function cmdValidate(parsed) {
     const commandId = makeId('cmd');
     const startedAt = utcNowIso();
@@ -291,6 +342,19 @@ export async function cmdValidate(parsed) {
         return { code: 1, response };
     }
 }
+async function cmdRunLocal(commandId, startedAt, scenario, warnings, runtime) {
+    const result = await runScenario(scenario, new LocalRuntimeAdapter(), runtime.device, runtime.timeout, runtime.output_dir);
+    const outputs = writeReports(result, runtime.output_dir);
+    const response = result.status === 'ok'
+        ? envelopeOk(commandId, startedAt, Object.values(outputs), 'report')
+        : envelopeFail(commandId, startedAt, result.error?.code ?? 'ACTION_ERROR', result.error?.message ?? 'Local runtime scenario failed', result.error?.likely_cause ?? 'The deterministic local runtime did not satisfy the scenario', result.error?.next_step ?? 'Inspect local runtime scenario artifacts and retry');
+    response.artifacts = Object.values(outputs);
+    response.data = {
+        run: result,
+        warnings
+    };
+    return { code: result.status === 'ok' ? 0 : 2, response };
+}
 export async function cmdRun(parsed) {
     const commandId = makeId('cmd');
     const startedAt = utcNowIso();
@@ -301,6 +365,24 @@ export async function cmdRun(parsed) {
         response.data = { issues };
         return { code: 1, response };
     }
+    if (parsed.options.runtime !== undefined &&
+        parsed.options.runtime !== 'appium' &&
+        parsed.options.runtime !== 'local') {
+        return unsupportedRuntimeResult(commandId, startedAt, parsed.options.runtime);
+    }
+    if (parsed.options.runtime === 'local') {
+        const runtime = {
+            device: 'local',
+            timeout: typeof parsed.options.timeout === 'number'
+                ? parsed.options.timeout
+                : typeof scenario.config.timeoutMs === 'number'
+                    ? scenario.config.timeoutMs
+                    : undefined,
+            output_dir: String(parsed.options.output ??
+                (typeof scenario.config.artifactsDir === 'string' ? scenario.config.artifactsDir : 'artifacts'))
+        };
+        return cmdRunLocal(commandId, startedAt, scenario, warningIssues(issues), runtime);
+    }
     let runtime;
     try {
         runtime = await resolvedRuntime({
@@ -329,7 +411,10 @@ export async function cmdRun(parsed) {
             device: runtime.device,
             app_id: runtime.app_id,
             attach_to_running: runtime.attach_to_running
-        }, scenario, runtime.device, runtime.timeout, runtime.output_dir);
+        }, scenario, runtime.device, runtime.timeout, runtime.output_dir, {
+            ...runtime.map,
+            appId: runtime.app_id
+        });
         const outputs = writeReports(result, runtime.output_dir);
         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);
@@ -362,6 +447,51 @@ export async function cmdRun(parsed) {
         return { code: 1, response };
     }
 }
+export async function cmdDiscover(parsed) {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    let runtime;
+    try {
+        runtime = await resolvedRuntime(parsed.options);
+    }
+    catch (error) {
+        if (!(error instanceof DeviceSelectionError)) {
+            throw error;
+        }
+        const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', 'Device selection failed', error.message, 'Start one target device or rerun with --device <device-id>');
+        response.data = { devices: error.devices };
+        return { code: 1, response };
+    }
+    try {
+        const result = await runDaemonDiscover({
+            platform: runtime.platform,
+            server_url: runtime.server_url,
+            device: runtime.device,
+            app_id: runtime.app_id,
+            attach_to_running: runtime.attach_to_running
+        }, {
+            ...runtime.map,
+            appId: runtime.app_id
+        });
+        const response = envelopeOk(commandId, startedAt, [], 'run');
+        response.data = result;
+        return { code: 0, response };
+    }
+    catch (error) {
+        const isDaemonUnavailable = error instanceof DaemonUnavailableError;
+        const isDaemonTimeout = error instanceof DaemonRequestTimeoutError;
+        const response = envelopeFail(commandId, startedAt, isDaemonUnavailable || isDaemonTimeout ? 'TARGET_ERROR' : 'ACTION_ERROR', isDaemonUnavailable
+            ? 'discover requires visor start'
+            : isDaemonTimeout
+                ? 'discover timed out waiting for Visor daemon'
+                : 'discover failed', errorMessage(error), isDaemonUnavailable
+            ? 'Run `visor start`, verify the target emulator/simulator is booted, and retry.'
+            : isDaemonTimeout
+                ? 'Inspect .visor/daemon/daemon.log and .visor/appium/*.log, then retry or run `visor stop --force` before restarting.'
+                : 'Check target app state and retry');
+        return { code: 1, response };
+    }
+}
 export async function cmdBenchmark(parsed) {
     const commandId = makeId('cmd');
     const startedAt = utcNowIso();
@@ -406,7 +536,10 @@ export async function cmdBenchmark(parsed) {
                 device: runtime.device,
                 app_id: runtime.app_id,
                 attach_to_running: runtime.attach_to_running
-            }, scenario, runtime.device, runtime.timeout, runtime.output_dir);
+            }, scenario, runtime.device, runtime.timeout, runtime.output_dir, {
+                ...runtime.map,
+                appId: runtime.app_id
+            });
             writeReports(result, runtime.output_dir);
             signatures.push(result.determinism_signature);
             runIds.push(result.run_id);
@@ -477,7 +610,10 @@ export async function cmdAction(command, parsed) {
             device: options.device,
             app_id: options.app_id,
             attach_to_running: options.attach_to_running
-        }, command, actionArgs(command, parsed.options));
+        }, command, actionArgs(command, parsed.options), {
+            ...options.map,
+            appId: options.app_id
+        });
         const actionPayload = payload.args;
         if (actionPayload && typeof actionPayload === 'object' && !Array.isArray(actionPayload)) {
             const maybePath = actionPayload.path;
@@ -487,6 +623,9 @@ export async function cmdAction(command, parsed) {
         }
     }
     catch (error) {
+        if (error instanceof DaemonOperationError && error.data) {
+            payload = error.data;
+        }
         actionError = error;
     }
     if (actionError) {
@@ -557,6 +696,9 @@ export async function executeCommand(argv) {
         argv.includes('-h')) {
         return cmdHelp();
     }
+    if (argv.includes('--version') || argv.includes('-v')) {
+        return cmdVersion();
+    }
     const parsed = parseCommand(argv);
     if (parsed.command === 'validate') {
         return cmdValidate(parsed);
@@ -564,6 +706,9 @@ export async function executeCommand(argv) {
     if (parsed.command === 'run') {
         return cmdRun(parsed);
     }
+    if (parsed.command === 'discover') {
+        return cmdDiscover(parsed);
+    }
     if (parsed.command === 'benchmark') {
         return cmdBenchmark(parsed);
     }

package/dist/daemon.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_SERVER_URL, getAdapter } from './adapters.js';
+import { createAppMapContext, createMapSummary, discoverAppMap, persistAppMapContext, runMappedCommand } from './appMap.js';
 import { DEFAULT_STARTUP_TIMEOUT_SECONDS, startManagedAppium, statusManagedAppium, stopManagedAppium } from './appiumLifecycle.js';
 import { runScenario } from './runner.js';
 import { ensureDir, errorMessage, resolveExecutable, sleep } from './utils.js';
@@ -19,6 +20,22 @@ export class DaemonRequestTimeoutError extends Error {
         this.name = 'DaemonRequestTimeoutError';
     }
 }
+export class DaemonOperationError extends Error {
+    data;
+    constructor(message, data) {
+        super(message);
+        this.name = 'DaemonOperationError';
+        this.data = data;
+    }
+}
+class DaemonResponseError extends Error {
+    data;
+    constructor(message, data) {
+        super(message);
+        this.name = 'DaemonResponseError';
+        this.data = data;
+    }
+}
 function daemonDir() {
     return ensureDir(path.join(process.cwd(), '.visor', 'daemon'));
 }
@@ -139,7 +156,7 @@ async function requestDaemon(request, timeoutMs = 1000) {
 async function daemonRequestData(request, timeoutMs = 1000) {
     const response = await requestDaemon(request, timeoutMs);
     if (!response.ok) {
-        throw new Error(response.error);
+        throw new DaemonOperationError(response.error, response.data);
     }
     return response.data;
 }
@@ -343,11 +360,14 @@ export async function stopVisorDaemon(serverUrl = DEFAULT_SERVER_URL, force = fa
         appium: await statusManagedAppium(serverUrl)
     };
 }
-export async function runDaemonAction(runtime, command, args) {
-    return daemonRequestData({ type: 'action', runtime, command, args }, 300000);
+export async function runDaemonAction(runtime, command, args, mapOptions) {
+    return daemonRequestData({ type: 'action', runtime, command, args, mapOptions }, 300000);
 }
-export async function runDaemonScenario(runtime, scenario, device, timeout, outputDir) {
-    return daemonRequestData({ type: 'scenario', runtime, scenario, device, timeout, outputDir }, 600000);
+export async function runDaemonScenario(runtime, scenario, device, timeout, outputDir, mapOptions) {
+    return daemonRequestData({ type: 'scenario', runtime, scenario, device, timeout, outputDir, mapOptions }, 600000);
+}
+export async function runDaemonDiscover(runtime, mapOptions) {
+    return daemonRequestData({ type: 'discover', runtime, mapOptions }, 300000);
 }
 export async function runDaemonFromEnv() {
     const options = {
@@ -398,10 +418,10 @@ export async function runDaemonFromEnv() {
             // The backing WebDriver session is already gone; removing it from the cache is enough.
         }
     }
-    async function runActionWithSessionRetry(runtime, command, args) {
+    async function runActionWithSessionRetry(runtime, command, args, mapOptions) {
         const adapter = await sessionFor(runtime);
         try {
-            return await adapter[command](args);
+            return await runActionWithMap(adapter, command, args, mapOptions);
         }
         catch (error) {
             if (!isRecoverableSessionCacheError(error)) {
@@ -409,7 +429,46 @@ export async function runDaemonFromEnv() {
             }
             await discardSession(runtime);
             const freshAdapter = await sessionFor(runtime);
-            return freshAdapter[command](args);
+            return runActionWithMap(freshAdapter, command, args, mapOptions);
+        }
+    }
+    async function runActionWithMap(adapter, command, args, mapOptions) {
+        const options = mapOptions;
+        const context = createAppMapContext(adapter, options);
+        if (!context) {
+            const summary = createMapSummary(adapter, options);
+            try {
+                const details = await adapter[command](args);
+                return {
+                    ...details,
+                    map: summary
+                };
+            }
+            catch (error) {
+                throw new DaemonResponseError(errorMessage(error), {
+                    map: summary
+                });
+            }
+        }
+        try {
+            const details = await runMappedCommand(context, command, args);
+            const stepMap = details.map && typeof details.map === 'object' ? details.map : {};
+            const summary = persistAppMapContext(context);
+            return {
+                ...details,
+                map: {
+                    ...summary,
+                    ...stepMap
+                }
+            };
+        }
+        catch (error) {
+            throw new DaemonResponseError(errorMessage(error), {
+                map: persistAppMapContext(context)
+            });
+        }
+        finally {
+            persistAppMapContext(context);
         }
     }
     function enqueue(work) {
@@ -463,11 +522,24 @@ export async function runDaemonFromEnv() {
                         });
                         return;
                     }
+                    else if (request.type === 'discover') {
+                        const data = await enqueue(async () => {
+                            activeOperation = `discover:${runtimeKey(request.runtime)}`;
+                            try {
+                                const adapter = await sessionFor(request.runtime);
+                                return await discoverAppMap(adapter, request.mapOptions);
+                            }
+                            finally {
+                                activeOperation = null;
+                            }
+                        });
+                        response = { ok: true, data };
+                    }
                     else if (request.type === 'action') {
                         const data = await enqueue(async () => {
                             activeOperation = `${request.command}:${runtimeKey(request.runtime)}`;
                             try {
-                                return await runActionWithSessionRetry(request.runtime, request.command, request.args);
+                                return await runActionWithSessionRetry(request.runtime, request.command, request.args, request.mapOptions);
                             }
                             finally {
                                 activeOperation = null;
@@ -480,7 +552,7 @@ export async function runDaemonFromEnv() {
                             activeOperation = `scenario:${runtimeKey(request.runtime)}`;
                             try {
                                 const adapter = await sessionFor(request.runtime);
-                                return await runScenario(request.scenario, adapter, request.device, request.timeout, request.outputDir, false);
+                                return await runScenario(request.scenario, adapter, request.device, request.timeout, request.outputDir, false, request.mapOptions);
                             }
                             finally {
                                 activeOperation = null;
@@ -490,7 +562,11 @@ export async function runDaemonFromEnv() {
                     }
                 }
                 catch (error) {
-                    response = { ok: false, error: errorMessage(error) };
+                    response = {
+                        ok: false,
+                        error: errorMessage(error),
+                        data: error instanceof DaemonResponseError ? error.data : undefined
+                    };
                 }
                 socket.end(`${JSON.stringify(response)}\n`);
             })();

package/dist/localRuntime.js

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const TINY_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMB/axDRf0AAAAASUVORK5CYII=', 'base64');
+function resolveArtifactPath(args, extension, fallbackLabel) {
+    const label = String(args.label ?? fallbackLabel);
+    return path.resolve(typeof args.path === 'string' ? args.path : `${label}.${extension}`);
+}
+function targetValue(target) {
+    const separatorIndex = target.indexOf('=');
+    return separatorIndex === -1 ? target : target.slice(separatorIndex + 1);
+}
+export class LocalRuntimeAdapter {
+    counter = 0;
+    route = 'app://home';
+    capability() {
+        return {
+            platform: 'android',
+            commands: ['navigate', 'tap', 'act', 'scroll', 'screenshot', 'wait', 'source']
+        };
+    }
+    async navigate(args) {
+        this.route = String(args.to ?? this.route);
+        return {
+            action: 'navigate',
+            platform: 'android',
+            args: { to: this.route }
+        };
+    }
+    async tap(args) {
+        const target = String(args.target ?? '');
+        if (targetValue(target) === 'Increment') {
+            this.counter += 1;
+        }
+        return {
+            action: 'tap',
+            platform: 'android',
+            args: { target }
+        };
+    }
+    async act(args) {
+        return {
+            action: 'act',
+            platform: 'android',
+            args
+        };
+    }
+    async scroll(args) {
+        return {
+            action: 'scroll',
+            platform: 'android',
+            args: {
+                direction: args.direction ?? 'down',
+                percent: args.percent ?? 70
+            }
+        };
+    }
+    async screenshot(args) {
+        const label = String(args.label ?? 'capture');
+        const filePath = resolveArtifactPath(args, 'png', label);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, TINY_PNG);
+        return {
+            action: 'screenshot',
+            platform: 'android',
+            args: {
+                label,
+                file: path.basename(filePath),
+                path: filePath,
+                width: 1,
+                height: 1
+            }
+        };
+    }
+    async wait(args) {
+        return {
+            action: 'wait',
+            platform: 'android',
+            args: { ms: Number(args.ms ?? 0) }
+        };
+    }
+    async source(args) {
+        const label = String(args.label ?? 'source');
+        const filePath = resolveArtifactPath(args, 'xml', label);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        const content = this.sourceXml();
+        fs.writeFileSync(filePath, content, 'utf8');
+        return {
+            action: 'source',
+            platform: 'android',
+            args: {
+                label,
+                file: path.basename(filePath),
+                path: filePath,
+                format: 'xml',
+                bytes: Buffer.byteLength(content, 'utf8')
+            }
+        };
+    }
+    async exists(target) {
+        const value = targetValue(target);
+        return value === 'Increment' || value === String(this.counter) || this.sourceXml().includes(value);
+    }
+    async close() {
+        return undefined;
+    }
+    sourceXml() {
+        return [
+            '<hierarchy>',
+            `  <node text="Route: ${this.route}" />`,
+            `  <node text="${this.counter}" label="${this.counter}" name="${this.counter}" value="${this.counter}" />`,
+            '  <node text="Increment" content-desc="Increment" label="Increment" name="Increment" />',
+            '</hierarchy>',
+            ''
+        ].join('\n');
+    }
+}

package/dist/main.js

@@ -12,6 +12,12 @@ function isHelpData(value) {
         'usageText' in value &&
         typeof value.usageText === 'string');
 }
+function isVersionData(value) {
+    return Boolean(value &&
+        typeof value === 'object' &&
+        'versionText' in value &&
+        typeof value.versionText === 'string');
+}
 async function main(argv = process.argv.slice(2)) {
     try {
         if (argv[0] === '__daemon') {
@@ -22,6 +28,9 @@ async function main(argv = process.argv.slice(2)) {
         if (isHelpData(result.response.data)) {
             console.log(result.response.data.usageText);
         }
+        else if (isVersionData(result.response.data)) {
+            console.log(result.response.data.versionText);
+        }
         else {
             console.log(JSON.stringify(result.response, null, 2));
         }