@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +312 -3
  3. package/README.vi.md +281 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13806 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +278 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify-endpoint.js +170 -0
  63. package/tools/lib/notify.js +188 -0
  64. package/tools/lib/npm-publish-guard.js +242 -0
  65. package/tools/lib/orphan-worktree.js +127 -0
  66. package/tools/lib/owner-branch.js +182 -0
  67. package/tools/lib/place.js +782 -0
  68. package/tools/lib/ports.js +167 -0
  69. package/tools/lib/procs.js +185 -0
  70. package/tools/lib/readiness.js +240 -0
  71. package/tools/lib/records.js +185 -0
  72. package/tools/lib/refs-brake.js +95 -0
  73. package/tools/lib/release-channel.js +99 -0
  74. package/tools/lib/release-cut.js +822 -0
  75. package/tools/lib/release-finalize.js +521 -0
  76. package/tools/lib/release-policy.js +358 -0
  77. package/tools/lib/release-tag.js +225 -0
  78. package/tools/lib/ship-batch.js +277 -0
  79. package/tools/lib/ship-roles.js +71 -0
  80. package/tools/lib/ship-target-sync.js +181 -0
  81. package/tools/lib/shipguard.js +317 -0
  82. package/tools/lib/shipped-branch.js +56 -0
  83. package/tools/lib/solo.js +213 -0
  84. package/tools/lib/squash.js +515 -0
  85. package/tools/lib/stale-base.js +70 -0
  86. package/tools/lib/stamp.js +740 -0
  87. package/tools/lib/state.js +262 -0
  88. package/tools/lib/teardown.js +83 -0
  89. package/tools/lib/trust-humans.js +104 -0
  90. package/tools/lib/util.js +98 -0
  91. package/tools/lib/wake.js +188 -0
  92. package/tools/lib/workflow-triggers.js +273 -0
  93. package/tools/lib/writes-authority.js +237 -0
  94. package/tools/lib/yaml.js +101 -0
  95. package/bin/cli.js +0 -3
