agent-device 0.4.2 → 0.5.0

package/src/utils/errors.ts

@@ -1,35 +0,0 @@
-export type ErrorCode =
-  | 'INVALID_ARGS'
-  | 'DEVICE_NOT_FOUND'
-  | 'TOOL_MISSING'
-  | 'APP_NOT_INSTALLED'
-  | 'UNSUPPORTED_PLATFORM'
-  | 'UNSUPPORTED_OPERATION'
-  | 'COMMAND_FAILED'
-  | 'UNKNOWN';
-
-export class AppError extends Error {
-  code: ErrorCode;
-  details?: Record<string, unknown>;
-  cause?: unknown;
-
-  constructor(
-    code: ErrorCode,
-    message: string,
-    details?: Record<string, unknown>,
-    cause?: unknown,
-  ) {
-    super(message);
-    this.code = code;
-    this.details = details;
-    this.cause = cause;
-  }
-}
-
-export function asAppError(err: unknown): AppError {
-  if (err instanceof AppError) return err;
-  if (err instanceof Error) {
-    return new AppError('UNKNOWN', err.message, undefined, err);
-  }
-  return new AppError('UNKNOWN', 'Unknown error', { err });
-}

package/src/utils/exec.ts

@@ -1,339 +0,0 @@
-import { spawn, spawnSync } from 'node:child_process';
-import { AppError } from './errors.ts';
-
-export type ExecResult = {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  stdoutBuffer?: Buffer;
-};
-
-export type ExecOptions = {
-  cwd?: string;
-  env?: NodeJS.ProcessEnv;
-  allowFailure?: boolean;
-  binaryStdout?: boolean;
-  stdin?: string | Buffer;
-  timeoutMs?: number;
-};
-
-export type ExecStreamOptions = ExecOptions & {
-  onStdoutChunk?: (chunk: string) => void;
-  onStderrChunk?: (chunk: string) => void;
-};
-
-export type ExecBackgroundResult = {
-  child: ReturnType<typeof spawn>;
-  wait: Promise<ExecResult>;
-};
-
-export async function runCmd(
-  cmd: string,
-  args: string[],
-  options: ExecOptions = {},
-): Promise<ExecResult> {
-  return new Promise((resolve, reject) => {
-    const child = spawn(cmd, args, {
-      cwd: options.cwd,
-      env: options.env,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    let stdout = '';
-    let stdoutBuffer: Buffer | undefined = options.binaryStdout ? Buffer.alloc(0) : undefined;
-    let stderr = '';
-    let didTimeout = false;
-    const timeoutMs = normalizeTimeoutMs(options.timeoutMs);
-    const timeoutHandle = timeoutMs
-      ? setTimeout(() => {
-        didTimeout = true;
-        child.kill('SIGKILL');
-      }, timeoutMs)
-      : null;
-
-    if (!options.binaryStdout) child.stdout.setEncoding('utf8');
-    child.stderr.setEncoding('utf8');
-
-    if (options.stdin !== undefined) {
-      child.stdin.write(options.stdin);
-    }
-    child.stdin.end();
-
-    child.stdout.on('data', (chunk) => {
-      if (options.binaryStdout) {
-        stdoutBuffer = Buffer.concat([
-          stdoutBuffer ?? Buffer.alloc(0),
-          Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk),
-        ]);
-      } else {
-        stdout += chunk;
-      }
-    });
-
-    child.stderr.on('data', (chunk) => {
-      stderr += chunk;
-    });
-
-    child.on('error', (err) => {
-      if (timeoutHandle) clearTimeout(timeoutHandle);
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === 'ENOENT') {
-        reject(new AppError('TOOL_MISSING', `${cmd} not found in PATH`, { cmd }, err));
-        return;
-      }
-      reject(new AppError('COMMAND_FAILED', `Failed to run ${cmd}`, { cmd, args }, err));
-    });
-
-    child.on('close', (code) => {
-      if (timeoutHandle) clearTimeout(timeoutHandle);
-      const exitCode = code ?? 1;
-      if (didTimeout && timeoutMs) {
-        reject(
-          new AppError('COMMAND_FAILED', `${cmd} timed out after ${timeoutMs}ms`, {
-            cmd,
-            args,
-            stdout,
-            stderr,
-            exitCode,
-            timeoutMs,
-          }),
-        );
-        return;
-      }
-      if (exitCode !== 0 && !options.allowFailure) {
-        reject(
-          new AppError('COMMAND_FAILED', `${cmd} exited with code ${exitCode}`, {
-            cmd,
-            args,
-            stdout,
-            stderr,
-            exitCode,
-          }),
-        );
-        return;
-      }
-      resolve({ stdout, stderr, exitCode, stdoutBuffer });
-    });
-  });
-}
-
-export async function whichCmd(cmd: string): Promise<boolean> {
-  try {
-    const { shell, args } = resolveWhichArgs(cmd);
-    const result = await runCmd(shell, args, { allowFailure: true });
-    return result.exitCode === 0 && result.stdout.trim().length > 0;
-  } catch {
-    return false;
-  }
-}
-
-export function runCmdSync(cmd: string, args: string[], options: ExecOptions = {}): ExecResult {
-  const result = spawnSync(cmd, args, {
-    cwd: options.cwd,
-    env: options.env,
-    stdio: ['pipe', 'pipe', 'pipe'],
-    encoding: options.binaryStdout ? undefined : 'utf8',
-    input: options.stdin,
-    timeout: normalizeTimeoutMs(options.timeoutMs),
-  });
-
-  if (result.error) {
-    const code = (result.error as NodeJS.ErrnoException).code;
-    if (code === 'ETIMEDOUT') {
-      throw new AppError('COMMAND_FAILED', `${cmd} timed out after ${normalizeTimeoutMs(options.timeoutMs)}ms`, {
-        cmd,
-        args,
-        timeoutMs: normalizeTimeoutMs(options.timeoutMs),
-      }, result.error);
-    }
-    if (code === 'ENOENT') {
-      throw new AppError('TOOL_MISSING', `${cmd} not found in PATH`, { cmd }, result.error);
-    }
-    throw new AppError('COMMAND_FAILED', `Failed to run ${cmd}`, { cmd, args }, result.error);
-  }
-
-  const stdoutBuffer = options.binaryStdout
-    ? Buffer.isBuffer(result.stdout)
-      ? result.stdout
-      : Buffer.from(result.stdout ?? '')
-    : undefined;
-  const stdout = options.binaryStdout
-    ? ''
-    : typeof result.stdout === 'string'
-      ? result.stdout
-      : (result.stdout ?? '').toString();
-  const stderr =
-    typeof result.stderr === 'string' ? result.stderr : (result.stderr ?? '').toString();
-  const exitCode = result.status ?? 1;
-
-  if (exitCode !== 0 && !options.allowFailure) {
-    throw new AppError('COMMAND_FAILED', `${cmd} exited with code ${exitCode}`, {
-      cmd,
-      args,
-      stdout,
-      stderr,
-      exitCode,
-    });
-  }
-
-  return { stdout, stderr, exitCode, stdoutBuffer };
-}
-
-export function runCmdDetached(cmd: string, args: string[], options: ExecOptions = {}): void {
-  const child = spawn(cmd, args, {
-    cwd: options.cwd,
-    env: options.env,
-    stdio: 'ignore',
-    detached: true,
-  });
-  child.unref();
-}
-
-export async function runCmdStreaming(
-  cmd: string,
-  args: string[],
-  options: ExecStreamOptions = {},
-): Promise<ExecResult> {
-  return new Promise((resolve, reject) => {
-    const child = spawn(cmd, args, {
-      cwd: options.cwd,
-      env: options.env,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    let stdout = '';
-    let stderr = '';
-    let stdoutBuffer: Buffer | undefined = options.binaryStdout ? Buffer.alloc(0) : undefined;
-
-    if (!options.binaryStdout) child.stdout.setEncoding('utf8');
-    child.stderr.setEncoding('utf8');
-
-    if (options.stdin !== undefined) {
-      child.stdin.write(options.stdin);
-    }
-    child.stdin.end();
-
-    child.stdout.on('data', (chunk) => {
-      if (options.binaryStdout) {
-        stdoutBuffer = Buffer.concat([
-          stdoutBuffer ?? Buffer.alloc(0),
-          Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk),
-        ]);
-        return;
-      }
-      const text = String(chunk);
-      stdout += text;
-      options.onStdoutChunk?.(text);
-    });
-
-    child.stderr.on('data', (chunk) => {
-      const text = String(chunk);
-      stderr += text;
-      options.onStderrChunk?.(text);
-    });
-
-    child.on('error', (err) => {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === 'ENOENT') {
-        reject(new AppError('TOOL_MISSING', `${cmd} not found in PATH`, { cmd }, err));
-        return;
-      }
-      reject(new AppError('COMMAND_FAILED', `Failed to run ${cmd}`, { cmd, args }, err));
-    });
-
-    child.on('close', (code) => {
-      const exitCode = code ?? 1;
-      if (exitCode !== 0 && !options.allowFailure) {
-        reject(
-          new AppError('COMMAND_FAILED', `${cmd} exited with code ${exitCode}`, {
-            cmd,
-            args,
-            stdout,
-            stderr,
-            exitCode,
-          }),
-        );
-        return;
-      }
-      resolve({ stdout, stderr, exitCode, stdoutBuffer });
-    });
-  });
-}
-
-export function runCmdBackground(
-  cmd: string,
-  args: string[],
-  options: ExecOptions = {},
-): ExecBackgroundResult {
-  const child = spawn(cmd, args, {
-    cwd: options.cwd,
-    env: options.env,
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-
-  let stdout = '';
-  let stderr = '';
-
-  child.stdout.setEncoding('utf8');
-  child.stderr.setEncoding('utf8');
-
-  child.stdout.on('data', (chunk) => {
-    stdout += chunk;
-  });
-  child.stderr.on('data', (chunk) => {
-    stderr += chunk;
-  });
-
-  const wait = new Promise<ExecResult>((resolve, reject) => {
-    child.on('error', (err) => {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === 'ENOENT') {
-        reject(new AppError('TOOL_MISSING', `${cmd} not found in PATH`, { cmd }, err));
-        return;
-      }
-      reject(new AppError('COMMAND_FAILED', `Failed to run ${cmd}`, { cmd, args }, err));
-    });
-    child.on('close', (code) => {
-      const exitCode = code ?? 1;
-      if (exitCode !== 0 && !options.allowFailure) {
-        reject(
-          new AppError('COMMAND_FAILED', `${cmd} exited with code ${exitCode}`, {
-            cmd,
-            args,
-            stdout,
-            stderr,
-            exitCode,
-          }),
-        );
-        return;
-      }
-      resolve({ stdout, stderr, exitCode });
-    });
-  });
-
-  return { child, wait };
-}
-
-export function whichCmdSync(cmd: string): boolean {
-  try {
-    const { shell, args } = resolveWhichArgs(cmd);
-    const result = runCmdSync(shell, args, { allowFailure: true });
-    return result.exitCode === 0 && result.stdout.trim().length > 0;
-  } catch {
-    return false;
-  }
-}
-
-function resolveWhichArgs(cmd: string): { shell: string; args: string[] } {
-  if (process.platform === 'win32') {
-    return { shell: 'cmd.exe', args: ['/c', 'where', cmd] };
-  }
-  return { shell: 'bash', args: ['-lc', `command -v ${cmd}`] };
-}
-
-function normalizeTimeoutMs(value: number | undefined): number | undefined {
-  if (!Number.isFinite(value)) return undefined;
-  const timeout = Math.floor(value as number);
-  if (timeout <= 0) return undefined;
-  return timeout;
-}

package/src/utils/finders.ts

@@ -1,101 +0,0 @@
-import type { SnapshotNode } from './snapshot.ts';
-
-export type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
-
-export type FindMatchOptions = {
-  requireRect?: boolean;
-};
-
-export type FindBestMatches = {
-  matches: SnapshotNode[];
-  score: number;
-};
-
-export function findNodeByLocator(
-  nodes: SnapshotNode[],
-  locator: FindLocator,
-  query: string,
-  options: FindMatchOptions = {},
-): SnapshotNode | null {
-  const best = findBestMatchesByLocator(nodes, locator, query, options);
-  return best.matches[0] ?? null;
-}
-
-export function findBestMatchesByLocator(
-  nodes: SnapshotNode[],
-  locator: FindLocator,
-  query: string,
-  options: FindMatchOptions = {},
-): FindBestMatches {
-  const normalizedQuery = normalizeText(query);
-  if (!normalizedQuery) return { matches: [], score: 0 };
-  let bestScore = 0;
-  const matches: SnapshotNode[] = [];
-  for (const node of nodes) {
-    if (options.requireRect && !node.rect) continue;
-    const score = matchNode(node, locator, normalizedQuery);
-    if (score <= 0) continue;
-    if (score > bestScore) {
-      bestScore = score;
-      matches.length = 0;
-      matches.push(node);
-      continue;
-    }
-    if (score === bestScore) {
-      matches.push(node);
-    }
-  }
-  return { matches, score: bestScore };
-}
-
-function matchNode(node: SnapshotNode, locator: FindLocator, query: string): number {
-  switch (locator) {
-    case 'role':
-      return matchRole(node.type, query);
-    case 'label':
-      return matchText(node.label, query);
-    case 'value':
-      return matchText(node.value, query);
-    case 'id':
-      return matchText(node.identifier, query);
-    case 'text':
-    case 'any':
-    default:
-      return Math.max(
-        matchText(node.label, query),
-        matchText(node.value, query),
-        matchText(node.identifier, query),
-      );
-  }
-}
-
-function matchText(value: string | undefined, query: string): number {
-  const normalized = normalizeText(value ?? '');
-  if (!normalized) return 0;
-  if (normalized === query) return 2;
-  if (normalized.includes(query)) return 1;
-  return 0;
-}
-
-function matchRole(value: string | undefined, query: string): number {
-  const normalized = normalizeRole(value ?? '');
-  if (!normalized) return 0;
-  if (normalized === query) return 2;
-  if (normalized.includes(query)) return 1;
-  return 0;
-}
-
-function normalizeText(value: string): string {
-  return value.trim().toLowerCase().replace(/\s+/g, ' ');
-}
-
-function normalizeRole(value: string): string {
-  let normalized = value.trim();
-  if (!normalized) return '';
-  const lastSegment = normalized.split('.').pop() ?? normalized;
-  normalized = lastSegment.replace(/XCUIElementType/gi, '').toLowerCase();
-  if (normalized.startsWith('ax')) {
-    normalized = normalized.replace(/^ax/, '');
-  }
-  return normalized;
-}

package/src/utils/interactive.ts

@@ -1,4 +0,0 @@
-export function isInteractive(): boolean {
-  if (process.env.CI) return false;
-  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
-}

package/src/utils/interactors.ts

@@ -1,173 +0,0 @@
-import { AppError } from './errors.ts';
-import type { DeviceInfo } from './device.ts';
-import {
-  closeAndroidApp,
-  fillAndroid,
-  focusAndroid,
-  longPressAndroid,
-  openAndroidApp,
-  openAndroidDevice,
-  pressAndroid,
-  swipeAndroid,
-  scrollAndroid,
-  scrollIntoViewAndroid,
-  screenshotAndroid,
-  typeAndroid,
-} from '../platforms/android/index.ts';
-import {
-  closeIosApp,
-  openIosApp,
-  openIosDevice,
-  screenshotIos,
-} from '../platforms/ios/index.ts';
-import { runIosRunnerCommand } from '../platforms/ios/runner-client.ts';
-
-export type RunnerContext = {
-  appBundleId?: string;
-  verbose?: boolean;
-  logPath?: string;
-  traceLogPath?: string;
-};
-
-export type Interactor = {
-  open(app: string, options?: { activity?: string; appBundleId?: string; url?: string }): Promise<void>;
-  openDevice(): Promise<void>;
-  close(app: string): Promise<void>;
-  tap(x: number, y: number): Promise<void>;
-  swipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
-  longPress(x: number, y: number, durationMs?: number): Promise<void>;
-  focus(x: number, y: number): Promise<void>;
-  type(text: string): Promise<void>;
-  fill(x: number, y: number, text: string): Promise<void>;
-  scroll(direction: string, amount?: number): Promise<void>;
-  scrollIntoView(text: string): Promise<{ attempts?: number } | void>;
-  screenshot(outPath: string): Promise<void>;
-};
-
-export function getInteractor(device: DeviceInfo, runnerContext: RunnerContext): Interactor {
-  switch (device.platform) {
-    case 'android':
-      return {
-        open: (app, options) => openAndroidApp(device, app, options?.activity),
-        openDevice: () => openAndroidDevice(device),
-        close: (app) => closeAndroidApp(device, app),
-        tap: (x, y) => pressAndroid(device, x, y),
-        swipe: (x1, y1, x2, y2, durationMs) => swipeAndroid(device, x1, y1, x2, y2, durationMs),
-        longPress: (x, y, durationMs) => longPressAndroid(device, x, y, durationMs),
-        focus: (x, y) => focusAndroid(device, x, y),
-        type: (text) => typeAndroid(device, text),
-        fill: (x, y, text) => fillAndroid(device, x, y, text),
-        scroll: (direction, amount) => scrollAndroid(device, direction, amount),
-        scrollIntoView: (text) => scrollIntoViewAndroid(device, text),
-        screenshot: (outPath) => screenshotAndroid(device, outPath),
-      };
-    case 'ios':
-      return {
-        open: (app, options) => openIosApp(device, app, { appBundleId: options?.appBundleId, url: options?.url }),
-        openDevice: () => openIosDevice(device),
-        close: (app) => closeIosApp(device, app),
-        screenshot: (outPath) => screenshotIos(device, outPath),
-        ...iosRunnerOverrides(device, runnerContext),
-      };
-    default:
-      throw new AppError('UNSUPPORTED_PLATFORM', `Unsupported platform: ${device.platform}`);
-  }
-}
-
-type IoRunnerOverrides = Pick<Interactor, 'tap' | 'swipe' | 'longPress' | 'focus' | 'type' | 'fill' | 'scroll' | 'scrollIntoView'>;
-
-function iosRunnerOverrides(device: DeviceInfo, ctx: RunnerContext): IoRunnerOverrides {
-  const runnerOpts = { verbose: ctx.verbose, logPath: ctx.logPath, traceLogPath: ctx.traceLogPath };
-
-  return {
-    tap: async (x, y) => {
-      await runIosRunnerCommand(
-        device,
-        { command: 'tap', x, y, appBundleId: ctx.appBundleId },
-        runnerOpts,
-      );
-    },
-    swipe: async (x1, y1, x2, y2, durationMs) => {
-      await runIosRunnerCommand(
-        device,
-        { command: 'drag', x: x1, y: y1, x2, y2, durationMs, appBundleId: ctx.appBundleId },
-        runnerOpts,
-      );
-    },
-    longPress: async (x, y, durationMs) => {
-      await runIosRunnerCommand(
-        device,
-        { command: 'longPress', x, y, durationMs, appBundleId: ctx.appBundleId },
-        runnerOpts,
-      );
-    },
-    focus: async (x, y) => {
-      await runIosRunnerCommand(
-        device,
-        { command: 'tap', x, y, appBundleId: ctx.appBundleId },
-        runnerOpts,
-      );
-    },
-    type: async (text) => {
-      await runIosRunnerCommand(
-        device,
-        { command: 'type', text, appBundleId: ctx.appBundleId },
-        runnerOpts,
-      );
-    },
-    fill: async (x, y, text) => {
-      await runIosRunnerCommand(
-        device,
-        { command: 'tap', x, y, appBundleId: ctx.appBundleId },
-        runnerOpts,
-      );
-      await runIosRunnerCommand(
-        device,
-        { command: 'type', text, clearFirst: true, appBundleId: ctx.appBundleId },
-        runnerOpts,
-      );
-    },
-    scroll: async (direction, _amount) => {
-      if (!['up', 'down', 'left', 'right'].includes(direction)) {
-        throw new AppError('INVALID_ARGS', `Unknown direction: ${direction}`);
-      }
-      const inverted = invertScrollDirection(direction as 'up' | 'down' | 'left' | 'right');
-      await runIosRunnerCommand(
-        device,
-        { command: 'swipe', direction: inverted, appBundleId: ctx.appBundleId },
-        runnerOpts,
-      );
-    },
-    scrollIntoView: async (text) => {
-      const maxAttempts = 8;
-      for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
-        const found = (await runIosRunnerCommand(
-          device,
-          { command: 'findText', text, appBundleId: ctx.appBundleId },
-          runnerOpts,
-        )) as { found?: boolean };
-        if (found?.found) return { attempts: attempt + 1 };
-        await runIosRunnerCommand(
-          device,
-          { command: 'swipe', direction: 'up', appBundleId: ctx.appBundleId },
-          runnerOpts,
-        );
-        await new Promise((resolve) => setTimeout(resolve, 300));
-      }
-      throw new AppError('COMMAND_FAILED', `scrollintoview could not find text: ${text}`);
-    },
-  };
-}
-
-function invertScrollDirection(direction: 'up' | 'down' | 'left' | 'right'): 'up' | 'down' | 'left' | 'right' {
-  switch (direction) {
-    case 'up':
-      return 'down';
-    case 'down':
-      return 'up';
-    case 'left':
-      return 'right';
-    case 'right':
-      return 'left';
-  }
-}

package/src/utils/keyed-lock.ts

@@ -1,14 +0,0 @@
-export async function withKeyedLock<T>(
-  locks: Map<string, Promise<unknown>>,
-  key: string,
-  task: () => Promise<T>,
-): Promise<T> {
-  const previous = locks.get(key) ?? Promise.resolve();
-  const current = previous.catch(() => {}).then(task);
-  locks.set(key, current);
-  return current.finally(() => {
-    if (locks.get(key) === current) {
-      locks.delete(key);
-    }
-  });
-}