feat: add approval-gated npm releases [policy]

Change-Id: Iae0db1a40fac3bbdaa4d1dfc2e0c41b0d05c4dba

Author: heimanba

.changeset/pre.json

@@ -1,5 +1,5 @@
 {
-	"mode": "pre",
+	"mode": "exit",
 	"tag": "beta",
 	"initialVersions": {
 		"@openagentpack/server": "0.0.1",

.github/workflows/prepare-beta.yml

@@ -0,0 +1,81 @@
+name: Prepare Beta Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Stable SemVer series, for example 0.1.0
+        required: true
+        type: string
+
+concurrency:
+  group: prepare-beta-${{ inputs.version }}
+  cancel-in-progress: false
+
+jobs:
+  prepare:
+    if: github.ref_name == 'main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: "1.3.5"
+
+      - name: Validate requested version
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::version must be a stable SemVer such as 0.1.0"
+            exit 1
+          fi
+
+      - name: Prepare isolated beta branch
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          branch="release/${VERSION}-beta"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git fetch origin main
+          if git ls-remote --exit-code --heads origin "${branch}" >/dev/null 2>&1; then
+            git fetch origin "${branch}"
+            git checkout --branch "${branch}" --track "origin/${branch}"
+            git merge --no-edit origin/main
+          else
+            git checkout --branch "${branch}" origin/main
+            bunx changeset pre enter beta
+          fi
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Calculate next beta version
+        run: bun run release:version
+
+      - name: Validate calculated beta version
+        id: release
+        run: >-
+          bun run scripts/release/channel.ts validate
+          --channel beta
+          --ref "release/${{ inputs.version }}-beta"
+          --expected "${{ inputs.version }}"
+          --output "$GITHUB_OUTPUT"
+
+      - name: Commit and push beta branch
+        env:
+          VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          if git diff --quiet && git diff --cached --quiet; then
+            echo "::error::No unreleased changesets are available for the next beta."
+            exit 1
+          fi
+          git add --all
+          git commit --message "chore: prepare ${VERSION}"
+          git push origin HEAD

.github/workflows/release-pr.yml

@@ -0,0 +1,36 @@
+name: Release PR
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: release-pr
+  cancel-in-progress: false
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: "1.3.5"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Create or update stable Release PR
+        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0
+        with:
+          version: bun run release:version
+          commit: "chore: release packages"
+          title: "chore: release packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -1,27 +1,34 @@
-name: Release
+name: Publish npm
 
 on:
   workflow_dispatch:
-  push:
-    branches: [main]
+    inputs:
+      channel:
+        description: npm channel to publish
+        required: true
+        type: choice
+        options:
+          - beta
+          - stable
+      confirm:
+        description: Type PUBLISH to confirm
+        required: true
+        type: string
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
   # Publishing three packages is not atomic. Never cancel a run after the first
-  # package may already have reached npm; the publish script is also idempotent
-  # so a failed run can safely be retried.
+  # package may already have reached npm; exact versions are safe to retry.
+  group: npm-publish
   cancel-in-progress: false
 
 jobs:
-  release:
-    # Missing repository variables resolve to an empty string, so a newly
-    # created repository cannot publish until maintainers explicitly opt in.
-    if: vars.NPM_RELEASE_ENABLED == 'true'
+  publish:
+    if: vars.NPM_RELEASE_ENABLED == 'true' && inputs.confirm == 'PUBLISH'
     runs-on: ubuntu-latest
+    environment: npm-release
     permissions:
       contents: write
       id-token: write
-      pull-requests: write
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
         with:
@@ -43,22 +50,48 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Validate channel, branch, and package versions
+        id: release
+        run: >-
+          bun run scripts/release/channel.ts validate
+          --channel "${{ inputs.channel }}"
+          --ref "${{ github.ref_name }}"
+          --output "$GITHUB_OUTPUT"
+
       - name: Verify release
-        env:
-          BASE: ${{ github.event.before }}
         run: bun run verify:release
 
-      - name: Create Release PR or Publish
-        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0
-        with:
-          version: bun run release:version
-          publish: bun run release:publish
-          commit: "chore: release packages"
-          title: "chore: release packages"
+      - name: Publish packages with npm Trusted Publishing
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Bootstrap only: set this secret for the first publication, then remove
-          # and revoke it after npm Trusted Publishers are configured. With the
-          # secret absent, npm authenticates through OIDC trusted publishing.
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           NPM_CONFIG_PROVENANCE: "true"
+        run: bun run release:publish
+
+      - name: Create immutable Git tag
+        env:
+          VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          tag="v${VERSION}"
+          if git rev-parse --verify --quiet "refs/tags/${tag}"; then
+            test "$(git rev-list -n 1 "${tag}")" = "$GITHUB_SHA" || {
+              echo "::error::${tag} already points to another commit"
+              exit 1
+            }
+          else
+            git tag --annotate "${tag}" --message "${tag}"
+            git push origin "${tag}"
+          fi
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.release.outputs.version }}
+          CHANNEL: ${{ steps.release.outputs.channel }}
+        run: |
+          tag="v${VERSION}"
+          if gh release view "${tag}" >/dev/null 2>&1; then
+            echo "GitHub Release ${tag} already exists; nothing to do."
+          elif test "${CHANNEL}" = beta; then
+            gh release create "${tag}" --verify-tag --generate-notes --prerelease --title "${tag}"
+          else
+            gh release create "${tag}" --verify-tag --generate-notes --title "${tag}"
+          fi

