visor-ai 0.2.8 → 0.2.9

package/dist/cli.js

@@ -47,6 +47,7 @@ const GLOBAL_SPEC = {
     'app-id': 'string',
     attach: 'boolean',
     'no-map': 'boolean',
+    repair: 'boolean',
     verbose: 'boolean'
 };
 const ACTION_SPEC = {
@@ -54,12 +55,17 @@ const ACTION_SPEC = {
     target: 'string',
     x: 'number',
     y: 'number',
+    'start-x': 'number',
+    'start-y': 'number',
+    'end-x': 'number',
+    'end-y': 'number',
     direction: 'string',
     percent: 'number',
     normalized: 'boolean',
     to: 'string',
     name: 'string',
     value: 'string',
+    'start-value': 'number',
     label: 'string',
     ms: 'number',
     path: 'string'
@@ -75,7 +81,11 @@ const COMMAND_SPECS = {
         'server-url': 'string',
         'app-id': 'string',
         attach: 'boolean',
-        'no-map': 'boolean'
+        'no-map': 'boolean',
+        repair: 'boolean',
+        crawl: 'boolean',
+        'crawl-depth': 'number',
+        'crawl-limit': 'number'
     },
     discover: {
         device: 'string',
@@ -84,7 +94,11 @@ const COMMAND_SPECS = {
         'server-url': 'string',
         'app-id': 'string',
         attach: 'boolean',
-        'no-map': 'boolean'
+        'no-map': 'boolean',
+        repair: 'boolean',
+        crawl: 'boolean',
+        'crawl-depth': 'number',
+        'crawl-limit': 'number'
     },
     benchmark: {
         runs: 'number',
@@ -96,7 +110,9 @@ const COMMAND_SPECS = {
         'server-url': 'string',
         'app-id': 'string',
         attach: 'boolean',
-        'no-map': 'boolean'
+        'no-map': 'boolean',
+        repair: 'boolean',
+        'compare-map': 'boolean'
     },
     report: { format: 'string' },
     start: {
@@ -121,6 +137,13 @@ const COMMAND_SPECS = {
     wait: ACTION_SPEC,
     source: ACTION_SPEC
 };
+const ACTION_ARG_OPTION_NAMES = {
+    'start-x': 'startX',
+    'start-y': 'startY',
+    'end-x': 'endX',
+    'end-y': 'endY',
+    'start-value': 'startValue'
+};
 function helpText() {
     return [
         'Visor TypeScript CLI',
@@ -152,6 +175,116 @@ function helpText() {
         '  visor status'
     ].join('\n');
 }
+function commandHelpText(command) {
+    if (command === 'tap') {
+        const examples = [
+            'visor tap --target accessibility=Continue',
+            'visor tap --target text=Continue',
+            'visor tap --target text~=Settings',
+            'visor tap --target "first-in-section=Featured products"',
+            'visor tap --x 120 --y 640',
+            'visor tap --x 0.5 --y 0.92 --normalized'
+        ];
+        return {
+            usageText: [
+                'Visor tap',
+                '',
+                'Usage:',
+                '  visor tap --target <selector> [runtime options]',
+                '  visor tap --x <points> --y <points> [--normalized] [runtime options]',
+                '',
+                'Options:',
+                '  --target <selector>       Selector to tap',
+                '  --x <points>              X coordinate in screen points, or fraction with --normalized',
+                '  --y <points>              Y coordinate in screen points, or fraction with --normalized',
+                '  --normalized              Treat x/y as fractions of current screen size',
+                '  --no-map                  Disable app-map reads and writes',
+                '  --repair                  Allow opt-in exploratory app-map repair'
+            ].join('\n'),
+            examples
+        };
+    }
+    if (command === 'discover') {
+        const examples = [
+            'visor discover --app-id com.example.app',
+            'visor discover --app-id com.example.app --crawl --crawl-depth 2 --crawl-limit 24'
+        ];
+        return {
+            usageText: [
+                'Visor discover',
+                '',
+                'Usage:',
+                '  visor discover [--app-id <id>] [--crawl] [runtime options]',
+                '',
+                'Options:',
+                '  --crawl                   Explore safe controls and record app-map edges',
+                '  --crawl-depth <n>         Maximum crawl depth, default 2',
+                '  --crawl-limit <n>         Maximum crawl actions, default 24',
+                '  --no-map                  Disable app-map reads and writes'
+            ].join('\n'),
+            examples
+        };
+    }
+    if (command === 'act') {
+        const examples = [
+            'visor act --name back',
+            'visor act --name reset --app-id com.example.app',
+            'visor act --name drag --start-x 120 --start-y 640 --end-x 320 --end-y 640',
+            'visor act --name slider --target accessibility=Amount --value 0.5'
+        ];
+        return {
+            usageText: [
+                'Visor act',
+                '',
+                'Usage:',
+                '  visor act --name <type|back|home|reset|drag|slider> [options]',
+                '',
+                'Options:',
+                '  --name <operation>        Helper action name',
+                '  --target <selector>      Target selector for type or slider',
+                '  --value <value>          Text value for type, or 0..1 slider value',
+                '  --start-x <points>       Drag start x coordinate',
+                '  --start-y <points>       Drag start y coordinate',
+                '  --end-x <points>         Drag end x coordinate',
+                '  --end-y <points>         Drag end y coordinate',
+                '  --start-value <0..1>     Slider starting value, default 0.5',
+                '  --normalized             Treat drag coordinates as viewport fractions'
+            ].join('\n'),
+            examples
+        };
+    }
+    if (command === 'benchmark') {
+        const examples = [
+            'visor benchmark scenarios/checkout-smoke.json --runs 20',
+            'visor benchmark scenarios/checkout-smoke.json --runs 5 --compare-map'
+        ];
+        return {
+            usageText: [
+                'Visor benchmark',
+                '',
+                'Usage:',
+                '  visor benchmark <scenario> [--runs <n>] [--threshold <percent>] [--compare-map]',
+                '',
+                'Options:',
+                '  --runs <n>               Number of runs, default 20',
+                '  --threshold <percent>    Required determinism score, default 95',
+                '  --compare-map            Run no-map and app-map variants for A/B comparison'
+            ].join('\n'),
+            examples
+        };
+    }
+    return {
+        usageText: [
+            `Visor ${command}`,
+            '',
+            'Usage:',
+            `  visor ${command} [options]`,
+            '',
+            'Run visor --help for the full command list.'
+        ].join('\n'),
+        examples: []
+    };
+}
 function envelopeOk(commandId, startedAt, artifacts = [], nextAction = '') {
     return {
         status: 'ok',
@@ -237,7 +370,11 @@ async function resolvedRuntime(options) {
         app_id: typeof options['app-id'] === 'string' ? options['app-id'] : undefined,
         attach_to_running: Boolean(options.attach),
         map: {
-            enabled: !Boolean(options['no-map'])
+            enabled: !Boolean(options['no-map']),
+            ...(options.repair === true ? { repair: true } : {}),
+            ...(options.crawl === true ? { crawl: true } : {}),
+            ...(typeof options['crawl-depth'] === 'number' ? { crawlDepth: options['crawl-depth'] } : {}),
+            ...(typeof options['crawl-limit'] === 'number' ? { crawlLimit: options['crawl-limit'] } : {})
         }
     };
 }
@@ -253,11 +390,12 @@ function actionArgs(command, options) {
         'runtime',
         'app-id',
         'attach',
-        'no-map'
+        'no-map',
+        'repair'
     ]);
     const args = Object.entries(options).reduce((acc, [key, value]) => {
         if (!commonIgnored.has(key) && value !== undefined) {
-            acc[key] = value;
+            acc[ACTION_ARG_OPTION_NAMES[key] ?? key] = value;
         }
         return acc;
     }, {});
@@ -289,14 +427,78 @@ function targetInitializationNextStep(error) {
     }
     return 'Verify Appium driver setup, target device state, and app id, then retry.';
 }
-function cmdHelp() {
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function optionalString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function mapArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function mapActionCount(variants) {
+    let total = 0;
+    for (const variant of variants) {
+        if (!isRecord(variant)) {
+            continue;
+        }
+        total += mapArray(variant.actions).length;
+    }
+    return total;
+}
+function appMapSummaryFromPath(mapPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(mapPath, 'utf8'));
+        if (!isRecord(parsed)) {
+            return undefined;
+        }
+        const variants = mapArray(parsed.variants);
+        return {
+            schema_version: typeof parsed.schema_version === 'number' ? parsed.schema_version : undefined,
+            identity: optionalString(parsed.identity),
+            app_id: optionalString(parsed.app_id),
+            platform: optionalString(parsed.platform),
+            screens: mapArray(parsed.screens).length,
+            variants: variants.length,
+            edges: mapArray(parsed.edges).length,
+            actions: mapActionCount(variants),
+            auth_required_variants: variants.filter((variant) => isRecord(variant) && variant.auth_required === true).length,
+            updated_at: optionalString(parsed.updated_at)
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function addDiscoverMapSummary(result) {
+    if (!isRecord(result.map)) {
+        return result;
+    }
+    const map = result.map;
+    if (map.summary !== undefined || typeof map.path !== 'string') {
+        return result;
+    }
+    const summary = appMapSummaryFromPath(map.path);
+    if (!summary) {
+        return result;
+    }
+    return {
+        ...result,
+        map: {
+            ...map,
+            summary
+        }
+    };
+}
+function cmdHelp(command) {
     const commandId = makeId('cmd');
     const startedAt = utcNowIso();
     const response = envelopeOk(commandId, startedAt, [], 'validate');
+    const commandHelp = command ? commandHelpText(command) : undefined;
     response.data = {
-        usageText: helpText(),
-        commands: Array.from(ALL_COMMANDS),
-        examples: [
+        usageText: commandHelp?.usageText ?? helpText(),
+        commands: command ? [command] : Array.from(ALL_COMMANDS),
+        examples: commandHelp?.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',
@@ -474,7 +676,7 @@ export async function cmdDiscover(parsed) {
             appId: runtime.app_id
         });
         const response = envelopeOk(commandId, startedAt, [], 'run');
-        response.data = result;
+        response.data = addDiscoverMapSummary(result);
         return { code: 0, response };
     }
     catch (error) {
@@ -525,42 +727,97 @@ export async function cmdBenchmark(parsed) {
     }
     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;
-    for (let index = 0; index < runs; index += 1) {
-        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, {
-                ...runtime.map,
-                appId: runtime.app_id
-            });
-            writeReports(result, runtime.output_dir);
-            signatures.push(result.determinism_signature);
-            runIds.push(result.run_id);
-            if (result.status !== 'ok') {
+    const runtimeRequest = {
+        platform: runtime.platform,
+        server_url: runtime.server_url,
+        device: runtime.device,
+        app_id: runtime.app_id,
+        attach_to_running: runtime.attach_to_running
+    };
+    const runVariant = async (name, mapEnabled, mapOptions) => {
+        const signatures = [];
+        const runIds = [];
+        let failures = 0;
+        for (let index = 0; index < runs; index += 1) {
+            try {
+                const result = await runDaemonScenario(runtimeRequest, scenario, runtime.device, runtime.timeout, runtime.output_dir, mapOptions);
+                writeReports(result, runtime.output_dir);
+                signatures.push(result.determinism_signature);
+                runIds.push(result.run_id);
+                if (result.status !== 'ok') {
+                    failures += 1;
+                }
+            }
+            catch (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 { error: { 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 { error: { code: 1, response } };
+                }
                 failures += 1;
             }
         }
-        catch (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 };
+        const score = determinismCheck(signatures);
+        return {
+            variant: {
+                name,
+                mapEnabled,
+                runs,
+                threshold,
+                determinismScore: score,
+                pass: score >= threshold && failures === 0,
+                failures,
+                runIds
             }
-            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 };
+        };
+    };
+    if (parsed.options['compare-map'] === true) {
+        const variants = [];
+        for (const variantConfig of [
+            { name: 'no-map', mapEnabled: false },
+            { name: 'map', mapEnabled: true }
+        ]) {
+            const outcome = await runVariant(variantConfig.name, variantConfig.mapEnabled, {
+                ...runtime.map,
+                enabled: variantConfig.mapEnabled,
+                appId: runtime.app_id
+            });
+            if ('error' in outcome) {
+                return outcome.error;
             }
-            failures += 1;
+            variants.push(outcome.variant);
         }
-    }
-    const score = determinismCheck(signatures);
-    const passGate = score >= threshold && failures === 0;
+        const failures = variants.reduce((total, variant) => total + Number(variant.failures ?? 0), 0);
+        const score = Math.min(...variants.map((variant) => Number(variant.determinismScore ?? 0)));
+        const passGate = variants.every((variant) => variant.pass === true);
+        const runIds = variants.flatMap((variant) => Array.isArray(variant.runIds) ? variant.runIds : []);
+        const response = envelopeOk(commandId, startedAt, [], 'report');
+        response.data = {
+            runs,
+            threshold,
+            determinismScore: score,
+            pass: passGate,
+            failures,
+            runIds,
+            variants,
+            warnings: warningIssues(issues)
+        };
+        return { code: passGate ? 0 : 3, response };
+    }
+    const outcome = await runVariant('benchmark', runtime.map.enabled !== false, {
+        ...runtime.map,
+        appId: runtime.app_id
+    });
+    if ('error' in outcome) {
+        return outcome.error;
+    }
+    const score = Number(outcome.variant.determinismScore ?? 0);
+    const failures = Number(outcome.variant.failures ?? 0);
+    const passGate = outcome.variant.pass === true;
+    const runIds = Array.isArray(outcome.variant.runIds) ? outcome.variant.runIds : [];
     const response = envelopeOk(commandId, startedAt, [], 'report');
     response.data = {
         runs,
@@ -690,10 +947,12 @@ export async function cmdStop(parsed) {
     }
 }
 export async function executeCommand(argv) {
-    if (argv.length === 0 ||
-        argv[0] === 'help' ||
-        argv.includes('--help') ||
-        argv.includes('-h')) {
+    const requestedHelp = argv[0] === 'help' || argv.includes('--help') || argv.includes('-h');
+    if (requestedHelp) {
+        const helpCommand = argv.find((token) => ALL_COMMANDS.has(token));
+        return cmdHelp(helpCommand);
+    }
+    if (argv.length === 0) {
         return cmdHelp();
     }
     if (argv.includes('--version') || argv.includes('-v')) {

package/dist/localRuntime.js

@@ -38,6 +38,14 @@ export class LocalRuntimeAdapter {
         };
     }
     async act(args) {
+        const name = String(args.name ?? '');
+        if (name === 'reset') {
+            this.counter = 0;
+            this.route = 'app://home';
+        }
+        if (name === 'home') {
+            this.route = 'app://home';
+        }
         return {
             action: 'act',
             platform: 'android',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visor-ai",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Visor CLI for LLM-driven mobile app interaction and artifact capture",
   "type": "module",
   "license": "MIT",