crewly 1.20.430 → 1.20.432

package/config/skills/agent/core/reproduce-ui/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: Reproduce UI
+description: Open a Crewly dashboard feature by its feature-map entry in a headless browser and save evidence (screenshot, console errors, failed requests, timings) before you reproduce or fix a UI bug report.
+version: 1.0.0
+category: development
+skillType: claude-skill
+assignableRoles:
+  - developer
+  - frontend-developer
+  - fullstack-dev
+  - qa
+  - qa-engineer
+  - team-leader
+  - orchestrator
+  - generalist
+triggers:
+  - reproduce
+  - screenshot bug
+  - UI bug
+  - feature map
+tags:
+  - frontend
+  - debugging
+  - evidence
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 180000
+---
+
+# Reproduce UI
+
+A bug report from the owner is often a phone screenshot and one sentence.
+Before you guess, open the feature the way a user does and keep the evidence.
+The feature map (`frontend/FEATURE_MAP.md` in a Crewly checkout, #811) says
+for every route how a user reaches it, what it should do and which
+`data-testid` anchors it has; this skill turns one map entry into a run.
+
+```bash
+# By route (tabs go in the query string, as the map shows them)
+bash execute.sh --route "/tickets?tab=runs"
+
+# By a word from the map's Routes table; :params get values
+bash execute.sh --feature "Run detail" --param id=<work item id>
+
+# Your own wait target and a full-page shot
+bash execute.sh --route /wiki --wait '[data-testid="wiki-recent-list"]' --full-page
+
+# See what would run (route, URL, wait selector, evidence folder) without a browser
+bash execute.sh --feature Usage --dry-run
+```
+
+What you get back is one JSON line with `dir`: the evidence folder under
+`$CREWLY_HOME/evidence/<utc stamp>-<route>/` holding `screenshot.png`,
+`console.json` (console errors, warnings and page errors), `requests.json`
+(failed requests and responses ≥ 400), `report.md` and `summary.json`.
+Exit 0 means the key element appeared; exit 2 means it did not (the
+evidence is still there — that is the bug, or the wrong selector); exit 1 is
+a usage or browser problem.
+
+How to use it on a report:
+
+1. Find the feature in the map (the words on the screenshot are usually in
+   a page's **Expected** or **Elements** line). Note its route and `?tab=`.
+2. Run this skill on that route. Compare `screenshot.png` with the owner's
+   screenshot; read `console.json` and `requests.json` first — a failed
+   `/api/...` call explains most blank or stale pages.
+3. Put the `report.md` path (or its key lines) in the ticket, then fix. After
+   the fix, run it again and attach the second folder as proof.
+
+Notes:
+
+- The dashboard must be running on this machine (`CREWLY_API_URL`, default
+  `http://localhost:8787`); loopback needs no token.
+- Needs Google Chrome (or `--browser <chromium path>`); playwright-core ships
+  with Crewly, no browser download.
+- `--feature` needs the map: a Crewly checkout at `CREWLY_PROJECT_PATH`, or
+  `--map <path>`. Without a map, pass `--route` and `--wait`.
+- Pages behind a Cloud sign-in or that need a real agent session show their
+  empty or signed-out state; that is still evidence, say so in the ticket.
+- For a page the owner is looking at in Chrome right now, or a site outside
+  this dashboard, use the `remote-browser` skill instead.

package/config/skills/agent/core/reproduce-ui/execute.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# =============================================================================
+# reproduce-ui — open a dashboard feature by its feature-map entry and save
+# evidence: screenshot, console errors, failed requests, timings (#811).
+#
+# Drives a headless Chrome with playwright-core (a Crewly dependency) against
+# the local dashboard. The feature map (frontend/FEATURE_MAP.md in a Crewly
+# checkout) supplies the route and the element to wait for; without it, pass
+# --route and --wait.
+# =============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+# config/skills/agent/core/<skill> → the Crewly package root (repo or npm install)
+PKG_ROOT="$(cd "${SCRIPT_DIR}/../../../../.." && pwd)"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  bash execute.sh --route /tickets?tab=runs                 Open a route, wait for its key element, save evidence
+  bash execute.sh --feature "Run detail" --param id=<uuid>   Resolve the route from the feature map
+  bash execute.sh --route /wiki --wait '[data-testid="wiki-recent-list"]' --full-page
+
+Options:
+  --route      Path to open (with ?tab= when the page has tabs)
+  --feature    A route or a word from a Routes row of FEATURE_MAP.md (needs the map)
+  --param k=v  Value for a :param in the route (repeatable)
+  --wait       CSS selector to wait for (default: the feature's first data-testid, else body)
+  --map        FEATURE_MAP.md path (default: <project>/frontend/FEATURE_MAP.md when present)
+  --base-url   Dashboard origin (default: CREWLY_API_URL)
+  --out        Evidence root (default: $CREWLY_HOME/evidence)
+  --timeout    Milliseconds to wait for navigation and for the element (default 60000)
+  --full-page  Full-page screenshot
+  --browser    Chrome/Chromium executable (default: the installed Google Chrome)
+  --dry-run    Print the resolved plan, open nothing
+  --help | -h  Show this help
+
+Output: one JSON line with the evidence folder (screenshot.png, console.json,
+requests.json, report.md, summary.json). Exit 0 when the element appeared, 2
+when it did not (evidence still saved), 1 on a usage or browser error.
+EOF_USAGE
+}
+
+ROUTE=""; FEATURE=""; WAIT=""; MAP=""; BASE_URL=""; OUT=""; TIMEOUT=""; FULL_PAGE=""; BROWSER=""; DRY_RUN=""
+PARAMS=()
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  ROUTE=$(printf '%s' "$1" | jq -r '.route // empty')
+  FEATURE=$(printf '%s' "$1" | jq -r '.feature // empty')
+  WAIT=$(printf '%s' "$1" | jq -r '.wait // empty')
+  MAP=$(printf '%s' "$1" | jq -r '.map // empty')
+  BASE_URL=$(printf '%s' "$1" | jq -r '.baseUrl // empty')
+  OUT=$(printf '%s' "$1" | jq -r '.out // empty')
+  TIMEOUT=$(printf '%s' "$1" | jq -r '.timeout // empty')
+  FULL_PAGE=$(printf '%s' "$1" | jq -r 'if .fullPage == true then "1" else empty end')
+  DRY_RUN=$(printf '%s' "$1" | jq -r 'if .dryRun == true then "1" else empty end')
+  while IFS= read -r kv; do [ -n "$kv" ] && PARAMS+=("$kv"); done < <(printf '%s' "$1" | jq -r '(.params // {}) | to_entries[] | "\(.key)=\(.value)"')
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --route)     [ $# -ge 2 ] || error_exit "--route requires a value";    ROUTE="$2";    shift 2 ;;
+    --feature)   [ $# -ge 2 ] || error_exit "--feature requires a value";  FEATURE="$2";  shift 2 ;;
+    --param)     [ $# -ge 2 ] || error_exit "--param requires k=v";        PARAMS+=("$2"); shift 2 ;;
+    --wait)      [ $# -ge 2 ] || error_exit "--wait requires a selector";  WAIT="$2";     shift 2 ;;
+    --map)       [ $# -ge 2 ] || error_exit "--map requires a path";       MAP="$2";      shift 2 ;;
+    --base-url)  [ $# -ge 2 ] || error_exit "--base-url requires a value"; BASE_URL="$2"; shift 2 ;;
+    --out)       [ $# -ge 2 ] || error_exit "--out requires a path";       OUT="$2";      shift 2 ;;
+    --timeout)   [ $# -ge 2 ] || error_exit "--timeout requires ms";       TIMEOUT="$2";  shift 2 ;;
+    --browser)   [ $# -ge 2 ] || error_exit "--browser requires a path";   BROWSER="$2";  shift 2 ;;
+    --full-page) FULL_PAGE="1"; shift ;;
+    --dry-run)   DRY_RUN="1"; shift ;;
+    --help|-h)   print_usage; exit 0 ;;
+    *) unknown_arg_exit "$1" ;;
+  esac
+done
+
+[ -n "$ROUTE" ] || [ -n "$FEATURE" ] || error_exit "one of --route or --feature is required (--help for usage)"
+command -v node >/dev/null 2>&1 || error_exit "node is required"
+
+# The map: explicit, else the project's checkout, else the package's own copy (a repo install).
+if [ -z "$MAP" ]; then
+  for cand in "${CREWLY_PROJECT_PATH:-$PWD}/frontend/FEATURE_MAP.md" "${PKG_ROOT}/frontend/FEATURE_MAP.md"; do
+    if [ -f "$cand" ]; then MAP="$cand"; break; fi
+  done
+fi
+
+for kv in "${PARAMS[@]+"${PARAMS[@]}"}"; do
+  [[ "$kv" == *=* ]] || error_exit "--param needs k=v, got: $kv"
+  key="${kv%%=*}"; val="${kv#*=}"
+  [[ "$key" =~ ^[A-Za-z_]+$ ]] || error_exit "--param name must be a word: $key"
+  export "RU_PARAM_${key}=${val}"
+done
+
+RU_MAIN=1 RU_ROUTE="$ROUTE" RU_FEATURE="$FEATURE" RU_WAIT="$WAIT" RU_MAP="$MAP" RU_BASE_URL="$BASE_URL" \
+RU_OUT="$OUT" RU_TIMEOUT_MS="$TIMEOUT" RU_FULL_PAGE="$FULL_PAGE" RU_BROWSER="$BROWSER" RU_DRY_RUN="$DRY_RUN" \
+RU_PKG_ROOT="$PKG_ROOT" node "${SCRIPT_DIR}/reproduce.mjs"

