Skip to content

Commit 4b925b3

Browse files
committed
✨ Bootstrap an npm package as a real xmd run
Closes #276, and answers the bootstrap cycle #152 recorded. Before CI can publish a package to npm, someone has to publish it once by hand. CI authenticates with OIDC and never holds a secret, but npm only lets you configure a trusted publisher on a package that already exists — so the first version cannot come from CI. It cannot be the real package either: one that declares `workspace:*` dependencies resolves its siblings from the registry at build time, and those siblings cannot be published until this record exists. `scripts/bootstrap-npm-package.md` publishes an empty placeholder under the `bootstrap` dist-tag and installs the trusted publisher. The one-time password arrives through `<Elicit>` at the point of use, so the npm commands are non-interactive; the target package arrives as a root prop. The document is prose that executes. Each step explains why it is necessary, performs it, and shows the result: `npm whoami` and `npm --version` become two reported lines, `<File>` and `<Parse>` read the npm and JSR names and confirm they match, `<File>` writes the placeholder into a wrapping `<TempDir>`, and every registry answer becomes a binding that a TypeScript comparison classifies and `<If>` acts on. Terms of art are explained where they first appear — OIDC, one-time password, `npm trust`, dist-tag, JSR — because whoever runs this does so once and should not have to already know them. The machinery stays out of the report: captures, classifiers and schemas render nothing, and the two writes run `silent` so the document says what it did rather than npm saying it. The operational sequence is one `<Output>` region, so a failing step ends the run and nothing after it begins, while everything already rendered still reaches the stream. Asking the registry first is what makes the document safe to run twice. Each half is skipped separately when it is already done, and a package with real versions, an unexpected `bootstrap` tag, or a different trusted publisher is a live package — treating it as a fresh one could break it for everyone installing it, so any of those stops the run before a code is requested. npm holds one trusted publisher per package and refuses a second, so a foreign one is reported with the exact `npm trust revoke --id` command rather than replaced. A code is requested only when something will actually be written. The spec records the procedure, the operator command, what is checked, the rerun behaviour and the refusals. It keeps npm's documented ordering without claiming the registry enforces it: #276 observed trust being accepted for a package the registry still 404'd, and nothing here relies on that. It also drops two claims that are no longer true — `packages/web` carries a public identity and publish jobs, and effection is 4.1.0 rather than a prerelease needing `--legacy-peer-deps`.
1 parent 6a777dd commit 4b925b3

4 files changed

Lines changed: 1522 additions & 23 deletions

File tree

‎README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,22 @@ deno task test # the full Deno suite
7777
deno task verify # the whole applicable battery, concurrently
7878
```
7979

80+
Adding a package to `packages/*` needs one manual step before CI can release it.
81+
A tagged release publishes to npm with OIDC, and OIDC can only publish a package
82+
that already exists — so the name is reserved by hand, once, per package:
83+
84+
```sh
85+
npm login
86+
deno task xmd run scripts/bootstrap-npm-package.md --props-package packages/<name>
87+
```
88+
89+
Run it **without `--journal` and without `--verbose`**. It asks you for a
90+
one-time code, and either flag would persist that code. The document explains
91+
each step as it takes it, previews the placeholder before publishing anything,
92+
and refuses rather than touch a package that already carries versions.
93+
[`specs/release-process-spec.md`](specs/release-process-spec.md) §6 carries the
94+
whole procedure, including the JSR half.
95+
8096
## Setup
8197

8298
Run this after changing a dependency, or whenever you want the checkout restored

0 commit comments

Comments
 (0)