@catladder/cli 0.0.0-main-8dbb6c76 → 0.0.0-main-a6b45abe

package/dist/skills/catladder-migrate-ci-backend/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: catladder-migrate-ci-backend
+description: Guiding a catladder project from one CI backend to the other — GitLab CI → GitHub Actions or GitHub Actions → GitLab CI — using the `pipelines` config to run both in parallel first, then cutting over. Covers the blockers to check up front (unsupported features, secrets vault, release tokens, container registry) and the manual cleanup a cut-over needs. Use when moving a project between GitLab and GitHub, enabling a second CI backend, or decommissioning one. Triggers on "migrate to github", "move to github actions", "switch from gitlab to github", "migrate to gitlab", "enable github pipeline", "run both pipelines", "gitRemote", "secrets-sync-github".
+---
+
+# Migrating between GitLab CI and GitHub Actions
+
+catladder generates pipelines for both CI systems from the same
+`catladder.ts`, and **both can be enabled at once**. That is what makes
+this migration safe: run the new backend in parallel with the old one on
+the same commits, compare, and only then cut over.
+
+```ts
+pipelines: {
+  gitlab: true,
+  github: { gitRemote: "github" },
+}
+```
+
+(`pipelineType: "gitlab"` is the deprecated single-backend form —
+replace it with `pipelines` as the first step.)
+
+Never do this as one big-bang commit. Work through the steps below and
+**stop at each decision point that is the user's to make** — creating
+repositories, pushing to a new host, and moving secrets are all
+outward-facing actions that need their explicit go-ahead.
+
+## Step 0 — scope it with the user
+
+Ask up front (once, with your reading of the repo attached):
+
+- **Direction and end state**: is the old backend going away, or do both
+  stay live permanently (some projects keep GitLab for releases and
+  GitHub for PR checks)?
+- **Repository**: does the target repo already exist, or must it be
+  created and pushed?
+- **Which backend owns releases** during the parallel phase — see step 6.
+- **Where secret values live afterwards** — see step 5. This is the one
+  that blocks decommissioning, so raise it early rather than at the end.
+
+## Step 1 — check the blockers before changing anything
+
+Read the project's `catladder.ts` and report what will *not* carry over.
+Going **GitLab → GitHub**:
+
+- **`deploy: { type: "pages" }`** — not supported on the GitHub backend.
+  Those components simply generate no deploy jobs there (a warning, not
+  a generation error), so the site silently stops being published.
+- **`agents`** (the Claude agent integration) — GitLab-only; agent jobs
+  are skipped on GitHub.
+- **Default branch must be `main`** — the generated GitHub main-branch
+  workflow triggers on `push: branches: [main]`. A project on `master`
+  or `develop` gets a workflow that never runs.
+- **`hooks.transformYamlBeforeWrite` / `transformFileBeforeWrite`** —
+  hooks run for the GitHub files too. Any hook that keys on
+  `.gitlab-ci.yml` or on GitLab's YAML shape needs revisiting; a hook
+  that blindly rewrites `data.include` will corrupt workflow files.
+- **`customJobs`** do carry over (they are platform-neutral job specs),
+  but anything GitLab-shaped *inside* them — raw `rules:`, `only:`,
+  GitLab-specific job keys — does not.
+- **`secrets.vault: "gitlab"`** (the default) requires a GitLab project.
+  See step 5.
+
+Going **GitHub → GitLab** the feature list is easier (GitLab supports
+everything the GitHub backend does), but still check the hooks, and note
+that GitLab needs a real access token for releases (step 6).
+
+Report this list to the user before touching the config. If a blocker
+has no first-class solution, that is worth an issue on catladder —
+https://git.panter.ch/catladder/catladder/-/issues.
+
+## Step 2 — get the repository onto the target host
+
+For a new GitHub repo: create it and push `main` plus **all tags**
+(the release job derives the version from the nearest `v*` tag — a
+tagless mirror re-releases `1.0.0`).
+
+Add it as a **second remote** rather than replacing `origin`, so the old
+backend keeps working during the parallel phase:
+
+```bash
+git remote add github git@github.com:<owner>/<repo>.git
+git push github main --tags
+```
+
+Ask before creating the repository or pushing — this publishes the code
+to a new host.
+
+## Step 3 — enable both backends
+
+```ts
+pipelines: {
+  gitlab: true,
+  github: { gitRemote: "github" },
+}
+```
+
+`gitRemote` tells catladder which git remote points at that CI system's
+repository (default `origin`). Then regenerate and commit:
+
+```bash
+yarn catenv
+```
+
+The two file sets live side by side and never collide:
+
+| backend | generated files |
+|---|---|
+| gitlab | `.gitlab-ci.yml`, `.catladder-generated/gitlab/` |
+| github | `.github/workflows/catladder-*.yml`, `.catladder-generated/github/scripts/` |
+
+Shared (generated once for both): `.catladder-generated/images/` and
+`.catladder-generated/catci/`.
+
+If the hosted runners of the new backend are smaller than the old ones,
+tune them per backend instead of globally:
+
+```ts
+github: { gitRemote: "github", runnerVariables: { TURBO_CONCURRENCY: "2" } },
+```
+
+## Step 4 — mirror the secrets to the new backend
+
+GitHub Actions cannot read the vault at runtime, so the values must be
+pushed into GitHub:
+
+```bash
+gh auth login
+yarn catladder project secrets-sync-github
+```
+
+This creates one **GitHub environment per catladder env** and writes
+each secret/variable into the environment(s) whose generated jobs
+actually reference it. (Environments are not cosmetic: GitHub caps a
+repository at 100 secrets, which a multi-env project blows through; the
+cap applies per environment.) Re-run it after every secret change for as
+long as both backends are live.
+
+Then verify:
+
+```bash
+yarn catladder project doctor
+```
+
+It compares the secret/variable *names* the generated workflows
+reference against what is actually set, per environment, and prints the
+command that heals each gap. Values cannot be compared — GitHub secrets
+are write-only by design.
+
+## Step 5 — the secrets vault is what actually blocks decommissioning
+
+`secrets.vault` defaults to `"gitlab"`: the GitLab project variables
+double as the **readable source of truth**, and the CI backends only
+ever get mirrored copies. GitHub secrets can never serve as that source.
+
+So if GitLab is going away, move the vault **before** deleting anything:
+
+```ts
+secrets: {
+  vault: { type: "bitwarden", collection: "catladder" },
+}
+```
+
+A safe order:
+
+1. `yarn catladder project secrets-pull <env>: --out /tmp/secrets.yml`
+   against the old vault (unset values show as `🚨 FILL ME`)
+2. switch `secrets.vault` in `catladder.ts`, `yarn catenv`
+3. `yarn catladder project secrets-push <env>: --file /tmp/secrets.yml`
+4. `yarn catladder project doctor`, then delete the temp file
+5. only now decommission the GitLab project
+
+Never commit the intermediate file, and see the `catladder-secrets`
+skill for the exact command surface.
+
+## Step 6 — releases and tokens
+
+- **GitLab** needs a `GL_TOKEN` project access token (named
+  `semantic-release`) to push the release commit and tag. It is created
+  and rotated by `yarn catladder project setup`.
+- **GitHub** needs nothing extra — the release jobs use the built-in
+  `github.token`. Tags pushed by that token do not retrigger workflows,
+  so the release job dispatches the tagged-release workflow explicitly;
+  that is built in and needs no configuration.
+- **Only one backend should own releases at a time.** Both backends
+  generate release jobs, and with `releases: { when: "auto" }` both would
+  try to tag the same commit. During the parallel phase, agree with the
+  user which backend releases; the other one's release job must stay
+  unclicked (`when: "manual"`) or the parallel phase must be short.
+
+See the `catladder-releases` skill for how the release jobs differ
+(GitLab manual job vs. GitHub dispatch workflow).
+
+## Step 7 — registry and the first run
+
+The **job images** (the catladder runner images) always live in the CI
+system's own registry, so they change host with the backend:
+`$CI_REGISTRY_IMAGE` on GitLab, `ghcr.io/<owner>/<repo>` on GitHub. The
+first pipeline on the new backend therefore **rebuilds every job image**
+— it will be slow, and that is expected, not a bug.
+
+Where the **app image** goes depends on the deploy type:
+
+- **`google-cloudrun`** — the image goes to Google Artifact Registry
+  (`<region>-docker.pkg.dev/<projectId>/catladder-deploy/…`) on both
+  backends. Cloud Run can only pull from AR/GCR, so a backend migration
+  does not move the app image at all. Nothing to do here.
+- **`kubernetes`** — the app image lives in the CI registry and does
+  move. catladder handles the pull itself: every deploy runs
+  `kubernetesCreateSecret`, which writes a `docker-registry` secret
+  (`gitlab-registry-<component>`) into the namespace, and the chart wires
+  it in as `imagePullSecrets`. Note the secret keeps its historical name
+  on both backends.
+
+The credential behind that secret differs per backend, and this is the
+one thing to raise before a kubernetes component moves to GitHub:
+
+- **GitLab** provisions a durable one automatically —
+  `catladder project setup` creates a `gitlab-deploy-token` (scope
+  `read_registry`), GitLab exposes it to jobs as `CI_DEPLOY_USER` /
+  `CI_DEPLOY_PASSWORD`, and `project doctor` fails when it is missing.
+- **GitHub has no equivalent.** The deploy falls back to the workflow
+  token, which expires with the run: the initial pull succeeds and the
+  job goes green, but a pod rescheduled later cannot re-pull —
+  `ImagePullBackOff` weeks after a deploy that looked fine. Until that
+  is solved (catladder issue #75), a project moving kubernetes to GitHub
+  must supply a long-lived registry credential itself, declared as
+  secrets named `CI_DEPLOY_USER` / `CI_DEPLOY_PASSWORD` (a PAT with
+  `read:packages`), which take precedence in the deploy.
+
+## Step 8 — run both, compare, then cut over
+
+Let both pipelines run on the same commits until the new backend is
+green for all three triggers: a merge/pull request, the main branch, and
+a tagged release. Only then flip:
+
+```ts
+pipelines: { github: true }
+```
+
+```bash
+yarn catenv
+```
+
+⚠️ **catladder only cleans up backends that are still enabled** — the
+disabled backend's files stay behind and must be deleted by hand:
+
+- gitlab: `.gitlab-ci.yml` and `.catladder-generated/gitlab/`
+- github: `.github/workflows/catladder-*.yml` and
+  `.catladder-generated/github/scripts/`
+
+Then, if the new host becomes `origin`, update the remotes and drop the
+now-wrong `gitRemote`, regenerate once more, and finish with
+`yarn catladder project doctor`.
+
+## After the cut-over
+
+- **Set up merge gating — GitHub has none by default.** On GitLab,
+  "merge when pipeline succeeds" is built in; on a fresh GitHub repo a
+  PR is mergeable the moment it opens, checks still running, and the
+  auto-merge button does not even appear. `yarn catladder project setup`
+  configures it: auto-merge + delete-merged-branches on the repo, and a
+  branch protection rule on the default branch requiring the generated
+  **`catladder ✅`** aggregate check (the one stable context — never
+  require individual job names, they change with every component
+  add/rename and a stale required name blocks its own PR forever).
+  `project doctor` verifies it. Two things stay human choices: "Do not
+  allow bypassing" (leave it off — generated CI means a generation bug
+  can only be fixed via the admin bypass) and required reviews.
+- Tell the team where the pipeline lives now and how manual actions
+  work there (on GitHub, manual jobs are dispatch workflows in the
+  Actions sidebar — `🚀 catladder create release`, `▶️ catladder deploy`,
+  `⏹️ catladder stop`, `↩️ catladder rollback`).
+- Revoke tokens that are no longer needed (`GL_TOKEN`).
+- Keep the old host readable until the vault migration is verified in
+  practice — a rotated secret is much cheaper to recover than a deleted
+  one.
+
+## Related skills
+
+- `catladder-config` — `catladder.ts` structure, `pipelines`, regeneration
+- `catladder-secrets` — vault, `secrets-sync-github`, secret commands
+- `catladder-releases` — release jobs and how they differ per backend
+- `catladder-pipelines` — triggers, generated file layout, debugging CI
+- `catladder-cli` — `project doctor`, `project setup`, non-interactive usage
+- `catladder-migrate-package-manager` — migrating between yarn and pnpm

