appium-session-recorder 0.0.2 → 0.0.4

package/src/cli/arg-parser.ts

@@ -1,311 +0,0 @@
-import type { RecorderOptions } from '../server/types';
-
-export type ParsedArgs = Partial<RecorderOptions> & {
-    help?: boolean;
-    version?: boolean;
-};
-
-export type ParseArgsResult =
-    | { success: true; args: ParsedArgs }
-    | { success: false; error: string };
-
-export function parseArgs(argv: string[]): ParseArgsResult {
-    const args = argv.slice(2);
-    const parsed: ParsedArgs = {};
-
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-
-        if (arg === '--help' || arg === '-h') {
-            parsed.help = true;
-        } else if (arg === '--version' || arg === '-v') {
-            parsed.version = true;
-        } else if (arg === '--port' || arg === '-p') {
-            if (i + 1 >= args.length) {
-                return { success: false, error: '--port requires a value' };
-            }
-            parsed.port = Number(args[++i]);
-            if (isNaN(parsed.port)) {
-                return { success: false, error: '--port must be a number' };
-            }
-        } else if (arg === '--appium-url' || arg === '-u') {
-            if (i + 1 >= args.length) {
-                return { success: false, error: '--appium-url requires a value' };
-            }
-            parsed.appiumUrl = args[++i];
-        } else if (arg === '--host') {
-            if (i + 1 >= args.length) {
-                return { success: false, error: '--host requires a value' };
-            }
-            parsed.host = args[++i];
-        }
-    }
-
-    return { success: true, args: parsed };
-}
-
-export function validatePort(value: string): string | undefined {
-    if (value.trim().length === 0) return undefined;
-    const num = Number(value);
-    if (isNaN(num) || num < 1 || num > 65535) {
-        return 'Please enter a valid port number (1-65535)';
-    }
-    return undefined;
-}
-
-export function validateUrl(value: string): string | undefined {
-    if (value.trim().length === 0) return undefined;
-    try {
-        new URL(value);
-        return undefined;
-    } catch {
-        return 'Please enter a valid URL';
-    }
-}
-
-export function validateHost(value: string): string | undefined {
-    if (value.trim().length === 0) return undefined;
-    if (!value || value.trim().length === 0) {
-        return 'Please enter a valid host';
-    }
-    return undefined;
-}
-
-export type GlobalCliOptions = {
-    pretty: boolean;
-    output?: string;
-};
-
-export type CommandRoute = {
-    group: 'proxy' | 'session' | 'screen' | 'selectors' | 'drive';
-    command: string;
-    args: string[];
-};
-
-export type ParsedCliInput = {
-    mode: 'legacy' | 'command';
-    global: GlobalCliOptions;
-    legacyArgv?: string[];
-    route?: CommandRoute;
-    help?: boolean;
-    version?: boolean;
-};
-
-export type ParseCliInputResult =
-    | { success: true; value: ParsedCliInput }
-    | { success: false; error: string };
-
-const commandSubcommands: Record<string, string[]> = {
-    proxy: ['start'],
-    session: ['create', 'delete'],
-    screen: ['snapshot', 'elements'],
-    selectors: ['best'],
-    drive: ['tap', 'type', 'back', 'swipe', 'scroll'],
-};
-
-const LEGACY_GLOBAL_FLAGS_ERROR = '--pretty and --output are only supported with <group> <command> mode';
-
-function hasLegacyOnlyGlobalFlags(global: GlobalCliOptions): boolean {
-    return global.pretty || global.output !== undefined;
-}
-
-export function parseCliInput(argv: string[]): ParseCliInputResult {
-    const input = argv.slice(2);
-    const global: GlobalCliOptions = { pretty: false };
-    const remaining: string[] = [];
-    let wantsHelp = false;
-    let wantsVersion = false;
-
-    for (let i = 0; i < input.length; i++) {
-        const token = input[i];
-
-        if (token === '--pretty') {
-            global.pretty = true;
-            continue;
-        }
-
-        if (token === '--output') {
-            const value = input[i + 1];
-            if (!value || value.startsWith('-')) {
-                return { success: false, error: '--output requires a file path value' };
-            }
-            global.output = value;
-            i++;
-            continue;
-        }
-
-        if (token === '--help' || token === '-h') {
-            wantsHelp = true;
-            continue;
-        }
-
-        if (token === '--version' || token === '-v') {
-            wantsVersion = true;
-            continue;
-        }
-
-        remaining.push(token);
-    }
-
-    if (wantsHelp) {
-        if (hasLegacyOnlyGlobalFlags(global)) {
-            return { success: false, error: LEGACY_GLOBAL_FLAGS_ERROR };
-        }
-        return {
-            success: true,
-            value: {
-                mode: 'legacy',
-                help: true,
-                global,
-                legacyArgv: ['node', 'script', '--help'],
-            },
-        };
-    }
-
-    if (wantsVersion) {
-        if (hasLegacyOnlyGlobalFlags(global)) {
-            return { success: false, error: LEGACY_GLOBAL_FLAGS_ERROR };
-        }
-        return {
-            success: true,
-            value: {
-                mode: 'legacy',
-                version: true,
-                global,
-                legacyArgv: ['node', 'script', '--version'],
-            },
-        };
-    }
-
-    if (remaining.length === 0) {
-        if (hasLegacyOnlyGlobalFlags(global)) {
-            return { success: false, error: LEGACY_GLOBAL_FLAGS_ERROR };
-        }
-        return {
-            success: true,
-            value: {
-                mode: 'legacy',
-                global,
-                legacyArgv: ['node', 'script'],
-            },
-        };
-    }
-
-    const maybeGroup = remaining[0];
-    if (!(maybeGroup in commandSubcommands)) {
-        if (hasLegacyOnlyGlobalFlags(global)) {
-            return { success: false, error: LEGACY_GLOBAL_FLAGS_ERROR };
-        }
-        return {
-            success: true,
-            value: {
-                mode: 'legacy',
-                global,
-                legacyArgv: ['node', 'script', ...remaining],
-            },
-        };
-    }
-
-    const subcommand = remaining[1];
-    if (!subcommand) {
-        return { success: false, error: `Missing subcommand for '${maybeGroup}'` };
-    }
-
-    const allowed = commandSubcommands[maybeGroup];
-    if (!allowed.includes(subcommand)) {
-        return {
-            success: false,
-            error: `Unknown subcommand '${subcommand}' for '${maybeGroup}'. Allowed: ${allowed.join(', ')}`,
-        };
-    }
-
-    return {
-        success: true,
-        value: {
-            mode: 'command',
-            global,
-            route: {
-                group: maybeGroup as CommandRoute['group'],
-                command: subcommand,
-                args: remaining.slice(2),
-            },
-        },
-    };
-}
-
-export type ParseFlagsResult =
-    | { success: true; flags: Record<string, string | boolean>; positionals: string[] }
-    | { success: false; error: string };
-
-export function parseFlags(args: string[]): ParseFlagsResult {
-    const flags: Record<string, string | boolean> = {};
-    const positionals: string[] = [];
-
-    for (let i = 0; i < args.length; i++) {
-        const token = args[i];
-
-        if (!token.startsWith('-')) {
-            positionals.push(token);
-            continue;
-        }
-
-        if (!token.startsWith('--')) {
-            return { success: false, error: `Short options are not supported in command mode: '${token}'` };
-        }
-
-        const equalsIndex = token.indexOf('=');
-        if (equalsIndex > -1) {
-            const key = token.slice(2, equalsIndex);
-            const value = token.slice(equalsIndex + 1);
-            if (!key) return { success: false, error: `Invalid flag '${token}'` };
-            flags[key] = value;
-            continue;
-        }
-
-        const key = token.slice(2);
-        if (!key) return { success: false, error: `Invalid flag '${token}'` };
-
-        const next = args[i + 1];
-        if (!next || next.startsWith('--')) {
-            flags[key] = true;
-            continue;
-        }
-
-        flags[key] = next;
-        i++;
-    }
-
-    return { success: true, flags, positionals };
-}
-
-export function parseNumberFlag(name: string, value: string | boolean | undefined): number | undefined {
-    if (typeof value !== 'string') return undefined;
-    const parsed = Number(value);
-    if (!Number.isFinite(parsed)) {
-        throw new Error(`--${name} must be a number`);
-    }
-    return parsed;
-}
-
-export function expectStringFlag(name: string, value: string | boolean | undefined): string {
-    if (typeof value !== 'string' || value.trim().length === 0) {
-        throw new Error(`--${name} is required`);
-    }
-    return value;
-}
-
-export function expectOptionalString(value: string | boolean | undefined): string | undefined {
-    if (typeof value !== 'string') return undefined;
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-}
-
-export function ensureNoUnexpectedFlags(
-    flags: Record<string, string | boolean>,
-    allowed: string[],
-): void {
-    const unknown = Object.keys(flags).filter(key => !allowed.includes(key));
-    if (unknown.length > 0) {
-        throw new Error(`Unknown flags: ${unknown.map(flag => `--${flag}`).join(', ')}`);
-    }
-}

