@sonnechasser/ntrp 1.8.1 → 2.0.1

package/README.md

@@ -145,6 +145,69 @@ Checkout URL overrides (optional):
 - `NTRP_CHECKOUT_URL` — signup / first-run
 - `NTRP_UPGRADE_URL` — Pro upgrade (`/upgrade`)
 
+## Release Process
+
+How a new version of `@sonnechasser/ntrp` reaches npm today. This is a reference for release review — it does not change how releases work.
+
+### What triggers a release
+
+A maintainer (or their assistant, acting on the maintainer's explicit version approval) runs `node scripts/release-ntrp.mjs X.Y.Z`. That script:
+
+1. Bumps `package.json` / `package-lock.json` to `X.Y.Z`.
+2. Commits `Release X.Y.Z` on `main` and pushes it.
+3. Creates and pushes the git tag `vX.Y.Z`.
+4. Waits for GitHub Actions and reports the result.
+
+Pushing that `v*` tag is the trigger. The script never runs `npm publish` itself.
+
+### What must be true first
+
+- `main` is green and the release commit is on `main` — a tag publishes with the workflow file **as of the tagged commit**, so any workflow fix has to land on `main` before the tag is cut.
+- The version does not already exist on npm. The script stops rather than republish.
+- `X.Y.Z` is higher than the current `package.json` version (unless the tag already exists and only the publish needs retrying).
+- The working tree is clean.
+
+The exact version number is Dan's call. Naming the version is the approval to ship; nothing publishes without it.
+
+### What GitHub Actions does automatically
+
+`.github/workflows/publish-npm.yml` runs on any pushed `v*` tag (and can be re-dispatched manually for a tag that was pushed but never published, without moving the tag). It:
+
+- Checks out the tagged commit.
+- Uses **Node 22** — pinned because DuckDB's native binding has no Node 24 prebuild.
+- Upgrades the npm CLI to `>= 11.5.1`, which trusted publishing requires.
+- Runs `npm ci`, confirms the DuckDB binding loads, and builds.
+- Runs the pre-publish checks `npm run test:publish-pack` (tarball contents) and `npm run test:publish-workflow` (workflow contract).
+- Publishes with `npm publish --access public` using **npm trusted publishing over OIDC**. There is no `NPM_TOKEN` secret in this repo, and none should ever be added.
+
+CI is the DuckDB test gate; the publish job does not repeat the full smoke suite.
+
+### Publishing never happens outside GitHub Actions
+
+`npm publish` must never be run from Slack, Cursor, Devin, any agent shell, or a laptop. The only path to npm is the tag-triggered GitHub Actions workflow, after Dan has approved the exact version.
+
+### One-time npm Trusted Publisher setup
+
+This flow depends on one piece of configuration outside the repo. On [npmjs.com](https://www.npmjs.com) → `@sonnechasser/ntrp` → **Settings** → **Trusted Publisher** → **GitHub Actions**:
+
+| Field | Value |
+|---|---|
+| Organization or user | `sonnechasser` |
+| Repository | `ntrp-cli-v2` |
+| Workflow filename | `publish-npm.yml` (filename only, not the full path) |
+| Allowed actions | `npm publish` |
+
+The workflow must also exist on the default branch. These are configuration identifiers, not secrets.
+
+### If a release fails
+
+Do not create a second tag. Check whether the tag was pushed and whether npm has the version, then look at the two most likely causes:
+
+- **DuckDB / Node version mismatch** — the publish run fails installing or loading `duckdb`. The tagged commit is running an old workflow that used Node 24. Get the Node 22 workflow onto `main`, then ship the next version.
+- **Missing or misconfigured npm Trusted Publisher** — the publish step fails with a 404 or an authentication error. Re-check the four Trusted Publisher values above; the workflow filename in particular must match `publish-npm.yml` exactly.
+
+If a tag exists but npm does not have that version, either re-dispatch the workflow for that tag from `main` (`gh workflow run publish-npm.yml --ref main -f ref=vX.Y.Z`) or ship the next version so the tagged commit includes the current workflow.
+
 ## Links
 
 - **Website:** [ntrp.sonnechasser.com](https://ntrp.sonnechasser.com)