Files

T

Marcos Paulo 48c31dc1b3 build: migrate from npm to pnpm

Ten git worktrees each carried their own 225 MB node_modules (1.1 GB across
five) and paid 11s per `npm ci`. pnpm hardlinks from a shared store: the same
five worktrees cost ~250 MB total, and a fresh install is 4s.

What changed beyond the mechanical rename:

- `overrides` moved to `pnpm-workspace.yaml`. pnpm 11 does not read the `pnpm`
  field in package.json *or* npm's top-level `overrides`, and it fails silently
  — the vite/defu/language-server pins would have quietly stopped applying.
- Build scripts are blocked by default in pnpm; esbuild and sharp are allowed
  explicitly via `allowBuilds` (renamed from `onlyBuiltDependencies` in 11).
- `packageManager` + `engines` pin the toolchain.
- gate.sh rejects a package-lock.json/yarn.lock/bun.lock outright, so an agent
  running `npm install` out of habit fails loudly instead of building a second,
  divergent dependency tree.
- CI bootstraps pnpm with `npm install --global pnpm@11.25.0` rather than
  corepack (unbundled as of Node 25) or pnpm/action-setup (this self-hosted
  act-runner has never run a job; fetching a third-party action is not
  something to discover on the first one).

Two pre-existing CI bugs fixed while in the file:

- the gate installed with `npm install --package-lock=false`, which discarded
  the lockfile the previous session had just fixed.
- the visual-regression step imported `playwright`, which is not a dependency,
  and `visual-regression.mjs` has no compare mode anyway — in CI it overwrote
  its own baselines and passed unconditionally. Removed with a comment; it
  comes back when it can diff.

The `publish` job is now manual (`workflow_dispatch`). During the migration
dist/ holds three HTML files against the live pages branch's ten, so publishing
on every push to main would take the site down to a stub. Restore at task 20.

HANDOVER.md's incident log still says npm where it describes what happened at
the time; that is history, not a missed rename.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-05 04:29:42 +00:00

2.4 KiB

Raw Permalink Blame History

name, description

name	description
visual-regression	Prove a refactor did not change how the site looks. Use before and after any page migration, token consolidation, or breakpoint change on ai-for-dummies.

Visual regression

"Maintain the same styles" is a testable claim. Test it.

Capture

The repo already has a Playwright pattern (scripts/inspect.py). Extend it rather than inventing one.

from playwright.sync_api import sync_playwright
ROUTES = ['/', '/full-guide/', '/summary/', '/models/', '/agents/',
          '/skills/', '/rules/', '/skills-review/',
          '/hands-on/starter/', '/hands-on/rules/']
WIDTHS = [560, 800, 1100, 1600]

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    for route in ROUTES:
        for w in WIDTHS:
            page = browser.new_page(viewport={'width': w, 'height': 900})
            page.goto(f'{BASE}{route}', wait_until='networkidle')
            page.screenshot(path=f'{OUT}/{route.strip("/").replace("/","_") or "index"}-{w}.png',
                            full_page=True)
            page.close()
    browser.close()

Run once against the vanilla site (pnpm run serve), once against pnpm run preview. Keep both sets.

Compare

for f in before/*.png; do
  compare -metric AE "$f" "after/$(basename $f)" null: 2>&1   # ImageMagick
  echo "  <- $(basename $f)"
done

Pixel-exact is not the bar — antialiasing differs. Judge by eye where the metric is non-trivial, and attach the pair to the task report.

The three widths that catch the most

560px — where the 16 ad-hoc breakpoints collapse to --bp-sm. Highest risk in the whole migration.
800px — the most common existing breakpoint; layout flips here.
1600px — min-width rules that only fire on large screens are the ones nobody notices are broken.

Also screenshot at the old breakpoint values you removed (520, 530, 600, 620, 720, 850, 880, 900), not just the new ones. Regressions hide exactly there.

What a real difference looks like

Expect and accept: sub-pixel text shifts, antialiasing.

Investigate: anything that moves by more than ~2px, any colour change (that is a token bug), any element that appears or disappears (that is content loss — stop and check the snapshot diff).

Reduced motion

Capture one pass with prefers_reduced_motion='reduce'. Animations must land in their correct end state, not vanish.

2.4 KiB Raw Permalink Blame History