agent-device 0.4.2 → 0.5.0

package/src/platforms/ios/apps.ts

@@ -1,358 +0,0 @@
-import type { DeviceInfo } from '../../utils/device.ts';
-import { AppError } from '../../utils/errors.ts';
-import { runCmd } from '../../utils/exec.ts';
-import { Deadline, retryWithPolicy } from '../../utils/retry.ts';
-import { isDeepLinkTarget, resolveIosDeviceDeepLinkBundleId } from '../../core/open-target.ts';
-
-import { IOS_APP_LAUNCH_TIMEOUT_MS } from './config.ts';
-import { listIosDeviceApps, runIosDevicectl, type IosAppInfo } from './devicectl.ts';
-import { ensureBootedSimulator, ensureSimulator, getSimulatorState } from './simulator.ts';
-
-const ALIASES: Record<string, string> = {
-  settings: 'com.apple.Preferences',
-};
-
-export async function resolveIosApp(device: DeviceInfo, app: string): Promise<string> {
-  const trimmed = app.trim();
-  if (trimmed.includes('.')) return trimmed;
-
-  const alias = ALIASES[trimmed.toLowerCase()];
-  if (alias) return alias;
-
-  const list =
-    device.kind === 'simulator'
-      ? await listSimulatorApps(device)
-      : await listIosDeviceApps(device, 'all');
-  const matches = list.filter((entry) => entry.name.toLowerCase() === trimmed.toLowerCase());
-  if (matches.length === 1) return matches[0].bundleId;
-  if (matches.length > 1) {
-    throw new AppError('INVALID_ARGS', `Multiple apps matched "${app}"`, { matches });
-  }
-
-  throw new AppError('APP_NOT_INSTALLED', `No app found matching "${app}"`);
-}
-
-export async function openIosApp(
-  device: DeviceInfo,
-  app: string,
-  options?: { appBundleId?: string; url?: string },
-): Promise<void> {
-  const explicitUrl = options?.url?.trim();
-  if (explicitUrl) {
-    if (!isDeepLinkTarget(explicitUrl)) {
-      throw new AppError('INVALID_ARGS', 'open <app> <url> requires a valid URL target');
-    }
-    if (device.kind === 'simulator') {
-      await ensureBootedSimulator(device);
-      await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
-      await runCmd('xcrun', ['simctl', 'openurl', device.id, explicitUrl]);
-      return;
-    }
-    const appBundleId = options?.appBundleId ?? (await resolveIosApp(device, app));
-    const bundleId = resolveIosDeviceDeepLinkBundleId(appBundleId, explicitUrl);
-    if (!bundleId) {
-      throw new AppError(
-        'INVALID_ARGS',
-        'Deep link open on iOS devices requires an active app bundle ID. Open the app first, then open the URL.',
-      );
-    }
-    await launchIosDeviceProcess(device, bundleId, { payloadUrl: explicitUrl });
-    return;
-  }
-
-  const deepLinkTarget = app.trim();
-  if (isDeepLinkTarget(deepLinkTarget)) {
-    if (device.kind === 'simulator') {
-      await ensureBootedSimulator(device);
-      await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
-      await runCmd('xcrun', ['simctl', 'openurl', device.id, deepLinkTarget]);
-      return;
-    }
-    const bundleId = resolveIosDeviceDeepLinkBundleId(options?.appBundleId, deepLinkTarget);
-    if (!bundleId) {
-      throw new AppError(
-        'INVALID_ARGS',
-        'Deep link open on iOS devices requires an active app bundle ID. Open the app first, then open the URL.',
-      );
-    }
-    await launchIosDeviceProcess(device, bundleId, { payloadUrl: deepLinkTarget });
-    return;
-  }
-
-  const bundleId = options?.appBundleId ?? (await resolveIosApp(device, app));
-  if (device.kind === 'simulator') {
-    await launchIosSimulatorApp(device, bundleId);
-    return;
-  }
-
-  await launchIosDeviceProcess(device, bundleId);
-}
-
-export async function openIosDevice(device: DeviceInfo): Promise<void> {
-  if (device.kind !== 'simulator') return;
-  const state = await getSimulatorState(device.id);
-  if (state === 'Booted') return;
-
-  await ensureBootedSimulator(device);
-  await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
-}
-
-export async function closeIosApp(device: DeviceInfo, app: string): Promise<void> {
-  const bundleId = await resolveIosApp(device, app);
-  if (device.kind === 'simulator') {
-    await ensureBootedSimulator(device);
-    const result = await runCmd('xcrun', ['simctl', 'terminate', device.id, bundleId], {
-      allowFailure: true,
-    });
-    if (result.exitCode !== 0) {
-      const stderr = result.stderr.toLowerCase();
-      if (stderr.includes('found nothing to terminate')) return;
-      throw new AppError('COMMAND_FAILED', `xcrun exited with code ${result.exitCode}`, {
-        cmd: 'xcrun',
-        args: ['simctl', 'terminate', device.id, bundleId],
-        stdout: result.stdout,
-        stderr: result.stderr,
-        exitCode: result.exitCode,
-      });
-    }
-    return;
-  }
-
-  await runIosDevicectl(['device', 'process', 'terminate', '--device', device.id, bundleId], {
-    action: 'terminate iOS app',
-    deviceId: device.id,
-  });
-}
-
-export async function uninstallIosApp(device: DeviceInfo, app: string): Promise<{ bundleId: string }> {
-  ensureSimulator(device, 'reinstall');
-  const bundleId = await resolveIosApp(device, app);
-  await ensureBootedSimulator(device);
-
-  const result = await runCmd('xcrun', ['simctl', 'uninstall', device.id, bundleId], {
-    allowFailure: true,
-  });
-  if (result.exitCode !== 0) {
-    const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
-    if (!output.includes('not installed') && !output.includes('not found') && !output.includes('no such file')) {
-      throw new AppError('COMMAND_FAILED', `simctl uninstall failed for ${bundleId}`, {
-        stdout: result.stdout,
-        stderr: result.stderr,
-        exitCode: result.exitCode,
-      });
-    }
-  }
-
-  return { bundleId };
-}
-
-export async function installIosApp(device: DeviceInfo, appPath: string): Promise<void> {
-  ensureSimulator(device, 'reinstall');
-  await ensureBootedSimulator(device);
-  await runCmd('xcrun', ['simctl', 'install', device.id, appPath]);
-}
-
-export async function reinstallIosApp(
-  device: DeviceInfo,
-  app: string,
-  appPath: string,
-): Promise<{ bundleId: string }> {
-  const { bundleId } = await uninstallIosApp(device, app);
-  await installIosApp(device, appPath);
-  return { bundleId };
-}
-
-export async function screenshotIos(device: DeviceInfo, outPath: string): Promise<void> {
-  if (device.kind === 'simulator') {
-    await ensureBootedSimulator(device);
-    await runCmd('xcrun', ['simctl', 'io', device.id, 'screenshot', outPath]);
-    return;
-  }
-
-  await runIosDevicectl(['device', 'screenshot', '--device', device.id, outPath], {
-    action: 'capture iOS screenshot',
-    deviceId: device.id,
-  });
-}
-
-export async function setIosSetting(
-  device: DeviceInfo,
-  setting: string,
-  state: string,
-  appBundleId?: string,
-): Promise<void> {
-  ensureSimulator(device, 'settings');
-  await ensureBootedSimulator(device);
-  const normalized = setting.toLowerCase();
-  const enabled = parseSettingState(state);
-
-  switch (normalized) {
-    case 'wifi': {
-      const mode = enabled ? 'active' : 'failed';
-      await runCmd('xcrun', ['simctl', 'status_bar', device.id, 'override', '--wifiMode', mode]);
-      return;
-    }
-    case 'airplane': {
-      if (enabled) {
-        await runCmd('xcrun', [
-          'simctl',
-          'status_bar',
-          device.id,
-          'override',
-          '--dataNetwork',
-          'hide',
-          '--wifiMode',
-          'failed',
-          '--wifiBars',
-          '0',
-          '--cellularMode',
-          'failed',
-          '--cellularBars',
-          '0',
-          '--operatorName',
-          '',
-        ]);
-      } else {
-        await runCmd('xcrun', ['simctl', 'status_bar', device.id, 'clear']);
-      }
-      return;
-    }
-    case 'location': {
-      if (!appBundleId) {
-        throw new AppError('INVALID_ARGS', 'location setting requires an active app in session');
-      }
-      const action = enabled ? 'grant' : 'revoke';
-      await runCmd('xcrun', ['simctl', 'privacy', device.id, action, 'location', appBundleId]);
-      return;
-    }
-    default:
-      throw new AppError('INVALID_ARGS', `Unsupported setting: ${setting}`);
-  }
-}
-
-export async function listIosApps(
-  device: DeviceInfo,
-  filter: 'user-installed' | 'all' = 'all',
-): Promise<IosAppInfo[]> {
-  if (device.kind === 'simulator') {
-    const apps = await listSimulatorApps(device);
-    return filterIosAppsByBundlePrefix(apps, filter);
-  }
-  return await listIosDeviceApps(device, filter);
-}
-
-export async function listSimulatorApps(device: DeviceInfo): Promise<IosAppInfo[]> {
-  const result = await runCmd('xcrun', ['simctl', 'listapps', device.id], { allowFailure: true });
-  const stdout = result.stdout as string;
-  const trimmed = stdout.trim();
-  if (!trimmed) return [];
-
-  let parsed: Record<string, { CFBundleDisplayName?: string; CFBundleName?: string }> | null = null;
-  if (trimmed.startsWith('{')) {
-    try {
-      parsed = JSON.parse(trimmed) as Record<string, { CFBundleDisplayName?: string; CFBundleName?: string }>;
-    } catch {
-      parsed = null;
-    }
-  }
-
-  if (!parsed && trimmed.startsWith('{')) {
-    try {
-      const converted = await runCmd('plutil', ['-convert', 'json', '-o', '-', '-'], {
-        allowFailure: true,
-        stdin: trimmed,
-      });
-      if (converted.exitCode === 0 && converted.stdout.trim().startsWith('{')) {
-        parsed = JSON.parse(converted.stdout) as Record<
-          string,
-          { CFBundleDisplayName?: string; CFBundleName?: string }
-        >;
-      }
-    } catch {
-      parsed = null;
-    }
-  }
-
-  if (!parsed) return [];
-  return Object.entries(parsed).map(([bundleId, info]) => ({
-    bundleId,
-    name: info.CFBundleDisplayName ?? info.CFBundleName ?? bundleId,
-  }));
-}
-
-function parseSettingState(state: string): boolean {
-  const normalized = state.toLowerCase();
-  if (normalized === 'on' || normalized === 'true' || normalized === '1') return true;
-  if (normalized === 'off' || normalized === 'false' || normalized === '0') return false;
-  throw new AppError('INVALID_ARGS', `Invalid setting state: ${state}`);
-}
-
-function isTransientSimulatorLaunchFailure(error: unknown): boolean {
-  if (!(error instanceof AppError)) return false;
-  if (error.code !== 'COMMAND_FAILED') return false;
-
-  const details = (error.details ?? {}) as { exitCode?: number; stderr?: unknown };
-  if (details.exitCode !== 4) return false;
-  const stderr = String(details.stderr ?? '').toLowerCase();
-
-  return (
-    stderr.includes('fbsopenapplicationserviceerrordomain') &&
-    stderr.includes('the request to open')
-  );
-}
-
-async function launchIosSimulatorApp(device: DeviceInfo, bundleId: string): Promise<void> {
-  await ensureBootedSimulator(device);
-  await runCmd('open', ['-a', 'Simulator'], { allowFailure: true });
-
-  const launchDeadline = Deadline.fromTimeoutMs(IOS_APP_LAUNCH_TIMEOUT_MS);
-  await retryWithPolicy(
-    async ({ deadline: attemptDeadline }) => {
-      if (attemptDeadline?.isExpired()) {
-        throw new AppError('COMMAND_FAILED', 'App launch deadline exceeded', {
-          timeoutMs: IOS_APP_LAUNCH_TIMEOUT_MS,
-        });
-      }
-
-      const result = await runCmd('xcrun', ['simctl', 'launch', device.id, bundleId], {
-        allowFailure: true,
-      });
-      if (result.exitCode === 0) return;
-
-      throw new AppError('COMMAND_FAILED', `xcrun exited with code ${result.exitCode}`, {
-        cmd: 'xcrun',
-        args: ['simctl', 'launch', device.id, bundleId],
-        stdout: result.stdout,
-        stderr: result.stderr,
-        exitCode: result.exitCode,
-      });
-    },
-    {
-      maxAttempts: 30,
-      baseDelayMs: 1_000,
-      maxDelayMs: 5_000,
-      jitter: 0.2,
-      shouldRetry: isTransientSimulatorLaunchFailure,
-    },
-    { deadline: launchDeadline },
-  );
-}
-
-async function launchIosDeviceProcess(
-  device: DeviceInfo,
-  bundleId: string,
-  options?: { payloadUrl?: string },
-): Promise<void> {
-  const args = ['device', 'process', 'launch', '--device', device.id, bundleId];
-  if (options?.payloadUrl) {
-    args.push('--payload-url', options.payloadUrl);
-  }
-  await runIosDevicectl(args, { action: 'launch iOS app', deviceId: device.id });
-}
-
-function filterIosAppsByBundlePrefix(apps: IosAppInfo[], filter: 'user-installed' | 'all'): IosAppInfo[] {
-  if (filter === 'user-installed') {
-    return apps.filter((app) => !app.bundleId.startsWith('com.apple.'));
-  }
-  return apps;
-}

