@momentiq/dark-factory-cli 2.4.0 → 2.6.0

package/skills/verify/producer/README.md

@@ -0,0 +1,73 @@
+# Reusable Playwright (UI) verification-route producer
+
+These are **reference files** for the Dark Factory `playwright` verification
+route — the UI-layer half of evidence-gated validation (`web/**` / `*.tsx`
+changes). They ship inside `@momentiq/dark-factory-cli` (so `df skills install
+verify` and the consumer guide can point you at them), but unlike a rendered
+skill they are **copy-once-and-own**: you adapt `SURFACES[]` and your auth to
+your app, and a future `df skills install verify` will **not** overwrite them.
+
+Generalized from the proven `dark-factory-dashboard` dogfood producer (Cycle 21
+EC2/EC8). The Clerk/Doppler auth coupling has been removed — auth is now an
+optional, consumer-supplied Playwright **storage-state**.
+
+## Files
+
+| File | Role | You edit? |
+|---|---|---|
+| `playwright-route.sh` | Route `command`: SHA + clean-tree guards, computes changed UI paths, runs Playwright, maps the 0/1/2 exit. | Env knobs only |
+| `playwright.ui-route.config.ts` | Dedicated Playwright config: one chromium project, optional storage-state, optional local-preview server. | `testDir` / dev command |
+| `ui-route.producer.spec.ts` | The capture: ARIA snapshot + after (+ optional before) screenshots, fail-closed coverage, optional VLM hook. | **`SURFACES[]`** (required) |
+| `coverage.ts` | Pure fail-closed coverage logic (a changed UI path with no surface blocks). Unit-tested upstream. | No |
+
+## Setup (one-time)
+
+1. **Copy** the four files into your repo. Convention: the script under
+   `scripts/verify/`, and `playwright.ui-route.config.ts` + `tests/e2e/
+   ui-route.producer.spec.ts` + `tests/e2e/coverage.ts` under your web app dir
+   (`web/` by default). Adjust `DF_UI_ROUTE_WEB_DIR` / `DF_UI_ROUTE_CONFIG` (see
+   the script header) if your layout differs.
+2. **Edit `SURFACES[]`** in `ui-route.producer.spec.ts` — your routes, each with
+   a structural `requiredHeading` (an accessible-name regex) and the `covers`
+   source globs it is the evidence for. v1 ships one public `/` surface so it
+   works zero-auth out of the box.
+3. **(Protected surfaces only)** Mint an authenticated Playwright `storageState`
+   JSON with your own auth and point `DF_UI_ROUTE_STORAGE_STATE` at it. Public
+   surfaces need none. Gitignore your storage-state (`**/.auth/`).
+4. **Arm the route** in `.agent-review/config.json` — override the `playwright`
+   route's placeholder `command` with `bash scripts/verify/playwright-route.sh`:
+
+   ```jsonc
+   {
+     "id": "playwright",
+     "trigger": ["web/**", "**/*.tsx"],
+     "command": "bash scripts/verify/playwright-route.sh",
+     "evidencePath": "agent-reviews/quality-gates/${sha}.json",
+     "category": "ui",
+     "evidenceKind": "playwright"
+   }
+   ```
+
+5. **Produce evidence**: `df verify --route playwright` (or it runs automatically
+   when `df verify` / `df gate-push` arm the route for a `web/**` / `*.tsx`
+   change). See `docs/guides/ui-verification-route.md` for the full walkthrough.
+
+## Environment knobs
+
+| Var | Default | Purpose |
+|---|---|---|
+| `DF_UI_ROUTE_WEB_DIR` | `web` | Where your app + `@playwright/test` live. |
+| `DF_UI_ROUTE_CONFIG` | `playwright.ui-route.config.ts` | Producer config, relative to the web dir. |
+| `DF_UI_ROUTE_STORAGE_STATE` | _(unset)_ | Path to an authenticated storage-state (protected surfaces). |
+| `PLAYWRIGHT_TEST_BASE_URL` | local preview | Point at a deployed preview of the SHA instead of serving locally. |
+| `DF_UI_ROUTE_DEV_CMD` | `npm run dev` | Local-preview server command. |
+| `DF_UI_ROUTE_PORT` | `3217` | Local-preview port. |
+| `DF_UI_ROUTE_BEFORE_BASE_URL` | _(unset)_ | Origin for the optional before/after baseline. |
+| `DF_UI_ROUTE_VLM` | _(unset)_ | `1` arms the optional VLM hook (deferred/no-op in v1). |
+
+## What this is NOT
+
+It does not mint your auth session and it does not guarantee that gitignored
+content absent from the commit cannot influence a capture (the v1 trust-boundary
+limitation — content-isolated re-execution is the v2 fix). It validates the
+**HEAD** working tree; producing evidence for a non-HEAD SHA fails closed.