package/src/cli/commands/drive.ts

@@ -1,147 +0,0 @@
-import { AppiumCommandClient } from '../../core/appium/client';
-import { ensureNoUnexpectedFlags, expectStringFlag, parseFlags, parseNumberFlag } from '../arg-parser';
-
-const SCROLL_DIRECTIONS = ['up', 'down', 'left', 'right'] as const;
-type ScrollDirection = (typeof SCROLL_DIRECTIONS)[number];
-import type { CommandExecutionResult } from './types';
-
-function parsePoint(name: string, value: string): { x: number; y: number } {
-    const [xRaw, yRaw] = value.split(',');
-    const x = Number(xRaw);
-    const y = Number(yRaw);
-
-    if (!Number.isFinite(x) || !Number.isFinite(y)) {
-        throw new Error(`--${name} must be in format x,y`);
-    }
-
-    return { x, y };
-}
-
-export async function runDriveTap(args: string[]): Promise<CommandExecutionResult> {
-    const parsed = parseFlags(args);
-    if (!parsed.success) throw new Error(parsed.error);
-    if (parsed.positionals.length > 0) throw new Error(`Unexpected arguments: ${parsed.positionals.join(', ')}`);
-
-    ensureNoUnexpectedFlags(parsed.flags, ['appium-url', 'session-id', 'using', 'value']);
-
-    const appiumUrl = expectStringFlag('appium-url', parsed.flags['appium-url']);
-    const sessionId = expectStringFlag('session-id', parsed.flags['session-id']);
-    const using = expectStringFlag('using', parsed.flags.using);
-    const value = expectStringFlag('value', parsed.flags.value);
-
-    const client = new AppiumCommandClient(appiumUrl);
-    await client.tap(sessionId, using, value);
-
-    return {
-        command: 'drive.tap',
-        result: { sessionId, using, value, performed: true },
-    };
-}
-
-export async function runDriveType(args: string[]): Promise<CommandExecutionResult> {
-    const parsed = parseFlags(args);
-    if (!parsed.success) throw new Error(parsed.error);
-    if (parsed.positionals.length > 0) throw new Error(`Unexpected arguments: ${parsed.positionals.join(', ')}`);
-
-    ensureNoUnexpectedFlags(parsed.flags, ['appium-url', 'session-id', 'using', 'value', 'text', 'clear-first']);
-
-    const appiumUrl = expectStringFlag('appium-url', parsed.flags['appium-url']);
-    const sessionId = expectStringFlag('session-id', parsed.flags['session-id']);
-    const using = expectStringFlag('using', parsed.flags.using);
-    const value = expectStringFlag('value', parsed.flags.value);
-    const text = expectStringFlag('text', parsed.flags.text);
-    const clearFirst = parsed.flags['clear-first'] === true;
-
-    const client = new AppiumCommandClient(appiumUrl);
-    await client.type(sessionId, using, value, text, clearFirst);
-
-    return {
-        command: 'drive.type',
-        result: { sessionId, using, value, textLength: text.length, clearFirst, performed: true },
-    };
-}
-
-export async function runDriveBack(args: string[]): Promise<CommandExecutionResult> {
-    const parsed = parseFlags(args);
-    if (!parsed.success) throw new Error(parsed.error);
-    if (parsed.positionals.length > 0) throw new Error(`Unexpected arguments: ${parsed.positionals.join(', ')}`);
-
-    ensureNoUnexpectedFlags(parsed.flags, ['appium-url', 'session-id']);
-
-    const appiumUrl = expectStringFlag('appium-url', parsed.flags['appium-url']);
-    const sessionId = expectStringFlag('session-id', parsed.flags['session-id']);
-
-    const client = new AppiumCommandClient(appiumUrl);
-    await client.back(sessionId);
-
-    return {
-        command: 'drive.back',
-        result: { sessionId, performed: true },
-    };
-}
-
-export async function runDriveSwipe(args: string[]): Promise<CommandExecutionResult> {
-    const parsed = parseFlags(args);
-    if (!parsed.success) throw new Error(parsed.error);
-    if (parsed.positionals.length > 0) throw new Error(`Unexpected arguments: ${parsed.positionals.join(', ')}`);
-
-    ensureNoUnexpectedFlags(parsed.flags, ['appium-url', 'session-id', 'from', 'to', 'duration-ms']);
-
-    const appiumUrl = expectStringFlag('appium-url', parsed.flags['appium-url']);
-    const sessionId = expectStringFlag('session-id', parsed.flags['session-id']);
-    const from = parsePoint('from', expectStringFlag('from', parsed.flags.from));
-    const to = parsePoint('to', expectStringFlag('to', parsed.flags.to));
-    const durationMs = parseNumberFlag('duration-ms', parsed.flags['duration-ms']) ?? 300;
-
-    if (!Number.isFinite(durationMs) || durationMs < 1) {
-        throw new Error('--duration-ms must be a positive number');
-    }
-
-    const client = new AppiumCommandClient(appiumUrl);
-    await client.swipe(sessionId, from, to, durationMs);
-
-    return {
-        command: 'drive.swipe',
-        result: {
-            sessionId,
-            from,
-            to,
-            durationMs,
-            performed: true,
-        },
-    };
-}
-
-export async function runDriveScroll(args: string[]): Promise<CommandExecutionResult> {
-    const parsed = parseFlags(args);
-    if (!parsed.success) throw new Error(parsed.error);
-    if (parsed.positionals.length > 0) throw new Error(`Unexpected arguments: ${parsed.positionals.join(', ')}`);
-
-    ensureNoUnexpectedFlags(parsed.flags, ['appium-url', 'session-id', 'direction', 'duration-ms']);
-
-    const appiumUrl = expectStringFlag('appium-url', parsed.flags['appium-url']);
-    const sessionId = expectStringFlag('session-id', parsed.flags['session-id']);
-    const direction = expectStringFlag('direction', parsed.flags.direction);
-    const durationMs = parseNumberFlag('duration-ms', parsed.flags['duration-ms']) ?? 300;
-
-    if (!SCROLL_DIRECTIONS.includes(direction as ScrollDirection)) {
-        throw new Error(`--direction must be one of: ${SCROLL_DIRECTIONS.join(', ')}`);
-    }
-
-    if (!Number.isFinite(durationMs) || durationMs < 1) {
-        throw new Error('--duration-ms must be a positive number');
-    }
-
-    const client = new AppiumCommandClient(appiumUrl);
-    await client.scroll(sessionId, direction as ScrollDirection, durationMs);
-
-    return {
-        command: 'drive.scroll',
-        result: {
-            sessionId,
-            direction,
-            durationMs,
-            performed: true,
-        },
-    };
-}