CONTRIBUTING.md

@@ -8,7 +8,7 @@ Thanks for your interest in improving OpenAgentPack. By participating you agree
 |-------|-----|
 | Dev setup, verification, package boundaries | [docs/contributing/development.md](./docs/contributing/development.md) |
 | Adding a new provider | [docs/contributing/provider-development.md](./docs/contributing/provider-development.md) |
-| npm release workflow | [docs/contributing/release.md](./docs/contributing/release.md) |
+| npm release workflow | [English](./docs/contributing/release.md) · [简体中文](./docs/contributing/release.zh-CN.md) |
 | Architecture and how it works | [docs/architecture/how-it-works.md](./docs/architecture/how-it-works.md) |
 
 ## Quick start

README.md

@@ -136,6 +136,7 @@ npm install -g @openagentpack/cli
 ```
 
 This provides the `agents` command. To run from source instead, see [Contributing](./CONTRIBUTING.md).
+Beta testers can install `@openagentpack/cli@beta`; see the [release guide](./docs/contributing/release.md#what-users-install) for version pinning and switching back to stable.
 
 ## Provider support
 

README.zh-CN.md

@@ -136,6 +136,7 @@ npm install -g @openagentpack/cli
 ```
 
 安装后即可使用 `agents` 命令。若想从源码运行，见 [贡献指南](./CONTRIBUTING.md)。
