@decocms/blocks-cli 7.37.6 → 7.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.37.6",
+  "version": "7.39.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -31,7 +31,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.37.6",
+    "@decocms/blocks": "7.39.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/migrate/phase-scaffold.ts

@@ -2,7 +2,11 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { MigrationContext } from "./types";
 import { log, logPhase } from "./types";
-import { CANONICAL_BUN_VERSION, generatePackageJson } from "./templates/package-json";
+import {
+  CANONICAL_BUN_VERSION,
+  CANONICAL_NODE_VERSION,
+  generatePackageJson,
+} from "./templates/package-json";
 import { generateLockfileCheckYml } from "./templates/lockfile-check-yml";
 import { generateTsconfig } from "./templates/tsconfig";
 import { generateViteConfig } from "./templates/vite-config";
@@ -21,6 +25,10 @@ import { generateCacheConfig } from "./templates/cache-config";
 import { generateSdkFiles } from "./templates/sdk-gen";
 import { generateMigrationPolicyPointerRule } from "./templates/cursor-rules";
 import { generatePerfFiles } from "./templates/perf-yml";
+import { generateCiFiles } from "./templates/ci-yml";
+import { generateMainPushGuardYml } from "./templates/main-push-guard-yml";
+import { generatePlaywrightFiles } from "./templates/playwright-yml";
+import { generateReactDoctorYml } from "./templates/react-doctor-yml";
 // `lib-utils` is imported lazily — see end of phase-cleanup. Eager
 // generation of all 11 shims left every site with dead code that had
 // to be cleaned up by hand.
