npm - visor-ai - Versions diffs - 0.2.1 - Mend

visor-ai 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/dist/report.js ADDED Viewed

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { canonicalJson, ensureDir } from './utils.js';
+function escapeXml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+function junitXml(run) {
+    const tests = run.steps.length;
+    const failures = run.steps.filter((step) => step.status !== 'ok').length;
+    const lines = [
+        `<testsuite name="${escapeXml(run.run_id)}" tests="${tests}" failures="${failures}">`
+    ];
+    for (const step of run.steps) {
+        lines.push(`  <testcase name="${escapeXml(step.id)}" classname="visor.${escapeXml(run.platform)}" time="${(step.duration_ms / 1000).toFixed(3)}">`);
+        if (step.status !== 'ok') {
+            const message = step.error?.message ?? 'step failed';
+            lines.push(`    <failure message="${escapeXml(message)}" />`);
+        }
+        lines.push('  </testcase>');
+    }
+    lines.push('</testsuite>');
+    return `${lines.join('\n')}\n`;
+}
+function materializeArtifacts(root, artifactPaths) {
+    const screenshotsDir = ensureDir(path.join(root, 'screenshots'));
+    const sourcesDir = ensureDir(path.join(root, 'sources'));
+    const persisted = [];
+    artifactPaths.forEach((artifactPath, index) => {
+        if (!fs.existsSync(artifactPath)) {
+            return;
+        }
+        const sourcePath = path.resolve(artifactPath);
+        const destinationRoot = sourcePath.toLowerCase().endsWith('.png') ? screenshotsDir : sourcesDir;
+        const destinationPath = path.join(destinationRoot, `${String(index + 1).padStart(3, '0')}-${path.basename(sourcePath)}`);
+        if (sourcePath !== path.resolve(destinationPath)) {
+            fs.copyFileSync(sourcePath, destinationPath);
+        }
+        persisted.push(destinationPath);
+    });
+    return persisted;
+}
+export function writeReports(result, reportDir) {
+    const root = ensureDir(path.join(reportDir, result.run_id));
+    const env = ensureDir(path.join(root, 'env'));
+    const payload = structuredClone(result);
+    const persistedArtifacts = materializeArtifacts(root, result.artifacts);
+    payload.artifacts = persistedArtifacts;
+    result.artifacts = persistedArtifacts;
+    const summaryTxt = path.join(root, 'summary.txt');
+    const summaryJson = path.join(root, 'summary.json');
+    const junitPath = path.join(root, 'junit.xml');
+    const timelinePath = path.join(root, 'timeline.log');
+    const htmlPath = path.join(root, 'report.html');
+    fs.writeFileSync(summaryTxt, [
+        `run_id: ${result.run_id}`,
+        `platform: ${result.platform}`,
+        `device: ${result.device}`,
+        `status: ${result.status}`,
+        `determinism_signature: ${result.determinism_signature}`,
+        `artifact_count: ${result.artifacts.length}`,
+        ''
+    ].join('\n'), 'utf8');
+    fs.writeFileSync(summaryJson, `${canonicalJson(payload)}\n`, 'utf8');
+    fs.writeFileSync(junitPath, junitXml(payload), 'utf8');
+    fs.writeFileSync(timelinePath, `${payload.steps
+        .map((step, index) => `${String(index + 1).padStart(3, '0')} ${step.id} ${step.command} ${step.status} ${step.duration_ms}ms`)
+        .join('\n')}\n`, 'utf8');
+    fs.writeFileSync(path.join(env, 'runtime.json'), `${JSON.stringify({
+        seed: result.seed,
+        started_at: result.started_at,
+        ended_at: result.ended_at
+    }, null, 2)}\n`, 'utf8');
+    fs.writeFileSync(path.join(env, 'device.json'), `${JSON.stringify({
+        platform: result.platform,
+        device: result.device
+    }, null, 2)}\n`, 'utf8');
+    fs.writeFileSync(htmlPath, `<html><body><h1>${escapeXml(result.run_id)}</h1><p>Status: ${escapeXml(result.status)}</p><p>Artifacts: ${result.artifacts.length}</p></body></html>\n`, 'utf8');
+    return {
+        summary: summaryTxt,
+        json: summaryJson,
+        junit: junitPath,
+        timeline: timelinePath,
+        html: htmlPath
+    };
+}

