[DO NOT MERGE] ci: stage npm releases via OIDC instead of publishing directly

.github/workflows/release.yml

@@ -32,14 +32,17 @@ jobs:
           cache: npm
           registry-url: "https://registry.npmjs.org"
 
-      # OIDC token exchange needs npm >= 11.5.1, which is newer than the npm
-      # bundled with some Node LTS lines.
+      # `npm stage publish` needs npm >= 11.15.0 (and Node >= 22.14.0), which is
+      # newer than the npm bundled with some Node LTS lines.
       - name: Update npm
         run: npm install -g npm@latest
 
       - run: npm ci
 
-      - name: Create Release Pull Request or Publish to npm
+      # `npm run release` stages the version instead of publishing it. A
+      # maintainer approves it with 2FA (`npm stage approve <stage-id>` or the
+      # Staged Packages tab on the npm website) before it goes live.
+      - name: Create Release Pull Request or Stage to npm
         id: changesets
         uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0
         with:
@@ -48,6 +51,7 @@ jobs:
           commit: "chore(release): new release"
           title: "chore(release): new release"
         # No NPM_TOKEN: authentication goes through the npm trusted publisher
-        # configured for this repository and workflow file.
+        # configured for this repository and workflow file. Restrict that
+        # trusted publisher to staging only so a direct publish is rejected.
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package.json

@@ -41,7 +41,7 @@
     "pretest": "npm run lint",
     "test": "npm run test:coverage",
     "prepare": "husky && npm run build",
-    "release": "changeset publish",
+    "release": "node scripts/stage-publish.mjs",
     "changeset": "changeset",
     "version-packages": "changeset version"
   },

scripts/stage-publish.mjs

@@ -0,0 +1,45 @@
+// Replacement for `changeset publish` that uses npm staged publishing.
+//
+// `npm stage publish` uploads the tarball to the npm stage queue through the
+// trusted publisher (OIDC). The version only goes live after a maintainer
+// approves it with 2FA (`npm stage approve <stage-id>` or on npmjs.com).
+//
+// changesets/action detects a release in a single-package repo by looking for a
+// "New tag:" line on stdout. It then pushes the `v<version>` tag and creates the
+// GitHub release, so this script creates the tag locally and prints that line.
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+const { name, version } = JSON.parse(readFileSync("package.json", "utf8"));
+const tag = `v${version}`;
+
+const run = (command, args, options = {}) =>
+  (execFileSync(command, args, { encoding: "utf8", ...options }) ?? "").trim();
+
+const isPublished = () => {
+  try {
+    return run("npm", ["view", `${name}@${version}`, "version"]) === version;
+  } catch {
+    return false;
+  }
+};
+
+// The tag is pushed right after staging, so it also marks a version that is
+// staged and still waiting for approval.
+const isTagged = () =>
+  run("git", ["ls-remote", "--tags", "origin", `refs/tags/${tag}`]) !== "";
+
+const log = (message) => process.stdout.write(`${message}\n`);
+
+if (isPublished()) {
+  log(`${name}@${version} is already published, skipping.`);
+} else if (isTagged()) {
+  log(`${tag} already exists, ${name}@${version} is staged, skipping.`);
+} else {
+  run("npm", ["stage", "publish"], { stdio: "inherit" });
+  run("git", ["tag", tag]);
+
+  log(`Staged ${name}@${version}, approve it with 2FA to publish.`);
+  log(`New tag: ${tag}`);
+}