package/src/cli/commands/index.ts

@@ -1,54 +0,0 @@
-import { runDriveBack, runDriveScroll, runDriveSwipe, runDriveTap, runDriveType } from './drive';
-import { runProxyStart } from './proxy';
-import { runScreenElements, runScreenSnapshot } from './screen';
-import { runSelectorsBest } from './selectors';
-import { runSessionCreate, runSessionDelete } from './session';
-import type { CommandExecutionResult } from './types';
-
-export async function dispatchCommand(group: string, command: string, args: string[]): Promise<CommandExecutionResult> {
-    if (group === 'proxy' && command === 'start') {
-        return await runProxyStart(args);
-    }
-
-    if (group === 'session' && command === 'create') {
-        return await runSessionCreate(args);
-    }
-
-    if (group === 'session' && command === 'delete') {
-        return await runSessionDelete(args);
-    }
-
-    if (group === 'screen' && command === 'snapshot') {
-        return await runScreenSnapshot(args);
-    }
-
-    if (group === 'screen' && command === 'elements') {
-        return await runScreenElements(args);
-    }
-
-    if (group === 'selectors' && command === 'best') {
-        return await runSelectorsBest(args);
-    }
-
-    if (group === 'drive' && command === 'tap') {
-        return await runDriveTap(args);
-    }
-
-    if (group === 'drive' && command === 'type') {
-        return await runDriveType(args);
-    }
-
-    if (group === 'drive' && command === 'back') {
-        return await runDriveBack(args);
-    }
-
-    if (group === 'drive' && command === 'swipe') {
-        return await runDriveSwipe(args);
-    }
-
-    if (group === 'drive' && command === 'scroll') {
-        return await runDriveScroll(args);
-    }
-
-    throw new Error(`Unsupported command: ${group} ${command}`);
-}

