@decocms/parity 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.11.0](https://github.com/decocms/parity/compare/v0.10.1...v0.11.0) (2026-06-17)
+
+### Added
+
+* **Claude Agent SDK as a third LLM provider (#66).** Reuses the local `claude` CLI auth via [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk). Auto-detected when no env key is set — devs with `claude` already logged in don't need to configure anything. Goes through the user's Claude plan instead of API billing.
+* **Per-feature model routing.** Selector discovery / step recovery / classification → Haiku 4.5 (cheap), visual diff / aggregation → Sonnet 4.6, explain → Opus 4.7. Overridable via `--llm-model <feat>=<model>,...`, `--llm-tier-default <tier>`, or `--llm-model-default <model>`. Cuts ~70% of the LLM cost on a `--preset full` run.
+* **`parity pr` CI/CD command (#79).** Compares a PR preview URL against prod and emits a Markdown comment ready to paste into a GitHub PR. With `--github`, writes to `$GITHUB_STEP_SUMMARY`. Thin wrapper around `parity run` with CI-tuned defaults (preset=ci, mobile-only, purchase-journey).
+* **`parity report --section <name>` (#74).** Extracts one tab from a saved run as HTML or, with `--json`, as a tailored JSON projection (verdict, top-issues, checks, network, etc.). Lets agents pull the SEO/Network/Vitals slice without parsing the whole report or loading the full Run.
+* **Per-page Network waterfall (#78).** SVG bar chart on the Network tab, positioned by `requestStart`, color-coded by resource type, faded for cached. `NetworkEntry` schema gets optional `startMs`/`endMs` (back-compat).
+* **Clickable dashboard tiles → per-check detail panels (#76).** Tiles route to `#detail/<checkName>` showing status, duration, summary, issues, raw `data` payload, and a copy-pasteable reproduction command.
+* **Side-by-side Home/PLP/PDP/Cart/Checkout buttons (#77).** SBS panel classifies captured paths by role and emits one button per role. URLs captured on one side only get a dashed border + warning chip.
+* **`--pt` flag for LLM output language (#67).** Available on `parity run`, `audit`, `e2e`, `journey`, `fix`, `explain`. Affects only LLM-generated content — static report stays in English.
+* **Tab descriptions / inline help (#73).** Every tab opens with a one-line description so new readers (and agents) immediately know what the tab covers.
+* **Interactive selector prompt foundation (#72).** When parity hits a missing selector AND no LLM provider is available AND running in a TTY, the new prompt module guides the dev through writing a `.parityrc.json` override. Wiring into the runner is a follow-up.
+
+### Changed
+
+* **Report HTML now in English by default (#67).** Every user-facing PT-BR string in the report, audit HTML, and visual-diff prompt is translated. New regression test scans the output for PT-BR diacritics and a deny-list of common tokens.
+* **`#diff` tab hidden when no baseline (#68).** The empty-state "Run executed without baseline" message that looked like a bug on every normal run is gone — the tab simply doesn't render unless `--baseline <name>` is loaded.
+* **LLM-only tabs hidden when no LLM ran (#75).** Visual Diff and LLM Prompt tabs are omitted entirely from the nav + DOM when no LLM output exists. Single header banner explains why.
+* **Side-by-side iframe forces mobile viewport via proxy (#70).** When `parity serve` is active, the proxy injects `<meta name="viewport" content="width=375">`, sets a mobile UA, and adds `Sec-CH-UA-Mobile: ?1` so cand renders in real mobile.
+* **Smart `--visual-pages` default (#71).** Auto-zeroes when no LLM provider is available — the capture without analysis was just wasted seconds. Opt in with `--visual-pages N` if you want the raw screenshots anyway.
+* **README rewrites around the agents-in-loop thesis (#80).** Three use cases (assisted migration, CI/CD PR review, continuous smoke) up front. New `docs/cli.md`, `docs/checks.md`, `docs/config.md`.
+* **Report mobile-friendly + a11y focus rings + tabular numerics (#81).** Below 880px the sidebar becomes a horizontal chip strip; numeric values in tiles stay aligned across columns.
+
+### Fixed
+
+* **SDK provider image handling.** First implementation embedded base64 data URLs as text in the prompt — vision features (visual-diff, section-understanding) silently produced garbage. Now switches to the async-iterable `SDKUserMessage` form with proper `image` content blocks when `userImages` is set.
+* **Timer leak in SDK provider abort handle.** `setTimeout` was created but never cleared. New `makeAbortHandle` returns a `clear()` callback that callers invoke in `finally`.
+* **JSON repair reuse in SDK provider.** Bare `JSON.parse` was dropping fenced/wrapped output the OpenRouter provider would have salvaged. Now reuses the exported `tryRepairJson`.
+* **`setForcedProvider` validates credentials before activating.** Returns a user-facing error string instead of failing with a 401 mid-run.
+* **`disallowedTools: ["*"]` removed.** Was treated as a literal tool name, not a glob — misleading dead code.
+* **Repo-wide lint sweep.** 9 biome errors carried over from in-flight PRs (template-literal-as-string, optional-chain, assign-in-expression) now fixed. `bun run lint` is clean.
+
 ## [0.10.1](https://github.com/decocms/parity/compare/v0.10.0...v0.10.1) (2026-05-30)
 
 ### Fixed

package/README.md

@@ -1,39 +1,27 @@
 # @decocms/parity
 
-E2E parity validator for site migrations. CLI that runs comparative tests between two URLs — `prod` (source of truth) and `cand` (migrated version) — and produces a single HTML report flagging UI, functional, SEO, and Web Vitals regressions.
+> **Infrastructure for agents in loop to close migrations, PRs, and incidents without a dev on the critical path.**
 
-Built originally for Fresh → TanStack Start migrations of Deco storefronts, but the checks are generic enough for any side-by-side migration.
+`parity` is a CLI that runs deep comparative tests between two URLs — `prod` (source of truth) and `cand` (migrated version, PR preview, or staging) — and produces:
+
+- A standalone **HTML report** for humans to scan in 30 seconds
+- A normalized **JSON projection** (`parity report --section <name> --json`) that agents can consume without parsing HTML
+- A **JSONL stream** (`--json`) that streams each check result as it completes
+- A **PR comment** (`parity pr --prod ... --preview ...`) ready to drop into a CI/CD pipeline
+
+It checks UI, functional, SEO, performance, console, network, and cache regressions. Built originally for Fresh → TanStack Start migrations of Deco storefronts, but the checks are generic enough for any side-by-side migration.
 
 > **Status:** alpha. APIs and report layout may still change.
 
-## What it checks
-
-| Check                         | What it catches                                                        |
-| ----------------------------- | ---------------------------------------------------------------------- |
-| HTTP status parity            | Routes that 404 / 500 in cand but worked in prod                       |
-| Console errors                | New hydration mismatches, failed fetches, JS exceptions                |
-| HTML structural diff          | Section / element counts drifting beyond tolerance                     |
-| Meta / SEO parity             | `<title>`, `<meta description>`, canonical, og:\*, twitter:\*, JSON-LD |
-| **Visual diff (LLM Vision)**  | Sections missing, wrong hero, broken shelf, layout shifts              |
-| Purchase journey              | Home → PLP → PDP → CEP → cart → checkout completes in both             |
-| Network summary               | Request count / bytes / cache hit rate                                 |
-| Web Vitals                    | LCP, FCP, TTFB, INP, CLS — mobile                                      |
-| Image loading health          | Missing alt text, no srcset, broken `<img>`                            |
-| Lazy section presence         | Deco `/deco/render` and `/_loader/*` routes responding                 |
-| SEO deep audit                | robots.txt, sitemap, noindex regressions                               |
-| Cache coverage                | Cache hit rate, opportunities to cache                                 |
-| **Search presence**           | Search input reachable from home in both                               |
-| **Search autocomplete**       | Typing reveals suggestions; cand keeps parity with prod                |
-| **Search results**            | Same keyword returns comparable product counts                         |
-| **Search no-results**         | Unicode garbage term shows empty state, doesn't match products         |
-| **Cart interactions**         | Increment / decrement / coupon / remove all behave in cand             |
-| **404 parity**                | Invalid URL returns 404 (no catch-all 200 in cand)                     |
-| **Cookie/CEP modal CLS**      | Modals don't introduce layout shifts >0.1 in cand                      |
-| **PDP gallery + related**     | Image gallery + "Related products" shelf still render                  |
-| **Footer links health**       | Institutional links (privacy, contact, etc.) aren't broken in cand     |
-| **Login flow** _(opt-in)_     | Valid credentials log in; invalid ones show a clear error              |
-
-All results are aggregated (optionally via Claude) and ranked by severity. Each issue includes screenshots, reproduction, and a suggested fix.
+## Why parity exists
+
+Migrations, PR reviews, and incident triage all share the same workflow: take two versions of a site, find what's different, fix it. Doing this by hand is slow and error-prone; spinning up an LLM agent to do it requires a tool the agent can drive. `parity` is that tool.
+
+Three use cases drive the design:
+
+1. **Assisted migration** (Fresh → TanStack, Shopify → Hydrogen, etc.) — an agent runs `parity run` on the migrated branch every commit, picks the top issue, fixes it, runs again. The HTML report + visual-diff prompt are both designed to be paste-ready into Claude / ChatGPT.
+2. **CI/CD PR review** — `parity pr --prod ... --preview ...` outputs a Markdown comment with verdict, top issues, and a link back to the full report. Drop it into a workflow with `gh pr comment -F` or `actions/github-script`.
+3. **Continuous smoke** — `parity run --preset smoke` finishes in ~30s and runs no LLM. Cheap enough to ping after every deploy.
 
 ## Quickstart
 
@@ -44,125 +32,98 @@ npm install -g @decocms/parity
 npx @decocms/parity run --prod ... --cand ...
 
 # First-time smoke run (~30s, no LLM needed)
-parity run \
-  --prod https://oldsite.com \
-  --cand https://newsite.example.dev \
-  --preset smoke --open
+parity run --prod https://oldsite.com --cand https://newsite.example.dev --preset smoke --open
 
-# Full audit with visual diff (set ANTHROPIC_API_KEY for the LLM bits)
+# Full audit with visual diff
 ANTHROPIC_API_KEY=sk-... parity run \
   --prod https://oldsite.com \
   --cand https://newsite.example.dev \
   --preset full --open
+
+# CI/CD PR comment
+parity pr --prod https://oldsite.com --preview https://pr-123-preview.example.dev --github
 ```
 
-## Presets
+## Agent contract
+
+For agents driving `parity` in a loop, the stable surface is:
 
-`--preset smoke` — homepage only, mobile only, no LLM, no extra crawl. Use to validate the pipeline runs at all (~30s).
+| Need | Command | Output |
+| --- | --- | --- |
+| Run a full comparison | `parity run --prod X --cand Y --json runs.jsonl` | JSON-Lines, one line per check |
+| Extract one tab from a saved run | `parity report <runId> --section <name>` | HTML slice |
+| Extract one tab as structured JSON | `parity report <runId> --section <name> --json` | JSON projection |
+| Drive a CI/CD pipeline | `parity pr --prod X --preview Y --github` | Markdown comment + `$GITHUB_STEP_SUMMARY` |
+| Drill into one issue | `parity explain <runId> <issueId>` | LLM deep-dive (needs key) |
+| Build a paste-ready prompt | `parity prompt <runId>` | Markdown ready for Claude/ChatGPT |
+| Generate visual-fix bundle | `parity fix --prod X --cand Y --selector S` | Markdown + screenshots + computed-styles diff |
 
-`--preset full` — purchase journey, mobile + desktop, 5 visual diff pages, 10 vitals pages, LLM enabled if API key is set. Use for releases.
+See [`docs/cli.md`](./docs/cli.md) for every command, [`docs/checks.md`](./docs/checks.md) for every check.
 
-`--preset ci` — purchase journey on mobile, smaller crawls (3 visual + 5 vitals). Tuned for CI runtime.
+## LLM providers
 
-Individual flags always override the preset.
+Three providers, auto-detected in this order — **none required** if you have the `claude` CLI logged in locally:
 
-## Commands
+1. `ANTHROPIC_API_KEY` — direct Anthropic API (fastest, billed to your API account)
+2. `OPENROUTER_API_KEY` — OpenRouter
+3. **Local `claude` CLI** — uses [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk); goes through your existing Claude plan. No env vars needed
 
-| Command            | What it does                                                                  |
-| ------------------ | ----------------------------------------------------------------------------- |
-| `parity run`       | Full comparison run between two URLs                                          |
-| `parity audit`     | **Single-site** absolute audit (no prod×cand). Console + Vitals + SEO + Imgs  |
-| `parity e2e`       | **Single-site** functional end-to-end: all flows + all checks. ONE URL.       |
-| `parity journey`   | CI-friendly: only the purchase journey, with JUnit / GitHub annotations       |
-| `parity vitals`    | Crawl N pages, compare Web Vitals prod vs cand                                |
-| `parity cache`     | CDN cache analysis, opportunities, request categorization                     |
-| `parity serve`     | Local HTTP server with iframe proxy so side-by-side tab works for any site    |
-| `parity report`    | Reopen an existing run's HTML report                                          |
-| `parity compare`   | Compare a run against a baseline                                              |
-| `parity baseline`  | Manage baselines (`set`, `list`, `unset`)                                     |
-| `parity list`      | List saved runs                                                               |
-| `parity check`     | Run a single check (`<name>`) — skips sitemap + LLM aggregation; sub-10s loop |
-| `parity console`   | Sub-10s capture of console errors/warnings + network failures for one URL     |
-| `parity html`      | Dump page/selector HTML or unified diff prod×cand (prettier + jsdiff)         |
-| `parity section`   | Focused prod×cand diff of a section: HTML + screenshot + computed styles      |
-| `parity fix`       | Pixel-perfect bundle: heatmap + CSS source + LLM-ready Markdown prompt        |
-| `parity prompt`    | Export issues as a Markdown prompt for any LLM                                |
-| `parity explain`   | LLM deep-dive on a specific issue (needs `ANTHROPIC_API_KEY`)                 |
-| `parity learned`   | Inspect the learned-selectors library                                         |
+Force with `--llm <anthropic|openrouter|claude-code|none|auto>`. Override per-feature with `--llm-model selector-discovery=claude-haiku-4-5,visual-diff=claude-opus-4-7`. Default tiers: Haiku for short tasks (selector discovery, classification), Sonnet for vision/aggregation, Opus for `explain`.
 
-Run any command with `--help` for the full flag list.
+Without any provider, the CLI still runs and outputs raw check results — only the LLM-tagged tabs (Visual Diff, LLM Prompt) hide themselves and a banner explains why.
 
 ## Output
 
 ```
 ./parity-output/runs/<runId>/
 ├── report.html       # standalone, open in any browser
-├── report.json       # structured output for CI / tooling
+├── report.json       # structured output for agents / CI / tooling
 ├── screenshots/      # per-page, per-viewport, per-side; includes pixelmatch heatmaps
 ├── har/              # Playwright HARs (one per viewport/side)
 ├── traces/           # Playwright traces — drag into trace.playwright.dev
 └── console/          # console messages captured per page
 ```
 
-Plus `./parity-baselines/<name>.json` for git-trackable baseline manifests.
-
-## Visual Diff tab
-
-When `--visual-pages > 0` and an LLM key is set, the report's **Visual Diff** tab shows, per page:
-
-- prod screenshot · cand screenshot · pixelmatch heatmap, side-by-side
-- list of Deco sections present in prod but missing in cand (auto-detected from `data-section`)
-- semantic differences identified by Claude Vision (region, type, severity, description)
-- one-click "Export visual prompt" — Markdown ready to paste into Claude / ChatGPT to generate the fix
+## Presets
 
-The visual prompt focuses *only* on visual diffs, references the screenshot paths, and includes migration-specific guidance (register section in `setup.ts`, loader shape drift, useDevice hydration, etc).
+- `--preset smoke` — homepage only, mobile only, no LLM, no extra crawl. ~30s. Use for "did the pipeline even run?".
+- `--preset full` — purchase journey, mobile + desktop, 5 visual diff pages, 10 vitals pages. Use for releases.
+- `--preset ci` — purchase journey on mobile, smaller crawls (3 visual + 5 vitals). Tuned for CI runtime.
 
-## Pixel-perfect fix loop
+Individual flags always override the preset. See `parity run --help` for the full default behavior breakdown.
 
-When `parity run` flags a section but you want the LLM to actually patch it, `parity fix` bundles every signal into one Markdown prompt:
+## CI usage (GitHub Actions)
 
-```bash
-parity fix \
-  --prod https://www.example.com \
-  --cand https://example.deco-cx.workers.dev \
-  --selector 'header'
+```yaml
+- name: Parity check
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  run: |
+    npx @decocms/parity pr \
+      --prod ${{ vars.PROD_URL }} \
+      --preview ${{ env.PR_PREVIEW_URL }} \
+      --github
 ```
 
-Writes (under `./parity-output/sections/`):
-
-- `section-<hash>-{prod,cand}.png` — locator screenshots, carousels stabilized
-- `section-<hash>-heatmap.png` — pixelmatch with bounding-box analysis
-- `section-<hash>-bundle.json` — machine-readable bundle (deltas + sources + bboxes)
-- `section-<hash>-prompt.md` — **paste-ready** Markdown with embedded images, computed-style deltas, CSS source per property, HTML diff, and an opinionated "summarize what you understand first, no code yet" instruction
-
-If `ANTHROPIC_API_KEY` is set, the LLM is invoked automatically and prints a one-paragraph diagnosis to stdout (uses Claude Vision on the screenshots). Pass `--no-llm` to stay offline.
-
-The same flags are available individually on `parity section`: `--heatmap`, `--css-source`, `--prompt`, `--llm-summary`. Use those when you only need one signal; `parity fix` is the "do everything" shortcut.
-
-## `parity e2e` — single-site functional run
-
-The `audit` command runs absolute checks (vitals, console, network, images, SEO) — useful but doesn't exercise interactions. `parity e2e` runs **all the functional flows** (homepage, plp, pdp, purchase-journey, search, cart-interactions, optionally login) against a single URL plus all parity checks in single-site mode.
-
-```bash
-# Quick e2e for a single site (no comparison, ~3-5min)
-parity e2e --url https://www.example.com
-
-# Pick specific flows
-parity e2e --url https://www.example.com --flows=search,cart-interactions
+The `--github` flag writes the Markdown to `$GITHUB_STEP_SUMMARY` so it shows up under the workflow summary. To also post as a PR comment:
 
-# Override LLM-discovered search term
-parity e2e --url https://www.example.com --search-terms="camisa,promocao"
-
-# With login (credentials via env or flags)
-PARITY_LOGIN_EMAIL=test@example.com PARITY_LOGIN_PASSWORD=*** \
-  parity e2e --url https://www.example.com --flows=login
+```yaml
+    npx @decocms/parity pr ... --out parity-comment.md
+- uses: actions/github-script@v7
+  with:
+    script: |
+      const fs = require('fs');
+      const body = fs.readFileSync('parity-comment.md', 'utf8');
+      github.rest.issues.createComment({
+        ...context.repo,
+        issue_number: context.issue.number,
+        body,
+      });
 ```
 
-**Use `parity e2e` when** you want to validate "does this site actually work end-to-end?" — pre-launch, post-deploy, partner sites. **Use `parity run` when** you need to detect *regressions* between two versions (prod vs migration candidate).
-
 ## Configuration (optional)
 
-`.parityrc.json` at the project root — selector overrides and run defaults:
+`.parityrc.json` at the project root — selector overrides and run defaults. See [`docs/config.md`](./docs/config.md) for the full schema.
 
 ```json
 {
@@ -170,77 +131,15 @@ PARITY_LOGIN_EMAIL=test@example.com PARITY_LOGIN_PASSWORD=*** \
   "selectors": {
     "categoryLink": "header a[href*='/c/']",
     "productCard": "[data-product-card] a",
-    "buyButton": "button:has-text('Comprar')",
-    "minicartTrigger": "[data-minicart-trigger]",
-    "cepInputPdp": "input[name='shipping-zipcode']",
-    "cepInputCart": "input[name='cart-zipcode']",
-    "checkoutButton": "a:has-text('Finalizar compra')",
-    "searchInput": "input[type='search']",
-    "cartCouponInput": "input[name*='coupon']"
-  },
-  "search": {
-    "terms": ["camisa", "promocao"]
+    "buyButton": "button:has-text('Comprar')"
   },
-  "footer": {
-    "maxLinks": 20,
-    "followExternal": false
-  },
-  "notFound": {
-    "testUrl": "/this-page-definitely-does-not-exist"
-  },
-  "login": { "enabled": true }
+  "search": { "terms": ["camisa", "promocao"] }
 }
 ```
 
-> **Credentials are NEVER read from `.parityrc.json`.** Set `PARITY_LOGIN_EMAIL` and `PARITY_LOGIN_PASSWORD` as environment variables (`.parityrc.json` is for non-secret config only).
-
-`.parityignore` — noise suppression:
-
-```json
-{
-  "ignoreSelectorsVisual": [".banner-rotativo", "#trustvox-trustbar"],
-  "ignoreRequestPatterns": ["*.gif?t=*", "**/pixel*"],
-  "ignoreConsolePatterns": ["ERR_BLOCKED_BY_CLIENT"]
-}
-```
-
-Both files are gitignored by default — they're per-user, not per-repo.
-
-## LLM (optional)
-
-Set **one** environment variable to unlock LLM-driven features:
-
-- `ANTHROPIC_API_KEY` — direct Anthropic API (Claude Sonnet 4.6 with prompt caching). Preferred.
-- `OPENROUTER_API_KEY` — OpenRouter (default model `anthropic/claude-sonnet-4.5`; override with `PARITY_OPENROUTER_MODEL`).
-
-What LLM enables:
-
-- **Issue aggregation** — flat raw issues become ranked, deduplicated top issues
-- **Selector discovery** — infers `categoryLink` / `productCard` / `buyButton` etc. from HTML
-- **Step recovery** — when a flow step fails, suggest a working selector
-- **Visual semantic diff** — Claude Vision interprets pixel diffs as missing sections / wrong layout / etc.
-- **PLP picker / PDP matcher** — cross-site disambiguation
-- **`parity explain <issue>`** — root-cause analysis on demand
-
-Without any key, the CLI still runs and outputs raw check results — only the smart bits are skipped. Deterministic fallbacks always apply.
-
-**Cost** — A `--preset full` run with visual diff uses ~6-12 Claude calls (each with 2 screenshots). Roughly $0.05–$0.20 per run on Sonnet 4.6 with prompt caching.
-
-## CI usage
-
-```yaml
-- name: Parity check
-  env:
-    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-  run: |
-    npx @decocms/parity journey \
-      --prod ${{ vars.PROD_URL }} \
-      --cand ${{ env.PR_PREVIEW_URL }} \
-      --junit parity.junit.xml \
-      --github
-```
+`.parityignore` — noise suppression. See `docs/config.md`.
 
-`parity journey` emits GitHub Actions `::error` and `::warning` annotations for each failed step and writes JUnit XML.
+> **Credentials are NEVER read from `.parityrc.json`.** Set `PARITY_LOGIN_EMAIL` and `PARITY_LOGIN_PASSWORD` as environment variables.
 
 ## Development