@@ -93,6 +101,22 @@ export function scaffold(ctx: MigrationContext): void {
   // (PR vs main), and posts a comparison comment. Gate = CLS + TBT only.
   writeMultiFile(ctx, generatePerfFiles(ctx.siteName));
 
+  // Per-PR quality pipeline (ci.yml) + its no-suppressions gate. BLOCKS on
+  // generate + build; the migration-cleanliness gates (no-suppressions,
+  // typecheck, format, knip) ship advisory so day-one CI is green. Node pinned
+  // in lockstep with the perf/playwright workflows.
+  writeMultiFile(ctx, generateCiFiles(CANONICAL_NODE_VERSION, CANONICAL_BUN_VERSION));
+
+  // Branch-protection surrogate: fails visibly if a commit reaches main
+  // without a PR (never blocks the push itself).
+  writeFile(ctx, ".github/workflows/main-push-guard.yml", generateMainPushGuardYml());
+
+  // Functional E2E harness (chromium + webkit) + self-contained config/smoke.
+  writeMultiFile(ctx, generatePlaywrightFiles(CANONICAL_BUN_VERSION));
+
+  // Advisory React lint (react-doctor): comments on PRs, never fails.
+  writeFile(ctx, ".github/workflows/react-doctor.yml", generateReactDoctorYml());
+
   // Server entry files (server.ts, worker-entry.ts, router.tsx, runtime.ts, context.ts)
   writeMultiFile(ctx, generateServerEntry(ctx));
 

package/scripts/migrate/phase-verify.ts

@@ -21,6 +21,12 @@ const REQUIRED_FILES = [
   // Workers Builds (D6.3) -- configured in the CF dashboard, not via
   // GitHub workflow files in the site repo.
   ".github/workflows/lockfile-check.yml",
+  ".github/workflows/ci.yml",
+  ".github/workflows/main-push-guard.yml",
+  ".github/workflows/playwright.yml",
+  ".github/workflows/react-doctor.yml",
+  "tools/gates/no-suppressions.sh",
+  "playwright.config.ts",
   "knip.config.ts",
   ".prettierrc",
   "src/server.ts",

package/scripts/migrate/templates/ci-workflows.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import { generateCiFiles } from "./ci-yml";
+import { generateMainPushGuardYml } from "./main-push-guard-yml";
+import { generatePlaywrightFiles } from "./playwright-yml";
+import { generateReactDoctorYml } from "./react-doctor-yml";
+
+describe("generateCiFiles", () => {
+  const files = generateCiFiles("22.15.0", "1.3.5");
+  const ci = files[".github/workflows/ci.yml"];
+
+  it("emits the workflow plus the no-suppressions gate + allowlist", () => {
+    expect(Object.keys(files).sort()).toEqual([
+      ".github/workflows/ci.yml",
+      "tools/gates/no-suppressions.sh",
+      "tools/gates/suppressions-allowlist.txt",
+    ]);
+  });
+
+  it("pins node + bun and installs frozen", () => {
+    expect(ci).toContain("name: CI");
+    expect(ci).toContain('NODE_VERSION: "22.15.0"');
+    expect(ci).toContain('BUN_VERSION: "1.3.5"');
+    expect(ci).toContain("bun install --frozen-lockfile");
+  });
+
+  it("blocks on generate + build, keeps cleanliness gates advisory", () => {
+    // generate + build have NO continue-on-error
+    expect(ci).toMatch(/Generate artifacts[\s\S]*?run: bun run generate && bun run generate:routes/);
+    expect(ci).toMatch(/Build \(vite\)\n\s+run: bun run build\n/);
+    // the four cleanliness gates are advisory
+    for (const advisory of ["Typecheck", "Format check", "Knip", "no new suppression"]) {
+      const stepIdx = ci.indexOf(advisory);
+      expect(stepIdx, `${advisory} step missing`).toBeGreaterThan(-1);
+      // a continue-on-error appears within the step block
+      expect(ci.slice(stepIdx, stepIdx + 200)).toContain("continue-on-error: true");
+    }
+  });
+
+  it("strips a bun@ prefix from the version", () => {
+    const f = generateCiFiles("22.15.0", "bun@1.3.5");
+    expect(f[".github/workflows/ci.yml"]).toContain('BUN_VERSION: "1.3.5"');
+  });
+
+  it("is de-projectized — no colombo migration-debt refs", () => {
+    const blob = Object.values(files).join("\n");
+    expect(blob).not.toMatch(/oficina/i);
+    expect(blob).not.toMatch(/#7[89]|#81/); // issues #78/#79/#81
+    expect(blob).not.toMatch(/AGENTS\.md/);
+  });
+
+  it("ships an empty allowlist (only comments)", () => {
+    const allow = files["tools/gates/suppressions-allowlist.txt"];
+    const entries = allow.split("\n").filter((l) => l.trim() && !l.trim().startsWith("#"));
+    expect(entries).toEqual([]);
+  });
+});
+
+describe("generateMainPushGuardYml", () => {
+  const yml = generateMainPushGuardYml();
+  it("guards main pushes via the commits/{sha}/pulls API", () => {
+    expect(yml).toContain("name: main-push-guard");
+    expect(yml).toMatch(/on:\s*\n\s*push:\s*\n\s*branches: \[main\]/);
+    expect(yml).toContain("commits/${SHA}/pulls");
+    expect(yml).toContain("exit 1");
+  });
+});
+
+describe("generatePlaywrightFiles", () => {
+  const files = generatePlaywrightFiles("1.3.5");
+
+  it("emits the workflow, a self-contained config, and a smoke spec", () => {
+    expect(Object.keys(files).sort()).toEqual([
+      ".github/workflows/playwright.yml",
+      "playwright.config.ts",
+      "tests/e2e/smoke.spec.ts",
+    ]);
+  });
+
+  it("installs chromium + webkit and pins bun", () => {
+    const wf = files[".github/workflows/playwright.yml"];
+    expect(wf).toContain('bun-version: "1.3.5"');
+    expect(wf).toContain("playwright install --with-deps chromium webkit");
+    expect(wf).toContain("bun run test:e2e");
+  });
+
+  it("config is self-contained (no support-helper imports) and targets tests/e2e", () => {
+    const cfg = files["playwright.config.ts"];
+    expect(cfg).toContain('testDir: "./tests/e2e"');
+    expect(cfg).not.toContain("./tests/support");
+    expect(cfg).toContain("webkit");
+  });
+
+  it("smoke needs no app boot or network (uses setContent)", () => {
+    const spec = files["tests/e2e/smoke.spec.ts"];
+    expect(spec).toContain("page.setContent");
+    expect(spec).not.toContain("await page.goto"); // no real navigation (comment may mention page.goto)
+  });
+});
+
+describe("generateReactDoctorYml", () => {
+  const yml = generateReactDoctorYml();
+  it("runs react-doctor advisory (no uncommented blocking)", () => {
+    expect(yml).toContain("name: React Doctor");
+    expect(yml).toContain("millionco/react-doctor@v2");
+    expect(yml).toContain("fetch-depth: 0");
+    expect(yml).not.toMatch(/^\s*blocking: error/m);
+  });
+});

package/scripts/migrate/templates/ci-yml.ts

@@ -0,0 +1,182 @@
+/**
+ * Scaffolds the per-PR quality pipeline and its companion gate script:
+ *   .github/workflows/ci.yml                 — GitHub Actions workflow
+ *   tools/gates/no-suppressions.sh           — bans NEW type suppressions + preact
+ *   tools/gates/suppressions-allowlist.txt   — grandfathered offenders (seeded empty)
+ *
+ * Design rationale:
+ *   - A freshly migrated site carries inherited debt (leftover
+ *     @ts-expect-error, not-yet-prettier-clean files, unused exports). So the
+ *     only BLOCKING gates are the ones a site MUST pass to run at all:
+ *     `generate` (CMS + route artifacts) and `build` (vite). Everything that
+ *     depends on migration cleanliness — no-suppressions, typecheck,
+ *     format:check, knip — ships ADVISORY (`continue-on-error: true`) so day-one
+ *     CI is green. Each carries a comment on how to promote it to blocking as
+ *     the debt zeroes out.
+ *   - The scripts the steps call (`generate`, `generate:routes`, `typecheck`,
+ *     `format:check`, `knip`) are all defined in the scaffolded package.json.
+ *
+ * @param nodeVersion  Node version for setup-node (lockstep with package.json engines).
+ * @param bunVersion   Bun version for setup-bun (= CANONICAL_BUN_VERSION).
+ */
+export function generateCiFiles(nodeVersion: string, bunVersion: string): Record<string, string> {
+  const bun = bunVersion.replace(/^bun@/, "");
+  return {
+    ".github/workflows/ci.yml": generateCiYml(nodeVersion, bun),
+    "tools/gates/no-suppressions.sh": NO_SUPPRESSIONS_SH,
+    "tools/gates/suppressions-allowlist.txt": SUPPRESSIONS_ALLOWLIST,
+  };
+}
+
+function generateCiYml(nodeVersion: string, bunVersion: string): string {
+  return `name: CI
+
+# Per-PR quality pipeline. No auto-merge: it only informs the human review.
+#
+# BLOCKS (the site must run): generate (CMS + routes), build.
+# ADVISORY (continue-on-error — inherited migration debt varies per site):
+# no-suppressions, typecheck, format:check, knip. Promote each to blocking by
+# removing its \`continue-on-error\` once that debt is zero.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-\${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  NODE_VERSION: "${nodeVersion}"
+  BUN_VERSION: "${bunVersion}"
+
+jobs:
+  gates:
+    name: gates (no-suppressions, generate, typecheck, format, knip, build)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: \${{ env.NODE_VERSION }}
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: \${{ env.BUN_VERSION }}
+
+      - name: bun install --frozen-lockfile
+        run: bun install --frozen-lockfile
+
+      # ADVISORY — a fresh migration ships inherited suppressions. Seed the
+      # allowlist with the current offenders, then remove \`continue-on-error\`:
+      #   git grep -nE '@ts-expect-error|@ts-ignore' -- src/ tools/ \\
+      #     > tools/gates/suppressions-allowlist.txt
+      - name: Gate — no new suppression + zero preact (advisory)
+        run: bash tools/gates/no-suppressions.sh
+        continue-on-error: true
+
+      # BLOCKS — CMS artifacts + route tree (the build depends on these). knip
+      # also needs routeTree.gen.ts (src/router.tsx imports it).
+      - name: Generate artifacts (CMS + routes)
+        run: bun run generate && bun run generate:routes
+
+      # ADVISORY — flip to blocking once typecheck is clean.
+      - name: Typecheck (advisory)
+        run: bun run typecheck
+        continue-on-error: true
+
+      # ADVISORY — flip to blocking after a repo-wide \`bun run format\` pass.
+      - name: Format check (advisory)
+        run: bun run format:check
+        continue-on-error: true
+
+      # ADVISORY — dead code / orphan deps.
+      - name: Knip (advisory)
+        run: bun run knip
+        continue-on-error: true
+
+      # BLOCKS — the site must compile (vite build does NOT typecheck).
+      - name: Build (vite)
+        run: bun run build
+`;
+}
+
+const NO_SUPPRESSIONS_SH = `#!/usr/bin/env bash
+set -euo pipefail
+
+# Gate: NO new type suppression + zero preact import.
+#
+# A migration leaves behind some @ts-expect-error/@ts-ignore. This gate keeps
+# that debt from GROWING: existing suppressions are grandfathered in the
+# allowlist (tools/gates/suppressions-allowlist.txt); any suppression outside it
+# fails the PR. As the type debt zeroes out, remove entries from the allowlist —
+# it only shrinks, never grows.
+#
+# Allowlist format: "path/file.ts:123" (the exact path:line from \`git grep -n\`).
+# Blank lines and "#" are ignored. If you touched a file and an existing
+# suppression's line number moved, update its entry — do not add a new one.
+#
+# Usage: bash tools/gates/no-suppressions.sh
+
+ROOT_DIR="\$(cd "\$(dirname "\${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "\$ROOT_DIR"
+
+ALLOWLIST="tools/gates/suppressions-allowlist.txt"
+SELF_PATH="tools/gates/no-suppressions.sh"
+EXIT_CODE=0
+
+SCAN_PATHS=(-- 'src/' 'tools/' ":(exclude)\${SELF_PATH}" ":(exclude)\${ALLOWLIST}")
+SUPPRESSION_PATTERN='@ts-expect-error|@ts-ignore'
+
+echo "== gate: no new type suppression (\${SUPPRESSION_PATTERN}) =="
+RAW_MATCHES="\$(git grep -nE "\${SUPPRESSION_PATTERN}" "\${SCAN_PATHS[@]}" 2>/dev/null || true)"
+
+if [ -n "\$RAW_MATCHES" ]; then
+  VIOLATIONS=""
+  while IFS= read -r match; do
+    [ -z "\$match" ] && continue
+    path_line="\$(echo "\$match" | cut -d: -f1,2)"
+    if [ -f "\$ALLOWLIST" ] && grep -qxF "\$path_line" "\$ALLOWLIST"; then
+      continue
+    fi
+    VIOLATIONS="\${VIOLATIONS}\${match}"\$'\\n'
+  done <<<"\$RAW_MATCHES"
+
+  if [ -n "\$VIOLATIONS" ]; then
+    echo "FAILED: type suppression outside the allowlist:"
+    echo "\$VIOLATIONS"
+    echo "Fix the type at the source instead of suppressing. If an existing line"
+    echo "only changed number, update its allowlist entry (do not create a new one)."
+    EXIT_CODE=1
+  fi
+fi
+
+echo "== gate: zero preact import =="
+# Matches REAL import specifiers ("preact", "preact/hooks", "@preact/signals"…),
+# not the bare word "preact". Requires straight quotes around the specifier.
+PREACT_IMPORT_PATTERN='["'"'"'](@preact/[a-zA-Z0-9_-]+|preact(/[a-zA-Z0-9_-]+)*)["'"'"']'
+PREACT_MATCHES="\$(git grep -nE "\${PREACT_IMPORT_PATTERN}" "\${SCAN_PATHS[@]}" 2>/dev/null || true)"
+if [ -n "\$PREACT_MATCHES" ]; then
+  echo "FAILED: preact import found (this stack is React, not Preact):"
+  echo "\$PREACT_MATCHES"
+  EXIT_CODE=1
+fi
+
+if [ "\$EXIT_CODE" -eq 0 ]; then
+  echo "OK: no new suppression, no preact import."
+fi
+
+exit "\$EXIT_CODE"
+`;
+
+const SUPPRESSIONS_ALLOWLIST = `# Grandfathered type suppressions (path:line from \`git grep -n\`).
+# Seed this with the migration's leftover offenders to flip the CI
+# no-suppressions gate from advisory to blocking:
+#   git grep -nE '@ts-expect-error|@ts-ignore' -- src/ tools/ >> tools/gates/suppressions-allowlist.txt
+# This list only shrinks — never add a new entry for new code.
+`;

package/scripts/migrate/templates/main-push-guard-yml.ts

@@ -0,0 +1,45 @@
+/**
+ * Scaffolds `.github/workflows/main-push-guard.yml` — a branch-protection
+ * surrogate. It does NOT block the push (real branch protection would, before
+ * the fact); it fails visibly in the Actions history when a commit reaches main
+ * without going through a PR (the "never commit straight to main" convention).
+ *
+ * Heuristic: GET /repos/{owner}/{repo}/commits/{sha}/pulls returns the PRs
+ * associated with a commit (including the merge/squash/rebase GitHub records on
+ * main when a PR merges). Empty list = the commit did not come from a PR.
+ *
+ * Fully generic — no per-site parameters.
+ */
+export function generateMainPushGuardYml(): string {
+  return `name: main-push-guard
+
+# Branch-protection surrogate: detects a commit that reaches main WITHOUT a PR.
+# Does not block the push — only fails visibly in the Actions history when the
+# "never commit straight to main" convention is broken.
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check that the commit on main came from a merged PR
+        env:
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          REPO: \${{ github.repository }}
+          SHA: \${{ github.sha }}
+        run: |
+          count="\$(gh api "repos/\${REPO}/commits/\${SHA}/pulls" --jq 'length')"
+          if [ "\$count" -eq 0 ]; then
+            echo "::error::commit \${SHA} reached main with no associated PR (direct push). Convention: one issue = one PR, never commit straight to main."
+            exit 1
+          fi
+          echo "OK: commit \${SHA} associated with \${count} PR(s)."
+`;
+}

package/scripts/migrate/templates/package-json.ts

@@ -12,6 +12,14 @@ import type { MigrationContext } from "../types";
  */
 export const CANONICAL_BUN_VERSION = "1.3.5";
 
+/**
+ * Fleet-wide canonical Node version. Used by the scaffolded CI / Playwright
+ * workflows' setup-node step (kept in lockstep with the perf workflow's pinned
+ * node-version). 22.15 is the floor for @cloudflare/vite-plugin's
+ * module.registerHooks.
+ */
+export const CANONICAL_NODE_VERSION = "22.15.0";
+
 /**
  * Get the latest published version of an npm package.
  * Falls back to the provided default if the lookup fails.
@@ -145,6 +153,7 @@ export function generatePackageJson(ctx: MigrationContext): string {
       format: 'prettier --write "src/**/*.{ts,tsx}"',
       "format:check": 'prettier --check "src/**/*.{ts,tsx}"',
       knip: "knip",
+      "test:e2e": "playwright test",
       clean:
         "rm -rf node_modules .cache dist .wrangler/state node_modules/.vite && bun install",
       "tailwind:lint":
@@ -174,6 +183,7 @@ export function generatePackageJson(ctx: MigrationContext): string {
     devDependencies: {
       "@cloudflare/vite-plugin": "^1.27.0",
       "@decocms/blocks-cli": `^${frameworkVersion}`,
+      "@playwright/test": "^1.62.1",
       // CLI build of src/styles/app.css — used by the migration's own
       // css-compile-check.ts (phase-compile) and by `tailwind:lint`, so a
       // dropped custom theme token fails migration/CI instead of shipping

package/scripts/migrate/templates/perf-yml.ts

@@ -3,14 +3,16 @@
  *   .github/workflows/perf.yml     — GitHub Actions workflow
  *   tools/perf/changed-paths.sh    — maps edited sections → CMS page paths
  *   tools/perf/compare.mjs         — compares two LHCI result dirs, emits markdown
- *   lighthouserc.json              — LHCI collect settings (3 runs, mobile UA)
+ *   lighthouserc.json              — LHCI collect settings (3 runs, mobile UA, 4 categories)
  *
  * Design rationale:
  *   - CF Workers Builds generates a per-PR preview URL (workers.dev). Both the
  *     PR and main previews are workers.dev — no edge cache — so the delta is
  *     purely code, not cache state.
- *   - Gate signal = CLS + TBT (layout stability / JS work; cache-insensitive).
- *     LCP and score are informational only (noisy on cold SSR).
+ *   - Gate signal = CLS + TBT + a11y/best-practices/SEO scores. CLS/TBT are
+ *     layout stability / JS work; the three category scores are static-analysis
+ *     audits. All cache-insensitive, so a regression is real code, not cold SSR.
+ *     LCP and performance score are informational only (noisy on cold SSR).
  *   - Advisory: `continue-on-error: true`. Remove it once the site stabilises.
  *   - LHCI 0.15 does not write manifest.json; compare.mjs reads lhr-*.json
  *     directly and selects the median run by performance score.
@@ -40,7 +42,7 @@ function generatePerfYml(workerName: string): string {
 # preview URL do output — sem token CF nem build local.
 #
 # Baseline: URL fixa da preview do main (https://${workerName}.deco-cx.workers.dev).
-# Gate: CLS + TBT (estrutura/JS, insensíveis a cache). LCP/score: informativos.
+# Gate: CLS + TBT + A11y/BP/SEO (estrutura/JS + auditorias estáticas, insensíveis a cache). LCP/score: informativos.
 
 on:
   pull_request:
@@ -297,8 +299,10 @@ const COMPARE_MJS = `#!/usr/bin/env node
 // cache, same runner/region, same mobile UA — so the delta is the PR's code
 // effect, not cache warm/cold.
 //
-// Gate signal = CLS + TBT (page structure / JS work — cache-insensitive).
-// LCP / score are shown but informative only (noisy on cold workers.dev SSR).
+// Gate signal = CLS + TBT + a11y/best-practices/SEO scores. CLS/TBT are page
+// structure / JS work; the three category scores are static-analysis audits.
+// All are cache-insensitive, so a regression is real code, not cold SSR.
+// LCP / performance score are shown but informative only (noisy on cold workers.dev SSR).
 //
 // LHCI 0.15 does not write manifest.json; we read lhr-*.json directly.
 //
@@ -312,7 +316,12 @@ const TBT_ABS = 50; // ms — deltas below this are noise
 const TBT_REL = 0.15; // 15% relative change
 const CLS_ABS = 0.02; // absolute CLS delta that matters
 const CLS_FLOOR = 0.1; // only flag CLS regression when PR is above "good"
+const SCORE_DROP = 3; // pts — a11y/bp/seo score drop that gates (tolerates 1–2pt audit jitter)
+const SCORES = ["a11y", "bp", "seo"]; // gated category scores (0–100)
 
+// base/pr = { tbt, cls, a11y, bp, seo }. Called from selftest with only
+// { tbt, cls }: the SCORES deltas become NaN and NaN comparisons are false,
+// so score gating is simply inert there.
 function verdict(base, pr) {
   const tbtUp = pr.tbt - base.tbt;
   const tbtBad = tbtUp > TBT_ABS && tbtUp > base.tbt * TBT_REL;
@@ -320,8 +329,10 @@ function verdict(base, pr) {
   const clsUp = pr.cls - base.cls;
   const clsBad = clsUp > CLS_ABS && pr.cls > CLS_FLOOR;
   const clsGood = -clsUp > CLS_ABS && base.cls > CLS_FLOOR;
-  if (tbtBad || clsBad) return { icon: "🔴", gate: true };
-  if (tbtGood || clsGood) return { icon: "🟢", gate: false };
+  const scoreBad = SCORES.some((k) => pr[k] - base[k] <= -SCORE_DROP);
+  const scoreGood = !scoreBad && SCORES.some((k) => pr[k] - base[k] >= SCORE_DROP);
+  if (tbtBad || clsBad || scoreBad) return { icon: "🔴", gate: true };
+  if (tbtGood || clsGood || scoreGood) return { icon: "🟢", gate: false };
   return { icon: "⚪", gate: false };
 }
 
@@ -340,7 +351,10 @@ function loadDir(dir) {
     const lhr = runs[Math.floor(runs.length / 2)];
     const a = lhr.audits;
     byPath[new URL(url).pathname] = {
-      score: Math.round((lhr.categories.performance.score ?? 0) * 100),
+      score: Math.round((lhr.categories.performance?.score ?? 0) * 100),
+      a11y: Math.round((lhr.categories.accessibility?.score ?? 0) * 100),
+      bp: Math.round((lhr.categories["best-practices"]?.score ?? 0) * 100),
+      seo: Math.round((lhr.categories.seo?.score ?? 0) * 100),
       lcp: a["largest-contentful-paint"].numericValue,
       cls: a["cumulative-layout-shift"].numericValue,
       tbt: a["total-blocking-time"].numericValue,
@@ -351,11 +365,14 @@ function loadDir(dir) {
 
 const ms = (v) => \`\${Math.round(v)}ms\`;
 const cls = (v) => v.toFixed(3);
+const pts = (v) => \`\${Math.round(v)}\`;
 function delta(base, pr, fmt) {
   const d = pr - base;
   const arrow = d < 0 ? "↓" : d > 0 ? "↑" : "";
   return \`\${d > 0 ? "+" : ""}\${fmt(d)} \${arrow}\`.trim();
 }
+// base→PR (Δ) for a 0–100 category score.
+const scoreCell = (b, p) => \`\${b}→\${p} (\${delta(b, p, pts)})\`;
 
 function render(base, pr) {
   const paths = [...new Set([...Object.keys(base), ...Object.keys(pr)])].sort();
@@ -365,29 +382,29 @@ function render(base, pr) {
     "",
     "Ambas as previews rodam em \`*.workers.dev\` (sem edge cache), mesmo runner e UA mobile — o delta é efeito do código, não de cache quente/frio.",
     "",
-    "**Gate:** CLS + TBT (estrutura / JS). LCP e score são informativos (ruído esperado em SSR frio).",
+    "**Gate:** CLS + TBT + A11y/BP/SEO (estrutura/JS + auditorias estáticas). LCP e score de performance são informativos (ruído esperado em SSR frio).",
     "",
-    "| Página | | CLS (base→PR) | TBT (base→PR) | LCP | Score |",
-    "|---|:--:|---|---|---|---|",
+    "| Página | | CLS (base→PR) | TBT (base→PR) | A11y | BP | SEO | LCP | Score |",
+    "|---|:--:|---|---|---|---|---|---|---|",
   ];
   for (const p of paths) {
     const b = base[p];
     const r = pr[p];
     if (!b || !r) {
-      lines.push(\`| \\\`\${p}\\\` | ⚠️ | \${b ? "faltou PR" : "faltou base"} | | | |\`);
+      lines.push(\`| \\\`\${p}\\\` | ⚠️ | \${b ? "faltou PR" : "faltou base"} | | | | | | |\`);
       continue;
     }
     const v = verdict(b, r);
     anyGate = anyGate || v.gate;
     lines.push(
-      \`| \\\`\${p}\\\` | \${v.icon} | \${cls(b.cls)}→\${cls(r.cls)} (\${delta(b.cls, r.cls, cls)}) | \${ms(b.tbt)}→\${ms(r.tbt)} (\${delta(b.tbt, r.tbt, ms)}) | \${ms(b.lcp)}→\${ms(r.lcp)} | \${b.score}→\${r.score} |\`,
+      \`| \\\`\${p}\\\` | \${v.icon} | \${cls(b.cls)}→\${cls(r.cls)} (\${delta(b.cls, r.cls, cls)}) | \${ms(b.tbt)}→\${ms(r.tbt)} (\${delta(b.tbt, r.tbt, ms)}) | \${scoreCell(b.a11y, r.a11y)} | \${scoreCell(b.bp, r.bp)} | \${scoreCell(b.seo, r.seo)} | \${ms(b.lcp)}→\${ms(r.lcp)} | \${b.score}→\${r.score} |\`,
     );
   }
   lines.push("");
   lines.push(
     anyGate
-      ? "🔴 **Regressão de CLS/TBT detectada** (advisory — não trava o merge)."
-      : "🟢 Sem regressão de CLS/TBT.",
+      ? "🔴 **Regressão detectada em CLS/TBT/A11y/BP/SEO** (advisory — não trava o merge)."
+      : "🟢 Sem regressão nas métricas gateadas (CLS/TBT/A11y/BP/SEO).",
   );
   return { md: lines.join("\\n"), anyGate };
 }
@@ -400,6 +417,13 @@ function selftest() {
   ok(!verdict({ tbt: 100, cls: 0.02 }, { tbt: 100, cls: 0.08 }).gate, "cls under 0.1 floor no gate");
   ok(verdict({ tbt: 300, cls: 0.01 }, { tbt: 100, cls: 0.01 }).icon === "🟢", "tbt drop is green");
   ok(verdict({ tbt: 100, cls: 0.01 }, { tbt: 105, cls: 0.01 }).icon === "⚪", "tiny change is neutral");
+  // Category-score gating. S() supplies a neutral CLS/TBT baseline plus perfect scores.
+  const S = (o) => ({ tbt: 100, cls: 0.01, a11y: 100, bp: 100, seo: 100, ...o });
+  ok(verdict(S({}), S({ seo: 96 })).gate, "seo 100→96 (-4) should gate");
+  ok(verdict(S({ a11y: 90 }), S({ a11y: 87 })).gate, "a11y -3 should gate");
+  ok(!verdict(S({}), S({ bp: 98 })).gate, "bp -2 is jitter, no gate");
+  ok(verdict(S({ a11y: 90 }), S({ a11y: 95 })).icon === "🟢", "a11y +5 is green");
+  ok(verdict(S({}), S({ a11y: 99, seo: 97 })).icon === "🔴", "seo -3 gates even with a11y -1");
   console.log("compare.mjs selftest: OK");
 }
 
@@ -411,12 +435,12 @@ process.stdout.write(render(loadDir(baseDir), loadDir(prDir)).md + "\\n");
 `;
 
 const LIGHTHOUSERC_JSON = `{
-  "//": "Lighthouse CI config for the per-PR perf workflow (.github/workflows/perf.yml). Mobile UA matches worker-entry.ts buildSegment (MOBILE_RE) so warmup and measurement hit the same device cache key.",
+  "//": "Lighthouse CI config for the per-PR perf workflow (.github/workflows/perf.yml). Mobile UA matches worker-entry.ts buildSegment (MOBILE_RE) so warmup and measurement hit the same device cache key. accessibility/best-practices/seo são análise estática determinística (não sofrem ruído de SSR frio como LCP/score), então compare.mjs os gateia por regressão de score.",
   "ci": {
     "collect": {
       "numberOfRuns": 3,
       "settings": {
-        "onlyCategories": ["performance"],
+        "onlyCategories": ["performance", "accessibility", "best-practices", "seo"],
         "emulatedUserAgent": "Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36"
       }
     }

package/scripts/migrate/templates/playwright-yml.ts

@@ -0,0 +1,127 @@
+/**
+ * Scaffolds the E2E harness and its config/smoke companions:
+ *   .github/workflows/playwright.yml  — GitHub Actions workflow (chromium + webkit)
+ *   playwright.config.ts              — self-contained config (no support helpers)
+ *   tests/e2e/smoke.spec.ts           — harness smoke, no app boot, no network
+ *
+ * Design rationale:
+ *   - The smoke proves the Playwright harness runs in CI (chromium + webkit)
+ *     without the app booting or hitting the network — it renders inline HTML
+ *     via page.setContent. Real storefront specs (page.goto("/")) need a VCR
+ *     layer so CI does not hit the commerce API; add a `webServer` block to the
+ *     config and specs that navigate the app once that harness exists.
+ *   - webkit is included because the storefront audience is majority iOS Safari.
+ *   - The workflow needs `@playwright/test` + the `test:e2e` script, both in the
+ *     scaffolded package.json.
+ *
+ * @param bunVersion  Bun version for setup-bun (= CANONICAL_BUN_VERSION).
+ */
+export function generatePlaywrightFiles(bunVersion: string): Record<string, string> {
+  const bun = bunVersion.replace(/^bun@/, "");
+  return {
+    ".github/workflows/playwright.yml": generatePlaywrightYml(bun),
+    "playwright.config.ts": PLAYWRIGHT_CONFIG,
+    "tests/e2e/smoke.spec.ts": SMOKE_SPEC,
+  };
+}
+
+function generatePlaywrightYml(bunVersion: string): string {
+  return `name: Playwright
+
+# Functional E2E (chromium + webkit). Today only a harness smoke that renders
+# inline HTML — no app boot, no network — so it runs on a plain ubuntu runner.
+# When specs navigate the real app (via VCR), pin the container and add a
+# webServer block to playwright.config.ts.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: playwright-\${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "${bunVersion}"
+
+      - name: bun install --frozen-lockfile
+        run: bun install --frozen-lockfile
+
+      - name: Install browsers (chromium + webkit)
+        run: bunx playwright install --with-deps chromium webkit
+
+      - name: E2E
+        run: bun run test:e2e
+
+      - name: Upload HTML report
+        if: \${{ !cancelled() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 14
+`;
+}
+
+const PLAYWRIGHT_CONFIG = `/**
+ * Playwright config — E2E base.
+ *
+ * Today only a harness smoke (tests/e2e/smoke.spec.ts) that renders inline HTML,
+ * proving the harness runs in CI without the app booting or hitting the network.
+ * Real app E2E (page.goto("/")) needs a VCR layer so CI does not call the
+ * commerce API — add a \`webServer\` block (e.g. { command: "bun run build && bun
+ * run preview", url: "http://localhost:4173" }) and the navigating specs then.
+ *
+ * chromium + webkit (webkit because the storefront audience is majority iOS
+ * Safari). 1 worker, 0 retries on purpose: retry masks flake instead of exposing it.
+ */
+
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: 0,
+  workers: 1,
+  reporter: [["html", { open: "never" }], ["list"]],
+  use: {
+    trace: "retain-on-failure",
+    screenshot: "only-on-failure",
+  },
+  projects: [
+    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "webkit", use: { ...devices["Desktop Safari"] } },
+  ],
+});
+`;
+
+const SMOKE_SPEC = `/**
+ * Smoke E2E — proves the Playwright harness runs (chromium + webkit) in CI
+ * without the app booting or hitting the network. Does not test the real app;
+ * the storefront E2E (page.goto("/")) comes with the VCR + cassettes harness.
+ */
+
+import { expect, test } from "@playwright/test";
+
+test("harness renders inline content", async ({ page }) => {
+  await page.setContent(
+    '<title>e2e smoke</title><h1>ok</h1><div data-testid="marker">ready</div>',
+  );
+
+  await expect(page).toHaveTitle("e2e smoke");
+  await expect(page.getByRole("heading", { name: "ok" })).toBeVisible();
+  await expect(page.getByTestId("marker")).toHaveText("ready");
+});
+`;

package/scripts/migrate/templates/react-doctor-yml.ts

@@ -0,0 +1,46 @@
+/**
+ * Scaffolds `.github/workflows/react-doctor.yml` — flags React
+ * security/perf/correctness/a11y/bundle-size/architecture issues on PRs.
+ *
+ * Advisory by construction (the action's default: comments, never fails the
+ * build). Separate workflow from ci.yml on purpose — zero coupling with the
+ * blocking gates. `fetch-depth: 0` gives the merge-base so it reports only what
+ * the PR introduces.
+ *
+ * Fully generic — no per-site parameters. Docs: https://www.react.doctor/ci
+ */
+export function generateReactDoctorYml(): string {
+  return `name: React Doctor
+
+# Flags React security/perf/correctness/a11y/bundle-size/architecture issues.
+# Advisory by construction (comments, never fails the check). To make it a hard
+# gate, add \`with: { blocking: error }\` to the action step below.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  statuses: write
+
+concurrency:
+  group: react-doctor-\${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  react-doctor:
+    runs-on: ubuntu-latest
+    steps:
+      # fetch-depth: 0 gives the merge-base so it reports only PR-introduced findings.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: millionco/react-doctor@v2
+`;
+}