@unrulysystems/rn-playwright-driver-runner 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1057 @@
+// src/config.ts
+function defineRnDriverConfig(config) {
+  return config;
+}
+
+// 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>"
+  });
+}
+
+// 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/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(path, companion, errors) {
+  if (companion === void 0) return;
+  if (!isRecord(companion)) {
+    errors.push(`${path}: expected an object`);
+    return;
+  }
+  reportUnknownKeys(path, companion, COMPANION_KEYS, errors);
+  if (companion.port !== void 0 && !isPort(companion.port))
+    errors.push(`${path}.port: expected a port (1-65535)`);
+  if (companion.readyTimeoutMs !== void 0 && !isPositiveNumber(companion.readyTimeoutMs)) {
+    errors.push(`${path}.readyTimeoutMs: expected a positive number`);
+  }
+}
+function validateLaunch(path, launch, errors) {
+  if (!isRecord(launch)) {
+    errors.push(`${path}: required (expected an object with mode and kind)`);
+    return void 0;
+  }
+  reportUnknownKeys(path, launch, LAUNCH_KEYS, errors);
+  optionalString(`${path}.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(`${path}.mode: expected one of ${LAUNCH_MODES.join(", ")}`);
+  if (!kindOk) errors.push(`${path}.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(path, value, errors) {
+  if (typeof value !== "string" || value.trim() === "")
+    errors.push(`${path}: 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(path, value, errors) {
+  if (typeof value !== "string" || value.trim() === "") {
+    errors.push(`${path}: required non-empty string`);
+    return;
+  }
+  if (!ANDROID_PACKAGE_RE.test(value))
+    errors.push(`${path}: expected a valid Android application id (e.g. com.company.app)`);
+}
+function requireAndroidActivity(path, value, errors) {
+  if (typeof value !== "string" || value.trim() === "") {
+    errors.push(`${path}: required non-empty string`);
+    return;
+  }
+  if (!ANDROID_ACTIVITY_RE.test(value))
+    errors.push(`${path}: 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(path, value, errors) {
+  if (typeof value !== "string" || value.trim() === "") {
+    errors.push(`${path}: expected a non-empty string`);
+    return;
+  }
+  if (!ANDROID_INSTRUMENTATION_RE.test(value))
+    errors.push(`${path}: expected an am instrument target (e.g. com.app.test/com.app.Runner)`);
+}
+function optionalString(path, value, errors) {
+  if (value !== void 0 && typeof value !== "string") errors.push(`${path}: expected a string`);
+}
+function reportUnknownKeys(path, value, allowed, errors) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) errors.push(`${path}.${key}: unknown key`);
+  }
+}
+var ConfigValidationError = class extends Error {
+  errors;
+  constructor(errors) {
+    super(`Invalid rn-driver config:
+  - ${errors.join("\n  - ")}`);
+    this.name = "ConfigValidationError";
+    this.errors = errors;
+  }
+};
+
+export { ConfigValidationError, buildDryRunPlan, defineRnDriverConfig, renderPlan, validateConfig };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map