visor-ai 0.2.5 → 0.2.6

package/dist/cli.js

@@ -1,8 +1,9 @@
-import { DEFAULT_SERVER_URL, getAdapter } from './adapters.js';
-import { DEFAULT_STARTUP_TIMEOUT_SECONDS, isAppiumReachable, startManagedAppium, statusManagedAppium, stopManagedAppium } from './appiumLifecycle.js';
+import { DEFAULT_SERVER_URL } from './adapters.js';
+import { DaemonRequestTimeoutError, DaemonUnavailableError, runDaemonAction, runDaemonScenario, startVisorDaemon, statusVisorDaemon, stopVisorDaemon } from './daemon.js';
+import { DeviceSelectionError, resolveRunningDevice } from './devices.js';
 import { makeError } from './errors.js';
 import { writeReports } from './report.js';
-import { determinismCheck, runScenario } from './runner.js';
+import { determinismCheck } from './runner.js';
 import { errorMessage, makeId, utcNowIso } from './utils.js';
 import { parseAndValidate } from './validator.js';
 const ACTION_COMMANDS = new Set([
@@ -25,7 +26,6 @@ const ALL_COMMANDS = new Set([
     'stop'
 ]);
 const GLOBAL_SPEC = {
-    platform: 'string',
     device: 'string',
     timeout: 'number',
     output: 'string',
@@ -33,11 +33,7 @@ const GLOBAL_SPEC = {
     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 = {
@@ -58,40 +54,29 @@ const ACTION_SPEC = {
 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'
+        attach: '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'
+        attach: 'boolean'
     },
     report: { format: 'string' },
     start: {
         'server-url': 'string',
         'appium-cmd': 'string',
-        'startup-timeout': 'number',
         format: 'string'
     },
     status: {
@@ -121,18 +106,19 @@ function helpText() {
         '',
         'Commands:',
         '  validate <scenario>',
-        '  run <scenario> [--mock] [--output <dir>]',
+        '  run <scenario> [--output <dir>]',
         '  benchmark <scenario> [--runs <n>] [--threshold <percent>]',
         '  report [path]',
-        '  start [--server-url <url>]',
+        '  start [--server-url <url>] [--appium-cmd <cmd>]',
         '  status [--server-url <url>]',
         '  stop [--server-url <url>] [--force]',
         '  tap|navigate|act|scroll|screenshot|wait|source',
         '',
         'Examples:',
         '  visor validate scenarios/checkout-smoke.json',
-        '  visor run scenarios/checkout-smoke.json --mock --output artifacts-test',
-        '  visor scroll --platform android --mock --direction down',
+        '  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'
     ].join('\n');
 }
@@ -208,69 +194,31 @@ function parseCommand(argv) {
 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;
+async function resolvedRuntime(options) {
+    const selectedDevice = await resolveRunningDevice(typeof options.device === 'string' ? options.device : undefined);
     return {
-        platform,
-        device: String(options.device ?? defaultDevice),
+        platform: selectedDevice.platform,
+        device: selectedDevice.id,
         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'),
+            : 2500,
+        output_dir: String(options.output ?? '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
+        attach_to_running: Boolean(options.attach)
     };
 }
-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'
+        'attach'
     ]);
     const args = Object.entries(options).reduce((acc, [key, value]) => {
         if (!commonIgnored.has(key) && value !== undefined) {
@@ -283,6 +231,25 @@ function actionArgs(command, options) {
     }
     return args;
 }
+function isTargetInitializationError(error) {
+    const message = errorMessage(error);
+    return (message.includes('Failed to create WebdriverIO Appium session') ||
+        message.includes('CoreSimulatorService') ||
+        message.includes('Could not find a driver for automationName'));
+}
+function targetInitializationNextStep(error) {
+    const message = errorMessage(error);
+    if (message.includes('CoreSimulatorService') || message.includes('simctl')) {
+        return 'Run `xcrun simctl list` from the same shell. If it fails, restart Simulator/CoreSimulator and ensure Appium is not running from a sandboxed process.';
+    }
+    if (message.includes('Could not find a driver for automationName')) {
+        return 'Install the matching Appium driver, verify it with `appium driver list --installed`, then restart `visor start`.';
+    }
+    if (message.includes('bundle identifier') && message.includes('unknown')) {
+        return 'Verify the iOS bundle id is installed on the selected simulator/device, launch it first when using `--attach`, then retry.';
+    }
+    return 'Verify Appium driver setup, target device state, and app id, then retry.';
+}
 function cmdHelp() {
     const commandId = makeId('cmd');
     const startedAt = utcNowIso();
@@ -292,8 +259,9 @@ function cmdHelp() {
         commands: Array.from(ALL_COMMANDS),
         examples: [
             'visor validate scenarios/checkout-smoke.json',
-            'visor run scenarios/checkout-smoke.json --mock --output artifacts-test',
-            'visor scroll --platform android --mock --direction down',
+            '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'
         ]
     };
@@ -333,17 +301,36 @@ export async function cmdRun(parsed) {
         response.data = { issues };
         return { code: 1, response };
     }
-    const runtime = resolvedRuntime(parsed.options, scenario);
-    let runtimeState;
-    let cleanupError;
+    let runtime;
     try {
-        if (!runtime.use_mock) {
-            runtimeState = await ensureNonMockRuntime(runtime);
+        runtime = await resolvedRuntime({
+            ...parsed.options,
+            timeout: typeof parsed.options.timeout === 'number'
+                ? parsed.options.timeout
+                : typeof scenario.config.timeoutMs === 'number'
+                    ? scenario.config.timeoutMs
+                    : undefined,
+            output: parsed.options.output ??
+                (typeof scenario.config.artifactsDir === 'string' ? scenario.config.artifactsDir : undefined)
+        });
+    }
+    catch (error) {
+        if (!(error instanceof DeviceSelectionError)) {
+            throw error;
         }
-        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 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 runDaemonScenario({
+            platform: runtime.platform,
+            server_url: runtime.server_url,
+            device: runtime.device,
+            app_id: runtime.app_id,
+            attach_to_running: runtime.attach_to_running
+        }, scenario, 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);
@@ -361,17 +348,19 @@ export async function cmdRun(parsed) {
         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.');
+        const isDaemonUnavailable = error instanceof DaemonUnavailableError;
+        const isDaemonTimeout = error instanceof DaemonRequestTimeoutError;
+        const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', isDaemonUnavailable
+            ? 'Run requires visor start'
+            : isDaemonTimeout
+                ? 'Timed out waiting for Visor daemon'
+                : 'Failed to initialize platform target', 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.'
+                : 'Verify the target emulator/simulator and Appium driver setup, then retry.');
         return { code: 1, response };
     }
-    finally {
-        try {
-            await stopAutoStartedAppium(runtimeState);
-        }
-        catch (error) {
-            cleanupError = error;
-        }
-    }
 }
 export async function cmdBenchmark(parsed) {
     const commandId = makeId('cmd');
@@ -383,62 +372,62 @@ export async function cmdBenchmark(parsed) {
         response.data = { issues };
         return { code: 1, response };
     }
-    const runtime = resolvedRuntime(parsed.options, scenario);
+    let runtime;
+    try {
+        runtime = await resolvedRuntime({
+            ...parsed.options,
+            timeout: typeof parsed.options.timeout === 'number'
+                ? parsed.options.timeout
+                : typeof scenario.config.timeoutMs === 'number'
+                    ? scenario.config.timeoutMs
+                    : undefined,
+            output: parsed.options.output ??
+                (typeof scenario.config.artifactsDir === 'string' ? scenario.config.artifactsDir : undefined)
+        });
+    }
+    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 };
+    }
     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) {
+    for (let index = 0; index < runs; index += 1) {
         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 {
+            const result = await runDaemonScenario({
+                platform: runtime.platform,
+                server_url: runtime.server_url,
+                device: runtime.device,
+                app_id: runtime.app_id,
+                attach_to_running: runtime.attach_to_running
+            }, scenario, 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;
             }
         }
-    }
-    finally {
-        try {
-            await stopAutoStartedAppium(runtimeState);
-        }
         catch (error) {
-            cleanupError = error;
+            if (error instanceof DaemonUnavailableError) {
+                const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', 'Benchmark requires visor start', errorMessage(error), 'Run `visor start`, verify the target emulator/simulator is booted, and retry.');
+                return { code: 1, response };
+            }
+            if (error instanceof DaemonRequestTimeoutError) {
+                const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', 'Timed out waiting for Visor daemon', errorMessage(error), 'Inspect .visor/daemon/daemon.log and .visor/appium/*.log, then retry or run `visor stop --force` before restarting.');
+                return { code: 1, response };
+            }
+            failures += 1;
         }
     }
     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,
@@ -466,43 +455,29 @@ export async function cmdReport(parsed) {
 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 options;
+    try {
+        options = 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 };
+    }
     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));
+        payload = await runDaemonAction({
+            platform: options.platform,
+            server_url: options.server_url,
+            device: options.device,
+            app_id: options.app_id,
+            attach_to_running: options.attach_to_running
+        }, command, actionArgs(command, parsed.options));
         const actionPayload = payload.args;
         if (actionPayload && typeof actionPayload === 'object' && !Array.isArray(actionPayload)) {
             const maybePath = actionPayload.path;
@@ -514,27 +489,23 @@ export async function cmdAction(command, parsed) {
     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');
+        const isDaemonUnavailable = actionError instanceof DaemonUnavailableError;
+        const isDaemonTimeout = actionError instanceof DaemonRequestTimeoutError;
+        const isTargetInitialization = isTargetInitializationError(actionError);
+        const response = envelopeFail(commandId, startedAt, isDaemonUnavailable || isDaemonTimeout || isTargetInitialization ? 'TARGET_ERROR' : 'ACTION_ERROR', isDaemonUnavailable
+            ? `${command} requires visor start`
+            : isDaemonTimeout
+                ? `${command} timed out waiting for Visor daemon`
+                : isTargetInitialization
+                    ? `${command} failed to initialize platform target`
+                    : `${command} failed`, errorMessage(actionError), 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.'
+                : isTargetInitialization
+                    ? targetInitializationNextStep(actionError)
+                    : 'Check command args and retry');
         response.data = payload;
         return { code: 1, response };
     }
@@ -546,23 +517,22 @@ 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 status = await startVisorDaemon(String(parsed.options['server-url'] ?? DEFAULT_SERVER_URL), typeof parsed.options['appium-cmd'] === 'string' ? parsed.options['appium-cmd'] : undefined);
         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');
+        const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', 'Failed to start Visor daemon', errorMessage(error), 'Install Node deps, check --appium-cmd, and inspect .visor/daemon/*.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');
+    const status = await statusVisorDaemon(String(parsed.options['server-url'] ?? DEFAULT_SERVER_URL));
+    const daemon = status.daemon;
+    const response = envelopeOk(commandId, startedAt, [], daemon?.running ? 'run' : daemon?.unresponsive ? 'stop' : 'start');
     response.data = status;
     return { code: 0, response };
 }
@@ -570,13 +540,13 @@ 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 result = await stopVisorDaemon(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');
+        const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', 'Failed to stop Visor daemon', errorMessage(error), 'Retry with --force or check process state manually');
         return { code: 1, response };
     }
 }