visor-ai 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksander Kapera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# Visor
+
+Visor is a TypeScript CLI for verified interaction with running mobile apps.
+
+Instead of inferring UI behavior from code alone, Visor captures evidence from the live app: interactions, screenshots, UI source, assertions, and run artifacts.
+
+## What Visor does
+
+- interacts with iOS and Android apps through Appium
+- captures screenshots and UI source from live app state
+- executes repeatable scenarios with ordered steps
+- evaluates visibility assertions after execution
+- writes artifacts and reports for review and automation
+- measures determinism across repeated runs
+
+## Why teams use it
+
+- reduce guesswork in agent-driven UI work
+- verify real app behavior instead of code intent alone
+- keep reproducible evidence for debugging and review
+- add a repeatable verification layer around mobile UI changes
+
+## Scope
+
+Visor is focused on mobile app verification.
+
+Supported today:
+
+- Android
+- iOS
+- real Appium-backed runs
+- mock runs for predictable dry-run behavior
+
+## Install
+
+Visor ships as the npm package `visor-ai` and requires Node `20` or later.
+
+For a published install:
+
+```bash
+npm install -g visor-ai
+visor --help
+```
+
+For a source checkout:
+
+```bash
+npm install
+npm run build
+node dist/main.js --help
+```
+
+## Release automation
+
+GitHub Actions publishes tagged releases of `visor-ai` to the npm registry.
+
+Maintainer requirements:
+
+- repository secret `NPM_TOKEN`
+- release tags in the form `v<package.json version>`
+
+The release workflow verifies the package with `npm ci`, `npm run build`, `npm test`, and `npm pack --dry-run` before publishing.
+
+## Documentation
+
+Comprehensive product documentation lives in [the docs site](https://na-ca6c7a2b.mintlify.app).

package/dist/adapters.js

@@ -0,0 +1,425 @@
+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';
+export const ANDROID_UIAUTOMATOR = '-android uiautomator';
+export const IOS_PREDICATE = '-ios predicate string';
+export const IOS_CLASS_CHAIN = '-ios class chain';
+function env(preferred, legacy, defaultValue) {
+    return process.env[preferred] ?? process.env[legacy] ?? defaultValue;
+}
+function envBool(preferred, legacy, defaultValue = false) {
+    const raw = env(preferred, legacy);
+    if (raw === undefined) {
+        return defaultValue;
+    }
+    return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
+}
+function pngDimensions(filePath) {
+    try {
+        const header = fs.readFileSync(filePath).subarray(0, 24);
+        if (header.length < 24 ||
+            !header.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+            return { width: null, height: null };
+        }
+        return {
+            width: header.readUInt32BE(16),
+            height: header.readUInt32BE(20)
+        };
+    }
+    catch {
+        return { width: null, height: null };
+    }
+}
+export function formatDriverCreationError(platform, appId, attachToRunning, error) {
+    const message = errorMessage(error);
+    if (platform === 'ios' && message.includes('bundle identifier') && message.includes('unknown')) {
+        const targetApp = appId ?? DEFAULT_IOS_BUNDLE;
+        const attachHint = attachToRunning
+            ? ' When using --attach, launch that app on the simulator/device first.'
+            : '';
+        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}`;
+    }
+    return `Failed to create WebdriverIO Appium session: ${message}`;
+}
+export function parseTarget(target) {
+    if (target.startsWith('text=')) {
+        const value = target.split('=', 2)[1] ?? '';
+        const xpath = `//*[contains(@text, '${value}') or contains(@content-desc, '${value}') or contains(@label, '${value}') or contains(@name, '${value}') or contains(@value, '${value}')]`;
+        return [XPATH, xpath];
+    }
+    if (target.startsWith('id=')) {
+        return [ELEMENT_ID, target.split('=', 2)[1] ?? ''];
+    }
+    if (target.startsWith('xpath=')) {
+        return [XPATH, target.split('=', 2)[1] ?? ''];
+    }
+    if (target.startsWith('uiautomator=')) {
+        return [ANDROID_UIAUTOMATOR, target.split('=', 2)[1] ?? ''];
+    }
+    if (target.startsWith('predicate=')) {
+        return [IOS_PREDICATE, target.split('=', 2)[1] ?? ''];
+    }
+    if (target.startsWith('classchain=')) {
+        return [IOS_CLASS_CHAIN, target.split('=', 2)[1] ?? ''];
+    }
+    if (target.startsWith('accessibility=')) {
+        return [ACCESSIBILITY_ID, target.split('=', 2)[1] ?? ''];
+    }
+    return [ACCESSIBILITY_ID, target];
+}
+function selectorForTarget(target) {
+    const [strategy, value] = parseTarget(target);
+    if (strategy === ACCESSIBILITY_ID) {
+        return { strategy, value, selector: `~${value}` };
+    }
+    if (strategy === XPATH) {
+        return { strategy, value, selector: value };
+    }
+    if (strategy === ELEMENT_ID) {
+        return { strategy, value, selector: `id=${value}` };
+    }
+    if (strategy === ANDROID_UIAUTOMATOR) {
+        return { strategy, value, selector: `android=${value}` };
+    }
+    if (strategy === IOS_PREDICATE) {
+        return { strategy, value, selector: `-ios predicate string:${value}` };
+    }
+    return { strategy, value, selector: `-ios class chain:${value}` };
+}
+export function resolveTapMode(args) {
+    const hasTarget = Object.hasOwn(args, 'target') && args.target !== undefined && args.target !== null;
+    const hasX = Object.hasOwn(args, 'x') && args.x !== undefined && args.x !== null;
+    const hasY = Object.hasOwn(args, 'y') && args.y !== undefined && args.y !== null;
+    if (hasTarget && (hasX || hasY)) {
+        throw new Error('tap cannot mix target with x/y coordinates');
+    }
+    if (hasTarget) {
+        return 'target';
+    }
+    if (hasX && hasY) {
+        return 'coordinates';
+    }
+    if (hasX !== hasY) {
+        throw new Error('tap coordinate mode requires both x and y');
+    }
+    throw new Error('tap requires target or x/y coordinates');
+}
+export class RealAppiumAdapter {
+    platform;
+    serverUrl;
+    device;
+    appId;
+    attachToRunning;
+    driver = null;
+    constructor(platform, serverUrl, device, appId, attachToRunning = false) {
+        this.platform = platform;
+        this.serverUrl = serverUrl;
+        this.device = device;
+        this.appId = appId;
+        this.attachToRunning = attachToRunning;
+    }
+    static async create(platform, serverUrl, device, appId, attachToRunning = false) {
+        const adapter = new RealAppiumAdapter(platform, serverUrl, device, appId, attachToRunning);
+        adapter.driver = await adapter.createDriver();
+        return adapter;
+    }
+    capability() {
+        return {
+            platform: this.platform,
+            commands: ['navigate', 'tap', 'act', 'screenshot', 'wait', 'source']
+        };
+    }
+    async navigate(args) {
+        const to = String(args.to ?? '');
+        if (to) {
+            await this.requireDriver().url(to);
+        }
+        return {
+            action: 'navigate',
+            platform: this.platform,
+            args: { to }
+        };
+    }
+    async tap(args) {
+        if (resolveTapMode(args) === 'coordinates') {
+            const { x, y } = await this.resolveCoordinates(args);
+            await this.tapPoint(x, y);
+            return {
+                action: 'tap',
+                platform: this.platform,
+                args: {
+                    x,
+                    y,
+                    normalized: Boolean(args.normalized)
+                }
+            };
+        }
+        const target = String(args.target);
+        const selector = selectorForTarget(target);
+        const element = await this.requireDriver().$(selector.selector);
+        await element.click();
+        return {
+            action: 'tap',
+            platform: this.platform,
+            args: { target }
+        };
+    }
+    async act(args) {
+        const name = String(args.name ?? '');
+        const value = String(args.value ?? '');
+        const target = typeof args.target === 'string' ? args.target : undefined;
+        if (name === 'type' && target) {
+            const selector = selectorForTarget(target);
+            const element = await this.requireDriver().$(selector.selector);
+            await element.clearValue();
+            await element.addValue(value);
+            return {
+                action: 'act',
+                platform: this.platform,
+                args: { name, target, value }
+            };
+        }
+        if (name === 'back') {
+            await this.requireDriver().back();
+            return {
+                action: 'act',
+                platform: this.platform,
+                args: { name }
+            };
+        }
+        throw new Error('Unsupported act operation; use --name type --target <selector> --value <text> or --name back');
+    }
+    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 });
+        await this.requireDriver().saveScreenshot(filePath);
+        const { width, height } = pngDimensions(filePath);
+        return {
+            action: 'screenshot',
+            platform: this.platform,
+            args: {
+                label,
+                file: path.basename(filePath),
+                path: filePath,
+                width,
+                height
+            }
+        };
+    }
+    async wait(args) {
+        const ms = Number(args.ms ?? 0);
+        if (ms < 0) {
+            throw new Error('wait requires non-negative ms');
+        }
+        await sleep(ms);
+        return {
+            action: 'wait',
+            platform: this.platform,
+            args: { ms }
+        };
+    }
+    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 = await this.requireDriver().getPageSource();
+        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 exists(target) {
+        const selector = selectorForTarget(target);
+        const elements = (await this.requireDriver().$$(selector.selector));
+        return elements.length > 0;
+    }
+    async close() {
+        if (!this.driver) {
+            return;
+        }
+        const currentDriver = this.driver;
+        this.driver = null;
+        await currentDriver.deleteSession();
+    }
+    requireDriver() {
+        if (!this.driver) {
+            throw new Error('Driver session is not initialized');
+        }
+        return this.driver;
+    }
+    async createDriver() {
+        const attachToRunning = this.attachToRunning ||
+            envBool('VISOR_ATTACH_TO_RUNNING', 'PATF_ATTACH_TO_RUNNING', false);
+        const server = parseServerUrl(this.serverUrl);
+        const capabilities = {};
+        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: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');
+            capabilities['appium:newCommandTimeout'] = 60;
+            if (attachToRunning) {
+                capabilities['appium:noReset'] = true;
+                capabilities['appium:fullReset'] = false;
+                capabilities['appium:autoLaunch'] = false;
+                capabilities['appium:dontStopAppOnReset'] = true;
+            }
+        }
+        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:bundleId'] =
+                this.appId ?? env('VISOR_IOS_BUNDLE_ID', 'PATF_IOS_BUNDLE_ID', DEFAULT_IOS_BUNDLE);
+            capabilities['appium:newCommandTimeout'] = 60;
+            if (attachToRunning) {
+                capabilities['appium:noReset'] = true;
+                capabilities['appium:fullReset'] = false;
+                capabilities['appium:autoLaunch'] = false;
+                capabilities['appium:shouldTerminateApp'] = false;
+                capabilities['appium:forceAppLaunch'] = false;
+            }
+        }
+        try {
+            return await remote({
+                protocol: server.protocol,
+                hostname: server.host,
+                port: server.port,
+                path: server.pathname,
+                capabilities,
+                logLevel: 'error'
+            });
+        }
+        catch (error) {
+            throw new Error(formatDriverCreationError(this.platform, this.appId, attachToRunning, error));
+        }
+    }
+    async resolveCoordinates(args) {
+        let x = Number(args.x);
+        let y = Number(args.y);
+        if (Boolean(args.normalized)) {
+            const size = await this.requireDriver().getWindowSize();
+            x *= Number(size.width);
+            y *= Number(size.height);
+        }
+        return {
+            x: Math.round(x),
+            y: Math.round(y)
+        };
+    }
+    async tapPoint(x, y) {
+        const driver = this.requireDriver();
+        if (this.platform === 'android') {
+            await driver.execute('mobile: clickGesture', [{ x, y }]);
+            return;
+        }
+        if (this.platform === 'ios') {
+            await driver.execute('mobile: tap', [{ x, y }]);
+            return;
+        }
+        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 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 } };
+    }
+    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 exists(target) {
+        const lowered = target.toLowerCase();
+        return !lowered.includes('missing') && !lowered.includes('not_found');
+    }
+    async close() {
+        return;
+    }
+}
+export async function getAdapter(platform, serverUrl = DEFAULT_SERVER_URL, device, useMock = false, appId, attachToRunning = false) {
+    const normalized = platform.toLowerCase();
+    if (useMock) {
+        return new MockAdapter(normalized);
+    }
+    return RealAppiumAdapter.create(normalized, serverUrl, device, appId, attachToRunning);
+}