feat(cli): --report-to flag for Guardian CI integration

[nucliweb]

Goal

Add an optional --report-to <url> flag that POSTs measurement results to a Guardian endpoint after the run completes. Without the flag, the CLI makes no external calls — fully offline by default.

This is the bridge between the open-source CLI and the perf.reviews CI SaaS (Guardian).

Behaviour

# Standalone — no external calls
npx webperf-snippets https://example.com --workflow audit

# With Guardian reporting
npx webperf-snippets https://example.com --workflow audit \
  --report-to https://perf.reviews/api/guardian/report \
  --api-key $PERF_REVIEWS_API_KEY

The CLI exits with the same codes as usual. The POST to Guardian is fire-and-forget (non-blocking on exit code).

Payload shape

{
  "url": "https://example.com",
  "workflow": "audit",
  "timestamp": "2026-05-06T10:00:00Z",
  "navMs": 1240,
  "results": [...],
  "meta": {
    "viewport": "mobile",
    "waitMs": 3000,
    "cli_version": "0.2.0"
  }
}

What Guardian does with it

• Stores the report tied to the API key (project / repo)
• Compares against the previous report for the same URL to detect regressions
• Returns { ok: true } or { ok: false, regressions: [...] } — CLI logs a warning if regressions are detected but does not change exit code (budget flags control that)

CI usage

- run: |
    npx webperf-snippets ${{ env.STAGING_URL }} \
      --workflow audit \
      --budget-lcp 2500 \
      --report-to https://perf.reviews/api/guardian/report \
      --api-key ${{ secrets.PERF_REVIEWS_API_KEY }}

Important constraints

• No gating via --report-to: exit code is always controlled by --budget-* flags, never by Guardian response
• No CWV in CI: LCP/CLS/INP are too noisy on GitHub Actions runners (±15–30%). Only deterministic snippets (audit workflow) are recommended for CI
• Offline by default: omitting --report-to produces zero network calls to perf.reviews

Files

• cli/src/reporter-to.js — new file, POST helper
• cli/src/bin.js — expose --report-to and --api-key flags, call after run

Acceptance criteria

• Without --report-to, no external calls are made
• With --report-to, results are POSTed after snippets complete
• Network failure on POST logs a warning but does not change exit code
• --api-key is sent as Authorization: Bearer <key> header
• Documented in README under a "Guardian integration" section