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.
.agents/rules/git-worktrees.md
+14 -12
View File
@@ -8,7 +8,7 @@ This project teaches worktrees. It should use them properly.
# from the main checkout
git worktree add ../af-task-07 -b refactor/task-07-route-cards
cd ../af-task-07
npm ci
pnpm install --frozen-lockfile
```
Naming: directory `../af-task-NN`, branch `refactor/task-NN-<slug>`. Both
@@ -18,8 +18,8 @@ derived from the task file so the mapping is never ambiguous.
The migration runs many agents in parallel over the same small set of files
(`tokens.css`, `verify.mjs`, `astro.config.mjs` are contended). Worktrees give
each agent its own working directory over one object store — cheap, and no
agent can see another's half-finished state.
each agent its own working directory over one object store — cheap, and no agent
can see another's half-finished state.
The failure mode without them: two agents both "fix" `verify.mjs`, and the
second overwrites the first's assertions.
@@ -29,12 +29,12 @@ second overwrites the first's assertions.
These are touched by many tasks. Whoever owns them per the plan is the **only**
writer; everyone else opens an issue in their task report instead of editing:
| File | Owner |
| --- | --- |
| `src/styles/tokens.css` | `design-system-keeper` |
| `scripts/verify.mjs` | `verification-engineer` |
| `astro.config.mjs`, `package.json` | `astro-architect` |
| `src/content/config.ts` | `content-i18n-migrator` |
| File | Owner |
| ---------------------------------- | ----------------------- |
| `src/styles/tokens.css` | `design-system-keeper` |
| `scripts/verify.mjs` | `verification-engineer` |
| `astro.config.mjs`, `package.json` | `astro-architect` |
| `src/content/config.ts` | `content-i18n-migrator` |
## Before you start
@@ -44,7 +44,7 @@ writer; everyone else opens an issue in their task report instead of editing:
## Before you finish
1. `npm run verify` green — without deleting assertions.
1. `pnpm run verify` green — without deleting assertions.
2. The relevant checklist in [`../checklists/`](../checklists/) complete.
3. `git rebase origin/main` again, resolve conflicts in your worktree.
4. Task report: what changed, what you verified, **what you did not do**.
@@ -64,6 +64,8 @@ should be short.
- Never work directly on `main`.
- Never force-push a shared branch. The `pages` branch is the sole exception,
and only if CI owns it (see [`../context/publishing.md`](../context/publishing.md)).
and only if CI owns it (see
[`../context/publishing.md`](../context/publishing.md)).
- Never `git add -A` from the repository root. This repo has untracked local
scratch (`.serena/`, `scripts/inspect.py`) that must not be swept into a commit.
scratch (`.serena/`, `scripts/inspect.py`) that must not be swept into a
commit.
.agents/rules/theming.md
+17 -14
View File
@@ -15,7 +15,7 @@ the token layer is missing something (add it there, not inline).
```css
/* forbidden */
color: #172f42;
color: rgba(23,47,66,.6);
color: rgba(23, 47, 66, 0.6);
/* required */
color: var(--ink);
@@ -23,7 +23,7 @@ color: var(--muted);
```
No raw hex outside `tokens.css`. `.agents/scripts/check-tokens.mjs` enforces it;
wire it into `npm run verify`.
wire it into `pnpm run verify`.
## Semantic names, not literal ones
@@ -31,20 +31,20 @@ wire it into `npm run verify`.
`--deep` are the existing vocabulary. Keep it — it is already semantic and the
team reads it fluently. Do not rename to `--color-neutral-900`.
If a genuine second surface is needed, extend semantically
(`--surface-lab`, `--ink-inverse`), never numerically.
If a genuine second surface is needed, extend semantically (`--surface-lab`,
`--ink-inverse`), never numerically.
## Type scale
Replace the 14 ad-hoc `clamp()` triples with named steps:
```css
--step-display: clamp(56px, 9vw, 126px); /* h1 */
--step-6: clamp(36px, 5vw, 65px); /* section h2 */
--step-5: clamp(24px, 3vw, 38px); /* sub-head */
--step-4: clamp(22px, 3vw, 36px); /* pull-quote */
--step-1: 15px; /* body */
--step-0: 11px; /* eyebrow / label */
--step-display: clamp(56px, 9vw, 126px); /* h1 */
--step-6: clamp(36px, 5vw, 65px); /* section h2 */
--step-5: clamp(24px, 3vw, 38px); /* sub-head */
--step-4: clamp(22px, 3vw, 36px); /* pull-quote */
--step-1: 15px; /* body */
--step-0: 11px; /* eyebrow / label */
```
The eyebrow treatment (`10–11px` monospace, `letter-spacing:.08–.1em`,
@@ -56,8 +56,11 @@ repetitions.
Five named widths replace the current sixteen:
```css
--bp-sm: 560px; --bp-md: 800px; --bp-lg: 1100px;
--bp-xl: 1600px; --bp-2xl: 2200px;
--bp-sm: 560px;
--bp-md: 800px;
--bp-lg: 1100px;
--bp-xl: 1600px;
--bp-2xl: 2200px;
```
When collapsing a component's old breakpoint onto a named one, screenshot at the
@@ -74,5 +77,5 @@ When collapsing a component's old breakpoint onto a named one, screenshot at the
## Fonts
Do not add a webfont without an explicit decision recorded in the task. The
intended Manrope/DM Mono has never rendered; introducing it is a visual redesign,
not a refactor. Default: match what renders today.
intended Manrope/DM Mono has never rendered; introducing it is a visual
redesign, not a refactor. Default: match what renders today.