@bugmole/cli 0.4.0

package/src/runtime/blocker-resolution.ts

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { json, type ObjectStore } from "../storage/object-store.js";
+import { projectPrefix } from "../storage/keys.js";
+
+export type BlockerFingerprintInput = {
+  category: string;
+  reason: string;
+  route?: string;
+  nodeId?: string;
+  environmentId?: string;
+};
+
+export type BlockerResolution = {
+  resolutionId: string;
+  fingerprint: string;
+  category: string;
+  reason: string;
+  route?: string;
+  nodeId?: string;
+  workspaceId?: string;
+  projectId: string;
+  environmentId?: string;
+  question: string;
+  resolution: string;
+  createdAt: string;
+  updatedAt: string;
+  expiresAt?: string;
+  supersededBy?: string;
+};
+
+function storeFor(cfg: any): ObjectStore {
+  return createProjectObjectStore(cfg);
+}
+
+function projectIdFor(cfg: any): string {
+  return cfg.project?.id ?? "default";
+}
+
+function normalize(value: string | undefined): string {
+  return (value ?? "").trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+export function blockerFingerprint(input: BlockerFingerprintInput): string {
+  const canonical = [
+    normalize(input.category),
+    normalize(input.reason),
+    normalize(input.route),
+    normalize(input.nodeId),
+    normalize(input.environmentId),
+  ].join("|");
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
+}
+
+export function blockerResolutionKey(cfg: any, fingerprint: string): string {
+  return `${projectPrefix(projectIdFor(cfg))}/blocker-resolutions/${fingerprint}.json`;
+}
+
+export async function readBlockerResolution(
+  cfg: any,
+  input: BlockerFingerprintInput,
+): Promise<BlockerResolution | null> {
+  const fingerprint = blockerFingerprint(input);
+  const store = storeFor(cfg);
+  const key = blockerResolutionKey(cfg, fingerprint);
+  if (!(await store.has(key))) return null;
+  try {
+    const value = JSON.parse(await store.getText(key)) as BlockerResolution;
+    if (value.supersededBy) return null;
+    if (value.expiresAt && Date.parse(value.expiresAt) <= Date.now()) return null;
+    return value.fingerprint === fingerprint ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeBlockerResolution(
+  cfg: any,
+  input: BlockerFingerprintInput & {
+    workspaceId?: string;
+    question: string;
+    resolution: string;
+    expiresAt?: string;
+  },
+): Promise<BlockerResolution> {
+  if (!input.question.trim() || !input.resolution.trim()) {
+    throw new Error("question and resolution are required");
+  }
+  const projectId = projectIdFor(cfg);
+  const fingerprint = blockerFingerprint(input);
+  const now = new Date().toISOString();
+  const existing = await readBlockerResolution(cfg, input);
+  const record: BlockerResolution = {
+    resolutionId: existing?.resolutionId ?? `resolution_${fingerprint}`,
+    fingerprint,
+    category: input.category.trim(),
+    reason: input.reason.trim(),
+    route: input.route?.trim() || undefined,
+    nodeId: input.nodeId?.trim() || undefined,
+    workspaceId: input.workspaceId ?? cfg.project?.workspace_id ?? cfg.project?.workspaceId,
+    projectId,
+    environmentId: input.environmentId ?? cfg.project?.environment_id ?? cfg.project?.environmentId,
+    question: input.question.trim(),
+    resolution: input.resolution.trim(),
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+    expiresAt: input.expiresAt,
+  };
+  await storeFor(cfg).put(blockerResolutionKey(cfg, fingerprint), json(record), "application/json");
+  return record;
+}

package/src/runtime/browser-matrix.integration.test.ts

@@ -0,0 +1,212 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { chromium, firefox, webkit } from "playwright";
+import { PlaywrightDriver } from "./playwright-driver.js";
+import type { RunTarget } from "./browser-matrix.js";
+
+const page = `<!doctype html>
+<html><head><meta name="viewport" content="width=device-width, initial-scale=1"></head><body>
+<h1>Matrix fixture</h1>
+<button onclick="document.querySelector('p').textContent='Signed in on ' + (window.innerWidth < 600 ? 'mobile' : 'desktop')">Sign in</button>
+<p></p>
+</body></html>`;
+
+async function installed(executablePath: () => string): Promise<boolean> {
+  try {
+    await fs.access(executablePath());
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Engines missing on this machine are skipped rather than failed, so CI with
+// only Chromium still runs the Chromium part.
+const engines: Array<{ target: RunTarget; available: Promise<boolean>; expect: string }> = [
+  { target: { id: "chromium", browser: "chromium" }, available: installed(() => chromium.executablePath()), expect: "desktop" },
+  { target: { id: "firefox", browser: "firefox" }, available: installed(() => firefox.executablePath()), expect: "desktop" },
+  { target: { id: "webkit", browser: "webkit" }, available: installed(() => webkit.executablePath()), expect: "desktop" },
+  {
+    target: { id: "webkit-iphone-15", browser: "webkit", device: "iPhone 15" },
+    available: installed(() => webkit.executablePath()),
+    expect: "mobile",
+  },
+];
+
+for (const engine of engines) {
+  test(`runs a flow on ${engine.target.id}`, async (t) => {
+    if (!(await engine.available)) {
+      t.skip(`${engine.target.browser} is not installed`);
+      return;
+    }
+    const server = http.createServer((_request, response) => {
+      response.writeHead(200, { "content-type": "text/html" });
+      response.end(page);
+    });
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address() as { port: number };
+    const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-matrix-"));
+    const flowPath = path.join(directory, "sign-in.yaml");
+    // Authored against another origin: the run must follow the environment URL.
+    await fs.writeFile(flowPath, `url: http://authored.invalid:9/
+---
+- launchApp
+- tapOn: "Sign in"
+- assertVisible: "Signed in on ${engine.expect}"
+`);
+    try {
+      const result = await new PlaywrightDriver({ headless: true }).run({
+        runId: "run-matrix",
+        projectId: "demo",
+        journeyId: "sign-in",
+        flowPath,
+        platform: "web",
+        target: { baseUrl: `http://127.0.0.1:${port}` },
+        timeoutMs: 30_000,
+        artifactsDir: directory,
+        runTarget: engine.target,
+        rebaseOrigin: true,
+      });
+      assert.equal(result.status, "passed", result.message);
+      assert.equal(typeof result.durationMs, "number");
+      const targetDir = path.join(directory, "demo", "run-matrix", "sign-in", engine.target.id);
+      assert.ok((await fs.readdir(targetDir)).length > 0, "artifacts are written under the target's own folder");
+    } finally {
+      server.close();
+      await fs.rm(directory, { recursive: true, force: true });
+    }
+  });
+}
+
+test("Edge either runs or is reported as not installed with the install command", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-matrix-edge-"));
+  const server = http.createServer((_request, response) => {
+    response.writeHead(200, { "content-type": "text/html" });
+    response.end(page);
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as { port: number };
+  const flowPath = path.join(directory, "edge.yaml");
+  await fs.writeFile(flowPath, `name: edge\n---\n- launchApp\n- assertVisible: "Matrix fixture"\n`);
+  try {
+    const result = await new PlaywrightDriver({ headless: true }).run({
+      runId: "run-edge",
+      projectId: "demo",
+      journeyId: "edge",
+      flowPath,
+      platform: "web",
+      target: { baseUrl: `http://127.0.0.1:${port}` },
+      timeoutMs: 30_000,
+      artifactsDir: directory,
+      runTarget: { id: "msedge", browser: "msedge" },
+    });
+    if (result.status === "blocked") {
+      assert.equal(result.failureCode, "browser_not_installed", result.message);
+      assert.match(result.message, /npx playwright install msedge/);
+    } else {
+      assert.equal(result.status, "passed", result.message);
+    }
+  } finally {
+    server.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("reports an unsupported pairing as blocked without launching a browser", async () => {
+  const result = await new PlaywrightDriver({ headless: true }).run({
+    runId: "run-matrix",
+    projectId: "demo",
+    journeyId: "sign-in",
+    flowPath: "/does/not/matter.yaml",
+    platform: "web",
+    target: { baseUrl: "http://127.0.0.1:9" },
+    timeoutMs: 5_000,
+    artifactsDir: os.tmpdir(),
+    runTarget: { id: "firefox-iphone-15", browser: "firefox", device: "iPhone 15" },
+  });
+  assert.equal(result.status, "blocked");
+  assert.equal(result.failureCode, "unsupported_target");
+});
+
+test("a failed checkout captures what was on screen, a trace, and a fix that makes it pass", async (t) => {
+  if (!(await installed(() => chromium.executablePath()))) {
+    t.skip("Chromium is not installed");
+    return;
+  }
+  const checkout = `<!doctype html><html><head><title>Checkout</title></head><body>
+<h1>Shipping address</h1>
+<form id="f" novalidate>
+<label>Full name <input name="name" required></label>
+<label>Email <input name="email" type="email" required></label>
+<button type="submit">Continue to payment</button>
+<p id="err" role="alert" hidden>Please enter a valid email</p>
+</form>
+<h2 id="pay" hidden>Payment</h2>
+<script>
+document.getElementById('f').addEventListener('submit', (e) => {
+  e.preventDefault();
+  const email = document.querySelector('[name=email]');
+  if (!/.+@.+/.test(email.value)) { email.setAttribute('aria-invalid', 'true'); document.getElementById('err').hidden = false; return; }
+  document.getElementById('pay').hidden = false;
+});
+</script></body></html>`;
+  const server = http.createServer((_request, response) => {
+    response.writeHead(200, { "content-type": "text/html" });
+    response.end(checkout);
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as { port: number };
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-analysis-"));
+  const flowPath = path.join(directory, "checkout.yaml");
+  await fs.writeFile(flowPath, `name: checkout
+---
+- launchApp
+- tapOn: "Full name"
+- inputText: "Ada Lovelace"
+- tapOn: "Continue to payment"
+- assertVisible:
+    text: "Payment"
+    timeout: 1500
+`);
+  const run = (runId: string) => new PlaywrightDriver({ headless: true }).run({
+    runId,
+    projectId: "demo",
+    journeyId: "checkout",
+    flowPath,
+    platform: "web",
+    target: { baseUrl: `http://127.0.0.1:${port}/` },
+    timeoutMs: 30_000,
+    artifactsDir: directory,
+    runTarget: { id: "chromium", browser: "chromium" },
+  });
+  try {
+    const failed = await run("run-fail");
+    assert.equal(failed.status, "failed");
+    const names = failed.artifacts.map((artifact) => artifact.name);
+    for (const name of ["failure-context.json", "analysis.json", "playwright-trace.zip", "playwright-failure.png", "playwright.log"]) {
+      assert.ok(names.includes(name), `${name} in ${names.join(", ")}`);
+    }
+    assert.equal(failed.steps?.[4].status, "failed");
+    assert.equal(failed.steps?.[4].label, "See “Payment”");
+    assert.equal(typeof failed.steps?.[4].durationMs, "number");
+    const read = async (name: string) => JSON.parse(await fs.readFile(failed.artifacts.find((artifact) => artifact.name === name)!.path, "utf8"));
+    const context = await read("failure-context.json");
+    assert.deepEqual(context.alerts, ["Please enter a valid email"]);
+    assert.deepEqual(context.invalidFields.map((field: { label: string }) => field.label), ["Email"]);
+    assert.doesNotMatch(JSON.stringify(context), /Ada Lovelace/);
+    const analysis = await read("analysis.json");
+    assert.equal(analysis.category, "test");
+
+    const { applyFlowChanges } = await import("./failure-analysis.js");
+    await fs.writeFile(flowPath, applyFlowChanges(await fs.readFile(flowPath, "utf8"), analysis.suggestedFix.changes));
+    const fixed = await run("run-fixed");
+    assert.equal(fixed.status, "passed", fixed.message);
+  } finally {
+    server.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});

package/src/runtime/browser-matrix.test.ts

@@ -0,0 +1,143 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  contextOptionsFor,
+  defaultTargets,
+  installHint,
+  isMissingBrowserError,
+  launcherFor,
+  matrixTargets,
+  MAX_RUN_TARGETS,
+  normalizeTargets,
+  RunTargetError,
+  targetLabel,
+  targetsFromFlags,
+} from "./browser-matrix.js";
+import { aggregateTargetResults, resolveTargetConcurrency, runPool } from "./target-runner.js";
+import type { DriverResult } from "./driver.js";
+
+test("normalizes targets into unique, slugged ids", () => {
+  const targets = normalizeTargets([
+    { browser: "chromium" },
+    { browser: "webkit", device: "iPhone 15" },
+    { browser: "chromium" },
+    { browser: "msedge", device: "" },
+  ]);
+  assert.deepEqual(targets, [
+    { id: "chromium", browser: "chromium" },
+    { id: "webkit-iphone-15", browser: "webkit", device: "iPhone 15" },
+    { id: "msedge", browser: "msedge" },
+  ]);
+  assert.deepEqual(normalizeTargets(undefined), []);
+});
+
+test("rejects unknown browsers and devices instead of dropping them", () => {
+  assert.throws(() => normalizeTargets([{ browser: "opera" }]), RunTargetError);
+  assert.throws(() => normalizeTargets([{ browser: "chromium", device: "Nokia 3310" }]), /Unknown device/);
+  assert.throws(() => normalizeTargets("chromium"), /must be an array/);
+});
+
+test("caps the matrix size", () => {
+  const devices = ["iPhone 15", "iPhone 14", "iPhone 13", "iPhone 12", "Pixel 7", "Pixel 5", "Galaxy S9+", "iPad Mini", "iPhone SE"];
+  assert.throws(() => matrixTargets(["chromium", "firefox", "webkit", "msedge"], devices), new RegExp(`at most ${MAX_RUN_TARGETS}`));
+});
+
+test("emulates each device on the engine it ships with", () => {
+  const targets = matrixTargets(["firefox"], ["iPhone 15", "Pixel 7"]);
+  assert.deepEqual(targets.map((target) => target.id), ["firefox", "webkit-iphone-15", "chromium-pixel-7"]);
+  assert.equal(targetLabel(targets[1]), "iPhone 15 · Safari");
+});
+
+test("reads the matrix from config, defaulting to desktop Chromium", () => {
+  assert.deepEqual(defaultTargets(undefined), [{ id: "chromium", browser: "chromium" }]);
+  assert.deepEqual(
+    defaultTargets({ execution: { playwright: { browsers: ["firefox", "webkit"], devices: ["Pixel 7"] } } }).map((target) => target.id),
+    ["firefox", "webkit", "chromium-pixel-7"],
+  );
+});
+
+test("builds targets from CLI flags", () => {
+  assert.deepEqual(targetsFromFlags(undefined, undefined), []);
+  assert.deepEqual(targetsFromFlags("chromium, msedge", undefined).map((target) => target.id), ["chromium", "msedge"]);
+  assert.deepEqual(targetsFromFlags(undefined, "iPhone 15").map((target) => target.id), ["webkit-iphone-15"]);
+});
+
+test("launches Edge through Chromium's msedge channel", () => {
+  assert.equal(launcherFor("msedge").channel, "msedge");
+  assert.equal(launcherFor("msedge").type.name(), "chromium");
+  assert.equal(launcherFor("webkit").type.name(), "webkit");
+  assert.equal(launcherFor("firefox").channel, undefined);
+});
+
+test("blocks Firefox mobile emulation and applies device descriptors elsewhere", () => {
+  const firefoxPhone = contextOptionsFor({ id: "firefox-iphone-15", browser: "firefox", device: "iPhone 15" });
+  assert.ok("unsupported" in firefoxPhone);
+  const safariPhone = contextOptionsFor({ id: "webkit-iphone-15", browser: "webkit", device: "iPhone 15" });
+  assert.ok("options" in safariPhone);
+  assert.equal(safariPhone.options.isMobile, true);
+  assert.equal("defaultBrowserType" in safariPhone.options, false);
+  assert.deepEqual(contextOptionsFor({ id: "chromium", browser: "chromium" }), { options: {} });
+});
+
+test("recognizes a missing browser binary and explains how to install it", () => {
+  assert.equal(isMissingBrowserError(new Error("browserType.launch: Executable doesn't exist at /ms-playwright/firefox")), true);
+  assert.equal(isMissingBrowserError(new Error("Chromium distribution 'msedge' is not found at /opt/microsoft/msedge")), true);
+  assert.equal(isMissingBrowserError(new Error("net::ERR_CONNECTION_REFUSED")), false);
+  assert.match(installHint("firefox"), /npx playwright install firefox/);
+});
+
+test("runPool keeps order and never exceeds the limit", async () => {
+  let inFlight = 0;
+  let peak = 0;
+  const results = await runPool([30, 5, 20, 1, 10], 2, async (delay, index) => {
+    inFlight += 1;
+    peak = Math.max(peak, inFlight);
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    inFlight -= 1;
+    return index;
+  });
+  assert.deepEqual(results, [0, 1, 2, 3, 4]);
+  assert.equal(peak, 2);
+});
+
+test("target concurrency prefers env, then config, then up to four", () => {
+  assert.equal(resolveTargetConcurrency(undefined, 6, {}), 4);
+  assert.equal(resolveTargetConcurrency(undefined, 2, {}), 2);
+  assert.equal(resolveTargetConcurrency(3, 6, {}), 3);
+  assert.equal(resolveTargetConcurrency(3, 6, { BUGMOLE_TARGET_CONCURRENCY: "1" }), 1);
+});
+
+const step = (status: "passed" | "failed" | "blocked") => ({ sequenceNumber: 0, status, durationMs: 1 });
+const outcome = (id: string, result: Partial<DriverResult>) => ({
+  target: { id, browser: "chromium" as const },
+  result: { status: "passed" as const, message: "ok", artifacts: [], ...result } as DriverResult,
+});
+
+test("aggregates target results: any failure fails, blocked-only blocks", () => {
+  const failed = aggregateTargetResults([
+    outcome("chromium", { steps: [step("passed"), step("passed")] }),
+    outcome("firefox", { status: "failed", message: "boom", failureCode: "assertion", steps: [step("passed"), step("failed")] }),
+    outcome("msedge", { status: "blocked", message: "not installed", failureCode: "browser_not_installed" }),
+  ]);
+  assert.equal(failed.status, "failed");
+  assert.equal(failed.failureCode, "assertion");
+  assert.match(failed.message, /1 of 3 target\(s\) failed/);
+  assert.deepEqual(failed.steps?.map((entry) => entry.status), ["passed", "failed"]);
+
+  const passed = aggregateTargetResults([
+    outcome("chromium", {}),
+    outcome("msedge", { status: "blocked", message: "not installed" }),
+  ]);
+  assert.equal(passed.status, "passed");
+  assert.match(passed.message, /1 could not run/);
+
+  const blocked = aggregateTargetResults([outcome("msedge", { status: "blocked", message: "not installed", failureCode: "browser_not_installed" })]);
+  assert.equal(blocked.status, "blocked");
+  assert.equal(blocked.failureCode, "browser_not_installed");
+
+  const mismatched = aggregateTargetResults([
+    outcome("chromium", { steps: [step("passed")] }),
+    outcome("webkit", { steps: [step("passed"), step("passed")] }),
+  ]);
+  assert.equal(mismatched.steps, undefined);
+});

package/src/runtime/browser-matrix.ts

@@ -0,0 +1,200 @@
+import { chromium, devices, firefox, webkit, type BrowserContextOptions, type BrowserType } from "playwright";
+import { cloudDeviceLabel, type CloudDevice } from "./device-clouds/types.js";
+import { cloudTargetId, parseCloudDevice as parseCloudDeviceTarget } from "./device-clouds/targets.js";
+
+export const BROWSER_NAMES = ["chromium", "firefox", "webkit", "msedge"] as const;
+export type BrowserName = (typeof BROWSER_NAMES)[number];
+
+/** One browser (optionally emulating one device) a run executes against. */
+export type RunTarget = {
+  id: string;
+  /** For a cloud device, the engine closest to its browser (reporting only). */
+  browser: BrowserName;
+  device?: string;
+  /** A real device or emulator on a device cloud, driven over Appium. */
+  cloud?: CloudDevice;
+};
+
+export type RunTargetInput = { browser?: unknown; device?: unknown; kind?: unknown } & Record<string, unknown>;
+
+
+
+export const MAX_RUN_TARGETS = 12;
+
+export class RunTargetError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RunTargetError";
+  }
+}
+
+const BROWSER_LABELS: Record<BrowserName, string> = {
+  chromium: "Chrome",
+  firefox: "Firefox",
+  webkit: "Safari",
+  msedge: "Edge",
+};
+
+const INSTALL_NAMES: Record<BrowserName, string> = {
+  chromium: "chromium",
+  firefox: "firefox",
+  webkit: "webkit",
+  msedge: "msedge",
+};
+
+export function browserLabel(browser: BrowserName): string {
+  return BROWSER_LABELS[browser];
+}
+
+export function isBrowserName(value: unknown): value is BrowserName {
+  return typeof value === "string" && (BROWSER_NAMES as readonly string[]).includes(value);
+}
+
+export function isKnownDevice(value: string): boolean {
+  return Object.prototype.hasOwnProperty.call(devices, value);
+}
+
+function slug(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+export function targetId(browser: BrowserName, device?: string): string {
+  return device ? `${browser}-${slug(device)}` : browser;
+}
+
+export function targetLabel(target: RunTarget): string {
+  if (target.cloud) return cloudDeviceLabel(target.cloud);
+  return target.device ? `${target.device} · ${browserLabel(target.browser)}` : browserLabel(target.browser);
+}
+
+/**
+ * Validates a requested matrix (from a run request, CLI flags, or config) into
+ * unique, well-formed targets. Unknown browsers or device names are rejected
+ * rather than silently dropped, so a typo never turns into a smaller run than
+ * the person asked for.
+ */
+export function normalizeTargets(input: unknown): RunTarget[] {
+  if (input === undefined || input === null) return [];
+  if (!Array.isArray(input)) throw new RunTargetError("targets must be an array of { browser, device? }");
+  const seen = new Set<string>();
+  const targets: RunTarget[] = [];
+  for (const raw of input as RunTargetInput[]) {
+    if (raw?.kind === "device") {
+      let cloud: CloudDevice;
+      try {
+        cloud = parseCloudDeviceTarget(raw);
+      } catch (error) {
+        throw new RunTargetError(error instanceof Error ? error.message : String(error));
+      }
+      const id = cloudTargetId(cloud);
+      if (seen.has(id)) continue;
+      seen.add(id);
+      targets.push({ id, browser: cloud.platform === "ios" ? "webkit" : "chromium", cloud });
+      continue;
+    }
+    const browser = raw?.browser;
+    if (!isBrowserName(browser)) {
+      throw new RunTargetError(`Unsupported browser "${String(browser)}". Use one of: ${BROWSER_NAMES.join(", ")}.`);
+    }
+    let device: string | undefined;
+    if (raw.device !== undefined && raw.device !== null && raw.device !== "") {
+      if (typeof raw.device !== "string" || !isKnownDevice(raw.device)) {
+        throw new RunTargetError(`Unknown device "${String(raw.device)}". Use a Playwright device name such as "iPhone 15" or "Pixel 7".`);
+      }
+      device = raw.device;
+    }
+    const id = targetId(browser, device);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    targets.push(device ? { id, browser, device } : { id, browser });
+  }
+  if (targets.length > MAX_RUN_TARGETS) {
+    throw new RunTargetError(`A run can target at most ${MAX_RUN_TARGETS} browser/device combinations.`);
+  }
+  return targets;
+}
+
+/**
+ * Builds the cross product of browsers and devices. Desktop is always one row
+ * per browser; each device adds one row per browser that can emulate it.
+ */
+export function matrixTargets(browsers: string[], deviceNames: string[] = []): RunTarget[] {
+  const rows: RunTargetInput[] = browsers.map((browser) => ({ browser }));
+  for (const device of deviceNames) {
+    // A phone is emulated on the engine that ships on that phone: Safari's
+    // WebKit for Apple devices, Chromium for everything else. Firefox cannot
+    // emulate mobile at all.
+    const descriptor = isKnownDevice(device) ? devices[device] : undefined;
+    const preferred: BrowserName = descriptor?.defaultBrowserType === "webkit" ? "webkit" : "chromium";
+    rows.push({ browser: preferred, device });
+  }
+  return normalizeTargets(rows);
+}
+
+function splitList(value: unknown): string[] {
+  if (typeof value !== "string") return [];
+  return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+/**
+ * Targets from CLI flags (`--browsers chromium,firefox --devices "iPhone 15"`),
+ * or an empty list when neither flag was given. Devices alone run on their
+ * native engine; browsers alone run desktop.
+ */
+export function targetsFromFlags(browsers: unknown, deviceNames: unknown): RunTarget[] {
+  const browserList = splitList(browsers);
+  const deviceList = splitList(deviceNames);
+  if (browserList.length === 0 && deviceList.length === 0) return [];
+  return matrixTargets(browserList, deviceList);
+}
+
+type ExecutionConfig = { execution?: { playwright?: { browsers?: unknown; devices?: unknown } } };
+
+export function defaultTargets(cfg: ExecutionConfig | undefined): RunTarget[] {
+  const browsers = Array.isArray(cfg?.execution?.playwright?.browsers)
+    ? (cfg!.execution!.playwright!.browsers as unknown[]).map(String)
+    : ["chromium"];
+  const deviceNames = Array.isArray(cfg?.execution?.playwright?.devices)
+    ? (cfg!.execution!.playwright!.devices as unknown[]).map(String)
+    : [];
+  return matrixTargets(browsers, deviceNames);
+}
+
+export function launcherFor(browser: BrowserName): { type: BrowserType; channel?: string } {
+  switch (browser) {
+    case "firefox":
+      return { type: firefox };
+    case "webkit":
+      return { type: webkit };
+    case "msedge":
+      return { type: chromium, channel: "msedge" };
+    default:
+      return { type: chromium };
+  }
+}
+
+/**
+ * Context options for a target, or the reason it cannot run. Firefox has no
+ * mobile emulation in Playwright (`isMobile` throws), so that pairing is a
+ * blocked target rather than a failed run.
+ */
+export function contextOptionsFor(target: RunTarget): { options: BrowserContextOptions } | { unsupported: string } {
+  if (!target.device) return { options: {} };
+  const descriptor = devices[target.device];
+  if (!descriptor) return { unsupported: `Unknown device "${target.device}".` };
+  const { defaultBrowserType: _ignored, ...options } = descriptor;
+  if (target.browser === "firefox" && options.isMobile) {
+    return { unsupported: `Firefox cannot emulate the mobile device "${target.device}".` };
+  }
+  return { options };
+}
+
+/** Recognizes Playwright's "browser binary is not installed" launch failure. */
+export function isMissingBrowserError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /Executable doesn't exist|browserType\.launch: .*(not found|is not installed)|Chromium distribution 'msedge' is not found/i.test(message);
+}
+
+export function installHint(browser: BrowserName): string {
+  return `${browserLabel(browser)} is not installed on this worker. Install it with: npx playwright install ${INSTALL_NAMES[browser]}`;
+}