/capture

name: capture
version: 0.5.0
description: >
  Captures HTTP traffic from a web app using playwright-cli — site fingerprinting
  (framework, protections, auth, API discovery) plus full traffic recording into
  raw-traffic.json. Use as Phase 1 of CLI generation whenever a target URL needs
  its API surface recorded or assessed.
when_to_use: >
  Trigger phrases: "record traffic from", "capture API calls from", "start Phase 1",
  "analyze traffic from URL", "assess site", "site fingerprint", "open browser for",
  or any URL given as the first step of CLI generation. Not for Phase 2
  implementation, test writing, or quality validation.

Traffic Capture (Phase 1)

Assess the site, then capture comprehensive HTTP traffic. This skill combines site assessment with full traffic recording in a single browser session.

Copy this checklist and check off items as you complete them:

Phase 1 Progress:
- [ ] Prerequisites: playwright-cli available, checkpoint restored if one exists
- [ ] Step 1: Browser open on target URL
- [ ] Step 2: Fingerprint run + auth handled + profile classified + assessment.md written
- [ ] Step 3: Full capture — exploration targets met for the profile
- [ ] Step 4: Trace parsed, validate-capture.py PASSED (the gate)
- [ ] Step 5: Browser closed, checkpoint + phase-state marked complete

---

CRITICAL EXECUTION RULES

> **NEVER use `run_in_background: true` for ANY playwright-cli command.** > All playwright-cli commands must run in the foreground with appropriate timeouts. > Background execution causes task ID tracking failures — the command completes > before you can read the output. See `references/playwright-cli-commands.md` > for the timeout table.

> **NEVER use `eval` for complex expressions.** `eval` fails silently on ternaries, > comma operators, and multi-branch logic with "not well-serializable" errors. > Use `run-code` instead. See `references/framework-detection.md` for details.

> **ESM context — no `require()`.** `run-code` uses ESM. Use `await import('fs')` > instead of `require('fs')`. See `references/playwright-cli-commands.md`.

---

Prerequisites (Hard Gate)

Do NOT start unless:

• [ ] playwright-cli is available (`npx @playwright/cli@latest --version`)
• [ ] Target URL is known

**Default capture method:** playwright-cli tracing (standard workflow below).

Optional `--mitmproxy` mode

When the `--mitmproxy` flag was passed to `/cli-anything-web` (or the capture needs untruncated bodies / enhanced metadata), follow this workflow with the step substitutions in `references/mitmproxy-mode.md` — Steps 1, 3, and 4 differ; everything else is identical. When playwright-cli itself is unavailable (e.g., no Node), fall back to chrome-devtools-mcp via `launch-chrome-debug.sh` — see HARNESS.md Tool Hierarchy.

Public API Shortcut

If the target site has a **documented public REST/JSON API** (e.g., Hacker News Firebase API, Dev.to API, Reddit API, Wikipedia API), browser capture is optional:

1. Probe the API endpoints directly with `httpx` or `curl` 2. Save responses as `<app>/traffic-capture/raw-traffic.json` 3. Skip to Phase 2 (methodology)

This applies when:

• API docs exist (OpenAPI/Swagger, developer docs page, `/api/` prefix)
• The API is publicly accessible without browser-specific auth
• Endpoints return JSON (not HTML)

If unsure whether a public API exists, proceed with browser capture as normal.

Resume from Checkpoint

Before starting, check if a previous capture session exists:

python ${CLAUDE_PLUGIN_ROOT}/scripts/capture-checkpoint.py restore <app>

If a checkpoint exists, read the `guidance` field and **resume from the last completed step** instead of starting over. This prevents duplicate work when sessions are interrupted.

---

Step 1: Setup

# Create output directory
mkdir -p <app>/traffic-capture

# Clear any stale sessions
npx @playwright/cli@latest kill-all 2>/dev/null || true

npx @playwright/cli@latest -s=<app> open <url> --headed --persistent
# Note: heavy SPAs (Next.js, React) may show "TimeoutError: page._snapshotForAI" on open.
# This is non-fatal — verify with: npx @playwright/cli@latest list
#
# IMPORTANT — "Browser opened with pid..." in command output means the daemon
# RE-ATTACHED to the existing browser, NOT that a new session was created.
# Do NOT re-navigate or restart when you see this. The session is still open.

> **`--mitmproxy` mode:** use the Step 1 substitution in > `references/mitmproxy-mode.md` (start the proxy, then open through it).

**Do NOT ask the user to log in yet** — Step 2 will determine if auth is needed.

---

Step 2: Site Fingerprint (Single Command)

Run the all-in-one site fingerprint command instead of individual eval calls. This is faster, more reliable, and detects framework + protection + iframes + auth requirements in one shot.

**Use the script file** — multi-line JS with arrow functions and optional chaining fails in playwright-cli's single-line command parser. The script file approach has been tested and works reliably:

npx @playwright/cli@latest -s=<app> run-code "$(grep -v '^\s*//' ${CLAUDE_PLUGIN_ROOT}/scripts/site-fingerprint.js | tr '\n' ' ')"

> **IMPORTANT:** The `site-fingerprint.js` script must be loaded via the command > above. Do NOT copy-paste the JS inline — it will fail with SyntaxError. > The `grep -v` strips comments and `tr` joins lines for single-line execution.

Interpret fingerprint results

The fingerprint returns four groups: `framework`, `protection`, `auth`, `iframes`. Map each `true` flag to the next action:

| Group | Action | |---|---| | **framework** | See `references/framework-detection.md` for the full protocol table (`googleBatch` / `nextPages` / `nextApp` / `nuxt` / `spaRoot`). | | **protection** | See `references/protection-detection.md` — **always start at the escalation ladder at the top** (plain httpx → curl_cffi → curl_cffi + cookies → camoufox → hybrid). | | **auth** | Table below (A