docs: clarify manifest-based version selection (#244)

* updating readme to include devEngines.packageManager.version in selecting version

* docs: check out the manifest before inferring pnpm version

---------

Co-authored-by: Zoltan Kochan <z@kochan.io>

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @zkochan

.github/workflows/pr-check.yaml

@@ -13,13 +13,20 @@ jobs:
   check-dist:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
         with:
           run_install: true
-          version: 9
+          version: 11
+
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: 24
+
+      - name: Test
+        run: pnpm test
 
       - name: Update dist/index.js
         run: pnpm run build

.github/workflows/test.yaml

@@ -1,43 +1,85 @@
 name: Test Action
 
 on:
-  - push
-  - pull_request
-  - workflow_dispatch
+  pull_request:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
 
 jobs:
-  test_default_inputs:
-    name: Test with default inputs
+  smoke:
+    # Cross-OS coverage. Exercises the bootstrap install + PATH on each platform,
+    # the version-respects-request regression (#225 / #230 — Windows PATH shadow),
+    # and the bin_dest output regression (#247). Multi-version coverage on Linux
+    # so we don't pay 3x for major-version differences.
+    name: 'Smoke (${{ matrix.name }})'
 
     runs-on: ${{ matrix.os }}
 
     strategy:
       fail-fast: false
       matrix:
-        pnpm:
-          - 9.15.5
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
+        include:
+          - name: 'ubuntu / v9.15.5'
+            os: ubuntu-latest
+            version: '9.15.5'
+          - name: 'ubuntu / v10.33.0'
+            os: ubuntu-latest
+            version: '10.33.0'
+          - name: 'ubuntu / v11.25.0'
+            os: ubuntu-latest
+            version: '11.25.0'
+          - name: 'ubuntu / v12.3.4'
+            os: ubuntu-latest
+            version: '12.3.4'
+          - name: 'ubuntu / v9.15.5 / custom-dest'
+            os: ubuntu-latest
+            version: '9.15.5'
+            dest: '~/test/pnpm'
+          - name: 'macos / v9.15.5'
+            os: macos-latest
+            version: '9.15.5'
+          - name: 'macos / v12.3.4'
+            os: macos-latest
+            version: '12.3.4'
+          - name: 'windows / v9.15.5'
+            os: windows-latest
+            version: '9.15.5'
+          - name: 'windows / v12.3.4'
+            os: windows-latest
+            version: '12.3.4'
 
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - name: Run the action
+      - id: pnpm
+        name: Run the action
         uses: ./
         with:
-          version: 9.15.5
+          version: ${{ matrix.version }}
+          dest: ${{ matrix.dest || '~/setup-pnpm' }}
 
-      - name: 'Test: which'
-        run: which pnpm; which pnpx
-
-      - name: 'Test: version'
+      - name: 'Test: pnpm/pnpx on PATH report the requested version (incl. via bin_dest)'
+        # Pass paths via env, not template interpolation, so Windows
+        # backslashes in `bin_dest` aren't eaten by bash's escape handling.
+        env:
+          BIN_DEST: ${{ steps.pnpm.outputs.bin_dest }}
+          REQUIRED: ${{ matrix.version }}
         run: |
+          set -e
+          which pnpm
+          which pnpx
           actual="$(pnpm --version)"
-          echo "pnpm version: ${actual}"
-          if [[ ! "${actual}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-.+)?$ ]]; then
-            echo "ERROR: pnpm --version did not produce valid output"
+          echo "pnpm --version: ${actual}"
+          if [ "${actual}" != "${REQUIRED}" ]; then
+            echo "Expected pnpm version ${REQUIRED}, but got ${actual}"
+            exit 1
+          fi
+          bin_dest_version="$("$BIN_DEST/pnpm" --version)"
+          echo "bin_dest pnpm --version: ${bin_dest_version}"
+          if [ "${bin_dest_version}" != "${REQUIRED}" ]; then
+            echo "Expected ${REQUIRED} via bin_dest, but got ${bin_dest_version}"
             exit 1
           fi
         shell: bash
@@ -50,225 +92,302 @@ jobs:
           pnpm add is-odd
         shell: bash
 
-  test_dest:
-    name: Test with dest
+  manifest_pin:
+    # Folds the old test_package_manager_field, test_dev_engines, and
+    # test_dev_engines_on_fail_error jobs. The action's manifest handling is
+    # OS-independent, so ubuntu-only is sufficient.
+    name: 'Manifest pin: ${{ matrix.label }}'
 
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
 
     strategy:
       fail-fast: false
       matrix:
-        pnpm:
-          - 9.15.5
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
+        include:
+          - label: 'packageManager pnpm@9.15.5 (#227)'
+            manifest: '{"packageManager":"pnpm@9.15.5"}'
+            version: '9.15.5'
+          - label: 'packageManager pnpm@10.33.0'
+            manifest: '{"packageManager":"pnpm@10.33.0"}'
+            version: '10.33.0'
+          - label: 'devEngines onFail=download, exact'
+            manifest: '{"devEngines":{"packageManager":{"name":"pnpm","version":"9.15.5","onFail":"download"}}}'
+            version: '9.15.5'
+          - label: 'devEngines onFail=download, range'
+            manifest: '{"devEngines":{"packageManager":{"name":"pnpm","version":">=9.15.0","onFail":"download"}}}'
+            version: '>=9.15.0'
+          - label: 'devEngines onFail=error, exact (#252)'
+            manifest: '{"devEngines":{"packageManager":{"name":"pnpm","version":"9.15.5","onFail":"error"}}}'
+            version: '9.15.5'
+          - label: 'devEngines onFail=error, range (#252)'
+            manifest: '{"devEngines":{"packageManager":{"name":"pnpm","version":">=9.15.0","onFail":"error"}}}'
+            version: '>=9.15.0'
+          - label: 'explicit version: pnpm_config_pm_on_fail not exported'
+            # Regression guard for the af8e203 scope fix: when the user passes an
+            # explicit `version:` input, the action must NOT export
+            # pnpm_config_pm_on_fail=download, so the user's strict onFail policy
+            # is preserved. Asserted directly on the env var rather than pnpm
+            # runtime behavior — different pnpm majors read devEngines
+            # differently (v10 ignores it, v11+ honors it).
+            manifest: '{"devEngines":{"packageManager":{"name":"pnpm","version":"9.15.5","onFail":"error"}}}'
+            explicit_version: '10.33.0'
+            expect_pm_on_fail_unset: true
 
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up package.json
+        run: echo '${{ matrix.manifest }}' > package.json
+        shell: bash
 
       - name: Run the action
         uses: ./
         with:
-          version: 9.15.5
-          dest: ~/test/pnpm
+          version: ${{ matrix.explicit_version }}
 
-      - name: 'Test: which'
-        run: which pnpm && which pnpx
-
-      - name: 'Test: version'
-        run: |
-          actual="$(pnpm --version)"
-          echo "pnpm version: ${actual}"
-          if [[ ! "${actual}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-.+)?$ ]]; then
-            echo "ERROR: pnpm --version did not produce valid output"
-            exit 1
-          fi
-        shell: bash
-
-  test_standalone:
-    name: Test with standalone
-
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      fail-fast: false
-      matrix:
-        os:
-          - ubuntu-latest
-          - windows-latest
-
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-
-      - name: Run the action
-        uses: ./
-        with:
-          version: 9.15.0
-          standalone: true
-
-      - name: 'Test: which'
-        run: which pnpm
-
-      - name: 'Test: version'
-        run: |
-          actual="$(pnpm --version)"
-          echo "pnpm version: ${actual}"
-          if [[ ! "${actual}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-.+)?$ ]]; then
-            echo "ERROR: pnpm --version did not produce valid output"
-            exit 1
-          fi
-        shell: bash
-
-      - name: 'Test: install in a fresh project'
-        run: |
-          mkdir /tmp/test-standalone
-          cd /tmp/test-standalone
-          pnpm init
-          pnpm add is-odd
-        shell: bash
-
-  test_version_respects_request:
-    name: 'Test version input is actually installed (${{ matrix.version }}, ${{ matrix.os }})'
-    # Regression test for #225 / #230: the bootstrap pnpm on PATH was shadowing the self-updated binary,
-    # so a user requesting e.g. `version: 9.15.5` would silently get the bootstrap version.
-
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      fail-fast: false
-      matrix:
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
-        version:
-          - '9.15.5'
-          - '10.33.0'
-
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-
-      - name: Run the action
-        uses: ./
-        with:
-          version: ${{ matrix.version }}
-
-      - name: 'Test: exact version installed'
-        run: |
-          required='${{ matrix.version }}'
-          actual="$(pnpm --version)"
-          echo "pnpm version: ${actual}"
-          if [ "${actual}" != "${required}" ]; then
-            echo "Expected pnpm version ${required}, but got ${actual}"
-            exit 1
-          fi
-        shell: bash
-
-  test_package_manager_field:
-    name: 'Test packageManager field is respected (${{ matrix.version }}, ${{ matrix.os }})'
-    # Reproduces #227: when `packageManager` is set in package.json and no `version:` input is given,
-    # the action should install the version specified there.
-
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      fail-fast: false
-      matrix:
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
-        version:
-          - '9.15.5'
-          - '10.33.0'
-
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-
-      - name: Set up package.json with packageManager field
-        run: echo '{"packageManager":"pnpm@${{ matrix.version }}"}' > package.json
-        shell: bash
-
-      - name: Run the action
-        uses: ./
-
-      - name: 'Test: exact version installed'
-        run: |
-          required='${{ matrix.version }}'
-          actual="$(pnpm --version)"
-          echo "pnpm version: ${actual}"
-          if [ "${actual}" != "${required}" ]; then
-            echo "Expected pnpm version ${required}, but got ${actual}"
-            exit 1
-          fi
-        shell: bash
-
-  test_dev_engines:
-    name: Test with devEngines.packageManager
-
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      fail-fast: false
-      matrix:
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
-        version:
-          - '9.15.5'
-          - '>=9.15.0'
-
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-
-      - name: Set up package.json with devEngines.packageManager
-        run: echo '{"devEngines":{"packageManager":{"name":"pnpm","version":"${{ matrix.version }}","onFail":"download"}}}' > package.json
-        shell: bash
-
-      - name: Run the action
-        uses: ./
-
-      - name: 'Test: which'
-        run: which pnpm; which pnpx
-
-      - name: 'Test: version'
+      - name: 'Test: pnpm reports the pinned version'
+        if: ${{ !matrix.expect_pm_on_fail_unset }}
+        env:
+          REQUIRED: ${{ matrix.version }}
         run: |
           set -e
-          required='${{ matrix.version }}'
           actual="$(pnpm --version)"
           echo "pnpm version: ${actual}"
-
-          if [ "${required}" = ">=9.15.0" ]; then
+          if [ "${REQUIRED}" = ">=9.15.0" ]; then
             min="9.15.0"
             if [ "$(printf '%s\n' "${min}" "${actual}" | sort -V | head -n1)" != "${min}" ]; then
               echo "Expected pnpm version >= ${min}, but got ${actual}"
               exit 1
             fi
           else
-            if [ "${actual}" != "${required}" ]; then
-              echo "Expected pnpm version ${required}, but got ${actual}"
+            if [ "${actual}" != "${REQUIRED}" ]; then
+              echo "Expected pnpm version ${REQUIRED}, but got ${actual}"
               exit 1
             fi
           fi
         shell: bash
 
-  test_run_install:
-    name: 'Test with run_install (${{ matrix.run_install.name }}, ${{ matrix.os }})'
+      - name: 'Test: pnpm_config_pm_on_fail not exported (explicit version preserves strict policy)'
+        if: ${{ matrix.expect_pm_on_fail_unset }}
+        run: |
+          if [ -n "${pnpm_config_pm_on_fail:-}" ]; then
+            echo "Expected pnpm_config_pm_on_fail to be unset, but got: '${pnpm_config_pm_on_fail}'"
+            exit 1
+          fi
+          echo "pnpm_config_pm_on_fail is unset, as expected"
+        shell: bash
 
-    runs-on: ${{ matrix.os }}
+  standalone:
+    name: 'Native pnpm bootstrap (npm 12)'
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: 26
+
+      - name: Use npm 12
+        run: |
+          npm install --global npm@12.0.2
+          test "$(npm --version)" = "12.0.2"
+
+      - id: pnpm
+        name: Run the action
+        uses: ./
+        with:
+          version: 12
+          standalone: true
+
+      - name: 'Test: pnpm works'
+        env:
+          PNPM_DEST: ${{ steps.pnpm.outputs.dest }}
+        run: |
+          set -e
+          test -x "$PNPM_DEST/node_modules/pnpm/pnpm"
+          test ! -d "$PNPM_DEST/node_modules/@pnpm/exe"
+          which pnpm
+          actual="$(pnpm --version)"
+          if [ "${actual}" != "12.17.0" ]; then
+            echo "Expected 12.17.0, got ${actual}"
+            exit 1
+          fi
+          mkdir /tmp/test-standalone
+          cd /tmp/test-standalone
+          pnpm init
+          pnpm add is-odd
+        shell: bash
+
+  shared_store:
+    name: 'Repeated install with shared store (pnpm ${{ matrix.version }})'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        version: ['12.11.2', '12.16.1']
+    env:
+      REQUIRED: ${{ matrix.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Configure the shared store and project pin
+        run: |
+          config_home="$RUNNER_TEMP/pnpm-config"
+          store_dir="$RUNNER_TEMP/pnpm-store"
+          mkdir -p "$config_home/pnpm"
+          printf 'storeDir: %s\nenableGlobalVirtualStore: true\n' "$store_dir" > "$config_home/pnpm/config.yaml"
+          printf 'XDG_CONFIG_HOME=%s\nPNPM_STORE_DIR=%s\n' "$config_home" "$store_dir" >> "$GITHUB_ENV"
+          printf '{"packageManager":"pnpm@%s"}\n' "$REQUIRED" > package.json
+
+      - id: first
+        name: Install pnpm into a fresh destination
+        uses: ./
+        with:
+          dest: ${{ runner.temp }}/setup-pnpm
+          standalone: false
+
+      - name: Verify the first installation and populated store
+        working-directory: ${{ runner.temp }}
+        env:
+          BIN_DEST: ${{ steps.first.outputs.bin_dest }}
+        run: |
+          test "$("$BIN_DEST/pnpm" --version)" = "$REQUIRED"
+          store_path="$("$BIN_DEST/pnpm" store path --silent)"
+          case "$store_path/" in
+            "$PNPM_STORE_DIR/"*) ;;
+            *) echo "Unexpected store path: $store_path"; exit 1 ;;
+          esac
+          test -n "$(find "$PNPM_STORE_DIR" -type f -print -quit)"
+          touch "$PNPM_STORE_DIR/reused-by-second-install"
+
+      - id: second
+        name: Reinstall pnpm with the same destination and store
+        uses: ./
+        with:
+          dest: ${{ runner.temp }}/setup-pnpm
+          standalone: false
+
+      - name: Verify the second installation reused the store
+        working-directory: ${{ runner.temp }}
+        env:
+          BIN_DEST: ${{ steps.second.outputs.bin_dest }}
+        run: |
+          test -f "$PNPM_STORE_DIR/reused-by-second-install"
+          test "$("$BIN_DEST/pnpm" --version)" = "$REQUIRED"
+          test "$(pnpm --version)" = "$REQUIRED"
+
+  standalone_windows_self_update:
+    # Regression guard for the patchPnpmEnv PATH-shadow bug. When
+    # standalone: true on Windows AND the requested pnpm differs from the
+    # bootstrap, the previous patchPnpmEnv prepended node_modules/.bin to
+    # PATH; that directory contains an npm-created pnpm.cmd shim pointing
+    # at the BOOTSTRAP pnpm, which shadowed the self-updated pnpm at
+    # $PNPM_HOME/bin and caused `pnpm install` inside the action to run
+    # under the bootstrap version. Exercising a newer-pnpm-only flag
+    # (`--no-runtime`, added in 11.1.0) makes the regression assertable:
+    # if the bootstrap (11.0.4) handles the install, it errors with
+    # "Unknown option: 'runtime'".
+    name: 'Standalone Windows self-update (PATH regression)'
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up package.json with a minimal manifest
+        # run_install needs a manifest to install against. Removing the
+        # repo's existing pnpm-lock.yaml avoids frozen-lockfile mismatch.
+        run: |
+          rm -f pnpm-lock.yaml
+          echo '{"name":"sw","private":true,"packageManager":"pnpm@11.1.0"}' > package.json
+        shell: bash
+
+      - name: Run the action
+        uses: ./
+        with:
+          version: 11.1.0
+          standalone: true
+          run_install: |
+            args: ['--no-runtime']
+
+      - name: 'Test: pnpm install completed under the self-updated pnpm'
+        # If the bug recurs, the previous step's run_install will have failed
+        # the job with "Unknown option: 'runtime'", so reaching this step
+        # implies success. Still verify the version on PATH matches request.
+        env:
+          REQUIRED: '11.1.0'
+        run: |
+          set -e
+          actual="$(pnpm --version)"
+          echo "pnpm --version: ${actual}"
+          if [ "${actual}" != "${REQUIRED}" ]; then
+            echo "Expected pnpm ${REQUIRED}, got ${actual}"
+            exit 1
+          fi
+        shell: bash
+
+  cache_store_path:
+    # Regression guard for #233. When package.json pins a pnpm major that
+    # differs from the bootstrap pnpm's major, the bootstrap reports its
+    # own STORE_VERSION from `pnpm store path` (the `store` command skips
+    # pnpm's auto-switch). The user's actual `pnpm install` runs under the
+    # pinned version and writes to a different STORE_VERSION, so the post
+    # step's saveCache then fails with "Path Validation Error". The fix is
+    # to self-update the bootstrap to the pinned version up front.
+    name: 'Cache store path matches install (#233): ${{ matrix.label }}'
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - label: 'packageManager pnpm@10.33.0'
+            manifest: '{"packageManager":"pnpm@10.33.0","dependencies":{"is-odd":"3.0.1"}}'
+          - label: 'devEngines exact pnpm@10.33.0'
+            manifest: '{"devEngines":{"packageManager":{"name":"pnpm","version":"10.33.0"}},"dependencies":{"is-odd":"3.0.1"}}'
+          - label: 'devEngines range >=10 <11'
+            manifest: '{"devEngines":{"packageManager":{"name":"pnpm","version":">=10 <11"}},"dependencies":{"is-odd":"3.0.1"}}'
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up package.json
+        run: echo '${{ matrix.manifest }}' > package.json
+        shell: bash
+
+      - id: pnpm
+        uses: ./
+        with:
+          cache: true
+          run_install: |
+            - args: [--no-frozen-lockfile]
+
+      - name: 'Test: store path computed by the action exists on disk'
+        run: |
+          set -e
+          actual="$(pnpm store path --silent)"
+          echo "pnpm store path: ${actual}"
+          if [ ! -d "${actual}" ]; then
+            echo "Expected store path to exist on disk; cache save would fail"
+            exit 1
+          fi
+        shell: bash
+
+  run_install:
+    name: 'run_install (${{ matrix.run_install.name }})'
+
+    runs-on: ubuntu-latest
 
     strategy:
       fail-fast: false
       matrix:
-        pnpm:
-          - 9.15.5
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
         run_install:
           - name: 'null'
             value: 'null'
@@ -281,7 +400,7 @@ jobs:
                 - yarn
 
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Run the action
         uses: ./
@@ -289,15 +408,14 @@ jobs:
           version: 9.15.5
           run_install: ${{ matrix.run_install.value }}
 
-      - name: 'Test: which'
-        run: which pnpm; which pnpx
-
-      - name: 'Test: version'
+      - name: 'Test: pnpm works'
         run: |
+          set -e
+          which pnpm
+          which pnpx
           actual="$(pnpm --version)"
-          echo "pnpm version: ${actual}"
-          if [[ ! "${actual}" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-.+)?$ ]]; then
-            echo "ERROR: pnpm --version did not produce valid output"
+          if [ "${actual}" != "9.15.5" ]; then
+            echo "Expected 9.15.5, got ${actual}"
             exit 1
           fi
         shell: bash

README.md

@@ -1,18 +1,70 @@
-> ## :warning: Upgrade from v2!
+> [!IMPORTANT]
+> **This action supports pnpm v12 and earlier.**
 >
-> The v2 version of this action [has stopped working](https://github.com/pnpm/action-setup/issues/135) with newer Node.js versions. Please, upgrade to the latest version to fix any issues.
+> For pnpm v11 and newer, [`pnpm/setup`](https://github.com/pnpm/setup) is also available. It downloads pnpm's self-contained release binary (no Node.js or npm required) and can install a JavaScript runtime (Node.js, Bun, or Deno) in the same step, replacing `actions/setup-node` when its feature set fits your workflow.
+>
+> You can continue using `pnpm/action-setup` with `actions/setup-node`, including for pnpm v11 and v12. See [Using pnpm/setup instead](#using-pnpmsetup-instead) below if you want a single action to install pnpm and a JavaScript runtime.
+>
+> `pnpm/setup` cannot install pnpm v11 on Intel macOS (`darwin-x64`), where no standalone pnpm v11 binary is published. On that platform, run `actions/setup-node` with Node.js 22.13 or newer before `pnpm/action-setup`, or upgrade to pnpm v12.
 
 # Setup pnpm
 
 Install pnpm package manager.
 
+> ## :warning: Upgrade from v2!
+>
+> The v2 version of this action [has stopped working](https://github.com/pnpm/action-setup/issues/135) with newer Node.js versions. Please, upgrade to the latest version to fix any issues.
+
+## Using pnpm/setup instead
+
+[`pnpm/setup`](https://github.com/pnpm/setup) installs pnpm v11+ as a native standalone executable and can install Node.js, Bun, or Deno in the same step, so a typical workflow no longer needs `actions/setup-node` or an explicit `pnpm install` step:
+
+```yaml
+steps:
+  - uses: actions/checkout@v6
+
+  # Before:
+  # - uses: pnpm/action-setup@v6
+  #   with:
+  #     version: 10
+  #     cache: true
+  # - uses: actions/setup-node@v4
+  #   with:
+  #     node-version: 22
+  # - run: pnpm install
+
+  # After:
+  - uses: pnpm/setup@v1
+    with:
+      version: 11
+      runtime: node@22
+      cache: true
+```
+
+The `version` input can be omitted only when `packageManager` (or `devEngines.packageManager`) in `package.json` declares pnpm v11 or newer; otherwise keep it explicit, since `pnpm/setup` requires pnpm v11+.
+
+Input and output changes:
+
+| `pnpm/action-setup` | `pnpm/setup` | Notes |
+| ------------------- | ------------ | ----- |
+| `version` | `version` | Must resolve to pnpm v11 or newer. As before, it can be omitted when `packageManager` (or `devEngines.packageManager`) is set in `package.json`. |
+| `dest` | `dest` | Unchanged. |
+| `run_install` | `install` | `pnpm/setup` runs `pnpm install` automatically when a `package.json` is present (`install: true` by default); set `install: false` to skip it. The object/array form (`recursive`, `cwd`, `args`) is not supported — run those commands in separate steps. |
+| `cache` | `cache` | Unchanged. |
+| `cache_dependency_path` | `cache-dependency-path` | Renamed to kebab-case. |
+| `package_json_file` | `package-json-file` | Renamed to kebab-case. |
+| `standalone` | removed | `pnpm/setup` always installs the standalone native executable. |
+| n/a | `runtime` | New: installs Node.js, Bun, or Deno (e.g. `node@22`, `bun@latest`, `deno@2`), or reads `devEngines.runtime` from `package.json`. |
+| n/a | `token` | New: GitHub token for release lookup; defaults to `${{ github.token }}` and rarely needs to be set. |
+| `bin_dest` (output) | `bin-dest` (output) | Renamed to kebab-case. New outputs `runtime-name` and `runtime-version` describe the installed runtime. |
+
 ## Inputs
 
 ### `version`
 
 Version of pnpm to install.
 
-**Optional** when there is a [`packageManager` field in the `package.json`](https://nodejs.org/api/corepack.html).
+**Optional** when `package.json` declares pnpm in `packageManager`, or sets `devEngines.packageManager.name` to `"pnpm"` and provides `devEngines.packageManager.version`.
 
 otherwise, this field is **required** It supports npm versioning scheme, it could be an exact version (such as `10.9.8`), or a version range (such as `10`, `10.x.x`, `10.9.x`, `^10.9.8`, `*`, etc.), or `latest`.
 
@@ -48,17 +100,17 @@ If `run_install` is a YAML string representation of either an object or an array
 
 ### `cache_dependency_path`
 
-**Optional** (_type:_ `string|string[]`, _default:_ `pnpm-lock.yaml`) File path to the pnpm lockfile, which contents hash will be used as a cache key.
+**Optional** (_type:_ `string`, _default:_ `pnpm-lock.yaml`) File path to the pnpm lockfile, whose contents hash will be used as a cache key. Accepts multiple paths delimited by newlines.
 
 ### `package_json_file`
 
-**Optional** (_type:_ `string`, _default:_ `package.json`) File path to the `package.json`/[`package.yaml`](https://github.com/pnpm/pnpm/pull/1799) to read "packageManager" configuration.
+**Optional** (_type:_ `string`, _default:_ `package.json`) File path to the `package.json`/[`package.yaml`](https://github.com/pnpm/pnpm/pull/1799) to read `packageManager` or `devEngines.packageManager` configuration.
 
 ### `standalone`
 
-**Optional** (_type:_ `boolean`, _default:_ `false`) When set to true, [@pnpm/exe](https://www.npmjs.com/package/@pnpm/exe), which is a Node.js bundled package, will be installed, enabling using `pnpm` without Node.js.
+**Optional** (_type:_ `boolean`, _default:_ `false`) For pnpm v11 and earlier, install [@pnpm/exe](https://www.npmjs.com/package/@pnpm/exe), enabling pnpm to run without Node.js.
 
-This is useful when you want to use a incompatible pair of Node.js and pnpm.
+For pnpm v12, this input has no effect because the plain `pnpm` package already installs a standalone native executable.
 
 ## Outputs
 
@@ -74,7 +126,7 @@ Location of `pnpm` and `pnpx` command.
 
 ### Install only pnpm without `packageManager`
 
-This works when the repo either doesn't have a `package.json` or has a `package.json` but it doesn't specify `packageManager`.
+This works when the repo either doesn't have a `package.json` or has a `package.json` but it doesn't specify `packageManager` or `devEngines.packageManager`.
 
 ```yaml
 on:
@@ -93,7 +145,7 @@ jobs:
 
 ###  Install only pnpm with `packageManager`
 
-Omit `version` input to use the version in the [`packageManager` field in the `package.json`](https://nodejs.org/api/corepack.html).
+Omit `version` input to use the version in the [`packageManager` or `devEngines.packageManager` field in the `package.json`](https://nodejs.org/api/corepack.html).
 
 ```yaml
 on:
@@ -105,6 +157,8 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      - uses: actions/checkout@v6
+
       - uses: pnpm/action-setup@v6
 ```
 
@@ -158,9 +212,36 @@ jobs:
 
 **Note:** You don't need to run `pnpm store prune` at the end; post-action has already taken care of that.
 
+### Cache dependencies from multiple lockfiles
+
+```yaml
+on:
+  - push
+  - pull_request
+
+jobs:
+  cache-and-install-multiple:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 10
+          cache: true
+          cache_dependency_path: |
+            one/pnpm-lock.yaml
+            two/pnpm-lock.yaml
+          run_install: |
+            - cwd: one
+            - cwd: two
+```
+
 ## Notes
 
-This action does not setup Node.js for you, use [actions/setup-node](https://github.com/actions/setup-node) yourself.
+This action does not set up Node.js. Use [actions/setup-node](https://github.com/actions/setup-node) yourself. As an alternative for pnpm v11 or newer, [`pnpm/setup`](https://github.com/pnpm/setup) can install pnpm and Node.js in a single step.
 
 ## License
 

action.yml

@@ -20,7 +20,7 @@ inputs:
     required: false
     default: 'false'
   cache_dependency_path:
-    description: File path to the pnpm lockfile, which contents hash will be used as a cache key
+    description: File path to the pnpm lockfile, whose contents hash will be used as a cache key. Accepts multiple paths delimited by newlines.
     required: false
     default: 'pnpm-lock.yaml'
   package_json_file:
@@ -28,7 +28,7 @@ inputs:
     required: false
     default: 'package.json'
   standalone:
-    description: When set to true, @pnpm/exe, which is a Node.js bundled package, will be installed, enabling using pnpm without Node.js.
+    description: When set to true for pnpm v11 and earlier, install @pnpm/exe to use pnpm without Node.js. pnpm v12 uses the plain pnpm package's native executable.
     required: false
     default: 'false'
 outputs:

package.json

@@ -4,7 +4,8 @@
     "build:bundle": "esbuild src/index.ts --bundle --platform=node --target=node24 --format=cjs --minify --outfile=dist/index.js --loader:.json=json",
     "build": "pnpm run build:bundle",
     "start": "pnpm run build && sh ./run.sh",
-    "update-bootstrap": "node scripts/update-bootstrap.mjs"
+    "update-bootstrap": "node scripts/update-bootstrap.mjs",
+    "test": "node --experimental-test-module-mocks --test test/*.test.mjs"
   },
   "dependencies": {
     "@actions/cache": "^4.1.0",
@@ -14,10 +15,12 @@
     "@types/expand-tilde": "^2.0.2",
     "@types/node": "^22.0.0",
     "expand-tilde": "^2.0.2",
+    "semver": "^7.8.5",
     "yaml": "^2.3.4",
     "zod": "^3.22.4"
   },
   "devDependencies": {
+    "@types/semver": "^7.8.0",
     "esbuild": "^0.27.4",
     "typescript": "^5.3.3"
   }

pnpm-lock.yaml

@@ -29,6 +29,9 @@ importers:
       expand-tilde:
         specifier: ^2.0.2
         version: 2.0.2
+      semver:
+        specifier: ^7.8.5
+        version: 7.8.5
       yaml:
         specifier: ^2.3.4
         version: 2.7.0
@@ -36,6 +39,9 @@ importers:
         specifier: ^3.22.4
         version: 3.24.1
     devDependencies:
+      '@types/semver':
+        specifier: ^7.8.0
+        version: 7.8.0
       esbuild:
         specifier: ^0.27.4
         version: 0.27.4
@@ -293,6 +299,9 @@ packages:
   '@types/node@22.19.11':
     resolution: {integrity: sha512-BH7YwL6rA93ReqeQS1c4bsPpcfOmJasG+Fkr6Y59q83f9M1WcBRHR2vM+P9eOisYRcN3ujQoiZY8uk5W+1WL8w==}
 
+  '@types/semver@7.8.0':
+    resolution: {integrity: sha512-1mAINjtQCXXeLkJ9ehXkwOcBpqtLxiVtKhpUf83DdRNdQKV0iXZpaHYqRr7nj+wvxuJzoAmAwXI+sCNMv1CzLQ==}
+
   '@typespec/ts-http-runtime@0.3.0':
     resolution: {integrity: sha512-sOx1PKSuFwnIl7z4RN0Ls7N9AQawmR9r66eI5rFCzLDIs8HTIYrIpH9QjYWoX0lkgGrkLxXhi4QnK7MizPRrIg==}
     engines: {node: '>=20.0.0'}
@@ -463,6 +472,11 @@ packages:
     resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
     hasBin: true
 
+  semver@7.8.5:
+    resolution: {integrity: sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==}
+    engines: {node: '>=10'}
+    hasBin: true
+
   strnum@2.1.1:
     resolution: {integrity: sha512-7ZvoFTiCnGxBtDqJ//Cu6fWtZtc7Y3x+QOirG15wztbdngGSkht27o2pyGWrVy0b4WAy3jbKmnoK6g5VlVNUUw==}
 
@@ -770,6 +784,8 @@ snapshots:
     dependencies:
       undici-types: 6.21.0
 
+  '@types/semver@7.8.0': {}
+
   '@typespec/ts-http-runtime@0.3.0':
     dependencies:
       http-proxy-agent: 7.0.2
@@ -957,6 +973,8 @@ snapshots:
 
   semver@6.3.1: {}
 
+  semver@7.8.5: {}
+
   strnum@2.1.1: {}
 
   tr46@0.0.3: {}

scripts/update-bootstrap.mjs

@@ -1,9 +1,5 @@
 #!/usr/bin/env node
 
-// Usage: node scripts/update-bootstrap.mjs [version]
-// If version is omitted, fetches the latest next-11 tag from npm.
-// Regenerates the bootstrap lockfiles used by action-setup to install pnpm via npm.
-
 import { execSync } from 'child_process'
 import { mkdtempSync, rmSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
@@ -11,21 +7,24 @@ import { tmpdir } from 'os'
 
 const BOOTSTRAP_DIR = new URL('../src/install-pnpm/bootstrap/', import.meta.url).pathname
 
-const version = process.argv[2] || resolveLatestVersion()
+const legacyVersion = process.argv[2] || resolveLatestVersion(11)
+const nativeVersion = process.argv[3] || resolveLatestVersion(12)
 
-console.log(`Updating bootstrap lockfiles to pnpm@${version} ...`)
+console.log(`Updating bootstrap lockfiles to pnpm@${legacyVersion} and pnpm@${nativeVersion} ...`)
 
-generateLock('pnpm-lock.json', { pnpm: version }, 'bootstrap-pnpm')
-generateLock('exe-lock.json', { '@pnpm/exe': version }, 'bootstrap-exe')
+generateLock('pnpm-lock.json', { pnpm: legacyVersion }, 'bootstrap-pnpm')
+generateLock('exe-lock.json', { '@pnpm/exe': legacyVersion }, 'bootstrap-exe')
+generateLock('native-lock.json', { pnpm: nativeVersion }, 'bootstrap-native-pnpm')
 
 console.log('Done!')
 
-function resolveLatestVersion() {
-  const json = execSync('npm view @pnpm/exe dist-tags --json', { encoding: 'utf8' })
-  const tags = JSON.parse(json)
-  const version = tags['next-11'] || tags['latest']
+function resolveLatestVersion(major) {
+  const json = execSync('npm view pnpm dist-tags --json', { encoding: 'utf8' })
+  const parsed = JSON.parse(json)
+  const tags = Array.isArray(parsed) ? parsed[0] : parsed
+  const version = tags[`next-${major}`] || tags[`latest-${major}`]
   if (!version) {
-    console.error('Could not determine latest pnpm version from npm dist-tags')
+    console.error(`Could not determine latest pnpm v${major} version from npm dist-tags`)
     process.exit(1)
   }
   return version
@@ -40,7 +39,8 @@ function generateLock(filename, dependencies, name) {
     const parsed = JSON.parse(lock)
     parsed.name = name
     writeFileSync(join(BOOTSTRAP_DIR, filename), JSON.stringify(parsed, null, 2) + '\n')
-    console.log(`  ${filename} -> ${Object.values(dependencies)[0]}@${version}`)
+    const [packageName, packageVersion] = Object.entries(dependencies)[0]
+    console.log(`  ${filename} -> ${packageName}@${packageVersion}`)
   } finally {
     rmSync(tmp, { recursive: true, force: true })
   }

src/cache-restore/run.ts

@@ -18,9 +18,18 @@ export async function runRestoreCache(inputs: Inputs) {
   debug(`Primary key is ${primaryKey}`)
   saveState('cache_primary_key', primaryKey)
 
-  let cacheKey = await restoreCache([cachePath], primaryKey)
+  // We don't need to download everything again if only one dependency changed
+  // We can still re-use previous store to cache the rest of the unchanged dependencies
+  const restoreKeys = [
+    `pnpm-cache-${process.env.RUNNER_OS}-${os.arch()}-`
+  ];
 
-  setOutput('cache-hit', Boolean(cacheKey))
+  let cacheKey = await restoreCache([cachePath], primaryKey, restoreKeys)
+
+  // A restore-key (prefix) match still restores an older store, but "cache-hit"
+  // must only report an exact primary-key match, so dependency installation
+  // is not skipped when the lockfile has changed.
+  setOutput('cache-hit', cacheKey === primaryKey)
 
   if (!cacheKey) {
     info(`Cache is not found`)

src/cache-save/run.ts

@@ -1,5 +1,6 @@
 import { saveCache } from '@actions/cache'
 import { getState, info } from '@actions/core'
+import { access } from 'fs/promises'
 
 export async function runSaveCache() {
   const state = getState('cache_restored_key')
@@ -11,6 +12,17 @@ export async function runSaveCache() {
     return
   }
 
+  try {
+    await access(cachePath)
+  } catch (error) {
+    if (!(error instanceof Error)) throw error
+    if (!('code' in error)) throw error
+    if (error.code !== 'ENOENT') throw error
+
+    info(`Cache path ${cachePath} does not exist, not saving cache.`)
+    return
+  }
+
   const cacheId = await saveCache([cachePath], primaryKey)
   if (cacheId == -1) return
 

src/index.ts

@@ -8,28 +8,30 @@ import pnpmInstall from './pnpm-install'
 import pruneStore from './pnpm-store-prune'
 
 async function main() {
-  const inputs = getInputs()
-
   if (getState('is_post') === 'true') {
-    await runPost(inputs)
+    await runPost()
   } else {
-    await runMain(inputs)
+    await runMain()
   }
 }
 
-async function runMain(inputs: Inputs) {
+async function runMain() {
+  const inputs = getInputs()
+  saveState('inputs', inputs)
   saveState('is_post', 'true')
 
-  await installPnpm(inputs)
+  const binDest = await installPnpm(inputs)
+  if (binDest === undefined) return
   console.log('Installation Completed!')
-  setOutputs(inputs)
+  setOutputs(inputs, binDest)
 
   await restoreCache(inputs)
 
   pnpmInstall(inputs)
 }
 
-async function runPost(inputs: Inputs) {
+async function runPost() {
+  const inputs = JSON.parse(getState('inputs')) as Inputs
   pruneStore(inputs)
   await saveCache(inputs)
 }

src/install-pnpm/bootstrap/exe-lock.json

@@ -5,18 +5,18 @@
   "packages": {
     "": {
       "dependencies": {
-        "@pnpm/exe": "11.0.0-rc.5"
+        "@pnpm/exe": "11.28.10"
       }
     },
     "node_modules/@pnpm/exe": {
-      "version": "11.0.0-rc.5",
-      "resolved": "https://registry.npmjs.org/@pnpm/exe/-/exe-11.0.0-rc.5.tgz",
-      "integrity": "sha512-HT1HxzeFc6RVIMhngQZ7bQgTNzF0IckeFpOvnwCJKfsjfsD/po3LvUVsidCvpALxCWOft1TuBZUkdHq03pEolA==",
+      "version": "11.28.10",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe/-/exe-11.28.10.tgz",
+      "integrity": "sha512-prIiCu3BBaIlim+JD6x2VnqCAp4Er4CevPhrIhOnXK7TRVjhNeULBEv9F7E5ZmEtseR2G+foubhcMZmM6eEqqg==",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
         "@reflink/reflink": "0.1.19",
-        "detect-libc": "^2.0.3"
+        "detect-libc": "^2.1.2"
       },
       "bin": {
         "pn": "pn",
@@ -28,20 +28,18 @@
         "url": "https://opencollective.com/pnpm"
       },
       "optionalDependencies": {
-        "@pnpm/linux-arm64": "11.0.0-rc.5",
-        "@pnpm/linux-x64": "11.0.0-rc.5",
-        "@pnpm/linuxstatic-arm64": "11.0.0-rc.5",
-        "@pnpm/linuxstatic-x64": "11.0.0-rc.5",
-        "@pnpm/macos-arm64": "11.0.0-rc.5",
-        "@pnpm/macos-x64": "11.0.0-rc.5",
-        "@pnpm/win-arm64": "11.0.0-rc.5",
-        "@pnpm/win-x64": "11.0.0-rc.5"
+        "@pnpm/linux-arm64": "11.28.10",
+        "@pnpm/linux-x64": "11.28.10",
+        "@pnpm/linuxstatic-x64": "11.28.10",
+        "@pnpm/macos-arm64": "11.28.10",
+        "@pnpm/win-arm64": "11.28.10",
+        "@pnpm/win-x64": "11.28.10"
       }
     },
     "node_modules/@pnpm/linux-arm64": {
-      "version": "11.0.0-rc.5",
-      "resolved": "https://registry.npmjs.org/@pnpm/linux-arm64/-/linux-arm64-11.0.0-rc.5.tgz",
-      "integrity": "sha512-AreNJJI0r5oEsv5+i+FMVK8AeYs0MpWTGWc2GQwf7qi/w8uA8UxVlIDwhgwY+R6YgdrYVrEjgbU4WcqIqYfgog==",
+      "version": "11.28.10",
+      "resolved": "https://registry.npmjs.org/@pnpm/linux-arm64/-/linux-arm64-11.28.10.tgz",
+      "integrity": "sha512-gtNgBYw2s0MLOU980IlqFqvc90iL9y7W6VIRQB8wydgbgeoIU1G0qUOWBRIKB57xDgVuFp7gnTWdwQ2lF2sU1Q==",
       "cpu": [
         "arm64"
       ],
@@ -55,9 +53,9 @@
       }
     },
     "node_modules/@pnpm/linux-x64": {
-      "version": "11.0.0-rc.5",
-      "resolved": "https://registry.npmjs.org/@pnpm/linux-x64/-/linux-x64-11.0.0-rc.5.tgz",
-      "integrity": "sha512-NzZPWeIVxCEfQs84wR/O3IND2HSDOClPB2L8vvkWb8KQ4pczOG2x3aNkltXDwYVKxvw4URmwct5u57JGTEvtfg==",
+      "version": "11.28.10",
+      "resolved": "https://registry.npmjs.org/@pnpm/linux-x64/-/linux-x64-11.28.10.tgz",
+      "integrity": "sha512-PCJF+0FwwHBOR7oBp3ySjvk7m1LQUhTN2xfLk3e+v0h036PgY9Z2Ldtu+l4xIYZoI6eEwBSQFXGLxslWrcZ5jg==",
       "cpu": [
         "x64"
       ],
@@ -70,29 +68,16 @@
         "url": "https://opencollective.com/pnpm"
       }
     },
-    "node_modules/@pnpm/linuxstatic-arm64": {
-      "version": "11.0.0-rc.5",
-      "resolved": "https://registry.npmjs.org/@pnpm/linuxstatic-arm64/-/linuxstatic-arm64-11.0.0-rc.5.tgz",
-      "integrity": "sha512-xK+U/fJDkvzs4ktswrCZ03cTSEAeFTfgUG88r2J+6JEDGuY/foNOMnnSNOiSplpaufY+Ie+uL+PEDlTyIy46Xg==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "funding": {
-        "url": "https://opencollective.com/pnpm"
-      }
-    },
     "node_modules/@pnpm/linuxstatic-x64": {
-      "version": "11.0.0-rc.5",
-      "resolved": "https://registry.npmjs.org/@pnpm/linuxstatic-x64/-/linuxstatic-x64-11.0.0-rc.5.tgz",
-      "integrity": "sha512-Z1kSilngaM2URfPhBjam/xhMDAn5jl8V0L5CjG/Gg5unmKkipyF93OYMpfnny7A9p1KWi6sNql/KufzUmRP4Eg==",
+      "version": "11.28.10",
+      "resolved": "https://registry.npmjs.org/@pnpm/linuxstatic-x64/-/linuxstatic-x64-11.28.10.tgz",
+      "integrity": "sha512-kkcKBNPEx/xyW97inm4pEs6VkuY6Cy7w6gWaCVbv8qVmyqsyF4yFXJwUG7VxqmCnwVhSb2x/122S9UZumQns4A==",
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -103,9 +88,9 @@
       }
     },
     "node_modules/@pnpm/macos-arm64": {
-      "version": "11.0.0-rc.5",
-      "resolved": "https://registry.npmjs.org/@pnpm/macos-arm64/-/macos-arm64-11.0.0-rc.5.tgz",
-      "integrity": "sha512-98p3ilSzkyusC2bxk7Ya34CWt9MeJy/+kpXfwn9YgnOD7GDqCjYY9dlPB9yrkdtKUUMeOIvOuacAQTWnCg2GOQ==",
+      "version": "11.28.10",
+      "resolved": "https://registry.npmjs.org/@pnpm/macos-arm64/-/macos-arm64-11.28.10.tgz",
+      "integrity": "sha512-eT/HzSBZHjZk2xb+XmTbLIPPSMeHzK8xov4mD9oQWwfplYBTU5P21yoJp6GNFLql1IXAoSaFeTv6EZ2DwBj/Eg==",
       "cpu": [
         "arm64"
       ],
@@ -118,26 +103,10 @@
         "url": "https://opencollective.com/pnpm"
       }
     },
-    "node_modules/@pnpm/macos-x64": {
-      "version": "11.0.0-rc.5",
-      "resolved": "https://registry.npmjs.org/@pnpm/macos-x64/-/macos-x64-11.0.0-rc.5.tgz",
-      "integrity": "sha512-WZ9UqjTbZN+dMZcy4qaPDsEo4sxTIrw5H+fDvdxT1GUavsf8SBDpvzZMHrGDQ/k22H8oKvPtJ+RGd/Ie5dvbuA==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "funding": {
-        "url": "https://opencollective.com/pnpm"
-      }
-    },
     "node_modules/@pnpm/win-arm64": {
-      "version": "11.0.0-rc.5",
-      "resolved": "https://registry.npmjs.org/@pnpm/win-arm64/-/win-arm64-11.0.0-rc.5.tgz",
-      "integrity": "sha512-hxgDmF4xpSVvUPvH+HdMllvHcV2zuYUn/uK182gzFvZ9DE0xEGVj09XaSn5VMbpa32i25oIqaT89QfMcOw/TJg==",
+      "version": "11.28.10",
+      "resolved": "https://registry.npmjs.org/@pnpm/win-arm64/-/win-arm64-11.28.10.tgz",
+      "integrity": "sha512-UFeYraIlLHNUBgMarcAX/jK3PR2iWfI4SJL8fucVWNHivdyXNQYLmUhf+8a6MPdh4Sr0/2W/h6LqzVdjnpPx6g==",
       "cpu": [
         "arm64"
       ],
@@ -151,9 +120,9 @@
       }
     },
     "node_modules/@pnpm/win-x64": {
-      "version": "11.0.0-rc.5",
-      "resolved": "https://registry.npmjs.org/@pnpm/win-x64/-/win-x64-11.0.0-rc.5.tgz",
-      "integrity": "sha512-B1H/6jhzW/6VLr8Bc3zOhMd2P3srANWytuBq0uppR5c7OJwUlqXqJtB6Q4nOEjWYZ2sA5m2xuFiaMeioZiiqgA==",
+      "version": "11.28.10",
+      "resolved": "https://registry.npmjs.org/@pnpm/win-x64/-/win-x64-11.28.10.tgz",
+      "integrity": "sha512-1Do1wLHqiLVQac53DqRtqz0h5UCetoI1oaUZJ62L2wDW4sfe/MBs427rwyaiGZzYLps8glsD1aZXT5uAv1zx8A==",
       "cpu": [
         "x64"
       ],
@@ -224,6 +193,9 @@
       "cpu": [
         "arm64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -240,6 +212,9 @@
       "cpu": [
         "arm64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -256,6 +231,9 @@
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -272,6 +250,9 @@
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [

src/install-pnpm/bootstrap/native-lock.json

@@ -0,0 +1,247 @@
+{
+  "name": "bootstrap-native-pnpm",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "dependencies": {
+        "pnpm": "12.17.0"
+      }
+    },
+    "node_modules/@pnpm/exe.android-arm64": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.android-arm64/-/exe.android-arm64-12.17.0.tgz",
+      "integrity": "sha512-gwu/F5YyoJp1bIbrIBl7B8JO3rkjkGlKikwQg9s0aVa5xWaBYIqPX+ZJqQ7I4D1YfbdI/Omfze0+6vnYiWHG6A==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@pnpm/exe.android-x64": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.android-x64/-/exe.android-x64-12.17.0.tgz",
+      "integrity": "sha512-qUNhCvWyeBrUByNWkqqQ3Koy1gIAQ8UV5HDHXxoo5NUWVTde0Ld2BxweNwWJw8CNKpqEGceCUdjZ506JYpTjJg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@pnpm/exe.darwin-arm64": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.darwin-arm64/-/exe.darwin-arm64-12.17.0.tgz",
+      "integrity": "sha512-0nkEqRLIbrm7dWl+p2EPpmyNKyM0bbdPEovdtMhHYbhkO+Vls38S+6emkx8kSTAr75BNXYXkCl4RtGinGG4Erg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@pnpm/exe.darwin-x64": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.darwin-x64/-/exe.darwin-x64-12.17.0.tgz",
+      "integrity": "sha512-w89cboNi4KCzmt/dSKrE4ijVNKICKiZsE9TcIWf77Tz+VpoDfuhPSmWPZK+iCHBvlI/9dIN+M3HiPPVsFnAx4Q==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@pnpm/exe.freebsd-x64": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.freebsd-x64/-/exe.freebsd-x64-12.17.0.tgz",
+      "integrity": "sha512-DJ0FOaUDXc71icSgiuBFEvqReqoSiS/rmnC6kltoiC3MzPyw3awcGbT/7FnnYzi/ziuoTC7v6vfBh0Vzv7VKOQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@pnpm/exe.linux-arm64": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-arm64/-/exe.linux-arm64-12.17.0.tgz",
+      "integrity": "sha512-Cj2nIzWTVm6ZuhQHqL9SiJ11scBnEGxJyNg7tYQPzh9fVF5UVRkv+LbyfwdftnAtJerK/7HDpK/55WeQqp8OkA==",
+      "cpu": [
+        "arm64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@pnpm/exe.linux-arm64-musl": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-arm64-musl/-/exe.linux-arm64-musl-12.17.0.tgz",
+      "integrity": "sha512-w5ZwZ4j8S804DGhMYlLLpc+G3Kkc+5GlDO++LLvO/nDIXBTHRhdxPfQBQU08q31k0JYfp3wXCQk0Y7DnsuVF6w==",
+      "cpu": [
+        "arm64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@pnpm/exe.linux-ppc64": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-ppc64/-/exe.linux-ppc64-12.17.0.tgz",
+      "integrity": "sha512-Gb//Wm15fXl+qWcxjNQmwlYDjGiJOnLU/A9uRZYmtkyZie2Yx8AHI6XkUIJioQz99TwVDKQ87ywD5Jtk8zcgyg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@pnpm/exe.linux-riscv64": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-riscv64/-/exe.linux-riscv64-12.17.0.tgz",
+      "integrity": "sha512-+kItEcFjdVZEDzODsc7icb8cB+3AouCrEzOCezzxLITRhw86m9t3J/qyPdcFELBjeMnS+IXV8sJaSCQcpSqfgA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@pnpm/exe.linux-s390x": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-s390x/-/exe.linux-s390x-12.17.0.tgz",
+      "integrity": "sha512-jf5ghD2uDeknWQgK/EsCFNwlyL7BYLWfXe687g5UMVFclPLt524CREZ8Yl5hf4u7p3evCIPBN/m5I1QXUmJpHw==",
+      "cpu": [
+        "s390x"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@pnpm/exe.linux-x64": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-x64/-/exe.linux-x64-12.17.0.tgz",
+      "integrity": "sha512-vQAusDzMofc/Ee4KOUYjE6FWeHOlMGQyvhR7W39QSamVeJWS16co/n+bhjdjwjI3UFh8IWOpamvTS+b4lvQUog==",
+      "cpu": [
+        "x64"
+      ],
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@pnpm/exe.linux-x64-musl": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.linux-x64-musl/-/exe.linux-x64-musl-12.17.0.tgz",
+      "integrity": "sha512-JGxrGSxkDkqRAUD49T9dOnKyJkQ3bWBeHnYH4o4mvj09R9eUzhWFi8oa6WPNyCO0/7/Max2gsSfgXOHj3QW7ug==",
+      "cpu": [
+        "x64"
+      ],
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@pnpm/exe.win32-arm64": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.win32-arm64/-/exe.win32-arm64-12.17.0.tgz",
+      "integrity": "sha512-qDQh8rmyK5sxlaCSCADcmPrvytJabMCbxtJ0nCitzRo2j3/8BhzLjlOcWF3C6iPGhR5CbIb+btNy+VCVhd06mQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@pnpm/exe.win32-x64": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/@pnpm/exe.win32-x64/-/exe.win32-x64-12.17.0.tgz",
+      "integrity": "sha512-qCo1OQlE3WrFZIAUK0O5EoupLaQ1fST7zNX8Qd+Tc4ojWgCvYA/ze0uP9hox8mSFC/JPAGRSG5o8gUBSq2rRxw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/pnpm": {
+      "version": "12.17.0",
+      "resolved": "https://registry.npmjs.org/pnpm/-/pnpm-12.17.0.tgz",
+      "integrity": "sha512-uNIj6+wEtYContIG2qcdG8y2oe4dUu+pXMOw23UnFWHfjw2OLEOt05xewIAYr3qKlRCOcJD5Win4hye3pA/VPQ==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "pn": "pn",
+        "pnpm": "pnpm",
+        "pnpx": "pnpx",
+        "pnx": "pnx"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@pnpm/exe.android-arm64": "12.17.0",
+        "@pnpm/exe.android-x64": "12.17.0",
+        "@pnpm/exe.darwin-arm64": "12.17.0",
+        "@pnpm/exe.darwin-x64": "12.17.0",
+        "@pnpm/exe.freebsd-x64": "12.17.0",
+        "@pnpm/exe.linux-arm64": "12.17.0",
+        "@pnpm/exe.linux-arm64-musl": "12.17.0",
+        "@pnpm/exe.linux-ppc64": "12.17.0",
+        "@pnpm/exe.linux-riscv64": "12.17.0",
+        "@pnpm/exe.linux-s390x": "12.17.0",
+        "@pnpm/exe.linux-x64": "12.17.0",
+        "@pnpm/exe.linux-x64-musl": "12.17.0",
+        "@pnpm/exe.win32-arm64": "12.17.0",
+        "@pnpm/exe.win32-x64": "12.17.0"
+      }
+    }
+  }
+}

src/install-pnpm/bootstrap/pnpm-lock.json

@@ -5,13 +5,13 @@
   "packages": {
     "": {
       "dependencies": {
-        "pnpm": "11.0.0-rc.5"
+        "pnpm": "11.28.10"
       }
     },
     "node_modules/pnpm": {
-      "version": "11.0.0-rc.5",
-      "resolved": "https://registry.npmjs.org/pnpm/-/pnpm-11.0.0-rc.5.tgz",
-      "integrity": "sha512-xGn7aqE6meV67JNc17hv9CJwH0YC7KwiMdPcIJEFhuv7a1CntFXQd47CKuVpEtjY6I6fngoDwIdaakF4OpShvQ==",
+      "version": "11.28.10",
+      "resolved": "https://registry.npmjs.org/pnpm/-/pnpm-11.28.10.tgz",
+      "integrity": "sha512-ZyIW8G4VwQm4VHHUnT++0X5vA+rSWN8Iwr9bSlwzMh6/v1lHa86BMl762has4Kx4VI/Qv816UTaek5GCo91Q5A==",
       "license": "MIT",
       "bin": {
         "pn": "bin/pnpm.mjs",

src/install-pnpm/index.ts

@@ -4,13 +4,15 @@ import runSelfInstaller from './run'
 
 export { runSelfInstaller }
 
-export async function install(inputs: Inputs) {
+export async function install(inputs: Inputs): Promise<string | undefined> {
   startGroup('Running self-installer...')
-  const status = await runSelfInstaller(inputs)
+  const { exitCode, binDest } = await runSelfInstaller(inputs)
   endGroup()
-  if (status) {
-    return setFailed(`Something went wrong, self-installer exits with code ${status}`)
+  if (exitCode) {
+    setFailed(`Something went wrong, self-installer exits with code ${exitCode}`)
+    return undefined
   }
+  return binDest
 }
 
 export default install

src/install-pnpm/run.ts

@@ -6,26 +6,50 @@ import path from 'path'
 import util from 'util'
 import { Inputs } from '../inputs'
 import { parse as parseYaml } from 'yaml'
+import { satisfies, subset, validRange } from 'semver'
 import pnpmLock from './bootstrap/pnpm-lock.json'
 import exeLock from './bootstrap/exe-lock.json'
+import nativeLock from './bootstrap/native-lock.json'
 
-const BOOTSTRAP_PNPM_PACKAGE_JSON = JSON.stringify({ private: true, dependencies: { pnpm: pnpmLock.packages['node_modules/pnpm'].version } })
-const BOOTSTRAP_EXE_PACKAGE_JSON = JSON.stringify({ private: true, dependencies: { '@pnpm/exe': exeLock.packages['node_modules/@pnpm/exe'].version } })
+const bootstrapPnpmVersion = pnpmLock.packages['node_modules/pnpm'].version
+const bootstrapExeVersion = exeLock.packages['node_modules/@pnpm/exe'].version
+const bootstrapNativeVersion = nativeLock.packages['node_modules/pnpm'].version
+const BOOTSTRAP_PNPM_PACKAGE_JSON = JSON.stringify({
+  private: true,
+  dependencies: { pnpm: bootstrapPnpmVersion },
+})
+const BOOTSTRAP_EXE_PACKAGE_JSON = JSON.stringify({
+  private: true,
+  dependencies: { '@pnpm/exe': bootstrapExeVersion },
+  allowScripts: { [`@pnpm/exe@${bootstrapExeVersion}`]: true },
+})
+const BOOTSTRAP_NATIVE_PACKAGE_JSON = JSON.stringify({
+  private: true,
+  dependencies: { pnpm: bootstrapNativeVersion },
+  allowScripts: { [`pnpm@${bootstrapNativeVersion}`]: true },
+})
 
-export async function runSelfInstaller(inputs: Inputs): Promise<number> {
+export interface SelfInstallerResult {
+  exitCode: number
+  binDest: string
+}
+
+export async function runSelfInstaller(inputs: Inputs): Promise<SelfInstallerResult> {
   const { version, dest, packageJsonFile } = inputs
-
-  // pnpm v11 requires Node >= 22.13; use standalone (exe) bootstrap which
-  // bundles its own Node.js when the system Node is too old
+  const targetVersion = readTargetVersion({ version, packageJsonFile })
+  const native = targetsPnpm12(targetVersion)
+  let standalone = false
+  if (!native) {
     const systemNode = await getSystemNodeVersion()
-  const standalone = inputs.standalone || systemNode.major < 22 || (systemNode.major === 22 && systemNode.minor < 13)
+    standalone = inputs.standalone || systemNode.major < 22 || (systemNode.major === 22 && systemNode.minor < 13)
+  }
 
   // Install bootstrap pnpm via npm (integrity verified by committed lockfile)
   await rm(dest, { recursive: true, force: true })
   await mkdir(dest, { recursive: true })
 
-  const lockfile = standalone ? exeLock : pnpmLock
-  const packageJson = standalone ? BOOTSTRAP_EXE_PACKAGE_JSON : BOOTSTRAP_PNPM_PACKAGE_JSON
+  const lockfile = native ? nativeLock : standalone ? exeLock : pnpmLock
+  const packageJson = native ? BOOTSTRAP_NATIVE_PACKAGE_JSON : standalone ? BOOTSTRAP_EXE_PACKAGE_JSON : BOOTSTRAP_PNPM_PACKAGE_JSON
   await writeFile(path.join(dest, 'package.json'), packageJson)
   await writeFile(path.join(dest, 'package-lock.json'), JSON.stringify(lockfile))
 
@@ -45,12 +69,9 @@ export async function runSelfInstaller(inputs: Inputs): Promise<number> {
   const npmEnv = { ...process.env, [pathKey]: currentPath ? currentPath + path.delimiter + nodeDir : nodeDir }
   const npmExitCode = await runCommand('npm', ['ci'], { cwd: dest, env: npmEnv })
   if (npmExitCode !== 0) {
-    return npmExitCode
+    return { exitCode: npmExitCode, binDest: path.join(dest, 'node_modules', '.bin') }
   }
 
-  // On Windows with standalone mode, npm's .bin shims can't properly
-  // execute the extensionless @pnpm/exe native binaries. Add the
-  // @pnpm/exe directory directly to PATH so pnpm.exe is found natively.
   const pnpmHome = standalone && process.platform === 'win32'
     ? path.join(dest, 'node_modules', '@pnpm', 'exe')
     : path.join(dest, 'node_modules', '.bin')
@@ -68,36 +89,48 @@ export async function runSelfInstaller(inputs: Inputs): Promise<number> {
     const pnpmBinLink = path.join(dest, 'node_modules', '.bin', 'pnpm')
     if (!existsSync(pnpmBinLink)) {
       await mkdir(path.join(dest, 'node_modules', '.bin'), { recursive: true })
-      const target = standalone
+      const target = native
+        ? path.join('..', 'pnpm', 'pnpm')
+        : standalone
           ? path.join('..', '@pnpm', 'exe', 'pnpm')
           : path.join('..', 'pnpm', 'bin', 'pnpm.mjs')
       await symlink(target, pnpmBinLink)
     }
   }
 
-  const bootstrapPnpm = standalone
+  const bootstrapPnpm = native
+    ? path.join(dest, 'node_modules', 'pnpm', process.platform === 'win32' ? 'pnpm.exe' : 'pnpm')
+    : standalone
       ? path.join(dest, 'node_modules', '@pnpm', 'exe', process.platform === 'win32' ? 'pnpm.exe' : 'pnpm')
       : path.join(dest, 'node_modules', 'pnpm', 'bin', 'pnpm.mjs')
+  const bootstrapVersion = native ? bootstrapNativeVersion : standalone ? bootstrapExeVersion : bootstrapPnpmVersion
 
-  // Determine the target version
-  const targetVersion = readTargetVersion({ version, packageJsonFile })
+  if (targetVersion === bootstrapVersion || (native && satisfies(bootstrapVersion, targetVersion))) {
+    return { exitCode: 0, binDest: pnpmHome }
+  }
 
-  if (targetVersion) {
-    const cmd = standalone ? bootstrapPnpm : process.execPath
-    const args = standalone ? ['self-update', targetVersion] : [bootstrapPnpm, 'self-update', targetVersion]
+  const cmd = native || standalone ? bootstrapPnpm : process.execPath
+  const args = native || standalone ? ['self-update', targetVersion] : [bootstrapPnpm, 'self-update', targetVersion]
   const exitCode = await runCommand(cmd, args, { cwd: dest })
   if (exitCode !== 0) {
-      return exitCode
+    return { exitCode, binDest: pnpmHome }
   }
-  }
-
-  return 0
+  // self-update writes the target pnpm/pnpx into PNPM_HOME/bin, leaving
+  // the bootstrap symlinks in pnpmHome pointing at the old version. Use
+  // PNPM_HOME/bin so consumers of the bin_dest output (e.g.
+  // `${steps.pnpm.outputs.bin_dest}/pnpm`) invoke the requested version.
+  //
+  // When the requested version resolves to the bootstrap version, self-update
+  // is a no-op and PNPM_HOME/bin is not created — fall back to pnpmHome,
+  // whose symlinks already point at the right version.
+  const updatedBinDir = path.join(pnpmHome, 'bin')
+  return { exitCode: 0, binDest: existsSync(updatedBinDir) ? updatedBinDir : pnpmHome }
 }
 
 function readTargetVersion(opts: {
   readonly version?: string | undefined
   readonly packageJsonFile: string
-}): string | undefined {
+}): string {
   const { version, packageJsonFile } = opts
   const { GITHUB_WORKSPACE } = process.env
 
@@ -118,12 +151,15 @@ function readTargetVersion(opts: {
     }
   }
 
+  // packageManager is always exact `pnpm@<version>[+<integrity>]` per spec.
+  // Strip the integrity hash for self-update.
+  const packageManagerVersion =
+    typeof packageManager === 'string' && packageManager.startsWith('pnpm@')
+      ? packageManager.slice('pnpm@'.length).split('+')[0]
+      : undefined
+
   if (version) {
-    if (
-      typeof packageManager === 'string' &&
-      packageManager.startsWith('pnpm@') &&
-      packageManager.replace('pnpm@', '') !== version
-    ) {
+    if (packageManagerVersion && packageManagerVersion !== version) {
       throw new Error(`Multiple versions of pnpm specified:
   - version ${version} in the GitHub Action config with the key "version"
   - version ${packageManager} in the package.json with the key "packageManager"
@@ -133,13 +169,22 @@ Remove one of these versions to avoid version mismatch errors like ERR_PNPM_BAD_
     return version
   }
 
-  // pnpm will automatically download and switch to the right version
-  if (typeof packageManager === 'string' && packageManager.startsWith('pnpm@')) {
-    return undefined
+  // Self-update the bootstrap pnpm to the version pinned in package.json so
+  // PATH-resolved `pnpm` (and the bin_dest output) reflect the target
+  // version. Without this, `pnpm store path` runs as the bootstrap and
+  // reports a different STORE_VERSION than the one the user's actual
+  // install writes to — breaking cache: true and actions/setup-node's
+  // `cache: pnpm` on cold caches (issue #233).
+  //
+  // devEngines.packageManager takes priority over packageManager, matching
+  // pnpm's getWantedPackageManager logic. `pnpm self-update` accepts both
+  // exact versions and semver ranges, so we pass either through directly.
+  if (devEngines?.packageManager?.name === 'pnpm' && devEngines.packageManager.version) {
+    return devEngines.packageManager.version
   }
 
-  if (devEngines?.packageManager?.name === 'pnpm' && devEngines.packageManager.version) {
-    return undefined
+  if (packageManagerVersion) {
+    return packageManagerVersion
   }
 
   if (!GITHUB_WORKSPACE) {
@@ -156,6 +201,12 @@ Please specify it by one of the following ways:
   - in the package.json with the key "devEngines.packageManager"`)
 }
 
+function targetsPnpm12(version: string): boolean {
+  if (version === 'latest-12' || version === 'next-12') return true
+  const range = validRange(version)
+  return range !== null && subset(range, '>=12.0.0 <13.0.0')
+}
+
 function getSystemNodeVersion(): Promise<{ major: number; minor: number }> {
   return new Promise((resolve) => {
     const cp = spawn('node', ['--version'], { stdio: ['pipe', 'pipe', 'pipe'], shell: process.platform === 'win32' })

src/outputs/index.ts

@@ -1,9 +1,7 @@
 import { setOutput } from '@actions/core'
 import { Inputs } from '../inputs'
-import { getBinDest } from '../utils'
 
-export function setOutputs(inputs: Inputs) {
-  const binDest = getBinDest(inputs)
+export function setOutputs(inputs: Inputs, binDest: string) {
   // NOTE: addPath is already called in installPnpm — do not call it again
   // here, as a second addPath would shadow the correct entry on Windows.
   setOutput('dest', inputs.dest)

src/pnpm-install/index.ts

@@ -1,11 +1,8 @@
 import { setFailed, startGroup, endGroup } from '@actions/core'
 import { spawnSync } from 'child_process'
 import { Inputs } from '../inputs'
-import { patchPnpmEnv } from '../utils'
 
 export function runPnpmInstall(inputs: Inputs) {
-  const env = patchPnpmEnv(inputs)
-
   for (const options of inputs.runInstall) {
     const args = ['install']
     if (options.recursive) args.unshift('recursive')
@@ -14,11 +11,16 @@ export function runPnpmInstall(inputs: Inputs) {
     const cmdStr = ['pnpm', ...args].join(' ')
     startGroup(`Running ${cmdStr}...`)
 
+    // spawnSync inherits process.env, which already has $PNPM_HOME/bin and
+    // $PNPM_HOME prepended via addPath() in install-pnpm. Do NOT pass a
+    // hand-patched env that adds node_modules/.bin to the front — on
+    // Windows standalone, .bin/pnpm.cmd is an npm shim pointing at the
+    // BOOTSTRAP pnpm, which would shadow the self-updated one and break
+    // newer-pnpm-only behavior.
     const { error, status } = spawnSync('pnpm', args, {
       stdio: 'inherit',
       cwd: options.cwd,
       shell: true,
-      env,
     })
 
     endGroup()

src/pnpm-store-prune/index.ts

@@ -1,7 +1,6 @@
 import { warning, startGroup, endGroup } from '@actions/core'
 import { spawnSync } from 'child_process'
 import { Inputs } from '../inputs'
-import { patchPnpmEnv } from '../utils'
 
 export function pruneStore(inputs: Inputs) {
   if (inputs.runInstall.length === 0) {
@@ -10,10 +9,11 @@ export function pruneStore(inputs: Inputs) {
   }
 
   startGroup('Running pnpm store prune...')
+  // spawnSync inherits process.env (which has the right PATH from addPath
+  // in install-pnpm). See pnpm-install/index.ts for the rationale.
   const { error, status } = spawnSync('pnpm', ['store', 'prune'], {
     stdio: 'inherit',
     shell: true,
-    env: patchPnpmEnv(inputs),
   })
   endGroup()
 

src/utils/index.ts

@@ -1,10 +0,0 @@
-import path from 'path'
-import process from 'process'
-import { Inputs } from '../inputs'
-
-export const getBinDest = (inputs: Inputs): string => path.join(inputs.dest, 'node_modules', '.bin')
-
-export const patchPnpmEnv = (inputs: Inputs): NodeJS.ProcessEnv => ({
-  ...process.env,
-  PATH: path.join(getBinDest(inputs), 'bin') + path.delimiter + getBinDest(inputs) + path.delimiter + process.env.PATH,
-})

test/cache-save.test.mjs

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, rm, access } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { after, beforeEach, mock, test } from 'node:test'
+
+const directory = await mkdtemp(join(tmpdir(), 'pnpm-cache-save-'))
+after(() => rm(directory, { recursive: true, force: true }))
+let state
+let checkAccess
+const saveCache = mock.fn(async () => 1)
+mock.module('@actions/cache', { namedExports: { saveCache } })
+mock.module('@actions/core', {
+  namedExports: { getState: name => state[name], info: () => {} },
+})
+mock.module('fs/promises', { namedExports: { access: path => checkAccess(path) } })
+const { runSaveCache } = await import('../src/cache-save/run.ts')
+
+beforeEach(() => {
+  state = { cache_restored_key: 'old', cache_primary_key: 'new', cache_path: directory }
+  checkAccess = access
+  saveCache.mock.resetCalls()
+})
+
+test('skips saving a missing directory', async () => {
+  state.cache_path = join(directory, 'missing')
+  await runSaveCache()
+  assert.equal(saveCache.mock.callCount(), 0)
+})
+
+test('saves an existing directory with the primary key', async () => {
+  await runSaveCache()
+  assert.deepEqual(saveCache.mock.calls[0].arguments, [[directory], 'new'])
+})
+
+test('skips saving a primary-key cache hit', async () => {
+  state.cache_restored_key = 'new'
+  await runSaveCache()
+  assert.equal(saveCache.mock.callCount(), 0)
+})
+
+test('propagates unexpected filesystem errors', async () => {
+  const error = Object.assign(new Error('access denied'), { code: 'EACCES' })
+  checkAccess = async () => { throw error }
+  await assert.rejects(runSaveCache(), error)
+  assert.equal(saveCache.mock.callCount(), 0)
+})