visor-ai 0.2.4 → 0.2.6

package/README.md

@@ -29,7 +29,6 @@ Supported today:
 - Android
 - iOS
 - real Appium-backed runs
-- mock runs for predictable dry-run behavior
 
 ## Install
 
@@ -42,4 +41,16 @@ visor --help
 
 ## Documentation
 
-Comprehensive product documentation lives in [the docs site](https://na-ca6c7a2b.mintlify.app).
+Comprehensive product documentation lives in [the docs site](https://www.visorai.dev/docs).
+
+## Releases
+
+Create a release by running one of:
+
+```bash
+npm run release:patch
+npm run release:minor
+npm run release:major
+```
+
+Each command runs `npm run check`, bumps the version, creates the matching `vX.Y.Z` git tag, and pushes the commit and tag upstream with `git push --follow-tags`.

package/dist/adapters.js

@@ -1,14 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { remote } from 'webdriverio';
 import { errorMessage, parseServerUrl, sleep } from './utils.js';
 export const DEFAULT_SERVER_URL = 'http://127.0.0.1:4723';
 export const DEFAULT_ANDROID_APP = 'com.example.app';
 export const DEFAULT_IOS_BUNDLE = 'com.example.app';
-export const DEFAULT_ANDROID_DEVICE = 'emulator-5554';
-export const DEFAULT_IOS_DEVICE = 'iPhone 17 Pro';
-const MINI_PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO7Z0x8AAAAASUVORK5CYII=';
-const MINI_PNG = Buffer.from(MINI_PNG_BASE64, 'base64');
 export const ACCESSIBILITY_ID = 'accessibility id';
 export const XPATH = 'xpath';
 export const ELEMENT_ID = 'id';
@@ -25,6 +20,18 @@ function envBool(preferred, legacy, defaultValue = false) {
     }
     return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
 }
+function envNumber(preferred, defaultValue) {
+    const raw = process.env[preferred];
+    if (raw === undefined) {
+        return defaultValue;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultValue;
+}
+export function resolveWebdriverConnectionTimeout(platform) {
+    const defaultTimeout = platform === 'ios' ? 240000 : 60000;
+    return envNumber('VISOR_WEBDRIVER_CONNECTION_TIMEOUT_MS', defaultTimeout);
+}
 function pngDimensions(filePath) {
     try {
         const header = fs.readFileSync(filePath).subarray(0, 24);
@@ -50,6 +57,9 @@ export function formatDriverCreationError(platform, appId, attachToRunning, erro
             : '';
         return `Failed to create WebdriverIO Appium session: ${message}. On iOS, --app-id must be the exact installed bundle identifier for the target app (${targetApp}). Android package names do not carry over automatically.${attachHint}`;
     }
+    if (platform === 'ios' && (message.includes('CoreSimulatorService') || message.includes('simctl'))) {
+        return `Failed to create WebdriverIO Appium session: ${message}. iOS simulator access failed before the command ran; verify \`xcrun simctl list\` works from the same shell and that Appium is not running in a sandboxed process.`;
+    }
     return `Failed to create WebdriverIO Appium session: ${message}`;
 }
 export function parseTarget(target) {
@@ -115,6 +125,22 @@ export function resolveTapMode(args) {
     }
     throw new Error('tap requires target or x/y coordinates');
 }
+function resolveScrollOptions(args) {
+    const direction = typeof args.direction === 'string' ? args.direction.toLowerCase() : '';
+    if (direction !== 'up' && direction !== 'down') {
+        throw new Error("scroll requires args.direction to be 'up' or 'down'");
+    }
+    const rawPercent = args.percent ?? 70;
+    const percent = Number(rawPercent);
+    if (!Number.isFinite(percent) || percent < 1 || percent > 100) {
+        throw new Error('scroll args.percent must be a number between 1 and 100');
+    }
+    return {
+        direction,
+        percent,
+        gesturePercent: percent / 100
+    };
+}
 export class RealAppiumAdapter {
     platform;
     serverUrl;
@@ -137,7 +163,7 @@ export class RealAppiumAdapter {
     capability() {
         return {
             platform: this.platform,
-            commands: ['navigate', 'tap', 'act', 'screenshot', 'wait', 'source']
+            commands: ['navigate', 'tap', 'act', 'scroll', 'screenshot', 'wait', 'source']
         };
     }
     async navigate(args) {
@@ -200,6 +226,15 @@ export class RealAppiumAdapter {
         }
         throw new Error('Unsupported act operation; use --name type --target <selector> --value <text> or --name back');
     }
+    async scroll(args) {
+        const { direction, percent, gesturePercent } = resolveScrollOptions(args);
+        await this.scrollViewport(direction, gesturePercent);
+        return {
+            action: 'scroll',
+            platform: this.platform,
+            args: { direction, percent }
+        };
+    }
     async screenshot(args) {
         const label = String(args.label ?? 'capture');
         const filePath = path.resolve(typeof args.path === 'string' ? args.path : `${label}.png`);
@@ -272,11 +307,13 @@ export class RealAppiumAdapter {
             envBool('VISOR_ATTACH_TO_RUNNING', 'PATF_ATTACH_TO_RUNNING', false);
         const server = parseServerUrl(this.serverUrl);
         const capabilities = {};
+        if (!this.device) {
+            throw new Error('A running device must be selected before creating an Appium session.');
+        }
         if (this.platform === 'android') {
             capabilities.platformName = 'Android';
             capabilities['appium:automationName'] = 'UiAutomator2';
-            capabilities['appium:udid'] =
-                this.device ?? env('VISOR_ANDROID_DEVICE', 'PATF_ANDROID_DEVICE', DEFAULT_ANDROID_DEVICE);
+            capabilities['appium:udid'] = this.device;
             capabilities['appium:appPackage'] =
                 this.appId ?? env('VISOR_ANDROID_APP_PACKAGE', 'PATF_ANDROID_APP_PACKAGE', DEFAULT_ANDROID_APP);
             capabilities['appium:appActivity'] = env('VISOR_ANDROID_APP_ACTIVITY', 'PATF_ANDROID_APP_ACTIVITY', '.MainActivity');
@@ -291,8 +328,7 @@ export class RealAppiumAdapter {
         else {
             capabilities.platformName = 'iOS';
             capabilities['appium:automationName'] = 'XCUITest';
-            capabilities['appium:deviceName'] =
-                this.device ?? env('VISOR_IOS_DEVICE', 'PATF_IOS_DEVICE', DEFAULT_IOS_DEVICE);
+            capabilities['appium:udid'] = this.device;
             capabilities['appium:bundleId'] =
                 this.appId ?? env('VISOR_IOS_BUNDLE_ID', 'PATF_IOS_BUNDLE_ID', DEFAULT_IOS_BUNDLE);
             capabilities['appium:newCommandTimeout'] = 60;
@@ -305,13 +341,16 @@ export class RealAppiumAdapter {
             }
         }
         try {
+            const { remote } = await import('webdriverio');
             return await remote({
                 protocol: server.protocol,
                 hostname: server.host,
                 port: server.port,
                 path: server.pathname,
                 capabilities,
-                logLevel: 'error'
+                logLevel: 'error',
+                connectionRetryCount: envNumber('VISOR_WEBDRIVER_CONNECTION_RETRY_COUNT', 0),
+                connectionRetryTimeout: resolveWebdriverConnectionTimeout(this.platform)
             });
         }
         catch (error) {
@@ -343,83 +382,60 @@ export class RealAppiumAdapter {
         }
         throw new Error(`Coordinate tap is unsupported for platform: ${this.platform}`);
     }
-}
-export class MockAdapter {
-    platform;
-    constructor(platform) {
-        this.platform = platform;
-    }
-    capability() {
-        return {
-            platform: this.platform,
-            commands: ['navigate', 'tap', 'act', 'screenshot', 'wait', 'source']
-        };
-    }
-    async navigate(args) {
-        return { action: 'navigate', platform: this.platform, args };
-    }
-    async tap(args) {
-        resolveTapMode(args);
-        return { action: 'tap', platform: this.platform, args };
-    }
-    async act(args) {
-        return { action: 'act', platform: this.platform, args };
-    }
-    async screenshot(args) {
-        const label = String(args.label ?? 'capture');
-        const filePath = path.resolve(typeof args.path === 'string' ? args.path : `${label}.png`);
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(filePath, MINI_PNG);
-        const { width, height } = pngDimensions(filePath);
-        return {
-            action: 'screenshot',
-            platform: this.platform,
-            args: {
-                label,
-                file: path.basename(filePath),
-                path: filePath,
-                width,
-                height
+    async scrollViewport(direction, gesturePercent) {
+        const driver = this.requireDriver();
+        const size = await driver.getWindowSize();
+        const left = Math.max(0, Math.round(size.width * 0.1));
+        const top = Math.max(0, Math.round(size.height * 0.1));
+        const width = Math.max(1, Math.round(size.width * 0.8));
+        const height = Math.max(1, Math.round(size.height * 0.8));
+        if (this.platform === 'android') {
+            await driver.execute('mobile: scrollGesture', [
+                { left, top, width, height, direction, percent: gesturePercent }
+            ]);
+            return;
+        }
+        if (this.platform === 'ios') {
+            try {
+                await driver.execute('mobile: scrollGesture', [
+                    { left, top, width, height, direction, percent: gesturePercent }
+                ]);
+                return;
+            }
+            catch {
+                await this.swipeViewport(direction, gesturePercent, size.width, size.height);
+                return;
             }
-        };
-    }
-    async wait(args) {
-        const ms = Number(args.ms ?? 0);
-        if (ms < 0) {
-            throw new Error('wait requires non-negative ms');
         }
-        return { action: 'wait', platform: this.platform, args: { ms } };
+        throw new Error(`Scroll is unsupported for platform: ${this.platform}`);
     }
-    async source(args) {
-        const label = String(args.label ?? 'source');
-        const filePath = path.resolve(typeof args.path === 'string' ? args.path : `${label}.xml`);
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        const content = `<hierarchy platform="${this.platform}"><node text="mock" /></hierarchy>\n`;
-        fs.writeFileSync(filePath, content, 'utf8');
-        return {
-            action: 'source',
-            platform: this.platform,
-            args: {
-                label,
-                file: path.basename(filePath),
-                path: filePath,
-                format: 'xml',
-                bytes: fs.statSync(filePath).size
+    async swipeViewport(direction, gesturePercent, viewportWidth, viewportHeight) {
+        const driver = this.requireDriver();
+        const x = Math.round(viewportWidth / 2);
+        const lowY = Math.round(viewportHeight * 0.75);
+        const highY = Math.round(viewportHeight * 0.25);
+        const travel = Math.max(1, Math.round(viewportHeight * gesturePercent));
+        const startY = direction === 'down' ? lowY : highY;
+        const unclampedEndY = direction === 'down' ? startY - travel : startY + travel;
+        const endY = Math.max(1, Math.min(viewportHeight - 1, unclampedEndY));
+        await driver.performActions([
+            {
+                type: 'pointer',
+                id: 'finger1',
+                parameters: { pointerType: 'touch' },
+                actions: [
+                    { type: 'pointerMove', duration: 0, x, y: startY },
+                    { type: 'pointerDown', button: 0 },
+                    { type: 'pause', duration: 150 },
+                    { type: 'pointerMove', duration: 400, x, y: endY },
+                    { type: 'pointerUp', button: 0 }
+                ]
             }
-        };
-    }
-    async exists(target) {
-        const lowered = target.toLowerCase();
-        return !lowered.includes('missing') && !lowered.includes('not_found');
-    }
-    async close() {
-        return;
+        ]);
+        await driver.releaseActions();
     }
 }
-export async function getAdapter(platform, serverUrl = DEFAULT_SERVER_URL, device, useMock = false, appId, attachToRunning = false) {
+export async function getAdapter(platform, serverUrl = DEFAULT_SERVER_URL, device, appId, attachToRunning = false) {
     const normalized = platform.toLowerCase();
-    if (useMock) {
-        return new MockAdapter(normalized);
-    }
     return RealAppiumAdapter.create(normalized, serverUrl, device, appId, attachToRunning);
 }

package/dist/appiumLifecycle.js

@@ -25,7 +25,10 @@ function pidExists(pid) {
         process.kill(pid, 0);
         return true;
     }
-    catch {
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'EPERM') {
+            return true;
+        }
         return false;
     }
 }