The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # npm promote |
| 2 | |
| 3 | `@effect/npm-promote` moves the `latest` dist-tag to a release that |
| 4 | `changeset publish` put under `staging`. It waits until npm's abbreviated |
| 5 | metadata lists the target version of every public workspace package, so fresh |
| 6 | installs never resolve an `@effect/*` version that needs an `effect` the |
| 7 | registry does not serve yet. |
| 8 | |
| 9 | Preview what it would do from the repository root: |
| 10 | |
| 11 | ```sh |
| 12 | node packages/tools/npm-promote/src/bin.ts --dry-run |
| 13 | ``` |
| 14 | |
| 15 | Each run: |
| 16 | |
| 17 | 1. Lists the non-private workspace packages and their versions at the |
| 18 | checked-out revision. |
| 19 | 2. Fetches each package's abbreviated metadata from `registry.npmjs.org`. If any |
| 20 | target version is missing, nothing is promoted. |
| 21 | 3. Runs `npm dist-tag add <name>@<version> latest`, `effect` first, for every |
| 22 | package whose `latest` is lower than the target. The CDN caches the |
| 23 | abbreviated metadata for minutes, so it only decides visibility; each |
| 24 | package is decided from its live `latest` on the dist-tags endpoint. A |
| 25 | higher `latest` is never moved back, so a run that failed halfway is |
| 26 | finished by the next one. A failed read or write stops the run, so no |
| 27 | package moves ahead of `effect`. |
| 28 | 4. Deploys the website for the version bump commit when `effect`'s live |
| 29 | `latest` is exactly the target and no deploy is recorded for that commit. |
| 30 | Deploys are recorded as GitHub deployments in the `website-v4` environment, |
| 31 | so a failed or interrupted deploy is retried by the next run. |
| 32 | 5. Closes every open tracking issue. A release that a newer one superseded |
| 33 | still closes them, and a failure to close never blocks the deploy. |
| 34 | |
| 35 | When the version bump commit is older than `--overdue-after-hours` (12 by |
| 36 | default) and the release is still not visible or cannot be promoted, the tool |
| 37 | opens or updates a single tracking issue. For versions that are not visible it |
| 38 | checks each version's own registry document and lists versions missing from npm |
| 39 | (404), versions published but not visible yet, and versions whose check failed. |
| 40 | Failed `npm dist-tag add` writes are listed separately, and a registry read |
| 41 | that fails during promotion lists its version as unchecked. Read failures while |
| 42 | deciding the website deploy happen after promotion succeeded, so they fail the |
| 43 | run and are retried, but never open the tracking issue. Prerelease versions are |
| 44 | never promoted. |
| 45 | |
| 46 | GitHub's issue listing can miss an open issue while GitHub is degraded, so a |
| 47 | run may open a duplicate tracking issue. The next run keeps the oldest open |
| 48 | tracking issue and closes the others as duplicates of it. |
| 49 | |
| 50 | `--dry-run` reads the registry and prints the plan. It never moves dist-tags, |
| 51 | deploys the website, or touches GitHub issues. Real runs need |
| 52 | `GITHUB_REPOSITORY`, `GITHUB_TOKEN` and `WEBSITE_DISPATCH_TOKEN`. |
| 53 | |
| 54 | ## Workflow |
| 55 | |
| 56 | `.github/workflows/npm-promote.yml` runs every 10 minutes and after each |
| 57 | `Release` run on `main`. Setting the `NPM_PROMOTE_PAUSED` repository variable |
| 58 | to `true` skips new runs, which keeps a bad release on `staging`. |
| 59 | |
| 60 | The job moves dist-tags with npm trusted publishing over OIDC, so no npm token |
| 61 | is stored anywhere. It runs in the `npm-promote` environment with |
| 62 | `id-token: write` and npm 11.21.0 or later. `effect` and every `@effect/*` |
| 63 | package need two trusted publisher configurations: |
| 64 | |
| 65 | - `release.yml`: publishing allowed, "Allow npm dist-tag" off. |
| 66 | - `npm-promote.yml` in environment `npm-promote`: publishing not allowed, |
| 67 | "Allow npm dist-tag" on. |
| 68 | |
| 69 | With no tokens involved, packages can also turn on "Require two-factor |
| 70 | authentication and disallow tokens". |
| 71 | |
| 72 | ## Other writers of `latest` |
| 73 | |
| 74 | Only this workflow is expected to move `latest`. `changeset publish` uses the |
| 75 | `staging` tag; npm sets `latest` itself only on the first publish of a new |
| 76 | package, which leaves it at the target. npm has no compare-and-set for |
| 77 | dist-tags, so the live read narrows but cannot close the window between reading |
| 78 | and writing a tag. |
| 79 | |
| 80 | To change `latest` by hand, set `NPM_PROMOTE_PAUSED=true`, then wait until no |
| 81 | `npm promote` run is in progress: pausing only skips runs that have not started. |
| 82 | Unpause once the manual change is done. To roll back a bad release, stay paused |
| 83 | until `main` has a fixed version: once unpaused, the tool moves `latest` back |
| 84 | to the version at HEAD. |
| 85 | |
| 86 | ## Website deploys |
| 87 | |
| 88 | A deploy sends the `publish-api-reference` dispatch to Effect-TS/website. The |
| 89 | website builds an API reference snapshot keyed by the v3 and v4 revisions and |
| 90 | reuses it when that snapshot is already published, so a repeated dispatch for |
| 91 | the same revision only redeploys the site. A recorded deploy means the website |
| 92 | accepted the dispatch, not that its own deploy succeeded. |