package/src/cli/commands/proxy.ts

@@ -1,41 +0,0 @@
-import { createServer } from '../../server/server';
-import { ensureNoUnexpectedFlags, expectOptionalString, parseFlags, parseNumberFlag } from '../arg-parser';
-import type { CommandExecutionResult } from './types';
-
-export async function runProxyStart(args: string[]): Promise<CommandExecutionResult> {
-    const parsed = parseFlags(args);
-    if (!parsed.success) throw new Error(parsed.error);
-    if (parsed.positionals.length > 0) throw new Error(`Unexpected arguments: ${parsed.positionals.join(', ')}`);
-
-    ensureNoUnexpectedFlags(parsed.flags, ['host', 'port', 'appium-url']);
-
-    const host = expectOptionalString(parsed.flags.host) ?? '127.0.0.1';
-    const port = parseNumberFlag('port', parsed.flags.port) ?? 4724;
-    const appiumUrl = expectOptionalString(parsed.flags['appium-url']) ?? 'http://127.0.0.1:4723';
-
-    if (!Number.isInteger(port) || port < 1 || port > 65535) {
-        throw new Error('--port must be an integer between 1 and 65535');
-    }
-
-    const { app } = createServer({ host, port, appiumUrl });
-    const server = app.listen(port, host);
-
-    process.on('SIGINT', () => {
-        server.close(() => process.exit(0));
-    });
-    process.on('SIGTERM', () => {
-        server.close(() => process.exit(0));
-    });
-
-    return {
-        command: 'proxy.start',
-        result: {
-            host,
-            port,
-            appiumUrl,
-            proxyUrl: `http://${host}:${port}`,
-            viewerUrl: `http://${host}:${port}/_recorder`,
-            running: true,
-        },
-    };
-}

