From 7079c96597c340f41cd1ec3471f7879018d84a0b Mon Sep 17 00:00:00 2001
From: Freeman <nabil@instafork.com>
Date: Fri, 1 May 2026 10:48:29 +0100
Subject: [PATCH 1/2] ci: restore npm upgrade with version pin and add
 skip-bump mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous "remove npm upgrade" commit was wrong — OIDC trusted
publishing requires npm ≥ 11.5.1, and Node 22 ships with npm 10.x.
Restore the upgrade but pin to npm@11 (not @latest) to avoid the
MODULE_NOT_FOUND bug in the bundled npm's self-upgrade path.

Also add a skip_bump workflow input so we can republish a version
whose git tag and GitHub release already exist but whose npm publish
failed. This is needed now to publish the existing v1.1.0 tag
whose publish failed on the previous run.
---
 .github/workflows/release.yml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index efe6c36..9699d34 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -12,6 +12,11 @@ on:
           - patch
           - minor
           - major
+      skip_bump:
+        description: 'Skip version bump (republish current version). When true, the `version` input above is ignored and the current package.json version is published as-is. Useful when a previous run succeeded at tagging/release creation but failed at npm publish.'
+        required: false
+        default: false
+        type: boolean
 
 jobs:
   release:
@@ -29,6 +34,16 @@ jobs:
           node-version: '22'
           cache: npm
 
+      - name: Upgrade npm (required for OIDC trusted publishing)
+        # OIDC trusted publishing requires npm >= 11.5.1. Node 22 ships with
+        # npm 10.x, which falls back to traditional auth and fails with
+        # ENEEDAUTH. We pin to npm@11 (major range) rather than @latest to
+        # avoid a MODULE_NOT_FOUND bug in the bundled npm's self-upgrade
+        # path when targeting @latest. If this ever breaks, a corepack-based
+        # fallback (`corepack prepare npm@latest --activate`) is the next
+        # option to try.
+        run: npm install -g npm@11
+
       # ── Test gate ─────────────────────────────────────────────────────
       # Install, build, and test BEFORE any mutating action (version bump,
       # git push, GitHub release, npm publish). If tests fail, the job
@@ -54,14 +69,17 @@ jobs:
 
       - name: Bump version
         id: bump
+        if: inputs.skip_bump != true
         run: |
           npm version ${{ inputs.version }} -m "chore: release v%s"
           echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
 
       - name: Push changes
+        if: inputs.skip_bump != true
         run: git push --follow-tags
 
       - name: Create GitHub Release
+        if: inputs.skip_bump != true
         uses: softprops/action-gh-release@v2
         with:
           tag_name: v${{ steps.bump.outputs.version }}

From 8e156e7626a08a19021a8a385e247a884618b642 Mon Sep 17 00:00:00 2001
From: Freeman <nabil@instafork.com>
Date: Fri, 1 May 2026 10:48:42 +0100
Subject: [PATCH 2/2] docs: add PR write-up for Fix release workflow OIDC auth
 and add republish mode

---
 .../2026-05-01-fix-release-npm-auth.md        | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-auth.md

diff --git a/documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-auth.md b/documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-auth.md
new file mode 100644
index 0000000..079e84e
--- /dev/null
+++ b/documentation/PULL_REQUESTS/2026-05-01-fix-release-npm-auth.md
@@ -0,0 +1,21 @@
+## Problem
+
+The previous release workflow attempt reached the publish step but failed to authenticate with npm, even though everything upstream had completed successfully — tag created, GitHub release page live. The underlying cause was that the `npm` version shipped with the GitHub Actions runner is too old to use our secure publishing path.
+
+A prior change in this repo had removed the step that upgrades `npm`, assuming it was no longer needed. That turned out to be wrong: the upgrade is necessary for our preferred authentication method to work. Simply putting the old step back doesn't work either, because the bundled `npm` has a bug when upgrading itself to the latest version.
+
+## Solution
+
+Two changes:
+
+1. Restore the `npm` upgrade with a safer target version, avoiding the bundled bug.
+2. Add a "skip version bump" option to the release workflow so we can finish publishing a version whose tag and GitHub release already exist but whose npm publish failed partway through — without re-bumping the version.
+
+## Impact
+
+Once this merges, we can complete the stalled `v1.1.0` release by running the workflow with the skip-bump option enabled. Future releases will use the normal full flow.
+
+# Credits
+
+- Nabs (Architect)
+- JENA (Lead Developer)