11# Releasing
22
3- How ` tskm ` , ` @tskm/compiler ` , and ` @tskm/vite ` are published, and the one-time setup
3+ How ` @ tskm/core ` , ` @tskm/compiler ` , and ` @tskm/vite ` are published, and the one-time setup
44required before the automated pipeline can run.
55
66Publishing is ** CI-only** and ** tokenless** : GitHub Actions publishes via npm OIDC
@@ -23,30 +23,55 @@ Do these once, in order, before the first automated release.
2323
2424### 2. Own the ` @tskm ` scope
2525- Create / confirm ownership of the ` @tskm ` scope (org or user scope) on npmjs.com.
26- ` @tskm/compiler ` and ` @tskm/vite ` cannot be published otherwise.
26+ ` @tskm/core ` , ` @tskm/ compiler` , and ` @tskm/vite ` cannot be published otherwise.
2727
2828### 3. Bootstrap publish (first version only)
2929The npm Trusted Publisher UI requires a package to already exist before you can attach a
30- trusted publisher to it. So publish ` 0.0.1 ` of each package ** once** , manually, from your
31- machine. This first version has ** no provenance** (provenance needs the CI OIDC context)
32- — that is expected and unavoidable.
30+ trusted publisher to it. So publish each package ** once** , manually, from your machine.
31+ These bootstrap versions have ** no provenance** (provenance needs the CI OIDC context) —
32+ that is expected and unavoidable.
33+
34+ ` publishConfig.provenance: true ` stays in every ` package.json ` as a ** fail-closed
35+ guardrail** : a non-CI publish refuses to run. It is ** not** overridable by an environment
36+ variable — ` NPM_CONFIG_PROVENANCE=false ` does ** not** turn provenance off, because
37+ ` publishConfig ` wins over env. So the bootstrap temporarily * removes* the line instead of
38+ trying to override it, then restores it.
3339
3440``` sh
3541npm login # issues a short-lived (~2h) session, prompts for your passkey
3642bun install --frozen-lockfile --ignore-scripts
3743bun run build
38- # Reuses scripts/publish.ts: ordered (compiler → tskm → vite), rewrites @tskm/vite's
39- # workspace:* dependency, and is idempotent. NPM_CONFIG_PROVENANCE=false is REQUIRED —
40- # publishConfig.provenance is true, which would otherwise fail outside CI.
41- NPM_CONFIG_PROVENANCE=false bun run release
44+
45+ # Temporarily drop the guardrail (env vars can't override publishConfig): delete the
46+ # `"provenance": true` line from each packages/*/package.json. Do NOT commit this.
47+
48+ # scripts/publish.ts publishes in dependency order (@tskm/compiler → @tskm/core →
49+ # @tskm/vite), rewrites @tskm/vite's workspace:* dependency to a concrete range, and is
50+ # idempotent (versions already on the registry are skipped). NPM_CONFIG_OTP is required
51+ # because the account is 2FA "auth-and-writes"; the env propagates to all three
52+ # `npm publish` calls. The TOTP window is ~30s — if a later publish fails with EOTP, just
53+ # re-run with a fresh code and the already-published packages are skipped.
54+ NPM_CONFIG_OTP=< 6-digit> bun run release
55+
56+ # Restore the guardrail (leaves main untouched):
57+ git checkout -- packages/* /package.json
4258```
4359
60+ > Right after a publish, ` npm view <pkg> ` may return E404 for up to a few minutes
61+ > (registry propagation lag) even though the publish succeeded — do not mistake it for a
62+ > failure. The authoritative idempotent check is ` bun run release ` itself, which reports
63+ > already-published versions as ` skip (already on registry) ` .
64+
65+ > An earlier ` @tskm/compiler@0.0.1 ` was published before the runtime was renamed to
66+ > ` @tskm/core ` (it targets the never-published unscoped ` tskm ` ); it is ** deprecated** . The
67+ > current compiler bootstrap is ` @tskm/compiler@0.0.2 ` .
68+
4469### 4. Install the pkg.pr.new GitHub App (for preview releases)
4570- Install < https://github.com/apps/pkg-pr-new > and scope it to ** only** ` ushironoko/tskm ` .
4671 Without it, ` preview.yml ` cannot publish preview packages.
4772
4873### 5. Configure the Trusted Publisher on npmjs.com (per package)
49- For ** each** of ` tskm ` , ` @tskm/compiler ` , ` @tskm/vite ` :
74+ For ** each** of ` @ tskm/core ` , ` @tskm/compiler ` , ` @tskm/vite ` :
5075- Package → Settings → ** Trusted Publisher** → GitHub Actions
5176- Organization/owner: ` ushironoko `
5277- Repository: ` tskm `
@@ -63,7 +88,8 @@ For **each** of `tskm`, `@tskm/compiler`, `@tskm/vite`:
6388### 7. After the first successful OIDC release
6489- For each package, enable ** "Require two-factor authentication and disallow tokens"**
6590 (trusted publishing keeps working under this setting).
66- - Revoke any granular token used for the bootstrap publish.
91+ - The bootstrap publishes with a one-time OTP, not a long-lived token, so there is nothing
92+ to revoke — just confirm no granular/classic token was created for it.
6793
6894---
6995
@@ -83,13 +109,15 @@ For **each** of `tskm`, `@tskm/compiler`, `@tskm/vite`:
83109 - the ` version ` job's gate detects an unpublished version (` should_publish=true ` );
84110 - the ` publish ` job starts and ** waits for ` release ` Environment approval** ;
85111 - once approved, it builds, runs ` publint ` / ` attw ` / the clean-room install smoke
86- test, then publishes ` compiler → tskm → vite ` over OIDC with provenance.
112+ test, then publishes ` @tskm/ compiler → @ tskm/core → @tskm/ vite` over OIDC with provenance.
87113
881144 . ** Verify** the green provenance badge on npmjs.com and:
89115 ``` sh
90116 npm audit signatures
91117 ```
92- Expected provenance: ** ` 0.0.1 ` = none** (bootstrap), ** ` 0.0.2 ` + = present** .
118+ Expected provenance: the manually bootstrapped versions — ` @tskm/core@0.0.1 ` ,
119+ ` @tskm/compiler@0.0.2 ` , ` @tskm/vite@0.0.1 ` — all have ** none** . The first CI OIDC
120+ release of each package (its next version) is the first to carry ** provenance** .
93121
94122## Preview releases
95123
0 commit comments