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/workflows/pr-check.yaml

@@ -13,14 +13,21 @@ 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: 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

@@ -51,7 +51,7 @@ jobs:
             version: '12.3.4'
 
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - id: pnpm
         name: Run the action
@@ -134,7 +134,7 @@ jobs:
             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
@@ -183,7 +183,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -234,7 +234,7 @@ jobs:
     env:
       REQUIRED: ${{ matrix.version }}
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -298,7 +298,7 @@ jobs:
     name: 'Standalone Windows self-update (PATH regression)'
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - 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
@@ -356,7 +356,7 @@ jobs:
             manifest: '{"devEngines":{"packageManager":{"name":"pnpm","version":">=10 <11"}},"dependencies":{"is-odd":"3.0.1"}}'
 
     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
@@ -400,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: ./

README.md

@@ -64,7 +64,7 @@ Input and output changes:
 
 Version of pnpm to install.
 
-**Optional** when there is a [`packageManager` or `devEngines.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`.
 
@@ -157,6 +157,8 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      - uses: actions/checkout@v6
+
       - uses: pnpm/action-setup@v6
 ```
 

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",

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/install-pnpm/bootstrap/exe-lock.json

@@ -5,13 +5,13 @@
   "packages": {
     "": {
       "dependencies": {
-        "@pnpm/exe": "11.25.0"
+        "@pnpm/exe": "11.28.10"
       }
     },
     "node_modules/@pnpm/exe": {
-      "version": "11.25.0",
-      "resolved": "https://registry.npmjs.org/@pnpm/exe/-/exe-11.25.0.tgz",
-      "integrity": "sha512-X19R2uC+VAJ4UJQE9c/PCdOXbDaWnZtad7WUrTHBFQuMVaK9MAHbyO/WgahQCuRtTmJkLbxcWKKCk+JeTYFm/g==",
+      "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": {
@@ -28,19 +28,18 @@
         "url": "https://opencollective.com/pnpm"
       },
       "optionalDependencies": {
-        "@pnpm/linux-arm64": "11.25.0",
-        "@pnpm/linux-x64": "11.25.0",
-        "@pnpm/linuxstatic-arm64": "11.25.0",
-        "@pnpm/linuxstatic-x64": "11.25.0",
-        "@pnpm/macos-arm64": "11.25.0",
-        "@pnpm/win-arm64": "11.25.0",
-        "@pnpm/win-x64": "11.25.0"
+        "@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.25.0",
-      "resolved": "https://registry.npmjs.org/@pnpm/linux-arm64/-/linux-arm64-11.25.0.tgz",
-      "integrity": "sha512-ra8akqhzsbcOhKSJ9fFV8H+Oc9uGQAcp/XmIBEdT+8hPPoZCit3+RNCHmg8bLoNvpSLtRvZE0WFCMj7WyzxeBA==",
+      "version": "11.28.10",
+      "resolved": "https://registry.npmjs.org/@pnpm/linux-arm64/-/linux-arm64-11.28.10.tgz",
+      "integrity": "sha512-gtNgBYw2s0MLOU980IlqFqvc90iL9y7W6VIRQB8wydgbgeoIU1G0qUOWBRIKB57xDgVuFp7gnTWdwQ2lF2sU1Q==",
       "cpu": [
         "arm64"
       ],
@@ -54,9 +53,9 @@
       }
     },
     "node_modules/@pnpm/linux-x64": {
-      "version": "11.25.0",
-      "resolved": "https://registry.npmjs.org/@pnpm/linux-x64/-/linux-x64-11.25.0.tgz",
-      "integrity": "sha512-pQl/L10diKQCbF73viRrtVU8qVWMTudUCSG1uZ+EWBNKtU9Sbxe6Q378diXDb1uTwSgUVMQoypxlC1MTzh7qvQ==",
+      "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"
       ],
@@ -69,29 +68,10 @@
         "url": "https://opencollective.com/pnpm"
       }
     },
-    "node_modules/@pnpm/linuxstatic-arm64": {
-      "version": "11.25.0",
-      "resolved": "https://registry.npmjs.org/@pnpm/linuxstatic-arm64/-/linuxstatic-arm64-11.25.0.tgz",
-      "integrity": "sha512-cYcrbB/xN1N6/5VUlFuHblb1gNyJgZv1CF5Pk1T0sHJxQMY4DFJV3OqHVAgahxyUfSTaQcVLvH1H2JFvd/+sgw==",
-      "cpu": [
-        "arm64"
-      ],
-      "libc": [
-        "musl"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "funding": {
-        "url": "https://opencollective.com/pnpm"
-      }
-    },
     "node_modules/@pnpm/linuxstatic-x64": {
-      "version": "11.25.0",
-      "resolved": "https://registry.npmjs.org/@pnpm/linuxstatic-x64/-/linuxstatic-x64-11.25.0.tgz",
-      "integrity": "sha512-HXDtaeQod16DDMUUcVLIMxvEc1jKn7IYsNPwbwAPs/Je/d3umRPJi3Ejjdn6e9qpXN6Oon+yvSsJr7B9oDt6KA==",
+      "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"
       ],
@@ -108,9 +88,9 @@
       }
     },
     "node_modules/@pnpm/macos-arm64": {
-      "version": "11.25.0",
-      "resolved": "https://registry.npmjs.org/@pnpm/macos-arm64/-/macos-arm64-11.25.0.tgz",
-      "integrity": "sha512-m/eAgEqKhiSexGxWPHNXNnSRI0hudymg6K7LbrU2EoDs9IgJ28OKEz9mGxMzhkYBweEquR4k5teMNes/aToy9w==",
+      "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"
       ],
@@ -124,9 +104,9 @@
       }
     },
     "node_modules/@pnpm/win-arm64": {
-      "version": "11.25.0",
-      "resolved": "https://registry.npmjs.org/@pnpm/win-arm64/-/win-arm64-11.25.0.tgz",
-      "integrity": "sha512-oAeECbtZ+eJziaBmPUkwJM8Dx7KVQ5FO367AXTjD2HGfB5ob1Bcu5hoUF5RBTgDBiP9fRQ1u13uAEpqar/6NLA==",
+      "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"
       ],
@@ -140,9 +120,9 @@
       }
     },
     "node_modules/@pnpm/win-x64": {
-      "version": "11.25.0",
-      "resolved": "https://registry.npmjs.org/@pnpm/win-x64/-/win-x64-11.25.0.tgz",
-      "integrity": "sha512-8/n+wCc0a8TRYTMFqti93Vh0cscdJ25xfMyYSDdXrLUh2ccxSFuS+SE7cNPjd/nOXoFAJvdW0kwfbyRPLa16/w==",
+      "version": "11.28.10",
+      "resolved": "https://registry.npmjs.org/@pnpm/win-x64/-/win-x64-11.28.10.tgz",
+      "integrity": "sha512-1Do1wLHqiLVQac53DqRtqz0h5UCetoI1oaUZJ62L2wDW4sfe/MBs427rwyaiGZzYLps8glsD1aZXT5uAv1zx8A==",
       "cpu": [
         "x64"
       ],

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

@@ -5,13 +5,13 @@
   "packages": {
     "": {
       "dependencies": {
-        "pnpm": "11.25.0"
+        "pnpm": "11.28.10"
       }
     },
     "node_modules/pnpm": {
-      "version": "11.25.0",
-      "resolved": "https://registry.npmjs.org/pnpm/-/pnpm-11.25.0.tgz",
-      "integrity": "sha512-XN6SW08HX3Jetx+64YpC/+eEUkeJ8ZthxzHLhyHsKKruFg4BqNWvT+2ypCzb8wDv4j2zVrDUoXtNY+EfirfJVg==",
+      "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",

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)
+})