agent-device 0.3.0 → 0.3.1

package/src/platforms/ios/index.ts

@@ -1,11 +1,16 @@
 import { runCmd } from '../../utils/exec.ts';
+import type { ExecResult } from '../../utils/exec.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
+import { Deadline, retryWithPolicy } from '../../utils/retry.ts';
+import { classifyBootFailure } from '../boot-diagnostics.ts';
 
 const ALIASES: Record<string, string> = {
   settings: 'com.apple.Preferences',
 };
 
+const IOS_BOOT_TIMEOUT_MS = resolveTimeoutMs(process.env.AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS, 120_000, 5_000);
+
 export async function resolveIosApp(device: DeviceInfo, app: string): Promise<string> {
   const trimmed = app.trim();
   if (trimmed.includes('.')) return trimmed;
@@ -207,8 +212,88 @@ export async function ensureBootedSimulator(device: DeviceInfo): Promise<void> {
   if (device.kind !== 'simulator') return;
   const state = await getSimulatorState(device.id);
   if (state === 'Booted') return;
-  await runCmd('xcrun', ['simctl', 'boot', device.id], { allowFailure: true });
-  await runCmd('xcrun', ['simctl', 'bootstatus', device.id, '-b'], { allowFailure: true });
+  const deadline = Deadline.fromTimeoutMs(IOS_BOOT_TIMEOUT_MS);
+  let bootResult: ExecResult | undefined;
+  let bootStatusResult: ExecResult | undefined;
+  try {
+    await retryWithPolicy(
+      async () => {
+        const currentState = await getSimulatorState(device.id);
+        if (currentState === 'Booted') return;
+        bootResult = await runCmd('xcrun', ['simctl', 'boot', device.id], { allowFailure: true });
+        const bootOutput = `${bootResult.stdout}\n${bootResult.stderr}`.toLowerCase();
+        const bootAlreadyDone =
+          bootOutput.includes('already booted') || bootOutput.includes('current state: booted');
+        if (bootResult.exitCode !== 0 && !bootAlreadyDone) {
+          throw new AppError('COMMAND_FAILED', 'simctl boot failed', {
+            stdout: bootResult.stdout,
+            stderr: bootResult.stderr,
+            exitCode: bootResult.exitCode,
+          });
+        }
+        bootStatusResult = await runCmd('xcrun', ['simctl', 'bootstatus', device.id, '-b'], {
+          allowFailure: true,
+        });
+        if (bootStatusResult.exitCode !== 0) {
+          throw new AppError('COMMAND_FAILED', 'simctl bootstatus failed', {
+            stdout: bootStatusResult.stdout,
+            stderr: bootStatusResult.stderr,
+            exitCode: bootStatusResult.exitCode,
+          });
+        }
+        const nextState = await getSimulatorState(device.id);
+        if (nextState !== 'Booted') {
+          throw new AppError('COMMAND_FAILED', 'Simulator is still booting', {
+            state: nextState,
+          });
+        }
+      },
+      {
+        maxAttempts: 3,
+        baseDelayMs: 500,
+        maxDelayMs: 2000,
+        jitter: 0.2,
+        shouldRetry: (error) => {
+          const reason = classifyBootFailure({
+            error,
+            stdout: bootStatusResult?.stdout ?? bootResult?.stdout,
+            stderr: bootStatusResult?.stderr ?? bootResult?.stderr,
+          });
+          return reason !== 'PERMISSION_DENIED' && reason !== 'TOOL_MISSING';
+        },
+      },
+      { deadline },
+    );
+  } catch (error) {
+    const bootStdout = bootResult?.stdout;
+    const bootStderr = bootResult?.stderr;
+    const bootExitCode = bootResult?.exitCode;
+    const bootstatusStdout = bootStatusResult?.stdout;
+    const bootstatusStderr = bootStatusResult?.stderr;
+    const bootstatusExitCode = bootStatusResult?.exitCode;
+    const reason = classifyBootFailure({
+      error,
+      stdout: bootstatusStdout ?? bootStdout,
+      stderr: bootstatusStderr ?? bootStderr,
+    });
+    throw new AppError('COMMAND_FAILED', 'iOS simulator failed to boot', {
+      platform: 'ios',
+      deviceId: device.id,
+      timeoutMs: IOS_BOOT_TIMEOUT_MS,
+      elapsedMs: deadline.elapsedMs(),
+      reason,
+      boot: bootResult
+        ? { exitCode: bootExitCode, stdout: bootStdout, stderr: bootStderr }
+        : undefined,
+      bootstatus: bootStatusResult
+        ? {
+          exitCode: bootstatusExitCode,
+          stdout: bootstatusStdout,
+          stderr: bootstatusStderr,
+        }
+        : undefined,
+    });
+  }
 }
 
 async function getSimulatorState(udid: string): Promise<string | null> {
@@ -229,3 +314,10 @@ async function getSimulatorState(udid: string): Promise<string | null> {
   }
   return null;
 }
+
+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));
+}