package/src/cli/commands/screen.ts

@@ -1,73 +0,0 @@
-import { AppiumCommandClient } from '../../core/appium/client';
-import { parseSource } from '../../core/xml/parse-source';
-import { ensureNoUnexpectedFlags, expectStringFlag, parseFlags, parseNumberFlag } from '../arg-parser';
-import type { CommandExecutionResult } from './types';
-
-export async function runScreenSnapshot(args: string[]): Promise<CommandExecutionResult> {
-    const parsed = parseFlags(args);
-    if (!parsed.success) throw new Error(parsed.error);
-    if (parsed.positionals.length > 0) throw new Error(`Unexpected arguments: ${parsed.positionals.join(', ')}`);
-
-    ensureNoUnexpectedFlags(parsed.flags, ['appium-url', 'session-id']);
-
-    const appiumUrl = expectStringFlag('appium-url', parsed.flags['appium-url']);
-    const sessionId = expectStringFlag('session-id', parsed.flags['session-id']);
-
-    const client = new AppiumCommandClient(appiumUrl);
-    const { source, screenshot } = await client.captureState(sessionId);
-    const parsedSource = parseSource(source);
-
-    return {
-        command: 'screen.snapshot',
-        result: {
-            sessionId,
-            platform: parsedSource.platform,
-            screenshot,
-            source,
-            metadata: {
-                elementCount: parsedSource.elements.length,
-            },
-        },
-    };
-}
-
-export async function runScreenElements(args: string[]): Promise<CommandExecutionResult> {
-    const parsed = parseFlags(args);
-    if (!parsed.success) throw new Error(parsed.error);
-    if (parsed.positionals.length > 0) throw new Error(`Unexpected arguments: ${parsed.positionals.join(', ')}`);
-
-    ensureNoUnexpectedFlags(parsed.flags, ['appium-url', 'session-id', 'limit', 'only-actionable']);
-
-    const appiumUrl = expectStringFlag('appium-url', parsed.flags['appium-url']);
-    const sessionId = expectStringFlag('session-id', parsed.flags['session-id']);
-    const limit = parseNumberFlag('limit', parsed.flags.limit);
-    const onlyActionable = parsed.flags['only-actionable'] === true;
-
-    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
-        throw new Error('--limit must be a positive integer');
-    }
-
-    const client = new AppiumCommandClient(appiumUrl);
-    const source = await client.getSource(sessionId);
-    const parsedSource = parseSource(source);
-
-    let elements = parsedSource.elements;
-    if (onlyActionable) {
-        elements = elements.filter(element => element.enabled && element.visible && (element.clickable || element.accessible));
-    }
-    if (limit !== undefined) {
-        elements = elements.slice(0, limit);
-    }
-
-    return {
-        command: 'screen.elements',
-        result: {
-            sessionId,
-            platform: parsedSource.platform,
-            total: parsedSource.elements.length,
-            returned: elements.length,
-            onlyActionable,
-            elements,
-        },
-    };
-}

