feat(npm): add support for staged publishing with pnpm

.github/workflows/reusable-release-npm.md

@@ -54,6 +54,7 @@ jobs:
 | `publish-args` | `string` | `--access public --no-git-checks` | Additional arguments passed to `pnpm publish`. |
 | `generate-changelog` | `boolean` | `true` | Generate a GitHub release changelog with `changelogithub`. |
 | `install-args` | `string` | `""` | Additional arguments passed to `pnpm install`. |
+| `stage` | `boolean` | `false` | Use `pnpm stage publish` for npm's staged publishing workflow instead of direct publishing. |
 
 ## Secrets
 
@@ -81,6 +82,29 @@ The workflow uses `git describe --tags --abbrev=0` to find the latest tag:
 - Tags containing `-` publish with the `next` dist-tag.
 - Other tags publish with the `latest` dist-tag.
 
+## Staged Publishing
+
+When `stage: true` is passed, the workflow uses `pnpm stage publish` instead of `pnpm publish`. This enables npm's staged publishing workflow, which uploads to staging and defers proof-of-presence (2FA) to a later point. This is useful for verifying release artifacts or smoke-testing before approving the final release to the live registry.
+
+Version requirements for staged publishing:
+
+- `pnpm >= 11.3.0` (required for `pnpm stage publish`)
+- `Node.js >= 22.14.0` and `npm CLI >= 11.15.0` (required for npm staged publishing)
+
+To use staged publishing:
+
+```yaml
+jobs:
+  release:
+    permissions:
+      id-token: write
+      contents: write
+    uses: luxass/shared-workflows/.github/workflows/[email protected]
+    with:
+      stage: true
+    secrets: inherit
+```
+
 ## Jobs
 
 | Job | Description |

.github/workflows/reusable-release-npm.yaml

@@ -43,6 +43,11 @@ on:
         type: string
         default: ""
         required: false
+      stage:
+        description: "Use pnpm stage publish instead of pnpm publish"
+        type: boolean
+        default: false
+        required: false
 
 permissions: {}
 
@@ -100,7 +105,17 @@ jobs:
             echo "tag=latest" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: publish to npm (staging)
+        if: ${{ inputs.stage }}
+        env:
+          TAG: ${{ steps.tag.outputs.tag }}
+          NPM_CONFIG_PROVENANCE: "true"
+          PUBLISH_ARGS: ${{ inputs.publish-args }}
+          RECURSIVE: ${{ inputs.recursive }}
+        run: pnpm stage publish ${{ env.RECURSIVE == 'true' && '-r' || '' }} --tag "$TAG" $PUBLISH_ARGS
+
       - name: publish to npm
+        if: ${{ !inputs.stage }}
         env:
           TAG: ${{ steps.tag.outputs.tag }}
           NPM_CONFIG_PROVENANCE: "true"