@decocms/parity 0.1.0

package/AGENTS.md

@@ -0,0 +1,112 @@
+# AGENTS.md
+
+Guidance for AI coding agents (Claude Code, Cursor, Aider, etc.) using `parity` to validate or fix a site migration.
+
+## When to run parity
+
+Use `parity run` (or `parity journey` in CI) when the user:
+
+- finished migrating a section / page / route and wants to verify nothing regressed
+- mentions "is this still working in cand?" / "compare prod and cand"
+- wants a baseline before starting a refactor
+- asks for a visual diff or "what's missing in the migration"
+- needs a structured artifact (`report.json`) to drive other automation
+
+Do **not** run parity for:
+
+- linting / type errors — that's `tsc`
+- single-component unit tests — use vitest
+- performance profiling of just one page — use Lighthouse or Chrome DevTools directly
+
+## Picking the command
+
+| User intent                                  | Command                                         |
+| -------------------------------------------- | ----------------------------------------------- |
+| "is everything still working?"               | `parity run --preset smoke` then `--preset full` if smoke is clean |
+| "compare these two URLs in CI"               | `parity journey --prod ... --cand ... --junit ... --github`        |
+| "find sections missing in the migration"     | `parity run --visual-pages 5` then read `report.json` `.visualDiff` |
+| "did web vitals regress?"                    | `parity vitals --prod ... --cand ... --limit 20`                   |
+| "is the new site missing cache?"             | `parity cache --cand ... --pages 30`                               |
+| "I want an LLM prompt with all the issues"   | `parity prompt <runId>` (writes Markdown to stdout)                |
+| "explain this specific issue"                | `parity explain <runId> <issueId>` (needs `ANTHROPIC_API_KEY`)     |
+
+## Reading the JSON output
+
+`./parity-output/runs/<runId>/report.json` is the source of truth. Key fields:
+
+```ts
+{
+  verdict: { status: "pass"|"warn"|"fail", score: 0..100, critical, high, medium, low },
+  topIssues: Issue[],       // LLM-ranked, deduplicated; usually 5-10 items
+  issues: Issue[],          // all raw issues from every check
+  checks: CheckResult[],    // one per check; .data has structured details
+  visualDiff: {
+    pagesChecked, pagesWithDiffs, pagesPassed,
+    results: VisualDiffPage[]   // per page: prod/cand screenshots, sections, LLM diffs
+  },
+  flowCaptures: FlowCapture[]   // per-flow page captures with vitals + network
+}
+```
+
+To programmatically decide if a migration is ready:
+
+```ts
+const run = JSON.parse(fs.readFileSync(`${runDir}/report.json`));
+if (run.verdict.critical === 0 && run.verdict.high === 0) {
+  // ship it
+}
+```
+
+## Driving fixes from the output
+
+The most useful flow for an AI agent is:
+
+1. Run `parity run --preset full` → wait → read `report.json`
+2. For each `topIssue` with severity ≥ high, open the file(s) referenced in `suggestedFix`
+3. For visual diffs: read `visualDiff.results[].sectionsOnlyInProd` — these are Deco sections present in prod's DOM but missing in cand. Most likely cause: not registered in `src/setup.ts → registerSections()`.
+4. For console errors: read `issues[].evidence[]` for HAR paths; the failed request is usually the root cause.
+5. Re-run `parity journey` (cheaper) after each fix to confirm.
+
+**Important:** prod is the source of truth. Never modify prod-side code to make tests pass — always fix cand.
+
+## When LLM features are unavailable
+
+If neither `ANTHROPIC_API_KEY` nor `OPENROUTER_API_KEY` is set:
+
+- `topIssues` will fall back to deterministic severity-sorted merge (still useful)
+- `visualDiff.results[].differences` will be empty (only pixelmatch heatmap survives)
+- `sectionsOnlyInProd` is still populated (uses DOM, not vision)
+- Selector discovery is skipped; defaults from `.parityrc.json` or platform heuristics kick in
+
+The CLI never fails just because the LLM is unavailable. Issues will still be reported, just less polished.
+
+## Cost-conscious usage
+
+A `--preset full` run with visual diff ≈ 6-12 Claude calls × ~$0.01-0.02 each. Cheap, but in tight loops:
+
+- Use `--preset smoke` first (no LLM, ~30s) to validate the URLs respond
+- Use `--no-visual-diff` if you only care about functional checks
+- Use `parity journey` (no aggregation step) for the tightest CI loop
+
+Hard caps already in place:
+
+- 12 max Claude Vision calls per `run` (visual diff)
+- 8 max selector recovery calls per run
+- 120s timeout per Vision call, 60s per text call
+
+## Gotchas
+
+- **First run is slower** — Playwright downloads Chromium (~150MB). After that, ~30s for smoke, ~5min for full.
+- **Sites with X-Frame-Options block the side-by-side iframe tab.** Use `parity serve <runId>` which proxies through.
+- **Cookies are isolated per run** — no shared session between prod and cand. If a flow needs auth, you'll need to handle that in `.parityrc.json` or extend the flow.
+- **Visual diff catches missing sections** mostly via DOM (`data-section`); if the migrated site doesn't emit that attribute, the LLM still sees the screenshots but loses the section-name context.
+- **`parity run` doesn't apply schema changes from old runs** — if you change `src/types/schema.ts`, old `report.json` files won't parse. Delete `parity-output/` or re-run.
+
+## Files agents should and should not write
+
+- ✅ `.parityrc.json` (selectors, CEP) — gitignored, per-user
+- ✅ `.parityignore` (noise filters) — gitignored
+- ✅ Code changes in `src/` of the candidate site
+- ❌ Don't commit `learned-selectors.json` (gitignored) — it contains host names
+- ❌ Don't commit `parity-output/` — gitignored, can be GB-sized
+- ❌ Don't modify `parity-baselines/<name>.json` by hand — use `parity baseline set`

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+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/).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-12
+
+First public release.
+
+### Added
+
+- `parity run` — full comparison between two URLs with 12 built-in checks
+- `parity journey` — CI-friendly purchase journey runner with JUnit + GitHub annotations
+- `parity vitals` — multi-page Web Vitals comparison
+- `parity cache` — CDN cache analysis with opportunities
+- `parity serve` — local HTTP proxy server so side-by-side iframes work for any site
+- `parity baseline` / `parity compare` — track regressions over time
+- `parity prompt` — export prioritized issues as LLM-ready Markdown
+- `parity explain` — LLM root-cause analysis on a specific issue
+- **Visual Diff tab** in the HTML report — galleries of prod / cand / pixelmatch heatmap with per-page Claude Vision analysis, missing-section detection from DOM, and dedicated export prompt
+- **CLI presets** (`--preset smoke|full|ci`) bundling common flag combinations
+- **Pre-flight check** — pings both URLs before the heavy capture phase, fails fast on dead URLs
+- **Hard timeouts everywhere**: 120s per LLM Vision call, 60s per text call, 60s per page capture, 5s per response body read, 5s for the response flush. No more infinite hangs on streaming endpoints.
+- Learned-selectors library with platform detection (VTEX, Shopify, Nuvemshop, Wake, Deco)
+- LLM-driven selector discovery and step recovery
+- Cross-site PDP matching via Claude (fingerprint comparison)
+
+### Security
+
+- `learned-selectors.json` is now gitignored and `.npmignored`. It may contain host names of sites you've tested.
+- `.parityrc.json` and `.parityignore` are gitignored — they're per-user config that may reference private URLs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 deco CMS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# @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.
+
+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                                 |
+
+All results are aggregated (optionally via Claude) and ranked by severity. Each issue includes screenshots, reproduction, and a suggested fix.
+
+## Quickstart
+
+```bash
+# Install
+npm install -g @decocms/parity
+# or run without install
+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
+
+# Full audit with visual diff (set ANTHROPIC_API_KEY for the LLM bits)
+ANTHROPIC_API_KEY=sk-... parity run \
+  --prod https://oldsite.com \
+  --cand https://newsite.example.dev \
+  --preset full --open
+```
+
+## Presets
+
+`--preset smoke` — homepage only, mobile only, no LLM, no extra crawl. Use to validate the pipeline runs at all (~30s).
+
+`--preset full` — purchase journey, mobile + desktop, 5 visual diff pages, 10 vitals pages, LLM enabled if API key is set. Use for releases.
+
+`--preset ci` — purchase journey on mobile, smaller crawls (3 visual + 5 vitals). Tuned for CI runtime.
+
+Individual flags always override the preset.
+
+## Commands
+
+| Command            | What it does                                                                  |
+| ------------------ | ----------------------------------------------------------------------------- |
+| `parity run`       | Full comparison run between two URLs                                          |
+| `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 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                                         |
+
+Run any command with `--help` for the full flag list.
+
+## Output
+
+```
+./parity-output/runs/<runId>/
+├── report.html       # standalone, open in any browser
+├── report.json       # structured output for 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
+
+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).
+
+## Configuration (optional)
+
+`.parityrc.json` at the project root — selector overrides and run defaults:
+
+```json
+{
+  "cep": "01310-100",
+  "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')"
+  }
+}
+```
+
+`.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
+```
+
+`parity journey` emits GitHub Actions `::error` and `::warning` annotations for each failed step and writes JUnit XML.
+
+## Development
+
+```bash
+git clone git@github.com:decocms/parity.git
+cd parity
+bun install
+bunx playwright install chromium
+bun run dev run --prod ... --cand ...
+```
+
+Tests: `bun run test` (vitest). Typecheck: `bun run check`. Build: `bun run build`.
+
+## License
+
+MIT