build(release): add maintainer-driven publishing flow

.changeset/config.json

@@ -3,7 +3,7 @@
   "changelog": "@changesets/cli/changelog",
   "commit": false,
   "linked": [],
-  "access": "restricted",
+  "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "ignore": []

.github/workflows/ci.yml

@@ -5,22 +5,25 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+
 jobs:
   test:
     name: Test
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
         with:
           package_json_path: package.json
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: '22'
           cache: 'pnpm'
@@ -36,4 +39,3 @@ jobs:
 
       - name: Test
         run: pnpm test
-

.nvmrc

@@ -1 +1 @@
-lts/hydrogen
+22

biome.json

@@ -10,6 +10,7 @@
 			"src/**/*.ts",
 			"src/**/*.d.ts",
 			"scripts/**/*.js",
+			"scripts/**/*.mjs",
 			"scripts/**/*.ts"
 		]
 	}

docs/releasing.md

@@ -0,0 +1,74 @@
+# Releasing ndepe
+
+Releases are prepared and published locally. GitHub Actions only validates pull requests and has no publishing credentials or write permissions.
+
+## Feature development
+
+Every pull request with a user-visible change must include one or more changesets:
+
+```bash
+pnpm change
+```
+
+Commit the generated `.changeset/*.md` files with the feature. Changesets accumulate on `main`; merging a feature pull request does not create a version pull request or publish anything.
+
+## Prepare a release
+
+The maintainer starts a short release window and pauses feature merges. From a clean and current `main`, run:
+
+```bash
+pnpm release:prepare
+```
+
+The command verifies Node.js 22, pnpm 10, GitHub CLI authentication, Git state, frozen dependencies, pending changesets, and the release branch. It then consumes every pending changeset, creates `release/vX.Y.Z`, commits the version files, pushes the branch, and opens a Version PR.
+
+Review the version, changelog, deleted changesets, and CI result. The Version PR must contain no source changes and must be merged with **Squash Merge**.
+
+## Publish a release
+
+Keep the release window open. Immediately after the Version PR is merged:
+
+```bash
+git switch main
+git pull --ff-only origin main
+pnpm release
+```
+
+The command requires a local npm login with 2FA and rejects `NPM_TOKEN` and `NODE_AUTH_TOKEN`. It installs the lockfile-pinned dependencies with lifecycle scripts disabled, verifies that `HEAD` is exactly the Version commit, runs lint/build/tests and package smoke tests, then asks you to type the complete version.
+
+After confirmation it publishes the generated tarball, creates and pushes an annotated Tag, and creates the GitHub Release from the matching changelog section. End the release window only after all three commands succeed.
+
+Stable SemVer releases are supported. Prereleases are intentionally not supported in the first version of this flow.
+
+## Recovery
+
+The script never overwrites an npm version or Tag and does not perform automatic rollback. If npm publishing succeeds but a later step fails, do not rerun the complete release command. Inspect the printed version and commit, then complete the missing steps manually:
+
+```bash
+git tag -a vX.Y.Z <release-commit-sha> -m "vX.Y.Z" # Skip if the local Tag exists
+git push origin refs/tags/vX.Y.Z:refs/tags/vX.Y.Z
+
+# Copy the matching CHANGELOG section to /tmp/release-notes.md first.
+gh release create vX.Y.Z --verify-tag --title "vX.Y.Z" \
+  --notes-file /tmp/release-notes.md --latest --repo web-infra-dev/nde
+```
+
+Before running recovery commands, verify npm contains the expected version and that any existing Tag points to the intended release commit. Never move an existing remote Tag automatically.
+
+If the package was published under the wrong dist-tag, restore the stable tag explicitly:
+
+```bash
+npm dist-tag add ndepe@X.Y.Z latest
+```
+
+## Repository setup
+
+Repository administrators must configure these controls outside the repository:
+
+- Require pull requests and the CI check for `main`.
+- Allow and use Squash Merge for Version PRs.
+- Restrict creation of `v*` Tags to release maintainers.
+- Remove the obsolete `NPM_TOKEN` GitHub secret.
+- On npm, require 2FA for publishing and disallow automation tokens.
+
+Historical Tags are not moved or recreated. The local flow starts with the next release.

package.json

@@ -15,19 +15,22 @@
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
   "scripts": {
     "build": "rslib build",
     "build:watch": "rslib build -w",
-    "bump": "changeset version",
     "change": "changeset",
     "prepare": "pnpm run build && husky install",
-    "prepublishOnly": "pnpm run build",
-    "release:github": "node scripts/create-github-release.js",
-    "release:local": "npx zx scripts/release.mjs",
-    "release:force": "pnpm publish --no-git-checks",
+    "prepublishOnly": "node -e \"console.error('Direct publishing is disabled. Use pnpm release.'); process.exit(1)\"",
+    "release:prepare": "node scripts/release-prepare.mjs",
+    "release": "node scripts/release.mjs",
     "reset": "rimraf ./**/node_modules",
-    "test": "pnpm run test:setup && vitest --run",
-    "test:setup": "cd tests/fixtures/project1 && [ -d node_modules ] || pnpm install --frozen-lockfile"
+    "test": "pnpm run test:setup && vitest --run && node --test scripts/*.node-test.mjs",
+    "test:setup": "cd tests/fixtures/project1 && [ -d node_modules ] || pnpm install --frozen-lockfile --ignore-scripts"
   },
   "lint-staged": {
     "*.{js,ts,jsx,tsx}": [
@@ -59,8 +62,7 @@
     "rimraf": "~3.0.2",
     "ts-node": "^10.9.2",
     "typescript": "~5.0.4",
-    "vitest": "^2.0.5",
-    "zx": "^8.5.5"
+    "vitest": "^2.0.5"
   },
   "packageManager": "pnpm@10.0.0",
   "publishConfig": {