Spike: npm -> pnpm

.github/workflows/build.yml

@@ -52,12 +52,18 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm ci --ignore-scripts --no-audit --no-fund
+          cache: 'pnpm'
+      - name: Cache pnpm supply-chain verification
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pnpm
+          key: pnpm-verify-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+      - run: pnpm install --frozen-lockfile --prefer-offline
       - name: Generate tsconfig
         env:
           PACKMIND_EDITION: ${{ vars.PACKMIND_EDITION }}
@@ -75,7 +81,7 @@ jobs:
         run: ./node_modules/.bin/nx test api
       - run: cp apps/api/docker-package.json dist/apps/api/.
       - run: cp package.json dist/apps/api/.
-      - run: cp package-lock.json dist/apps/api/.
+      - run: cp pnpm-lock.yaml dist/apps/api/.
       - run: cp tsconfig.base.effective.json dist/apps/api/.
 
       - name: Upload API build artifacts
@@ -95,22 +101,28 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm ci --ignore-scripts --no-audit --no-fund
+          cache: 'pnpm'
+      - name: Cache pnpm supply-chain verification
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pnpm
+          key: pnpm-verify-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+      - run: pnpm install --frozen-lockfile --prefer-offline
       - name: Generate tsconfig
         env:
           PACKMIND_EDITION: ${{ vars.PACKMIND_EDITION }}
         run: node scripts/select-tsconfig.mjs
       - name: Generate Chakra types
         env:
           PACKMIND_EDITION: ${{ vars.PACKMIND_EDITION }}
-        run: npm run chakra:typegen
+        run: pnpm chakra:typegen
       - name: Typechecks
-        run: npm run typecheck:frontend
+        run: pnpm typecheck:frontend
       - name: Test Frontend
         env:
           PACKMIND_EDITION: ${{ vars.PACKMIND_EDITION }}
@@ -144,12 +156,18 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm ci --ignore-scripts --no-audit --no-fund
+          cache: 'pnpm'
+      - name: Cache pnpm supply-chain verification
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pnpm
+          key: pnpm-verify-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+      - run: pnpm install --frozen-lockfile --prefer-offline
       - name: Generate tsconfig
         env:
           PACKMIND_EDITION: ${{ vars.PACKMIND_EDITION }}
@@ -165,6 +183,7 @@ jobs:
           NODE_OPTIONS: '--max-old-space-size=16384 --no-experimental-strip-types'
         run: ./node_modules/.bin/nx test mcp-server
       - run: cp tsconfig.base.effective.json dist/apps/mcp-server/.
+      - run: cp pnpm-lock.yaml dist/apps/mcp-server/.
 
       - name: Upload MCP-Server build artifacts
         uses: actions/upload-artifact@v4
@@ -183,12 +202,18 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm ci --ignore-scripts --no-audit --no-fund
+          cache: 'pnpm'
+      - name: Cache pnpm supply-chain verification
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pnpm
+          key: pnpm-verify-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+      - run: pnpm install --frozen-lockfile --prefer-offline
       - name: Generate tsconfig
         env:
           PACKMIND_EDITION: ${{ vars.PACKMIND_EDITION }}
@@ -224,11 +249,12 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
+          cache: 'pnpm'
 
       - name: Set up Bun
         uses: oven-sh/setup-bun@v2
@@ -239,7 +265,12 @@ jobs:
         id: get-version
         run: echo "version=$(node -p "require('./apps/cli/package.json').version")" >> $GITHUB_OUTPUT
 
-      - run: npm ci --ignore-scripts --no-audit --no-fund
+      - name: Cache pnpm supply-chain verification
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pnpm
+          key: pnpm-verify-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+      - run: pnpm install --frozen-lockfile --prefer-offline
       - name: Generate tsconfig
         env:
           PACKMIND_EDITION: ${{ vars.PACKMIND_EDITION }}
@@ -272,6 +303,9 @@ jobs:
           echo "Built executables (with embedded WASM files):"
           ls -lh dist/apps/cli-executables/
 
+      - name: Install dist CLI runtime dependencies
+        run: sh scripts/install-dist-cli-deps.sh
+
       - name: Test executables
         run: |
           node dist/apps/cli/main.cjs --version
@@ -300,14 +334,20 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
 
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
+          cache: 'pnpm'
 
-      - run: npm ci --ignore-scripts --no-audit --no-fund
+      - name: Cache pnpm supply-chain verification
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pnpm
+          key: pnpm-verify-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+      - run: pnpm install --frozen-lockfile --prefer-offline
 
       - name: Generate tsconfig
         env:
@@ -316,6 +356,9 @@ jobs:
 
       - run: ./node_modules/.bin/nx run packmind-cli:build
 
+      - name: Install dist CLI runtime dependencies
+        run: sh scripts/install-dist-cli-deps.sh
+
       - name: Fix CLI artifacts permissions
         run: |
           chmod +x dist/apps/cli/main.cjs || true
@@ -358,12 +401,16 @@ jobs:
           NODE_OPTIONS: '--max-old-space-size=16384 --no-experimental-strip-types'
         run: ./node_modules/.bin/nx test cli-e2e-tests
 
-      - name: Install latest production CLI from npm
+      - name: Install latest production CLI from registry
         run: |
           PROD_CLI_DIR="$(mktemp -d)"
           cd "${PROD_CLI_DIR}"
