From ac4b82f88ab78c6c647104d21a7d607a49de6d90 Mon Sep 17 00:00:00 2001
From: Northword <northword@outlook.com>
Date: Mon, 31 Aug 2026 18:03:17 +0800
Subject: [PATCH 1/9] feat(setup-js): support pnpm/setup for pnpm > 11

Auto-detect the package manager and the declared pnpm version in
setup-js, then pick the toolchain:

- pnpm > 11 (or undeclared pnpm version, which resolves to latest):
  pnpm/setup@v2, which installs pnpm and the Node.js runtime in one
  step (node-version is mapped to its runtime input; lts/* -> lts)
- otherwise (npm/yarn, or pnpm <= 11): the classic setup-node path
  (pnpm/action-setup), unchanged

pnpm/setup only supports pnpm >= 11, and v11 ships no binary for
Intel macOS runners, hence the > 11 boundary. The detected package
manager is passed to setup-node to avoid a second detection pass.
---
 README.md            |  2 +-
 setup-js/action.yml  | 76 ++++++++++++++++++++++++++++++++++++++++----
 setup-js/example.yml |  6 ++++
 3 files changed, 77 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 505998f..d96c374 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ A collection of reusable GitHub Actions workflows and composite actions for Zote
 
 - [x] Setup JavaScript (`setup-js`): checkout, then automatically pick the toolchain
   - [x] `setup-vp`: [Vite+](https://github.com/voidzero-dev/setup-vp) setup (auto-detected when `vite-plus` is in the devDependencies of `package.json`)
-  - [x] `setup-node`: Node.js + package manager setup and dependency install
+  - [x] `setup-node`: Node.js + package manager setup and dependency install. When pnpm > 11 (or an undeclared pnpm version) is detected, `setup-js` uses [pnpm/setup](https://github.com/pnpm/setup) instead, which installs pnpm and the Node.js runtime in one step; pnpm <= 11 keeps the classic `pnpm/action-setup` + `setup-node` path
 
 ### Reusable GitHub Actions workflows
 
diff --git a/setup-js/action.yml b/setup-js/action.yml
index d7eb2b4..d665f9f 100644
--- a/setup-js/action.yml
+++ b/setup-js/action.yml
@@ -25,13 +25,13 @@ inputs:
     required: false
     default: "true"
 
-  # --- setup-node only (ignored when Vite+ is used) ---
+  # --- Node.js setup (ignored when Vite+ is used) ---
   node-version:
-    description: "Version Spec of the version to use. Examples: 12.x, 10.15.1, >=10.15.0. Ignored when Vite+ is used."
+    description: "Version Spec of the Node.js version to use. Examples: 12.x, 10.15.1, >=10.15.0. Ignored when Vite+ is used. When pnpm is set up via pnpm/setup (pnpm > 11 or undeclared), this is passed as its `runtime` input, with `lts/*` translated to `lts`."
     default: "lts/*"
 
   package-manager:
-    description: "Package manager to use. Examples: npm, yarn, pnpm. Leave empty to auto-detect. Ignored when Vite+ is used."
+    description: "Package manager to use. Examples: npm, yarn, pnpm. Leave empty to auto-detect from lock files. Ignored when Vite+ is used. When pnpm is detected (or forced), pnpm > 11 or an undeclared version uses pnpm/setup@v2; pnpm <= 11 uses setup-node (pnpm/action-setup)."
     default: ""
 
   # --- setup-vp only ---
@@ -74,7 +74,63 @@ runs:
         if [[ "$USE_VP" == "true" ]]; then
           echo "Using Vite+ (setup-vp)"
         else
-          echo "Using classic Node.js setup (setup-node)"
+          echo "Using Node.js setup (setup-node or pnpm/setup)"
+        fi
+
+    - name: Detect package manager and pnpm strategy
+      id: detect
+      shell: bash
+      run: |
+        PM="${{ inputs.package-manager }}"
+        if [[ -z "$PM" ]]; then
+          if [[ -f "pnpm-lock.yaml" ]]; then
+            PM="pnpm"
+          elif [[ -f "yarn.lock" ]]; then
+            PM="yarn"
+          elif [[ -f "package-lock.json" ]]; then
+            PM="npm"
+          else
+            echo "No lock file found. Defaulting to pnpm."
+            PM="pnpm"
+          fi
+        fi
+        echo "pm=$PM" >> $GITHUB_OUTPUT
+
+        # pnpm >= 12 (or an undeclared version, which resolves to the latest
+        # pnpm, always >= 12) can use pnpm/setup@v2, which installs pnpm and a
+        # Node.js runtime in one step. pnpm <= 11 keeps the classic
+        # setup-node path (pnpm/action-setup): pnpm/setup only supports
+        # >= 11, and v11 ships no binary for Intel macOS runners.
+        USE_NEW=false
+        if [[ "$PM" == "pnpm" ]]; then
+          PM_VERSION=""
+          if [[ -f package.json ]]; then
+            # Top-level "packageManager": "pnpm@12.1.0[+sha256...]"
+            PM_VERSION=$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' package.json | head -1)
+            # Or devEngines.packageManager.version
+            if [[ -z "$PM_VERSION" ]]; then
+              PM_VERSION=$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*{[^}]*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' package.json | head -1)
+            fi
+          fi
+          if [[ -n "$PM_VERSION" ]]; then
+            # Extract the first number (major): handles "12.1.0", "pnpm@12.1.0",
+            # "12.1.0+sha256...", "^12.0.0", ">=12" and "12.x".
+            MAJOR=$(echo "$PM_VERSION" | sed 's/[^0-9]*\([0-9]*\).*/\1/')
+            if [[ "$MAJOR" =~ ^[0-9]+$ ]] && [[ "$MAJOR" -gt 11 ]]; then
+              USE_NEW=true
+            fi
+          else
+            USE_NEW=true
+          fi
+        fi
+        echo "use_new_pnpm=$USE_NEW" >> $GITHUB_OUTPUT
+
+        # Map node-version to pnpm/setup's runtime spec (node@<version>).
+        NV="${{ inputs.node-version }}"
+        if [[ -z "$NV" || "$NV" == "lts/*" ]]; then
+          echo "node_runtime=node@lts" >> $GITHUB_OUTPUT
+        else
+          echo "node_runtime=node@$NV" >> $GITHUB_OUTPUT
         fi
 
     - name: Setup Vite+ (setup-vp)
@@ -85,11 +141,19 @@ runs:
         run-install: ${{ inputs.auto-install }}
         cache: ${{ inputs.cache }}
 
+    - name: Setup pnpm + Node.js (pnpm/setup)
+      if: ${{ steps.vp.outputs.use_vp != 'true' && steps.detect.outputs.use_new_pnpm == 'true' }}
+      uses: pnpm/setup@v2
+      with:
+        runtime: ${{ steps.detect.outputs.node_runtime }}
+        install: ${{ inputs.auto-install }}
+        cache: ${{ inputs.cache }}
+
     - name: Setup Node.js (setup-node)
-      if: ${{ steps.vp.outputs.use_vp != 'true' }}
+      if: ${{ steps.vp.outputs.use_vp != 'true' && steps.detect.outputs.use_new_pnpm != 'true' }}
       uses: $/setup-node
       with:
         node-version: ${{ inputs.node-version }}
         auto-install: ${{ inputs.auto-install }}
-        package-manager: ${{ inputs.package-manager }}
+        package-manager: ${{ steps.detect.outputs.pm }}
         cache: ${{ inputs.cache }}
diff --git a/setup-js/example.yml b/setup-js/example.yml
index 36a8be5..b72884e 100644
--- a/setup-js/example.yml
+++ b/setup-js/example.yml
@@ -12,6 +12,12 @@ jobs:
         # By default, setup-vp is used when `vite-plus` is found in the
         # devDependencies of package.json. Set `vp: 'true'` or `vp: 'false'`
         # to force a specific setup.
+        #
+        # When pnpm is used, pnpm > 11 (or an undeclared pnpm version) is
+        # set up via pnpm/setup@v2, which also installs the Node.js runtime
+        # (`node-version` is passed through, with `lts/*` translated to
+        # `lts`); pnpm <= 11 keeps the classic setup-node path
+        # (pnpm/action-setup).
         # with:
         #   vp: "true"
         #   vp-version: "0.2.0"

From e1d344f07655d2a9f9c2ec8ab210270e9bd3a587 Mon Sep 17 00:00:00 2001
From: Northword <northword@outlook.com>
Date: Mon, 31 Aug 2026 18:43:02 +0800
Subject: [PATCH 2/9] refactor(setup-node): drop internal package-manager
 detection

setup-node is an internal building block of setup-js, which now always
detects the package manager and passes it in. Remove the duplicated
lockfile detection and make `package-manager` a required input.
---
 README.md             |  4 ++--
 setup-node/action.yml | 33 +++++++--------------------------
 2 files changed, 9 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index d96c374..d697c4a 100644
--- a/README.md
+++ b/README.md
@@ -7,8 +7,8 @@ A collection of reusable GitHub Actions workflows and composite actions for Zote
 ### Composite actions
 
 - [x] Setup JavaScript (`setup-js`): checkout, then automatically pick the toolchain
-  - [x] `setup-vp`: [Vite+](https://github.com/voidzero-dev/setup-vp) setup (auto-detected when `vite-plus` is in the devDependencies of `package.json`)
-  - [x] `setup-node`: Node.js + package manager setup and dependency install. When pnpm > 11 (or an undeclared pnpm version) is detected, `setup-js` uses [pnpm/setup](https://github.com/pnpm/setup) instead, which installs pnpm and the Node.js runtime in one step; pnpm <= 11 keeps the classic `pnpm/action-setup` + `setup-node` path
+  - [x] `setup-vp` (internal): [Vite+](https://github.com/voidzero-dev/setup-vp) setup (auto-detected when `vite-plus` is in the devDependencies of `package.json`)
+  - [x] `setup-node` (internal): classic Node.js + package manager setup and dependency install, fed with the package manager detected by `setup-js`. When pnpm > 11 (or an undeclared pnpm version) is detected, `setup-js` uses [pnpm/setup](https://github.com/pnpm/setup) instead, which installs pnpm and the Node.js runtime in one step; pnpm <= 11 keeps the classic `pnpm/action-setup` + `setup-node` path
 
 ### Reusable GitHub Actions workflows
 
diff --git a/setup-node/action.yml b/setup-node/action.yml
index d2a32c9..2261850 100644
--- a/setup-node/action.yml
+++ b/setup-node/action.yml
@@ -10,9 +10,10 @@ inputs:
     description: Whether to automatically install dependencies.
     default: "true"
 
+  # Internal: the package manager is detected by setup-js and passed in here.
   package-manager:
-    description: "Package manager to use. Examples: npm, yarn, pnpm. Leave empty to auto-detect."
-    default: ""
+    description: "Package manager to use. Examples: npm, yarn, pnpm. Required."
+    required: true
 
   cache:
     description: "Whether to cache dependencies."
@@ -22,40 +23,20 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: Auto detect package manager
-      id: detect
-      shell: bash
-      run: |
-        if [[ -n "${{ inputs.package-manager }}" ]]; then
-          echo "pm=${{ inputs.package-manager }}" >> $GITHUB_OUTPUT
-          exit 0
-        fi
-
-        if [[ -f "pnpm-lock.yaml" ]]; then
-          echo "pm=pnpm" >> $GITHUB_OUTPUT
-        elif [[ -f "yarn.lock" ]]; then
-          echo "pm=yarn" >> $GITHUB_OUTPUT
-        elif [[ -f "package-lock.json" ]]; then
-          echo "pm=npm" >> $GITHUB_OUTPUT
-        else
-          echo "No lock file found. Defaulting to pnpm."
-          echo "pm=pnpm" >> $GITHUB_OUTPUT
-        fi
-
     - name: Install pnpm
-      if: ${{ steps.detect.outputs.pm == 'pnpm' }}
+      if: ${{ inputs.package-manager == 'pnpm' }}
       uses: pnpm/action-setup@v6
 
     - name: Setup node
       uses: actions/setup-node@v7
       with:
         node-version: ${{ inputs.node-version }}
-        cache: ${{ inputs.cache == 'true' && steps.detect.outputs.pm || '' }}
+        cache: ${{ inputs.cache == 'true' && inputs.package-manager || '' }}
         registry-url: "https://registry.npmjs.org"
 
     - name: Install dependencies
       if: ${{ inputs.auto-install == 'true' }}
       shell: bash
       run: |
-        echo "Using package manager: ${{ steps.detect.outputs.pm }}"
-        ${{ steps.detect.outputs.pm }} install
+        echo "Using package manager: ${{ inputs.package-manager }}"
+        ${{ inputs.package-manager }} install

From f2101f5c8a1acaaf9a3cdbaea25c5c7629da8e95 Mon Sep 17 00:00:00 2001
From: Northword <northword@outlook.com>
Date: Mon, 31 Aug 2026 18:48:57 +0800
Subject: [PATCH 3/9] refactor(setup-js): split pnpm strategy into its own step

- package-manager detection and pnpm version/strategy detection are now
  separate steps (detect / pnpm-strategy)
- drop the node_runtime output: the node-version -> pnpm/setup runtime
  mapping is inlined into the pnpm/setup step's `runtime` input
  ('' or lts/* -> node@lts, otherwise node@<version>)
---
 setup-js/action.yml | 24 +++++++++++-------------
 1 file changed, 11 insertions(+), 13 deletions(-)

diff --git a/setup-js/action.yml b/setup-js/action.yml
index d665f9f..90227a0 100644
--- a/setup-js/action.yml
+++ b/setup-js/action.yml
@@ -77,7 +77,7 @@ runs:
           echo "Using Node.js setup (setup-node or pnpm/setup)"
         fi
 
-    - name: Detect package manager and pnpm strategy
+    - name: Detect package manager
       id: detect
       shell: bash
       run: |
@@ -96,13 +96,17 @@ runs:
         fi
         echo "pm=$PM" >> $GITHUB_OUTPUT
 
+    - name: Detect pnpm version and strategy
+      id: pnpm-strategy
+      shell: bash
+      run: |
         # pnpm >= 12 (or an undeclared version, which resolves to the latest
         # pnpm, always >= 12) can use pnpm/setup@v2, which installs pnpm and a
         # Node.js runtime in one step. pnpm <= 11 keeps the classic
         # setup-node path (pnpm/action-setup): pnpm/setup only supports
         # >= 11, and v11 ships no binary for Intel macOS runners.
         USE_NEW=false
-        if [[ "$PM" == "pnpm" ]]; then
+        if [[ "${{ steps.detect.outputs.pm }}" == "pnpm" ]]; then
           PM_VERSION=""
           if [[ -f package.json ]]; then
             # Top-level "packageManager": "pnpm@12.1.0[+sha256...]"
@@ -125,14 +129,6 @@ runs:
         fi
         echo "use_new_pnpm=$USE_NEW" >> $GITHUB_OUTPUT
 
-        # Map node-version to pnpm/setup's runtime spec (node@<version>).
-        NV="${{ inputs.node-version }}"
-        if [[ -z "$NV" || "$NV" == "lts/*" ]]; then
-          echo "node_runtime=node@lts" >> $GITHUB_OUTPUT
-        else
-          echo "node_runtime=node@$NV" >> $GITHUB_OUTPUT
-        fi
-
     - name: Setup Vite+ (setup-vp)
       if: ${{ steps.vp.outputs.use_vp == 'true' }}
       uses: $/setup-vp
@@ -142,15 +138,17 @@ runs:
         cache: ${{ inputs.cache }}
 
     - name: Setup pnpm + Node.js (pnpm/setup)
-      if: ${{ steps.vp.outputs.use_vp != 'true' && steps.detect.outputs.use_new_pnpm == 'true' }}
+      if: ${{ steps.vp.outputs.use_vp != 'true' && steps.pnpm-strategy.outputs.use_new_pnpm == 'true' }}
       uses: pnpm/setup@v2
       with:
-        runtime: ${{ steps.detect.outputs.node_runtime }}
+        # node-version is a setup-node spec (lts/*, 22.x, >=20.0.0); pnpm/setup
+        # expects its own runtime spec (node@<version>), so translate the default.
+        runtime: ${{ (inputs.node-version == '' || inputs.node-version == 'lts/*') && 'node@lts' || format('node@{0}', inputs.node-version) }}
         install: ${{ inputs.auto-install }}
         cache: ${{ inputs.cache }}
 
     - name: Setup Node.js (setup-node)
-      if: ${{ steps.vp.outputs.use_vp != 'true' && steps.detect.outputs.use_new_pnpm != 'true' }}
+      if: ${{ steps.vp.outputs.use_vp != 'true' && steps.pnpm-strategy.outputs.use_new_pnpm != 'true' }}
       uses: $/setup-node
       with:
         node-version: ${{ inputs.node-version }}

From 8fd81b577346d97597e28c0ad93b899e12cb6e5b Mon Sep 17 00:00:00 2001
From: Northword <northword@outlook.com>
Date: Mon, 31 Aug 2026 18:57:58 +0800
Subject: [PATCH 4/9] refactor(setup-js): only run pnpm strategy detection when
 pnpm is used

Gate the pnpm-strategy step on pm == 'pnpm' and drop the now-redundant
inner guard. When the step is skipped (npm/yarn), its output is empty,
which the downstream conditions already handle ('' != 'true' keeps the
classic setup-node path).
---
 setup-js/action.yml | 33 ++++++++++++++++-----------------
 1 file changed, 16 insertions(+), 17 deletions(-)

diff --git a/setup-js/action.yml b/setup-js/action.yml
index 90227a0..03dba3f 100644
--- a/setup-js/action.yml
+++ b/setup-js/action.yml
@@ -98,6 +98,7 @@ runs:
 
     - name: Detect pnpm version and strategy
       id: pnpm-strategy
+      if: ${{ steps.detect.outputs.pm == 'pnpm' }}
       shell: bash
       run: |
         # pnpm >= 12 (or an undeclared version, which resolves to the latest
@@ -106,26 +107,24 @@ runs:
         # setup-node path (pnpm/action-setup): pnpm/setup only supports
         # >= 11, and v11 ships no binary for Intel macOS runners.
         USE_NEW=false
-        if [[ "${{ steps.detect.outputs.pm }}" == "pnpm" ]]; then
-          PM_VERSION=""
-          if [[ -f package.json ]]; then
-            # Top-level "packageManager": "pnpm@12.1.0[+sha256...]"
-            PM_VERSION=$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' package.json | head -1)
-            # Or devEngines.packageManager.version
-            if [[ -z "$PM_VERSION" ]]; then
-              PM_VERSION=$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*{[^}]*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' package.json | head -1)
-            fi
+        PM_VERSION=""
+        if [[ -f package.json ]]; then
+          # Top-level "packageManager": "pnpm@12.1.0[+sha256...]"
+          PM_VERSION=$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' package.json | head -1)
+          # Or devEngines.packageManager.version
+          if [[ -z "$PM_VERSION" ]]; then
+            PM_VERSION=$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*{[^}]*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' package.json | head -1)
           fi
-          if [[ -n "$PM_VERSION" ]]; then
-            # Extract the first number (major): handles "12.1.0", "pnpm@12.1.0",
-            # "12.1.0+sha256...", "^12.0.0", ">=12" and "12.x".
-            MAJOR=$(echo "$PM_VERSION" | sed 's/[^0-9]*\([0-9]*\).*/\1/')
-            if [[ "$MAJOR" =~ ^[0-9]+$ ]] && [[ "$MAJOR" -gt 11 ]]; then
-              USE_NEW=true
-            fi
-          else
+        fi
+        if [[ -n "$PM_VERSION" ]]; then
+          # Extract the first number (major): handles "12.1.0", "pnpm@12.1.0",
+          # "12.1.0+sha256...", "^12.0.0", ">=12" and "12.x".
+          MAJOR=$(echo "$PM_VERSION" | sed 's/[^0-9]*\([0-9]*\).*/\1/')
+          if [[ "$MAJOR" =~ ^[0-9]+$ ]] && [[ "$MAJOR" -gt 11 ]]; then
             USE_NEW=true
           fi
+        else
+          USE_NEW=true
         fi
         echo "use_new_pnpm=$USE_NEW" >> $GITHUB_OUTPUT
 

From 68f07f5d54d04e3a35809ace2cbb22c48946346b Mon Sep 17 00:00:00 2001
From: Northword <northword@outlook.com>
Date: Mon, 31 Aug 2026 19:04:18 +0800
Subject: [PATCH 5/9] refactor(setup-js): inline voidzero-dev/setup-vp, drop
 setup-vp wrapper

setup-vp was a pure passthrough of version/run-install/cache to
voidzero-dev/setup-vp@v1. Call it directly from setup-js like
pnpm/setup, and delete the wrapper. The setup-js input surface
(vp/vp-version/auto-install/cache) is unchanged.
---
 README.md            |  2 +-
 setup-js/action.yml  | 12 ++++++------
 setup-js/example.yml |  6 +++---
 setup-vp/action.yml  | 28 ----------------------------
 4 files changed, 10 insertions(+), 38 deletions(-)
 delete mode 100644 setup-vp/action.yml

diff --git a/README.md b/README.md
index d697c4a..122e553 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ A collection of reusable GitHub Actions workflows and composite actions for Zote
 ### Composite actions
 
 - [x] Setup JavaScript (`setup-js`): checkout, then automatically pick the toolchain
-  - [x] `setup-vp` (internal): [Vite+](https://github.com/voidzero-dev/setup-vp) setup (auto-detected when `vite-plus` is in the devDependencies of `package.json`)
+  - [x] Vite+ ([voidzero-dev/setup-vp](https://github.com/voidzero-dev/setup-vp)) path (internal): auto-detected when `vite-plus` is in the devDependencies of `package.json`; the Vite+ runtime resolves the Node.js version from the project
   - [x] `setup-node` (internal): classic Node.js + package manager setup and dependency install, fed with the package manager detected by `setup-js`. When pnpm > 11 (or an undeclared pnpm version) is detected, `setup-js` uses [pnpm/setup](https://github.com/pnpm/setup) instead, which installs pnpm and the Node.js runtime in one step; pnpm <= 11 keeps the classic `pnpm/action-setup` + `setup-node` path
 
 ### Reusable GitHub Actions workflows
diff --git a/setup-js/action.yml b/setup-js/action.yml
index 03dba3f..475b469 100644
--- a/setup-js/action.yml
+++ b/setup-js/action.yml
@@ -15,7 +15,7 @@ inputs:
     description: Whether to fetch all commits and submodules.
     default: "false"
 
-  # --- shared by setup-node and setup-vp ---
+  # --- shared by setup-node and Vite+ ---
   auto-install:
     description: "Whether to automatically install dependencies."
     default: "true"
@@ -34,9 +34,9 @@ inputs:
     description: "Package manager to use. Examples: npm, yarn, pnpm. Leave empty to auto-detect from lock files. Ignored when Vite+ is used. When pnpm is detected (or forced), pnpm > 11 or an undeclared version uses pnpm/setup@v2; pnpm <= 11 uses setup-node (pnpm/action-setup)."
     default: ""
 
-  # --- setup-vp only ---
+  # --- Vite+ only ---
   vp:
-    description: "Use Vite+ (setup-vp) instead of the classic Node.js setup. 'true'/'false' to force; leave empty to auto-detect from the devDependencies of package.json (vite-plus)."
+    description: "Use Vite+ (voidzero-dev/setup-vp) instead of the classic Node.js setup. 'true'/'false' to force; leave empty to auto-detect from the devDependencies of package.json (vite-plus)."
     required: false
     default: ""
 
@@ -72,7 +72,7 @@ runs:
         fi
         echo "use_vp=$USE_VP" >> $GITHUB_OUTPUT
         if [[ "$USE_VP" == "true" ]]; then
-          echo "Using Vite+ (setup-vp)"
+          echo "Using Vite+ (voidzero-dev/setup-vp)"
         else
           echo "Using Node.js setup (setup-node or pnpm/setup)"
         fi
@@ -128,9 +128,9 @@ runs:
         fi
         echo "use_new_pnpm=$USE_NEW" >> $GITHUB_OUTPUT
 
-    - name: Setup Vite+ (setup-vp)
+    - name: Setup Vite+ (voidzero-dev/setup-vp)
       if: ${{ steps.vp.outputs.use_vp == 'true' }}
-      uses: $/setup-vp
+      uses: voidzero-dev/setup-vp@v1
       with:
         version: ${{ inputs.vp-version }}
         run-install: ${{ inputs.auto-install }}
diff --git a/setup-js/example.yml b/setup-js/example.yml
index b72884e..30b2ceb 100644
--- a/setup-js/example.yml
+++ b/setup-js/example.yml
@@ -9,9 +9,9 @@ jobs:
     steps:
       - name: Setup JS (auto-detect Vite+)
         uses: zotero-plugin-dev/workflows/setup-js@main
-        # By default, setup-vp is used when `vite-plus` is found in the
-        # devDependencies of package.json. Set `vp: 'true'` or `vp: 'false'`
-        # to force a specific setup.
+        # By default, the Vite+ setup (voidzero-dev/setup-vp) is used when
+        # `vite-plus` is found in the devDependencies of package.json. Set
+        # `vp: 'true'` or `vp: 'false'` to force a specific setup.
         #
         # When pnpm is used, pnpm > 11 (or an undeclared pnpm version) is
         # set up via pnpm/setup@v2, which also installs the Node.js runtime
diff --git a/setup-vp/action.yml b/setup-vp/action.yml
deleted file mode 100644
index 739eb28..0000000
--- a/setup-vp/action.yml
+++ /dev/null
@@ -1,28 +0,0 @@
-name: Setup Vite+ (vp)
-description: Setup Vite+ (vp) via voidzero-dev/setup-vp
-
-inputs:
-  version:
-    description: "Version of Vite+ to install. Leave empty to auto-detect from the project."
-    required: false
-    default: ""
-
-  run-install:
-    description: "Whether to run `vp install` after setup."
-    required: false
-    default: "true"
-
-  cache:
-    description: "Whether to cache project dependencies."
-    required: false
-    default: "true"
-
-runs:
-  using: composite
-  steps:
-    - name: Setup vp
-      uses: voidzero-dev/setup-vp@v1
-      with:
-        version: ${{ inputs.version }}
-        run-install: ${{ inputs.run-install }}
-        cache: ${{ inputs.cache }}

From 1a617a28adc1df5b401445a07ba6216d83c5d7c0 Mon Sep 17 00:00:00 2001
From: Northword <northword@outlook.com>
Date: Mon, 31 Aug 2026 19:08:05 +0800
Subject: [PATCH 6/9] docs(setup-js): level pnpm/setup path with setup-node in
 README

and add Checkout / Detect / Setup section separators to setup-js steps.
---
 README.md           | 3 ++-
 setup-js/action.yml | 3 +++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 122e553..8e07450 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,8 @@ A collection of reusable GitHub Actions workflows and composite actions for Zote
 
 - [x] Setup JavaScript (`setup-js`): checkout, then automatically pick the toolchain
   - [x] Vite+ ([voidzero-dev/setup-vp](https://github.com/voidzero-dev/setup-vp)) path (internal): auto-detected when `vite-plus` is in the devDependencies of `package.json`; the Vite+ runtime resolves the Node.js version from the project
-  - [x] `setup-node` (internal): classic Node.js + package manager setup and dependency install, fed with the package manager detected by `setup-js`. When pnpm > 11 (or an undeclared pnpm version) is detected, `setup-js` uses [pnpm/setup](https://github.com/pnpm/setup) instead, which installs pnpm and the Node.js runtime in one step; pnpm <= 11 keeps the classic `pnpm/action-setup` + `setup-node` path
+  - [x] pnpm/setup path (internal): for pnpm > 11 or an undeclared pnpm version — [pnpm/setup](https://github.com/pnpm/setup) installs pnpm and the Node.js runtime in one step
+  - [x] `setup-node` (internal): classic Node.js + package manager setup and dependency install (npm/yarn, or pnpm <= 11 via `pnpm/action-setup`), fed with the package manager detected by `setup-js`
 
 ### Reusable GitHub Actions workflows
 
diff --git a/setup-js/action.yml b/setup-js/action.yml
index 475b469..fd9c12d 100644
--- a/setup-js/action.yml
+++ b/setup-js/action.yml
@@ -48,6 +48,7 @@ inputs:
 runs:
   using: composite
   steps:
+    # --- Checkout ---
     - name: Checkout
       uses: actions/checkout@v7
       with:
@@ -56,6 +57,7 @@ runs:
         fetch-depth: "${{ inputs.fetch-all == 'true' && '0' || '1' }}"
         submodules: "${{ inputs.fetch-all == 'true' && 'recursive' || false }}"
 
+    # --- Detect toolchain and package manager ---
     - name: Detect Vite+ usage
       id: vp
       shell: bash
@@ -128,6 +130,7 @@ runs:
         fi
         echo "use_new_pnpm=$USE_NEW" >> $GITHUB_OUTPUT
 
+    # --- Setup ---
     - name: Setup Vite+ (voidzero-dev/setup-vp)
       if: ${{ steps.vp.outputs.use_vp == 'true' }}
       uses: voidzero-dev/setup-vp@v1

From c1dcdc4a45e2c1ed0a3e44616c95847e73a2b397 Mon Sep 17 00:00:00 2001
From: Northword <northword@outlook.com>
Date: Mon, 31 Aug 2026 19:15:07 +0800
Subject: [PATCH 7/9] refactor(setup-js): semantic detect step ids and gate
 them on Vite+ usage

- rename detect step ids: vp -> detect-vp, detect -> detect-pm,
  pnpm-strategy -> detect-pnpm
- skip package-manager and pnpm strategy detection when Vite+ is used
  (detect-pm gated on use_vp != 'true', detect-pnpm additionally on
  pm == 'pnpm'); all downstream references updated
---
 setup-js/action.yml | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/setup-js/action.yml b/setup-js/action.yml
index fd9c12d..61a3df3 100644
--- a/setup-js/action.yml
+++ b/setup-js/action.yml
@@ -59,7 +59,7 @@ runs:
 
     # --- Detect toolchain and package manager ---
     - name: Detect Vite+ usage
-      id: vp
+      id: detect-vp
       shell: bash
       run: |
         USE_VP="${{ inputs.vp }}"
@@ -80,7 +80,8 @@ runs:
         fi
 
     - name: Detect package manager
-      id: detect
+      id: detect-pm
+      if: ${{ steps.detect-vp.outputs.use_vp != 'true' }}
       shell: bash
       run: |
         PM="${{ inputs.package-manager }}"
@@ -99,8 +100,8 @@ runs:
         echo "pm=$PM" >> $GITHUB_OUTPUT
 
     - name: Detect pnpm version and strategy
-      id: pnpm-strategy
-      if: ${{ steps.detect.outputs.pm == 'pnpm' }}
+      id: detect-pnpm
+      if: ${{ steps.detect-vp.outputs.use_vp != 'true' && steps.detect-pm.outputs.pm == 'pnpm' }}
       shell: bash
       run: |
         # pnpm >= 12 (or an undeclared version, which resolves to the latest
@@ -132,7 +133,7 @@ runs:
 
     # --- Setup ---
     - name: Setup Vite+ (voidzero-dev/setup-vp)
-      if: ${{ steps.vp.outputs.use_vp == 'true' }}
+      if: ${{ steps.detect-vp.outputs.use_vp == 'true' }}
       uses: voidzero-dev/setup-vp@v1
       with:
         version: ${{ inputs.vp-version }}
@@ -140,7 +141,7 @@ runs:
         cache: ${{ inputs.cache }}
 
     - name: Setup pnpm + Node.js (pnpm/setup)
-      if: ${{ steps.vp.outputs.use_vp != 'true' && steps.pnpm-strategy.outputs.use_new_pnpm == 'true' }}
+      if: ${{ steps.detect-vp.outputs.use_vp != 'true' && steps.detect-pnpm.outputs.use_new_pnpm == 'true' }}
       uses: pnpm/setup@v2
       with:
         # node-version is a setup-node spec (lts/*, 22.x, >=20.0.0); pnpm/setup
@@ -150,10 +151,10 @@ runs:
         cache: ${{ inputs.cache }}
 
     - name: Setup Node.js (setup-node)
-      if: ${{ steps.vp.outputs.use_vp != 'true' && steps.pnpm-strategy.outputs.use_new_pnpm != 'true' }}
+      if: ${{ steps.detect-vp.outputs.use_vp != 'true' && steps.detect-pnpm.outputs.use_new_pnpm != 'true' }}
       uses: $/setup-node
       with:
         node-version: ${{ inputs.node-version }}
         auto-install: ${{ inputs.auto-install }}
-        package-manager: ${{ steps.detect.outputs.pm }}
+        package-manager: ${{ steps.detect-pm.outputs.pm }}
         cache: ${{ inputs.cache }}

From 7281812f164731f577c889817fa3cc362e0e7633 Mon Sep 17 00:00:00 2001
From: Northword <northword@outlook.com>
Date: Mon, 31 Aug 2026 19:20:17 +0800
Subject: [PATCH 8/9] feat(setup-js): log detection results in key steps

Each detect step now logs its own outcome (Vite+ usage, package
manager, detected pnpm version and strategy). Drop the old log lines
that announced subsequent steps in advance.
---
 setup-js/action.yml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/setup-js/action.yml b/setup-js/action.yml
index 61a3df3..3726cfa 100644
--- a/setup-js/action.yml
+++ b/setup-js/action.yml
@@ -73,11 +73,7 @@ runs:
           fi
         fi
         echo "use_vp=$USE_VP" >> $GITHUB_OUTPUT
-        if [[ "$USE_VP" == "true" ]]; then
-          echo "Using Vite+ (voidzero-dev/setup-vp)"
-        else
-          echo "Using Node.js setup (setup-node or pnpm/setup)"
-        fi
+        echo "Vite+ usage: $USE_VP"
 
     - name: Detect package manager
       id: detect-pm
@@ -98,6 +94,7 @@ runs:
           fi
         fi
         echo "pm=$PM" >> $GITHUB_OUTPUT
+        echo "Package manager: $PM"
 
     - name: Detect pnpm version and strategy
       id: detect-pnpm
@@ -123,13 +120,16 @@ runs:
           # Extract the first number (major): handles "12.1.0", "pnpm@12.1.0",
           # "12.1.0+sha256...", "^12.0.0", ">=12" and "12.x".
           MAJOR=$(echo "$PM_VERSION" | sed 's/[^0-9]*\([0-9]*\).*/\1/')
+          echo "Detected pnpm version: $PM_VERSION (major: $MAJOR)"
           if [[ "$MAJOR" =~ ^[0-9]+$ ]] && [[ "$MAJOR" -gt 11 ]]; then
             USE_NEW=true
           fi
         else
+          echo "No pnpm version declared in package.json"
           USE_NEW=true
         fi
         echo "use_new_pnpm=$USE_NEW" >> $GITHUB_OUTPUT
+        echo "pnpm strategy: use_new_pnpm=$USE_NEW"
 
     # --- Setup ---
     - name: Setup Vite+ (voidzero-dev/setup-vp)

From 07989a39d793fee7004f1eacae0bba8b6a316621 Mon Sep 17 00:00:00 2001
From: Northword <northword@outlook.com>
Date: Mon, 31 Aug 2026 19:24:12 +0800
Subject: [PATCH 9/9] docs(readme): simplify setup-js toolchain bullets

---
 README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 8e07450..a5cb48d 100644
--- a/README.md
+++ b/README.md
@@ -6,10 +6,10 @@ A collection of reusable GitHub Actions workflows and composite actions for Zote
 
 ### Composite actions
 
-- [x] Setup JavaScript (`setup-js`): checkout, then automatically pick the toolchain
-  - [x] Vite+ ([voidzero-dev/setup-vp](https://github.com/voidzero-dev/setup-vp)) path (internal): auto-detected when `vite-plus` is in the devDependencies of `package.json`; the Vite+ runtime resolves the Node.js version from the project
-  - [x] pnpm/setup path (internal): for pnpm > 11 or an undeclared pnpm version — [pnpm/setup](https://github.com/pnpm/setup) installs pnpm and the Node.js runtime in one step
-  - [x] `setup-node` (internal): classic Node.js + package manager setup and dependency install (npm/yarn, or pnpm <= 11 via `pnpm/action-setup`), fed with the package manager detected by `setup-js`
+- [x] Setup JavaScript (`setup-js`): checkout, then auto-pick a toolchain
+  - [x] Vite+ ([voidzero-dev/setup-vp](https://github.com/voidzero-dev/setup-vp)) when `vite-plus` is a devDependency
+  - [x] [pnpm/setup](https://github.com/pnpm/setup) when pnpm > 11 or version undeclared
+  - [x] `setup-node` (internal) otherwise (npm / yarn / pnpm ≤ 11)
 
 ### Reusable GitHub Actions workflows