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

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 (93) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +309 -3
  3. package/README.vi.md +279 -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 +117 -0
  22. package/templates/release-auto.yml +470 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13746 -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 +259 -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.js +188 -0
  63. package/tools/lib/npm-publish-guard.js +242 -0
  64. package/tools/lib/orphan-worktree.js +127 -0
  65. package/tools/lib/owner-branch.js +182 -0
  66. package/tools/lib/place.js +782 -0
  67. package/tools/lib/ports.js +167 -0
  68. package/tools/lib/procs.js +185 -0
  69. package/tools/lib/readiness.js +240 -0
  70. package/tools/lib/records.js +185 -0
  71. package/tools/lib/refs-brake.js +95 -0
  72. package/tools/lib/release-cut.js +822 -0
  73. package/tools/lib/release-finalize.js +481 -0
  74. package/tools/lib/release-policy.js +358 -0
  75. package/tools/lib/release-tag.js +225 -0
  76. package/tools/lib/ship-batch.js +277 -0
  77. package/tools/lib/ship-roles.js +71 -0
  78. package/tools/lib/ship-target-sync.js +181 -0
  79. package/tools/lib/shipguard.js +317 -0
  80. package/tools/lib/shipped-branch.js +56 -0
  81. package/tools/lib/solo.js +213 -0
  82. package/tools/lib/squash.js +515 -0
  83. package/tools/lib/stale-base.js +70 -0
  84. package/tools/lib/stamp.js +703 -0
  85. package/tools/lib/state.js +262 -0
  86. package/tools/lib/teardown.js +83 -0
  87. package/tools/lib/trust-humans.js +104 -0
  88. package/tools/lib/util.js +98 -0
  89. package/tools/lib/wake.js +188 -0
  90. package/tools/lib/workflow-triggers.js +273 -0
  91. package/tools/lib/writes-authority.js +237 -0
  92. package/tools/lib/yaml.js +101 -0
  93. package/bin/cli.js +0 -3