package/src/platforms/ios/ax-snapshot.ts

@@ -1,207 +0,0 @@
-import path from 'node:path';
-import fs from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { AppError } from '../../utils/errors.ts';
-import { runCmd } from '../../utils/exec.ts';
-import { withRetry } from '../../utils/retry.ts';
-import type { DeviceInfo } from '../../utils/device.ts';
-import type { RawSnapshotNode } from '../../utils/snapshot.ts';
-
-type AXFrame = { x: number; y: number; width: number; height: number };
-type AXNode = {
-  role?: string;
-  subrole?: string;
-  label?: string;
-  value?: string;
-  identifier?: string;
-  frame?: AXFrame;
-  children?: AXNode[];
-};
-
-export async function snapshotAx(
-  device: DeviceInfo,
-  options: { traceLogPath?: string } = {},
-): Promise<{ nodes: RawSnapshotNode[] }> {
-  if (device.platform !== 'ios' || device.kind !== 'simulator') {
-    throw new AppError('UNSUPPORTED_OPERATION', 'AX snapshot is only supported on iOS simulators');
-  }
-  const binary = await ensureAxSnapshotBinary();
-  const result = await withRetry(
-    async () => {
-      const attemptResult = await runCmd(binary, [], { allowFailure: true });
-      if (options.traceLogPath) {
-        appendAxTrace(options.traceLogPath, attemptResult);
-      }
-      if (attemptResult.exitCode !== 0) {
-        const stderrText = (attemptResult.stderr ?? '').toString();
-        const hint = axHintFromStderr(stderrText);
-        const retryable = isRetryableAxError(stderrText);
-        const error = new AppError('COMMAND_FAILED', 'AX snapshot failed', {
-          stderr: `${stderrText}${hint}`,
-          stdout: attemptResult.stdout,
-          retryable,
-        });
-        throw error;
-      }
-      return attemptResult;
-    },
-    {
-      shouldRetry: (err) => isRetryableError(err),
-    },
-  );
-  let tree: AXNode;
-  let originFrame: AXFrame | undefined;
-  try {
-    const payload = JSON.parse(result.stdout) as
-      | AXNode
-      | { root?: AXNode; windowFrame?: AXFrame | null };
-    if (payload && typeof payload === 'object' && 'root' in payload) {
-      const snapshot = payload as { root?: AXNode; windowFrame?: AXFrame | null };
-      if (!snapshot.root) throw new Error('AX snapshot missing root');
-      tree = snapshot.root;
-      originFrame = snapshot.windowFrame ?? undefined;
-    } else {
-      tree = payload as AXNode;
-    }
-  } catch (err) {
-    throw new AppError('COMMAND_FAILED', 'Invalid AX snapshot JSON', { error: String(err) });
-  }
-  const rootFrame = tree.frame ?? originFrame;
-  const frameSamples: AXFrame[] = [];
-  const nodes: Array<AXNode & { depth: number }> = [];
-  const walk = (node: AXNode, depth: number) => {
-    if (node.frame) frameSamples.push(node.frame);
-    const frame = node.frame && rootFrame
-      ? {
-          x: node.frame.x - rootFrame.x,
-          y: node.frame.y - rootFrame.y,
-          width: node.frame.width,
-          height: node.frame.height,
-        }
-      : node.frame;
-    nodes.push({ ...node, frame, children: undefined, depth });
-    for (const child of node.children ?? []) {
-      walk(child, depth + 1);
-    }
-  };
-  walk(tree, 0);
-  const normalized = normalizeFrames(nodes, rootFrame, frameSamples);
-  const mapped = normalized.map((node, index) => ({
-    index,
-    type: node.subrole ?? node.role,
-    label: node.label,
-    value: node.value,
-    identifier: node.identifier,
-    rect: node.frame
-      ? {
-          x: node.frame.x,
-          y: node.frame.y,
-          width: node.frame.width,
-          height: node.frame.height,
-        }
-      : undefined,
-    depth: node.depth,
-  }));
-  return { nodes: mapped };
-}
-
-function axHintFromStderr(stderrText: string): string {
-  const lower = stderrText.toLowerCase();
-  if (lower.includes('accessibility permission')) {
-    return (
-      ' Enable Accessibility for your terminal in System Settings > Privacy & Security > Accessibility, ' +
-      'or use --backend xctest (slower snapshots via XCTest).'
-    );
-  }
-  if (lower.includes('could not find ios app content')) {
-    return ' AX snapshot sometimes caches empty content. Try restarting the Simulator app.';
-  }
-  return '';
-}
-
-function appendAxTrace(traceLogPath: string, result: { stdout?: string; stderr?: string; exitCode: number }): void {
-  const stdoutText = (result.stdout ?? '').toString();
-  const stderrText = (result.stderr ?? '').toString();
-  const header = `\n[axsnapshot] exit=${result.exitCode} stdoutBytes=${stdoutText.length} stderrBytes=${stderrText.length}\n`;
-  fs.appendFileSync(traceLogPath, header);
-  if (result.exitCode !== 0 || stderrText.length > 0) {
-    if (stderrText.length > 0) {
-      fs.appendFileSync(traceLogPath, `${stderrText}\n`);
-    }
-    if (result.exitCode !== 0 && stdoutText.length > 0) {
-      fs.appendFileSync(traceLogPath, `${stdoutText}\n`);
-    }
-  }
-}
-
-function isRetryableAxError(stderrText: string): boolean {
-  const lower = stderrText.toLowerCase();
-  if (lower.includes('could not find ios app content')) return true;
-  if (lower.includes('timeout')) return true;
-  return false;
-}
-
-function isRetryableError(err: unknown): boolean {
-  return err instanceof AppError && err.code === 'COMMAND_FAILED' && err.details?.retryable === true;
-}
-
-function normalizeFrames(
-  nodes: Array<AXNode & { depth: number }>,
-  originFrame: AXFrame | undefined,
-  frames: AXFrame[],
-): Array<AXNode & { depth: number }> {
-  if (!originFrame || frames.length === 0) return nodes;
-  let minX = Number.POSITIVE_INFINITY;
-  let minY = Number.POSITIVE_INFINITY;
-  for (const frame of frames) {
-    if (frame.x < minX) minX = frame.x;
-    if (frame.y < minY) minY = frame.y;
-  }
-  const nearZero = minX <= 5 && minY <= 5;
-  if (nearZero) {
-    return nodes.map((node) => ({
-      ...node,
-      frame: node.frame
-        ? {
-            x: node.frame.x + originFrame.x,
-            y: node.frame.y + originFrame.y,
-            width: node.frame.width,
-            height: node.frame.height,
-          }
-        : undefined,
-    }));
-  }
-  return nodes;
-}
-
-async function ensureAxSnapshotBinary(): Promise<string> {
-  const projectRoot = findProjectRoot();
-  const packageDir = path.join(projectRoot, 'ios-runner', 'AXSnapshot');
-  const envPath = process.env.AGENT_DEVICE_AX_BINARY;
-  if (envPath && fs.existsSync(envPath)) return envPath;
-  const packagedPath = path.join(projectRoot, 'dist', 'bin', 'axsnapshot');
-  if (fs.existsSync(packagedPath)) return packagedPath;
-  const binaryPath = path.join(packageDir, '.build', 'release', 'axsnapshot');
-  if (fs.existsSync(binaryPath)) return binaryPath;
-  const result = await runCmd('swift', ['build', '-c', 'release'], {
-    cwd: packageDir,
-    allowFailure: true,
-  });
-  if (result.exitCode !== 0 || !fs.existsSync(binaryPath)) {
-    throw new AppError('COMMAND_FAILED', 'Failed to build AX snapshot tool', {
-      stderr: result.stderr,
-      stdout: result.stdout,
-    });
-  }
-  return binaryPath;
-}
-
-function findProjectRoot(): string {
-  let current = path.dirname(fileURLToPath(import.meta.url));
-  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 process.cwd();
-}