package/dist/runner.js ADDED Viewed

@@ -0,0 +1,177 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { makeError } from './errors.js';
+import { makeId, signatureFor, utcNowIso } from './utils.js';
+async function runStep(adapter, command, args) {
+    switch (command) {
+        case 'tap':
+            return adapter.tap(args);
+        case 'navigate':
+            return adapter.navigate(args);
+        case 'act':
+            return adapter.act(args);
+        case 'screenshot':
+            return adapter.screenshot(args);
+        case 'wait':
+            return adapter.wait(args);
+        case 'source':
+            return adapter.source(args);
+    }
+}
+async function evaluateAssertions(adapter, assertions) {
+    const results = [];
+    let ok = true;
+    const failedTargets = [];
+    for (const assertion of assertions) {
+        let status = 'passed';
+        let details = '';
+        if (assertion.type === 'visible') {
+            const visible = await adapter.exists(assertion.target);
+            if (!visible) {
+                status = 'failed';
+                details = `Target not visible: ${assertion.target}`;
+                ok = false;
+                failedTargets.push(assertion.target);
+            }
+        }
+        else {
+            status = 'failed';
+            details = `Unsupported assertion type: ${assertion.type}`;
+            ok = false;
+            failedTargets.push(assertion.target);
+        }
+        results.push({
+            id: assertion.id,
+            type: assertion.type,
+            target: assertion.target,
+            status,
+            details
+        });
+    }
+    return { results, ok, failedTargets };
+}
+function signatureSafeDetails(details) {
+    const safe = structuredClone(details);
+    const args = safe.args;
+    if (args && typeof args === 'object' && !Array.isArray(args)) {
+        delete args.path;
+    }
+    return safe;
+}
+export async function runScenario(scenario, adapter, device = 'local', timeoutMs, artifactBaseDir) {
+    const started_at = utcNowIso();
+    const run_id = makeId('run');
+    const platform = scenario.meta.platform;
+    const stepResults = [];
+    const artifacts = [];
+    let topError;
+    let screenshotDir;
+    let sourceDir;
+    if (artifactBaseDir) {
+        screenshotDir = path.join(artifactBaseDir, run_id, 'screenshots');
+        sourceDir = path.join(artifactBaseDir, run_id, 'sources');
+        fs.mkdirSync(screenshotDir, { recursive: true });
+        fs.mkdirSync(sourceDir, { recursive: true });
+    }
+    try {
+        for (const step of scenario.steps) {
+            const started = performance.now();
+            try {
+                const stepArgs = { ...step.args };
+                if (step.command === 'screenshot' && screenshotDir) {
+                    const label = String(stepArgs.label ?? step.id);
+                    stepArgs.path = path.join(screenshotDir, `${label}.png`);
+                }
+                if (step.command === 'source' && sourceDir) {
+                    const label = String(stepArgs.label ?? step.id);
+                    stepArgs.path = path.join(sourceDir, `${label}.xml`);
+                }
+                const details = await runStep(adapter, step.command, stepArgs);
+                const durationMs = Math.round(performance.now() - started);
+                const result = {
+                    id: step.id,
+                    command: step.command,
+                    status: 'ok',
+                    duration_ms: durationMs,
+                    details
+                };
+                if (step.command === 'screenshot' || step.command === 'source') {
+                    const args = details.args;
+                    if (args && typeof args === 'object' && !Array.isArray(args)) {
+                        const artifactPath = typeof args.path === 'string'
+                            ? args.path
+                            : typeof args.file === 'string'
+                                ? args.file
+                                : '';
+                        if (artifactPath) {
+                            artifacts.push(artifactPath);
+                        }
+                    }
+                }
+                if (timeoutMs && durationMs > timeoutMs) {
+                    result.status = 'fail';
+                    result.error = makeError('ACTION_ERROR', `Step '${step.id}' exceeded timeout`, 'Device/app was too slow for configured timeout', 'Increase --timeout or optimize target action');
+                }
+                stepResults.push(result);
+            }
+            catch (error) {
+                const durationMs = Math.round(performance.now() - started);
+                stepResults.push({
+                    id: step.id,
+                    command: step.command,
+                    status: 'fail',
+                    duration_ms: durationMs,
+                    details: {},
+                    error: makeError('ACTION_ERROR', `Step '${step.id}' failed`, error instanceof Error ? error.message : String(error), 'Inspect step args and platform adapter support')
+                });
+            }
+        }
+        const assertionEvaluation = await evaluateAssertions(adapter, scenario.assertions);
+        const stepsOk = stepResults.every((step) => step.status === 'ok');
+        if (!stepsOk) {
+            topError = makeError('ACTION_ERROR', 'Run failed due to one or more action step failures', 'At least one command execution step returned failure', 'Inspect failed step error payloads in run.steps and retry');
+        }
+        if (!assertionEvaluation.ok) {
+            const firstFailedTarget = assertionEvaluation.failedTargets[0] ?? 'unknown target';
+            topError = makeError('ASSERTION_ERROR', 'Run failed due to assertion failure', `Expected UI target was not satisfied: ${firstFailedTarget}`, 'Verify selector correctness and app state before assertion step');
+        }
+        const allPass = stepsOk && assertionEvaluation.ok;
+        const ended_at = utcNowIso();
+        const signatureInput = {
+            platform,
+            steps: stepResults.map((step) => ({
+                id: step.id,
+                command: step.command,
+                status: step.status,
+                details: signatureSafeDetails(step.details)
+            })),
+            assertions: assertionEvaluation.results
+        };
+        return {
+            run_id,
+            platform,
+            device,
+            started_at,
+            ended_at,
+            status: allPass ? 'ok' : 'fail',
+            steps: stepResults,
+            assertions: assertionEvaluation.results,
+            artifacts,
+            determinism_signature: signatureFor(signatureInput),
+            seed: typeof scenario.config.seed === 'number' ? scenario.config.seed : undefined,
+            error: topError
+        };
+    }
+    finally {
+        await adapter.close();
+    }
+}
+export function determinismCheck(signatures) {
+    if (signatures.length === 0) {
+        return 0;
+    }
+    const baseline = signatures[0];
+    const same = signatures.filter((signature) => signature === baseline).length;
+    return Math.round((same / signatures.length) * 10000) / 100;
+}

