diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index eb2e26b..ed1d7df 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -9,8 +9,9 @@ # Stage B (publish): runs only on workflow_dispatch with publish=true AND the # protected `npm-release` environment's approval. Downloads Stage A's exact # artifacts, verifies checksums / tag / declared versions, refuses to overwrite -# any existing version, publishes in dependency order with provenance, verifies -# via `npm view` + a clean registry install, and only then creates the GitHub +# any existing version, publishes in dependency order with provenance under the +# `latest` dist-tag, verifies via `npm view` (version + dist-tag) + a clean +# registry install, and only then creates the GitHub # prerelease. # # Auth: npm trusted publishing (GitHub Actions OIDC) — configured on @@ -187,7 +188,9 @@ jobs: fi done echo "no target version exists — safe to publish" - - name: Publish in dependency order (--access public --tag alpha --provenance) + # --tag latest even for prereleases: OIDC trusted publishing cannot run + # dist-tag mutations, so the publish itself must set the tag installs use. + - name: Publish in dependency order (--access public --tag latest --provenance) run: | set -euo pipefail VERSION="${RELEASE_TAG#v}" @@ -198,34 +201,34 @@ jobs: # of a file path and tries git ls-remote (run 29307312478). t="./release-artifacts/git-agentic-sentinel-$p-$VERSION.tgz" echo "publishing @git-agentic/sentinel-$p@$VERSION" - if ! npm publish "$t" --access public --tag alpha --provenance; then + if ! npm publish "$t" --access public --tag latest --provenance; then echo "::error::publish of @git-agentic/sentinel-$p failed. Already published (immutable): ${published:-none}. Do NOT unpublish; fix forward."; exit 1 fi published="$published @git-agentic/sentinel-$p" echo "- @git-agentic/sentinel-$p@$VERSION published" >> "$GITHUB_STEP_SUMMARY" done - name: Verify every published package via npm view + # Hard cap: the loop's deadline is checked between polls, and a hung + # `npm view` could otherwise outlast it. + timeout-minutes: 12 run: | set -euo pipefail VERSION="${RELEASE_TAG#v}" + # The registry can take minutes to show a fresh publish (run + # 44750832298 gave up after 75 s although every package was out). + # One shared 10-minute deadline covers all seven packages. + deadline=$(( $(date +%s) + 600 )) for p in core proxy sandbox mcp steward cli action; do - for i in 1 2 3 4 5; do - got="$(npm view "@git-agentic/sentinel-$p@$VERSION" version 2>/dev/null || true)" - [ "$got" = "$VERSION" ] && break + while :; do + got="$(npm view "@git-agentic/sentinel-$p@$VERSION" version --prefer-online 2>/dev/null || true)" + latest="$(npm view "@git-agentic/sentinel-$p" dist-tags.latest --prefer-online 2>/dev/null || true)" + [ "$got" = "$VERSION" ] && [ "$latest" = "$VERSION" ] && break + if [ "$(date +%s)" -ge "$deadline" ]; then + echo "::error::@git-agentic/sentinel-$p: version ${got:-missing}, dist-tag latest ${latest:-missing}; expected $VERSION after 10 minutes"; exit 1 + fi sleep 15 done - [ "$got" = "$VERSION" ] || { echo "::error::@git-agentic/sentinel-$p@$VERSION not visible after publish"; exit 1; } - tag_alpha="$(npm view "@git-agentic/sentinel-$p" dist-tags.alpha)" - [ "$tag_alpha" = "$VERSION" ] || { echo "::error::@git-agentic/sentinel-$p dist-tag alpha is $tag_alpha, expected $VERSION"; exit 1; } - # npm auto-creates `latest` on a package's first publish (even with - # --tag alpha) and never moves it. OIDC trusted publishing cannot - # run dist-tag mutations, so drift is surfaced here, not fixed here. - tag_latest="$(npm view "@git-agentic/sentinel-$p" dist-tags.latest 2>/dev/null || true)" - if [ -n "$tag_latest" ] && [ "$tag_latest" != "$VERSION" ]; then - echo "::warning::@git-agentic/sentinel-$p dist-tag latest is $tag_latest (stale). Until a stable release exists, retarget it: npm dist-tag add @git-agentic/sentinel-$p@$VERSION latest" - echo "- ⚠ sentinel-$p latest→$tag_latest is stale; run: \`npm dist-tag add @git-agentic/sentinel-$p@$VERSION latest\`" >> "$GITHUB_STEP_SUMMARY" - fi - echo "@git-agentic/sentinel-$p@$VERSION visible, dist-tag alpha OK" + echo "@git-agentic/sentinel-$p@$VERSION visible, dist-tag latest OK" done verify-registry-install: diff --git a/README.md b/README.md index 3e17f75..4157d09 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,10 @@ macOS Seatbelt enforcement is exercised on maintainers' machines) — but this has not yet been hardened by production use, and APIs may change without notice. The complete phase-by-phase build log lives in [docs/adr/](./docs/adr/) (one ADR per phase). **Published as an alpha -preview**: all seven packages ship under the `alpha` -dist-tag (`npm install -g @git-agentic/sentinel-cli@alpha @git-agentic/sentinel-proxy@alpha`) — see +preview**: every release, alphas included, is published as the `latest` +dist-tag (`npm install -g @git-agentic/sentinel-cli @git-agentic/sentinel-proxy`; +until `0.1.0-alpha.4` ships, `latest` still names `0.1.0-alpha.2` for most +packages, so append `@0.1.0-alpha.3` to get the current release) — see the [release notes](./docs/releases/) and [release process](./docs/release-process.md); building from source (Quickstart below) remains fully supported. Threat model: diff --git a/SECURITY.md b/SECURITY.md index a2e8d9c..a4a206f 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,7 +6,7 @@ sandbox for the npm ecosystem. We treat reports against it accordingly. ## Supported versions Sentinel is pre-1.0. Only the tip of `main` and the most recent published -prerelease (`@git-agentic/sentinel-*@alpha`) are supported; +prerelease (the `latest` dist-tag of `@git-agentic/sentinel-*`) are supported; there are no maintained release branches. Prereleases are snapshots of `main` — fixes ship as the next prerelease, never as patches to an old one. diff --git a/docs/release-process.md b/docs/release-process.md index 7cbc400..427dced 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -21,17 +21,14 @@ failure without unpublishing anything already released. ## Prerelease versioning -- Pre-1.0 releases use `0.1.0-alpha.N` (then `-beta.N`, `-rc.N`) with the - npm dist-tag matching the prerelease channel (`alpha`, `beta`, `rc`). -- **The `latest` dist-tag, pre-stable:** npm force-creates `latest` on a - package's first publish (even with `--tag alpha`) and never moves it; it - also cannot be deleted. Until a stable release exists, `latest` is - therefore kept pointing at the **newest prerelease** — retargeted manually - after each release (`npm dist-tag add @git-agentic/sentinel-