package/src/platforms/ios/config.ts

@@ -1,28 +0,0 @@
-import { isEnvTruthy, TIMEOUT_PROFILES } from '../../utils/retry.ts';
-import { resolveTimeoutMs } from '../../utils/timeouts.ts';
-
-export const IOS_BOOT_TIMEOUT_MS = resolveTimeoutMs(
-  process.env.AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS,
-  TIMEOUT_PROFILES.ios_boot.totalMs,
-  5_000,
-);
-
-export const IOS_SIMCTL_LIST_TIMEOUT_MS = resolveTimeoutMs(
-  process.env.AGENT_DEVICE_IOS_SIMCTL_LIST_TIMEOUT_MS,
-  TIMEOUT_PROFILES.ios_boot.operationMs,
-  1_000,
-);
-
-export const IOS_APP_LAUNCH_TIMEOUT_MS = resolveTimeoutMs(
-  process.env.AGENT_DEVICE_IOS_APP_LAUNCH_TIMEOUT_MS,
-  30_000,
-  5_000,
-);
-
-export const IOS_DEVICECTL_TIMEOUT_MS = resolveTimeoutMs(
-  process.env.AGENT_DEVICE_IOS_DEVICECTL_TIMEOUT_MS,
-  20_000,
-  1_000,
-);
-
-export const RETRY_LOGS_ENABLED = isEnvTruthy(process.env.AGENT_DEVICE_RETRY_LOGS);