netcracker/ai-for-dummies
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

build: migrate from npm to pnpm

Browse Source 
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>
This commit is contained in:
Marcos Paulo
2026-09-05 04:29:42 +00:00
parent 63da0a4727
commit 48c31dc1b3
53 changed files with 5958 additions and 9642 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/rules/gates.md
+14 -12
View File
@@ -4,15 +4,15 @@ Three tiers. Each is scoped so that **many agents committing in parallel
worktrees stay fast** — the whole point is that a gate you are tempted to skip
is not a gate.
| Tier | Hook | Scope | Budget | Runs |
| --- | --- | --- | --- | --- |
| 1 | `pre-commit` | **staged files only** (lint-staged) | < 3s | every commit |
| 2 | `pre-push` | whole project: build + verify + audit | < 90s | every push |
| 3 | CI (Gitea Actions) | tier 2 + visual regression | minutes | every push to `main` |
| Tier | Hook | Scope | Budget | Runs |
| ---- | ------------------ | ------------------------------------- | ------- | -------------------- |
| 1 | `pre-commit` | **staged files only** (lint-staged) | < 3s | every commit |
| 2 | `pre-push` | whole project: build + verify + audit | < 90s | every push |
| 3 | CI (Gitea Actions) | tier 2 + visual regression | minutes | every push to `main` |
Tier 1 must stay under a few seconds. If it creeps, move the check to tier 2.
An agent that waits 40s per commit will start passing `--no-verify`, and then
you have no gate at all.
Tier 1 must stay under a few seconds. If it creeps, move the check to tier 2. An
agent that waits 40s per commit will start passing `--no-verify`, and then you
have no gate at all.
## Tier 1 — pre-commit (lint-staged)
@@ -21,7 +21,8 @@ parallel worktrees do ten small jobs, not ten full-project sweeps.
- Prettier + ESLint on `*.{js,mjs,ts,astro}`
- Prettier + Stylelint on `*.css`
- `check-tokens.mjs` on changed `.astro`/`.css` — catches raw hex before it lands
- `check-tokens.mjs` on changed `.astro`/`.css` — catches raw hex before it
lands
- Prettier on `*.{json,md}`
## Tier 2 — pre-push
@@ -56,13 +57,14 @@ If a gate is wrong, fix the gate in its own commit. Do not route around it.
- The heavy tier-2 gate takes a **lock** (`.git/af-gate.lock`, shared across
worktrees) so ten agents pushing at once do not run ten concurrent builds and
thrash the machine. Waiters queue; they do not fail.
- `npm ci` in a fresh worktree should use `--prefer-offline` to avoid registry
contention when several spin up at once.
- `pnpm install --frozen-lockfile` in a fresh worktree is cheap: pnpm hardlinks
from the shared content-addressable store, so a second worktree costs seconds
and almost no disk instead of another 225 MB. No `--prefer-offline` needed.
## The silent-failure mode you must know about
Husky sets `core.hooksPath` to `.husky/_`, and **`.husky/_` is generated by
`npm install`, not committed**. A fresh `git worktree add` therefore has hooks
`pnpm install`, not committed**. A fresh `git worktree add` therefore has hooks
configured but the directory missing — so **hooks silently do not run**. Every
commit passes. Nothing is checked.