package/dist/types.js ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/dist/utils.js ADDED Viewed

@@ -0,0 +1,118 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+export function utcNowIso() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+export function makeId(prefix) {
+    return `${prefix}_${randomUUID().replace(/-/g, '').slice(0, 12)}`;
+}
+function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sortValue(item));
+    }
+    if (value && typeof value === 'object') {
+        const input = value;
+        return Object.keys(input)
+            .sort()
+            .reduce((acc, key) => {
+            acc[key] = sortValue(input[key]);
+            return acc;
+        }, {});
+    }
+    return value;
+}
+export function canonicalJson(data) {
+    return JSON.stringify(sortValue(data));
+}
+export function signatureFor(data) {
+    return createHash('sha256').update(canonicalJson(data), 'utf8').digest('hex');
+}
+export function ensureDir(targetPath) {
+    fs.mkdirSync(targetPath, { recursive: true });
+    return targetPath;
+}
+export async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function parseServerUrl(serverUrl) {
+    const parsed = new URL(serverUrl);
+    return {
+        server_url: serverUrl,
+        protocol: parsed.protocol.replace(':', '') || 'http',
+        host: parsed.hostname || '127.0.0.1',
+        port: Number(parsed.port || 4723),
+        pathname: parsed.pathname && parsed.pathname !== '' ? parsed.pathname : '/'
+    };
+}
+export function readJsonFile(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+export function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+export function resolveExecutable(baseName) {
+    const pathValue = process.env.PATH ?? '';
+    const pathEntries = pathValue.split(path.delimiter).filter(Boolean);
+    const candidates = process.platform === 'win32'
+        ? [baseName, `${baseName}.cmd`, `${baseName}.exe`, `${baseName}.bat`]
+        : [baseName];
+    for (const entry of pathEntries) {
+        for (const candidate of candidates) {
+            const fullPath = path.join(entry, candidate);
+            try {
+                fs.accessSync(fullPath, fs.constants.X_OK);
+                return fullPath;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+export function splitCommandLine(command) {
+    const parts = [];
+    let current = '';
+    let quote = null;
+    let escaping = false;
+    for (const char of command) {
+        if (escaping) {
+            current += char;
+            escaping = false;
+            continue;
+        }
+        if (char === '\\') {
+            escaping = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (current !== '') {
+                parts.push(current);
+                current = '';
+            }
+            continue;
+        }
+        current += char;
+    }
+    if (current !== '') {
+        parts.push(current);
+    }
+    return parts;
+}

package/dist/validator.js ADDED Viewed

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+const ALLOWED_TOP = new Set(['meta', 'config', 'steps', 'assertions', 'output']);
+const ALLOWED_META = new Set(['name', 'version', 'platform', 'tags']);
+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']);
+function validationIssue(severity, code, message, issuePath) {
+    return { severity, code, message, path: issuePath };
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function unknownFields(obj, allowed, issuePath) {
+    return Object.keys(obj)
+        .filter((key) => !allowed.has(key))
+        .map((key) => validationIssue('error', 'UNKNOWN_FIELD', `Unknown field '${key}'`, issuePath ? `${issuePath}.${key}` : key));
+}
+function requiredFields(obj, fields, issuePath) {
+    return fields
+        .filter((field) => !(field in obj))
+        .map((field) => validationIssue('error', 'MISSING_REQUIRED', `Missing required field '${field}'`, issuePath));
+}
+function validateTapArgs(args, issuePath) {
+    const issues = [];
+    const hasTarget = Object.hasOwn(args, 'target');
+    const hasX = Object.hasOwn(args, 'x');
+    const hasY = Object.hasOwn(args, 'y');
+    if (hasTarget) {
+        if (hasX || hasY) {
+            issues.push(validationIssue('error', 'ARG_ERROR', 'tap cannot mix args.target with args.x/args.y', issuePath));
+        }
+        return issues;
+    }
+    if (hasX !== hasY) {
+        issues.push(validationIssue('error', 'ARG_ERROR', 'tap coordinate mode requires both args.x and args.y', issuePath));
+        return issues;
+    }
+    if (!hasX && !hasY) {
+        issues.push(validationIssue('error', 'ARG_ERROR', 'tap requires args.target or args.x/args.y', issuePath));
+        return issues;
+    }
+    if (Object.hasOwn(args, 'normalized') && typeof args.normalized !== 'boolean') {
+        issues.push(validationIssue('error', 'ARG_ERROR', 'tap args.normalized must be boolean', issuePath));
+    }
+    return issues;
+}
+export function parseAndValidate(filePath) {
+    const issues = [];
+    const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (!isRecord(raw)) {
+        return {
+            scenario: null,
+            issues: [validationIssue('error', 'TYPE_ERROR', 'Scenario root must be object', '$')]
+        };
+    }
+    issues.push(...unknownFields(raw, ALLOWED_TOP, '$'));
+    issues.push(...requiredFields(raw, ['meta', 'config', 'steps'], '$'));
+    const metaRaw = raw.meta;
+    const configRaw = raw.config;
+    const stepsRaw = raw.steps;
+    const assertionsRaw = raw.assertions ?? [];
+    const outputRaw = raw.output ?? {};
+    let meta = null;
+    if (isRecord(metaRaw)) {
+        issues.push(...unknownFields(metaRaw, ALLOWED_META, '$.meta'));
+        issues.push(...requiredFields(metaRaw, ['name', 'version', 'platform'], '$.meta'));
+        if (metaRaw.platform !== 'ios' && metaRaw.platform !== 'android') {
+            issues.push(validationIssue('error', 'INPUT_ERROR', 'meta.platform must be ios|android', '$.meta.platform'));
+        }
+        else if (typeof metaRaw.name === 'string' && typeof metaRaw.version === 'string') {
+            meta = {
+                ...metaRaw,
+                name: metaRaw.name,
+                version: metaRaw.version,
+                platform: metaRaw.platform
+            };
+        }
+    }
+    else {
+        issues.push(validationIssue('error', 'TYPE_ERROR', 'meta must be object', '$.meta'));
+    }
+    const config = isRecord(configRaw) ? configRaw : {};
+    if (isRecord(configRaw)) {
+        issues.push(...unknownFields(configRaw, ALLOWED_CONFIG, '$.config'));
+    }
+    else {
+        issues.push(validationIssue('error', 'TYPE_ERROR', 'config must be object', '$.config'));
+    }
+    if (!Object.hasOwn(config, 'seed')) {
+        issues.push(validationIssue('warning', 'DETERMINISM_WARNING', 'config.seed is missing', '$.config'));
+    }
+    const steps = [];
+    if (!Array.isArray(stepsRaw) || stepsRaw.length === 0) {
+        issues.push(validationIssue('error', 'TYPE_ERROR', 'steps must be non-empty list', '$.steps'));
+    }
+    else {
+        for (const [index, rawStep] of stepsRaw.entries()) {
+            const issuePath = `$.steps[${index}]`;
+            if (!isRecord(rawStep)) {
+                issues.push(validationIssue('error', 'TYPE_ERROR', 'step must be object', issuePath));
+                continue;
+            }
+            issues.push(...unknownFields(rawStep, ALLOWED_STEP, issuePath));
+            issues.push(...requiredFields(rawStep, ['id', 'command', 'args'], issuePath));
+            const command = rawStep.command;
+            const args = rawStep.args;
+            if (typeof command === 'string' && !SUPPORTED_COMMANDS.has(command)) {
+                issues.push(validationIssue('error', 'UNSUPPORTED_COMMAND', `Unsupported command '${command}'`, `${issuePath}.command`));
+            }
+            if (command === 'tap' && isRecord(args)) {
+                issues.push(...validateTapArgs(args, `${issuePath}.args`));
+            }
+            if (command === 'navigate' && isRecord(args) && !Object.hasOwn(args, 'to')) {
+                issues.push(validationIssue('error', 'ARG_ERROR', 'navigate requires args.to', `${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`));
+            }
+            if (command === 'wait' && isRecord(args) && !Object.hasOwn(args, 'ms')) {
+                issues.push(validationIssue('error', 'ARG_ERROR', 'wait requires args.ms', `${issuePath}.args`));
+            }
+            if (typeof rawStep.id === 'string' &&
+                typeof command === 'string' &&
+                SUPPORTED_COMMANDS.has(command) &&
+                isRecord(args)) {
+                steps.push({
+                    id: rawStep.id,
+                    command: command,
+                    args
+                });
+            }
+        }
+    }
+    const assertions = [];
+    if (Array.isArray(assertionsRaw)) {
+        for (const [index, rawAssertion] of assertionsRaw.entries()) {
+            const issuePath = `$.assertions[${index}]`;
+            if (!isRecord(rawAssertion)) {
+                issues.push(validationIssue('error', 'TYPE_ERROR', 'assertion must be object', issuePath));
+                continue;
+            }
+            issues.push(...unknownFields(rawAssertion, ALLOWED_ASSERT, issuePath));
+            issues.push(...requiredFields(rawAssertion, ['id', 'type', 'target'], issuePath));
+            if (typeof rawAssertion.id === 'string' &&
+                typeof rawAssertion.type === 'string' &&
+                typeof rawAssertion.target === 'string') {
+                assertions.push({
+                    id: rawAssertion.id,
+                    type: rawAssertion.type,
+                    target: rawAssertion.target
+                });
+            }
+        }
+    }
+    else {
+        issues.push(validationIssue('error', 'TYPE_ERROR', 'assertions must be list', '$.assertions'));
+    }
+    const output = isRecord(outputRaw) ? outputRaw : {};
+    if (isRecord(outputRaw)) {
+        issues.push(...unknownFields(outputRaw, ALLOWED_OUTPUT, '$.output'));
+    }
+    else {
+        issues.push(validationIssue('error', 'TYPE_ERROR', 'output must be object', '$.output'));
+    }
+    if (issues.some((issue) => issue.severity === 'error') || meta === null) {
+        return {
+            scenario: null,
+            issues
+        };
+    }
+    return {
+        scenario: {
+            meta,
+            config,
+            steps,
+            assertions,
+            output
+        },
+        issues
+    };
+}

package/package.json ADDED Viewed

@@ -0,0 +1,46 @@
+{
+  "name": "visor-ai",
+  "version": "0.2.1",
+  "description": "Visor CLI for LLM-driven mobile app interaction and artifact capture",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "visor": "./dist/main.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "dev": "tsx src/main.ts",
+    "test": "vitest run",
+    "check": "npm run build && npm run test"
+  },
+  "keywords": [
+    "appium",
+    "mobile",
+    "automation",
+    "webdriverio",
+    "ios",
+    "android",
+    "cli"
+  ],
+  "dependencies": {
+    "appium": "^2.17.0",
+    "webdriverio": "^9.19.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
+  }
+}