@ - latest`, one per package; needs an interactive npm login — OIDC trusted - publishing covers publish only, not dist-tag mutations). Stage B warns in - the run summary when `latest` is stale. Once `0.1.0` stable ships with - `--tag latest`, this manual step disappears. +- Pre-1.0 releases use `0.1.0-alpha.N` (then `-beta.N`, `-rc.N`). +- **Every release is published with `--tag latest`**, prereleases included. + OIDC trusted publishing covers `npm publish` only, not `npm dist-tag`, and + a manual retarget needs one browser 2FA approval per package. So the + publish itself sets the tag that a plain `npm install` resolves, and no + release needs a manual dist-tag step. +- The `alpha` dist-tag is no longer moved. It stays on `0.1.0-alpha.3`, the + last release published with `--tag alpha`; install without a tag. - All seven packages version in lockstep — one release version across the workspace, even for packages with no changes. Lockstep keeps the internal dependency pins trivially correct and the support matrix one-dimensional. @@ -77,8 +74,9 @@ jobs): requires `publish=true` on the dispatch **and** approval of the protected artifacts, verifies checksums, verifies the tag points at the tested commit, verifies every tarball declares the release version, refuses to run if any target version already exists, publishes in dependency order with -`--access public --tag alpha --provenance`, and verifies each package via -`npm view` (version + dist-tag). The `verify-registry-install` job then installs +`--access public --tag latest --provenance`, and verifies each package via +`npm view` (version + `latest` dist-tag), waiting up to 10 minutes in total for +the registry to show them. The `verify-registry-install` job then installs the published packages from the public registry in a clean project. Only after that does the `github-release` job create the GitHub prerelease with the artifacts attached. @@ -124,7 +122,8 @@ exact commit + workflow run. 1. **Deprecate immediately**: `npm deprecate @git-agentic/sentinel-