-          npm init -y --silent
-          npm install @packmind/cli
+          pnpm init
+          # Throwaway install: only need the CLI binary resolvable to run --version.
+          # bcrypt/msgpackr-extract ship prebuilt binaries, so their build scripts
+          # are not required. Disable strictDepBuilds (default true in pnpm 11) to
+          # avoid ERR_PNPM_IGNORED_BUILDS here where there is no allowBuilds config.
+          pnpm add @packmind/cli --config.strictDepBuilds=false
           CLI_BINARY_PATH="$(node -e "console.log(require.resolve('@packmind/cli'))")"
           cd -
           echo "Installed CLI version: $(node "${CLI_BINARY_PATH}" --version)"

.github/workflows/docker.yml

@@ -92,11 +92,13 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - uses: pnpm/action-setup@v4
+
       - name: Set up Node.js ${{ inputs.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ inputs.node-version }}
-          cache: 'npm'
+          cache: 'pnpm'
 
       - name: Get package version
         id: get-version
@@ -144,8 +146,13 @@ jobs:
             echo "tag=${{ github.sha }}" >> $GITHUB_OUTPUT
           fi
 
+      - name: Cache pnpm supply-chain verification
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pnpm
+          key: pnpm-verify-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
       - name: Install dependencies
-        run: npm ci --ignore-scripts --no-audit --no-fund
+        run: pnpm install --frozen-lockfile --prefer-offline
 
       # Download all build artifacts
       - name: Download API build artifacts

.github/workflows/quality.yml

@@ -58,12 +58,18 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 10
+      - uses: pnpm/action-setup@v4
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm ci --ignore-scripts --no-audit --no-fund
+          cache: 'pnpm'
+      - name: Cache pnpm supply-chain verification
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pnpm
+          key: pnpm-verify-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+      - run: pnpm install --frozen-lockfile --prefer-offline
       - name: Generate Proprietary tsconfig
         env:
           PACKMIND_EDITION: ${{ env.ENTERPRISE_EDITION }}
@@ -73,7 +79,7 @@ jobs:
           PACKMIND_EDITION: ${{ env.ENTERPRISE_EDITION }}
         run: ./node_modules/.bin/nx run-many -t lint --tuiAutoExit
       - name: Check code formatting
-        run: npm run prettier:check
+        run: pnpm prettier:check
 
   sonarqube:
     if: vars.PACKMIND_EDITION != 'proprietary'
@@ -87,12 +93,18 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - uses: pnpm/action-setup@v4
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm ci --ignore-scripts --no-audit --no-fund
+          cache: 'pnpm'
+      - name: Cache pnpm supply-chain verification
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pnpm
+          key: pnpm-verify-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+      - run: pnpm install --frozen-lockfile --prefer-offline
       - name: Generate Proprietary tsconfig
         env:
           PACKMIND_EDITION: ${{ env.ENTERPRISE_EDITION }}

.github/workflows/tmp-cli-lint-windows.yml

@@ -18,17 +18,23 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - uses: pnpm/action-setup@v4
+
       - name: Use Node.js 24.15.0
         uses: actions/setup-node@v4
         with:
           node-version: '24.15.0'
-          cache: 'npm'
+          cache: 'pnpm'
 
       - name: Install dependencies
-        run: npm ci --ignore-scripts --no-audit --no-fund
+        run: pnpm install --frozen-lockfile --prefer-offline
 
       - name: Build CLI
-        run: npm run packmind-cli:build
+        run: pnpm packmind-cli:build
+
+      - name: Install dist CLI runtime dependencies
+        shell: bash
+        run: sh scripts/install-dist-cli-deps.sh
 
       - name: Run CLI lint
         run: node dist/apps/cli/main.cjs lint .

.gitignore

@@ -1,4 +1,5 @@
 .nx-daemon/
+.pnpm-store/
 node_modules/
 .vscode/
 .idea/
@@ -56,4 +57,7 @@ apps/mcp-server/key.pem
 docker/nginx/ssl
 
 .nx/polygraph
-.nx/self-healing
+.nx/self-healing
+
+# Node.js V8 compile cache (auto-generated by Node 22+ when NODE_COMPILE_CACHE is set)
+node-compile-cache/

.husky/pre-commit

@@ -1,2 +1,2 @@
-npx pretty-quick --staged
+pnpm exec pretty-quick --staged
 scripts/precommit-lint.sh

CONTRIBUTING.md

@@ -2,17 +2,34 @@
 
 ## Starting the stack:
 
-You will need node 24.15.0 and docker to start the development stack:
+You will need node 24.15.0 and docker to start the development stack. This repo
+uses **pnpm 11** (pinned via `packageManager` in `package.json`); enable it through
+corepack — no global install needed. pnpm settings (overrides, `allowBuilds`,
+hoisting) live in `pnpm-workspace.yaml`, not `.npmrc` or the `package.json` `pnpm`
+field, as required since pnpm 11:
 
 ```shell
 nvm use
-npm i
+corepack enable
+pnpm install --frozen-lockfile
 PACKMIND_EDITION=oss node scripts/select-tsconfig.mjs
 docker compose --profile=dev up
 ```
 
 The app should be available at [http://localhost:4200](http://localhost:4200)
 
+## Migrating an existing checkout from npm to pnpm
+
+If you previously worked with npm, run the one-shot migration script from the
+repo root. It removes stale `node_modules` and `package-lock.json`, activates
+pnpm via corepack, installs against the lockfile, and regenerates the tsconfig:
+
+```shell
+./pnpm_migrate.sh
+```
+
+The script is safe to re-run.
+
 ## Switching packmind-cli versions (pvm)
 
 `pvm` is a lightweight dev tool (inspired by nvm) to manage multiple packmind-cli versions locally.