@decocms/blocks-cli 8.0.0 → 8.1.0-next.0

package/scripts/migrate/templates/app-css.test.ts

@@ -12,6 +12,8 @@ describe("generateAppCss — tailwind.config.ts porting", () => {
       colors: { perola: "#F5F0E8", "brand-500": "#B10200" },
       fontFamily: { "bebas-neue": "Bebas Neue, sans-serif" },
       screens: { "3xl": "1920px" },
+      animations: {},
+      keyframes: {},
       safelist: ["bg-red-500", "text-brand-500"],
       safelistPatterns: [],
       plugins: [],
@@ -27,6 +29,28 @@ describe("generateAppCss — tailwind.config.ts porting", () => {
     expect(css).toContain('@source inline("bg-red-500 text-brand-500");');
   });
 
+  it("emits --animate-* in @theme and @keyframes blocks from tailwind.config.ts", () => {
+    const ctx = createContext("/tmp/does-not-exist");
+    ctx.tailwindConfig = {
+      colors: {},
+      fontFamily: {},
+      screens: {},
+      animations: { "fade-in": "fadeIn 0.5s ease-in" },
+      keyframes: { fadeIn: { "0%": "opacity: 0", "100%": "opacity: 1" } },
+      safelist: [],
+      safelistPatterns: [],
+      plugins: [],
+      reviewItems: [],
+    };
+
+    const css = generateAppCss(ctx);
+
+    expect(css).toContain("--animate-fade-in: fadeIn 0.5s ease-in;");
+    expect(css).toContain("@keyframes fadeIn {");
+    expect(css).toContain("0% { opacity: 0; }");
+    expect(css).toContain("100% { opacity: 1; }");
+  });
+
   it("does not duplicate a custom color that collides with a daisyUI semantic key", () => {
     const ctx = createContext("/tmp/does-not-exist");
     ctx.tailwindConfig.colors = { primary: "#000000" };

package/scripts/migrate/templates/app-css.ts

@@ -240,6 +240,15 @@ ${colorLines}
     }
   }
 
+  const twAnimations = ctx.tailwindConfig.animations;
+  const twAnimationKeys = Object.keys(twAnimations);
+  if (twAnimationKeys.length > 0) {
+    themeBlock += `\n\n  /* Custom animations ported from tailwind.config.ts */`;
+    for (const key of twAnimationKeys) {
+      themeBlock += `\n  --animate-${key}: ${twAnimations[key]};`;
+    }
+  }
+
   // Gray scale compat (Tailwind v3 had gray-50..gray-950 by default) — uses
   // the site's own tailwind.config.ts gray-* override when present, falling
   // back to the v3 default otherwise.
@@ -254,6 +263,16 @@ ${colorLines}
   themeBlock += `\n}`;
   sections.push(themeBlock);
 
+  // Emit @keyframes for each extracted keyframe from tailwind.config.ts.
+  // TW4 has no keyframes config — they must live in CSS directly.
+  const twKeyframes = ctx.tailwindConfig.keyframes;
+  for (const [name, stops] of Object.entries(twKeyframes)) {
+    const stopLines = Object.entries(stops)
+      .map(([pct, props]) => `  ${pct} { ${props}; }`)
+      .join("\n");
+    sections.push(`@keyframes ${name} {\n${stopLines}\n}`);
+  }
+
   // ── DaisyUI v5 compat ─────────────────────────────────────────────
   sections.push(`/* DaisyUI v5: flatten depth/noise to match v4 look */
 :root {
@@ -353,6 +372,14 @@ section[data-deferred="true"] {
     overflow: hidden;
   }
 
+  /* Tailwind v3 -> v4 compat: restore the default border-color.
+     TW4 Preflight changed border-color from gray-200 (#e5e7eb) to currentColor --
+     any element with "border" but no explicit "border-{color}" now renders black.
+     --color-gray-200 is always defined in the ported @theme (gray scale compat block). */
+  *, *::before, *::after {
+    border-color: var(--color-gray-200, #e5e7eb);
+  }
+
   /* Tailwind v3 → v4 compat: restore the default cursor:pointer on interactive
      elements. Tailwind v4 dropped this from Preflight, leaving Fresh-era sites
      with hundreds of buttons looking unclickable. See:

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

@@ -0,0 +1,179 @@
+import { describe, expect, it } from "vitest";
+import { generateCiFiles } from "./ci-yml";
+import { generateMainPushGuardYml } from "./main-push-guard-yml";
+import { generateParityYml } from "./parity-yml";
+import { generatePlaywrightFiles } from "./playwright-yml";
+import { generateReactDoctorYml } from "./react-doctor-yml";
+import { generateSyncBlocksBotYml } from "./sync-blocks-bot-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 site-specific migration-debt refs", () => {
+    const blob = Object.values(files).join("\n");
+    expect(blob).not.toMatch(/sitea|siteb/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);
+  });
+});
+
+describe("generateParityYml", () => {
+  const yml = generateParityYml("loja-tanstack");
+  it("runs parity journey advisory, gated on PARITY_PROD_URL", () => {
+    expect(yml).toContain("name: Parity");
+    expect(yml).toContain("continue-on-error: true"); // advisory, never blocks
+    expect(yml).toContain("vars.PARITY_PROD_URL"); // prod = original storefront
+    expect(yml).toContain("bunx @decocms/parity journey");
+    expect(yml).toContain("--junit parity-results.xml");
+    expect(yml).toContain("--github");
+    expect(yml).toContain("Workers Builds: loja-tanstack"); // worker name interpolated
+    expect(yml).toContain("secrets.ANTHROPIC_API_KEY"); // optional LLM key
+  });
+});
+
+describe("generateSyncBlocksBotYml", () => {
+  const yml = generateSyncBlocksBotYml("bun@1.3.5");
+
+  it("pulls on a daily cron, gated on SYNC_BLOCKS_ORIGIN", () => {
+    expect(yml).toContain("name: sync-blocks-bot");
+    expect(yml).toContain('BUN_VERSION: "1.3.5"'); // bun@ prefix stripped
+    expect(yml).toContain('- cron: "0 6 * * *"');
+    expect(yml).toContain("vars.SYNC_BLOCKS_ORIGIN");
+    expect(yml).toContain("scripts/sync-blocks-bot.ts");
+    expect(yml).toContain("--fail-on-plaintext-secret");
+  });
+
+  it("only ever needs GITHUB_TOKEN — no cross-repo credential", () => {
+    expect(yml).toContain("secrets.GITHUB_TOKEN");
+    expect(yml).not.toMatch(/secrets\.(?!GITHUB_TOKEN)[A-Z_]+/);
+    expect(yml).toContain("permissions:");
+    expect(yml).toContain("concurrency:");
+  });
+
+  it("guards the diff to .deco/blocks and builds before opening the PR", () => {
+    const guardIdx = yml.indexOf("Guard");
+    const buildIdx = yml.indexOf("Validar (generate + build)");
+    const prIdx = yml.indexOf("gh pr create");
+    expect(guardIdx).toBeGreaterThan(-1);
+    expect(guardIdx).toBeLessThan(buildIdx);
+    expect(buildIdx).toBeLessThan(prIdx);
+    expect(yml).toContain("grep -v '^\\.deco/blocks/'");
+    expect(yml).toContain("git add .deco/blocks");
+  });
+
+  it("is de-projectized — no real site/customer names", () => {
+    expect(yml).not.toMatch(/sitea|acme|siteb/i);
+  });
+
+  it("runs the site's own installed CLI, or a pinned one when given", () => {
+    expect(yml).toContain("bunx tsx node_modules/@decocms/blocks-cli/scripts/sync-blocks-bot.ts");
+    const pinned = generateSyncBlocksBotYml("1.3.5", "7.51.0");
+    // `npx --package=<pkg> <bin>`, never `bunx <pkg> <bin>` — the latter treats
+    // the bin name as an argument and silently runs deco-migrate instead.
+    expect(pinned).toContain("npx --yes --package=@decocms/blocks-cli@7.51.0 deco-sync-blocks-bot");
+    expect(pinned).not.toMatch(/bunx\s+(-y\s+)?@decocms\/blocks-cli/);
+    expect(pinned).not.toContain("node_modules/@decocms/blocks-cli");
+  });
+
+  it("cannot pass green having run the wrong tool", () => {
+    // pipefail so `| tee` doesn't swallow the plaintext-secret exit 1, plus a
+    // grep on the report that only this script emits.
+    expect(yml).toContain("set -o pipefail");
+    expect(yml).toContain("--json --github");
+    expect(yml).toContain(`grep -q '"remoteBlocks"'`);
+  });
+});

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/cursor-rules.test.ts

@@ -58,8 +58,8 @@ describe("generateMigrationPolicyPointerRule", () => {
 	it("escapes nothing weird from siteName — siteName is used as a label only", () => {
 		// We don't sanitise; we trust the migration script to pass a real
 		// package name. But verify nothing surprising happens with hyphens
-		// (a common shape, e.g. "casaevideo-storefront").
-		const out = generateMigrationPolicyPointerRule("casaevideo-storefront");
-		expect(out).toContain("`casaevideo-storefront`");
+		// (a common shape, e.g. "acme-storefront").
+		const out = generateMigrationPolicyPointerRule("acme-storefront");
+		expect(out).toContain("`acme-storefront`");
 	});
 });

package/scripts/migrate/templates/hooks.test.ts

@@ -12,7 +12,9 @@ function makeCtx(platform: MigrationContext["platform"]): MigrationContext {
 		importMap: {},
 		discoveredNpmDeps: {},
 		themeColors: {},
-	tailwindConfig: { colors: {}, fontFamily: {}, screens: {}, safelist: [], safelistPatterns: [], plugins: [], reviewItems: [] },
+	tailwindConfig: { colors: {}, fontFamily: {}, screens: {}, animations: {}, keyframes: {}, safelist: [], safelistPatterns: [], plugins: [], reviewItems: [] },
+	layout: "classic",
+	googleFonts: { preconnects: [], stylesheets: [] },
 		fontFamily: null,
 		files: [],
 		sectionMetas: [],

package/scripts/migrate/templates/lib-utils.ts

@@ -9,7 +9,7 @@
  * - Most sites end up importing zero of these (apps-start exports
  *   direct equivalents for most VTEX utilities — see migrate#107).
  * - Eager generation creates dead `src/lib/*.ts` files that every site
- *   then has to clean up by hand (see baggagio-tanstack#7, ~235 LOC).
+ *   then has to clean up by hand (~235 LOC on one production migration).
  *
  * Registry shape: `"src/lib/<name>.ts"` → file contents.
  */
@@ -41,8 +41,8 @@ export function selectImportedLibTemplates(
 // Per the migration tooling policy (D3 — Throwing stubs):
 // generated stubs MUST throw at runtime so the first call surfaces the
 // gap loudly. Silent identity-cast `toProduct` was the bug behind
-// baggagio-tanstack#10 (PDP product data was being dropped on the floor
-// for weeks before anyone noticed).
+// a real production incident (PDP product data was being dropped on the
+// floor for weeks before anyone noticed).
 //
 // Each thrown message points at the canonical replacement so the fix
 // is mechanical. `deco-post-cleanup --fix` automates the swap.

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