@@ -0,0 +1,470 @@
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 version whose colab CLI makes the release decisions. Pin a tag;
128
+ # moving it is a deliberate act, like re-copying a template.
129
+ HANDBOOK_REF: "v1.11.0"
130
+ HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
131
+
132
+ jobs:
133
+ release:
134
+ name: Cut, finalize, publish
135
+ # A red CI run on main is not a candidate; skip rather than refuse.
136
+ if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
137
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
138
+ permissions:
139
+ contents: write # push the tags (and, with promotion: main-loop, the promotion), publish the GitHub Release
140
+ issues: write # finalize opens / comments on / closes the "release: vX.Y.Z" tracking issue
141
+ actions: write # read the runs at a commit (ci-green, full-suite, trunk-green); dispatch CI after a promotion
142
+ # What the npm job below needs (#433) — empty / publish=false unless this run tagged something
143
+ # AND .github/project.yml opts in with release.npm.
144
+ outputs:
145
+ tags: ${{ steps.npm-target.outputs.tags }}
146
+ npm: ${{ steps.npm-target.outputs.publish }}
147
+ npm-dir: ${{ steps.npm-target.outputs.dir }}
148
+ npm-gate: ${{ steps.npm-target.outputs.gate }}
149
+ npm-package: ${{ steps.npm-target.outputs.package }}
150
+ env:
151
+ GH_TOKEN: ${{ github.token }}
152
+ steps:
153
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
154
+ with:
155
+ ref: main
156
+ # Full history plus tags: versions, bumps and "previous final" are all read from
157
+ # git, and the on-trunk check refuses a shallow checkout outright.
158
+ fetch-depth: 0
159
+ # Left on deliberately: `colab release cut` / `finalize` push their tag over the
160
+ # checkout's origin. The token is this job's, scoped by `permissions:` above.
161
+ persist-credentials: true
162
+
163
+ - name: Fetch the colab CLI
164
+ run: |
165
+ set -euo pipefail
166
+ git clone --quiet --depth 1 --branch "$HANDBOOK_REF" "$HANDBOOK_REPO" "$RUNNER_TEMP/colab-handbook"
167
+ echo "COLAB=$RUNNER_TEMP/colab-handbook/tools/colab" >> "$GITHUB_ENV"
168
+ # The tags are annotated; git needs an identity to write one.
169
+ git config user.name "github-actions[bot]"
170
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
171
+
172
+ # #440: where project.yml grants `promotion: main-loop` on `deploy: tag`, promote a green dev
173
+ # into main, then dispatch CI there — its green run fires this workflow again to cut the
174
+ # candidate. Everywhere else the CLI answers a no-op. A refusal (dev CI not green, a push
175
+ # rejected) is a warning; the job stays green.
176
+ - name: Promote unattended (colab promote --auto)
177
+ id: promote
178
+ if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
179
+ env:
180
+ # EDIT: your test-suite workflow — the same one `workflow_run.workflows` names above.
181
+ CI_WORKFLOW: "CI"
182
+ run: |
183
+ set -uo pipefail
184
+ OUT="$RUNNER_TEMP/promote.json"
185
+ rc=0
186
+ node "$COLAB" promote --auto --json > "$OUT" || rc=$?
187
+ if ! jq -e 'has("promoted")' "$OUT" > /dev/null 2>&1; then
188
+ echo "::warning::colab promote --auto gave no verdict (exit $rc; a HANDBOOK_REF older than #440?) — nothing was promoted"
189
+ exit 0
190
+ fi
191
+ {
192
+ echo "### colab promote --auto"
193
+ echo
194
+ jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
195
+ echo
196
+ } >> "$GITHUB_STEP_SUMMARY"
197
+ if [ "$(jq -r '.promoted' "$OUT")" = "true" ]; then
198
+ echo "promoted=true" >> "$GITHUB_OUTPUT"
199
+ echo "Promoted to main @ $(jq -r '.sha' "$OUT")" | tee -a "$GITHUB_STEP_SUMMARY"
200
+ if gh workflow run "$CI_WORKFLOW" --ref main; then
201
+ echo "Dispatched $CI_WORKFLOW on main — its green run cuts the candidate." | tee -a "$GITHUB_STEP_SUMMARY"
202
+ else
203
+ echo "::warning::promoted, but could not dispatch $CI_WORKFLOW on main (does it declare workflow_dispatch:?) — run it by hand to cut the candidate"
204
+ fi
205
+ elif [ "$(jq -r '.noop' "$OUT")" = "true" ]; then
206
+ echo "No promotion: $(jq -r '.reason' "$OUT")" | tee -a "$GITHUB_STEP_SUMMARY"
207
+ else
208
+ echo "::warning::colab promote --auto refused: $(jq -r '.reason' "$OUT")"
209
+ fi
210
+
211
+ # #443: the newest candidate always names main's head. The scheduled run cuts too, so a head a
212
+ # declared release.candidates-per-day window held back is tagged once the window ends, even
213
+ # with no new merge to fire workflow_run. A head already carrying a candidate is a no-op. Not
214
+ # right after this run promoted: that head has no CI yet — the dispatched run cuts it.
215
+ - name: Cut a candidate (colab release cut --auto)
216
+ id: cut
217
+ if: (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
218
+ run: |
219
+ set -uo pipefail
220
+ OUT="$RUNNER_TEMP/cut.json"
221
+ rc=0
222
+ node "$COLAB" release cut --auto --json > "$OUT" || rc=$?
223
+ # A verdict is JSON carrying `ok`; anything else is a run that never decided.
224
+ if ! jq -e 'has("ok")' "$OUT" > /dev/null 2>&1; then
225
+ echo "::error::colab release cut produced no verdict (exit $rc)"
226
+ cat "$OUT"
227
+ exit 1
228
+ fi
229
+ {
230
+ echo "### colab release cut --auto"
231
+ echo
232
+ jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
233
+ echo
234
+ } >> "$GITHUB_STEP_SUMMARY"
235
+ if [ "$(jq -r '.created' "$OUT")" = "true" ]; then
236
+ TAG="$(jq -r '.tag' "$OUT")"
237
+ echo "tag=$TAG" >> "$GITHUB_OUTPUT"
238
+ echo "Cut $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
239
+ elif [ "$(jq -r '.noop' "$OUT")" = "true" ]; then
240
+ 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"
241
+ elif [ "$(jq -r '.ok' "$OUT")" = "true" ]; then
242
+ echo "Verdict ok but nothing created." | tee -a "$GITHUB_STEP_SUMMARY"
243
+ else
244
+ echo "::warning::colab release cut refused: $(jq -r '[.checks[]? | select(.ok | not) | .condition] | join(", ")' "$OUT")"
245
+ fi
246
+
247
+ - name: Finalize the newest clean candidate (colab release finalize --auto)
248
+ id: finalize
249
+ if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
250
+ run: |
251
+ set -uo pipefail
252
+ OUT="$RUNNER_TEMP/finalize.json"
253
+ rc=0
254
+ node "$COLAB" release finalize --auto --json > "$OUT" || rc=$?
255
+ if ! jq -e 'has("state")' "$OUT" > /dev/null 2>&1; then
256
+ echo "::error::colab release finalize produced no verdict (exit $rc)"
257
+ cat "$OUT"
258
+ exit 1
259
+ fi
260
+ STATE="$(jq -r '.state' "$OUT")"
261
+ {
262
+ echo "### colab release finalize --auto — $STATE"
263
+ echo
264
+ jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
265
+ echo
266
+ } >> "$GITHUB_STEP_SUMMARY"
267
+ if [ "$(jq -r '.tagged' "$OUT")" = "true" ]; then
268
+ TAG="$(jq -r '.finalTag' "$OUT")"
269
+ echo "tag=$TAG" >> "$GITHUB_OUTPUT"
270
+ echo "Finalized $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
271
+ else
272
+ case "$STATE" in
273
+ refused|needs-new-candidate|held) echo "::warning::colab release finalize: $STATE" ;;
274
+ *) echo "Finalize: $STATE" ;;
275
+ esac
276
+ fi
277
+
278
+ # Whether the npm job publishes what this run tagged — `colab release npm` reads the
279
+ # release: block (one reading, the same as cut/finalize). A CLI older than #433 gives no
280
+ # verdict; that is a warning and no npm publish, never a failed release.
281
+ - name: Read the npm target (colab release npm)
282
+ id: npm-target
283
+ if: steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != ''
284
+ env:
285
+ TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
286
+ run: |
287
+ set -uo pipefail
288
+ OUT="$RUNNER_TEMP/npm.json"
289
+ node "$COLAB" release npm --json > "$OUT" 2> /dev/null || true
290
+ if ! jq -e 'has("publish")' "$OUT" > /dev/null 2>&1; then
291
+ echo "::warning::colab release npm gave no verdict (a HANDBOOK_REF older than #433?) — nothing is published to npm"
292
+ echo "publish=false" >> "$GITHUB_OUTPUT"
293
+ exit 0
294
+ fi
295
+ if [ "$(jq -r '.publish' "$OUT")" != "true" ]; then
296
+ if [ "$(jq -r '.findings | length' "$OUT")" != "0" ]; then
297
+ echo "::warning::not publishing to npm: $(jq -r '.findings | join("; ")' "$OUT")"
298
+ fi
299
+ echo "publish=false" >> "$GITHUB_OUTPUT"
300
+ exit 0
301
+ fi
302
+ {
303
+ echo "publish=true"
304
+ echo "tags=$(echo $TAGS)"
305
+ echo "dir=$(jq -r '.dir' "$OUT")"
306
+ echo "gate=$(jq -r '.gate' "$OUT")"
307
+ echo "package=$(jq -r '.package' "$OUT")"
308
+ } >> "$GITHUB_OUTPUT"
309
+
310
+ # Publishes every tag THIS run created. In this run, never via a tag-push workflow:
311
+ # see "PUBLISHING HAPPENS IN THIS RUN" in the header.
312
+ - name: Publish GitHub Release (same run)
313
+ if: steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != ''
314
+ env:
315
+ TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
316
+ run: |
317
+ set -euo pipefail
318
+ for TAG in $TAGS; do
319
+ if gh release view "$TAG" > /dev/null 2>&1; then
320
+ echo "$TAG already has a Release — skipping"
321
+ continue
322
+ fi
323
+ # Notes since the previous FINAL tag, candidate or final alike — never since an
324
+ # earlier candidate (the same rule as release-tag.yml).
325
+ PREV="$(git describe --tags --abbrev=0 --match 'v*.*.*' --exclude '*-*' "${TAG}^" 2>/dev/null || true)"
326
+ NOTES="$RUNNER_TEMP/notes-$TAG.md"
327
+ if [ -n "$PREV" ]; then
328
+ node "$COLAB" release-notes "${PREV}..${TAG}" --out "$NOTES"
329
+ else
330
+ printf '## %s\n\nFirst release.\n' "$TAG" > "$NOTES"
331
+ fi
332
+ case "$TAG" in
333
+ *-*) KIND=(--prerelease --latest=false) ;;
334
+ *) KIND=(--latest) ;;
335
+ esac
336
+ gh release create "$TAG" --verify-tag --title "$TAG" --notes-file "$NOTES" --generate-notes "${KIND[@]}"
337
+ echo "Published $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
338
+ done
339
+
340
+ # ---------------------------------------------------------------------------------------------
341
+ # npm (#433) — publishes what the release job tagged, in this same run. Opt-in: it runs only when
342
+ # .github/project.yml declares release.npm + release.npm-gate on the public-tool route, so a repo
343
+ # without them never gets this job.
344
+ #
345
+ # candidate vX.Y.Z-rc.N -> npm publish --tag next --provenance
346
+ # final vX.Y.Z -> npm publish --tag latest --provenance (latest never moves to an rc)
347
+ #
348
+ # TRUSTED PUBLISHING (OIDC) ONLY. No npm token is stored, read, or offered as a fallback — the
349
+ # job refuses to run with one in its environment. npm ends direct publishing with 2FA-bypass
350
+ # tokens in January 2027; this design never used one. One-time setup on npmjs.com: the package's
351
+ # Settings -> Trusted publishing -> GitHub Actions, this repository, workflow file
352
+ # `release-auto.yml` (the file's name, not its `name:`).
353
+ #
354
+ # GITHUB-HOSTED, ALWAYS. npm trusted publishing does not support self-hosted runners, so this job
355
+ # stays on GitHub-hosted even where `release` above runs self-hosted (free on a public repo — the
356
+ # only kind that publishes here; a private repo is refused outright, #432).
357
+ #
358
+ # IT NEVER MOVES GIT. It checks out the tag, stamps the version from the tag into package.json
359
+ # (the manifest carries none — the tag is the version), runs the gate, publishes. Nothing is
360
+ # committed or pushed. If it fails, the tag stands, `npm-record` writes "tagged, not published"
361
+ # on the Release, and re-running the failed job publishes the existing tag; a version already on
362
+ # npm is skipped, so a re-run never double-publishes.
363
+ npm:
364
+ name: Publish to npm (trusted publishing)
365
+ needs: release
366
+ if: needs.release.outputs.npm == 'true'
367
+ runs-on: ubuntu-latest # NEVER self-hosted: npm trusted publishing does not support it.
368
+ permissions:
369
+ contents: read # check out the tag; read the repository's visibility
370
+ id-token: write # the OIDC token npm exchanges for a one-time publish credential
371
+ env:
372
+ GH_TOKEN: ${{ github.token }}
373
+ REPO: ${{ github.repository }}
374
+ TAGS: ${{ needs.release.outputs.tags }}
375
+ PKG_DIR: ${{ needs.release.outputs.npm-dir }}
376
+ GATE: ${{ needs.release.outputs.npm-gate }}
377
+ PACKAGE: ${{ needs.release.outputs.npm-package }}
378
+ steps:
379
+ - name: Refuse a private repository, and any npm token
380
+ run: |
381
+ set -uo pipefail
382
+ # Visibility from the API, never assumed: unknown is refused like private.
383
+ PRIVATE="$(gh api "repos/$REPO" --jq '.private' 2> /dev/null || echo unknown)"
384
+ if [ "$PRIVATE" != "false" ]; then
385
+ 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."
386
+ exit 1
387
+ fi
388
+ if [ -n "${NODE_AUTH_TOKEN:-}${NPM_TOKEN:-}" ]; then
389
+ 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."
390
+ exit 1
391
+ fi
392
+
393
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
394
+ with:
395
+ fetch-depth: 0
396
+ persist-credentials: false # nothing here pushes
397
+
398
+ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
399
+ with:
400
+ node-version: 24 # no registry-url: that writes an .npmrc expecting a token
401
+
402
+ - name: npm new enough for trusted publishing (>= 11.5.1)
403
+ run: |
404
+ set -euo pipefail
405
+ 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
406
+ npm install --global npm@11
407
+ fi
408
+ npm --version
409
+
410
+ # EDIT: a package that needs a build step builds here, BEFORE the gate — the gate measures
411
+ # what ships, and the publish below runs with --ignore-scripts so nothing changes after it.
412
+ - name: Publish each tag (npm publish --provenance)
413
+ run: |
414
+ set -euo pipefail
415
+ for TAG in $TAGS; do
416
+ VERSION="${TAG#v}"
417
+ case "$VERSION" in
418
+ *-*) DIST=next ;;
419
+ *) DIST=latest ;;
420
+ esac
421
+ if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
422
+ echo "$PACKAGE@$VERSION is already on npm — skipping" | tee -a "$GITHUB_STEP_SUMMARY"
423
+ continue
424
+ fi
425
+ git checkout --quiet --force "refs/tags/$TAG"
426
+ git clean -fdxq
427
+ (cd "$PKG_DIR" && npm pkg set "version=$VERSION")
428
+ sh -c "$GATE"
429
+ (cd "$PKG_DIR" && npm publish --tag "$DIST" --provenance --access public --ignore-scripts)
430
+ echo "Published $PACKAGE@$VERSION to npm (dist-tag $DIST)" | tee -a "$GITHUB_STEP_SUMMARY"
431
+ done
432
+
433
+ # Writes the npm outcome onto each GitHub Release the run published, replacing its own earlier
434
+ # line on a re-run: "published" once it is, "tagged, not published" with the re-run hint until then.
435
+ npm-record:
436
+ name: Record the npm outcome on the Release
437
+ needs: [release, npm]
438
+ if: always() && needs.release.outputs.npm == 'true'
439
+ runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
440
+ permissions:
441
+ contents: write # edit the Release notes
442
+ env:
443
+ GH_TOKEN: ${{ github.token }}
444
+ REPO: ${{ github.repository }}
445
+ TAGS: ${{ needs.release.outputs.tags }}
446
+ PACKAGE: ${{ needs.release.outputs.npm-package }}
447
+ RESULT: ${{ needs.npm.result }}
448
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
449
+ steps:
450
+ - name: Record the npm outcome
451
+ run: |
452
+ set -euo pipefail
453
+ for TAG in $TAGS; do
454
+ BODY="$(gh release view "$TAG" --repo "$REPO" --json body --jq '.body' 2> /dev/null)" || {
455
+ echo "$TAG has no Release — nothing to record on"
456
+ continue
457
+ }
458
+ VERSION="${TAG#v}"
459
+ case "$VERSION" in *-*) DIST=next ;; *) DIST=latest ;; esac
460
+ if [ "$RESULT" = "success" ]; then
461
+ LINE="npm: published \`$PACKAGE@$VERSION\` (dist-tag \`$DIST\`)."
462
+ else
463
+ 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."
464
+ fi
465
+ NOTES="$RUNNER_TEMP/notes-$TAG.md"
466
+ printf '%s\n' "$BODY" | sed '/^<!-- colab:npm -->$/,/^<!-- \/colab:npm -->$/d' > "$NOTES"
467
+ printf '\n<!-- colab:npm -->\n%s\n<!-- /colab:npm -->\n' "$LINE" >> "$NOTES"
468
+ gh release edit "$TAG" --repo "$REPO" --notes-file "$NOTES" > /dev/null
469
+ echo "$TAG: $LINE" | tee -a "$GITHUB_STEP_SUMMARY"
470
+ done