@decocms/parity

Infrastructure for agents in loop to close migrations, PRs, and incidents without a dev on the critical path.

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.

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

# Install — auto-installs Playwright Chromium on postinstall (~140 MB, one-time)
npm install -g @decocms/parity
# or run without install
npx @decocms/parity run --prod ... --cand ...

# In CI / behind a corp proxy? Skip the auto-install and do it later:
# PARITY_SKIP_PLAYWRIGHT_INSTALL=1 npm install -g @decocms/parity
# npx playwright install chromium

# 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
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

Agent contract

For agents driving parity in a loop, the stable surface is:

See docs/cli.md for every command, docs/checks.md for every check. See docs/reports.md for the HTML outputs and the two report template kits.

LLM providers

Three providers, auto-detected in this order — none required if you have the claude CLI logged in locally:

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; goes through your existing Claude plan. No env vars needed

Force with --llm <anthropic|openrouter|claude-code|none|auto>. Override per-feature with --llm-model visual-diff=claude-opus-5,explain=claude-opus-5, or flatten everything to one tier with --llm-tier-default <haiku|sonnet|opus>. Default tiers: Sonnet for selector discovery / recovery / matching / vision (the structural-reasoning calls), Haiku for short copy-list classification (search-terms), Opus for explain. Cost-conscious? Try --llm-tier-default haiku and bump features back to Sonnet selectively if you hit selector misses.

Without any provider, the CLI still runs and outputs raw check results.

Output

./parity-output/runs/<runId>/
├── report.json       # structured output for agents / CI / tooling
├── report.html       # only with --html/--open, or rendered later by `parity report <runId>`;
│                     # links to screenshots/ by relative path — keep the two together
├── screenshots/      # per-page, per-viewport, per-side; includes pixelmatch heatmaps
├── har/              # Playwright HARs, one per viewport/side — only with PARITY_HAR=1
└── traces/           # Playwright traces (drag into trace.playwright.dev) — only with PARITY_TRACE=1

Presets

• --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.

Individual flags always override the preset. See parity run --help for the full default behavior breakdown.

A note on Web Vitals numbers

By default parity measures TTFB/FCP/LCP with the browser's HTTP cache enabled, on a warm connection — a "repeat visit" scenario. Lighthouse and CrUX field data, by contrast, simulate/measure cold first-time visits (cache disabled). Neither is wrong, but they answer different questions, so don't compare parity's default vitals 1:1 against Lighthouse or CrUX. Pass --bypass-cache to approximate a cold-visit measurement instead (disables the browser cache via CDP in addition to bypassing CDN/edge caches).

CI usage (GitHub Actions)

- 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

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:

    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,
      });

Configuration (optional)

.parityrc.json at the project root — selector overrides and run defaults. See docs/config.md for the full schema.

{
  "cep": "01310-100",
  "selectors": {
    "categoryLink": "header a[href*='/c/']",
    "productCard": "[data-product-card] a",
    "buyButton": "button:has-text('Comprar')"
  },
  "search": { "terms": ["camisa", "promocao"] }
}

.parityignore — noise suppression. See docs/config.md.

Credentials are NEVER read from .parityrc.json. Set PARITY_LOGIN_EMAIL and PARITY_LOGIN_PASSWORD as environment variables.

Development

git clone [email protected]: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