appium-session-recorder 0.0.2 → 0.0.4

package/src/cli/commands/session.ts

@@ -1,64 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { AppiumCommandClient } from '../../core/appium/client';
-import { ensureNoUnexpectedFlags, expectOptionalString, expectStringFlag, parseFlags } from '../arg-parser';
-import type { CommandExecutionResult } from './types';
-
-export async function runSessionCreate(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', 'caps-file', 'caps-json']);
-
-    const appiumUrl = expectStringFlag('appium-url', parsed.flags['appium-url']);
-    const capsFile = expectOptionalString(parsed.flags['caps-file']);
-    const capsJson = expectOptionalString(parsed.flags['caps-json']);
-
-    if ((capsFile && capsJson) || (!capsFile && !capsJson)) {
-        throw new Error('Provide exactly one of --caps-file or --caps-json');
-    }
-
-    let capabilities: Record<string, unknown>;
-
-    if (capsFile) {
-        const raw = await readFile(capsFile, 'utf8');
-        capabilities = JSON.parse(raw);
-    } else {
-        capabilities = JSON.parse(capsJson!);
-    }
-
-    const client = new AppiumCommandClient(appiumUrl);
-    const session = await client.createSession(capabilities);
-
-    return {
-        command: 'session.create',
-        result: {
-            appiumUrl,
-            sessionId: session.sessionId,
-            value: session.value,
-        },
-    };
-}
-
-export async function runSessionDelete(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.deleteSession(sessionId);
-
-    return {
-        command: 'session.delete',
-        result: {
-            appiumUrl,
-            sessionId,
-            deleted: true,
-        },
-    };
-}

package/src/cli/commands/types.ts

@@ -1,11 +0,0 @@
-import type { CliOutputOptions } from '../response';
-
-export type CommandHandlerInput = {
-    args: string[];
-    output: CliOutputOptions;
-};
-
-export type CommandExecutionResult = {
-    command: string;
-    result: unknown;
-};

package/src/cli/index.ts

@@ -1,158 +0,0 @@
-import * as p from '@clack/prompts';
-import { runPrompts } from './prompts';
-import { startServer } from '../server';
-import { parseArgs, parseCliInput } from './arg-parser';
-import { dispatchCommand } from './commands';
-import { emitResponse, errorResponse, successResponse } from './response';
-import { AppiumCommandError } from '../core/appium/client';
-import type { RecorderOptions } from '../server';
-
-function showHelp() {
-    console.log(`
-🎬 Appium Session Recorder
-
-USAGE:
-  bun run cli [legacy-options]
-  bun run cli <group> <command> [flags]
-
-LEGACY OPTIONS:
-  -p, --port <number>        Proxy server port (default: 4724)
-  -u, --appium-url <url>     Appium server URL (default: http://127.0.0.1:4723)
-  --host <host>              Proxy server host (default: 127.0.0.1)
-  -h, --help                 Show this help message
-  -v, --version              Show version
-
-GLOBAL COMMAND FLAGS:
-  --pretty                   Pretty-print JSON output
-  --output <path>            Write command JSON output to file
-  (supported only with <group> <command> mode)
-
-COMMAND GROUPS:
-  proxy start                Start proxy server (JSON-first output)
-  session create             Create Appium session
-  session delete             Delete Appium session
-  screen snapshot            Capture screenshot/source and parsed metadata
-  screen elements            List parsed elements
-  selectors best             Return top ranked selectors for an element
-  drive tap                  Tap element by selector
-  drive type                 Type text into element by selector
-  drive back                 Navigate back
-  drive swipe                Perform swipe gesture
-  drive scroll               Scroll in a direction (up/down/left/right)
-`);
-}
-
-function showVersion() {
-    console.log('Appium Session Recorder v3.0.0');
-}
-
-async function runLegacyCLI(argv: string[]): Promise<void> {
-    const result = parseArgs(argv);
-
-    if (!result.success) {
-        console.error(`Error: ${result.error}`);
-        process.exit(1);
-    }
-
-    const args = result.args;
-
-    if (args.help) {
-        showHelp();
-        process.exit(0);
-    }
-
-    if (args.version) {
-        showVersion();
-        process.exit(0);
-    }
-
-    // Determine if we need to run interactive prompts
-    const hasRequiredArgs = args.port !== undefined || args.appiumUrl !== undefined;
-
-    let promptConfig: Partial<RecorderOptions> = {
-        port: args.port,
-        appiumUrl: args.appiumUrl,
-        host: args.host,
-    };
-
-    if (!hasRequiredArgs) {
-        // Run interactive prompts
-        promptConfig = await runPrompts();
-    }
-
-    // Display startup banner
-    console.log('');
-    p.intro('🎬 Starting Appium Session Recorder');
-
-    const s = p.spinner();
-    s.start('Initializing server...');
-
-    try {
-        // Start server
-        startServer(promptConfig);
-        s.stop('✅ Server initialized');
-
-        console.log('');
-        console.log(`📊 Configuration:`);
-        console.log(`   Port:       ${promptConfig.port}`);
-        console.log(`   Appium URL: ${promptConfig.appiumUrl}`);
-        console.log(`   Host:       ${promptConfig.host}`);
-
-        p.outro('🚀 Server is running! Press Ctrl+C to stop.');
-    } catch (error) {
-        s.stop('❌ Failed to start server');
-        console.error(error);
-        process.exit(1);
-    }
-
-    // Handle graceful shutdown
-    process.on('SIGINT', () => {
-        console.log('\n');
-        p.outro('👋 Shutting down...');
-        process.exit(0);
-    });
-}
-
-export async function runCLI(): Promise<void> {
-    const parsedInput = parseCliInput(process.argv);
-
-    if (!parsedInput.success) {
-        const response = errorResponse('cli.parse', 'CLI_PARSE_ERROR', parsedInput.error);
-        await emitResponse(response, { pretty: true });
-        process.exit(1);
-    }
-
-    const cliInput = parsedInput.value;
-
-    if (cliInput.mode === 'legacy') {
-        await runLegacyCLI(cliInput.legacyArgv ?? process.argv);
-        return;
-    }
-
-    const route = cliInput.route!;
-    const commandName = `${route.group}.${route.command}`;
-
-    try {
-        const execution = await dispatchCommand(route.group, route.command, route.args);
-        const response = successResponse(execution.command, execution.result);
-        await emitResponse(response, cliInput.global);
-    } catch (error) {
-        if (error instanceof AppiumCommandError) {
-            const response = errorResponse(commandName, error.code, error.message, {
-                status: error.status,
-                details: error.details,
-            });
-            await emitResponse(response, cliInput.global);
-            process.exit(1);
-            return;
-        }
-
-        const response = errorResponse(
-            commandName,
-            'COMMAND_EXECUTION_ERROR',
-            error instanceof Error ? error.message : 'Unknown error',
-        );
-        await emitResponse(response, cliInput.global);
-        process.exit(1);
-    }
-}

