@unrulysystems/rn-playwright-driver-runner 0.1.0

package/dist/cli.mjs

@@ -0,0 +1,1891 @@
+import { mkdtemp, readFile, writeFile, chmod, rm } from 'fs/promises';
+import net from 'net';
+import { tmpdir } from 'os';
+import path from 'path';
+import { promisify, parseArgs } from 'util';
+import { existsSync, createReadStream, openSync } from 'fs';
+import { pathToFileURL } from 'url';
+import { execFile, spawn } from 'child_process';
+import { randomBytes } from 'crypto';
+
+// src/cli.ts
+
+// src/constants.ts
+var ENV = {
+  metroUrl: "RN_METRO_URL",
+  deviceName: "RN_DEVICE_NAME",
+  timeout: "RN_TIMEOUT",
+  touchBackend: "RN_TOUCH_BACKEND",
+  xctestPort: "RN_TOUCH_XCTEST_PORT",
+  xctestTokenFile: "RN_TOUCH_XCTEST_TOKEN_FILE",
+  instrumentationPort: "RN_TOUCH_INSTRUMENTATION_PORT",
+  instrumentationTokenFile: "RN_TOUCH_INSTRUMENTATION_TOKEN_FILE",
+  androidSerial: "ANDROID_SERIAL"
+};
+var TOUCH_BACKEND = {
+  ios: "xctest",
+  android: "instrumentation"
+};
+var DEFAULTS = {
+  metroHost: "127.0.0.1",
+  metroPort: 8081,
+  metroReadyTimeoutMs: 9e4,
+  companionPort: 9999,
+  /** Covers a cold `xcodebuild test` build, not just process startup (FU-2). */
+  iosCompanionReadyTimeoutMs: 3e5,
+  androidCompanionReadyTimeoutMs: 45e3,
+  hermesTargetTimeoutMs: 6e4,
+  appLaunchAttempts: 3,
+  driverTimeoutMs: 3e4,
+  androidGradleTasks: [":app:assembleDebug", ":app:assembleDebugAndroidTest"],
+  androidAppApkPath: "android/app/build/outputs/apk/debug/app-debug.apk",
+  androidTestApkPath: "android/app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk",
+  instrumentationClass: "com.rndriver.touchcompanion.RNDriverTouchCompanion",
+  /** UI-test method the iOS companion exposes as a long-running server. */
+  xctestServerTest: "RNDriverTouchCompanionTests/testRunServer",
+  /** Device-private filename the Android companion reads its token from. */
+  androidTokenFileName: "rn-driver-touch-token"
+};
+var SECRET_PLACEHOLDER = "<token-file>";
+
+// src/plan/env.ts
+function buildIosDriverEnv(resolved, metro, timeoutMs) {
+  return {
+    [ENV.touchBackend]: TOUCH_BACKEND.ios,
+    [ENV.metroUrl]: metro.url,
+    [ENV.deviceName]: resolved.simName,
+    [ENV.timeout]: String(timeoutMs ?? DEFAULTS.driverTimeoutMs),
+    [ENV.xctestPort]: String(resolved.touchPort),
+    [ENV.xctestTokenFile]: resolved.tokenFile
+  };
+}
+function buildAndroidDriverEnv(resolved, metro, deviceName, timeoutMs) {
+  return {
+    [ENV.touchBackend]: TOUCH_BACKEND.android,
+    [ENV.metroUrl]: metro.url,
+    [ENV.deviceName]: deviceName,
+    [ENV.androidSerial]: resolved.serial,
+    [ENV.timeout]: String(timeoutMs ?? DEFAULTS.driverTimeoutMs),
+    [ENV.instrumentationPort]: String(resolved.touchPort),
+    [ENV.instrumentationTokenFile]: resolved.tokenFile
+  };
+}
+
+// src/plan/shared.ts
+function cmd(command, args) {
+  return { command, args };
+}
+function npx(args) {
+  return { command: "npx", args };
+}
+function shell(command) {
+  return { command: "sh", args: ["-c", command] };
+}
+function metroStartStep(metro) {
+  return {
+    id: "metro.start",
+    stage: "metro",
+    description: metro.reuseExisting ? `Start Metro (reuse if running) ${metro.url}` : `Start Metro ${metro.url}`,
+    action: {
+      type: "command",
+      background: true,
+      processKey: "metro",
+      command: shell(metro.command ?? `npx expo start --localhost --port ${metro.port}`)
+    }
+  };
+}
+function playwrightCommand(playwright, specs, passthrough) {
+  const args = ["playwright", "test"];
+  if (playwright?.config) args.push("--config", playwright.config);
+  const effectiveSpecs = specs.length > 0 ? specs : playwright?.specs ?? [];
+  args.push(...effectiveSpecs, ...passthrough);
+  args.push("--reporter=line");
+  return npx(args);
+}
+
+// src/plan/android.ts
+function planAndroid(input) {
+  const { android, metro, resolved, playwright, timeoutMs, specs, passthrough, hermesDeviceName } = input;
+  const serial = resolved.serial;
+  const gradleTasks = android.gradleTasks ?? [...DEFAULTS.androidGradleTasks];
+  const appApk = android.appApkPath ?? DEFAULTS.androidAppApkPath;
+  const testApk = android.testApkPath ?? DEFAULTS.androidTestApkPath;
+  const steps = [];
+  const push = (step) => steps.push(step);
+  push({
+    id: "android.prebuild",
+    stage: "build",
+    description: "Generate Android project (expo prebuild)",
+    action: {
+      type: "command",
+      command: npx(["expo", "prebuild", "--platform", "android", "--no-install"])
+    },
+    skippable: true
+  });
+  push({
+    id: "android.gradle",
+    stage: "build",
+    description: `Build app + androidTest APKs (${gradleTasks.join(" ")})`,
+    action: {
+      type: "command",
+      command: { command: "./gradlew", args: gradleTasks, cwd: "android" }
+    },
+    skippable: true
+  });
+  push({
+    id: "android.install-app",
+    stage: "build",
+    description: `Install app APK`,
+    action: { type: "command", command: adb(serial, ["install", "-r", appApk]) },
+    skippable: true
+  });
+  push({
+    id: "android.install-test",
+    stage: "build",
+    description: `Install androidTest APK`,
+    action: { type: "command", command: adb(serial, ["install", "-r", "-t", testApk]) },
+    skippable: true
+  });
+  push({
+    id: "android.install-token",
+    stage: "companion",
+    description: "Install companion token into app private files",
+    action: {
+      type: "command",
+      command: {
+        ...adbShellScript(
+          serial,
+          `run-as ${android.packageName} sh -c 'mkdir -p files && cat > files/${resolved.deviceTokenFileName} && chmod 600 files/${resolved.deviceTokenFileName}'`
+        ),
+        stdinFromFile: resolved.tokenFile
+      }
+    }
+  });
+  push(metroStartStep(metro));
+  push({
+    id: "metro.ready",
+    stage: "metro",
+    description: `Wait for Metro at ${metro.url}`,
+    action: {
+      type: "probe",
+      probe: { kind: "metro-status", metroUrl: metro.url, timeoutMs: metro.readyTimeoutMs }
+    }
+  });
+  push({
+    id: "android.reverse-metro",
+    stage: "device",
+    description: `adb reverse tcp:${metro.port}`,
+    action: {
+      type: "command",
+      command: adb(serial, ["reverse", `tcp:${metro.port}`, `tcp:${metro.port}`])
+    }
+  });
+  if (metro.port !== DEFAULTS.metroPort) {
+    push({
+      id: "android.reverse-default",
+      stage: "device",
+      description: `adb reverse tcp:${DEFAULTS.metroPort} -> tcp:${metro.port}`,
+      action: {
+        type: "command",
+        command: adb(serial, ["reverse", `tcp:${DEFAULTS.metroPort}`, `tcp:${metro.port}`])
+      }
+    });
+  }
+  push({
+    id: "android.debug-host",
+    stage: "device",
+    description: "Write app debug_http_host",
+    action: {
+      type: "command",
+      command: {
+        // Single adb-shell arg so the redirect runs inside the run-as'd app-uid
+        // shell (the shared_prefs path is app-private; the outer `shell` uid
+        // cannot write it).
+        ...adbShellScript(
+          serial,
+          `run-as ${android.packageName} sh -c 'mkdir -p /data/data/${android.packageName}/shared_prefs && cat > /data/data/${android.packageName}/shared_prefs/${android.packageName}_preferences.xml'`
+        ),
+        stdinContents: debugHostXml(`localhost:${metro.port}`)
+      }
+    }
+  });
+  const launchCommand = launchCommandFor(android, serial);
+  push(launchStep("android.launch-1", android, serial));
+  push(hermesStep("android.hermes-1", android, metro, resolved, hermesDeviceName, launchCommand));
+  push({
+    id: "android.forward-clean",
+    stage: "companion",
+    description: `Clear stale adb forward tcp:${resolved.touchPort}`,
+    action: {
+      type: "command",
+      command: adb(serial, ["forward", "--remove", `tcp:${resolved.touchPort}`]),
+      allowFailure: true
+    }
+  });
+  push({
+    id: "android.forward",
+    stage: "companion",
+    description: `adb forward tcp:${resolved.touchPort}`,
+    action: {
+      type: "command",
+      command: adb(serial, ["forward", `tcp:${resolved.touchPort}`, `tcp:${resolved.touchPort}`])
+    }
+  });
+  push({
+    id: "android.instrument-start",
+    stage: "companion",
+    description: `Start instrumentation companion on port ${resolved.touchPort}`,
+    action: {
+      type: "command",
+      background: true,
+      processKey: "companion",
+      command: adb(serial, [
+        "shell",
+        "am",
+        "instrument",
+        "-e",
+        "rnDriverAuthTokenFile",
+        resolved.deviceTokenFileName,
+        "-e",
+        "rnDriverPort",
+        String(resolved.touchPort),
+        "-w",
+        resolved.instrumentationTarget
+      ])
+    }
+  });
+  push({
+    id: "android.instrument-ready",
+    stage: "companion",
+    description: "Wait for companion to accept a hello",
+    action: {
+      type: "probe",
+      probe: {
+        kind: "instrumentation-hello",
+        port: resolved.touchPort,
+        tokenFile: resolved.tokenFile,
+        timeoutMs: resolved.companionReadyTimeoutMs
+      }
+    }
+  });
+  push(launchStep("android.launch-2", android, serial));
+  push(hermesStep("android.hermes-2", android, metro, resolved, hermesDeviceName, launchCommand));
+  const cleanup = [
+    {
+      type: "kill-process",
+      processKey: "companion",
+      description: "Stop instrumentation companion"
+    },
+    {
+      type: "command",
+      command: adb(serial, ["reverse", "--remove", `tcp:${metro.port}`]),
+      description: "Remove metro reverse"
+    },
+    // Mirror android.reverse-default: when Metro is off 8081 the plan also adds a
+    // `tcp:8081 -> tcp:<port>` fallback reverse, so cleanup must remove BOTH or a
+    // stale 8081 mapping wedges the next run (REQ-CLEAN-003).
+    ...metro.port === DEFAULTS.metroPort ? [] : [
+      {
+        type: "command",
+        command: adb(serial, ["reverse", "--remove", `tcp:${DEFAULTS.metroPort}`]),
+        description: "Remove fallback 8081 metro reverse"
+      }
+    ],
+    {
+      type: "command",
+      command: adb(serial, ["forward", "--remove", `tcp:${resolved.touchPort}`]),
+      description: "Remove companion forward"
+    },
+    {
+      type: "command",
+      command: adb(serial, [
+        "shell",
+        "run-as",
+        android.packageName,
+        "rm",
+        "-f",
+        `files/${resolved.deviceTokenFileName}`
+      ]),
+      description: "Remove device token file"
+    },
+    {
+      type: "command",
+      command: adb(serial, ["shell", "am", "force-stop", android.packageName]),
+      description: "Force-stop app"
+    },
+    { type: "kill-process", processKey: "metro", description: "Stop runner-owned Metro" },
+    { type: "remove-file", path: resolved.tokenFile, description: "Remove per-run token file" }
+  ];
+  return {
+    platform: "android",
+    steps,
+    cleanup,
+    driverEnv: buildAndroidDriverEnv(resolved, metro, hermesDeviceName, timeoutMs),
+    playwright: playwrightCommand(playwright, specs, passthrough)
+  };
+}
+function launchCommandFor(android, serial) {
+  return adb(serial, [
+    "shell",
+    "am",
+    "start",
+    "-W",
+    "-n",
+    `${android.packageName}/${android.activity}`
+  ]);
+}
+function launchStep(id, android, serial) {
+  return {
+    id,
+    stage: "app-launch",
+    description: `Launch ${android.packageName}/${android.activity}`,
+    action: { type: "command", command: launchCommandFor(android, serial) }
+  };
+}
+function hermesStep(id, android, metro, resolved, deviceNameMatch, launchCommand) {
+  return {
+    id,
+    stage: "hermes-target",
+    description: "Wait for Hermes target",
+    action: {
+      type: "probe",
+      probe: {
+        kind: "hermes-target",
+        platform: "android",
+        metroUrl: metro.url,
+        appId: android.packageName,
+        deviceNameMatch,
+        timeoutMs: resolved.hermesTimeoutMs
+      },
+      // REQ-AND-005: on a transient miss, re-issue `am start` and re-probe.
+      // `appLaunchAttempts` total attempts ⇒ that many minus the first = retries.
+      retry: { command: launchCommand, max: DEFAULTS.appLaunchAttempts - 1 }
+    }
+  };
+}
+function debugHostXml(host) {
+  return `<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
+<map>
+  <string name="debug_http_host">${host}</string>
+</map>
+`;
+}
+function adb(serial, args) {
+  return { command: "adb", args: ["-s", serial, ...args] };
+}
+function adbShellScript(serial, remote) {
+  return { command: "adb", args: ["-s", serial, "shell", remote] };
+}
+
+// src/plan/ios.ts
+function planIos(input) {
+  const { ios, metro, resolved, playwright, timeoutMs, specs, passthrough } = input;
+  const isDevClient = ios.launch.kind === "expo-dev-client";
+  const steps = [];
+  const push = (step) => steps.push(step);
+  push({
+    id: "ios.boot",
+    stage: "device",
+    description: `Boot simulator ${resolved.simName}`,
+    action: {
+      type: "command",
+      command: xcrun(["simctl", "boot", resolved.simUdid]),
+      allowFailure: true
+    }
+  });
+  push({
+    id: "ios.boot-wait",
+    stage: "device",
+    description: `Wait for ${resolved.simName} to finish booting`,
+    action: { type: "command", command: xcrun(["simctl", "bootstatus", resolved.simUdid, "-b"]) }
+  });
+  push({
+    id: "ios.prebuild",
+    stage: "build",
+    description: "Generate iOS project (expo prebuild)",
+    action: {
+      type: "command",
+      command: npx(["expo", "prebuild", "--platform", "ios", "--no-install"])
+    },
+    skippable: true
+  });
+  push({
+    id: "ios.scaffold",
+    stage: "build",
+    description: "Scaffold XCTest companion target",
+    action: {
+      type: "command",
+      // Pass the resolved UI-test scheme so a custom `ios.uitestScheme` scaffolds
+      // the SAME target that companion startup later builds (default is
+      // `${appScheme}UITests`).
+      command: npx([
+        "rn-driver-xctest-scaffold",
+        "--ios-dir",
+        "ios",
+        "--project-name",
+        ios.appScheme,
+        "--uitest-scheme",
+        resolved.uitestScheme
+      ])
+    },
+    skippable: true
+  });
+  push({
+    id: "ios.runtime-config",
+    stage: "build",
+    description: "Write companion runtime config (port + token-file ref)",
+    action: {
+      type: "write-file",
+      path: resolved.runtimeConfigFile,
+      contents: runtimeConfigJson(resolved, ios),
+      mode: 384
+    }
+  });
+  push({
+    id: "ios.pods",
+    stage: "build",
+    description: "Install CocoaPods",
+    action: { type: "command", command: cmd("pod", ["install", "--project-directory=ios"]) },
+    skippable: true
+  });
+  push(metroStartStep(metro));
+  push({
+    id: "metro.ready",
+    stage: "metro",
+    description: `Wait for Metro at ${metro.url}`,
+    action: {
+      type: "probe",
+      probe: { kind: "metro-status", metroUrl: metro.url, timeoutMs: metro.readyTimeoutMs }
+    }
+  });
+  push({
+    id: "ios.packager-host-location",
+    stage: "device",
+    description: "Point app at Metro (RCT_jsLocation)",
+    action: {
+      type: "command",
+      command: xcrun([
+        "simctl",
+        "spawn",
+        resolved.simUdid,
+        "defaults",
+        "write",
+        ios.bundleId,
+        "RCT_jsLocation",
+        `${metro.host}:${metro.port}`
+      ]),
+      allowFailure: true
+    }
+  });
+  push({
+    id: "ios.packager-host-scheme",
+    stage: "device",
+    description: "Point app at Metro (RCT_packager_scheme)",
+    action: {
+      type: "command",
+      command: xcrun([
+        "simctl",
+        "spawn",
+        resolved.simUdid,
+        "defaults",
+        "write",
+        ios.bundleId,
+        "RCT_packager_scheme",
+        "http"
+      ]),
+      allowFailure: true
+    }
+  });
+  push({
+    id: "ios.build-app",
+    stage: "build",
+    description: `Build app scheme ${ios.appScheme}`,
+    action: {
+      type: "command",
+      command: xcodebuild([
+        "build",
+        "-workspace",
+        ios.workspace,
+        "-scheme",
+        ios.appScheme,
+        "-destination",
+        resolved.destination,
+        `RCT_METRO_PORT=${metro.port}`
+      ])
+    },
+    skippable: true
+  });
+  for (const [key, value] of Object.entries(ios.defaults ?? {})) {
+    push({
+      id: `ios.seed.${key}`,
+      stage: "device",
+      description: `Seed default ${key}`,
+      action: {
+        type: "command",
+        command: xcrun([
+          "simctl",
+          "spawn",
+          resolved.simUdid,
+          "defaults",
+          "write",
+          ios.bundleId,
+          ...defaultsArgs(key, value)
+        ]),
+        allowFailure: true
+      }
+    });
+  }
+  push({
+    id: "ios.free-port",
+    stage: "companion",
+    description: `Free stale listener on port ${resolved.touchPort}`,
+    action: { type: "free-port", port: resolved.touchPort }
+  });
+  push({
+    id: "ios.companion-start",
+    stage: "companion",
+    description: `Start XCTest companion on port ${resolved.touchPort}`,
+    action: {
+      type: "command",
+      background: true,
+      processKey: "companion",
+      command: xcodebuild(
+        [
+          "test",
+          "-workspace",
+          ios.workspace,
+          "-scheme",
+          resolved.uitestScheme,
+          "-destination",
+          resolved.destination,
+          `-only-testing:${resolved.uitestScheme}/${DEFAULTS.xctestServerTest}`,
+          `RCT_METRO_PORT=${metro.port}`
+        ],
+        {
+          RN_TOUCH_XCTEST_PORT: String(resolved.touchPort),
+          RN_TOUCH_XCTEST_CONFIG_FILE: resolved.runtimeConfigFile
+        }
+      )
+    }
+  });
+  push({
+    id: "ios.companion-ready",
+    stage: "companion",
+    description: "Wait for companion to accept a hello",
+    action: {
+      type: "probe",
+      probe: {
+        kind: "xctest-hello",
+        port: resolved.touchPort,
+        tokenFile: resolved.tokenFile,
+        timeoutMs: resolved.companionReadyTimeoutMs
+      }
+    }
+  });
+  if (isDevClient) {
+    push({
+      id: "ios.terminate-before-launch",
+      stage: "app-launch",
+      description: "Terminate any running instance (cold launch requires it)",
+      action: {
+        type: "command",
+        command: xcrun(["simctl", "terminate", resolved.simUdid, ios.bundleId]),
+        allowFailure: true
+      }
+    });
+    push({
+      id: "ios.launch",
+      stage: "app-launch",
+      description: `Cold-launch dev client via --initialUrl ${resolved.initialUrl}`,
+      action: {
+        type: "command",
+        command: xcrun([
+          "simctl",
+          "launch",
+          resolved.simUdid,
+          ios.bundleId,
+          "--initialUrl",
+          resolved.initialUrl
+        ])
+      }
+    });
+  }
+  push({
+    id: "ios.hermes",
+    stage: "hermes-target",
+    description: "Wait for Hermes target",
+    action: {
+      type: "probe",
+      probe: {
+        kind: "hermes-target",
+        platform: "ios",
+        metroUrl: metro.url,
+        appId: ios.bundleId,
+        deviceNameMatch: resolved.simName,
+        timeoutMs: resolved.hermesTimeoutMs
+      }
+    }
+  });
+  const cleanup = [
+    { type: "kill-process", processKey: "companion", description: "Stop XCTest companion" },
+    {
+      type: "free-port",
+      port: resolved.touchPort,
+      description: "Free companion port (reap sim-hosted child)"
+    },
+    { type: "kill-process", processKey: "metro", description: "Stop runner-owned Metro" },
+    { type: "remove-file", path: resolved.tokenFile, description: "Remove per-run token file" },
+    // REQ-SEC-004: the per-run runtime config (port + token-file ref) is written
+    // into the UI-test target every run; remove it so no generated artifact is
+    // left in the app project.
+    {
+      type: "remove-file",
+      path: resolved.runtimeConfigFile,
+      description: "Remove per-run companion runtime config"
+    }
+  ];
+  return {
+    platform: "ios",
+    steps,
+    cleanup,
+    driverEnv: buildIosDriverEnv(resolved, metro, timeoutMs),
+    playwright: playwrightCommand(playwright, specs, passthrough)
+  };
+}
+function runtimeConfigJson(resolved, ios) {
+  return JSON.stringify({
+    port: resolved.touchPort,
+    authTokenFile: resolved.tokenFile,
+    launch: ios.launch.mode
+  });
+}
+function defaultsArgs(key, value) {
+  if (typeof value === "boolean") return [key, "-bool", value ? "YES" : "NO"];
+  if (typeof value === "number") return [key, "-int", String(value)];
+  return [key, value];
+}
+function xcrun(args) {
+  return { command: "xcrun", args };
+}
+function xcodebuild(args, env) {
+  return env ? { command: "env", args: ["-u", "LD", "xcodebuild", ...args], env } : { command: "env", args: ["-u", "LD", "xcodebuild", ...args] };
+}
+
+// src/plan/resolved.ts
+function resolveMetro(metro, overrides = {}) {
+  const host = overrides.host ?? metro?.host ?? DEFAULTS.metroHost;
+  const fromUrl = parseMetroUrl(overrides.url ?? metro?.url);
+  const port = fromUrl?.port ?? overrides.port ?? metro?.port ?? DEFAULTS.metroPort;
+  const resolvedHost = fromUrl?.host ?? host;
+  const url = fromUrl?.url ?? `http://${resolvedHost}:${port}`;
+  return {
+    url,
+    host: resolvedHost,
+    port,
+    command: metro?.command,
+    reuseExisting: metro?.reuseExisting ?? false,
+    readyTimeoutMs: metro?.readyTimeoutMs ?? DEFAULTS.metroReadyTimeoutMs
+  };
+}
+function parseMetroUrl(raw) {
+  if (!raw) return void 0;
+  const parsed = new URL(raw);
+  const port = parsed.port ? Number.parseInt(parsed.port, 10) : parsed.protocol === "https:" ? 443 : 80;
+  return { url: raw.replace(/\/$/, ""), host: parsed.hostname, port };
+}
+function uitestScheme(ios) {
+  return ios.uitestScheme ?? `${ios.appScheme}UITests`;
+}
+function instrumentationTarget(android) {
+  return android.instrumentationTarget ?? `${android.packageName}.test/${DEFAULTS.instrumentationClass}`;
+}
+function placeholderIos(ios, metro) {
+  return {
+    simUdid: "<sim-udid>",
+    simName: "<sim-name>",
+    destination: ios.destination ?? "platform=iOS Simulator,id=<sim-udid>",
+    uitestScheme: uitestScheme(ios),
+    touchPort: ios.companion?.port ?? DEFAULTS.companionPort,
+    companionReadyTimeoutMs: ios.companion?.readyTimeoutMs ?? DEFAULTS.iosCompanionReadyTimeoutMs,
+    hermesTimeoutMs: DEFAULTS.hermesTargetTimeoutMs,
+    tokenFile: SECRET_PLACEHOLDER,
+    runtimeConfigFile: "<runtime-config>",
+    initialUrl: ios.launch.initialUrl ?? metro.url
+  };
+}
+function placeholderAndroid(android, _metro) {
+  return {
+    serial: "<android-serial>",
+    touchPort: android.companion?.port ?? DEFAULTS.companionPort,
+    companionReadyTimeoutMs: android.companion?.readyTimeoutMs ?? DEFAULTS.androidCompanionReadyTimeoutMs,
+    hermesTimeoutMs: DEFAULTS.hermesTargetTimeoutMs,
+    tokenFile: SECRET_PLACEHOLDER,
+    deviceTokenFileName: DEFAULTS.androidTokenFileName,
+    instrumentationTarget: instrumentationTarget(android)
+  };
+}
+
+// src/build-plan.ts
+function buildDryRunPlan(config, platform, opts = {}) {
+  const metro = resolveMetro(config.metro, opts.metroOverrides ?? {});
+  const specs = opts.specs ?? [];
+  const passthrough = opts.passthrough ?? [];
+  if (platform === "ios") {
+    const ios = config.ios;
+    if (!ios) throw new Error("config.ios is required to plan the ios platform");
+    return planIos({
+      ios,
+      metro,
+      resolved: placeholderIos(ios, metro),
+      playwright: config.playwright,
+      timeoutMs: config.timeoutMs,
+      specs,
+      passthrough
+    });
+  }
+  const android = config.android;
+  if (!android) throw new Error("config.android is required to plan the android platform");
+  return planAndroid({
+    android,
+    metro,
+    resolved: placeholderAndroid(android),
+    playwright: config.playwright,
+    timeoutMs: config.timeoutMs,
+    specs,
+    passthrough,
+    hermesDeviceName: "<android-device>"
+  });
+}
+var DEFAULT_CONFIG_NAMES = [
+  "rn-driver.config.ts",
+  "rn-driver.config.mts",
+  "rn-driver.config.mjs",
+  "rn-driver.config.js"
+];
+var ConfigNotFoundError = class extends Error {
+  constructor(searchedFrom, configPath) {
+    super(
+      configPath ? `Config file not found: ${configPath}` : `No rn-driver.config.{ts,mts,mjs,js} found searching up from ${searchedFrom}`
+    );
+    this.name = "ConfigNotFoundError";
+  }
+};
+var defaultImporter = (absolutePath) => import(pathToFileURL(absolutePath).href);
+async function loadConfig(opts) {
+  const importer = opts.importer ?? defaultImporter;
+  const fileExists = opts.fileExists ?? existsSync;
+  const resolvedPath = opts.configPath ? path.resolve(opts.cwd, opts.configPath) : findConfigUp(opts.cwd, fileExists);
+  if (!resolvedPath || !fileExists(resolvedPath)) {
+    throw new ConfigNotFoundError(opts.cwd, opts.configPath);
+  }
+  const namespace = await importer(resolvedPath);
+  const config = extractDefault(namespace);
+  return { path: resolvedPath, config };
+}
+function extractDefault(namespace) {
+  if (namespace && typeof namespace === "object" && "default" in namespace) {
+    return namespace.default;
+  }
+  return namespace;
+}
+function findConfigUp(startDir, fileExists) {
+  let dir = path.resolve(startDir);
+  for (; ; ) {
+    for (const name of DEFAULT_CONFIG_NAMES) {
+      const candidate = path.join(dir, name);
+      if (fileExists(candidate)) return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+
+// src/print-plan.ts
+function renderPlan(plan) {
+  const lines = [];
+  lines.push(`Plan (${plan.platform}) \u2014 ${plan.steps.length} steps`);
+  for (const step of plan.steps) {
+    const tag = `[${step.stage}]`.padEnd(15);
+    const skip = step.skippable ? " (skip-build: skipped)" : "";
+    lines.push(`  ${tag}${step.id} \u2014 ${step.description}${skip}`);
+    lines.push(`      ${renderAction(step.action)}`);
+  }
+  lines.push("");
+  lines.push("Driver env (handed to Playwright):");
+  for (const [key, value] of Object.entries(plan.driverEnv)) {
+    lines.push(`  ${key}=${value}`);
+  }
+  lines.push("");
+  lines.push("Playwright:");
+  lines.push(`  ${renderCommand(plan.playwright)}`);
+  lines.push("");
+  lines.push("Cleanup (defensive, idempotent):");
+  for (const action of plan.cleanup) {
+    lines.push(`  - ${action.description}: ${renderCleanup(action)}`);
+  }
+  return lines.join("\n");
+}
+function renderAction(action) {
+  switch (action.type) {
+    case "command":
+      return `${action.background ? "spawn " : "$ "}${renderCommand(action.command)}${action.allowFailure ? "  (best-effort)" : ""}`;
+    case "write-file":
+      return `write ${action.path}${action.mode ? ` (mode ${action.mode.toString(8)})` : ""}`;
+    case "free-port":
+      return `free-port ${action.port}`;
+    case "probe":
+      return `probe ${renderProbe(action.probe)}`;
+    default: {
+      const _exhaustive = action;
+      throw new Error(`unhandled action: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+function renderCleanup(action) {
+  switch (action.type) {
+    case "kill-process":
+      return `kill ${action.processKey}`;
+    case "free-port":
+      return `free-port ${action.port}`;
+    case "remove-file":
+      return `rm ${action.path}`;
+    case "command":
+      return `$ ${renderCommand(action.command)}`;
+    default: {
+      const _exhaustive = action;
+      throw new Error(`unhandled cleanup: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+function renderCommand(command) {
+  const env = command.env ? `${Object.entries(command.env).map(([k, v]) => `${k}=${v}`).join(" ")} ` : "";
+  const stdin = command.stdinFromFile ? ` < ${command.stdinFromFile}` : command.stdinContents ? " < <stdin>" : "";
+  const cwd = command.cwd ? ` (cwd: ${command.cwd})` : "";
+  return `${env}${command.command} ${command.args.join(" ")}${stdin}${cwd}`.trim();
+}
+function renderProbe(probe) {
+  switch (probe.kind) {
+    case "metro-status":
+      return `metro-status ${probe.metroUrl} (\u2264${probe.timeoutMs}ms)`;
+    case "hermes-target":
+      return `hermes-target ${probe.appId}${probe.deviceNameMatch ? ` @ ${probe.deviceNameMatch}` : ""} (\u2264${probe.timeoutMs}ms)`;
+    case "xctest-hello":
+      return `xctest-hello :${probe.port} (\u2264${probe.timeoutMs}ms)`;
+    case "instrumentation-hello":
+      return `instrumentation-hello :${probe.port} (\u2264${probe.timeoutMs}ms)`;
+    default: {
+      const _exhaustive = probe;
+      throw new Error(`unhandled probe: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+
+// src/runner/execute.ts
+var StageError = class extends Error {
+  stage;
+  stepId;
+  constructor(stage, stepId, message) {
+    super(`[${stage}] ${stepId}: ${message}`);
+    this.name = "StageError";
+    this.stage = stage;
+    this.stepId = stepId;
+  }
+};
+async function executePlan(plan, runner, opts) {
+  const processes = /* @__PURE__ */ new Map();
+  const isAlive = (key) => {
+    const handle = processes.get(key);
+    return handle ? runner.isAlive(handle) : true;
+  };
+  try {
+    for (const step of plan.steps) {
+      if (opts.skipBuild && step.skippable) {
+        if (opts.verbose) runner.log(`skip (skip-build): ${step.id}`);
+        continue;
+      }
+      if (opts.skipStep && await opts.skipStep(step)) {
+        if (opts.verbose) runner.log(`skip: ${step.id}`);
+        continue;
+      }
+      await runStep(step, runner, opts, processes, isAlive);
+    }
+    runner.log(`Running Playwright: ${plan.playwright.command} ${plan.playwright.args.join(" ")}`);
+    const result = await runner.exec({
+      ...plan.playwright,
+      env: { ...plan.playwright.env, ...plan.driverEnv }
+    });
+    return { playwrightCode: result.code };
+  } finally {
+    await runCleanup(plan.cleanup, runner, opts, processes);
+  }
+}
+async function runStep(step, runner, opts, processes, isAlive) {
+  if (opts.verbose) runner.log(`\u2192 ${step.id}: ${step.description}`);
+  const action = step.action;
+  switch (action.type) {
+    case "command": {
+      if (action.background) {
+        const key = action.processKey ?? step.id;
+        const handle = runner.spawn(action.command, { key, logPath: logPathFor(opts.logDir, key) });
+        processes.set(key, handle);
+        return;
+      }
+      const result = await runner.exec(action.command);
+      if (result.code !== 0 && !action.allowFailure) {
+        throw new StageError(step.stage, step.id, `command exited ${result.code}`);
+      }
+      return;
+    }
+    case "write-file": {
+      await runner.writeFile(action.path, action.contents, action.mode);
+      return;
+    }
+    case "free-port": {
+      await runner.freePort(action.port);
+      return;
+    }
+    case "probe": {
+      const key = processKeyForProbe(action.probe);
+      const aliveFn = key === null ? () => true : () => isAlive(key);
+      let ready = await runner.probe(action.probe, aliveFn);
+      let remaining = action.retry?.max ?? 0;
+      while (!ready && remaining > 0) {
+        remaining -= 1;
+        if (action.retry) {
+          runner.log(`retry ${step.id}: re-running launch (${remaining} attempt(s) left)`);
+          await runner.exec(action.retry.command);
+        }
+        ready = await runner.probe(action.probe, aliveFn);
+      }
+      if (!ready) {
+        throw new StageError(
+          step.stage,
+          step.id,
+          `readiness timed out after ${action.probe.timeoutMs}ms`
+        );
+      }
+      return;
+    }
+    default: {
+      const _exhaustive = action;
+      throw new Error(`unhandled action: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+async function runCleanup(actions, runner, opts, processes) {
+  for (const action of actions) {
+    if (opts.skipCleanup && opts.skipCleanup(action)) continue;
+    try {
+      switch (action.type) {
+        case "kill-process": {
+          const handle = processes.get(action.processKey);
+          if (handle) await runner.kill(handle);
+          break;
+        }
+        case "free-port":
+          await runner.freePort(action.port);
+          break;
+        case "remove-file":
+          await runner.removeFile(action.path);
+          break;
+        case "command":
+          await runner.exec(action.command);
+          break;
+        default: {
+          const _exhaustive = action;
+          throw new Error(`unhandled cleanup: ${JSON.stringify(_exhaustive)}`);
+        }
+      }
+    } catch (error) {
+      runner.log(`cleanup ${action.description} failed: ${String(error)}`);
+    }
+  }
+}
+function processKeyForProbe(probe) {
+  switch (probe.kind) {
+    case "metro-status":
+      return "metro";
+    case "xctest-hello":
+    case "instrumentation-hello":
+      return "companion";
+    case "hermes-target":
+      return null;
+    default: {
+      const _exhaustive = probe;
+      throw new Error(`unhandled probe: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+function logPathFor(logDir, key) {
+  return `${logDir}/${key}.log`;
+}
+var PROBE_INTERVAL_MS = 1e3;
+var NodeProcessRunner = class {
+  children = /* @__PURE__ */ new Map();
+  exec(spec, _opts) {
+    return new Promise((resolve, reject) => {
+      const usesStdin = Boolean(spec.stdinFromFile) || spec.stdinContents !== void 0;
+      const child = spawn(spec.command, [...spec.args], {
+        cwd: spec.cwd,
+        env: { ...process.env, ...spec.env },
+        stdio: [usesStdin ? "pipe" : "inherit", "inherit", "inherit"]
+      });
+      child.on("error", reject);
+      if (usesStdin && child.stdin) {
+        if (spec.stdinFromFile) {
+          createReadStream(spec.stdinFromFile).pipe(child.stdin);
+        } else {
+          child.stdin.end(spec.stdinContents ?? "");
+        }
+      }
+      child.on("close", (code) => resolve({ code: code ?? 1, stdout: "", stderr: "" }));
+    });
+  }
+  spawn(spec, opts) {
+    const fd = openSync(opts.logPath, "a");
+    const child = spawn(spec.command, [...spec.args], {
+      cwd: spec.cwd,
+      env: { ...process.env, ...spec.env },
+      detached: true,
+      stdio: ["ignore", fd, fd]
+    });
+    child.unref();
+    this.children.set(opts.key, child);
+    return { key: opts.key, pid: child.pid };
+  }
+  isAlive(handle) {
+    const child = this.children.get(handle.key);
+    if (!child || child.exitCode !== null || child.signalCode !== null) return false;
+    if (handle.pid === void 0) return false;
+    try {
+      process.kill(handle.pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async kill(handle) {
+    const child = this.children.get(handle.key);
+    if (!child || handle.pid === void 0) return;
+    killGroup(handle.pid, "SIGTERM");
+    await delay(500);
+    if (this.isAlive(handle)) killGroup(handle.pid, "SIGKILL");
+    this.children.delete(handle.key);
+  }
+  /**
+   * Best-effort synchronous teardown for signal handlers: SIGKILL every tracked
+   * child's process group so a Ctrl-C / SIGTERM does not orphan the detached
+   * Metro/companion processes (REQ-CLEAN-001, signal clause). Synchronous because
+   * a signal handler cannot await before `process.exit`.
+   */
+  killAll() {
+    for (const child of this.children.values()) {
+      if (child.pid !== void 0) killGroup(child.pid, "SIGKILL");
+    }
+    this.children.clear();
+  }
+  async writeFile(path4, contents, mode) {
+    await writeFile(path4, contents);
+    if (mode !== void 0) await chmod(path4, mode);
+  }
+  async removeFile(path4) {
+    await rm(path4, { force: true });
+  }
+  async freePort(port) {
+    const pids = await this.lsofPids(port);
+    for (const pid of pids) {
+      try {
+        process.kill(pid, "SIGTERM");
+      } catch {
+      }
+    }
+    if (pids.length > 0) await delay(1e3);
+  }
+  probe(probe, isAlive) {
+    const deadline = Date.now() + probe.timeoutMs;
+    const attempt = async () => {
+      for (; ; ) {
+        if (!isAlive()) return false;
+        if (await probeOnce(probe)) return true;
+        if (Date.now() >= deadline) return false;
+        await delay(PROBE_INTERVAL_MS);
+      }
+    };
+    return attempt();
+  }
+  log(line) {
+    process.stderr.write(`${line}
+`);
+  }
+  lsofPids(port) {
+    return new Promise((resolve) => {
+      const child = spawn("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
+        stdio: ["ignore", "pipe", "ignore"]
+      });
+      let out = "";
+      child.stdout?.on("data", (chunk) => {
+        out += chunk.toString();
+      });
+      child.on("error", () => resolve([]));
+      child.on("close", () => {
+        const pids = out.split("\n").map((line) => Number.parseInt(line.trim(), 10)).filter((pid) => Number.isInteger(pid) && pid > 0);
+        resolve(pids);
+      });
+    });
+  }
+};
+function killGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+    }
+  }
+}
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function probeOnce(probe) {
+  switch (probe.kind) {
+    case "metro-status":
+      return metroStatusOk(probe.metroUrl);
+    case "hermes-target":
+      return hermesTargetPresent(probe);
+    case "xctest-hello":
+      return xctestHelloOk(probe.port, probe.tokenFile);
+    case "instrumentation-hello":
+      return instrumentationHelloOk(probe.port, probe.tokenFile);
+    default: {
+      const _exhaustive = probe;
+      throw new Error(`unhandled probe: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+async function metroStatusOk(metroUrl) {
+  try {
+    const response = await fetch(`${metroUrl}/status`, {
+      signal: AbortSignal.timeout(PROBE_INTERVAL_MS)
+    });
+    const body = await response.text();
+    return body.includes("packager-status:running");
+  } catch {
+    return false;
+  }
+}
+async function hermesTargetPresent(probe) {
+  try {
+    const response = await fetch(`${probe.metroUrl}/json`, {
+      signal: AbortSignal.timeout(PROBE_INTERVAL_MS)
+    });
+    if (!response.ok) return false;
+    const targets = await response.json();
+    return targets.some((target) => {
+      const isReactNative = String(target.title ?? "").includes("Hermes") || target.vm === "Hermes" || String(target.description ?? "").includes("React Native");
+      if (!isReactNative || target.appId !== probe.appId) return false;
+      if (!probe.deviceNameMatch) return true;
+      return String(target.deviceName ?? "").includes(probe.deviceNameMatch);
+    });
+  } catch {
+    return false;
+  }
+}
+async function xctestHelloOk(port, tokenFile) {
+  const WebSocketCtor = globalThis.WebSocket;
+  if (!WebSocketCtor)
+    throw new Error(
+      "global WebSocket is required for the xctest probe (run under bun or Node >= 22)"
+    );
+  const authToken = await readTokenFile(tokenFile);
+  return new Promise((resolve) => {
+    const socket = new WebSocketCtor(`ws://127.0.0.1:${port}`);
+    const timer = setTimeout(() => {
+      close(socket);
+      resolve(false);
+    }, PROBE_INTERVAL_MS);
+    socket.addEventListener("open", () => {
+      socket.send(
+        JSON.stringify({
+          id: 1,
+          type: "hello",
+          protocolVersion: 1,
+          client: "rn-driver-runner",
+          ...authToken ? { authToken } : {}
+        })
+      );
+    });
+    socket.addEventListener("message", (event) => {
+      clearTimeout(timer);
+      close(socket);
+      try {
+        const payload = JSON.parse(String(event.data));
+        resolve(payload.id === 1 && payload.ok === true);
+      } catch {
+        resolve(false);
+      }
+    });
+    socket.addEventListener("error", () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+  });
+}
+async function instrumentationHelloOk(port, tokenFile) {
+  try {
+    const token = await readTokenFile(tokenFile);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_INTERVAL_MS);
+    const response = await fetch(`http://127.0.0.1:${port}/command`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...token ? { "x-rn-driver-auth": token } : {}
+      },
+      body: JSON.stringify({ type: "hello" }),
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    const payload = await response.json().catch(() => void 0);
+    return response.ok && payload?.ok === true;
+  } catch {
+    return false;
+  }
+}
+async function readTokenFile(path4) {
+  try {
+    const token = (await readFile(path4, "utf8")).trim();
+    return token === "" ? void 0 : token;
+  } catch {
+    return void 0;
+  }
+}
+function close(socket) {
+  try {
+    socket.close();
+  } catch {
+  }
+}
+var run = promisify(execFile);
+async function resolveIosTarget(ios, metro, opts) {
+  const { udid, name } = await selectSimulator(ios, opts.device);
+  await terminateStaleOnOtherSims(udid, ios.bundleId);
+  const tokenFile = await mintTokenFile();
+  const scheme = uitestScheme(ios);
+  return {
+    simUdid: udid,
+    simName: name,
+    destination: ios.destination ?? `platform=iOS Simulator,id=${udid}`,
+    uitestScheme: scheme,
+    touchPort: ios.companion?.port ?? DEFAULTS.companionPort,
+    companionReadyTimeoutMs: ios.companion?.readyTimeoutMs ?? DEFAULTS.iosCompanionReadyTimeoutMs,
+    hermesTimeoutMs: DEFAULTS.hermesTargetTimeoutMs,
+    tokenFile,
+    runtimeConfigFile: path.join("ios", scheme, "RNDriverTouchCompanionRuntimeConfig.json"),
+    initialUrl: ios.launch.initialUrl ?? metro.url
+  };
+}
+async function resolveAndroidTarget(android, _metro, opts) {
+  const serial = await selectSerial(opts.device);
+  await requireBooted(serial);
+  const deviceName = (await capture("adb", ["-s", serial, "shell", "getprop", "ro.product.model"])).trim();
+  const tokenFile = await mintTokenFile();
+  return {
+    resolved: {
+      serial,
+      touchPort: android.companion?.port ?? DEFAULTS.companionPort,
+      companionReadyTimeoutMs: android.companion?.readyTimeoutMs ?? DEFAULTS.androidCompanionReadyTimeoutMs,
+      hermesTimeoutMs: DEFAULTS.hermesTargetTimeoutMs,
+      tokenFile,
+      deviceTokenFileName: DEFAULTS.androidTokenFileName,
+      instrumentationTarget: instrumentationTarget(android)
+    },
+    deviceName
+  };
+}
+async function selectSimulator(ios, deviceOverride) {
+  const data = JSON.parse(
+    await capture("xcrun", ["simctl", "list", "devices", "available", "--json"])
+  );
+  const all = Object.entries(data.devices ?? {}).flatMap(([runtime, list]) => list.map((device) => ({ ...device, runtime }))).filter((device) => device.isAvailable !== false);
+  return pickSimulator(all, deviceOverride, ios.destination);
+}
+function pickSimulator(devices, deviceOverride, destination) {
+  const explicitUdid = parseUdid(deviceOverride) ?? parseUdid(destination);
+  if (explicitUdid) {
+    const match = devices.find((device) => device.udid === explicitUdid);
+    if (!match) throw new Error(`requested iOS simulator not found: ${explicitUdid}`);
+    return { udid: match.udid, name: match.name };
+  }
+  if (deviceOverride) {
+    const byName = devices.find((device) => device.name === deviceOverride) ?? devices.find((device) => device.name.includes(deviceOverride));
+    if (!byName) throw new Error(`requested iOS simulator not found by name: ${deviceOverride}`);
+    return { udid: byName.udid, name: byName.name };
+  }
+  const byNewest = (a, b) => compareRuntime(runtimeVersion(b.runtime), runtimeVersion(a.runtime));
+  const iphones = devices.filter((device) => device.name.startsWith("iPhone"));
+  const booted = iphones.filter((device) => device.state === "Booted").sort(byNewest);
+  const pick = booted[0] ?? [...iphones].sort(byNewest)[0];
+  if (!pick) throw new Error("no available iPhone simulator found");
+  return { udid: pick.udid, name: pick.name };
+}
+async function terminateStaleOnOtherSims(keepUdid, bundleId) {
+  const booted = await capture("xcrun", ["simctl", "list", "devices", "booted"]);
+  const udids = booted.match(/[0-9A-Fa-f-]{36}/g) ?? [];
+  for (const udid of udids) {
+    if (udid === keepUdid) continue;
+    await capture("xcrun", ["simctl", "terminate", udid, bundleId]).catch(() => "");
+  }
+}
+async function selectSerial(deviceOverride) {
+  await capture("adb", ["start-server"]).catch(() => "");
+  if (deviceOverride) {
+    await run("adb", ["-s", deviceOverride, "get-state"]);
+    return deviceOverride;
+  }
+  const devices = await capture("adb", ["devices"]);
+  const serial = devices.split("\n").slice(1).map((line) => line.trim().split(/\s+/)).find((cols) => cols[1] === "device" && cols[0]?.startsWith("emulator-"))?.[0];
+  if (!serial) throw new Error("no booted emulator found in `adb devices`");
+  return serial;
+}
+async function requireBooted(serial) {
+  const state = (await capture("adb", ["-s", serial, "get-state"])).trim();
+  if (state !== "device") throw new Error(`adb device ${serial} is not ready (state: ${state})`);
+  const booted = (await capture("adb", ["-s", serial, "shell", "getprop", "sys.boot_completed"])).trim();
+  if (booted !== "1") throw new Error(`adb device ${serial} has not completed boot`);
+}
+async function mintTokenFile() {
+  const dir = await mkdtemp(path.join(tmpdir(), "rn-driver-token-"));
+  const file = path.join(dir, "token");
+  await writeFile(file, randomBytes(16).toString("hex"));
+  await chmod(file, 384);
+  return file;
+}
+async function capture(command, args) {
+  const { stdout } = await run(command, args, { maxBuffer: 16 * 1024 * 1024 });
+  return stdout.toString();
+}
+function parseUdid(value) {
+  if (!value) return void 0;
+  const match = value.match(/id=([0-9A-Fa-f-]{36})/) ?? value.match(/^([0-9A-Fa-f-]{36})$/);
+  return match?.[1];
+}
+function runtimeVersion(runtime) {
+  const match = runtime.match(/iOS-([0-9-]+)$/);
+  return match?.[1] ? match[1].split("-").map((part) => Number.parseInt(part, 10)) : [0];
+}
+function compareRuntime(a, b) {
+  const length = Math.max(a.length, b.length);
+  for (let index = 0; index < length; index += 1) {
+    const delta = (a[index] ?? 0) - (b[index] ?? 0);
+    if (delta !== 0) return delta;
+  }
+  return 0;
+}
+
+// src/validate.ts
+var LAUNCH_MODES = ["launch", "activate", "attach"];
+var LAUNCH_KINDS = ["plain", "expo-dev-client"];
+var TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["metro", "ios", "android", "playwright", "timeoutMs"]);
+var METRO_KEYS = /* @__PURE__ */ new Set(["url", "command", "host", "port", "reuseExisting", "readyTimeoutMs"]);
+var LAUNCH_KEYS = /* @__PURE__ */ new Set(["mode", "kind", "initialUrl"]);
+var COMPANION_KEYS = /* @__PURE__ */ new Set(["port", "readyTimeoutMs"]);
+var IOS_KEYS = /* @__PURE__ */ new Set([
+  "bundleId",
+  "workspace",
+  "appScheme",
+  "uitestScheme",
+  "destination",
+  "launch",
+  "companion",
+  "defaults"
+]);
+var ANDROID_KEYS = /* @__PURE__ */ new Set([
+  "packageName",
+  "activity",
+  "gradleTasks",
+  "appApkPath",
+  "testApkPath",
+  "instrumentationTarget",
+  "launch",
+  "companion"
+]);
+var PLAYWRIGHT_KEYS = /* @__PURE__ */ new Set(["config", "specs"]);
+function validateConfig(config, platforms) {
+  const errors = [];
+  if (!isRecord(config)) {
+    return {
+      ok: false,
+      errors: ["config: expected an object exported as default from rn-driver.config"]
+    };
+  }
+  reportUnknownKeys("config", config, TOP_LEVEL_KEYS, errors);
+  if (config.timeoutMs !== void 0 && !isPositiveNumber(config.timeoutMs)) {
+    errors.push("config.timeoutMs: expected a positive number");
+  }
+  validateMetro(config.metro, errors);
+  validatePlaywright(config.playwright, errors);
+  if (platforms.includes("ios")) validateIos(config.ios, errors);
+  if (platforms.includes("android")) validateAndroid(config.android, errors);
+  return { ok: errors.length === 0, errors };
+}
+function validateMetro(metro, errors) {
+  if (metro === void 0) return;
+  if (!isRecord(metro)) {
+    errors.push("config.metro: expected an object");
+    return;
+  }
+  reportUnknownKeys("config.metro", metro, METRO_KEYS, errors);
+  optionalString("config.metro.url", metro.url, errors);
+  optionalString("config.metro.command", metro.command, errors);
+  optionalString("config.metro.host", metro.host, errors);
+  if (metro.port !== void 0 && !isPort(metro.port))
+    errors.push("config.metro.port: expected a port (1-65535)");
+  if (metro.reuseExisting !== void 0 && typeof metro.reuseExisting !== "boolean") {
+    errors.push("config.metro.reuseExisting: expected a boolean");
+  }
+  if (metro.readyTimeoutMs !== void 0 && !isPositiveNumber(metro.readyTimeoutMs)) {
+    errors.push("config.metro.readyTimeoutMs: expected a positive number");
+  }
+}
+function validatePlaywright(playwright, errors) {
+  if (playwright === void 0) return;
+  if (!isRecord(playwright)) {
+    errors.push("config.playwright: expected an object");
+    return;
+  }
+  reportUnknownKeys("config.playwright", playwright, PLAYWRIGHT_KEYS, errors);
+  optionalString("config.playwright.config", playwright.config, errors);
+  if (playwright.specs !== void 0 && !isStringArray(playwright.specs)) {
+    errors.push("config.playwright.specs: expected an array of strings");
+  }
+}
+function validateIos(ios, errors) {
+  if (!isRecord(ios)) {
+    errors.push('config.ios: required when platform "ios" is selected (expected an object)');
+    return;
+  }
+  reportUnknownKeys("config.ios", ios, IOS_KEYS, errors);
+  requireString("config.ios.bundleId", ios.bundleId, errors);
+  requireString("config.ios.workspace", ios.workspace, errors);
+  requireString("config.ios.appScheme", ios.appScheme, errors);
+  optionalString("config.ios.uitestScheme", ios.uitestScheme, errors);
+  optionalString("config.ios.destination", ios.destination, errors);
+  validateCompanion("config.ios.companion", ios.companion, errors);
+  if (ios.defaults !== void 0) {
+    if (!isRecord(ios.defaults)) {
+      errors.push("config.ios.defaults: expected an object of key -> string|number|boolean");
+    } else {
+      for (const [key, value] of Object.entries(ios.defaults)) {
+        const kind = typeof value;
+        if (kind !== "string" && kind !== "number" && kind !== "boolean") {
+          errors.push(`config.ios.defaults.${key}: expected string|number|boolean`);
+        }
+      }
+    }
+  }
+  const launch = validateLaunch("config.ios.launch", ios.launch, errors);
+  if (launch && launch.kind === "expo-dev-client" && launch.mode !== "attach") {
+    errors.push(
+      'config.ios.launch: kind "expo-dev-client" requires mode "attach" (the host owns the launch)'
+    );
+  }
+  if (launch && launch.mode === "attach" && launch.kind !== "expo-dev-client") {
+    errors.push(
+      'config.ios.launch: mode "attach" requires kind "expo-dev-client"; a plain app uses mode "launch" or "activate" (the companion launches it)'
+    );
+  }
+}
+function validateAndroid(android, errors) {
+  if (!isRecord(android)) {
+    errors.push('config.android: required when platform "android" is selected (expected an object)');
+    return;
+  }
+  reportUnknownKeys("config.android", android, ANDROID_KEYS, errors);
+  requireAndroidPackage("config.android.packageName", android.packageName, errors);
+  requireAndroidActivity("config.android.activity", android.activity, errors);
+  optionalString("config.android.appApkPath", android.appApkPath, errors);
+  optionalString("config.android.testApkPath", android.testApkPath, errors);
+  if (android.instrumentationTarget !== void 0)
+    requireInstrumentationTarget(
+      "config.android.instrumentationTarget",
+      android.instrumentationTarget,
+      errors
+    );
+  if (android.gradleTasks !== void 0 && !isStringArray(android.gradleTasks)) {
+    errors.push("config.android.gradleTasks: expected an array of strings");
+  }
+  validateCompanion("config.android.companion", android.companion, errors);
+  validateLaunch("config.android.launch", android.launch, errors);
+}
+function validateCompanion(path4, companion, errors) {
+  if (companion === void 0) return;
+  if (!isRecord(companion)) {
+    errors.push(`${path4}: expected an object`);
+    return;
+  }
+  reportUnknownKeys(path4, companion, COMPANION_KEYS, errors);
+  if (companion.port !== void 0 && !isPort(companion.port))
+    errors.push(`${path4}.port: expected a port (1-65535)`);
+  if (companion.readyTimeoutMs !== void 0 && !isPositiveNumber(companion.readyTimeoutMs)) {
+    errors.push(`${path4}.readyTimeoutMs: expected a positive number`);
+  }
+}
+function validateLaunch(path4, launch, errors) {
+  if (!isRecord(launch)) {
+    errors.push(`${path4}: required (expected an object with mode and kind)`);
+    return void 0;
+  }
+  reportUnknownKeys(path4, launch, LAUNCH_KEYS, errors);
+  optionalString(`${path4}.initialUrl`, launch.initialUrl, errors);
+  const modeOk = typeof launch.mode === "string" && LAUNCH_MODES.includes(launch.mode);
+  const kindOk = typeof launch.kind === "string" && LAUNCH_KINDS.includes(launch.kind);
+  if (!modeOk) errors.push(`${path4}.mode: expected one of ${LAUNCH_MODES.join(", ")}`);
+  if (!kindOk) errors.push(`${path4}.kind: expected one of ${LAUNCH_KINDS.join(", ")}`);
+  return modeOk && kindOk ? { mode: launch.mode, kind: launch.kind } : void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPositiveNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function isPort(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535;
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function requireString(path4, value, errors) {
+  if (typeof value !== "string" || value.trim() === "")
+    errors.push(`${path4}: required non-empty string`);
+}
+var ANDROID_PACKAGE_RE = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$/;
+var ANDROID_ACTIVITY_RE = /^\.?[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)*$/;
+function requireAndroidPackage(path4, value, errors) {
+  if (typeof value !== "string" || value.trim() === "") {
+    errors.push(`${path4}: required non-empty string`);
+    return;
+  }
+  if (!ANDROID_PACKAGE_RE.test(value))
+    errors.push(`${path4}: expected a valid Android application id (e.g. com.company.app)`);
+}
+function requireAndroidActivity(path4, value, errors) {
+  if (typeof value !== "string" || value.trim() === "") {
+    errors.push(`${path4}: required non-empty string`);
+    return;
+  }
+  if (!ANDROID_ACTIVITY_RE.test(value))
+    errors.push(`${path4}: expected an activity name (e.g. .MainActivity)`);
+}
+var ANDROID_INSTRUMENTATION_RE = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)*\/[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)*$/;
+function requireInstrumentationTarget(path4, value, errors) {
+  if (typeof value !== "string" || value.trim() === "") {
+    errors.push(`${path4}: expected a non-empty string`);
+    return;
+  }
+  if (!ANDROID_INSTRUMENTATION_RE.test(value))
+    errors.push(`${path4}: expected an am instrument target (e.g. com.app.test/com.app.Runner)`);
+}
+function optionalString(path4, value, errors) {
+  if (value !== void 0 && typeof value !== "string") errors.push(`${path4}: expected a string`);
+}
+function reportUnknownKeys(path4, value, allowed, errors) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) errors.push(`${path4}.${key}: unknown key`);
+  }
+}
+function assertValid(config, platforms) {
+  const result = validateConfig(config, platforms);
+  if (!result.ok) {
+    throw new ConfigValidationError(result.errors);
+  }
+}
+var ConfigValidationError = class extends Error {
+  errors;
+  constructor(errors) {
+    super(`Invalid rn-driver config:
+  - ${errors.join("\n  - ")}`);
+    this.name = "ConfigValidationError";
+    this.errors = errors;
+  }
+};
+
+// src/cli.ts
+var STAGE_EXIT_CODES = {
+  config: 10,
+  metro: 11,
+  device: 12,
+  build: 13,
+  companion: 14,
+  "app-launch": 15,
+  "hermes-target": 16,
+  playwright: 1,
+  cleanup: 17
+};
+async function run2(argv) {
+  const { command, specs, passthrough, flags } = parseCliArgs(argv);
+  if (flags.help) {
+    printHelp();
+    return 0;
+  }
+  if (command !== "test") {
+    process.stderr.write(`Unknown command: ${command ?? "(none)"}
+`);
+    printHelp();
+    return 2;
+  }
+  let platforms;
+  try {
+    platforms = resolvePlatforms(flags.platform);
+  } catch (error) {
+    process.stderr.write(`${error.message}
+`);
+    return 2;
+  }
+  let config;
+  try {
+    const loaded = await loadConfig({
+      cwd: process.cwd(),
+      ...flags.config ? { configPath: flags.config } : {}
+    });
+    assertValid(loaded.config, platforms);
+    config = loaded.config;
+  } catch (error) {
+    if (error instanceof ConfigValidationError || error instanceof ConfigNotFoundError) {
+      process.stderr.write(`${error.message}
+`);
+      return 2;
+    }
+    throw error;
+  }
+  if (flags.dryRun) {
+    for (const platform of platforms) {
+      process.stdout.write(
+        `${renderPlan(buildDryRunPlan(config, platform, { specs, passthrough }))}
+
+`
+      );
+    }
+    return 0;
+  }
+  const runner = new NodeProcessRunner();
+  const logDir = await mkdtemp(path.join(tmpdir(), "rn-driver-logs-"));
+  const onSignal = (signal) => {
+    process.stderr.write(`
+Received ${signal} \u2014 terminating runner-owned processes\u2026
+`);
+    runner.killAll();
+    process.exit(130);
+  };
+  const onSigint = () => onSignal("SIGINT");
+  const onSigterm = () => onSignal("SIGTERM");
+  process.on("SIGINT", onSigint);
+  process.on("SIGTERM", onSigterm);
+  try {
+    let exitCode = 0;
+    for (const platform of platforms) {
+      runner.log(`
+=== platform: ${platform} ===`);
+      const code = await runPlatform(platform, config, {
+        runner,
+        logDir,
+        flags,
+        specs,
+        passthrough
+      });
+      if (code !== 0) exitCode = code;
+    }
+    return exitCode;
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+    process.removeListener("SIGTERM", onSigterm);
+  }
+}
+async function runPlatform(platform, config, ctx) {
+  const metro = resolveMetro(config.metro);
+  const reuseMetro = metro.reuseExisting && await metroRunning(metro.url);
+  if (reuseMetro) ctx.runner.log(`Reusing Metro already running at ${metro.url}`);
+  if (!reuseMetro && await portInUse(metro.host, metro.port)) {
+    process.stderr.write(
+      `
+FAILED [${platform}] at stage [metro] metro.preflight: ${metro.host}:${metro.port} is already in use. Free it, set metro.reuseExisting, or choose another metro.port.
+`
+    );
+    return STAGE_EXIT_CODES.metro;
+  }
+  let plan;
+  try {
+    plan = await buildPlatformPlan(platform, config, metro, ctx);
+  } catch (error) {
+    process.stderr.write(`
+FAILED [${platform}] at stage [device]: ${error.message}
+`);
+    return STAGE_EXIT_CODES.device;
+  }
+  try {
+    const result = await executePlan(plan, ctx.runner, {
+      logDir: ctx.logDir,
+      skipBuild: ctx.flags.skipBuild,
+      verbose: ctx.flags.verbose,
+      skipStep: (step) => reuseMetro && step.id === "metro.start",
+      skipCleanup: (action) => reuseMetro && action.type === "kill-process" && action.processKey === "metro"
+    });
+    if (result.playwrightCode === 0) {
+      ctx.runner.log(`PASS: ${platform} e2e`);
+    } else {
+      ctx.runner.log(`FAIL: ${platform} Playwright exited ${result.playwrightCode}`);
+    }
+    return result.playwrightCode;
+  } catch (error) {
+    if (error instanceof StageError) {
+      process.stderr.write(
+        `
+FAILED [${platform}] at stage [${error.stage}] ${error.stepId}: ${error.message}
+`
+      );
+      process.stderr.write(`Logs: ${ctx.logDir}
+`);
+      await printLogTail(ctx.logDir, "metro");
+      await printLogTail(ctx.logDir, "companion");
+      return STAGE_EXIT_CODES[error.stage];
+    }
+    throw error;
+  }
+}
+async function buildPlatformPlan(platform, config, metro, ctx) {
+  if (platform === "ios") {
+    if (!config.ios) throw new Error("config.ios is required for the ios platform");
+    const resolved2 = await resolveIosTarget(config.ios, metro, deviceOpt(ctx.flags.device));
+    return planIos({
+      ios: config.ios,
+      metro,
+      resolved: resolved2,
+      playwright: config.playwright,
+      timeoutMs: config.timeoutMs,
+      specs: ctx.specs,
+      passthrough: ctx.passthrough
+    });
+  }
+  if (!config.android) throw new Error("config.android is required for the android platform");
+  const { resolved, deviceName } = await resolveAndroidTarget(
+    config.android,
+    metro,
+    deviceOpt(ctx.flags.device)
+  );
+  return planAndroid({
+    android: config.android,
+    metro,
+    resolved,
+    playwright: config.playwright,
+    timeoutMs: config.timeoutMs,
+    specs: ctx.specs,
+    passthrough: ctx.passthrough,
+    hermesDeviceName: deviceName
+  });
+}
+function deviceOpt(device) {
+  return device ? { device } : {};
+}
+async function metroRunning(metroUrl) {
+  try {
+    const response = await fetch(`${metroUrl}/status`, { signal: AbortSignal.timeout(2e3) });
+    return (await response.text()).includes("packager-status:running");
+  } catch {
+    return false;
+  }
+}
+async function printLogTail(logDir, key, lines = 20) {
+  try {
+    const content = await readFile(path.join(logDir, `${key}.log`), "utf8");
+    const tail = content.split("\n").filter((line) => line.length > 0).slice(-lines);
+    if (tail.length > 0)
+      process.stderr.write(`
+--- ${key} log (last ${tail.length} lines) ---
+${tail.join("\n")}
+`);
+  } catch {
+  }
+}
+function portInUse(host, port) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port });
+    const finish = (inUse) => {
+      socket.destroy();
+      resolve(inUse);
+    };
+    socket.setTimeout(1e3);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+  });
+}
+function resolvePlatforms(platform) {
+  if (!platform) throw new Error("--platform <ios|android|all> is required");
+  if (platform === "all") return ["ios", "android"];
+  if (platform === "ios" || platform === "android") return [platform];
+  throw new Error(`--platform must be one of ios, android, all (got: ${platform})`);
+}
+function parseCliArgs(argv) {
+  const dashDash = argv.indexOf("--");
+  const before = dashDash === -1 ? argv : argv.slice(0, dashDash);
+  const passthrough = dashDash === -1 ? [] : argv.slice(dashDash + 1);
+  const { values, positionals } = parseArgs({
+    args: before,
+    options: {
+      platform: { type: "string", short: "p" },
+      config: { type: "string", short: "c" },
+      device: { type: "string", short: "d" },
+      "dry-run": { type: "boolean" },
+      "skip-build": { type: "boolean" },
+      verbose: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    },
+    allowPositionals: true
+  });
+  const [command = "test", ...specs] = positionals;
+  return {
+    command,
+    specs,
+    passthrough,
+    flags: {
+      platform: values.platform,
+      config: values.config,
+      device: values.device,
+      dryRun: values["dry-run"] ?? false,
+      skipBuild: values["skip-build"] ?? false,
+      verbose: values.verbose ?? false,
+      help: values.help ?? false
+    }
+  };
+}
+function printHelp() {
+  process.stdout.write(`
+rn-driver \u2014 config-backed cross-platform RN Playwright e2e runner
+
+Usage:
+  rn-driver test --platform <ios|android|all> [options] [specs...] [-- <playwright args>]
+
+Options:
+  -p, --platform   ios | android | all                       (required)
+  -c, --config     Path to rn-driver.config.{ts,mjs,js}      (default: searched upward)
+  -d, --device     Simulator udid / emulator serial override
+      --dry-run    Print the resolved plan and exit (no side effects)
+      --skip-build Reuse an already-built native project
+      --verbose    Stream per-step progress
+  -h, --help       Show help
+
+Examples:
+  rn-driver test --platform ios
+  rn-driver test --platform android --skip-build
+  rn-driver test --platform all --dry-run
+  rn-driver test --platform ios e2e/integration/counter.spec.ts
+`);
+}
+
+export { run2 as run };
+//# sourceMappingURL=cli.mjs.map
+//# sourceMappingURL=cli.mjs.map