package/skills/verify/producer/coverage.ts

@@ -0,0 +1,121 @@
+/**
+ * Fail-closed coverage logic for the reusable Evidence-Gated Validation
+ * **playwright (UI) route** producer (momentiq-ai/dark-factory#193).
+ *
+ * Generalized from the dark-factory-dashboard dogfood producer (Cycle 21 PR-4).
+ * This module is pure, importable, and unit-tested without a browser, so the
+ * load-bearing rule — *a changed UI path that maps to no capture surface BLOCKS
+ * the route* — cannot regress.
+ *
+ * A `web/**`/`*.tsx` change arms the route; this module decides, per changed
+ * path, whether a capture surface exists. If a changed *product-UI* path has no
+ * surface, it lands in `uncovered` and the producer fails closed — so the gate
+ * cannot be satisfied by rendering only an unaffected surface.
+ *
+ * This is a CONSUMER REFERENCE FILE: copy it into your repo alongside the
+ * producer spec and own it. It has no Dark Factory / vendor dependency.
+ */
+
+export interface UiSurface {
+  /** URL path to navigate (relative to baseURL). */
+  path: string;
+  /** Filesystem-safe slug for the evidence subdir. */
+  slug: string;
+  /** A role+name the surface MUST expose (structural floor assertion). */
+  requiredHeading: RegExp;
+  /**
+   * Source-path globs this surface is the evidence for. A changed path
+   * matching one of these is "covered" by this surface's capture.
+   */
+  covers: readonly string[];
+}
+
+export interface CoveragePartition {
+  /** Surfaces armed because a changed path matches their `covers`. */
+  armed: UiSurface[];
+  /** Changed UI paths with no mapped surface (the fail-closed set). */
+  uncovered: string[];
+  /**
+   * True when the route is armed (the change touched the trigger surface) but
+   * NO surface was armed AND nothing is uncovered — i.e. the change is
+   * harness/non-UI only (e.g. an edit to the gate logic or the producer config
+   * itself). In that case the producer captures ALL surfaces as a regression
+   * smoke so the route still produces real ARIA + after evidence and cannot be
+   * passed with zero captures (the harness-only bypass — symmetric to the
+   * false-positive hole).
+   */
+  smokeAllSurfaces: boolean;
+}
+
+/**
+ * Translate a glob (`**`, `*`, literal route-group `(group)` dirs) to a RegExp.
+ * `**` matches across `/`; `*` matches within a path segment. Anchored.
+ *
+ * Built by scanning the glob (no placeholder char) so `**` and `*` are expanded
+ * cleanly; everything else is regex-escaped — including the parentheses in
+ * Next.js route groups, which we want treated as literals.
+ */
+export function globToRegExp(glob: string): RegExp {
+  let pattern = "";
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i] as string;
+    if (ch === "*") {
+      if (glob[i + 1] === "*") {
+        pattern += ".*"; // ** → any chars including /
+        i++;
+      } else {
+        pattern += "[^/]*"; // * → any chars except /
+      }
+      continue;
+    }
+    pattern += ch.replace(/[.+^${}()|[\]\\]/, "\\$&"); // escape one metachar
+  }
+  return new RegExp(`^${pattern}$`);
+}
+
+export function matchesAny(path: string, globs: readonly string[]): boolean {
+  return globs.some((g) => globToRegExp(g).test(path));
+}
+
+/**
+ * Partition changed UI paths into the surfaces they arm and the paths that map
+ * to NO surface (the fail-closed set). `nonSurfaceGlobs` are harness / non-UI
+ * files that are exempt from the coverage requirement.
+ *
+ * Empty `changed` (e.g. a manual run with the env unset) arms every surface so
+ * the producer still captures evidence; the gate's real armed-by-diff semantics
+ * come from the changed-paths the route script computes.
+ */
+export function partitionChangedPaths(
+  changed: readonly string[],
+  surfaces: readonly UiSurface[],
+  nonSurfaceGlobs: readonly string[],
+): CoveragePartition {
+  if (changed.length === 0) {
+    // No changed-path signal (e.g. a manual run with the env unset) — arm all
+    // surfaces so the producer still captures evidence.
+    return { armed: [...surfaces], uncovered: [], smokeAllSurfaces: false };
+  }
+  const armed = new Set<UiSurface>();
+  const uncovered: string[] = [];
+  for (const path of changed) {
+    if (matchesAny(path, nonSurfaceGlobs)) continue; // harness/non-UI — skip.
+    const matched = surfaces.filter((s) => matchesAny(path, s.covers));
+    if (matched.length === 0) {
+      uncovered.push(path);
+      continue;
+    }
+    for (const s of matched) armed.add(s);
+  }
+  // Harness-only change (the route is armed by a web/** edit, but every changed
+  // path is a non-surface harness/config/gate-logic file): capture ALL surfaces
+  // as a regression smoke so the route NEVER passes with zero evidence. This
+  // closes the harness-only bypass — a change to the gate logic itself still
+  // produces real ARIA + after captures.
+  const smokeAllSurfaces = armed.size === 0 && uncovered.length === 0;
+  return {
+    armed: smokeAllSurfaces ? [...surfaces] : [...armed],
+    uncovered,
+    smokeAllSurfaces,
+  };
+}

