agent-device 0.4.2 → 0.5.0

package/src/utils/output.ts

@@ -1,204 +0,0 @@
-import { AppError } from './errors.ts';
-
-export type JsonResult =
-  | { success: true; data?: Record<string, unknown> }
-  | { success: false; error: { code: string; message: string; details?: Record<string, unknown> } };
-
-export function printJson(result: JsonResult): void {
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-}
-
-export function printHumanError(err: AppError): void {
-  const details = err.details ? `\n${JSON.stringify(err.details, null, 2)}` : '';
-  process.stderr.write(`Error (${err.code}): ${err.message}${details}\n`);
-}
-
-type SnapshotRect = { x: number; y: number; width: number; height: number };
-type SnapshotNode = {
-  ref?: string;
-  depth?: number;
-  type?: string;
-  label?: string;
-  value?: string;
-  identifier?: string;
-  rect?: SnapshotRect;
-  hittable?: boolean;
-  enabled?: boolean;
-};
-
-export function formatSnapshotText(
-  data: Record<string, unknown>,
-  options: { raw?: boolean; flatten?: boolean } = {},
-): string {
-  const rawNodes = data.nodes;
-  const nodes = Array.isArray(rawNodes) ? (rawNodes as SnapshotNode[]) : [];
-  const truncated = Boolean(data.truncated);
-  const appName = typeof data.appName === 'string' ? data.appName : undefined;
-  const appBundleId = typeof data.appBundleId === 'string' ? data.appBundleId : undefined;
-  const meta: string[] = [];
-  if (appName) meta.push(`Page: ${appName}`);
-  if (appBundleId) meta.push(`App: ${appBundleId}`);
-  const header = `Snapshot: ${nodes.length} nodes${truncated ? ' (truncated)' : ''}`;
-  const prefix = meta.length > 0 ? `${meta.join('\n')}\n` : '';
-  if (nodes.length === 0) {
-    return `${prefix}${header}\n`;
-  }
-  if (options.raw) {
-    const rawLines = nodes.map((node) => JSON.stringify(node));
-    return `${prefix}${header}\n${rawLines.join('\n')}\n`;
-  }
-  if (options.flatten) {
-    const flatLines = nodes.map((node) => formatSnapshotLine(node, 0, false));
-    return `${prefix}${header}\n${flatLines.join('\n')}\n`;
-  }
-  const hiddenGroupDepths: number[] = [];
-  const lines: string[] = [];
-  for (const node of nodes) {
-    const depth = node.depth ?? 0;
-    while (hiddenGroupDepths.length > 0 && depth <= hiddenGroupDepths[hiddenGroupDepths.length - 1]) {
-      hiddenGroupDepths.pop();
-    }
-    const label = node.label?.trim() || node.value?.trim() || node.identifier?.trim() || '';
-    const type = formatRole(node.type ?? 'Element');
-    const isHiddenGroup = type === 'group' && !label;
-    if (isHiddenGroup) {
-      hiddenGroupDepths.push(depth);
-    }
-    const adjustedDepth = isHiddenGroup
-      ? depth
-      : Math.max(0, depth - hiddenGroupDepths.length);
-    lines.push(formatSnapshotLine(node, adjustedDepth, isHiddenGroup));
-  }
-  return `${prefix}${header}\n${lines.join('\n')}\n`;
-}
-
-function formatSnapshotLine(node: SnapshotNode, depth: number, hiddenGroup: boolean): string {
-  const type = formatRole(node.type ?? 'Element');
-  const label = displayLabel(node, type);
-  const indent = '  '.repeat(depth);
-  const ref = node.ref ? `@${node.ref}` : '';
-  const flags = [node.enabled === false ? 'disabled' : null].filter(Boolean).join(', ');
-  const flagText = flags ? ` [${flags}]` : '';
-  const textPart = label ? ` "${label}"` : '';
-  if (hiddenGroup) {
-    return `${indent}${ref} [${type}]${flagText}`.trimEnd();
-  }
-  return `${indent}${ref} [${type}]${textPart}${flagText}`.trimEnd();
-}
-
-function displayLabel(node: SnapshotNode, type: string): string {
-  const label = node.label?.trim();
-  const value = node.value?.trim();
-  if (isEditableRole(type)) {
-    // For inputs, prefer current value over placeholder/accessibility label.
-    if (value) return value;
-    if (label) return label;
-  } else if (label) {
-    return label;
-  }
-  if (value) return value;
-  const identifier = node.identifier?.trim();
-  if (!identifier) return '';
-  if (isGenericResourceId(identifier) && (type === 'group' || type === 'image' || type === 'list' || type === 'collection')) {
-    return '';
-  }
-  return identifier;
-}
-
-function isEditableRole(type: string): boolean {
-  return type === 'text-field' || type === 'text-view' || type === 'search';
-}
-
-function isGenericResourceId(value: string): boolean {
-  return /^[\w.]+:id\/[\w.-]+$/i.test(value);
-}
-
-function formatRole(type: string): string {
-  const raw = type;
-  let normalized = type.replace(/XCUIElementType/gi, '').toLowerCase();
-  const isAndroidClass =
-    raw.includes('.') &&
-    (raw.startsWith('android.') || raw.startsWith('androidx.') || raw.startsWith('com.'));
-  if (normalized.startsWith('ax')) {
-    normalized = normalized.replace(/^ax/, '');
-  }
-  if (normalized.includes('.')) {
-    normalized = normalized
-      .replace(/^android\.widget\./, '')
-      .replace(/^android\.view\./, '')
-      .replace(/^android\.webkit\./, '')
-      .replace(/^androidx\./, '')
-      .replace(/^com\.google\.android\./, '')
-      .replace(/^com\.android\./, '');
-  }
-  switch (normalized) {
-    case 'application':
-      return 'application';
-    case 'navigationbar':
-      return 'navigation-bar';
-    case 'tabbar':
-      return 'tab-bar';
-    case 'button':
-    case 'imagebutton':
-      return 'button';
-    case 'link':
-      return 'link';
-    case 'cell':
-      return 'cell';
-    case 'statictext':
-    case 'checkedtextview':
-      return 'text';
-    case 'textfield':
-    case 'edittext':
-      return 'text-field';
-    case 'textview':
-      return isAndroidClass ? 'text' : 'text-view';
-    case 'textarea':
-      return 'text-view';
-    case 'switch':
-      return 'switch';
-    case 'slider':
-      return 'slider';
-    case 'image':
-    case 'imageview':
-      return 'image';
-    case 'webview':
-      return 'webview';
-    case 'framelayout':
-    case 'linearlayout':
-    case 'relativelayout':
-    case 'constraintlayout':
-    case 'viewgroup':
-    case 'view':
-      return 'group';
-    case 'listview':
-    case 'recyclerview':
-      return 'list';
-    case 'collectionview':
-      return 'collection';
-    case 'searchfield':
-      return 'search';
-    case 'segmentedcontrol':
-      return 'segmented-control';
-    case 'group':
-      return 'group';
-    case 'window':
-      return 'window';
-    case 'checkbox':
-      return 'checkbox';
-    case 'radio':
-      return 'radio';
-    case 'menuitem':
-      return 'menu-item';
-    case 'toolbar':
-      return 'toolbar';
-    case 'scrollarea':
-    case 'scrollview':
-    case 'nestedscrollview':
-      return 'scroll-area';
-    case 'table':
-      return 'table';
-    default:
-      return normalized || 'element';
-  }
-}

