Skip to content
Trazum

Releasing

Documentation / Contributing · Versioning

Publishing is the one action in this repository that cannot be undone. npm allows unpublishing for 72 hours and then the version number is spent for good — it can never be reused, even for identical content. Everything here is arranged so a mistake fails the workflow rather than reaching the registry.

One-time setup#

This has to be done once, by whoever owns the npm scope, before any release can work. Until it is done a tag push runs every check and then fails at the publish step — which is the right failure, having published nothing.

1. Create the @trazum scope — done#

The org exists and all three packages are on npm as of 2026-08-13, published by hand at 1.8.0.

That first publish had to be manual, and it was not a workaround. A trusted publisher is configured on a package's settings page, and that page does not exist until the package does. So the order was: publish once with a login, then configure trusted publishing, and every release after that goes through a tag with no credential anywhere.

Kept here because it is the sequence anyone forking this into a new scope has to repeat, and because two things went wrong that are worth not repeating:

npm login                                     # E404 on PUT means "not logged in",
npm whoami                                    # not "no such scope" — check both
npm org ls trazum                             # before blaming the manifests
npm publish -w @trazum/core --access public   # core first: the others pin it exactly
npm publish -w @trazum/cli  --access public
npm publish -w @trazum/mcp  --access public
  • A 404 Not Found - PUT is an auth failure. npm hides the difference between "this scope does not exist" and "you may not write to it", so the first real attempt looked like a scope problem and was an expired token. npm whoami is the one-second check that says which.

  • npm view 404s for several minutes after a successful publish, and 1.83.0 measured how long that can be. @trazum/cli was accepted, signed and written to the transparency log, and the registry served the previous version for twenty minutes while its two siblings from the same job were installable within seconds. The CLI's tarball is 862 kB against the MCP server's 65 kB, which is the only difference between them.

    Since 1.83.0 the release job waits for it: scripts/npm-serves.mjs asks the registry's dist-tags endpoint for every publishable package until each serves the version being released, and fails the job if one never does. A release is not the moment npm publish returns; it is the moment a stranger typing npm install gets what RELEASES.md says they will.

    And the dist-tag was not that moment either. On 2.7.12 the check passed at 22:42:49 UTC and @trazum/core's tarball answered 404 for three minutes more, so npx @trazum/cli@2.7.12 failed with E404 while the job was tagging the release. The script now asks for each tarball as well, with a HEAD request to the address an install fetches, and says which of the two it is still waiting for.

  • npm view 404s for several minutes after a successful publish. The aggregated packument propagates behind the per-version document and the tarball, so + @trazum/cli@1.8.0 on screen and npm view returning 404 are both true at once. Fetch registry.npmjs.org/@trazum%2fcli/1.8.0 to check the publish actually landed; it answers first.

prepublishOnly rebuilds and runs the tests before each of the four uploads, so a failure aborts the publish rather than reaching the registry.

Nothing extra is needed to make the packages public, and there is nothing to get wrong here. A scoped package is restricted by default, so all four manifests carry publishConfig.access: "public" and all four publish steps pass --access public. Belt and braces on purpose: the failure they prevent is not a loud one. On a free account a missing --access public fails the publish, which is fine; on a paid account it succeeds and uploads a package nobody outside the org can install — a release that looks completely normal, for an open-source project, and unpublishable after 72 hours.

publish.test.js asserts both of those, asserts that apps/web stays private: true so an application never reaches a registry, and derives the set of publishable workspaces from the root workspaces globs — so a workspace added later has to make the choice rather than inherit one.

If the org's default visibility is set to private, leave it: the per-package access setting is what decides, and it is already committed here.

2. Create the release environment — done#

Repository Settings → Environments → New environment, named exactly release. Twenty seconds, and no configuration needed inside it.

This one is already in place, and it has been exercised: a workflow_dispatch run went green through verify and npm pack --dry-run with all four publish steps correctly skipped. If the environment were missing or gated, the job would have sat in waiting before running anything, so a run that starts at all is the proof.

Do this rather than relying on the workflow to bring it into existence. It is also where a required reviewer goes if you ever want publishing to need a second pair of eyes — the environment gate runs before the job starts, so an approval there blocks the publish rather than interrupting it halfway.