package/config/skills/agent/core/reproduce-ui/execute.test.sh

@@ -0,0 +1,123 @@
+#!/bin/bash
+# Tests for reproduce-ui — run with: bash execute.test.sh
+# Offline: a fixture feature map, --dry-run only (no browser is started).
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+PASS=0; FAIL=0
+check() {
+  local name="$1"; local got="$2"; local want="$3"
+  if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+
+T="$(mktemp -d)"; trap 'rm -rf "$T"' EXIT
+MAP="$T/FEATURE_MAP.md"
+cat > "$MAP" <<'EOF_MAP'
+# Feature map
+
+## Routes
+
+| Route | Page | Reached from | One job |
+| --- | --- | --- | --- |
+| `/` | `src/pages/Dashboard.tsx` | sidebar Dashboard | What needs me |
+| `/tickets` | `src/pages/hubs/TicketsHub.tsx` | sidebar Tickets | Board · Requests · Runs tabs |
+| `/tickets/runs/:id` | `src/pages/WorkItemDetail.tsx` | Tickets › Runs row | One run (work item) |
+| `/usage` | `src/pages/Usage.tsx` | sidebar Usage | Tokens by team |
+
+## Old URLs
+
+| Old URL | Goes to |
+| --- | --- |
+| `/workitems` | `/tickets?tab=runs` |
+
+## Features
+
+### Dashboard (`/`)
+
+- **Elements**: `dashboard`, `crew-now`.
+
+### Tickets hub (`/tickets`, tabs `board` · `runs`)
+
+- **Elements**: `tickets-panel-${tab}`, `tickets-page`, `tickets-board`.
+
+### Run detail (`/tickets/runs/:id`)
+
+- **Elements**: `workitem-detail-loading|error|not-found`, `workitem-detail`.
+
+### Usage (`/usage`)
+
+- **Expected**: one headline.
+EOF_MAP
+export CREWLY_API_URL="http://127.0.0.1:18799"
+export CREWLY_HOME="$T/home"
+
+# ---- help ----
+OUT=$(bash "$EXEC" --help 2>&1); RC=$?
+check "help exits 0" "$RC" "0"
+check "help names --feature" "$(printf '%s' "$OUT" | grep -c -- '--feature')" "$(printf '%s' "$OUT" | grep -c -- '--feature')"
+[ "$(printf '%s' "$OUT" | grep -c -- '--feature')" -ge 1 ] || { FAIL=$((FAIL+1)); echo "FAIL: help lacks --feature"; }
+
+# ---- no route / feature ----
+ERR=$(bash "$EXEC" --dry-run 2>&1 >/dev/null); RC=$?
+check "no route: exit 1" "$RC" "1"
+check "no route: error says so" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'route or --feature')" "1"
+
+# ---- route + map: wait selector from the Elements line; ${} and a|b skipped ----
+OUT=$(bash "$EXEC" --route "/tickets?tab=runs" --map "$MAP" --dry-run)
+check "route: dryRun" "$(printf '%s' "$OUT" | jq -r .dryRun)" "true"
+check "route: url" "$(printf '%s' "$OUT" | jq -r .url)" "http://127.0.0.1:18799/tickets?tab=runs"
+check "route: wait = the tab's panel" "$(printf '%s' "$OUT" | jq -r .waitFor)" '[data-testid="tickets-panel-runs"]'
+check "route without tab: first static id" "$(bash "$EXEC" --route /tickets --map "$MAP" --dry-run | jq -r .waitFor)" '[data-testid="tickets-page"]'
+check "route: waitSource map" "$(printf '%s' "$OUT" | jq -r .waitSource)" "map"
+check "route: feature job from the row" "$(printf '%s' "$OUT" | jq -r .feature.job)" "Board · Requests · Runs tabs"
+check "route: evidence root under CREWLY_HOME" "$(printf '%s' "$OUT" | jq -r .outRoot)" "$T/home/evidence"
+
+OUT=$(bash "$EXEC" --route "/tickets/runs/abc" --map "$MAP" --dry-run)
+check "run detail literal id: alternatives skipped" "$(printf '%s' "$OUT" | jq -r .waitFor)" '[data-testid="workitem-detail"]'
+
+# ---- feature word → route; :id from --param ----
+OUT=$(bash "$EXEC" --feature "One run" --param id=wi-9 --map "$MAP" --dry-run)
+check "feature: route resolved" "$(printf '%s' "$OUT" | jq -r .route)" "/tickets/runs/:id"
+check "feature: param filled" "$(printf '%s' "$OUT" | jq -r .path)" "/tickets/runs/wi-9"
+
+ERR=$(bash "$EXEC" --feature "One run" --map "$MAP" --dry-run 2>&1 >/dev/null); RC=$?
+check "feature without param: exit 1" "$RC" "1"
+check "feature without param: names it" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'param id')" "1"
+
+OUT=$(bash "$EXEC" --feature "/usage" --map "$MAP" --dry-run)
+check "exact route as feature" "$(printf '%s' "$OUT" | jq -r .path)" "/usage"
+check "no Elements line → body" "$(printf '%s' "$OUT" | jq -r .waitFor)" "body"
+check "waitSource default" "$(printf '%s' "$OUT" | jq -r .waitSource)" "default"
+
+ERR=$(bash "$EXEC" --feature "tickets" --map "$MAP" --dry-run 2>&1 >/dev/null); RC=$?
+check "ambiguous feature: exit 1" "$RC" "1"
+check "ambiguous feature: lists candidates" "$(printf '%s' "$ERR" | jq -r .error | grep -c '/tickets/runs/:id')" "1"
+
+ERR=$(bash "$EXEC" --feature "nothing-like-this" --map "$MAP" --dry-run 2>&1 >/dev/null); RC=$?
+check "unknown feature: exit 1" "$RC" "1"
+check "unknown feature: says no row" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'no feature-map row')" "1"
+
+ERR=$(bash "$EXEC" --feature "Usage" --map "$T/missing.md" --dry-run 2>&1 >/dev/null); RC=$?
+check "feature without map: exit 1" "$RC" "1"
+check "feature without map: explains" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'needs the feature map')" "1"
+
+# ---- explicit wait, base url, timeout, full page, JSON input ----
+OUT=$(bash "$EXEC" --route /x --wait '#main' --base-url http://localhost:9999/ --timeout 500 --full-page --dry-run)
+check "explicit wait" "$(printf '%s' "$OUT" | jq -r .waitFor)" "#main"
+check "waitSource arg" "$(printf '%s' "$OUT" | jq -r .waitSource)" "arg"
+check "base url trailing slash trimmed" "$(printf '%s' "$OUT" | jq -r .url)" "http://localhost:9999/x"
+check "timeout" "$(printf '%s' "$OUT" | jq -r .timeoutMs)" "500"
+check "full page" "$(printf '%s' "$OUT" | jq -r .fullPage)" "true"
+
+OUT=$(bash "$EXEC" '{"route":"/usage","map":"'"$MAP"'","dryRun":true,"params":{"id":"1"},"fullPage":true}')
+check "json input: route" "$(printf '%s' "$OUT" | jq -r .path)" "/usage"
+check "json input: fullPage" "$(printf '%s' "$OUT" | jq -r .fullPage)" "true"
+
+ERR=$(bash "$EXEC" --route relative --dry-run 2>&1 >/dev/null); RC=$?
+check "route must start with /" "$(printf '%s' "$ERR" | jq -r .error | grep -c 'must start with /')" "1"
+
+ERR=$(bash "$EXEC" --route /x --bogus 2>&1 >/dev/null); RC=$?
+check "unknown arg: exit 2" "$RC" "2"
+
+echo "reproduce-ui: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/config/skills/agent/core/reproduce-ui/reproduce.mjs

@@ -0,0 +1,366 @@
+/**
+ * reproduce-ui — open a dashboard feature by its feature-map entry and save
+ * evidence (#811 slice 2, specs/2026-10-26-feature-map.md).
+ *
+ * Driven by execute.sh through environment variables:
+ *   RU_ROUTE      route to open, e.g. `/tickets?tab=runs` (or RU_FEATURE)
+ *   RU_FEATURE    a word of a Routes row of the map, resolved to its route
+ *   RU_WAIT       CSS selector to wait for; default = the first data-testid
+ *                 of the feature's Elements line in the map, else `body`
+ *   RU_MAP        path of FEATURE_MAP.md (optional; lookups need it)
+ *   RU_BASE_URL   dashboard origin, default CREWLY_API_URL
+ *   RU_OUT        evidence root, default $CREWLY_HOME/evidence
+ *   RU_TIMEOUT_MS how long to wait for the element (default 60000)
+ *   RU_FULL_PAGE  "1" = full-page screenshot
+ *   RU_BROWSER    path of a Chromium/Chrome executable (default: installed Chrome)
+ *   RU_DRY_RUN    "1" = print the resolved plan as JSON and exit (no browser)
+ *   RU_PKG_ROOT   Crewly package root (where playwright-core resolves from)
+ *
+ * Output: one JSON line on stdout — the plan (dry run) or the summary with the
+ * evidence folder. Exit 0 when the element appeared, 2 when it did not (the
+ * evidence is still written), 1 on a usage or launch error.
+ */
+
+import { createRequire } from 'node:module';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const env = process.env;
+
+/**
+ * How long to wait for navigation and for the element. The dashboard bundle
+ * takes 20–40 s to render on a loaded machine (headless Chrome shares the
+ * CPU with the agents), so a short default would report bugs that are not.
+ */
+const DEFAULT_TIMEOUT_MS = 60000;
+
+/**
+ * Print a JSON error and exit.
+ *
+ * @param {string} message - What went wrong
+ * @param {number} [code] - Exit code
+ */
+function fail(message, code = 1) {
+	process.stderr.write(`${JSON.stringify({ ok: false, error: message })}\n`);
+	process.exit(code);
+}
+
+/**
+ * The text of one `## ` section of a markdown document.
+ *
+ * @param {string} markdown - The document
+ * @param {string} heading - The exact heading line
+ * @returns {string} The section body, '' when absent
+ */
+export function markdownSection(markdown, heading) {
+	const lines = markdown.split('\n');
+	const start = lines.findIndex((l) => l.trim() === heading);
+	if (start < 0) return '';
+	const rest = lines.slice(start + 1);
+	const end = rest.findIndex((l) => /^## /.test(l));
+	return (end < 0 ? rest : rest.slice(0, end)).join('\n');
+}
+
+/**
+ * The rows of the map's Routes table.
+ *
+ * @param {string} markdown - FEATURE_MAP.md
+ * @returns {Array<{route: string, page: string, reach: string, job: string}>}
+ */
+export function routeRows(markdown) {
+	const rows = [];
+	for (const line of markdownSection(markdown, '## Routes').split('\n')) {
+		const cells = line.trim().split('|').map((c) => c.trim());
+		// A table row is `| a | b | c | d |` → ['', a, b, c, d, '']
+		if (cells.length < 5 || !/^`\/.*`$/.test(cells[1])) continue;
+		rows.push({ route: cells[1].replace(/`/g, ''), page: cells[2].replace(/`/g, ''), reach: cells[3], job: cells[4] ?? '' });
+	}
+	return rows;
+}
+
+/**
+ * Resolve a feature word to one Routes row: an exact route, else the only
+ * row whose route, page, reach or job contains the word (case-insensitive).
+ *
+ * @param {string} markdown - FEATURE_MAP.md
+ * @param {string} feature - Route or word
+ * @returns {{row?: object, candidates?: string[], error?: string}}
+ */
+export function resolveFeature(markdown, feature) {
+	const rows = routeRows(markdown);
+	const exact = rows.find((r) => r.route === feature);
+	if (exact) return { row: exact };
+	const needle = feature.toLowerCase();
+	const hits = rows.filter((r) => [r.route, r.page, r.reach, r.job].some((c) => c.toLowerCase().includes(needle)));
+	if (hits.length === 1) return { row: hits[0] };
+	if (hits.length === 0) return { error: `no feature-map row matches "${feature}"`, candidates: rows.map((r) => r.route) };
+	return { error: `"${feature}" matches several routes; pass --route`, candidates: hits.map((r) => r.route) };
+}
+
+/**
+ * The data-testid to wait for on a route, from the Features section that
+ * mentions it (its `**Elements**` line), as a CSS selector.
+ *
+ * A page with tabs lists its panel as `x-panel-${tab}`; with a `tab` the
+ * placeholder is filled (`tickets-panel-runs`), which is the element that
+ * proves the right tab rendered. Otherwise the first static id wins: `${…}`
+ * ids are per-item, `a|b` lists variants, neither is one selector.
+ *
+ * @param {string} markdown - FEATURE_MAP.md
+ * @param {string} route - Route pattern, e.g. `/tickets/runs/:id`
+ * @param {string} [tab] - The `?tab=` value of the opened path
+ * @returns {string|null} `[data-testid="x"]`, or null when none fits
+ */
+export function defaultWaitSelector(markdown, route, tab) {
+	const features = markdownSection(markdown, '## Features');
+	const blocks = features.split(/\n(?=### )/);
+	const block = blocks.find((b) => b.split('\n')[0].includes(`\`${route}\``));
+	if (!block) return null;
+	const elements = block.split('\n').find((l) => l.includes('**Elements**'));
+	if (!elements) return null;
+	const ids = [...elements.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+	if (tab) {
+		const panel = ids.find((id) => id.includes('${tab}'));
+		if (panel) return `[data-testid="${panel.replace('${tab}', tab)}"]`;
+	}
+	for (const id of ids) {
+		if (id.includes('$') || id.includes('|') || /\s/.test(id)) continue;
+		return `[data-testid="${id}"]`;
+	}
+	return null;
+}
+
+/**
+ * The Routes row whose pattern matches an opened path (`/tickets/runs/abc`
+ * → `/tickets/runs/:id`); an exact match wins, the query string is ignored.
+ *
+ * @param {Array<{route: string}>} rows - From {@link routeRows}
+ * @param {string} path - Route or path, with or without `?tab=`
+ * @returns {object|null} The row, or null
+ */
+export function matchRouteRow(rows, path) {
+	const bare = path.split('?')[0].split('#')[0];
+	const exact = rows.find((r) => r.route === bare);
+	if (exact) return exact;
+	return (
+		rows.find((r) => {
+			const re = new RegExp(`^${r.route.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/:[A-Za-z_]+/g, '[^/]+')}$`);
+			return re.test(bare);
+		}) ?? null
+	);
+}
+
+/**
+ * Turn a route pattern into an openable path: `:id` params need values.
+ *
+ * @param {string} route - Route or pattern
+ * @param {Record<string,string>} params - RU_PARAM_<name> values
+ * @returns {{path: string, missing: string[]}}
+ */
+export function fillRoute(route, params) {
+	const missing = [];
+	const path = route.replace(/:([A-Za-z_]+)/g, (_, name) => {
+		const v = params[name];
+		if (v === undefined) missing.push(name);
+		return v === undefined ? `:${name}` : encodeURIComponent(v);
+	});
+	return { path, missing };
+}
+
+/**
+ * A folder name for one run: `<utc-stamp>-<route slug>`.
+ *
+ * @param {string} route - The opened path
+ * @param {Date} now - Clock
+ * @returns {string}
+ */
+export function runFolderName(route, now) {
+	const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+	const slug = route.replace(/^\//, '').replace(/[^A-Za-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'home';
+	return `${stamp}-${slug.slice(0, 60)}`;
+}
+
+/**
+ * The run plan from the environment (pure apart from reading the map file).
+ *
+ * @returns {object} plan
+ */
+export function buildPlan() {
+	const mapPath = env.RU_MAP && existsSync(env.RU_MAP) ? env.RU_MAP : null;
+	const map = mapPath ? readFileSync(mapPath, 'utf8') : null;
+	let route = env.RU_ROUTE || '';
+	let row = null;
+	if (!route && env.RU_FEATURE) {
+		if (!map) fail(`--feature needs the feature map; pass --map or --route (looked for ${env.RU_MAP || 'FEATURE_MAP.md'})`);
+		const r = resolveFeature(map, env.RU_FEATURE);
+		if (r.error) fail(`${r.error}${r.candidates?.length ? ` (routes: ${r.candidates.join(', ')})` : ''}`);
+		row = r.row;
+		route = row.route;
+	} else if (route && map) {
+		row = matchRouteRow(routeRows(map), route);
+	}
+	if (!route) fail('one of --route or --feature is required');
+	if (!route.startsWith('/')) fail('--route must start with /');
+	const params = {};
+	for (const [k, v] of Object.entries(env)) if (k.startsWith('RU_PARAM_') && v) params[k.slice('RU_PARAM_'.length)] = v;
+	const { path, missing } = fillRoute(route, params);
+	if (missing.length) fail(`route ${route} needs a value for ${missing.map((m) => `--param ${m}=…`).join(', ')}`);
+	const mapRoute = row?.route ?? route.split('?')[0];
+	const tab = /[?&]tab=([^&#]+)/.exec(route)?.[1];
+	const waitFor = env.RU_WAIT || (map ? defaultWaitSelector(map, mapRoute, tab ? decodeURIComponent(tab) : undefined) : null) || 'body';
+	const baseUrl = (env.RU_BASE_URL || env.CREWLY_API_URL || `http://localhost:${env.WEB_PORT || 8787}`).replace(/\/+$/, '');
+	const outRoot = env.RU_OUT || join(env.CREWLY_HOME || join(homedir(), '.crewly'), 'evidence');
+	return {
+		route,
+		path,
+		url: `${baseUrl}${path}`,
+		waitFor,
+		waitSource: env.RU_WAIT ? 'arg' : waitFor === 'body' ? 'default' : 'map',
+		timeoutMs: Number(env.RU_TIMEOUT_MS) > 0 ? Number(env.RU_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS,
+		fullPage: env.RU_FULL_PAGE === '1',
+		map: mapPath,
+		feature: row ? { page: row.page, reach: row.reach, job: row.job } : null,
+		outRoot,
+	};
+}
+
+/**
+ * Load playwright-core from the Crewly package.
+ *
+ * @returns {import('playwright-core')}
+ */
+function loadPlaywright() {
+	const root = env.RU_PKG_ROOT || resolve(process.cwd());
+	try {
+		const req = createRequire(join(root, 'package.json'));
+		return req('playwright-core');
+	} catch (e) {
+		fail(`playwright-core is not available under ${root} (${e instanceof Error ? e.message : String(e)})`);
+	}
+}
+
+/**
+ * Run the plan in a headless browser and write the evidence.
+ *
+ * @param {object} plan - From {@link buildPlan}
+ * @returns {Promise<number>} Exit code
+ */
+async function run(plan) {
+	const started = Date.now();
+	const debug = (m) => {
+		if (env.RU_DEBUG === '1') process.stderr.write(`[reproduce-ui +${Date.now() - started}ms] ${m}\n`);
+	};
+	const pw = loadPlaywright();
+	const dir = join(plan.outRoot, runFolderName(plan.path, new Date()));
+	mkdirSync(dir, { recursive: true });
+	const launch = plan.browser ? { executablePath: plan.browser } : { channel: 'chrome' };
+	let browser;
+	try {
+		browser = await pw.chromium.launch({ headless: true, ...launch });
+	} catch (e) {
+		fail(`could not start a browser (${e instanceof Error ? e.message.split('\n')[0] : String(e)}); install Google Chrome or pass --browser <path>`);
+	}
+	debug('browser launched');
+	const console_ = [];
+	const requests = [];
+	const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+	page.on('console', (m) => {
+		if (m.type() === 'error' || m.type() === 'warning') console_.push({ type: m.type(), text: m.text().slice(0, 500), at: Date.now() });
+	});
+	page.on('pageerror', (e) => console_.push({ type: 'pageerror', text: String(e.message ?? e).slice(0, 500), at: Date.now() }));
+	page.on('requestfailed', (r) => requests.push({ url: r.url(), method: r.method(), failure: r.failure()?.errorText ?? 'failed' }));
+	page.on('response', (r) => {
+		if (r.status() >= 400) requests.push({ url: r.url(), method: r.request().method(), status: r.status() });
+	});
+	const t0 = Date.now();
+	let navMs = null;
+	let waitMs = null;
+	let found = false;
+	let navError = null;
+	try {
+		await page.goto(plan.url, { waitUntil: 'domcontentloaded', timeout: plan.timeoutMs });
+		navMs = Date.now() - t0;
+		debug(`navigated in ${navMs}ms`);
+		const t1 = Date.now();
+		await page.waitForSelector(plan.waitFor, { state: 'visible', timeout: plan.timeoutMs });
+		waitMs = Date.now() - t1;
+		found = true;
+		debug(`element in ${waitMs}ms`);
+		await page.waitForLoadState('networkidle', { timeout: 5000 }).catch(() => {});
+	} catch (e) {
+		navError = e instanceof Error ? e.message.split('\n')[0] : String(e);
+		debug(`stopped: ${navError}`);
+	}
+	const screenshot = join(dir, 'screenshot.png');
+	try {
+		await page.screenshot({ path: screenshot, fullPage: plan.fullPage, timeout: plan.timeoutMs });
+	} catch {
+		// A page that never rendered has nothing to shoot; the report says so.
+	}
+	debug('screenshot taken');
+	const title = await page.title().catch(() => '');
+	const finalUrl = page.url();
+	await browser.close();
+	debug('browser closed');
+
+	const summary = {
+		ok: found,
+		route: plan.route,
+		url: plan.url,
+		finalUrl,
+		title,
+		waitFor: plan.waitFor,
+		waitSource: plan.waitSource,
+		found,
+		error: navError,
+		timings: { navigationMs: navMs, elementMs: waitMs, totalMs: Date.now() - t0 },
+		consoleErrors: console_.length,
+		failedRequests: requests.length,
+		dir,
+		screenshot: existsSync(screenshot) ? screenshot : null,
+		feature: plan.feature,
+	};
+	writeFileSync(join(dir, 'console.json'), `${JSON.stringify(console_, null, 2)}\n`);
+	writeFileSync(join(dir, 'requests.json'), `${JSON.stringify(requests, null, 2)}\n`);
+	writeFileSync(join(dir, 'summary.json'), `${JSON.stringify(summary, null, 2)}\n`);
+	writeFileSync(join(dir, 'report.md'), renderReport(summary, console_, requests));
+	process.stdout.write(`${JSON.stringify(summary)}\n`);
+	return found ? 0 : 2;
+}
+
+/**
+ * The human-readable report of one run.
+ *
+ * @param {object} s - Summary
+ * @param {Array<object>} console_ - Console errors
+ * @param {Array<object>} requests - Failed requests
+ * @returns {string} Markdown
+ */
+export function renderReport(s, console_, requests) {
+	const lines = [
+		`# Reproduce: ${s.route}`,
+		'',
+		`- URL: ${s.url}${s.finalUrl && s.finalUrl !== s.url ? ` → ${s.finalUrl}` : ''}`,
+		`- Title: ${s.title || '(none)'}`,
+		`- Waited for: \`${s.waitFor}\` (${s.waitSource}) — ${s.found ? 'appeared' : `NOT found${s.error ? `: ${s.error}` : ''}`}`,
+		`- Timings: navigation ${s.timings.navigationMs ?? '–'} ms, element ${s.timings.elementMs ?? '–'} ms, total ${s.timings.totalMs} ms`,
+		`- Screenshot: ${s.screenshot ? 'screenshot.png' : '(none)'}`,
+	];
+	if (s.feature) lines.push(`- Feature: ${s.feature.job} — reached from ${s.feature.reach}; page \`${s.feature.page}\``);
+	lines.push('', `## Console errors (${console_.length})`, '');
+	lines.push(...(console_.length ? console_.map((c) => `- [${c.type}] ${c.text}`) : ['- none']));
+	lines.push('', `## Failed requests (${requests.length})`, '');
+	lines.push(...(requests.length ? requests.map((r) => `- ${r.method} ${r.url} → ${r.status ?? r.failure}`) : ['- none']));
+	return `${lines.join('\n')}\n`;
+}
+
+if (env.RU_MAIN === '1') {
+	const plan = buildPlan();
+	plan.browser = env.RU_BROWSER || null;
+	if (env.RU_DRY_RUN === '1') {
+		process.stdout.write(`${JSON.stringify({ ok: true, dryRun: true, ...plan })}\n`);
+	} else {
+		run(plan).then((code) => process.exit(code));
+	}
+}