+Beta 用户可以安装 `@openagentpack/cli@beta`；固定版本及切回稳定版的方法见 [发布指南](./docs/contributing/release.zh-CN.md#用户如何安装)。
 
 ## Provider 支持
 

docs/contributing/release.md

@@ -1,64 +1,95 @@
-# Release
+# npm releases
 
-How `@openagentpack/sdk`, `@openagentpack/playground`, and `@openagentpack/cli` are published. This is a concise summary of the full procedure in [`packages/sdk/docs/release.md`](../../packages/sdk/docs/release.md).
+OpenAgentPack publishes `@openagentpack/sdk`, `@openagentpack/playground`, and `@openagentpack/cli` as one fixed version group. Real publishing happens only in GitHub Actions; local commands can build and dry-run the tarballs but cannot publish them.
 
-## Principles
+## One-time repository setup
 
-- npm packages publish **only** from GitHub Actions on `modelstudioai/OpenAgentPack`, via the `release.yml` workflow.
-- Publishing uses **npm Trusted Publishing** (OIDC) — no long-lived write `NPM_TOKEN` is kept.
-- Every release is gated by `bun run verify:release`, which runs the full check suite, package builds, `npm publish --dry-run`, and a packed-consumer smoke (importing every SDK entry point, running `agents --version`, and booting the Playground) on Node.js 20 and 24.
-- Packages publish in topological order: `sdk → playground → cli`.
+An organization owner must allow GitHub Actions to create pull requests in the organization Actions settings; then enable the matching option in **Repository Settings → Actions → General**. The Release PR workflow uses the repository `GITHUB_TOKEN`, not a personal token.
 
-## First-time bootstrap
+Create a GitHub Environment named `npm-release`. Add required reviewers so a maintainer must approve every npm publish job. Do not store an npm token in this environment. GitHub may expose reviewer protection only after the repository is public or on a qualifying private-repository plan.
 
-npm only allows configuring a Trusted Publisher for a package that already exists. Before the first release:
+On npmjs.com, open the settings for each of the three packages and configure the same Trusted Publisher:
 
-1. Create a short-lived granular npm token (allow creating public packages under `@openagentpack`) and save it as the GitHub Actions secret `NPM_TOKEN`.
-2. The repository Actions variable `NPM_RELEASE_ENABLED` is intentionally absent while open-source review is pending. After approval, set it to `true` and manually dispatch the Release workflow to publish the verified prereleases with the `beta` dist-tag.
-3. On each of the three npm packages, configure the Trusted Publisher: Provider `GitHub Actions`, org `modelstudioai`, repo `OpenAgentPack`, workflow `release.yml`, allowed action `npm publish`.
-4. Delete the `NPM_TOKEN` secret, revoke the bootstrap token, require 2FA, and disallow traditional token publishing on all three packages.
-5. Publish a subsequent beta through OIDC and verify the provenance link.
+| npm setting | Value |
+|---|---|
+| Provider | GitHub Actions |
+| Organization | `modelstudioai` |
+| Repository | `OpenAgentPack` |
+| Workflow filename | `release.yml` |
+| Environment | `npm-release` |
 
-Requires npm CLI 11.5.1+ and Node.js 22.14+. The Release workflow uses Node.js 24, pins the npm CLI, and grants `id-token: write`.
+The workflow uses a GitHub-hosted runner, Node.js 24, npm 12, `id-token: write`, and provenance. No `NPM_TOKEN` or `NODE_AUTH_TOKEN` is required. The packages must already exist before npm lets you add a Trusted Publisher.
 
-## Day-to-day releases
+Only after the Trusted Publishers and Environment reviewers are ready, create the repository Actions variable `NPM_RELEASE_ENABLED` with value `true`. Its absence is a kill switch: publish jobs are skipped even if somebody manually dispatches the workflow.
 
-Create a changeset in a feature PR:
+## Changes required in every feature PR
+
+Add a changeset whenever a user-visible package change is made:
 
 ```bash
 bun run changeset
 ```
 
-After merge to `main`, the Release workflow creates/updates a version PR, runs full verification, updates versions and changelogs, and publishes the three packages with OIDC and provenance. If a precise version already exists it is skipped, so a partially-failed release can be safely re-run.
+Choose the SemVer impact and describe the change for the generated changelog. Once merged, the **Release PR** workflow creates or updates a stable version PR on `main`. It never publishes npm packages.
 
-## Beta / pre-release
+## Publish a beta
 
-```bash
-bunx changeset pre enter beta
-bun run changeset
-# ... merge version PR ...
-bunx changeset pre exit
-```
+1. In GitHub, open **Actions → Prepare Beta Release → Run workflow**.
+2. Keep the workflow branch set to `main`, enter the target stable series (for example `0.1.0`), and run it.
+3. The workflow creates or updates `release/0.1.0-beta`, consumes the available changesets, and commits the next version such as `0.1.0-beta.0`.
+4. Open **Actions → Publish npm → Run workflow**.
+5. Select `release/0.1.0-beta` in the workflow branch dropdown, choose `beta`, type `PUBLISH`, and run it.
+6. Approve the `npm-release` Environment deployment after reviewing the commit and job summary.
 
-Pre-release versions derive the npm dist-tag from the SemVer identifier (e.g. `1.0.1-beta.5` → `beta`), so `latest` is never occupied by a pre-release.
+The publish workflow validates that the selected branch, package version, and channel agree. It publishes with the npm `beta` dist-tag, creates an immutable `v0.1.0-beta.N` tag, and creates a GitHub prerelease.
 
-## Local verification
+For another beta, merge fixes and their changesets into `main`, then rerun **Prepare Beta Release** for the same series. The workflow merges `main` into the beta branch and calculates the next beta. Never merge the beta branch back into `main`; delete it after the stable release.
 
-Local machines never perform a real publish — only verify what would be published:
+## Publish a stable release
+
+1. Review and merge the automated `chore: release packages` PR.
+2. Open **Actions → Publish npm → Run workflow**.
+3. Select `main`, choose `stable`, type `PUBLISH`, and run it.
+4. Approve the `npm-release` Environment deployment after reviewing the exact package version.
+
+Only a clean `X.Y.Z` version on `main` can publish to npm's `latest` tag. A successful run creates the matching immutable Git tag and GitHub Release. Publishing is idempotent: packages whose exact version already exists are skipped, so a partially failed run can be retried.
+
+## Local verification
 
 ```bash
 bun run verify:release
-# or check the packed packages directly:
+```
+
+This runs the full repository checks, builds the packages, performs `npm publish --dry-run`, and installs the packed artifacts into clean Node.js 20 and 24 consumer projects. To inspect only the package tarballs:
+
+```bash
 bun run build:packages
-bun run release:publish -- --dry-run --tag beta
+bun run release:publish -- --dry-run
 ```
 
-The publish script temporarily rewrites `./src/*.ts` exports to `./dist/*.js`, resolves `workspace:` dependencies to real versions, and drops the root Apache-2.0 `LICENSE` into each tarball — restoring the workspace in `finally`.
+The publish script blocks any real publish outside GitHub Actions.
+
+## What users install
+
+```bash
+# Stable CLI (npm latest)
+npm install --global @openagentpack/cli
+
+# Beta CLI (npm beta)
+npm install --global @openagentpack/cli@beta
+
+# Pin or test an exact version without a global install
+npx @openagentpack/cli@0.1.0-beta.0 --version
+
+# SDK
+npm install @openagentpack/sdk
+```
 
-## Troubleshooting
+After installing the CLI, run `agents --help`. A beta user returns to stable with `npm install --global @openagentpack/cli@latest`.
 
-- `ENEEDAUTH` — for the first release, confirm the temporary `NPM_TOKEN` secret exists and allows creating a scoped public package. After bootstrap, confirm the Trusted Publisher org/repo/workflow match exactly and the workflow has `id-token: write`.
-- Incomplete package contents — run `bun run verify:release` and confirm the dry-run output includes `README.md`, `LICENSE`, `package.json`, and built `dist/`.
-- Leftover `package.json`/`LICENSE` changes — the publish script restores these on normal exit; if killed forcefully, check the workspace and remove only the temporary package-local `LICENSE`.
+## Recovery
 
-See [`packages/sdk/docs/release.md`](../../packages/sdk/docs/release.md) for the full procedure and troubleshooting.
+- If npm authentication fails, compare the Trusted Publisher repository, workflow filename, and Environment character-for-character with the table above.
+- If a package published before another failed, rerun the same workflow from the same commit. Already-published exact versions are skipped.
+- If a version tag already points at another commit, stop. Tags are immutable; investigate the repository history instead of moving or deleting the tag.
+- If **Prepare Beta Release** reports no unreleased changesets, add a changeset on `main` before preparing another beta.