package/src/cli/prompts.ts

@@ -1,64 +0,0 @@
-import * as p from '@clack/prompts';
-import type {RecorderOptions} from '../server/types';
-
-export async function runPrompts(): Promise<Partial<RecorderOptions>> {
-    console.clear();
-
-    p.intro('🎬 Appium Session Recorder');
-
-    const defaults = {
-        port: '4724',
-        host: '127.0.0.1',
-        appiumUrl: 'http://127.0.0.1:4723',
-    } as const;
-
-    const answers = await p.group(
-        {
-            port: () => p.text({
-                message: `Proxy port (default: ${defaults.port}):`,
-                placeholder: defaults.port,
-                defaultValue: defaults.port,
-                validate: (value) => {
-                    if (!value || value.trim().length === 0) return;
-                    const num = Number(value);
-                    if (isNaN(num) || num < 1 || num > 65535) {
-                        return 'Please enter a valid port number (1-65535)';
-                    }
-                },
-            }),
-            host: () => p.text({
-                message: `Proxy host (default: ${defaults.host}):`,
-                placeholder: defaults.host,
-                defaultValue: defaults.host,
-                validate: (value) => {
-                    if (!value || value.trim().length === 0) return undefined;
-                },
-            }),
-            appiumUrl: () => p.text({
-                message: `Appium server URL (default: ${defaults.appiumUrl}):`,
-                placeholder: defaults.appiumUrl,
-                defaultValue: defaults.appiumUrl,
-                validate: (value) => {
-                    if (!value || value.trim().length === 0) return;
-                    try {
-                        new URL(value);
-                    } catch {
-                        return 'Please enter a valid URL';
-                    }
-                },
-            }),
-        },
-        {
-            onCancel: () => {
-                p.cancel('Operation cancelled.');
-                process.exit(0);
-            },
-        }
-    );
-
-    return {
-        port: Number((answers.port as string) || defaults.port),
-        host: ((answers.host as string) || defaults.host).trim(),
-        appiumUrl: ((answers.appiumUrl as string) || defaults.appiumUrl).trim(),
-    };
-}

package/src/cli/response.ts

