Skip to content

Commit 807f7ff

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 807f7ff

5 files changed

Lines changed: 1607 additions & 23 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
---
2+
props:
3+
package:
4+
type: string
5+
pattern: "^packages/[a-z0-9][a-z0-9._-]*$"
6+
description: Workspace package to reserve on npm, e.g. packages/workflow
7+
---
8+
19
# executable.md
210

311
This is the development guide for the executable.md repository. It covers
@@ -55,6 +63,7 @@ README.md#Build
5563
README.md#Test
5664
README.md#Test/Focused
5765
README.md#Test/Complete
66+
README.md#Bootstrap
5867
```
5968

6069
Preparation is common to all of them, so the block above is the document's own
@@ -183,3 +192,32 @@ Success provides delivery verification: the whole battery passed, and the
183192
worktree it ran in is unchanged — `verify` compares tracked files afterwards and
184193
fails if any command moved one, so a green result is also evidence that the
185194
battery left the repository exactly as it found it.
195+
196+
## Bootstrap
197+
198+
Adding a package to `packages/*` needs one manual step before CI can release it.
199+
A tagged release publishes to npm with OIDC, and OIDC can only publish a package
200+
that already exists — so the name is reserved by hand, once, per package.
201+
202+
```bash
203+
npm login
204+
deno task xmd run README.md#Bootstrap --props-package packages/<name>
205+
```
206+
207+
Run it **without `--journal` and without `--verbose`**. It asks you for a
208+
one-time code, and either flag would persist that code.
209+
210+
<If condition={props.package !== undefined}>
211+
<Scripts.BootstrapNpmPackage package={props.package} />
212+
</If>
213+
214+
<If condition={props.package === undefined}>
215+
216+
No package was named, so nothing was reserved. Name one with `--props-package`
217+
to run the reservation; it explains each step as it takes it, previews the
218+
placeholder before publishing anything, and refuses rather than touch a package
219+
that already carries versions.
220+
[`specs/release-process-spec.md`](specs/release-process-spec.md) §6 carries the
221+
whole procedure, including the JSR half.
222+
223+
</If>

0 commit comments

Comments
 (0)