package/src/utils/__tests__/retry.test.ts

@@ -0,0 +1,27 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { Deadline, retryWithPolicy } from '../retry.ts';
+
+test('Deadline tracks remaining and expiration', async () => {
+  const deadline = Deadline.fromTimeoutMs(25);
+  assert.equal(deadline.isExpired(), false);
+  await new Promise((resolve) => setTimeout(resolve, 30));
+  assert.equal(deadline.isExpired(), true);
+  assert.equal(deadline.remainingMs(), 0);
+});
+
+test('retryWithPolicy retries until success', async () => {
+  let attempts = 0;
+  const result = await retryWithPolicy(
+    async () => {
+      attempts += 1;
+      if (attempts < 3) {
+        throw new Error('transient');
+      }
+      return 'ok';
+    },
+    { maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 1, jitter: 0 },
+  );
+  assert.equal(result, 'ok');
+  assert.equal(attempts, 3);
+});

package/src/utils/args.ts

@@ -25,11 +25,12 @@ export type ParsedArgs = {
     noRecord?: boolean;
     replayUpdate?: boolean;
     help: boolean;
+    version: boolean;
   };
 };
 
 export function parseArgs(argv: string[]): ParsedArgs {
-  const flags: ParsedArgs['flags'] = { json: false, help: false };
+  const flags: ParsedArgs['flags'] = { json: false, help: false, version: false };
   const positionals: string[] = [];
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -42,6 +43,10 @@ export function parseArgs(argv: string[]): ParsedArgs {
       flags.help = true;
       continue;
     }
+    if (arg === '--version' || arg === '-V') {
+      flags.version = true;
+      continue;
+    }
     if (arg === '--verbose' || arg === '-v') {
       flags.verbose = true;
       continue;
@@ -229,5 +234,6 @@ Flags:
   --update, -u                               Replay: update selectors and rewrite replay file in place
   --user-installed                           Apps: list user-installed packages (Android only)
   --all                                      Apps: list all packages (Android only)
+  --version, -V                              Print version and exit
 `;
 }

package/src/utils/retry.ts

@@ -8,6 +8,20 @@ type RetryOptions = {
   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;
+};
+
 const defaultOptions: Required<Pick<RetryOptions, 'attempts' | 'baseDelayMs' | 'maxDelayMs' | 'jitter'>> = {
   attempts: 3,
   baseDelayMs: 200,
@@ -15,30 +29,76 @@ const defaultOptions: Required<Pick<RetryOptions, 'attempts' | 'baseDelayMs' | '
   jitter: 0.2,
 };
 
-export async function withRetry<T>(
-  fn: () => Promise<T>,
-  options: RetryOptions = {},
+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 } = {},
 ): Promise<T> {
-  const attempts = options.attempts ?? defaultOptions.attempts;
-  const baseDelayMs = options.baseDelayMs ?? defaultOptions.baseDelayMs;
-  const maxDelayMs = options.maxDelayMs ?? defaultOptions.maxDelayMs;
-  const jitter = options.jitter ?? defaultOptions.jitter;
+  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 <= attempts; attempt += 1) {
+  for (let attempt = 1; attempt <= merged.maxAttempts; attempt += 1) {
+    if (options.deadline?.isExpired() && attempt > 1) break;
     try {
-      return await fn();
+      return await fn({ attempt, maxAttempts: merged.maxAttempts, deadline: options.deadline });
     } catch (err) {
       lastError = err;
-      if (attempt >= attempts) break;
-      if (options.shouldRetry && !options.shouldRetry(err, attempt)) break;
-      const delay = computeDelay(baseDelayMs, maxDelayMs, jitter, attempt);
-      await sleep(delay);
+      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;
+      await sleep(boundedDelay);
     }
   }
   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;

package/src/utils/version.ts

@@ -0,0 +1,26 @@
+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;
+}

package/dist/src/861.js

@@ -1 +0,0 @@
-import{spawn as e}from"node:child_process";function t(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}class n extends Error{constructor(e,n,o,r){super(n),t(this,"code",void 0),t(this,"details",void 0),t(this,"cause",void 0),this.code=e,this.details=o,this.cause=r}}function o(e){return e instanceof n?e:e instanceof Error?new n("UNKNOWN",e.message,void 0,e):new n("UNKNOWN","Unknown error",{err:e})}async function r(t,o,d={}){return new Promise((r,i)=>{let s=e(t,o,{cwd:d.cwd,env:d.env,stdio:["pipe","pipe","pipe"]}),u="",a=d.binaryStdout?Buffer.alloc(0):void 0,c="";d.binaryStdout||s.stdout.setEncoding("utf8"),s.stderr.setEncoding("utf8"),void 0!==d.stdin&&s.stdin.write(d.stdin),s.stdin.end(),s.stdout.on("data",e=>{d.binaryStdout?a=Buffer.concat([a??Buffer.alloc(0),Buffer.isBuffer(e)?e:Buffer.from(e)]):u+=e}),s.stderr.on("data",e=>{c+=e}),s.on("error",e=>{"ENOENT"===e.code?i(new n("TOOL_MISSING",`${t} not found in PATH`,{cmd:t},e)):i(new n("COMMAND_FAILED",`Failed to run ${t}`,{cmd:t,args:o},e))}),s.on("close",e=>{let s=e??1;0===s||d.allowFailure?r({stdout:u,stderr:c,exitCode:s,stdoutBuffer:a}):i(new n("COMMAND_FAILED",`${t} exited with code ${s}`,{cmd:t,args:o,stdout:u,stderr:c,exitCode:s}))})})}async function d(e){try{var t;let{shell:n,args:o}=(t=e,"win32"===process.platform?{shell:"cmd.exe",args:["/c","where",t]}:{shell:"bash",args:["-lc",`command -v ${t}`]}),d=await r(n,o,{allowFailure:!0});return 0===d.exitCode&&d.stdout.trim().length>0}catch{return!1}}function i(t,n,o={}){e(t,n,{cwd:o.cwd,env:o.env,stdio:"ignore",detached:!0}).unref()}async function s(t,o,r={}){return new Promise((d,i)=>{let s=e(t,o,{cwd:r.cwd,env:r.env,stdio:["pipe","pipe","pipe"]}),u="",a="",c=r.binaryStdout?Buffer.alloc(0):void 0;r.binaryStdout||s.stdout.setEncoding("utf8"),s.stderr.setEncoding("utf8"),void 0!==r.stdin&&s.stdin.write(r.stdin),s.stdin.end(),s.stdout.on("data",e=>{if(r.binaryStdout){c=Buffer.concat([c??Buffer.alloc(0),Buffer.isBuffer(e)?e:Buffer.from(e)]);return}let t=String(e);u+=t,r.onStdoutChunk?.(t)}),s.stderr.on("data",e=>{let t=String(e);a+=t,r.onStderrChunk?.(t)}),s.on("error",e=>{"ENOENT"===e.code?i(new n("TOOL_MISSING",`${t} not found in PATH`,{cmd:t},e)):i(new n("COMMAND_FAILED",`Failed to run ${t}`,{cmd:t,args:o},e))}),s.on("close",e=>{let s=e??1;0===s||r.allowFailure?d({stdout:u,stderr:a,exitCode:s,stdoutBuffer:c}):i(new n("COMMAND_FAILED",`${t} exited with code ${s}`,{cmd:t,args:o,stdout:u,stderr:a,exitCode:s}))})})}function u(t,o,r={}){let d=e(t,o,{cwd:r.cwd,env:r.env,stdio:["ignore","pipe","pipe"]}),i="",s="";d.stdout.setEncoding("utf8"),d.stderr.setEncoding("utf8"),d.stdout.on("data",e=>{i+=e}),d.stderr.on("data",e=>{s+=e});let a=new Promise((e,u)=>{d.on("error",e=>{"ENOENT"===e.code?u(new n("TOOL_MISSING",`${t} not found in PATH`,{cmd:t},e)):u(new n("COMMAND_FAILED",`Failed to run ${t}`,{cmd:t,args:o},e))}),d.on("close",d=>{let a=d??1;0===a||r.allowFailure?e({stdout:i,stderr:s,exitCode:a}):u(new n("COMMAND_FAILED",`${t} exited with code ${a}`,{cmd:t,args:o,stdout:i,stderr:s,exitCode:a}))})});return{child:d,wait:a}}export{fileURLToPath,pathToFileURL}from"node:url";export{default as node_net}from"node:net";export{default as node_fs,promises}from"node:fs";export{default as node_os}from"node:os";export{default as node_path}from"node:path";export{o as asAppError,n as errors_AppError,r as runCmd,u as runCmdBackground,i as runCmdDetached,s as runCmdStreaming,d as whichCmd};