Skip to content

feat(release): add monthly npm extended-stable publication#99352

Merged
kevinslin merged 8 commits into
openclaw:mainfrom
kevinslin:dev/kevinlin/minimal-npm-stable
Jul 4, 2026
Merged

feat(release): add monthly npm extended-stable publication#99352
kevinslin merged 8 commits into
openclaw:mainfrom
kevinslin:dev/kevinlin/minimal-npm-stable

Conversation

@kevinslin

@kevinslin kevinslin commented Jul 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What Problem This Solves

OpenClaw cannot currently publish a trailing-month core package to the npm
extended-stable dist-tag without treating it like the existing promoted
latest channel or adopting the much larger superseded release-policy
framework. The existing Full Release Validation graph also rejects the required
extended-stable/YYYY.M.33 workflow ref, making a guarded monthly run
unreachable.

The user-facing stable update channel already resolves through npm latest.
This PR intentionally uses the separate extended-stable name so the new
trailing-month contract does not redefine that existing channel.

Why This Change Was Made

This adds one npm-only extended-stable mode to the existing release workflow.
Final YYYY.M.PATCH versions at patch 33 or later must publish from the exact
extended-stable/YYYY.M.33 branch, with the release tag, checkout, branch tip,
package version, preflight run, Full Release Validation run, manifest, and
promoted tarball all bound to the same commit.

The implementation reuses the existing preflight manifest v1 and tested
tarball, captures the prior npm selector before mutation, performs bounded
exact-version and selector readback, and prints a forward repair command that
points extended-stable at the newly published version. Rollback to the prior
selector is a separate operator decision. Full Release Validation narrowly
trusts the canonical extended-stable branch shape and verifies every required
child run used the target SHA.

Plugin publication, native platforms, GitHub Releases, private dist-tags,
Docker, mobile, and website publication remain out of scope. Protected main
must be on any strictly later calendar month with a daily patch below 33, so
supported maintenance patches remain publishable after development advances
more than one month.

Fork and non-production rehearsals can explicitly set
bypass_extended_stable_guard=true to relax the .33 threshold and protected
main month policy. The bypass is extended-stable-only and default-off; it
still requires the canonical branch, branch-tip/tag/checkout SHA equality,
final tag/package identity, authenticated validation evidence, verified
tarball, environment approval, and registry proof.

User Impact

Release operators can publish the completed month's core openclaw package to
npm extended-stable, beginning at .33, without moving latest or invoking
other publication surfaces. Maintainers can exercise the guarded path with a
historical test version by enabling the audited bypass. Existing user-facing
stable | beta | dev CLI channel behavior is unchanged.

Evidence

  • Current head: 4c0a6e5fef.
  • Addressed review feedback:
    • selector recovery now prints
      npm dist-tag add [email protected] extended-stable, targeting the new
      published version rather than restoring/removing the prior selector;
    • the tarball mismatch test derives the expected checkout version from
      package.json instead of hard-coding 2026.6.11;
    • the docs/ci.md release link now uses the required root-relative Mintlify
      route without a .md suffix.
  • Current-head dependency-free checks passed:
    • node --check scripts/openclaw-npm-extended-stable-release.mjs;
    • bash -n scripts/openclaw-npm-publish.sh;
    • forward repair command probe for v2026.6.33;
    • invalid repair input rejection;
    • git diff --check.
  • Fork-only live publication canary on descendant SHA
    66a3300450148206e063c20d2de78a508f4fd691:
    • published @kevins8/[email protected] and 2000.4.34 to a persistent
      loopback-only Verdaccio registry;
    • observed extended-stable: absent -> 2000.4.33 -> 2000.4.34;
    • independently installed @kevins8/openclaw@extended-stable from a separate
      host process and observed OpenClaw 2000.4.34;
    • tarball SHA-256 values:
      82375e4931bb865283b9ca62e45d09a25999a5d44feddb22683697ec3c1a0d23
      (.33) and
      6b7eb3c48a8ed6f44cce010b78aabca04c9f2d66eb7b20d06fed9f4e7493c287
      (.34).
  • The code-bearing head 770800b43a passed all exact-head checks in
    run 28707921579.
    On the current docs-only head 4c0a6e5fef, all latest checks passed or were
    skipped/neutral except checks-node-compact-large-whole-1 in
    run 28708169657.
    Its sole failure is the pre-existing ClawHub plugin documentation fixture
    mismatch at src/docs/clawhub-plugin-docs.test.ts:74; this PR changes neither
    that test nor docs/plugins/building-plugins.md. Local Vitest was not run
    because the worktree lockfile differs from the shared node_modules;
    Blacksmith Testbox was unavailable because installed Crabbox 0.16.0 is
    below the repository-required 0.22.0.

The canary proves package build/publish/readback/install and selector promotion
against a real local npm registry. It does not claim official openclaw npm
publication, GitHub OIDC trusted publishing, production npm-release
environment approval, or public provenance. Those remain an explicit
release-owner proof/override gate before merge.

@kevinslin
kevinslin requested a review from a team as a code owner July 3, 2026 03:51
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation scripts Repository scripts size: XL maintainer Maintainer-authored PR labels Jul 3, 2026
chatgpt-codex-connector[bot]
chatgpt-codex-connector Bot reviewed Jul 3, 2026
View reviewed changes

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9dc0b836df

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/openclaw-npm-stable-release.mjs Outdated
@clawsweeper

clawsweeper Bot commented Jul 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 4, 2026, 10:04 AM ET / 14:04 UTC.

Summary
The PR adds an npm-only extended-stable dist-tag publication path across release workflows, helper scripts, docs, and tests.

PR surface: Tests +793, Docs +108, Config +93, Other +494. Total +1488 across 13 files.

Reproducibility: not applicable. this is a release-automation feature rather than a reported runtime bug. Current main and the public npm registry do not yet expose the requested extended-stable publication path.

Review metrics: 2 noteworthy metrics.

  • Release inputs changed: 1 dist-tag option added, 1 default-false workflow input added. Operator-facing release inputs affect dispatch runbooks, environment approval expectations, and release-manager review before merge.
  • Trusted release refs expanded: 3 gates widened. The NPM release workflow, release checks workflow, and Full Release Validation child-run check now recognize extended-stable/YYYY.M.33 authority.

Stored data model
Persistent data-model change detected: migration/backfill/repair: docs/ci.md, serialized state: scripts/openclaw-npm-publish.sh, serialized state: test/scripts/openclaw-npm-publish.test.ts, vector/embedding metadata: test/scripts/openclaw-npm-publish.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: canonical
Canonical: #99352
Summary: This PR is the canonical narrow npm publication path; the broader release-policy PR overlaps but is open and not a safe superseding target, while the CLI issue and PR are adjacent downstream work.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Record release-owner acceptance or waiver for the official npm trusted-publish/public-registry proof gap and bypass boundary.
  • [P2] Rerun or explain the current-head checks-node-compact-large-whole-1 failure before merge.

Risk before merge

  • [P1] Release owners still need to approve or waive the lack of official openclaw npm trusted-publish, npm-release environment, and public-registry proof because the current proof is a fork/local Verdaccio canary.
  • [P1] The default-off bypass relaxes the .33 patch threshold and protected-main month policy inside the production NPM release workflow, so misuse depends on release environment approval and operator discipline.
  • [P1] The trusted release surface expands to extended-stable/YYYY.M.33 for NPM release dispatch, release checks, and Full Release Validation child-run acceptance; this is a release authority decision that green unit tests cannot settle.
  • [P1] The current exact PR head has one failing CI shard, so maintainers need a rerun or an explanation before merge even though the failure does not currently point to a reviewable line-level defect in this patch.

Maintainer options:

  1. Record Release-Owner Acceptance (recommended)
    Have release owners explicitly approve or waive the official npm trusted-publish/public-registry proof gap, the default-off bypass, and the exact extended-stable branch authority before merge.
  2. Exercise An Owner-Controlled Rehearsal
    If maintainers want stronger proof, pause merge until an owner-controlled npm-release environment rehearsal or first official publication records the trusted-publishing and public-registry evidence.
  3. Pause Behind Broader Release Policy
    If maintainers prefer the larger monthly release-policy framework, keep this PR paused until the broader release-policy PR has a clear landing direction.

Next step before merge

  • [P2] Human release-owner review is required because the remaining blockers are trusted npm publication approval, bypass/security-boundary acceptance, and exact-head CI resolution, not a narrow automatable code repair.

Security
Needs attention: The diff changes trusted npm publication behavior and adds a default-off release-policy bypass, so release-owner security review remains required before merge.

Review details

Best possible solution:

Merge only after release owners explicitly accept or waive the production npm proof gap, the default-off bypass boundary, and the expanded trusted-ref model, while keeping stable/latest behavior unchanged and sequencing CLI update support separately.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a release-automation feature rather than a reported runtime bug. Current main and the public npm registry do not yet expose the requested extended-stable publication path.

Is this the best way to solve the issue?

Yes, the narrow npm-only path is a maintainable alternative to the broader release-policy PR and keeps existing stable/latest behavior unchanged. It is not fully merge-ready until release owners accept the production proof and bypass/security boundaries.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 4287d2629fb3.

Label changes

Label justifications:

  • P2: This is normal-priority release automation and operator workflow work with limited blast radius and no active end-user outage.
  • merge-risk: 🚨 compatibility: The PR adds a new operator-facing npm dist-tag mode and patch 33+ publication rule while preserving existing stable/latest semantics.
  • merge-risk: 🚨 security-boundary: The PR changes which branch refs can reach trusted npm publishing and adds a default-off bypass in the production release workflow.
  • merge-risk: 🚨 automation: The diff changes NPM release workflow gates, Full Release Validation child-run acceptance, release-check trusted refs, and registry readback behavior.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes after-fix terminal proof from a fork/local Verdaccio canary that builds, publishes, promotes, reads back, and installs the selector; official npm proof remains a release-owner gate.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix terminal proof from a fork/local Verdaccio canary that builds, publishes, promotes, reads back, and installs the selector; official npm proof remains a release-owner gate.
Evidence reviewed

PR surface:

Tests +793, Docs +108, Config +93, Other +494. Total +1488 across 13 files.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 5 798 5 +793
Docs 3 129 21 +108
Config 3 127 34 +93
Generated 0 0 0 0
Other 2 511 17 +494
Total 13 1565 77 +1488

Security concerns:

  • [medium] Production workflow gains an extended-stable bypass — .github/workflows/openclaw-npm-release.yml:37
    bypass_extended_stable_guard is default-off and still behind identity checks, but it relaxes patch and protected-main month eligibility inside the production NPM release workflow and should be explicitly accepted by release owners.
    Confidence: 0.84
  • [medium] Trusted publish refs expand to extended-stable branches — .github/workflows/openclaw-npm-release.yml:432
    The publish guard now accepts refs/heads/extended-stable/* when the dist-tag is extended-stable; the helper narrows the exact branch shape, but this still changes which branch refs can reach OIDC npm publish.
    Confidence: 0.8

What I checked:

Likely related people:

  • vincentkoc: Recent history on the NPM release workflow, Full Release Validation, release checks, and publish wrapper includes release control hardening and argument validation that this PR extends. (role: recent release workflow contributor; confidence: high; commits: abb6f04e0cac, a1201e99fc26, f5a7f613ee4d; files: .github/workflows/openclaw-npm-release.yml, .github/workflows/full-release-validation.yml, .github/workflows/openclaw-release-checks.yml)
  • steipete: History shows repeated work on configurable npm release tags, trusted publish recovery, beta/latest behavior, release preflight artifacts, and release documentation around the same operator path. (role: release automation history contributor; confidence: high; commits: 209535b7c76d, ad06d5ab4db2, 50b7a2ffa193; files: .github/workflows/openclaw-npm-release.yml, scripts/openclaw-npm-publish.sh, .github/workflows/full-release-validation.yml)
  • osolmaz: Older history on the NPM release workflow introduced trusted publishing and manual publish flow changes that remain part of the publication boundary this PR changes. (role: adjacent trusted-publishing workflow contributor; confidence: medium; commits: cd7d49b48e30; files: .github/workflows/openclaw-npm-release.yml, scripts/openclaw-npm-publish.sh)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.
Review history (4 earlier review cycles)
  • reviewed 2026-07-04T00:45:52.704Z sha 423941d :: needs real behavior proof before merge. :: [P1] Point selector repair at the published version | [P2] Derive the expected version in the mismatch test
  • reviewed 2026-07-04T13:44:09.830Z sha 770800b :: found issues before merge. :: [P3] Use the published docs route for the release link
  • reviewed 2026-07-04T13:50:35.521Z sha 4c0a6e5 :: needs maintainer review before merge. :: none
  • reviewed 2026-07-04T13:56:54.287Z sha 4c0a6e5 :: needs maintainer review before merge. :: none

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. merge-risk: 🚨 automation 🚨 May affect CI, automerge, proof capture, label sync, or maintainer automation. labels Jul 3, 2026
@kevinslin
kevinslin force-pushed the dev/kevinlin/minimal-npm-stable branch from c3be4f0 to daa23a8 Compare July 3, 2026 06:45
@kevinslin kevinslin changed the title feat(release): add monthly npm stable publication feat(release): add monthly npm extended-stable publication Jul 4, 2026
This was referenced Jul 4, 2026
Closed
Merged
@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jul 4, 2026
@kevinslin

kevinslin commented Jul 4, 2026

Copy link
Copy Markdown
Contributor Author

Fixed the actionable review findings in 770800b43a:

  • selector recovery now moves extended-stable forward to the newly published version instead of restoring or removing the previous selector;
  • the tarball mismatch test derives the checkout version from package.json instead of hard-coding a release number;
  • focused tests cover forward recovery, invalid repair inputs, and workflow wiring.

Exact-head CI is green: all required checks passed in run 28707921579. The PR body now also records the fork-only Verdaccio publish, promotion, readback, and separate-process install proof.

The remaining official npm/OIDC/npm-release environment proof is a release-owner approval or override gate; this PR does not claim that production publication occurred.

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jul 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels Jul 4, 2026
@kevinslin

kevinslin commented Jul 4, 2026

Copy link
Copy Markdown
Contributor Author

Follow-up review finding fixed in 4c0a6e5fef: docs/ci.md now uses the root-relative Mintlify route /reference/RELEASING#monthly-npm-only-extended-stable-publication without a .md suffix.

Current-head CI completed. Every latest check passed or was skipped/neutral except checks-node-compact-large-whole-1 in run 28708169657. Its sole failure is the pre-existing ClawHub plugin documentation fixture mismatch at src/docs/clawhub-plugin-docs.test.ts:74; this PR changes neither that test nor docs/plugins/building-plugins.md, so it is intentionally left out of scope. The prior code-bearing head passed all exact-head checks in run 28707921579.

The remaining official npm trusted-publish/environment approval is a release-owner acceptance or waiver gate.

@clawsweeper re-review

@kevinslin
kevinslin merged commit ba7b5db into openclaw:main Jul 4, 2026
106 of 113 checks passed
@kevinslin
kevinslin deleted the dev/kevinlin/minimal-npm-stable branch July 4, 2026 15:24
@github-actions github-actions Bot mentioned this pull request Jul 4, 2026
Open
@RomneyDa RomneyDa mentioned this pull request Jul 4, 2026
Merged
@clawsweeper clawsweeper Bot mentioned this pull request Jul 4, 2026
Open
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jul 5, 2026
@kevinslin
feat(release): add monthly npm extended-stable publication (openclaw#…
8260dfe 
…99352)

* feat(release): add npm stable publication

* fix(release): allow stable full validation

* feat(release): add stable guard test bypass

* fix(release): allow stable maintenance after month rollover

* docs: refresh release documentation map

* refactor(release): rename monthly channel to extended-stable

* fix(release): repair extended-stable selector forward

* docs(release): fix extended-stable link
@clawsweeper clawsweeper Bot mentioned this pull request Jul 7, 2026
Merged
@clawsweeper clawsweeper Bot mentioned this pull request Jul 17, 2026
Merged
RomneyDa added a commit that referenced this pull request Jul 17, 2026
@RomneyDa
fix(release): allow canonical extended-stable checks
e3eb01a 
Restore the openclaw-release-checks.yml portion of c7810fc (#99352) that authorizes the canonical extended-stable/YYYY.M.33 workflow branch.
@RomneyDa RomneyDa mentioned this pull request Jul 17, 2026
Merged
RomneyDa added a commit that referenced this pull request Jul 17, 2026
@RomneyDa
fix(release): restore frozen validation startup (#110210)
3341ade 
* fix(release): restore frozen validation startup

Adapt the no-write validation portion of b597a8d (#103834) for the 6.x extended-stable workflow set. Remove validation-owned image publisher jobs instead of granting write permissions; Docker publication remains out of scope.

* fix(release): allow canonical extended-stable checks

Restore the openclaw-release-checks.yml portion of c7810fc (#99352) that authorizes the canonical extended-stable/YYYY.M.33 workflow branch.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@chatgpt-codex-connector chatgpt-codex-connector[bot] chatgpt-codex-connector[bot] left review comments

Assignees

No one assigned

Labels

docs Improvements or additions to documentation maintainer Maintainer-authored PR merge-risk: 🚨 automation 🚨 May affect CI, automerge, proof capture, label sync, or maintainer automation. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. P2 Normal backlog priority with limited blast radius. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. scripts Repository scripts size: XL status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@kevinslin