package/dist/skills/catladder-migrate-package-manager/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: catladder-migrate-package-manager
+description: Migrating a catladder project's node package manager — yarn → pnpm (via `pnpm import`, keeping the resolved versions) or pnpm → yarn — including the workspace file, the yarn-isms in scripts and catladder.ts, phantom dependencies, and what changes in the generated pipeline. Use when a project should switch package managers, when `pnpm import` is mentioned, or when a pnpm migration breaks builds or docker images. Triggers on "migrate to pnpm", "switch to pnpm", "yarn to pnpm", "use pnpm instead of yarn", "pnpm import", "back to yarn", "change package manager", "pnpm-workspace.yaml", "phantom dependency", "frozen-lockfile fails".
+---
+
+# Migrating the package manager (yarn ↔ pnpm)
+
+catladder supports **yarn** (classic and berry) and **pnpm** for the
+node build family, and autodetects which one a project uses. So the
+catladder side of this migration is nearly free — the work is in the
+repository: lockfile, workspace file, scripts, and the dependencies
+that only ever resolved because yarn hoisted them.
+
+Typical motivation: pnpm is substantially faster in CI (a real project
+saw lint 584s → 187s, app build 470s → 228s, docker builds 2–3× faster
+on warm caches).
+
+**Do this on a branch and expect several iterations.** The first
+pipeline will not be green. Plan for it instead of promising a one-shot
+migration.
+
+## What catladder detects, and what it generates
+
+Detection order (`packageManager` in `catladder.ts` → `packageManager`
+field in package.json → lockfile → yarn fallback):
+
+```ts
+// catladder.ts — only needed to override the detection
+packageManager: "pnpm",
+```
+
+Prefer the `packageManager` field in the root `package.json`
+(`"packageManager": "pnpm@11.6.0"`) — it drives local dev, corepack and
+catladder at once, and catladder installs *that* version in the docker
+build. Corepack's `+sha512…` integrity suffix is fine; catladder strips
+it before using the version as an npm spec.
+
+Once detected, catladder switches all of this automatically — no config
+change needed:
+
+| | yarn | pnpm |
+|---|---|---|
+| CI install | `yarn install --immutable` | `pnpm install --frozen-lockfile` |
+| download cache | `.yarn` zip cache | **none** — installing from the registry is cheaper than moving the store |
+| node_modules cache | mutable slot per build dir | **none** (measured: the archive costs more than the install it saves) |
+| docker prod install | `yarn workspaces focus --production` | `pnpm install --prod --frozen-lockfile --filter <pkg>...` |
+| audit job | `yarn npm audit … --all --recursive` | `pnpm audit --prod --audit-level critical` |
+| build/start defaults | `yarn build` / `yarn start` | `pnpm build` / `pnpm start` |
+
+The audit job is the one place where the two are not equivalent in
+practice: it is easy to have a yarn pipeline whose audit checked nothing
+(before catladder 5 the generated command lacked `--all --recursive`), so
+the pnpm job can turn up long-standing vulnerabilities. Read them as
+pre-existing, not as caused by the migration.
+
+Because the cache keys differ per package manager, the first pnpm
+pipeline runs **cold** (and rebuilds job images). Judge speed on the
+second run, not the first.
+
+## Step 0 — check the blockers
+
+- **node version** — pnpm 11 requires **node ≥ 22.13**, pnpm 10 only
+  ≥ 18.12. Check `.nvmrc` (and any explicit node version in job images):
+  the jobs switch with nvm, so an `.nvmrc` of `20` downgrades a node-22
+  image and pnpm 11 dies mid-install with
+  `ERR_UNKNOWN_BUILTIN_MODULE: No such built-in module: node:sqlite`.
+  Either bump `.nvmrc` to 22 in the same change, or pin
+  `"packageManager": "pnpm@10.x"`.
+- **`build: { type: "meteor" }`** — yarn-only in catladder; generation
+  fails outright. That component blocks the migration.
+- **Yarn PnP** (`nodeLinker: pnp`, `.pnp.cjs`) — the migration is bigger
+  than a lockfile swap: everything that relied on PnP resolution changes.
+  Say so before starting.
+- **Yarn plugins** (`.yarn/plugins`, `yarn workspaces focus`,
+  `yarn-plugin-*`) — no pnpm equivalent; each needs a decision.
+- **catladder version** — pnpm support landed in catladder 5. On an
+  older version, upgrade first.
+- **`docker: { yarnRebuildEnabled }`** in a build config — yarn-only;
+  it is silently ignored under pnpm. Remove it as cleanup.
+
+## Step 1 — inventory the yarn-isms
+
+Grep the repo, not just `catladder.ts`. Every one of these needs a
+decision *before* the lockfile changes:
+
+```bash
+grep -rn "yarn " --include=package.json --include="*.ts" --include="*.md" --include="*.yml" --include="*.yaml" --include=Dockerfile* .
+```
+
+Look at: package.json `scripts`, `catladder.ts`
+(`buildCommand`, `startCommand`, `postInstall`, `lint`/`test`/`audit`
+`command`, deploy `command`/`script`, `customJobs`), Dockerfiles,
+husky hooks, `lint-staged`, `.github/`-adjacent tooling, and the README.
+
+The mapping table is in
+[references/yarn-to-pnpm-differences.md](references/yarn-to-pnpm-differences.md)
+— read it before rewriting scripts; several of the entries there
+(root-script fallback, shell globs, the `pnpm run` banner) have caused
+silent, hard-to-debug breakage in production images.
+
+## Step 2 — write `pnpm-workspace.yaml` first
+
+`pnpm import` **requires the workspace file to exist already**, or it
+generates a lockfile for the root package only.
+
+Translate, in one file:
+
+```yaml
+packages: # from package.json "workspaces"
+  - "packages/*"
+  - "apps/*"
+
+overrides: # from package.json "resolutions"
+  some-pkg: 1.2.3
+
+patchedDependencies: # from yarn's .yarn/patches + resolutions patch: entries
+  some-pkg@1.2.3: patches/some-pkg.patch
+
+allowBuilds: # deps whose install scripts may run (see step 4)
+  esbuild: true
+  prisma: true
+
+minimumReleaseAge: 0 # pnpm 11 defaults to 1440 (min); 0 keeps yarn's behavior
+```
+
+On **pnpm 11+ nearly all settings live in `pnpm-workspace.yaml` only** —
+`pnpm.overrides` in package.json and non-auth settings in `.npmrc` are
+ignored (pnpm 10 read them; this reversal silently drops overrides).
+`.npmrc` keeps auth and registry settings.
+
+The yarn patches themselves (`.yarn/patches/*.patch`) can be reused as
+files; move them somewhere neutral (`patches/`) and reference them from
+`patchedDependencies`.
+
+## Step 3 — import the lockfile
+
+```bash
+pnpm import          # yarn.lock -> pnpm-lock.yaml, keeping resolved versions
+rm -rf yarn.lock node_modules **/node_modules .yarn/cache .yarn/install-state.gz
+pnpm install
+```
+
+`pnpm import` is what keeps this migration honest: it preserves the
+versions yarn had resolved instead of re-resolving every range. Do not
+skip it and run a bare `pnpm install` — that silently upgrades hundreds
+of transitive dependencies at the same time as the package manager
+changes, and you will not know which change broke what.
+
+Then set the `packageManager` field, and update `.gitignore`: `.yarn/*`
+entries out (keep `.yarn/patches` only if you left the patches there).
+Nothing pnpm-specific needs ignoring — the store lives outside the repo.
+
+## Step 4 — fix the fallout locally
+
+Work through these *before* touching CI; every one of them fails the
+same way in the pipeline, only slower.
+
+1. **Phantom dependencies** — pnpm does not hoist. Every package your
+   code imports must be in *its own* `package.json`. This is the single
+   biggest source of failures, and the nastiest ones surface only in the
+   docker image (a bundler happily resolved the hoisted copy at build
+   time; the prod install does not ship it). Fix by declaring, never by
+   `shamefully-hoist`.
+2. **Install scripts are not run** unless approved. `pnpm install`
+   prints the list it skipped → add them to `allowBuilds`
+   (pnpm 11; `onlyBuiltDependencies` list on pnpm 10). Missing prisma,
+   esbuild, sharp, playwright, husky, … show up as "works locally,
+   fails in the image".
+3. **Root `prepare` runs in the production install** (docker), where
+   devDependencies are absent: `"prepare": "husky || true"`.
+4. **Quote your globs.** yarn berry's built-in shell expands `**`;
+   pnpm's `sh` does not. `node build.mjs ./entrypoints/**/*.ts` silently
+   builds fewer files → a container that boots without its entrypoint.
+   Quote the pattern and let the tool expand it.
+5. **`pnpm run` prints a banner to stdout** — any script whose output is
+   piped needs `pnpm --silent run …`.
+6. **No root-script fallback**: yarn berry falls back to the root
+   package's scripts, pnpm does not. Inline shared scripts into each
+   workspace (the root `node_modules/.bin` *is* on the script PATH).
+
+Then, still locally: full build, typecheck, lint and test — and
+`docker build` at least one generated Dockerfile and boot the image.
+That catches phantom dependencies far faster than a pipeline round-trip.
+
+## Step 5 — regenerate the pipeline
+
+Nothing in `catladder.ts` needs to change beyond the yarn-isms from
+step 1 (and, optionally, an explicit `packageManager: "pnpm"`).
+
+```bash
+pnpm catenv
+```
+
+Commit the regenerated `.catladder-generated/`, `.gitlab-ci.yml` and
+`.github/workflows/catladder-*` with the rest — see `catladder-config`.
+
+Review the diff: install commands, cache keys/paths, the default
+build/lint/test commands and the docker install lines should have
+flipped to pnpm everywhere. Anything still saying `yarn` is a command
+you spelled out yourself in `catladder.ts` (step 1), not a default.
+
+## Step 6 — verify in CI
+
+- The first pipeline is cold and rebuilds job images — slow by design.
+- Expect the failures to arrive **in waves**: install → build → docker →
+  deploy. A green build job says nothing about the images.
+- If a docker job fails on `--frozen-lockfile`, the cause is almost
+  always a file missing from the build context (a workspace manifest, a
+  patch file) or a lockfile that was not regenerated after a
+  package.json edit.
+- Deploy at least one component to a review/dev environment and check it
+  actually boots — bundlers hide missing dependencies until runtime.
+- Compare timings against the **second** run.
+
+## Step 7 — hand over to the team
+
+Tell the user what changes for everyone:
+
+- `yarn <x>` → `pnpm <x>`; `yarn workspace a b` → `pnpm --filter a b`;
+  `yarn dlx` → `pnpm dlx`. The CLIs become `pnpm catenv` / `pnpm catladder`.
+- new dependencies must be declared where they are imported — the
+  hoisting safety net is gone
+- a dependency with an install script needs an `allowBuilds` entry
+- update the README / contributing docs and any developer onboarding
+  script in the same MR
+
+## The other direction: pnpm → yarn
+
+Mirrored, with one loss to state up front: **there is no importer back**.
+`yarn import` only reads npm lockfiles, so yarn berry has to re-resolve
+every range — the migration necessarily bumps transitive versions.
+Do it deliberately:
+
+1. Delete `pnpm-lock.yaml`, `pnpm-workspace.yaml`, and the `node_modules`
+   trees.
+2. Move `packages:` back into package.json `workspaces`, `overrides` →
+   `resolutions`, `patchedDependencies` → yarn's patch protocol,
+   `allowBuilds` → (yarn runs build scripts by default; nothing needed).
+3. `yarn install`, then re-run the whole local verification of step 4 —
+   the version drift is the risk here, not the tooling.
+4. Set `packageManager: "yarn@x.y.z"`, drop `packageManager: "pnpm"`
+   from `catladder.ts` if it was set, run `yarn catenv`, commit the
+   regenerated files.
+
+## Related skills
+
+- `catladder-builds` — the `build` config, pnpm gotchas per build type,
+  workspace builds
+- `catladder-config` — catladder.ts structure, `packageManager`,
+  regeneration
+- `catladder-pipelines` — caching, job images, debugging CI
+- `catladder-migrate-ci-backend` — moving between GitLab CI and GitHub
+  Actions
+- `catladder-migrate-release-method` — switching between
+  semantic-release and changesets

