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

1.9 KiB

Raw Blame History

Task 03 — Verification net

Agent: verification-engineer · Model: Codex Depends on: 01 · Parallel with: 02, 04 · Blocks: 12–16 Worktree: .agents/scripts/worktree.sh start 03 verification-net

Goal

Rendered-text baselines for all ten routes, captured from the vanilla site, before any page is migrated. Without this the page migrators have nothing to diff against and "no content was lost" becomes an opinion.

This task is on the critical path. Do it early.

Scope

.agents/snapshots/, scripts/audit-ui.mjs, .agents/scripts/visual-regression.mjs.

Steps

pnpm run serve against the current, unmigrated site.

Snapshot all ten routes:

for r in "" full-guide summary models agents skills rules skills-review \
         hands-on/starter hands-on/rules; do
  node .agents/scripts/snapshot-route.mjs "http://localhost:4173/$r/" \
    > ".agents/snapshots/${r:-index}.txt"
done

Commit them. They are the regression net.

Write .agents/scripts/visual-regression.mjs (Playwright). Extend the existing scripts/inspect.py pattern rather than inventing one. Baselines to .agents/snapshots/before/.
Fix the audit gap: audit-ui.mjs rejects external <script>/<link> but misses external URLs in CSS — which is exactly how the broken Google Fonts @font-face got into this "dependency-free" site. Add @import, src: url(https:…), url(https:…).

Done when

Ten committed snapshots, each non-empty and containing that page's real prose
visual-regression.mjs captures 10 routes × 4 widths
Extended audit-ui.mjs fails on today's styles.css (prove it catches the real bug), then the dead rule is removed by task 02
pnpm run gate green

Do not

Do not change any assertion in verify.mjs yet. That is task 19, after the pages exist.

1.9 KiB Raw Blame History Unescape Escape