@@ -0,0 +1,475 @@
1
+ # Release (auto) — TEMPLATE. Copy me into your repo at .github/workflows/release-auto.yml.
2
+ #
3
+ # This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
4
+ # Edit it freely; nothing calls it remotely and nothing will update it for you.
5
+ #
6
+ # EDIT POINTS are marked `# EDIT:` — walk them once after copying.
7
+ #
8
+ # WHAT IT DOES. It runs CONVENTIONS.md §6's release rung so nobody has to remember to:
9
+ #
10
+ # trigger step
11
+ # ---------------------------------------- ------------------------------------------------
12
+ # a daily schedule, first colab promote --auto → dev → main, then
13
+ # (`trunk: dev` + `deploy: tag` + CI dispatched on
14
+ # `promotion: main-loop` only; a no-op main (#440)
15
+ # everywhere else)
16
+ # your CI workflow finished green on main colab release cut --auto → vX.Y.Z-rc.N
17
+ # (on `trunk: dev`: the promotion's push), (#443: the newest candidate always names main's
18
+ # and the daily schedule head; a head already carrying one is a no-op)
19
+ # a daily schedule colab release finalize --auto → vX.Y.Z (or a
20
+ # hand-off where
21
+ # the final is a
22
+ # human's)
23
+ # workflow_dispatch all three, in that order
24
+ # any of the above tagged something, and npm publish (job `npm`, #433) — candidates to
25
+ # project.yml declares release.npm dist-tag `next`, finals to `latest`; see the
26
+ # comment above that job
27
+ #
28
+ # Every decision — whether a candidate is owed, which bump, whether the test period
29
+ # elapsed clean, whether the final is automatic on this repo at all — is the colab CLI's,
30
+ # read from .github/project.yml's release rung. This file only schedules it and publishes
31
+ # what it tagged. Where the rung leaves candidates off, every run is a recorded refusal.
32
+ #
33
+ # WHERE IT FITS. `colab release cut` tags origin/main — release tags land on `main` on every
34
+ # trunk shape — so the same file, unchanged, fits two kinds of repo:
35
+ #
36
+ # `trunk: main` + `deploy: tag | none` every green CI run on main may cut a candidate.
37
+ # `trunk: dev` + `deploy: tag` main only moves when dev is promoted into main (by
38
+ # a human, or unattended below), so the green CI run
39
+ # on that promotion is the trigger. The CLI reads `trunk:` and cuts only when
40
+ # main's head IS a promotion of dev (a --no-ff merge
41
+ # whose later parent is on dev, or a fast-forward);
42
+ # any other head — a hotfix straight on main — is a
43
+ # no-op, carried by the next promotion or cut by hand
44
+ # with `colab release cut`. The bump reads the
45
+ # promoted dev commits (never the merge subject, never
46
+ # dev commits not yet promoted), and the manifest
47
+ # version is read on main's promotion commit, so a
48
+ # version bump must reach main through the promotion.
49
+ # Finalize only posts the one-click hand-off: a final
50
+ # is a human act wherever a tag deploys. Needs a
51
+ # HANDBOOK_REF that carries #429; older CLIs cut on
52
+ # any green main head.
53
+ #
54
+ # UNATTENDED PROMOTION (#440). Who may promote is project.yml's `promotion:`, read by the CLI. Where
55
+ # it says `main-loop` — and only on `deploy: tag`, where promotion verifies and deploys nothing —
56
+ # the daily run first runs `colab promote --auto`: when dev's head CI is green and dev is ahead of
57
+ # main it merges dev → main (`--no-ff`) and pushes main, then dispatches your CI workflow on main.
58
+ # The dispatch is needed because a push made with GITHUB_TOKEN triggers no workflow; a
59
+ # workflow_dispatch is the documented exception. That CI run's green completion fires this
60
+ # workflow again, and the cut step cuts the candidate exactly as it does for a human promotion. So
61
+ # your CI workflow must accept `workflow_dispatch:` (the handbook's CI templates do), and main
62
+ # must accept a push from this job's token (a ruleset on main that blocks it turns every promotion
63
+ # into a recorded refusal). Everywhere else — `promotion: human` or absent, `deploy: push-main`,
64
+ # `manual`, `none`, `trunk: main` — the step is a no-op and nothing promotes. The final tag stays
65
+ # the human click. Needs a HANDBOOK_REF that carries #440; an older CLI gives no verdict, which is
66
+ # a warning, never a failed run.
67
+ #
68
+ # Your CI workflow must run on pushes to main for the trigger to fire — the handbook's CI
69
+ # templates run on every branch. It does not fit `exposure: live` (no tags: the promotion
70
+ # itself is the deploy).
71
+ #
72
+ # PUBLISHING HAPPENS IN THIS RUN — deliberately. A tag pushed with GITHUB_TOKEN does NOT
73
+ # trigger other workflows (GitHub suppresses it to prevent loops). So "cut the tag here and
74
+ # let release.yml fire on the tag push" silently does nothing: the tag exists, no Release
75
+ # is ever published. The last step below publishes whatever this run tagged, itself.
76
+ # The same suppression means a deploy workflow on `v*.*.*` does not fire for a tag this
77
+ # workflow pushes either — on a `deploy: tag` repo the final is a human act anyway, and
78
+ # finalize --auto only posts the command for it.
79
+ #
80
+ # IT READS TAGS AND CREATES TAGS. IT NEVER WRITES A COMMIT. No step here commits; the refs
81
+ # pushed are the tags `colab release cut` / `colab release finalize` create (annotated, their
82
+ # checks recorded in the tag message) and — only on a repo granting unattended promotion — the
83
+ # promotion merge `colab promote --auto` pushes to main. The npm job never moves git either. `-rc.N` tags are published as
84
+ # pre-releases, never "Latest". The audit's pre-release deploy-trigger check (#332) still
85
+ # applies to your deploy workflows exactly as before.
86
+ #
87
+ # A REFUSAL IS NOT A FAILURE. `colab release cut --auto` refusing (nothing owed, a check
88
+ # failed) is the ordinary output of most runs; it is printed to the run summary as a
89
+ # warning and the job stays green, so a refusal never paints main red for `colab ship`.
90
+ # Only a run that produced no verdict at all (a crash, gh unusable, bad flags) fails.
91
+ #
92
+ # THE CLI IGNORES THIS WORKFLOW'S OWN RUNS when it reads CI at a commit (GITHUB_WORKFLOW,
93
+ # #425) — otherwise its own in-progress run would read as "CI not finished" forever. So
94
+ # never fold these steps into the workflow that runs your test suite: that suite's runs
95
+ # would be ignored with it.
96
+ #
97
+ # NO TOOLCHAIN RESOLUTION. It runs the colab CLI (zero-dependency Node) on the runner's
98
+ # preinstalled Node and gh. Nothing of your project is built here — except in the opt-in
99
+ # `npm` job, which sets up its own Node for npm's trusted publishing (EDIT point there for
100
+ # a package that needs a build). The npm job needs a HANDBOOK_REF that carries #433; an
101
+ # older CLI gives no npm verdict and nothing is published to npm.
102
+
103
+ name: Release (auto)
104
+
105
+ on:
106
+ workflow_run:
107
+ # EDIT: the `name:` of the workflow that runs your test suite on main.
108
+ workflows: ["CI"]
109
+ types: [completed]
110
+ branches: [main]
111
+ schedule:
112
+ # EDIT: when the daily finalize runs (UTC). Off the hour on purpose — the top of the
113
+ # hour is when scheduled runs queue longest.
114
+ - cron: "17 3 * * *"
115
+ workflow_dispatch:
116
+
117
+ # One release run at a time; a second one waits rather than racing the first for the same
118
+ # candidate number. Never cancelled mid-run: a half-finished run may have pushed a tag
119
+ # without publishing it.
120
+ concurrency:
121
+ group: release-auto
122
+ cancel-in-progress: false
123
+
124
+ permissions: {}
125
+
126
+ env:
127
+ # EDIT: the handbook ref whose colab CLI makes the release decisions — a CHANNEL or a
128
+ # version tag (CONVENTIONS.md §6, *Release channels*, #445):
129
+ # stable the newest final release — the default; it moves forward as finals are cut,
130
+ # and that release's notes say what changed
131
+ # next the newest candidate (vX.Y.Z-rc.N) — the fast channel
132
+ # vX.Y.Z an exact version tag — frozen; moving it is a deliberate act, like re-copying
133
+ # a template
134
+ HANDBOOK_REF: "stable"
135
+ HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
136
+
137
+ jobs:
138
+ release:
139
+ name: Cut, finalize, publish
140
+ # A red CI run on main is not a candidate; skip rather than refuse.
141
+ if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
142
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
143
+ permissions:
144
+ contents: write # push the tags (and, with promotion: main-loop, the promotion), publish the GitHub Release
145
+ issues: write # finalize opens / comments on / closes the "release: vX.Y.Z" tracking issue
146
+ actions: write # read the runs at a commit (ci-green, full-suite, trunk-green); dispatch CI after a promotion
147
+ # What the npm job below needs (#433) — empty / publish=false unless this run tagged something
148
+ # AND .github/project.yml opts in with release.npm.
149
+ outputs:
150
+ tags: ${{ steps.npm-target.outputs.tags }}
151
+ npm: ${{ steps.npm-target.outputs.publish }}
152
+ npm-dir: ${{ steps.npm-target.outputs.dir }}
153
+ npm-gate: ${{ steps.npm-target.outputs.gate }}
154
+ npm-package: ${{ steps.npm-target.outputs.package }}
155
+ env:
156
+ GH_TOKEN: ${{ github.token }}
157
+ steps:
158
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
159
+ with:
160
+ ref: main
161
+ # Full history plus tags: versions, bumps and "previous final" are all read from
162
+ # git, and the on-trunk check refuses a shallow checkout outright.
163
+ fetch-depth: 0
164
+ # Left on deliberately: `colab release cut` / `finalize` push their tag over the
165
+ # checkout's origin. The token is this job's, scoped by `permissions:` above.
166
+ persist-credentials: true
167
+
168
+ - name: Fetch the colab CLI
169
+ run: |
170
+ set -euo pipefail
171
+ git clone --quiet --depth 1 --branch "$HANDBOOK_REF" "$HANDBOOK_REPO" "$RUNNER_TEMP/colab-handbook"
172
+ echo "COLAB=$RUNNER_TEMP/colab-handbook/tools/colab" >> "$GITHUB_ENV"
173
+ # The tags are annotated; git needs an identity to write one.
174
+ git config user.name "github-actions[bot]"
175
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
176
+
177
+ # #440: where project.yml grants `promotion: main-loop` on `deploy: tag`, promote a green dev
178
+ # into main, then dispatch CI there — its green run fires this workflow again to cut the
179
+ # candidate. Everywhere else the CLI answers a no-op. A refusal (dev CI not green, a push
180
+ # rejected) is a warning; the job stays green.
181
+ - name: Promote unattended (colab promote --auto)
182
+ id: promote
183
+ if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
184
+ env:
185
+ # EDIT: your test-suite workflow — the same one `workflow_run.workflows` names above.
186
+ CI_WORKFLOW: "CI"
187
+ run: |
188
+ set -uo pipefail
189
+ OUT="$RUNNER_TEMP/promote.json"
190
+ rc=0
191
+ node "$COLAB" promote --auto --json > "$OUT" || rc=$?
192
+ if ! jq -e 'has("promoted")' "$OUT" > /dev/null 2>&1; then
193
+ echo "::warning::colab promote --auto gave no verdict (exit $rc; a HANDBOOK_REF older than #440?) — nothing was promoted"
194
+ exit 0
195
+ fi
196
+ {
197
+ echo "### colab promote --auto"
198
+ echo
199
+ jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
200
+ echo
201
+ } >> "$GITHUB_STEP_SUMMARY"
202
+ if [ "$(jq -r '.promoted' "$OUT")" = "true" ]; then
203
+ echo "promoted=true" >> "$GITHUB_OUTPUT"
204
+ echo "Promoted to main @ $(jq -r '.sha' "$OUT")" | tee -a "$GITHUB_STEP_SUMMARY"
205
+ if gh workflow run "$CI_WORKFLOW" --ref main; then
206
+ echo "Dispatched $CI_WORKFLOW on main — its green run cuts the candidate." | tee -a "$GITHUB_STEP_SUMMARY"
207
+ else
208
+ echo "::warning::promoted, but could not dispatch $CI_WORKFLOW on main (does it declare workflow_dispatch:?) — run it by hand to cut the candidate"
209
+ fi
210
+ elif [ "$(jq -r '.noop' "$OUT")" = "true" ]; then
211
+ echo "No promotion: $(jq -r '.reason' "$OUT")" | tee -a "$GITHUB_STEP_SUMMARY"
212
+ else
213
+ echo "::warning::colab promote --auto refused: $(jq -r '.reason' "$OUT")"
214
+ fi
215
+
216
+ # #443: the newest candidate always names main's head. The scheduled run cuts too, so a head a
217
+ # declared release.candidates-per-day window held back is tagged once the window ends, even
218
+ # with no new merge to fire workflow_run. A head already carrying a candidate is a no-op. Not
219
+ # right after this run promoted: that head has no CI yet — the dispatched run cuts it.
220
+ - name: Cut a candidate (colab release cut --auto)
221
+ id: cut
222
+ if: (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
223
+ run: |
224
+ set -uo pipefail
225
+ OUT="$RUNNER_TEMP/cut.json"
226
+ rc=0
227
+ node "$COLAB" release cut --auto --json > "$OUT" || rc=$?
228
+ # A verdict is JSON carrying `ok`; anything else is a run that never decided.
229
+ if ! jq -e 'has("ok")' "$OUT" > /dev/null 2>&1; then
230
+ echo "::error::colab release cut produced no verdict (exit $rc)"
231
+ cat "$OUT"
232
+ exit 1
233
+ fi
234
+ {
235
+ echo "### colab release cut --auto"
236
+ echo
237
+ jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
238
+ echo
239
+ } >> "$GITHUB_STEP_SUMMARY"
240
+ if [ "$(jq -r '.created' "$OUT")" = "true" ]; then
241
+ TAG="$(jq -r '.tag' "$OUT")"
242
+ echo "tag=$TAG" >> "$GITHUB_OUTPUT"
243
+ echo "Cut $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
244
+ elif [ "$(jq -r '.noop' "$OUT")" = "true" ]; then
245
+ echo "No-op: nothing owed, head already a candidate, inside a declared cadence window, or main's head is not a promotion." | tee -a "$GITHUB_STEP_SUMMARY"
246
+ elif [ "$(jq -r '.ok' "$OUT")" = "true" ]; then
247
+ echo "Verdict ok but nothing created." | tee -a "$GITHUB_STEP_SUMMARY"
248
+ else
249
+ echo "::warning::colab release cut refused: $(jq -r '[.checks[]? | select(.ok | not) | .condition] | join(", ")' "$OUT")"
250
+ fi
251
+
252
+ - name: Finalize the newest clean candidate (colab release finalize --auto)
253
+ id: finalize
254
+ if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
255
+ run: |
256
+ set -uo pipefail
257
+ OUT="$RUNNER_TEMP/finalize.json"
258
+ rc=0
259
+ node "$COLAB" release finalize --auto --json > "$OUT" || rc=$?
260
+ if ! jq -e 'has("state")' "$OUT" > /dev/null 2>&1; then
261
+ echo "::error::colab release finalize produced no verdict (exit $rc)"
262
+ cat "$OUT"
263
+ exit 1
264
+ fi
265
+ STATE="$(jq -r '.state' "$OUT")"
266
+ {
267
+ echo "### colab release finalize --auto — $STATE"
268
+ echo
269
+ jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
270
+ echo
271
+ } >> "$GITHUB_STEP_SUMMARY"
272
+ if [ "$(jq -r '.tagged' "$OUT")" = "true" ]; then
273
+ TAG="$(jq -r '.finalTag' "$OUT")"
274
+ echo "tag=$TAG" >> "$GITHUB_OUTPUT"
275
+ echo "Finalized $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
276
+ else
277
+ case "$STATE" in
278
+ refused|needs-new-candidate|held) echo "::warning::colab release finalize: $STATE" ;;
279
+ *) echo "Finalize: $STATE" ;;
280
+ esac
281
+ fi
282
+
283
+ # Whether the npm job publishes what this run tagged — `colab release npm` reads the
284
+ # release: block (one reading, the same as cut/finalize). A CLI older than #433 gives no
285
+ # verdict; that is a warning and no npm publish, never a failed release.
286
+ - name: Read the npm target (colab release npm)
287
+ id: npm-target
288
+ if: steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != ''
289
+ env:
290
+ TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
291
+ run: |
292
+ set -uo pipefail
293
+ OUT="$RUNNER_TEMP/npm.json"
294
+ node "$COLAB" release npm --json > "$OUT" 2> /dev/null || true
295
+ if ! jq -e 'has("publish")' "$OUT" > /dev/null 2>&1; then
296
+ echo "::warning::colab release npm gave no verdict (a HANDBOOK_REF older than #433?) — nothing is published to npm"
297
+ echo "publish=false" >> "$GITHUB_OUTPUT"
298
+ exit 0
299
+ fi
300
+ if [ "$(jq -r '.publish' "$OUT")" != "true" ]; then
301
+ if [ "$(jq -r '.findings | length' "$OUT")" != "0" ]; then
302
+ echo "::warning::not publishing to npm: $(jq -r '.findings | join("; ")' "$OUT")"
303
+ fi
304
+ echo "publish=false" >> "$GITHUB_OUTPUT"
305
+ exit 0
306
+ fi
307
+ {
308
+ echo "publish=true"
309
+ echo "tags=$(echo $TAGS)"
310
+ echo "dir=$(jq -r '.dir' "$OUT")"
311
+ echo "gate=$(jq -r '.gate' "$OUT")"
312
+ echo "package=$(jq -r '.package' "$OUT")"
313
+ } >> "$GITHUB_OUTPUT"
314
+
315
+ # Publishes every tag THIS run created. In this run, never via a tag-push workflow:
316
+ # see "PUBLISHING HAPPENS IN THIS RUN" in the header.
317
+ - name: Publish GitHub Release (same run)
318
+ if: steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != ''
319
+ env:
320
+ TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
321
+ run: |
322
+ set -euo pipefail
323
+ for TAG in $TAGS; do
324
+ if gh release view "$TAG" > /dev/null 2>&1; then
325
+ echo "$TAG already has a Release — skipping"
326
+ continue
327
+ fi
328
+ # Notes since the previous FINAL tag, candidate or final alike — never since an
329
+ # earlier candidate (the same rule as release-tag.yml).
330
+ PREV="$(git describe --tags --abbrev=0 --match 'v*.*.*' --exclude '*-*' "${TAG}^" 2>/dev/null || true)"
331
+ NOTES="$RUNNER_TEMP/notes-$TAG.md"
332
+ if [ -n "$PREV" ]; then
333
+ node "$COLAB" release-notes "${PREV}..${TAG}" --out "$NOTES"
334
+ else
335
+ printf '## %s\n\nFirst release.\n' "$TAG" > "$NOTES"
336
+ fi
337
+ case "$TAG" in
338
+ *-*) KIND=(--prerelease --latest=false) ;;
339
+ *) KIND=(--latest) ;;
340
+ esac
341
+ gh release create "$TAG" --verify-tag --title "$TAG" --notes-file "$NOTES" --generate-notes "${KIND[@]}"
342
+ echo "Published $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
343
+ done
344
+
345
+ # ---------------------------------------------------------------------------------------------
346
+ # npm (#433) — publishes what the release job tagged, in this same run. Opt-in: it runs only when
347
+ # .github/project.yml declares release.npm + release.npm-gate on the public-tool route, so a repo
348
+ # without them never gets this job.
349
+ #
350
+ # candidate vX.Y.Z-rc.N -> npm publish --tag next --provenance
351
+ # final vX.Y.Z -> npm publish --tag latest --provenance (latest never moves to an rc)
352
+ #
353
+ # TRUSTED PUBLISHING (OIDC) ONLY. No npm token is stored, read, or offered as a fallback — the
354
+ # job refuses to run with one in its environment. npm ends direct publishing with 2FA-bypass
355
+ # tokens in January 2027; this design never used one. One-time setup on npmjs.com: the package's
356
+ # Settings -> Trusted publishing -> GitHub Actions, this repository, workflow file
357
+ # `release-auto.yml` (the file's name, not its `name:`).
358
+ #
359
+ # GITHUB-HOSTED, ALWAYS. npm trusted publishing does not support self-hosted runners, so this job
360
+ # stays on GitHub-hosted even where `release` above runs self-hosted (free on a public repo — the
361
+ # only kind that publishes here; a private repo is refused outright, #432).
362
+ #
363
+ # IT NEVER MOVES GIT. It checks out the tag, stamps the version from the tag into package.json
364
+ # (the manifest carries none — the tag is the version), runs the gate, publishes. Nothing is
365
+ # committed or pushed. If it fails, the tag stands, `npm-record` writes "tagged, not published"
366
+ # on the Release, and re-running the failed job publishes the existing tag; a version already on
367
+ # npm is skipped, so a re-run never double-publishes.
368
+ npm:
369
+ name: Publish to npm (trusted publishing)
370
+ needs: release
371
+ if: needs.release.outputs.npm == 'true'
372
+ runs-on: ubuntu-latest # NEVER self-hosted: npm trusted publishing does not support it.
373
+ permissions:
374
+ contents: read # check out the tag; read the repository's visibility
375
+ id-token: write # the OIDC token npm exchanges for a one-time publish credential
376
+ env:
377
+ GH_TOKEN: ${{ github.token }}
378
+ REPO: ${{ github.repository }}
379
+ TAGS: ${{ needs.release.outputs.tags }}
380
+ PKG_DIR: ${{ needs.release.outputs.npm-dir }}
381
+ GATE: ${{ needs.release.outputs.npm-gate }}
382
+ PACKAGE: ${{ needs.release.outputs.npm-package }}
383
+ steps:
384
+ - name: Refuse a private repository, and any npm token
385
+ run: |
386
+ set -uo pipefail
387
+ # Visibility from the API, never assumed: unknown is refused like private.
388
+ PRIVATE="$(gh api "repos/$REPO" --jq '.private' 2> /dev/null || echo unknown)"
389
+ if [ "$PRIVATE" != "false" ]; then
390
+ echo "::error::$REPO is private (or its visibility could not be read: $PRIVATE) — a private repository never publishes to public npm (#432). Remove release.npm, or install from git."
391
+ exit 1
392
+ fi
393
+ if [ -n "${NODE_AUTH_TOKEN:-}${NPM_TOKEN:-}" ]; then
394
+ echo "::error::an npm token is set in this job's environment — this workflow publishes through trusted publishing (OIDC) only and never with a token. Remove it."
395
+ exit 1
396
+ fi
397
+
398
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
399
+ with:
400
+ fetch-depth: 0
401
+ persist-credentials: false # nothing here pushes
402
+
403
+ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
404
+ with:
405
+ node-version: 24 # no registry-url: that writes an .npmrc expecting a token
406
+
407
+ - name: npm new enough for trusted publishing (>= 11.5.1)
408
+ run: |
409
+ set -euo pipefail
410
+ if ! node -e 'const [a,b,c]=process.argv[1].split(".").map(Number);process.exit(a>11||(a===11&&(b>5||(b===5&&c>=1)))?0:1)' "$(npm --version)"; then
411
+ npm install --global npm@11
412
+ fi
413
+ npm --version
414
+
415
+ # EDIT: a package that needs a build step builds here, BEFORE the gate — the gate measures
416
+ # what ships, and the publish below runs with --ignore-scripts so nothing changes after it.
417
+ - name: Publish each tag (npm publish --provenance)
418
+ run: |
419
+ set -euo pipefail
420
+ for TAG in $TAGS; do
421
+ VERSION="${TAG#v}"
422
+ case "$VERSION" in
423
+ *-*) DIST=next ;;
424
+ *) DIST=latest ;;
425
+ esac
426
+ if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
427
+ echo "$PACKAGE@$VERSION is already on npm — skipping" | tee -a "$GITHUB_STEP_SUMMARY"
428
+ continue
429
+ fi
430
+ git checkout --quiet --force "refs/tags/$TAG"
431
+ git clean -fdxq
432
+ (cd "$PKG_DIR" && npm pkg set "version=$VERSION")
433
+ sh -c "$GATE"
434
+ (cd "$PKG_DIR" && npm publish --tag "$DIST" --provenance --access public --ignore-scripts)
435
+ echo "Published $PACKAGE@$VERSION to npm (dist-tag $DIST)" | tee -a "$GITHUB_STEP_SUMMARY"
436
+ done
437
+
438
+ # Writes the npm outcome onto each GitHub Release the run published, replacing its own earlier
439
+ # line on a re-run: "published" once it is, "tagged, not published" with the re-run hint until then.
440
+ npm-record:
441
+ name: Record the npm outcome on the Release
442
+ needs: [release, npm]
443
+ if: always() && needs.release.outputs.npm == 'true'
444
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
445
+ permissions:
446
+ contents: write # edit the Release notes
447
+ env:
448
+ GH_TOKEN: ${{ github.token }}
449
+ REPO: ${{ github.repository }}
450
+ TAGS: ${{ needs.release.outputs.tags }}
451
+ PACKAGE: ${{ needs.release.outputs.npm-package }}
452
+ RESULT: ${{ needs.npm.result }}
453
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
454
+ steps:
455
+ - name: Record the npm outcome
456
+ run: |
457
+ set -euo pipefail
458
+ for TAG in $TAGS; do
459
+ BODY="$(gh release view "$TAG" --repo "$REPO" --json body --jq '.body' 2> /dev/null)" || {
460
+ echo "$TAG has no Release — nothing to record on"
461
+ continue
462
+ }
463
+ VERSION="${TAG#v}"
464
+ case "$VERSION" in *-*) DIST=next ;; *) DIST=latest ;; esac
465
+ if [ "$RESULT" = "success" ]; then
466
+ LINE="npm: published \`$PACKAGE@$VERSION\` (dist-tag \`$DIST\`)."
467
+ else
468
+ LINE="**npm: tagged, not published** (\`$PACKAGE@$VERSION\`, job $RESULT). Re-run the failed \`npm\` job of $RUN_URL — it publishes this existing tag; nothing in git moves."
469
+ fi
470
+ NOTES="$RUNNER_TEMP/notes-$TAG.md"
471
+ printf '%s\n' "$BODY" | sed '/^<!-- colab:npm -->$/,/^<!-- \/colab:npm -->$/d' > "$NOTES"
472
+ printf '\n<!-- colab:npm -->\n%s\n<!-- /colab:npm -->\n' "$LINE" >> "$NOTES"
473
+ gh release edit "$TAG" --repo "$REPO" --notes-file "$NOTES" > /dev/null
474
+ echo "$TAG: $LINE" | tee -a "$GITHUB_STEP_SUMMARY"
475
+ done