fix: self-update accepts ranges; drop exact-semver gate

`pnpm self-update` resolves semver ranges to a specific version, so
`devEngines.packageManager.version: ">=10 <11"` can also go through
the self-update path. That makes readTargetVersion total — it always
returns a string or throws — so the runtime auto-switch fallback (and
the `pnpm_config_pm_on_fail=download` export from #252) is no longer
reachable and gets removed.

Adds a range case to the cache_store_path matrix.

.github/CODEOWNERS

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

.github/workflows/test.yaml

@@ -1,43 +1,73 @@
 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 / 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: 'windows / v9.15.5'
+            os: windows-latest
+            version: '9.15.5'
 
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.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,54 +80,95 @@ 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
 
+      - 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'
+      - name: 'Test: pnpm reports the pinned version'
+        if: ${{ !matrix.expect_pm_on_fail_unset }}
+        env:
+          REQUIRED: ${{ matrix.version }}
         run: |
+          set -e
           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
+          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}"
+              exit 1
+            fi
           fi
         shell: bash
 
-  test_standalone:
-    name: Test with standalone
+      - 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: Standalone mode
 
-    strategy:
-      fail-fast: false
-      matrix:
-        os:
-          - ubuntu-latest
-          - windows-latest
+    runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
@@ -108,210 +179,77 @@ jobs:
           version: 9.15.0
           standalone: true
 
-      - name: 'Test: which'
-        run: which pnpm
-
-      - name: 'Test: version'
+      - name: 'Test: pnpm works'
         run: |
+          set -e
+          which pnpm
           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.0" ]; then
+            echo "Expected 9.15.0, got ${actual}"
             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.
+  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: ${{ matrix.os }}
+    runs-on: ubuntu-latest
 
     strategy:
       fail-fast: false
       matrix:
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
-        version:
-          - '9.15.5'
-          - '10.33.0'
+        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@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
+      - name: Set up package.json
+        run: echo '${{ matrix.manifest }}' > package.json
         shell: bash
 
-  test_bin_dest_output:
-    name: 'Test bin_dest output points to requested version (${{ matrix.version }}, ${{ matrix.os }})'
-    # Regression test for #247: invoking pnpm via the `bin_dest` output returned the
-    # bootstrap version because self-update writes the target to `${bin_dest}/bin/`,
-    # not directly into `${bin_dest}/`.
-
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      fail-fast: false
-      matrix:
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
-        version:
-          - '9.15.5'
-          - '10.33.2'
-
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-
       - id: pnpm
-        name: Run the action
         uses: ./
         with:
-          version: ${{ matrix.version }}
+          cache: true
+          run_install: |
+            - args: [--no-frozen-lockfile]
 
-      - name: 'Test: bin_dest/pnpm reports requested version'
-        # 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: |
-          actual="$("$BIN_DEST/pnpm" --version)"
-          echo "pnpm version via bin_dest: ${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: store path computed by the action exists on disk'
         run: |
           set -e
-          required='${{ matrix.version }}'
-          actual="$(pnpm --version)"
-          echo "pnpm version: ${actual}"
-
-          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}"
-              exit 1
-            fi
+          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
 
-  test_run_install:
-    name: 'Test with run_install (${{ matrix.run_install.name }}, ${{ matrix.os }})'
+  run_install:
+    name: 'run_install (${{ matrix.run_install.name }})'
 
-    runs-on: ${{ matrix.os }}
+    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'
@@ -332,15 +270,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

src/index.ts

@@ -8,16 +8,16 @@ 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')
 
   const binDest = await installPnpm(inputs)
@@ -30,7 +30,8 @@ async function runMain(inputs: 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/run.ts

@@ -84,32 +84,31 @@ export async function runSelfInstaller(inputs: Inputs): Promise<SelfInstallerRes
     ? path.join(dest, 'node_modules', '@pnpm', 'exe', process.platform === 'win32' ? 'pnpm.exe' : 'pnpm')
     : path.join(dest, 'node_modules', 'pnpm', 'bin', 'pnpm.mjs')
 
-  // Determine the target version
+  // Self-update the bootstrap to the requested pnpm version. readTargetVersion
+  // either returns a value or throws, so this always runs.
   const targetVersion = readTargetVersion({ version, packageJsonFile })
-
-  if (targetVersion) {
-    const cmd = standalone ? bootstrapPnpm : process.execPath
-    const args = standalone ? ['self-update', targetVersion] : [bootstrapPnpm, 'self-update', targetVersion]
-    const exitCode = await runCommand(cmd, args, { cwd: dest })
-    if (exitCode !== 0) {
-      return { exitCode, binDest: pnpmHome }
-    }
-    // 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.
-    return { exitCode: 0, binDest: path.join(pnpmHome, 'bin') }
+  const cmd = standalone ? bootstrapPnpm : process.execPath
+  const args = standalone ? ['self-update', targetVersion] : [bootstrapPnpm, 'self-update', targetVersion]
+  const exitCode = await runCommand(cmd, args, { cwd: dest })
+  if (exitCode !== 0) {
+    return { exitCode, binDest: pnpmHome }
   }
-
-  // No explicit target version: rely on the bootstrap pnpm to switch to
-  // the version declared in packageManager/devEngines at runtime.
-  return { exitCode: 0, binDest: pnpmHome }
+  // 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
 
@@ -130,12 +129,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"
@@ -145,13 +147,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) {