@catladder/cli 0.0.0-next-d8b92979 → 0.0.0-next-2eda2fde

package/dist/bundles/catenv/index.js

@@ -5694,19 +5694,15 @@ exports.WORKSPACE_BUILD_TYPES = exports.BUILD_TYPES = void 0;
 const custom_1 = __nccwpck_require__(67225);
 const node_1 = __nccwpck_require__(23114);
 const rails_1 = __nccwpck_require__(42427);
+const runScript_1 = __nccwpck_require__(74419);
 __exportStar(__nccwpck_require__(23114), exports);
 __exportStar(__nccwpck_require__(40632), exports);
-/**
- * run a package.json script with the project's package manager
- * (`yarn build` / `pnpm build`)
- */
-const runScript = (packageManager, script) => `${packageManager} ${script}`;
 exports.BUILD_TYPES = {
     node: {
         jobs: node_1.createNodeJobs,
         defaults: (_, pm) => ({
-            buildCommand: runScript(pm, "build"),
-            startCommand: runScript(pm, "start"),
+            buildCommand: (0, runScript_1.runScript)(pm, "build"),
+            startCommand: (0, runScript_1.runScript)(pm, "start"),
             artifactsPaths: ["dist", ".next"],
             artifactsExcludePaths: [".next/cache/**/*"],
         }),
@@ -5714,14 +5710,14 @@ exports.BUILD_TYPES = {
     "node-static": {
         jobs: node_1.createNodeJobs,
         defaults: (_, pm) => ({
-            buildCommand: runScript(pm, "build"),
+            buildCommand: (0, runScript_1.runScript)(pm, "build"),
             artifactsPaths: ["dist"],
         }),
     },
     storybook: {
         jobs: node_1.createStorybookJobs,
         defaults: (_, pm) => ({
-            buildCommand: [runScript(pm, "build-storybook --quiet -o ./dist")],
+            buildCommand: [(0, runScript_1.runScript)(pm, "build-storybook --quiet -o ./dist")],
             artifactsPaths: ["dist"],
         }),
     },
@@ -5752,12 +5748,12 @@ exports.WORKSPACE_BUILD_TYPES = {
     node: {
         jobs: node_1.createNodeJobs,
         defaults: (pm) => ({
-            buildCommand: runScript(pm, "build"),
+            buildCommand: (0, runScript_1.runScript)(pm, "build"),
             lint: {
-                command: runScript(pm, "lint"),
+                command: (0, runScript_1.runScript)(pm, "lint"),
             },
             test: {
-                command: runScript(pm, "test"),
+                command: (0, runScript_1.runScript)(pm, "test"),
             },
         }),
     },
@@ -6323,6 +6319,7 @@ const context_1 = __nccwpck_require__(47747);
 const jobs_1 = __nccwpck_require__(28006);
 const utils_1 = __nccwpck_require__(24516);
 const createArtifactsConfig_1 = __nccwpck_require__(24494);
+const runScript_1 = __nccwpck_require__(74419);
 const cache_1 = __nccwpck_require__(21100);
 const constants_1 = __nccwpck_require__(97627);
 const packageManagerInstall_1 = __nccwpck_require__(18600);
@@ -6394,7 +6391,9 @@ const createNodeTestJobs = async (context) => {
                 ...(0, packageManagerInstall_1.ensureNodeVersion)(context),
                 `cd ${context.build.dir}`,
                 ...packageManagerInstall,
-                ...((_r = (0, utils_1.ensureArrayOrNull)((_q = buildConfig.lint) === null || _q === void 0 ? void 0 : _q.command)) !== null && _r !== void 0 ? _r : ["yarn lint"]),
+                ...((_r = (0, utils_1.ensureArrayOrNull)((_q = buildConfig.lint) === null || _q === void 0 ? void 0 : _q.command)) !== null && _r !== void 0 ? _r : [
+                    (0, runScript_1.runScript)(packageManagerInfo.type, "lint"),
+                ]),
             ],
             allow_failure: (_s = buildConfig.lint) === null || _s === void 0 ? void 0 : _s.allowFailure,
             ...(0, createArtifactsConfig_1.createArtifactsConfig)(context.build.dir, (_t = buildConfig.lint) === null || _t === void 0 ? void 0 : _t.artifactsReports, (_u = buildConfig.lint) === null || _u === void 0 ? void 0 : _u.artifacts),
@@ -6416,7 +6415,9 @@ const createNodeTestJobs = async (context) => {
                 ...(0, packageManagerInstall_1.ensureNodeVersion)(context),
                 `cd ${context.build.dir}`,
                 ...packageManagerInstall,
-                ...((_0 = (0, utils_1.ensureArrayOrNull)((_z = buildConfig.test) === null || _z === void 0 ? void 0 : _z.command)) !== null && _0 !== void 0 ? _0 : ["yarn test"]),
+                ...((_0 = (0, utils_1.ensureArrayOrNull)((_z = buildConfig.test) === null || _z === void 0 ? void 0 : _z.command)) !== null && _0 !== void 0 ? _0 : [
+                    (0, runScript_1.runScript)(packageManagerInfo.type, "test"),
+                ]),
             ],
             allow_failure: (_1 = buildConfig.test) === null || _1 === void 0 ? void 0 : _1.allowFailure,
             ...(0, createArtifactsConfig_1.createArtifactsConfig)(context.build.dir, (_2 = buildConfig.test) === null || _2 === void 0 ? void 0 : _2.artifactsReports, (_3 = buildConfig.test) === null || _3 === void 0 ? void 0 : _3.artifacts),
@@ -6624,6 +6625,23 @@ exports.createRailsTestJobs = createRailsTestJobs;
 
 /***/ }),
 
+/***/ 74419:
+/***/ ((__unused_webpack_module, exports) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.runScript = void 0;
+/**
+ * run a package.json script with the project's package manager
+ * (`yarn build` / `pnpm build`)
+ */
+const runScript = (packageManager, script) => `${packageManager} ${script}`;
+exports.runScript = runScript;
+//# sourceMappingURL=runScript.js.map
+
+/***/ }),
+
 /***/ 40632:
 /***/ ((__unused_webpack_module, exports) => {
 
@@ -11339,19 +11357,38 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.detectPackageManager = void 0;
+exports.detectPackageManager = exports.parsePackageManagerField = void 0;
 const child_process_promise_1 = __nccwpck_require__(42242);
 const fs_1 = __nccwpck_require__(79896);
 const promises_1 = __nccwpck_require__(91943);
 const path_1 = __nccwpck_require__(16928);
 const memoizee_1 = __importDefault(__nccwpck_require__(14199));
+/**
+ * parse a `packageManager` field value (`pnpm@11.6.0`).
+ *
+ * `corepack use` appends an integrity hash (`pnpm@11.6.0+sha512.abc…`).
+ * That suffix is semver build metadata, and generated pipelines
+ * interpolate the version into `npm install -g <pm>@<version>` (docker
+ * builds, job images without the package manager) where it is not a
+ * valid spec — so it is dropped here, at the single place the field is
+ * read.
+ */
+const parsePackageManagerField = (value) => {
+    if (typeof value !== "string")
+        return null;
+    const match = /^(yarn|pnpm)@(.+)$/.exec(value);
+    if (!match)
+        return null;
+    const version = match[2].split("+")[0];
+    if (!version)
+        return null;
+    return { type: match[1], version };
+};
+exports.parsePackageManagerField = parsePackageManagerField;
 const readPackageManagerField = async (dir) => {
     try {
         const pkg = JSON.parse(await (0, promises_1.readFile)((0, path_1.join)(dir, "package.json"), "utf-8"));
-        const match = /^(yarn|pnpm)@(.+)$/.exec(pkg.packageManager);
-        if (!match)
-            return null;
-        return { type: match[1], version: match[2] };
+        return (0, exports.parsePackageManagerField)(pkg.packageManager);
     }
     catch (_a) {
         return null;

package/dist/bundles/cli/index.js

@@ -11893,19 +11893,15 @@ exports.WORKSPACE_BUILD_TYPES = exports.BUILD_TYPES = void 0;
 const custom_1 = __nccwpck_require__(67225);
 const node_1 = __nccwpck_require__(23114);
 const rails_1 = __nccwpck_require__(42427);
+const runScript_1 = __nccwpck_require__(74419);
 __exportStar(__nccwpck_require__(23114), exports);
 __exportStar(__nccwpck_require__(40632), exports);
-/**
- * run a package.json script with the project's package manager
- * (`yarn build` / `pnpm build`)
- */
-const runScript = (packageManager, script) => `${packageManager} ${script}`;
 exports.BUILD_TYPES = {
     node: {
         jobs: node_1.createNodeJobs,
         defaults: (_, pm) => ({
-            buildCommand: runScript(pm, "build"),
-            startCommand: runScript(pm, "start"),
+            buildCommand: (0, runScript_1.runScript)(pm, "build"),
+            startCommand: (0, runScript_1.runScript)(pm, "start"),
             artifactsPaths: ["dist", ".next"],
             artifactsExcludePaths: [".next/cache/**/*"],
         }),
@@ -11913,14 +11909,14 @@ exports.BUILD_TYPES = {
     "node-static": {
         jobs: node_1.createNodeJobs,
         defaults: (_, pm) => ({
-            buildCommand: runScript(pm, "build"),
+            buildCommand: (0, runScript_1.runScript)(pm, "build"),
             artifactsPaths: ["dist"],
         }),
     },
     storybook: {
         jobs: node_1.createStorybookJobs,
         defaults: (_, pm) => ({
-            buildCommand: [runScript(pm, "build-storybook --quiet -o ./dist")],
+            buildCommand: [(0, runScript_1.runScript)(pm, "build-storybook --quiet -o ./dist")],
             artifactsPaths: ["dist"],
         }),
     },
@@ -11951,12 +11947,12 @@ exports.WORKSPACE_BUILD_TYPES = {
     node: {
         jobs: node_1.createNodeJobs,
         defaults: (pm) => ({
-            buildCommand: runScript(pm, "build"),
+            buildCommand: (0, runScript_1.runScript)(pm, "build"),
             lint: {
-                command: runScript(pm, "lint"),
+                command: (0, runScript_1.runScript)(pm, "lint"),
             },
             test: {
-                command: runScript(pm, "test"),
+                command: (0, runScript_1.runScript)(pm, "test"),
             },
         }),
     },
@@ -12522,6 +12518,7 @@ const context_1 = __nccwpck_require__(47747);
 const jobs_1 = __nccwpck_require__(28006);
 const utils_1 = __nccwpck_require__(24516);
 const createArtifactsConfig_1 = __nccwpck_require__(24494);
+const runScript_1 = __nccwpck_require__(74419);
 const cache_1 = __nccwpck_require__(21100);
 const constants_1 = __nccwpck_require__(97627);
 const packageManagerInstall_1 = __nccwpck_require__(18600);
@@ -12593,7 +12590,9 @@ const createNodeTestJobs = async (context) => {
                 ...(0, packageManagerInstall_1.ensureNodeVersion)(context),
                 `cd ${context.build.dir}`,
                 ...packageManagerInstall,
-                ...((_r = (0, utils_1.ensureArrayOrNull)((_q = buildConfig.lint) === null || _q === void 0 ? void 0 : _q.command)) !== null && _r !== void 0 ? _r : ["yarn lint"]),
+                ...((_r = (0, utils_1.ensureArrayOrNull)((_q = buildConfig.lint) === null || _q === void 0 ? void 0 : _q.command)) !== null && _r !== void 0 ? _r : [
+                    (0, runScript_1.runScript)(packageManagerInfo.type, "lint"),
+                ]),
             ],
             allow_failure: (_s = buildConfig.lint) === null || _s === void 0 ? void 0 : _s.allowFailure,
             ...(0, createArtifactsConfig_1.createArtifactsConfig)(context.build.dir, (_t = buildConfig.lint) === null || _t === void 0 ? void 0 : _t.artifactsReports, (_u = buildConfig.lint) === null || _u === void 0 ? void 0 : _u.artifacts),
@@ -12615,7 +12614,9 @@ const createNodeTestJobs = async (context) => {
                 ...(0, packageManagerInstall_1.ensureNodeVersion)(context),
                 `cd ${context.build.dir}`,
                 ...packageManagerInstall,
-                ...((_0 = (0, utils_1.ensureArrayOrNull)((_z = buildConfig.test) === null || _z === void 0 ? void 0 : _z.command)) !== null && _0 !== void 0 ? _0 : ["yarn test"]),
+                ...((_0 = (0, utils_1.ensureArrayOrNull)((_z = buildConfig.test) === null || _z === void 0 ? void 0 : _z.command)) !== null && _0 !== void 0 ? _0 : [
+                    (0, runScript_1.runScript)(packageManagerInfo.type, "test"),
+                ]),
             ],
             allow_failure: (_1 = buildConfig.test) === null || _1 === void 0 ? void 0 : _1.allowFailure,
             ...(0, createArtifactsConfig_1.createArtifactsConfig)(context.build.dir, (_2 = buildConfig.test) === null || _2 === void 0 ? void 0 : _2.artifactsReports, (_3 = buildConfig.test) === null || _3 === void 0 ? void 0 : _3.artifacts),
@@ -12823,6 +12824,23 @@ exports.createRailsTestJobs = createRailsTestJobs;
 
 /***/ }),
 
+/***/ 74419:
+/***/ ((__unused_webpack_module, exports) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.runScript = void 0;
+/**
+ * run a package.json script with the project's package manager
+ * (`yarn build` / `pnpm build`)
+ */
+const runScript = (packageManager, script) => `${packageManager} ${script}`;
+exports.runScript = runScript;
+//# sourceMappingURL=runScript.js.map
+
+/***/ }),
+
 /***/ 40632:
 /***/ ((__unused_webpack_module, exports) => {
 
@@ -17538,19 +17556,38 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.detectPackageManager = void 0;
+exports.detectPackageManager = exports.parsePackageManagerField = void 0;
 const child_process_promise_1 = __nccwpck_require__(42242);
 const fs_1 = __nccwpck_require__(79896);
 const promises_1 = __nccwpck_require__(91943);
 const path_1 = __nccwpck_require__(16928);
 const memoizee_1 = __importDefault(__nccwpck_require__(14199));
+/**
+ * parse a `packageManager` field value (`pnpm@11.6.0`).
+ *
+ * `corepack use` appends an integrity hash (`pnpm@11.6.0+sha512.abc…`).
+ * That suffix is semver build metadata, and generated pipelines
+ * interpolate the version into `npm install -g <pm>@<version>` (docker
+ * builds, job images without the package manager) where it is not a
+ * valid spec — so it is dropped here, at the single place the field is
+ * read.
+ */
+const parsePackageManagerField = (value) => {
+    if (typeof value !== "string")
+        return null;
+    const match = /^(yarn|pnpm)@(.+)$/.exec(value);
+    if (!match)
+        return null;
+    const version = match[2].split("+")[0];
+    if (!version)
+        return null;
+    return { type: match[1], version };
+};
+exports.parsePackageManagerField = parsePackageManagerField;
 const readPackageManagerField = async (dir) => {
     try {
         const pkg = JSON.parse(await (0, promises_1.readFile)((0, path_1.join)(dir, "package.json"), "utf-8"));
-        const match = /^(yarn|pnpm)@(.+)$/.exec(pkg.packageManager);
-        if (!match)
-            return null;
-        return { type: match[1], version: match[2] };
+        return (0, exports.parsePackageManagerField)(pkg.packageManager);
     }
     catch (_a) {
         return null;

package/dist/bundles/skills/catladder-builds/SKILL.md

@@ -150,3 +150,5 @@ build type's options, the `docker` sub-config, and the exact defaults.
 - `catladder-deploys` — the matching `deploy` config
 - `catladder-pipelines` — how build jobs, caching and job images work
 - `catladder-secrets` — env vars available at build time
+- `catladder-migrate-package-manager` — migrating a project from yarn
+  to pnpm (or back)

package/dist/bundles/skills/catladder-config/SKILL.md

@@ -121,3 +121,5 @@ escape hatches to shrink over time, not accumulate.
   and GitHub Actions
 - `catladder-migrate-release-method` — switching between
   semantic-release and changesets
+- `catladder-migrate-package-manager` — switching a project between
+  yarn and pnpm

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

@@ -283,3 +283,4 @@ now-wrong `gitRemote`, regenerate once more, and finish with
 - `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/bundles/skills/catladder-migrate-package-manager/SKILL.md

@@ -0,0 +1,242 @@
+---
+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 --store-dir …` |
+| download cache | `.yarn` zip cache | project-local `.pnpm-store`, cache slot scoped by pnpm major |
+| node_modules cache | mutable slot per build dir | **lockfile-keyed** slot (a pnpm install over a foreign tree leaves orphaned `.pnpm` dirs) |
+| docker prod install | `yarn workspaces focus --production` | `pnpm install --prod --frozen-lockfile --filter <pkg>...` |
+| audit job | `yarn npm audit …` | `pnpm audit --prod --audit-level critical` |
+| build/start defaults | `yarn build` / `yarn start` | `pnpm build` / `pnpm start` |
+
+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
+
+- **`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`:
+`.pnpm-store/` in, `.yarn/*` entries out (keep `.yarn/patches` only if
+you left the patches there).
+
+## 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`, `.pnpm-store`, 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/bundles/skills/catladder-migrate-package-manager/references/yarn-to-pnpm-differences.md

@@ -0,0 +1,103 @@
+# 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` | `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. That is why catladder keys the pnpm node_modules
+cache by the lockfile instead of reusing a mutable slot — and why you
+should never reuse a yarn branch's cache for a pnpm branch.
+
+**`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.