Since 2026-11-19 the environment is stated in the repository, with a required reviewer. .github/environments.json holds release beside staging and production (the web app's), each with its reviewers, the branches and tags that may use it, and the names of its secrets, never their values. npm run environments compares GitHub with the file, and npm run environments -- apply --yes, run by an admin with their own gh, makes GitHub match it; the weekly Repository settings run compares and never writes, the way it does for the branch ruleset. release admits any branch on purpose: a dry run from a release pull request's branch is how the token is checked before the merge (below), and that run needs the environment too. With a reviewer on it, every run of the Publish to npm job waits for an approval, the dry runs included, and decide does not, so an ordinary merge to main queues behind nothing.

3. Configure this repository as a trusted publisher — the token is what publishes#

Read this first. On 2026-08-29 the merges of the 1.85.0 and 1.86.0 release PRs each published all four packages through the workflow, with provenance, and created the tag and the GitHub release with no human step. That makes the standing instruction below — assume tags will not publish and release by hand — wrong. Releases go through the workflow now. What still does not work is the trusted publisher itself, which is the next paragraph.

Which credential authenticated the upload: the token, not OIDC. That was left open at 1.85.0 and 1.86.0 answered it. Provenance is signed with the job's OIDC identity either way, so the signed attestation proves nothing about the auth — the Can this workflow authenticate to npm? step is the only thing that does, and on the 1.86.0 run it reported:

npm refused the OIDC token for @trazum/cli, @trazum/core, @trazum/mcp, @trazum/tokenizer-openai. Trusted publishing is not configured, or a claim does not match.

All four rejected, and all four published in the same job seconds later. The only other credential in that job is the granular token on the release environment, so the token is what is holding releases up and trusted publishing is still not working. Do not delete the fallback.

That also settles the thing 1.85.0 only narrowed. The token was made when three packages existed and @trazum/tokenizer-openai published anyway; the two explanations were OIDC or a wider scope than the instruction below describes. OIDC is now ruled out for that package by name, so the token's scope is wider than three packages. Worth knowing before trusting the instruction that says to list packages by name — and it does not remove the rule below about regenerating the token when a package is added, because a scope nobody has inspected is not a scope anybody can rely on.

Read from the run page's annotation, not from the step's job summary table. The summary is the better artefact and it is where the per-package verdicts are written, but the annotation is what a fetch of the run page actually returns — so that is where this quote comes from, and it is the same sentence the warning in checkAuth composes.

The history that follows is kept because it is what the fix has to survive, not because it is still the current state.

It failed on six real publish attempts across three versions: 1.8.0 because the packages did not exist yet, 1.9.0 because this had not been done, and v1.11.0 four times on 2026-08-19 — after the settings had been reported filled in. Every one of those releases that shipped went out by hand, and none has provenance as a result. 1.25.0 was the last of those: published from a clean clone of the tag, with the workflow's own preflight and verify run first by hand. Since then the token fallback (below) authenticates the workflow's own publishes, so a broken trusted publisher no longer forces a release onto a laptop.

The v1.11.0 failures settled one thing the 2026-08-13 attempt could not: the GitHub side is not the problem. The failing run prints the claims its token actually carried, and all of them matched what these instructions say to type — repository Davmunrey/Trazum, user Davmunrey, workflow release.yml, an environment present. The mismatch, whatever it is, lives on npm's side of the form: a configuration that did not save, saved onto the wrong package, or an account-level restriction this document does not know about. Until someone confirms the four package pages display a saved trusted publisher — not that the form accepts one — assume tags will not publish and release by hand (see Releasing by hand, below).

For each published package — @trazum/core, @trazum/cli, @trazum/mcp and @trazum/tokenizer-openai — on the package's npm settings page under Publishing access → Trusted publisher, enter exactly:

FieldValue
PublisherGitHub Actions
Organization or userDavmunrey
RepositoryTrazum
Workflow filenamerelease.yml
Environmentrelease

The environment field is not optional here. .github/workflows/release.yml declares environment: release, so the OIDC token GitHub mints carries that claim. If npm's configuration leaves the environment blank while the token asserts one, the claims do not match and the publish is rejected — with an error about the token rather than about the mismatch, which is a confusing hour if you do not know to look for it.

Check it without spending a version. Run the release workflow from the Actions tab — workflow_dispatch is dry-run only — and read the Can this workflow authenticate to npm? step. It asks npm's token-exchange endpoint the same question the upload steps ask it, once per package:

  configured            @trazum/cli
  rejected (404)        @trazum/core
  configured            @trazum/mcp
VerdictIt means
configuredEvery claim matched for that package.
rejected (401/403/404)Not configured for that package, or a claim does not match.
unknown (…)Something else answered. Tag if you like; the upload is still the authority.

Per package, and it is listed per package because that is how it goes wrong. The trusted publisher is a setting on three separate pages, so configuring two of them is the easiest mistake available — and the release publishes @trazum/core first, so the package that fails is not necessarily the one you last looked at.

On a refusal the step also prints the claims the token carries:

  The token this run carries:
    repository: Davmunrey/Trazum
    workflow_ref: Davmunrey/Trazum/.github/workflows/release.yml@refs/tags/v1.9.0
    environment: release

Compare each against what you typed into npm. environment: (absent) is the answer whenever it appears — the claim exists only when the job declares an environment, so a rule requiring release can never match a token without it.

Until this existed the only way to test a trusted publisher was to spend a version number on it, which is why 1.9.0 found out the expensive way.

Why it only reports, and when to disbelieve it. The exchange endpoint is npm's own plumbing rather than a documented API — how to call it was worked out by probing. So a rejected verdict has two possible causes and the check cannot tell them apart: the configuration is wrong, or the request is. If you have filled in all three settings pages and it still says rejected, believe the settings. Tag, and let the publish answer — a tag that fails publishes nothing, which is the same position as not having tagged.

That is also why it never gates. A gate built on a guess would one day block a release that would have worked, and that is worse than the failure it prevents. What it buys is a chance of knowing before you tag, not a verdict.

With a working trusted publisher there would be no token to paste and none to rotate, and that was the whole design: a long-lived NPM_TOKEN is the highest-value credential this project holds, and unlike every other secret a leak is not recoverable by rotation alone, because whatever was published under it stays published. That is not where this repository is. A token on the release environment is what uploads today, it expires, and The token fallback is the section to read: what holds it, how its expiry is known in advance, and what to do the day it lapses.

Cutting a release#

Most of it is one command (since 2.7.0):

git fetch --tags
node scripts/prepare-release.mjs 2.7.0 --dry-run   # what would change
node scripts/prepare-release.mjs 2.7.0             # change it

It moves every version that has to move in lockstep (the root, the six workspaces, each workspace's @trazum/core pin, the lockfile, packages/mcp/server.json, the plugin manifest and the MCP handshake), folds the files in changes/ under the version's heading in CHANGELOG.md and deletes them, moves the "on npm at" line at the top of RELEASES.md, writes the version's pricing dataset with its changelog and schema into apps/web/public/datasets/pricing/ from the catalogue as built (so run npm run build first; it refuses without one, and refuses to rewrite a version already published), and moves the Action pin in every document to the newest tag that exists. Every replacement is counted, and a count that differs from what a file is known to hold stops the run before anything is written, so a manifest added later is a refusal, not a version left behind. What it leaves for you is prose and prices, and it prints that list at the end. node scripts/prepare-release.mjs --pin-only moves the pin on its own.

The pin rule is what removes the follow-up PR: the docs-pin guard allows one release of lag, and the newest existing tag is always within one of the release being cut, so a pin moved in every release PR never falls out of the guard. Before this, the pin moved in a separate PR after each release, and when two releases went by without it, the guard held every open pull request red for three weeks.

Between releases, the weekly scheduled CI run calls node scripts/freshness.mjs, which fails when a provider's price review is past the 45-day line or the pin is two releases behind, and reports unreleased commits. On pull requests the same report goes to the job summary without failing, so a stale price review never blocks unrelated work.

The same weekly run reads the pricing pages themselves. node scripts/price-drift.mjs fetches Anthropic's and OpenAI's pricing pages in their Markdown form and compares every published figure with the catalogue: input, output, cache hits, both cache writes, batch, the long-prompt bands with their own cache writes, the rows OpenAI's specialised table splits into "(short context)" and "(long context)", Anthropic's fast mode, its data residency multiplier (the generation it starts at and the multiple, against every Claude row) and its web search fee (the dollars per 1,000 searches, against every Claude row). A changed price is drift, a model on the page that the catalogue lacks is missing, and a page whose tables are no longer where the script looks is unread; each fails the scheduled run, and on any other run the report is printed in the step's log without failing. Freshness says how long ago a provider was read; this says whether its page still agrees. It never writes a price: a finding is a reason to re-read the page and change packages/core/src/pricing.ts by hand, with the page quoted. A model left unpriced on purpose goes in DELIBERATELY_UNPRICED with its reason, and is reported as a note on every run. Google, DeepSeek, Moonshot, xAI and Mistral publish no page a script reads reliably, so they stay with freshness and a person, and with the cross-check below. --report never fails; --anthropic-file and --openai-file run it on saved copies.

For those providers, the weekly run also asks LiteLLM. node scripts/price-crosscheck.mjs reads LiteLLM's public model_prices_and_context_window.json (on raw.githubusercontent.com, a host trusted-hosts.test.js records as public data) and reports, per provider, a LiteLLM chat model whose id the catalogue does not price (missing), an input, output or cache-read rate that differs from the catalogue's (differs, with the catalogue's source page and the date it was read printed beside it), and a LiteLLM file with nothing for a provider (unread). A LiteLLM rate that equals the row's base, its rate in force or any of its tiers (DeepSeek's peak hours) counts as agreement and is a note naming the tier, and a retired row is not compared. Names are matched exactly, after taking off LiteLLM's own provider prefix, and never by resemblance: a catalogue model LiteLLM does not list is a note. LiteLLM is a signal, not a source. Nothing is copied, the script never writes a price or a file, and a finding means re-read the named page. On the schedule a differing rate or an unread file fails the run and a missing model does not, because LiteLLM lists retired, experimental and free models the catalogue leaves out on purpose; on any other run the report is printed without failing. A row a person re-read and found right goes in CONFIRMED_DIFFERENCES with the page and the date, and is reported as a note. --litellm-file runs it on a saved copy.

It also reads each provider's lifecycle. Anthropic's deprecations page has one table of every model's state, and each OpenAI model page opens with a Status: line when the model is deprecated or shut down and gives its context window. A model the provider marks deprecated, retired or shut down that the catalogue still recommends is a status finding, and a context window that differs from the page is drift; both fail the scheduled run. It exists because the catalogue recommended GPT-5, mini and nano for weeks after their pages said "Status: Deprecated". --anthropic-lifecycle-file and --openai-models-dir run it on saved copies.

The steps below are what the script does and what it leaves, in order.

Which number first. Since 1.50.1 the version carries the narrative: a chapter of the arc in progress is a patch, and the minor is spent only on the release that lands the arc's thesis. A pricing correction is also a patch, and the changelog entry is what tells the two apart. The full reasoning, including what it costs a reader pinning with a tilde, is in VERSIONING.md.

  1. Fold changes/ into CHANGELOG.md under the new version heading, and delete the files: prepare-release.mjs does it. Per CONTRIBUTING.md, a change that alters nothing installable still has an entry, so this is every change since the last release.

  2. Move the ROADMAP.md entry from Next to Released in HISTORY.md, and say what actually shipped rather than what was planned — they differ more often than they should.

  3. Bump the root and all six workspace manifests — packages/core, packages/cli, packages/mcp, packages/tokenizer-openai, apps/web and apps/vscode — plus every workspace's pinned @trazum/core dependency and the lockfile. The web app and editor extension remain private to npm. publish.test.js fails if they disagree, which is how the missing third one was found: this list said two for as long as the web app has depended on core, and every release that followed it left apps/web resolving a registry copy until the guard caught it. The Claude Code plugin manifest joins the lockstep: plugin/.claude-plugin/plugin.json carries the same version, held by claude-plugin.test.js — a plugin claiming one version over a CLI at another would describe commands that behave differently than its skill says. packages/mcp/server.json joins it, held by publish.test.js: the MCP registry hosts metadata rather than artefacts, so a stale version there advertises a server that is no longer the one on npm, and a stranger is the one who finds out.

  4. Move the action pin (the script does this) to the newest existing release commit, with its version in the trailing comment. security.test.js asks git what version that commit declares and fails if the label disagrees — so the pin can only be advanced once the commit it names exists, which is after the merge rather than in it.

  5. Nothing to drop any more. The "not published yet" notes are gone, and publish.test.js now asserts they stay gone rather than keying on a tag. That guard used the tag as a proxy for "on npm" and the manual first publish broke it: no tag was pushed, so the repository went on telling visitors nothing was installable while three packages sat on the registry. Publication does not reverse, so the assertion is one-directional now.

  6. Sweep every .md in the repository — the standing rule: a release is not cut until all the documentation says so. Three of them are enforced by publish.test.js (RELEASES.md must have the version's section, CHANGELOG.md its heading, HISTORY.md a mention), so verify fails a release prep that skipped them. The rest is a two-minute grep for what the tests cannot know is stale: Update the handshake version in packages/mcp/src/index.ts too. packages/mcp/test/server.test.js starts the real stdio server and checks its announced version against the package manifest; no runtime manifest access is added to the server.

    git grep -nE "<previous version>" -- '*.md' ':!CHANGELOG.md' ':!RELEASES.md'

    Anything that surfaces is either history (fine where it is) or a claim about the present (update it). The README's action pin is the known straggler: it can only advance to the release commit after that commit exists, so it moves in the next PR — security.test.js keeps the label honest either way.

  7. Check the prices, per provider. The one set of numbers in this product that cannot be derived from anything in the repository. PROVIDER_REVIEWED in packages/core/src/pricing.ts carries a date per provider; open the pricing page for any provider whose date is more than STALE_PRICING_DAYS old, compare every model this table prices, and move that provider's date only if you actually looked. The catalogue's headline date is derived as the oldest of the seven, so a partial review records itself honestly instead of overstating the rest.

    Two things pricing-review.test.js will catch and one it cannot. It catches a promotion that expires before the next review is due — a price change this table can see coming, and the reason Sonnet 5 nearly went out 50% too high — and it catches a review date in the future or a provider priced with no date at all. It cannot catch a provider quietly changing a price, which is what this step is.

    And ask whether the models still exist, which is a different question from whether the prices are right and was unasked for eighty releases:

    ANTHROPIC_API_KEY=... OPENAI_API_KEY=... npm run check:models

    It sends one real request per priced model and rewrites packages/core/test/fixtures/model-availability.json; commit what it writes. The first run found four ids the provider refuses outright, two of which that provider's own model list still returns. Any key you have is worth using and any you lack is recorded as unasked, so a partial run is honest rather than reassuring. A newly refused model is marked retired in the provider's own words and keeps its price, because the calls in somebody's log really happened; what it costs to move off it is a price, and comes off the provider's page under the step above or not at all.

  8. npm run verify, and read the exit code rather than the output. The agent suite includes the synthetic task stress probes documented in Contributing. Run npm run verify:packages to pack the public workspaces, install their tarballs together in a temporary directory and rerun the stress probes against that installation. CI and the release workflow both require this check before publication. This catches missing package files and workspace-only resolution. Then node scripts/adoption.mjs and paste the line it prints under the new heading in RELEASES.md. Three public counters — npm downloads of @trazum/cli over the last thirty days, GitHub stars, the MCP registry's latest version — read once and written beside the version, so the next plan starts from a figure the way docs/plan-2.4.md did. A counter the network would not give is printed as unavailable, never as zero; leave it that way rather than filling it in from memory.

  9. Merge. That is the release. The push to main triggers the workflow's decide job, which sees a manifest version the registry does not have and hands it to the release job: verify again, publish all four packages, create the v<version> tag on the merge commit, and publish the GitHub release from RELEASES.md with the bill of materials attached. Then a third job waits for npm to serve the new @trazum/mcp and updates the MCP registry listing, which was the last manual step until 1.80.2. No tag to type, no second step to remember.

    If the packages published and the tag or the release did not, push the tag yourself on the release commit, and the tag-triggered run skips the uploads (every version is already on npm) and creates the release:

    git tag v2.7.2 <release commit> && git push origin v2.7.2

    That is what 2.7.2 needed. A pull request that changed a comment in ci.yml merged while the Release run was publishing, and GitHub refuses the workflow's token any ref whose .github/workflows/ files differ from main's: GITHUB_TOKEN can never hold the workflows permission that would allow it. The failed step now says so and prints the command. Don't merge a pull request that touches .github/workflows/ while a Release run is in progress, and it does not happen. backfill-releases can create one missing release from its version, commit and latest inputs, but only while that commit's workflow files still match main's.

    When the tag is pushed days later, the run it starts may fail at Verify, and that is expected. A tag-triggered run checks out the tagged commit and verifies that tree before it creates the release, and some of this repository's tests fail by the calendar: a promotional price in its last 45 days, a provider review past its window. 2.7.2's tree has failed the first of those since 2026-11-16, so its tag gives a failed Release run and no release page. Nothing is published either way, because every version is already on npm. Finish it from the Actions tab: run backfill-releases with the version, the release commit and latest off. It finds the tag, skips the push it would be refused, and creates the release from RELEASES.md.

    Only the tag itself needs a person. The workflow's token is refused the ref for as long as the commit's workflow files differ from main's, and an agent session can neither push a tag nor create one through the GitHub tools it is given.

    A pushed tag still works as the manual override — for re-running a release whose publish failed, or releasing a commit that is not the newest merge:

    git tag v1.2.0 <commit> && git push origin v1.2.0

The workflow does the rest. It will refuse if the tag and the manifests disagree, and it runs the same verify a pull request runs before anything is published — a release gate that checks less than the pull-request gate lets through exactly what the tag was for.

Every GitHub release carries a bill of materials, from the first release after 2.7.7: trazum-v<version>.cdx.json, a CycloneDX 1.5 document listing each workspace and every third-party package any of them needs at run time, with its version, licence, purl, hash and tarball, and what depends on what. The release job writes it with scripts/sbom.mjs before anything is uploaded, and the script checks the document before writing it, so a bill that fails stops the release while nothing is published. It is read from the lockfile rather than made by npm sbom --omit dev, which on this tree leaves out seven packages a runtime dependency needs whenever a development tool needs them as well. test/sbom.test.mjs makes the same document on every pull request and requires it to hold everything npm ls --omit dev and npm sbom find. To make one yourself: node scripts/sbom.mjs trazum.cdx.json. A release created by hand or by backfill-releases has none: that workflow runs on main's tree, whose lockfile is not the old commit's, so a bill made there would describe the wrong release.

@trazum/core publishes first. The CLI and the MCP server depend on it at an exact version, so the other order leaves a window where installing the CLI fails on a dependency that does not exist yet.

A next prerelease#

A next is a build of what is coming, on npm, for whoever asks for it: npm install @trazum/cli@next. It never moves latest, which is what npm install @trazum/cli resolves, and it changes nothing on the record: no section in RELEASES.md, no heading in CHANGELOG.md, no pricing dataset, no GitHub release, no files, no MCP registry listing.

Its version is MAJOR.MINOR.PATCH-next.N, leading up to the release it previews: 3.1.0-next.1, then 3.1.0-next.2, then 3.1.0 itself through the ordinary release pull request. No other prerelease word is published. scripts/npm-channel.mjs decides the channel from the version and refuses anything else.

git fetch origin
git switch -c next/3.1.0-next.1 origin/main
npm run build
node scripts/prepare-release.mjs 3.1.0-next.1   # the versions only
npm run verify
git commit -as -m "3.1.0-next.1"
git tag v3.1.0-next.1
git push origin v3.1.0-next.1                   # the tag, not the branch

prepare-release.mjs with a -next.N version moves the versions that move in lockstep (the manifests, each @trazum/core pin, the lockfile, server.json, the MCP handshake, the plugin manifest and the Gemini extension) and nothing else. The documents keep naming the release on latest, and the tests that hold a document to "the current version" read that release on a next's tree (recordedVersion in npm-channel.mjs), so the tree passes the same verify a release does.

The tag starts the same Release workflow as a release, and goes through the same gate: the approval on release, the tag and the manifests agreeing, the whole verify, verify:packages, the version preflight. Then each package is uploaded with --tag next, and npm actually serves every package waits for next to name the version and fails at once if latest does. The GitHub release, the files and the listing are skipped.

Never merge the branch. Main's manifests name the release on latest, and a merge to main publishes whatever version main names. A prerelease version on main is refused by npm-channel.mjs before the job that holds the token starts, so a merged next fails loudly rather than publishing, and the fix is to revert the merge. The branch can be deleted once the tag is pushed: the tag holds the commit.

What holds it, in npm-channel.test.js: the table of versions and channels; a prerelease refused on main; a tag refused when it does not name the manifests' version, in both directions; every npm publish in release.yml passing --tag "$NPM_DIST_TAG" from decide; the wait for npm reading the same tag; and the GitHub release, the assets job and the mcp-registry job gated on latest.

If latest moved anyway, the job says so and names the command. Put latest back on the version RELEASES.md says is on npm, for each package:

npm dist-tag add @trazum/cli@<the version RELEASES.md names> latest

The files a release carries#

Besides the packages, a release carries trazum-vscode-<version>.vsix, trazum-mcp-<version>.mcpb, trazum-pricing-<version>.json and SHA256SUMS (#640, #780, #784). They are built by the assets job of release.yml, which needs the job that publishes, so it starts after npm actually serves every package and after the GitHub release exists; the publish order is not touched. The job holds contents: write and no npm credential, no id-token and no environment, because it runs two packagers fetched by npx at an exact version (scripts/release-assets.mjs names them). A manual run of the workflow makes the files and prints their sums and attaches nothing: do that from a release pull request's branch to know the packagers still work before the merge.

The pricing dataset is not made in that job, only checked there. It is the document prepare-release.mjs wrote into apps/web/public/datasets/pricing/ in the release pull request, which the site serves at the same version; release-assets.mjs builds it again from the core the job just built and copies the committed file only when the two are the same bytes, so the asset and the site's file are one file under one digest. A difference stops the job before anything is uploaded. It should not get that far: in the release pull request the document records the pricing.ts it was built from, so test/pricing-dataset.test.mjs compares it byte for byte with a fresh build and fails there, which is how a document written from a dist/ older than its source is caught before the merge. node scripts/pricing-dataset.mjs check asks the same question locally. The pricing dataset is the page for whoever consumes it.

If the job fails after the release exists, re-run it: the upload replaces what an earlier attempt left. The MCP registry listing waits for it and adds the bundle to what it publishes (below), so a failed attachment holds the listing back until it is re-run, and a version is never listed with a bundle that is not there.

The Homebrew formula is not part of the workflow. See "The Homebrew formula is a manual step" in RELEASES.md.

Listing on the MCP registry#

Separate from npm, and automated since 1.80.2. The official MCP registry hosts metadata: it records that a name maps to a package, and it verifies the claim by fetching that package from npm and reading mcpName out of its manifest. So the listing can only ever point at a version that is already published, which is what shapes the job.

release.yml has an mcp-registry job that runs after the npm publishes:

  1. scripts/mcp-registry-preflight.mjs asks npm for the exact version until it answers 200 and serves the right mcpName, up to five minutes.
  2. mcp-publisher is downloaded at a pinned version and checked against the checksum published for that tag.
  3. mcp-publisher login github-oidc exchanges the job's OIDC token for a registry token. No stored credential: the registry grants the namespace matching the token's repository_owner claim.
  4. mcp-publisher publish sends packages/mcp/server.json.
  5. The job then asks the registry what it now serves, and fails if it is not the version just sent.

Three deliberate choices, each paid for.

  • A separate job, not a step in the release job. It downloads a third-party binary and runs it, in a process that can mint a token for the whole io.github.<owner>/* namespace. Keeping it out of environment: release means that binary never shares a process with secrets.NPM_TOKEN or with contents: write. By the time it runs, npm and the GitHub release are done, so the worst it can do is fail, and a failed listing is recoverable by hand.
  • The publisher binary is pinned by version and checksum, not fetched from releases/latest/download as the upstream guide shows. Same rule as every action in this repository. The cost is a maintenance edge: when the registry rotates its OIDC audience, an old binary fails with invalid audience and the fix is to bump MCP_PUBLISHER_VERSION and MCP_PUBLISHER_SHA256 together, taking the checksum from registry_<version>_checksums.txt on that release. The job's failure note says exactly that, because the error names nothing that would lead you here.
  • The wait is a poll, not a sleep. npm serves a new version minutes after the publish returns, and chaining the two publishes without waiting produces a 400 that reads like a manifest bug and is a propagation race. A fixed sleep is either too short on a slow day or too long on every other day.

security.test.js holds all of it: the job exists, it is gated on the same decision the uploads are, it waits before it publishes, the binary is pinned and verified, and the job is not in the release environment.

Publishing the listing by hand#

Still the fallback when the job fails, and the only route for a listing that has to move without a release:

cd packages/mcp
mcp-publisher login github     # device flow, opens a code in the browser
mcp-publisher publish          # reads ./server.json

Four things that cost real attempts:

  • Do not run mcp-publisher init. It writes a server.json named after the directory, io.github.<user>/mcp, overwriting the one this repository keeps in the version lockstep. The committed file is the source of truth; if it is missing, the checkout is stale, not the tool.

  • The namespace is case-sensitive. GitHub authentication grants io.github.<login>/* with the login spelled exactly as GitHub spells it, so io.github.davmunrey and io.github.Davmunrey are two different namespaces and only one of them is yours. Getting this wrong returns a 403 that quotes both strings, and it cost 1.80.1: the corrected mcpName only counts once it is on npm, so the fix was a release. publish.test.js now derives the owner from server.json's repository URL and holds both files to it.

  • A 400 saying the package is "missing required mcpName field" means the version server.json advertises does not carry that field on npm, usually because the manifest was edited after the last publish, or because npm has not propagated yet. Check what the registry sees before blaming the login:

    curl -s https://registry.npmjs.org/@trazum%2fmcp/<version> | grep mcpName
  • A 401 saying the token is expired is exactly that. The device-flow credential is short-lived; mcp-publisher login github again and republish.

The token fallback#

The publish steps authenticate with OIDC when nothing else is configured, and with an environment-scoped npm token when one is — the fallback that keeps a merge from failing while npm's trusted publishing stays broken. Setting it up, once:

  1. On npm (as the account that owns @trazum): Access Tokens → Generate New Token → Granular Access Token. Permissions Read and write, scoped to only the @trazum packages this repository publishes, with an expiry — 90 days is a fine default. Do not create a classic automation token; granular is the one whose blast radius is those packages instead of the account.

    It must be allowed to publish without a one-time code. The account protects publishing with two-factor authentication, a workflow has no authenticator, and a token made without that allowance authenticates and is then refused the upload with EOTP. The first replacement token on 2026-11-17 was one of those. npm's token form has an option to bypass two-factor authentication for the token; that is the one.

    A package added after the token was made is not in its scope. A token listing packages by name cannot publish a fifth one and cannot create it, and the failure is the same E404 as a missing trusted publisher, on the package nobody was looking at. Whenever this repository starts publishing a new package, regenerate the token with it included and update the secret, in the same change that adds the package.

  2. On GitHub: Settings → Environments → release → Environment secrets → Add secret, name NPM_TOKEN, value the token. An environment secret on purpose: only jobs that enter the release environment can read it, which is exactly one job in one workflow.

  3. In this repository: write the expiry date npm showed into .github/release-credentials.json, as "expires": "YYYY-MM-DD", in a pull request of its own. The date is not a secret and the token never goes there. It is the only way anything here learns when the token lapses: npm shows the date when the token is made and this repository cannot ask for it afterwards.

What the trade costs, honestly: a long-lived credential now exists, and a leak of it is not recoverable by rotation alone — whatever was published under it stays published. What it does not cost is provenance: the attestation is signed with the job's OIDC identity, which is independent of how the upload authenticates, so releases through the workflow carry provenance with either auth. security.test.js pins the containment: only release.yml may reference the secret, only in the one shape, only in the four upload steps and the two that ask npm about it, and token material committed anywhere fails the build.

When trusted publishing finally works, delete the secret and set "expires" back to null; the same workflow reverts to pure OIDC with no edit.

When the token expires#

npm stopped accepting it on the day of 2.7.10. The release pull request merged on 2026-11-17, the job verified, packed and stressed the release for five minutes, and the first upload answered E404 Not Found - PUT, under a note that said a job holding the token had failed for some other reason. Nothing was half-published, and main named a version npm did not have. npm's answer does not say whether a token expired or was revoked; the fix is the same. Three things now stand between a lapsing token and that state:

  • Two weeks ahead. node scripts/freshness.mjs reads the recorded date and calls it overdue from fourteen days before, which turns the weekly scheduled CI run red on main, where GitHub notifies the owner. A date nobody recorded is printed as a note that says so, on every run.

  • Before the release is prepared. node scripts/prepare-release.mjs refuses to prepare a release once the recorded date has come, and lists a near or unrecorded date among what is still yours. A dry run says what a real run would refuse.

  • At the start of the job. Is the stored npm token still alive? asks npm whoami with the token before verify, and on a manual dry run too, so a dry run from a release pull request's branch answers before the merge. A refusal is an error on the run page and in the job summary, with the steps below, and the failure note at the end of the job asks again and ends on the answer.

    It reports and does not fail. Measured against the live registry on 2026-11-17: a token npm does not know is answered 401, and so was the token stored on the release environment, 42 minutes after it failed 2.7.10's upload (the dry run). The token that replaced it was answered 200 the same afternoon. What keeps the step a report is the trusted publisher: if npm ever accepts it, an upload needs no token, and a gate on a dead one would stop a release that would have gone out.

    An accepted token is not a promise, and that was measured the same day too. Thirteen minutes after that 200, the first upload with the new token answered EOTP, "This operation requires a one-time password from your authenticator": the account asks for a code to publish and the token had not been made to publish without one. whoami cannot be asked that, nor whether the token may write to each package.

Renewing it, which only the owner of the npm account can do:

  1. Generate a new granular token as in step 1 above, with all the @trazum packages in its scope.
  2. Replace the NPM_TOKEN secret on the release environment.
  3. Record the new expiry date in .github/release-credentials.json.

If a release pull request has already merged, do not merge anything else first. Re-run the failed jobs of that release's run: it is pinned to the release commit, so it uploads exactly the tree its notes describe. Every push to main starts a publish attempt for whatever version the manifests name, so a merge between the failure and the re-run is tried again with the dead token, and re-running that later attempt once the token is renewed would upload the later tree under the release's number and notes.

Releasing by hand#

The last resort — for when the workflow itself is broken, not just npm's authentication (the token fallback above covers that without leaving GitHub). It is the exact procedure 1.25.0 used, before the fallback existed. The cost is stated first because it is the only one: a manual publish carries no provenance attestation — nobody can verify the tarball was built from this repository at this commit. Users notice nothing.

Publish from a clean clone, never from a working tree — a local checkout can be behind, dirty, or missing files, and what npm publish packs is whatever is on disk:

cd /tmp && rm -rf trazum-release
git clone --depth 1 https://github.com/Davmunrey/Trazum.git trazum-release
cd trazum-release
node -p "require('./package.json').version"        # read it: this is what ships
npm ci
node scripts/npm-publish-preflight.mjs versions    # aborts if any number is spent
npm run verify
npm whoami || npm login                            # and `npm logout` when done
npm publish -w @trazum/core --access public        # core first: the others pin it exactly
npm publish -w @trazum/cli  --access public
npm publish -w @trazum/mcp  --access public

Then push the tag by hand (this is the one path where the tag comes second), and let the workflow create the GitHub release — its preflight sees the versions on the registry and skips the uploads. Two reminders from doing this for real: npm view 404s for several minutes after a successful publish (fetch registry.npmjs.org/@trazum%2fcore/<version> to check instead), and npm logout afterwards revokes the session token, which is the closest a manual publish gets to not holding a credential.

Checking a release without publishing one#

Run the workflow from the Actions tab. workflow_dispatch is dry-run only — every publish step is gated on a tag, so a manual run does the install, the verify, the npm pack --dry-run and the bill of materials, and stops. A publish reachable without a tag would be a release with no version to check against.

A dry run also says which channel a tag of that tree would publish to, latest or next, in Which npm channel? and on its last line.

Two of its first steps are about credentials and are worth a dry run on their own: Can this workflow authenticate to npm? (the trusted publisher) and Is the stored npm token still alive? (the token that actually uploads). Run it from a release pull request's branch before merging and the second one says whether the merge can publish. The run page shows it as an annotation, and the last line of the job's own script repeats it as one word (accepted, refused, absent or unknown), because the end of the log is what the API returns and the step itself is forty thousand lines above it.

If something goes wrong#

  • The tag was wrong — nothing was published, because the version check runs before verify. Delete the tag, fix it, tag again.

  • E404 Not Found - PUT — an authentication failure, not a missing package. npm reports a write you are not authorised for as "not found", which is why this cost an hour at the first publish and reappeared at 1.9.0 and at 2.7.10. The failed job ends on how npm answers each credential. If it says npm refuses the stored token, the token has expired or been revoked: go to When the token expires. If it says npm accepts the token, the package that failed is outside the token's scope: regenerate it with every package included. Step 3 is for the trusted publisher, which has not authenticated an upload yet.

  • EOTP, "This operation requires a one-time password" — the token authenticates and may not publish without a two-factor code, which a workflow cannot supply. Generate it again with the option that lets the token bypass two-factor authentication (The token fallback, step 1) and re-run the failed job. Nothing was uploaded.

  • @trazum/core published and @trazum/cli or @trazum/mcp failed — the core version is spent. Bump to the next patch across all manifests and release again rather than trying to reuse the number; npm will not let you, and a --force that worked would be worse.

    This is the shape the preflight exists to prevent: No version may already be on the registry checks all three before the first upload, so a re-tag of a half-published release aborts instead of spending another number. It cannot help with a failure that happens between two uploads — nothing can, short of a transaction npm does not offer — but that is now the only way to get here.

  • Within 72 hours, badly wrong — npm unpublish @trazum/core@1.2.0. After that the version is permanent and the answer is a new one with a changelog entry saying what the bad one did.