@ "SECURITY: compromised — do not install"` for every affected package. 2. Point the dist-tag at the last known-good version (`npm dist-tag add - @git-agentic/sentinel-

@ alpha`). + @git-agentic/sentinel-

@ latest`; interactive login, one 2FA + approval per package). 3. Request npm unpublish/security takedown through npm support if within policy; do not rely on it. 4. Rotate every credential the pipeline touched (npm token, corpus/policy @@ -145,11 +144,9 @@ path. 1. Land fixes on `main`; bump all workspaces + internal pins + `ENGINE_VERSION`/CLI/MCP versions to `0.1.0` (no prerelease suffix). -2. Run the same two-stage pipeline with tag `v0.1.0`, publishing with - `--tag latest` (the workflow's dist-tag is the one alpha-specific knob to - change — everything else is identical). -3. Keep `alpha` pointing at the last alpha until `latest` exists, then move - `alpha` forward to `0.1.0` as well so `@alpha` installs never resolve - older than stable. +2. Run the same two-stage pipeline with tag `v0.1.0`. It already publishes + with `--tag latest`, so nothing in the workflow changes. +3. Once stable releases exist, publish later prereleases under a channel tag + (`--tag next` or `--tag beta`) so they stop replacing stable on `latest`. 4. The GitHub release loses the `--prerelease` flag; SECURITY.md's supported versions section starts naming the stable line. diff --git a/packages/action/README.md b/packages/action/README.md index 14dfcf2..d938af2 100644 --- a/packages/action/README.md +++ b/packages/action/README.md @@ -9,7 +9,7 @@ idempotent PR comment body — no separately-running proxy needed. > without notice. Not production-ready. ```bash -npm install @git-agentic/sentinel-action@alpha +npm install @git-agentic/sentinel-action ``` This package is the engine behind the composite GitHub Action defined at the diff --git a/packages/cli/README.md b/packages/cli/README.md index db61811..9e9ce14 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -10,7 +10,7 @@ authoring/signing, and signed audit attestations. > without notice. Not production-ready. ```bash -npm install -g @git-agentic/sentinel-cli@alpha +npm install -g @git-agentic/sentinel-cli sentinel --version sentinel audit is-odd 3.0.1 # requires a running @git-agentic/sentinel-proxy diff --git a/packages/core/README.md b/packages/core/README.md index f657e85..c8f71f7 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -9,7 +9,7 @@ that can only ever *enrich* — never set — a score. > without notice. Not production-ready. ```bash -npm install @git-agentic/sentinel-core@alpha +npm install @git-agentic/sentinel-core ``` ```ts diff --git a/packages/mcp/README.md b/packages/mcp/README.md index 92a66dc..3f8a749 100644 --- a/packages/mcp/README.md +++ b/packages/mcp/README.md @@ -9,7 +9,7 @@ only write tool *requests* approval; it can never grant one. > without notice. Not production-ready. ```bash -npm install -g @git-agentic/sentinel-mcp@alpha +npm install -g @git-agentic/sentinel-mcp ``` MCP client configuration: diff --git a/packages/proxy/README.md b/packages/proxy/README.md index 6081dba..35485ff 100644 --- a/packages/proxy/README.md +++ b/packages/proxy/README.md @@ -10,7 +10,7 @@ npm compatibility surface (packuments, dist-tags, unpublish-as-retraction). > without notice. Not production-ready. ```bash -npm install -g @git-agentic/sentinel-proxy@alpha +npm install -g @git-agentic/sentinel-proxy sentinel-proxy # starts the proxy on 127.0.0.1:4873 ``` diff --git a/packages/sandbox/README.md b/packages/sandbox/README.md index a178f4e..9caf95c 100644 --- a/packages/sandbox/README.md +++ b/packages/sandbox/README.md @@ -10,7 +10,7 @@ with a fail-closed contract on any other platform. > without notice. Not production-ready. ```bash -npm install @git-agentic/sentinel-sandbox@alpha +npm install @git-agentic/sentinel-sandbox ``` ## Platform behavior in this alpha diff --git a/packages/steward/README.md b/packages/steward/README.md index a30d873..431416b 100644 --- a/packages/steward/README.md +++ b/packages/steward/README.md @@ -10,7 +10,7 @@ retraction-corpus releases that Sentinel proxies consume offline. > without notice. Not production-ready. ```bash -npm install -g @git-agentic/sentinel-steward@alpha +npm install -g @git-agentic/sentinel-steward ``` All four variables are required: