sailfork / t3code-github / .repos/ effect/ packages/ tools/ npm-promote
.repos/effect/packages/tools/npm-promote/README.md
npm promote
@effect/npm-promote moves the latest dist-tag to a release that
changeset publish put under staging. It waits until npm's abbreviated
metadata lists the target version of every public workspace package, so fresh
installs never resolve an @effect/* version that needs an effect the
registry does not serve yet.
Preview what it would do from the repository root:
node packages/tools/npm-promote/src/bin.ts --dry-run Each run:
- Lists the non-private workspace packages and their versions at the checked-out revision.
- Fetches each package's abbreviated metadata from
registry.npmjs.org. If any target version is missing, nothing is promoted. - Runs
npm dist-tag add <name>@<version> latest,effectfirst, for every package whoselatestis lower than the target. The CDN caches the abbreviated metadata for minutes, so it only decides visibility; each package is decided from its livelateston the dist-tags endpoint. A higherlatestis never moved back, so a run that failed halfway is finished by the next one. A failed read or write stops the run, so no package moves ahead ofeffect. - Deploys the website for the version bump commit when
effect's livelatestis exactly the target and no deploy is recorded for that commit. Deploys are recorded as GitHub deployments in thewebsite-v4environment, so a failed or interrupted deploy is retried by the next run. - Closes every open tracking issue. A release that a newer one superseded still closes them, and a failure to close never blocks the deploy.
When the version bump commit is older than --overdue-after-hours (12 by
default) and the release is still not visible or cannot be promoted, the tool
opens or updates a single tracking issue. For versions that are not visible it
checks each version's own registry document and lists versions missing from npm
(404), versions published but not visible yet, and versions whose check failed.
Failed npm dist-tag add writes are listed separately, and a registry read
that fails during promotion lists its version as unchecked. Read failures while
deciding the website deploy happen after promotion succeeded, so they fail the
run and are retried, but never open the tracking issue. Prerelease versions are
never promoted.
GitHub's issue listing can miss an open issue while GitHub is degraded, so a run may open a duplicate tracking issue. The next run keeps the oldest open tracking issue and closes the others as duplicates of it.
--dry-run reads the registry and prints the plan. It never moves dist-tags,
deploys the website, or touches GitHub issues. Real runs need
GITHUB_REPOSITORY, GITHUB_TOKEN and WEBSITE_DISPATCH_TOKEN.
Workflow
.github/workflows/npm-promote.yml runs every 10 minutes and after each
Release run on main. Setting the NPM_PROMOTE_PAUSED repository variable
to true skips new runs, which keeps a bad release on staging.
The job moves dist-tags with npm trusted publishing over OIDC, so no npm token
is stored anywhere. It runs in the npm-promote environment with
id-token: write and npm 11.21.0 or later. effect and every @effect/*
package need two trusted publisher configurations:
release.yml: publishing allowed, "Allow npm dist-tag" off.npm-promote.ymlin environmentnpm-promote: publishing not allowed, "Allow npm dist-tag" on.
With no tokens involved, packages can also turn on "Require two-factor authentication and disallow tokens".
Other writers of latest
Only this workflow is expected to move latest. changeset publish uses the
staging tag; npm sets latest itself only on the first publish of a new
package, which leaves it at the target. npm has no compare-and-set for
dist-tags, so the live read narrows but cannot close the window between reading
and writing a tag.
To change latest by hand, set NPM_PROMOTE_PAUSED=true, then wait until no
npm promote run is in progress: pausing only skips runs that have not started.
Unpause once the manual change is done. To roll back a bad release, stay paused
until main has a fixed version: once unpaused, the tool moves latest back
to the version at HEAD.
Website deploys
A deploy sends the publish-api-reference dispatch to Effect-TS/website. The
website builds an API reference snapshot keyed by the v3 and v4 revisions and
reuses it when that snapshot is already published, so a repeated dispatch for
the same revision only redeploys the site. A recorded deploy means the website
accepted the dispatch, not that its own deploy succeeded.