package/src/utils/process-identity.ts

@@ -1,100 +0,0 @@
-import { runCmdSync } from './exec.ts';
-
-const PS_TIMEOUT_MS = 1_000;
-const DAEMON_COMMAND_PATTERNS = [
-  /(^|[\/\s"'=])dist\/src\/daemon\.js($|[\s"'])/,
-  /(^|[\/\s"'=])src\/daemon\.ts($|[\s"'])/,
-];
-
-export function isProcessAlive(pid: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return (err as NodeJS.ErrnoException).code === 'EPERM';
-  }
-}
-
-export function readProcessStartTime(pid: number): string | null {
-  if (!Number.isInteger(pid) || pid <= 0) return null;
-  try {
-    const result = runCmdSync('ps', ['-p', String(pid), '-o', 'lstart='], {
-      allowFailure: true,
-      timeoutMs: PS_TIMEOUT_MS,
-    });
-    if (result.exitCode !== 0) return null;
-    const value = result.stdout.trim();
-    return value.length > 0 ? value : null;
-  } catch {
-    return null;
-  }
-}
-
-export function readProcessCommand(pid: number): string | null {
-  if (!Number.isInteger(pid) || pid <= 0) return null;
-  try {
-    const result = runCmdSync('ps', ['-p', String(pid), '-o', 'command='], {
-      allowFailure: true,
-      timeoutMs: PS_TIMEOUT_MS,
-    });
-    if (result.exitCode !== 0) return null;
-    const value = result.stdout.trim();
-    return value.length > 0 ? value : null;
-  } catch {
-    return null;
-  }
-}
-
-export function isAgentDeviceDaemonCommand(command: string): boolean {
-  const normalized = command.toLowerCase().replaceAll('\\', '/');
-  if (!normalized.includes('agent-device')) return false;
-  return DAEMON_COMMAND_PATTERNS.some((pattern) => pattern.test(normalized));
-}
-
-export function isAgentDeviceDaemonProcess(pid: number, expectedStartTime?: string): boolean {
-  if (!isProcessAlive(pid)) return false;
-  if (expectedStartTime) {
-    const actualStartTime = readProcessStartTime(pid);
-    if (!actualStartTime || actualStartTime !== expectedStartTime) return false;
-  }
-  const command = readProcessCommand(pid);
-  if (!command) return false;
-  return isAgentDeviceDaemonCommand(command);
-}
-
-function trySignalProcess(pid: number, signal: NodeJS.Signals): boolean {
-  try {
-    process.kill(pid, signal);
-    return true;
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code === 'ESRCH' || code === 'EPERM') return false;
-    throw err;
-  }
-}
-
-export async function waitForProcessExit(pid: number, timeoutMs: number): Promise<boolean> {
-  if (!isProcessAlive(pid)) return true;
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    await new Promise((resolve) => setTimeout(resolve, 50));
-    if (!isProcessAlive(pid)) return true;
-  }
-  return !isProcessAlive(pid);
-}
-
-export async function stopProcessForTakeover(
-  pid: number,
-  options: {
-    termTimeoutMs: number;
-    killTimeoutMs: number;
-    expectedStartTime?: string;
-  },
-): Promise<void> {
-  if (!isAgentDeviceDaemonProcess(pid, options.expectedStartTime)) return;
-  if (!trySignalProcess(pid, 'SIGTERM')) return;
-  if (await waitForProcessExit(pid, options.termTimeoutMs)) return;
-  if (!trySignalProcess(pid, 'SIGKILL')) return;
-  await waitForProcessExit(pid, options.killTimeoutMs);
-}

package/src/utils/retry.ts

@@ -1,180 +0,0 @@
-import { AppError } from './errors.ts';
-
-type RetryOptions = {
-  attempts?: number;
-  baseDelayMs?: number;
-  maxDelayMs?: number;
-  jitter?: number;
-  shouldRetry?: (error: unknown, attempt: number) => boolean;
-};
-
-export type RetryPolicy = {
-  maxAttempts: number;
-  baseDelayMs: number;
-  maxDelayMs: number;
-  jitter: number;
-  shouldRetry?: (error: unknown, attempt: number) => boolean;
-};
-
-export type RetryAttemptContext = {
-  attempt: number;
-  maxAttempts: number;
-  deadline?: Deadline;
-};
-
-export type TimeoutProfile = {
-  startupMs: number;
-  operationMs: number;
-  totalMs: number;
-};
-
-export type RetryTelemetryEvent = {
-  phase?: string;
-  event: 'attempt_failed' | 'retry_scheduled' | 'succeeded' | 'exhausted';
-  attempt: number;
-  maxAttempts: number;
-  delayMs?: number;
-  elapsedMs?: number;
-  remainingMs?: number;
-  reason?: string;
-};
-
-export function isEnvTruthy(value: string | undefined): boolean {
-  return ['1', 'true', 'yes', 'on'].includes((value ?? '').toLowerCase());
-}
-
-export const TIMEOUT_PROFILES: Record<string, TimeoutProfile> = {
-  ios_boot: { startupMs: 120_000, operationMs: 20_000, totalMs: 120_000 },
-  ios_runner_connect: { startupMs: 120_000, operationMs: 15_000, totalMs: 120_000 },
-  android_boot: { startupMs: 60_000, operationMs: 10_000, totalMs: 60_000 },
-};
-
-const defaultOptions: Required<Pick<RetryOptions, 'attempts' | 'baseDelayMs' | 'maxDelayMs' | 'jitter'>> = {
-  attempts: 3,
-  baseDelayMs: 200,
-  maxDelayMs: 2000,
-  jitter: 0.2,
-};
-
-export class Deadline {
-  private readonly startedAtMs: number;
-  private readonly expiresAtMs: number;
-
-  private constructor(startedAtMs: number, timeoutMs: number) {
-    this.startedAtMs = startedAtMs;
-    this.expiresAtMs = startedAtMs + Math.max(0, timeoutMs);
-  }
-
-  static fromTimeoutMs(timeoutMs: number, nowMs = Date.now()): Deadline {
-    return new Deadline(nowMs, timeoutMs);
-  }
-
-  remainingMs(nowMs = Date.now()): number {
-    return Math.max(0, this.expiresAtMs - nowMs);
-  }
-
-  elapsedMs(nowMs = Date.now()): number {
-    return Math.max(0, nowMs - this.startedAtMs);
-  }
-
-  isExpired(nowMs = Date.now()): boolean {
-    return this.remainingMs(nowMs) <= 0;
-  }
-}
-
-export async function retryWithPolicy<T>(
-  fn: (context: RetryAttemptContext) => Promise<T>,
-  policy: Partial<RetryPolicy> = {},
-  options: {
-    deadline?: Deadline;
-    phase?: string;
-    classifyReason?: (error: unknown) => string | undefined;
-    onEvent?: (event: RetryTelemetryEvent) => void;
-  } = {},
-): Promise<T> {
-  const merged: RetryPolicy = {
-    maxAttempts: policy.maxAttempts ?? defaultOptions.attempts,
-    baseDelayMs: policy.baseDelayMs ?? defaultOptions.baseDelayMs,
-    maxDelayMs: policy.maxDelayMs ?? defaultOptions.maxDelayMs,
-    jitter: policy.jitter ?? defaultOptions.jitter,
-    shouldRetry: policy.shouldRetry,
-  };
-  let lastError: unknown;
-  for (let attempt = 1; attempt <= merged.maxAttempts; attempt += 1) {
-    if (options.deadline?.isExpired() && attempt > 1) break;
-    try {
-      const result = await fn({ attempt, maxAttempts: merged.maxAttempts, deadline: options.deadline });
-      options.onEvent?.({
-        phase: options.phase,
-        event: 'succeeded',
-        attempt,
-        maxAttempts: merged.maxAttempts,
-        elapsedMs: options.deadline?.elapsedMs(),
-        remainingMs: options.deadline?.remainingMs(),
-      });
-      return result;
-    } catch (err) {
-      lastError = err;
-      const reason = options.classifyReason?.(err);
-      options.onEvent?.({
-        phase: options.phase,
-        event: 'attempt_failed',
-        attempt,
-        maxAttempts: merged.maxAttempts,
-        elapsedMs: options.deadline?.elapsedMs(),
-        remainingMs: options.deadline?.remainingMs(),
-        reason,
-      });
-      if (attempt >= merged.maxAttempts) break;
-      if (merged.shouldRetry && !merged.shouldRetry(err, attempt)) break;
-      const delay = computeDelay(merged.baseDelayMs, merged.maxDelayMs, merged.jitter, attempt);
-      const boundedDelay = options.deadline ? Math.min(delay, options.deadline.remainingMs()) : delay;
-      if (boundedDelay <= 0) break;
-      options.onEvent?.({
-        phase: options.phase,
-        event: 'retry_scheduled',
-        attempt,
-        maxAttempts: merged.maxAttempts,
-        delayMs: boundedDelay,
-        elapsedMs: options.deadline?.elapsedMs(),
-        remainingMs: options.deadline?.remainingMs(),
-        reason,
-      });
-      await sleep(boundedDelay);
-    }
-  }
-  options.onEvent?.({
-    phase: options.phase,
-    event: 'exhausted',
-    attempt: merged.maxAttempts,
-    maxAttempts: merged.maxAttempts,
-    elapsedMs: options.deadline?.elapsedMs(),
-    remainingMs: options.deadline?.remainingMs(),
-    reason: options.classifyReason?.(lastError),
-  });
-  if (lastError) throw lastError;
-  throw new AppError('COMMAND_FAILED', 'retry failed');
-}
-
-export async function withRetry<T>(
-  fn: () => Promise<T>,
-  options: RetryOptions = {},
-): Promise<T> {
-  return retryWithPolicy(() => fn(), {
-    maxAttempts: options.attempts,
-    baseDelayMs: options.baseDelayMs,
-    maxDelayMs: options.maxDelayMs,
-    jitter: options.jitter,
-    shouldRetry: options.shouldRetry,
-  });
-}
-
-function computeDelay(base: number, max: number, jitter: number, attempt: number): number {
-  const exp = Math.min(max, base * 2 ** (attempt - 1));
-  const jitterAmount = exp * jitter;
-  return Math.max(0, exp + (Math.random() * 2 - 1) * jitterAmount);
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/src/utils/snapshot.ts

@@ -1,64 +0,0 @@
-export type Rect = {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-};
-
-export type SnapshotOptions = {
-  interactiveOnly?: boolean;
-  compact?: boolean;
-  depth?: number;
-  scope?: string;
-  raw?: boolean;
-};
-
-export type RawSnapshotNode = {
-  index: number;
-  type?: string;
-  label?: string;
-  value?: string;
-  identifier?: string;
-  rect?: Rect;
-  enabled?: boolean;
-  selected?: boolean;
-  hittable?: boolean;
-  depth?: number;
-  parentIndex?: number;
-};
-
-export type SnapshotNode = RawSnapshotNode & {
-  ref: string;
-};
-
-export type SnapshotState = {
-  nodes: SnapshotNode[];
-  createdAt: number;
-  truncated?: boolean;
-  backend?: 'ax' | 'xctest' | 'android';
-};
-
-export function attachRefs(nodes: RawSnapshotNode[]): SnapshotNode[] {
-  return nodes.map((node, idx) => ({ ...node, ref: `e${idx + 1}` }));
-}
-
-export function normalizeRef(input: string): string | null {
-  const trimmed = input.trim();
-  if (trimmed.startsWith('@')) {
-    const ref = trimmed.slice(1);
-    return ref ? ref : null;
-  }
-  if (trimmed.startsWith('e')) return trimmed;
-  return null;
-}
-
-export function findNodeByRef(nodes: SnapshotNode[], ref: string): SnapshotNode | null {
-  return nodes.find((node) => node.ref === ref) ?? null;
-}
-
-export function centerOfRect(rect: Rect): { x: number; y: number } {
-  return {
-    x: Math.round(rect.x + rect.width / 2),
-    y: Math.round(rect.y + rect.height / 2),
-  };
-}

package/src/utils/timeouts.ts

@@ -1,9 +0,0 @@
-export function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number {
-  if (!raw) return fallback;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return fallback;
-  return Math.max(min, Math.floor(parsed));
-}
-
-/** Alias for `resolveTimeoutMs` — semantically marks the caller expects seconds. */
-export const resolveTimeoutSeconds = resolveTimeoutMs;

package/src/utils/version.ts

@@ -1,26 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-export function readVersion(): string {
-  try {
-    const root = findProjectRoot();
-    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')) as {
-      version?: string;
-    };
-    return pkg.version ?? '0.0.0';
-  } catch {
-    return '0.0.0';
-  }
-}
-
-export function findProjectRoot(): string {
-  const start = path.dirname(fileURLToPath(import.meta.url));
-  let current = start;
-  for (let i = 0; i < 6; i += 1) {
-    const pkgPath = path.join(current, 'package.json');
-    if (fs.existsSync(pkgPath)) return current;
-    current = path.dirname(current);
-  }
-  return start;
-}