package/skills/verify/producer/playwright-route.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# Reusable Evidence-Gated Validation **playwright (UI) route** producer command
+# (momentiq-ai/dark-factory#193). Generalized from the dark-factory-dashboard
+# dogfood (Cycle 21 PR-4).
+#
+# This is the `command` of the `playwright` route in
+# `.agent-review/config.json:validation.verificationRoutes`. The
+# @momentiq/dark-factory-cli route-runner (`df verify` / `df gate-push`) spawns
+# it with NO shell — the route command is `command.trim().split(/\s+/)` then
+# `spawn(argv[0], argv.slice(1))` — which is why the route command is the single
+# token-pair `bash scripts/verify/playwright-route.sh` and ALL the real work
+# (guards, Playwright, exit mapping) lives here.
+#
+# Exit-code contract (the 0/1/2 route contract):
+#   0 — green: evidence captured, the routed UI surface(s) rendered + asserted.
+#   1 — block: a routed UI surface failed to render/assert, OR a real producer
+#       error (Playwright crashed, a guarded file is dirty). Fail closed.
+#   2 — soft-skip: the producer cannot run HERE (Playwright not installed, or a
+#       required auth storage-state is configured but absent). Mapped by the CLI
+#       to `requiresHumanJudgment` — NOT a pass. We NEVER fabricate evidence.
+#
+# ── CONSUMER REFERENCE FILE — copy into your repo (e.g. scripts/verify/) and
+#    OWN it. Adjust the env knobs at the top to your repo layout. Then arm the
+#    `playwright` route's `command` to `bash <path-to-this-script>` in
+#    .agent-review/config.json. `df skills install verify` does NOT overwrite it.
+#
+# Usage (normally invoked by the route-runner via `df verify --route playwright`):
+#   bash scripts/verify/playwright-route.sh [--commit <ref>]
+
+set -uo pipefail
+
+EXIT_GREEN=0
+EXIT_BLOCK=1
+EXIT_SOFT_SKIP=2
+
+# --- consumer-tunable knobs (env overrides) --------------------------------
+# Directory where your web app + @playwright/test live (Playwright runs there).
+WEB_DIR="${DF_UI_ROUTE_WEB_DIR:-web}"
+# The producer config, relative to WEB_DIR.
+ROUTE_CONFIG="${DF_UI_ROUTE_CONFIG:-playwright.ui-route.config.ts}"
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "${REPO_ROOT}"
+
+# Path of THIS script relative to the repo root — added to the clean-tree guard
+# so a dirty producer (which would run DIFFERENT logic than the committed SHA)
+# fails closed too. Computed dynamically so it works wherever you copy it.
+SCRIPT_ABS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$(basename "${BASH_SOURCE[0]}")"
+SCRIPT_REL="${SCRIPT_ABS#"${REPO_ROOT}/"}"
+
+# --- resolve the SHA under review ------------------------------------------
+# Prefer DF_VERIFY_COMMIT (exported by a route orchestrator that pins the gated
+# commit), then an explicit --commit, then HEAD.
+SHA_REF="${DF_VERIFY_COMMIT:-HEAD}"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --commit) SHA_REF="${2:-HEAD}"; shift 2 ;;
+    --commit=*) SHA_REF="${1#*=}"; shift ;;
+    *) shift ;;
+  esac
+done
+SHA="$(git rev-parse "${SHA_REF}" 2>/dev/null || echo "")"
+if [[ -z "${SHA}" ]]; then
+  echo "[playwright-route] FAIL: could not resolve commit '${SHA_REF}'." >&2
+  exit "${EXIT_BLOCK}"
+fi
+
+# SHA-binding guard: the producer drives a browser against the CHECKED-OUT
+# working tree (HEAD), so it can only honestly attest evidence for HEAD. If
+# asked to produce evidence for a non-HEAD SHA, FAIL CLOSED rather than stamp a
+# passing record whose screenshots actually reflect HEAD.
+HEAD_SHA="$(git rev-parse HEAD 2>/dev/null || echo "")"
+if [[ "${SHA}" != "${HEAD_SHA}" ]]; then
+  echo "[playwright-route] BLOCK: asked to produce evidence for ${SHA:0:12} but HEAD is ${HEAD_SHA:0:12}." >&2
+  echo "[playwright-route] the producer validates the checked-out tree (HEAD) only; refusing to mis-bind evidence. Check out the target SHA and re-run." >&2
+  exit "${EXIT_BLOCK}"
+fi
+
+# Clean-tree guard: the producer screenshots the WORKING TREE, but evidence
+# binds to the committed SHA. If any file that affects either the rendered UI OR
+# the route's execution/evidence contract is dirty or untracked, the capture
+# would attest code that is NOT in ${SHA}. FAIL CLOSED. The guarded set is the
+# UI surface (web/** + *.tsx) AND the route machinery itself (this script + the
+# route config) — a dirty producer runs different logic than the committed SHA.
+GUARDED_PATHS=(
+  "${WEB_DIR}/**" '*.tsx'
+  "${SCRIPT_REL}"
+  '.agent-review/config.json'
+)
+if ! git diff-index --quiet HEAD -- "${GUARDED_PATHS[@]}" 2>/dev/null; then
+  echo "[playwright-route] BLOCK: tracked UI or route-machinery files are dirty (uncommitted changes)." >&2
+  echo "[playwright-route] the producer captures the working tree but evidence binds to ${SHA:0:12}; commit or stash changes under ${WEB_DIR}/**, *.tsx, ${SCRIPT_REL}, or .agent-review/config.json, then re-run." >&2
+  exit "${EXIT_BLOCK}"
+fi
+UNTRACKED_GUARDED="$(git ls-files --others --exclude-standard -- "${GUARDED_PATHS[@]}" 2>/dev/null | head -1 || true)"
+if [[ -n "${UNTRACKED_GUARDED}" ]]; then
+  echo "[playwright-route] BLOCK: untracked UI/route-machinery file(s) present (e.g. ${UNTRACKED_GUARDED}) not in ${SHA:0:12}." >&2
+  echo "[playwright-route] commit or remove untracked files under the guarded set so the capture matches the gated commit, then re-run." >&2
+  exit "${EXIT_BLOCK}"
+fi
+
+echo "[playwright-route] producing UI evidence for ${SHA:0:12} (ref=${SHA_REF}, =HEAD, clean tree)" >&2
+
+# Compute the UI paths this commit actually changed (parent..SHA), restricted to
+# the route's trigger surface (web/** + *.tsx). Handed to the producer so it can
+# FAIL CLOSED when a changed UI path has no mapped capture surface. Excludes
+# deletions (D) — a removed file has no surface to render.
+PARENT="$(git rev-parse "${SHA}^" 2>/dev/null || echo "")"
+if [[ -n "${PARENT}" ]]; then
+  CHANGED_UI_PATHS="$(git diff --name-only --diff-filter=ACMRT "${PARENT}" "${SHA}" -- "${WEB_DIR}/**" '*.tsx' 2>/dev/null || true)"
+else
+  # Root commit — list all tracked UI paths.
+  CHANGED_UI_PATHS="$(git ls-files -- "${WEB_DIR}/**" '*.tsx' 2>/dev/null || true)"
+fi
+export DF_UI_ROUTE_CHANGED_PATHS="${CHANGED_UI_PATHS}"
+
+# Anchor the evidence dir at the REPO ROOT (absolute), because Playwright runs
+# with cwd=${WEB_DIR} — a relative path would land under ${WEB_DIR}.
+OUT_DIR="${REPO_ROOT}/agent-reviews/quality-gates/ui/${SHA}"
+mkdir -p "${OUT_DIR}"
+export DF_UI_ROUTE_SHA="${SHA}"
+export DF_UI_ROUTE_OUT="${OUT_DIR}"
+
+# --- preflight: web tier present + Playwright installed --------------------
+if [[ ! -d "${WEB_DIR}/node_modules/@playwright" ]]; then
+  echo "[playwright-route] SOFT-SKIP: ${WEB_DIR}/ Playwright not installed (run \`cd ${WEB_DIR} && npm ci\`)." >&2
+  echo "[playwright-route] not fabricating evidence — requiresHumanJudgment." >&2
+  exit "${EXIT_SOFT_SKIP}"
+fi
+
+# --- auth storage-state gate (optional) ------------------------------------
+# Public surfaces need no auth. If you configured an auth storage-state
+# (DF_UI_ROUTE_STORAGE_STATE) but the file is absent (e.g. a cloud sandbox where
+# your auth harness could not mint it), SOFT-SKIP rather than pass — we will not
+# produce a protected-surface artifact we cannot legitimately authenticate.
+if [[ -n "${DF_UI_ROUTE_STORAGE_STATE:-}" && ! -f "${DF_UI_ROUTE_STORAGE_STATE}" ]]; then
+  echo "[playwright-route] SOFT-SKIP: DF_UI_ROUTE_STORAGE_STATE=${DF_UI_ROUTE_STORAGE_STATE} is set but the file is absent." >&2
+  echo "[playwright-route] cannot authenticate the configured session; not fabricating evidence (requiresHumanJudgment)." >&2
+  exit "${EXIT_SOFT_SKIP}"
+fi
+
+# --- run the producer -------------------------------------------------------
+LOG_FILE="$(mktemp -t df-playwright-route.XXXXXX)"
+trap 'rm -f "${LOG_FILE}"' EXIT
+
+set +e
+( cd "${WEB_DIR}" && npx playwright test --config "${ROUTE_CONFIG}" ) \
+  >"${LOG_FILE}" 2>&1
+RC=$?
+set -e 2>/dev/null || true
+
+# Surface the producer output (bounded) for the gate log / critic.
+tail -n 120 "${LOG_FILE}" >&2 || true
+
+if [[ ${RC} -eq 0 ]]; then
+  echo "[playwright-route] OK — evidence in ${OUT_DIR}" >&2
+  exit "${EXIT_GREEN}"
+fi
+
+echo "[playwright-route] BLOCK: producer failed (exit ${RC}) — see output above." >&2
+exit "${EXIT_BLOCK}"

package/skills/verify/producer/playwright.ui-route.config.ts

@@ -0,0 +1,111 @@
+import { defineConfig, devices } from "@playwright/test";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Reusable Playwright config for the Evidence-Gated Validation **playwright
+ * (UI) route producer** (momentiq-ai/dark-factory#193). Generalized from the
+ * dark-factory-dashboard dogfood (Cycle 21 PR-4; ADR 2026-06).
+ *
+ * Kept SEPARATE from your broad e2e config so the route producer is a single,
+ * fast, deterministic capture:
+ *   - one chromium project, the producer spec only.
+ *   - no retries (a flaky retry could mask a genuinely-failing UI surface).
+ *   - an OPTIONAL authenticated storage-state (public surfaces need none).
+ *   - an OPTIONAL local preview `webServer` (the SHA under review) for the
+ *     no-auth dogfood path; set `PLAYWRIGHT_TEST_BASE_URL` to point at a
+ *     deployed preview of the SHA instead.
+ *
+ * This config is invoked by `playwright-route.sh`, which is the route's
+ * `command` in `.agent-review/config.json`.
+ *
+ * ── CONSUMER REFERENCE FILE — copy into your repo (next to the producer spec)
+ *    and OWN it. Adjust `testDir`, the `webServer.command`, and the env knobs
+ *    to your repo's layout. `df skills install verify` does NOT overwrite it.
+ *
+ * NEVER set a routine pre-push bypass to get around a failing producer — a
+ * failing/absent capture MUST block the route (that is the feature).
+ */
+
+// Auth is OPTIONAL and consumer-supplied. Mint an authenticated Playwright
+// storageState JSON with YOUR auth (Clerk/Auth0/bot login/etc.) and point
+// DF_UI_ROUTE_STORAGE_STATE at it for protected surfaces. Public surfaces need
+// none — when the file is absent we run unauthenticated rather than fail.
+//
+// The default path is anchored to `process.cwd()` — NOT `__dirname` or
+// `import.meta.url`. Playwright may load this config as CJS or ESM depending on
+// the consumer's `"type"` + Playwright version: `__dirname` is undefined under
+// ESM and `import.meta` is invalid under CJS, so either module-global would
+// crash the producer for half of consumers before it could even soft-skip. The
+// route script runs Playwright with `cwd` = the web dir (where this config
+// lives), so cwd-relative resolves to `<web>/.auth/storage-state.json` and
+// works in both. Gitignore **/.auth/.
+const STORAGE_STATE_PATH =
+  process.env.DF_UI_ROUTE_STORAGE_STATE ||
+  resolve(process.cwd(), ".auth/storage-state.json");
+const storageState = existsSync(STORAGE_STATE_PATH) ? STORAGE_STATE_PATH : undefined;
+
+// Local preview port for the SHA-under-review server. Overridable via
+// DF_UI_ROUTE_PORT to avoid collisions with other local services.
+const PREVIEW_PORT = process.env.DF_UI_ROUTE_PORT || "3217";
+const BASE_URL =
+  process.env.PLAYWRIGHT_TEST_BASE_URL?.replace(/\/$/, "") ||
+  `http://localhost:${PREVIEW_PORT}`;
+
+// Only stand up the local preview server when we are NOT pointed at a remote
+// deployed surface. (A remote base URL means the SHA is already served.)
+const usingLocalPreview =
+  !process.env.PLAYWRIGHT_TEST_BASE_URL ||
+  /^https?:\/\/localhost(:|\/|$)/.test(process.env.PLAYWRIGHT_TEST_BASE_URL);
+
+// The command that serves the SHA under review for the local-preview path.
+// Default `npm run dev`; override via DF_UI_ROUTE_DEV_CMD for your stack.
+const DEV_CMD = process.env.DF_UI_ROUTE_DEV_CMD || "npm run dev";
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  // Only the route producer — not your broad e2e suite.
+  testMatch: /ui-route\.producer\.spec\.ts$/,
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  // The producer must be deterministic; no flaky retries that could mask a
+  // genuinely-failing UI surface behind a lucky re-run.
+  retries: 0,
+  workers: 1,
+  timeout: 90 * 1000,
+  expect: { timeout: 15 * 1000 },
+  reporter: [["list"]],
+
+  use: {
+    baseURL: BASE_URL,
+    // Authenticate ONLY when a storage-state file is present (protected
+    // surfaces). Public surfaces ignore it.
+    ...(storageState ? { storageState } : {}),
+    trace: "retain-on-failure",
+    screenshot: "only-on-failure",
+    ignoreHTTPSErrors: true,
+    actionTimeout: 15 * 1000,
+    navigationTimeout: 30 * 1000,
+  },
+
+  projects: [
+    {
+      name: "ui-route-producer",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+
+  webServer: usingLocalPreview
+    ? {
+        // Serve the SHA under review. Set the port via the PORT env var (the
+        // common convention); adjust DEV_CMD if your dev server differs.
+        command: DEV_CMD,
+        url: BASE_URL,
+        reuseExistingServer: !process.env.CI,
+        timeout: 120 * 1000,
+        env: {
+          PORT: PREVIEW_PORT,
+        },
+      }
+    : undefined,
+});