@@ -1,44 +0,0 @@
-import { mkdir, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import type { CommandResponse } from '../core/types';
-
-export type CliOutputOptions = {
-    pretty: boolean;
-    output?: string;
-};
-
-export function successResponse<T>(command: string, result: T): CommandResponse<T> {
-    return {
-        ok: true,
-        command,
-        timestamp: new Date().toISOString(),
-        result,
-    };
-}
-
-export function errorResponse(command: string, code: string, message: string, details?: unknown): CommandResponse {
-    return {
-        ok: false,
-        command,
-        timestamp: new Date().toISOString(),
-        error: {
-            code,
-            message,
-            details,
-        },
-    };
-}
-
-export async function emitResponse(response: CommandResponse, options: CliOutputOptions): Promise<void> {
-    const output = options.pretty
-        ? `${JSON.stringify(response, null, 2)}\n`
-        : `${JSON.stringify(response)}\n`;
-
-    process.stdout.write(output);
-
-    if (options.output) {
-        const outPath = path.resolve(options.output);
-        await mkdir(path.dirname(outPath), { recursive: true });
-        await writeFile(outPath, output, 'utf8');
-    }
-}

package/src/core/appium/client.ts

@@ -1,248 +0,0 @@
-import type { Point } from '../types';
-
-const W3C_ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';
-
-export class AppiumCommandError extends Error {
-    constructor(
-        message: string,
-        public readonly code: string,
-        public readonly status: number,
-        public readonly details?: unknown,
-    ) {
-        super(message);
-    }
-}
-
-export class AppiumCommandClient {
-    constructor(private readonly appiumUrl: string) {}
-
-    private parseWindowSize(value: unknown): { width: number; height: number } | null {
-        if (!value || typeof value !== 'object') {
-            return null;
-        }
-
-        const candidate = value as Record<string, unknown>;
-        const width = Number(candidate.width);
-        const height = Number(candidate.height);
-
-        if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) {
-            return null;
-        }
-
-        return { width, height };
-    }
-
-    private async tryGetWindowSize(sessionId: string, endpoint: '/window/rect' | '/window/size'): Promise<{ width: number; height: number } | null> {
-        try {
-            const result = await this.request<unknown>('GET', `/session/${sessionId}${endpoint}`);
-            return this.parseWindowSize(result);
-        } catch {
-            return null;
-        }
-    }
-
-    private async getWindowSize(sessionId: string): Promise<{ width: number; height: number }> {
-        const rect = await this.tryGetWindowSize(sessionId, '/window/rect');
-        if (rect) {
-            return rect;
-        }
-
-        const size = await this.tryGetWindowSize(sessionId, '/window/size');
-        if (size) {
-            return size;
-        }
-
-        throw new AppiumCommandError(
-            'Unable to determine window size for scroll gesture',
-            'WINDOW_SIZE_UNAVAILABLE',
-            500,
-        );
-    }
-
-    private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
-        const response = await fetch(`${this.appiumUrl}${path}`, {
-            method,
-            headers: {
-                'Content-Type': 'application/json',
-            },
-            body: body === undefined ? undefined : JSON.stringify(body),
-        });
-
-        let data: any = null;
-        try {
-            data = await response.json();
-        } catch {
-            data = null;
-        }
-
-        if (!response.ok) {
-            const errorMessage = data?.value?.message || data?.message || `Appium request failed (${response.status})`;
-            const errorCode = data?.value?.error || 'APPIUM_REQUEST_FAILED';
-            throw new AppiumCommandError(errorMessage, errorCode, response.status, data);
-        }
-
-        if (data && typeof data === 'object' && 'value' in data) {
-            return data.value as T;
-        }
-
-        return data as T;
-    }
-
-    async createSession(caps: Record<string, unknown>): Promise<{ sessionId: string; value: unknown }> {
-        const payload = 'capabilities' in caps
-            ? caps
-            : {
-                  capabilities: {
-                      alwaysMatch: caps,
-                      firstMatch: [{}],
-                  },
-              };
-
-        const response = await fetch(`${this.appiumUrl}/session`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify(payload),
-        });
-
-        const data: any = await response.json();
-
-        if (!response.ok) {
-            const errorMessage = data?.value?.message || data?.message || `Failed to create session (${response.status})`;
-            const errorCode = data?.value?.error || 'APPIUM_SESSION_CREATE_FAILED';
-            throw new AppiumCommandError(errorMessage, errorCode, response.status, data);
-        }
-
-        const sessionId = data?.sessionId || data?.value?.sessionId;
-        if (!sessionId) {
-            throw new AppiumCommandError('Appium did not return a sessionId', 'APPIUM_SESSION_ID_MISSING', 500, data);
-        }
-
-        return {
-            sessionId,
-            value: data?.value,
-        };
-    }
-
-    async deleteSession(sessionId: string): Promise<void> {
-        await this.request('DELETE', `/session/${sessionId}`);
-    }
-
-    async getSource(sessionId: string): Promise<string> {
-        return await this.request<string>('GET', `/session/${sessionId}/source`);
-    }
-
-    async getScreenshot(sessionId: string): Promise<string> {
-        return await this.request<string>('GET', `/session/${sessionId}/screenshot`);
-    }
-
-    async captureState(sessionId: string): Promise<{ source: string; screenshot: string }> {
-        const [source, screenshot] = await Promise.all([
-            this.getSource(sessionId),
-            this.getScreenshot(sessionId),
-        ]);
-
-        return {
-            source,
-            screenshot,
-        };
-    }
-
-    async findElement(sessionId: string, using: string, value: string): Promise<string> {
-        const result = await this.request<Record<string, string>>('POST', `/session/${sessionId}/element`, {
-            using,
-            value,
-        });
-
-        return result[W3C_ELEMENT_KEY] || result.ELEMENT;
-    }
-
-    async tap(sessionId: string, using: string, value: string): Promise<void> {
-        const elementId = await this.findElement(sessionId, using, value);
-        if (!elementId) {
-            throw new AppiumCommandError('Element not found for tap command', 'ELEMENT_NOT_FOUND', 404, {
-                using,
-                value,
-            });
-        }
-
-        await this.request('POST', `/session/${sessionId}/element/${elementId}/click`, {});
-    }
-
-    async clear(sessionId: string, using: string, value: string): Promise<void> {
-        const elementId = await this.findElement(sessionId, using, value);
-        if (!elementId) {
-            throw new AppiumCommandError('Element not found for clear command', 'ELEMENT_NOT_FOUND', 404, {
-                using,
-                value,
-            });
-        }
-        await this.request('POST', `/session/${sessionId}/element/${elementId}/clear`, {});
-    }
-
-    async type(sessionId: string, using: string, value: string, text: string, clearFirst: boolean): Promise<void> {
-        const elementId = await this.findElement(sessionId, using, value);
-        if (!elementId) {
-            throw new AppiumCommandError('Element not found for type command', 'ELEMENT_NOT_FOUND', 404, {
-                using,
-                value,
-            });
-        }
-
-        if (clearFirst) {
-            await this.request('POST', `/session/${sessionId}/element/${elementId}/clear`, {});
-        }
-
-        await this.request('POST', `/session/${sessionId}/element/${elementId}/value`, {
-            text,
-            value: [...text],
-        });
-    }
-
-    async back(sessionId: string): Promise<void> {
-        await this.request('POST', `/session/${sessionId}/back`, {});
-    }
-
-    async swipe(sessionId: string, from: Point, to: Point, durationMs: number): Promise<void> {
-        await this.request('POST', `/session/${sessionId}/actions`, {
-            actions: [
-                {
-                    type: 'pointer',
-                    id: 'finger1',
-                    parameters: { pointerType: 'touch' },
-                    actions: [
-                        { type: 'pointerMove', duration: 0, x: from.x, y: from.y },
-                        { type: 'pointerDown', button: 0 },
-                        { type: 'pause', duration: Math.max(50, durationMs) },
-                        { type: 'pointerMove', duration: Math.max(50, durationMs), x: to.x, y: to.y },
-                        { type: 'pointerUp', button: 0 },
-                    ],
-                },
-            ],
-        });
-
-        await this.request('DELETE', `/session/${sessionId}/actions`);
-    }
-
-    async scroll(sessionId: string, direction: 'up' | 'down' | 'left' | 'right', durationMs = 300): Promise<void> {
-        const { width, height } = await this.getWindowSize(sessionId);
-
-        const centerX = Math.round(width * 0.5);
-        const centerY = Math.round(height * 0.5);
-        const startY = Math.round(height * 0.8);
-        const endY = Math.round(height * 0.2);
-        const startX = Math.round(width * 0.8);
-        const endX = Math.round(width * 0.2);
-
-        const coords: Record<'up' | 'down' | 'left' | 'right', { from: Point; to: Point }> = {
-            down: { from: { x: centerX, y: startY }, to: { x: centerX, y: endY } },
-            up: { from: { x: centerX, y: endY }, to: { x: centerX, y: startY } },
-            left: { from: { x: startX, y: centerY }, to: { x: endX, y: centerY } },
-            right: { from: { x: endX, y: centerY }, to: { x: startX, y: centerY } },
-        };
-
-        const { from, to } = coords[direction];
-        await this.swipe(sessionId, from, to, durationMs);
-    }
-}

package/src/core/index.ts

@@ -1,5 +0,0 @@
-export * from './types';
-export * from './appium/client';
-export * from './xml/parse-source';
-export * from './selectors/generate-candidates';
-export * from './selectors/score-candidates';