package/src/cli/commands/selectors.ts

@@ -1,42 +0,0 @@
-import { AppiumCommandClient } from '../../core/appium/client';
-import { generateSelectorCandidates } from '../../core/selectors/generate-candidates';
-import { rankSelectorCandidates } from '../../core/selectors/score-candidates';
-import { parseSource } from '../../core/xml/parse-source';
-import { ensureNoUnexpectedFlags, expectStringFlag, parseFlags } from '../arg-parser';
-import type { CommandExecutionResult } from './types';
-
-export async function runSelectorsBest(args: string[]): Promise<CommandExecutionResult> {
-    const parsed = parseFlags(args);
-    if (!parsed.success) throw new Error(parsed.error);
-    if (parsed.positionals.length > 0) throw new Error(`Unexpected arguments: ${parsed.positionals.join(', ')}`);
-
-    ensureNoUnexpectedFlags(parsed.flags, ['appium-url', 'session-id', 'element-ref']);
-
-    const appiumUrl = expectStringFlag('appium-url', parsed.flags['appium-url']);
-    const sessionId = expectStringFlag('session-id', parsed.flags['session-id']);
-    const elementRef = expectStringFlag('element-ref', parsed.flags['element-ref']);
-
-    const client = new AppiumCommandClient(appiumUrl);
-    const source = await client.getSource(sessionId);
-    const parsedSource = parseSource(source);
-
-    const target = parsedSource.elements.find(element => element.elementRef === elementRef);
-    if (!target) {
-        throw new Error(`Element not found for --element-ref '${elementRef}'`);
-    }
-
-    const candidates = generateSelectorCandidates(target);
-    const ranked = rankSelectorCandidates(target, parsedSource.elements, candidates);
-
-    return {
-        command: 'selectors.best',
-        result: {
-            sessionId,
-            platform: parsedSource.platform,
-            elementRef,
-            target,
-            topSelectors: ranked.slice(0, 5),
-            allSelectors: ranked,
-        },
-    };
-}