package/dist/skills/catladder-migrate-package-manager/references/yarn-to-pnpm-differences.md

@@ -0,0 +1,135 @@
+# yarn → pnpm: what actually differs
+
+Companion to the `catladder-migrate-package-manager` skill. Everything
+here has bitten a real catladder project during a migration.
+
+## Command mapping
+
+| yarn | pnpm |
+|---|---|
+| `yarn` / `yarn install` | `pnpm install` |
+| `yarn install --immutable` (`--frozen-lockfile` classic) | `pnpm install --frozen-lockfile` |
+| `yarn add x` / `yarn add -D x` | `pnpm add x` / `pnpm add -D x` |
+| `yarn remove x` | `pnpm remove x` |
+| `yarn up x` (berry) | `pnpm update x` |
+| `yarn <script>` | `pnpm <script>` (or `pnpm run <script>`) |
+| `yarn workspace pkg <script>` | `pnpm --filter pkg <script>` |
+| `yarn workspaces foreach …` | `pnpm -r <script>` |
+| `yarn workspaces focus --production` | `pnpm install --prod --filter pkg...` |
+| `yarn run -T x` / `yarn -T x` (berry top-level) | `x` (root `node_modules/.bin` is on the script PATH) |
+| `yarn dlx x` | `pnpm dlx x` |
+| `yarn node x` / `yarn exec x` | `pnpm exec x` |
+| `yarn npm audit --environment production --all --recursive` | `pnpm audit --prod` |
+| `yarn bin x` | `pnpm bin x` |
+
+## Configuration mapping
+
+| yarn | pnpm |
+|---|---|
+| package.json `workspaces` | `packages:` in `pnpm-workspace.yaml` |
+| package.json `resolutions` | `overrides:` in `pnpm-workspace.yaml` |
+| `.yarn/patches/*` + `patch:` resolutions | `patchedDependencies:` in `pnpm-workspace.yaml` |
+| `.yarnrc.yml` settings | `pnpm-workspace.yaml` (auth/registry stay in `.npmrc`) |
+| `.yarnrc.yml` `npmScopes` / auth | `.npmrc` |
+| `catalog:` / `catalogs:` in `.yarnrc.yml` | `catalog:` / `catalogs:` in `pnpm-workspace.yaml` |
+| (yarn runs install scripts by default) | `allowBuilds:` map — pnpm 11; `onlyBuiltDependencies:` list on pnpm 10 |
+| `.yarn/cache` (zip cache) | the content-addressable store (catladder points it at a project-local `.pnpm-store`) |
+
+**pnpm 11 reads settings from `pnpm-workspace.yaml` only.** A
+`pnpm` section in package.json (`pnpm.overrides`,
+`pnpm.patchedDependencies`) works on pnpm 10 and is *silently ignored*
+on 11 — the opposite of what most migration guides written for pnpm 10
+say. `.npmrc` keeps auth/registry settings and nothing else.
+
+## Behavioral differences that break things
+
+**No hoisting → phantom dependencies.** yarn flattens
+`node_modules`, so a package you never declared is importable anyway.
+pnpm's symlinked layout does not. Every undeclared import fails —
+sometimes only inside the production docker image, where the bundler is
+no longer there to paper over it. The fix is always to declare the
+dependency; `shamefully-hoist` only postpones the failure.
+
+**Install scripts are opt-in.** `pnpm install` skips dependency build
+scripts and prints the list. Anything with a native build or a
+generator step (prisma, esbuild, sharp, playwright, husky, …) needs an
+`allowBuilds` entry, or it is missing at runtime.
+
+**The root `prepare` script runs during `--prod` installs.** In the
+docker image, devDependencies are gone: `"prepare": "husky"` fails the
+build. Use `"prepare": "husky || true"`.
+
+**`pnpm run` writes a banner to stdout.** yarn does not. Any script
+whose output is piped or captured (`pnpm build:x > out.json`, generated
+supergraph schemas, …) must use `pnpm --silent run …`.
+
+**Scripts run in `sh`, not yarn's built-in shell.** yarn berry ships a
+POSIX-ish shell that expands `**` recursively; `sh` does not. An
+unquoted `./src/**/*.ts` silently matches *fewer* files. Quote the
+pattern and let the receiving tool expand it. This is the failure mode
+that ships a container missing half its entrypoints and still boots the
+build job green.
+
+**No root-script fallback.** yarn berry falls back to the root
+package's scripts when a workspace has none; pnpm errors. Inline shared
+scripts into each workspace, or add a thin per-workspace wrapper.
+
+**`--frozen-lockfile` verifies every importer.** pnpm checks that every
+workspace listed in the lockfile exists on disk, and that every
+`patchedDependencies` patch file is present with the right hash — which
+is why catladder copies all workspace manifests and all patch files into
+the docker build context.
+
+**Version drift in `--prod` installs.** `pnpm install --prod` on a
+node_modules tree from a *different* lockfile does not prune orphaned
+`.pnpm` directories — never reuse one branch's node_modules for another
+lockfile, and never a yarn tree for a pnpm branch.
+
+**Nothing is cached.** A yarn pipeline caches its zip cache and
+node_modules; a pnpm pipeline caches neither, and does not copy a store
+into docker images either. pnpm installs a 3800-package monorepo from
+the registry in 30-40s, which is less than it costs to move a 1 GB
+store or a 1.3 GB node_modules tree through a CI cache — measured
+side-by-side, caching made jobs about twice as slow on gitlab. Two
+consequences when migrating: CI pulls more from the registry than the
+yarn setup did (worth a registry proxy if that matters to you), and
+`.pnpm-store` should not appear anywhere in the repo or a build
+context.
+
+**Docker images must not carry the store.** If a store is copied into
+an image, it lands in a layer below `node_modules`, pnpm cannot hardlink
+across the overlay boundary, and every package is copied instead — the
+install gets *slower* (28s vs 10s from the registry) and the image
+carries the packages twice. Let the `--prod` install download, into a
+store outside the app directory that the same `RUN` layer deletes.
+
+**pnpm 11 needs node ≥ 22.13** (pnpm 10: ≥ 18.12), and it does not fail
+politely: it prints a `warn:` line and then crashes on
+`No such built-in module: node:sqlite`. In CI this bites even when the
+job image ships node 22 — the jobs run `nvm install` from `.nvmrc`, so
+an `.nvmrc` of `20` downgrades the image right before the install.
+
+**`pnpm audit` needs no scope flags.** It audits every workspace and the
+whole transitive tree by default, which is what `yarn npm audit` only does
+with `--all --recursive` (without them it checks the current workspace's
+*direct* dependencies — in a monorepo root that is usually nothing at all).
+Expect the pnpm audit job to surface vulnerabilities the yarn one never
+reported. In return `--prod` is stricter than yarn's
+`--environment production`: yarn still reports a devDependency of a
+workspace, pnpm does not.
+
+**`minimumReleaseAge`** defaults to 1440 minutes on pnpm 11: freshly
+published versions are refused. Set it to `0` while migrating (it is a
+supply-chain feature worth enabling deliberately later, not something to
+discover mid-migration).
+
+## catladder-specific notes
+
+- The `packageManager` field feeds the pnpm version installed in the
+  docker build; corepack's `+sha512…` integrity suffix is stripped.
+- `build: { type: "meteor" }` is yarn-only in catladder and fails
+  generation under pnpm.
+- `docker: { yarnRebuildEnabled }` applies to yarn berry only.
+- The job image ships pnpm; custom `jobImage`s and custom
+  `dockerfileContent` images get a `npm install -g pnpm@<version>`
+  fallback injected, so they work too — but they pay for it on every job.