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

3.6 KiB

Raw Blame History

Context: publishing, and what a build step changes

How it works today

The Gitea Pages Server serves the pages branch tree directly. There is no build. main and pages end up with byte-identical trees; pages exists only because the Pages Server publishes a branch, not a directory.

Live at https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/.

Full procedure, including the fact that merge --ff-only main fails (the histories diverged), is in ../../docs/operations-guide.md.

What Astro changes

Astro emits dist/. The Pages Server cannot run a build, so something has to put built output on pages. Pick one, deliberately, in task 01:

Option	How	Cost
A. Build locally, commit `dist/` to `pages`	`pnpm run build`, copy `dist/*` into the `pages` worktree, commit	`pages` stops being "the exact source". Diffs become unreadable. Publishing depends on one workstation. Simple, no new infra.
B. Gitea Actions builds and pushes `pages`	workflow on `main` → `pnpm install --frozen-lockfile && pnpm run build` → force-push `dist/` to `pages`	`pages` becomes a machine-owned branch (force-push is fine because nothing else writes it). Needs the act-runner to be healthy. Recommended.
C. Serve from a container instead	drop Pages Server for an nginx pod behind the existing ingress	most control, most infra, changes the URL story

Recommended: B, with A as the documented manual fallback for when the runner is down. Note the known failure mode: this Gitea's act-runner registration lives in an emptyDir, so a pod restart silently kills CI until re-registered. The runbook must say "if the site stopped updating, check the runner first".

Whichever you pick, docs/operations-guide.md must be rewritten in the same task — it currently promises pages is "the exact published source", and that stops being true under A and B.

Base path

The site is served from a subdirectory: /ai-for-dummies/. Astro needs base: '/ai-for-dummies' in astro.config.mjs, and every internal link must go through import.meta.env.BASE_URL or Astro's <a href={...}> helpers rather than a hand-written absolute /models/.

This is the single most likely source of "works locally, 404s in production" in this migration. Verify it on the real host, not just pnpm run preview.

Verification before you call it published

curl -sS -o /dev/null -w '%{http_code}\n' \
  "https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/?v=$(git rev-parse --short HEAD)"

The ?v= cache-buster matters: the Pages Server caches, and a stale 200 looks exactly like a successful deploy. Check one nested route (/ai-for-dummies/skills-review/) and one static asset too — the base-path bug shows up on assets first.

3.6 KiB Raw Blame History