visor-ai 0.2.1 → 0.2.5

package/README.md

@@ -35,32 +35,23 @@ Supported today:
 
 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.
+## Documentation
 
-Maintainer requirements:
+Comprehensive product documentation lives in [the docs site](https://www.visorai.dev/docs).
 
-- repository secret `NPM_TOKEN`
-- release tags in the form `v<package.json version>`
+## Releases
 
-The release workflow verifies the package with `npm ci`, `npm run build`, `npm test`, and `npm pack --dry-run` before publishing.
+Create a release by running one of:
 
-## Documentation
+```bash
+npm run release:patch
+npm run release:minor
+npm run release:major
+```
 
-Comprehensive product documentation lives in [the docs site](https://na-ca6c7a2b.mintlify.app).
+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

@@ -115,6 +115,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 +153,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 +216,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`);
@@ -343,6 +368,58 @@ export class RealAppiumAdapter {
         }
         throw new Error(`Coordinate tap is unsupported for platform: ${this.platform}`);
     }
+    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;
+            }
+        }
+        throw new Error(`Scroll is unsupported for platform: ${this.platform}`);
+    }
+    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 }
+                ]
+            }
+        ]);
+        await driver.releaseActions();
+    }
 }
 export class MockAdapter {
     platform;
@@ -352,7 +429,7 @@ export class MockAdapter {
     capability() {
         return {
             platform: this.platform,
-            commands: ['navigate', 'tap', 'act', 'screenshot', 'wait', 'source']
+            commands: ['navigate', 'tap', 'act', 'scroll', 'screenshot', 'wait', 'source']
         };
     }
     async navigate(args) {
@@ -365,6 +442,14 @@ export class MockAdapter {
     async act(args) {
         return { action: 'act', platform: this.platform, args };
     }
+    async scroll(args) {
+        const { direction, percent } = resolveScrollOptions(args);
+        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`);

package/dist/cli.js

@@ -9,6 +9,7 @@ const ACTION_COMMANDS = new Set([
     'tap',
     'navigate',
     'act',
+    'scroll',
     'screenshot',
     'wait',
     'source'
@@ -44,6 +45,8 @@ const ACTION_SPEC = {
     target: 'string',
     x: 'number',
     y: 'number',
+    direction: 'string',
+    percent: 'number',
     normalized: 'boolean',
     to: 'string',
     name: 'string',
@@ -103,6 +106,7 @@ const COMMAND_SPECS = {
     tap: ACTION_SPEC,
     navigate: ACTION_SPEC,
     act: ACTION_SPEC,
+    scroll: ACTION_SPEC,
     screenshot: ACTION_SPEC,
     wait: ACTION_SPEC,
     source: ACTION_SPEC
@@ -123,11 +127,12 @@ function helpText() {
         '  start [--server-url <url>]',
         '  status [--server-url <url>]',
         '  stop [--server-url <url>] [--force]',
-        '  tap|navigate|act|screenshot|wait|source',
+        '  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',
         '  node dist/main.js status'
     ].join('\n');
 }
@@ -288,6 +293,7 @@ function cmdHelp() {
         examples: [
             'visor validate scenarios/checkout-smoke.json',
             'visor run scenarios/checkout-smoke.json --mock --output artifacts-test',
+            'visor scroll --platform android --mock --direction down',
             'node dist/main.js status'
         ]
     };

package/dist/main.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { executeCommand } from './cli.js';
 import { makeError } from './errors.js';
 import { makeId, utcNowIso } from './utils.js';
@@ -35,7 +38,20 @@ async function main(argv = process.argv.slice(2)) {
         return 1;
     }
 }
-if (import.meta.url === `file://${process.argv[1]}`) {
+function isDirectExecution() {
+    if (!process.argv[1]) {
+        return false;
+    }
+    try {
+        const currentModulePath = fs.realpathSync(fileURLToPath(import.meta.url));
+        const invokedPath = fs.realpathSync(path.resolve(process.argv[1]));
+        return currentModulePath === invokedPath;
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectExecution()) {
     void main().then((code) => {
         process.exitCode = code;
     });

package/dist/runner.js

@@ -11,6 +11,8 @@ async function runStep(adapter, command, args) {
             return adapter.navigate(args);
         case 'act':
             return adapter.act(args);
+        case 'scroll':
+            return adapter.scroll(args);
         case 'screenshot':
             return adapter.screenshot(args);
         case 'wait':

package/dist/validator.js

@@ -5,7 +5,7 @@ const ALLOWED_CONFIG = new Set(['timeoutMs', 'seed', 'artifactsDir']);
 const ALLOWED_STEP = new Set(['id', 'command', 'args']);
 const ALLOWED_ASSERT = new Set(['id', 'type', 'target']);
 const ALLOWED_OUTPUT = new Set(['report']);
-const SUPPORTED_COMMANDS = new Set(['tap', 'navigate', 'act', 'screenshot', 'wait', 'source']);
+const SUPPORTED_COMMANDS = new Set(['tap', 'navigate', 'act', 'scroll', 'screenshot', 'wait', 'source']);
 function validationIssue(severity, code, message, issuePath) {
     return { severity, code, message, path: issuePath };
 }
@@ -46,6 +46,21 @@ function validateTapArgs(args, issuePath) {
     }
     return issues;
 }
+function validateScrollArgs(args, issuePath) {
+    const issues = [];
+    if (!Object.hasOwn(args, 'direction')) {
+        issues.push(validationIssue('error', 'ARG_ERROR', 'scroll requires args.direction', issuePath));
+        return issues;
+    }
+    if (typeof args.direction !== 'string' || !['up', 'down'].includes(args.direction.toLowerCase())) {
+        issues.push(validationIssue('error', 'ARG_ERROR', "scroll args.direction must be 'up' or 'down'", issuePath));
+    }
+    if (Object.hasOwn(args, 'percent') &&
+        (typeof args.percent !== 'number' || !Number.isFinite(args.percent) || args.percent < 1 || args.percent > 100)) {
+        issues.push(validationIssue('error', 'ARG_ERROR', 'scroll args.percent must be a number between 1 and 100', issuePath));
+    }
+    return issues;
+}
 export function parseAndValidate(filePath) {
     const issues = [];
     const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
@@ -115,6 +130,9 @@ export function parseAndValidate(filePath) {
             if (command === 'navigate' && isRecord(args) && !Object.hasOwn(args, 'to')) {
                 issues.push(validationIssue('error', 'ARG_ERROR', 'navigate requires args.to', `${issuePath}.args`));
             }
+            if (command === 'scroll' && isRecord(args)) {
+                issues.push(...validateScrollArgs(args, `${issuePath}.args`));
+            }
             if (command === 'screenshot' && isRecord(args) && !Object.hasOwn(args, 'label')) {
                 issues.push(validationIssue('warning', 'DETERMINISM_WARNING', 'screenshot missing label may reduce determinism', `${issuePath}.args`));
             }

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "visor-ai",
-  "version": "0.2.1",
+  "version": "0.2.5",
   "description": "Visor CLI for LLM-driven mobile app interaction and artifact capture",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AleksKapera/visor"
+  },
+  "homepage": "https://github.com/AleksKapera/visor",
+  "bugs": {
+    "url": "https://github.com/AleksKapera/visor/issues"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -22,7 +30,11 @@
     "build": "rm -rf dist && tsc -p tsconfig.json",
     "dev": "tsx src/main.ts",
     "test": "vitest run",
-    "check": "npm run build && npm run test"
+    "check": "npm run build && npm run test",
+    "release": "node scripts/release.mjs",
+    "release:patch": "node scripts/release.mjs patch",
+    "release:minor": "node scripts/release.mjs minor",
+    "release:major": "node scripts/release.mjs major"
   },
   "keywords": [
     "appium",
@@ -43,4 +55,4 @@
     "typescript": "^5.8.2",
     "vitest": "^3.0.8"
   }
-}
+}