@futurelastic/colab-handbook 1.14.1-rc.9 → 1.15.0-rc.1

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.
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.14.1-rc.9"
36
+ "version": "1.15.0-rc.1"
37
37
  }
@@ -79,7 +79,7 @@ Named it something other than `ci-heavy.yml`? Say so with `heavy-workflow:` in `
79
79
  | `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push. Toolchain and install steps are copied from the light lane's `build` job, so the two resolve the same versions — keep them in step. `TRUNK` is an edit point. |
80
80
  | `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. |
81
81
  | `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
82
- | `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
82
+ | `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main — at the sha that CI run tested (`--sha`, #622), even once main has moved on — and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
83
83
  | `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
84
84
  | `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path. A **channel** committish (`#stable`, `#next`, #465) is resolved to the release tag on the commit npx installed, then installed as that version; any other branch is refused. Also the library `npx-service.mjs` imports. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
85
85
  | `npx-service.mjs` | the same directory as your `npx-launcher.mjs` copy (e.g. `bin/service.mjs`), named by the root `package.json`'s `bin` | A tool that runs as a **per-machine service** (a dashboard, a daemon, a JS app a launch agent serves), installed with npx ([CONVENTIONS §6, *Services over npx*](../CONVENTIONS.md#services-over-npx--init-update-rollback-465)) | `npx github:<org>/<repo>#vX.Y.Z init [--auto-update 6h \| --no-auto-update]`, then `<tool> update [--check] [--version vX.Y.Z] [--channel next\|stable]`, `<tool> rollback`, `<tool> status`, `<tool> uninstall [--purge]` (#472: unit, timer, shim and every version go; config and state stay unless `--purge`); anything else runs the current version's payload. Versions side by side under `$XDG_DATA_HOME/<tool>/` with `current`/`previous` links the unit and the `~/.local/bin` shim go through; update installs beside, switches, restarts, health-checks, and **switches back** on failure. Config/secrets under `$XDG_CONFIG_HOME/<tool>/`, state and logs under `$XDG_STATE_HOME/<tool>/` — the unit carries their locations, never a value. launchd agent on macOS, systemd user unit on Linux, Windows refused; `<TOOL>_SERVICE_MANAGER=none` skips the manager. `--auto-update` (#471) adds a timer (launchd `StartInterval` agent / systemd user `.timer`) that runs the same `update`. Node ≥ 18, zero dependencies; needs `git`, `npm` for `update`, `tar` for `dist`. **Imports `./npx-launcher.mjs`** — copy both, or edit the import. Edit points: `KIND` (`binary` = a compiled tool from dist refs, `package` = a JS app run with node, `dist` = a prebuilt JS app unpacked from one verified tarball in the `dist/vX.Y.Z/any` ref, #470), `LABEL`, `SERVICE_ARGS`, `ENTRY`, `DIST_FILE`, `HEALTH_URL`, `KEEP`, `AUTO_UPDATE`, `VERBS`. The package's `files` must include both copies (and a `package` app's built output). `colab template npx-service.mjs --dest <path>`, `--dest` required. |
@@ -15,7 +15,9 @@
15
15
  # everywhere else)
16
16
  # your CI workflow finished green on main colab release cut --auto → vX.Y.Z-rc.N
17
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)
18
+ # and the daily schedule head; a head already carrying one is a no-op.
19
+ # #622: a CI-fired run cuts the sha that run
20
+ # tested — `--sha` — even once main moved on)
19
21
  # a daily schedule colab release finalize --auto → vX.Y.Z (or a
20
22
  # hand-off where
21
23
  # the final is a
@@ -457,16 +459,41 @@ jobs:
457
459
  # declared release.candidates-per-day window held back is tagged once the window ends, even
458
460
  # with no new merge to fire workflow_run. A head already carrying a candidate is a no-op. Not
459
461
  # right after this run promoted: that head has no CI yet — the dispatched run cuts it.
462
+ # #622: a run fired by workflow_run cuts the sha THAT CI run tested (`--sha`), not main's head —
463
+ # on a busy trunk something lands during almost every suite run, so the green sha is rarely
464
+ # still the head when its run ends, and the head itself has no green run yet. The head gets its
465
+ # own candidate when its own run is green; a run that finishes out of order (a later commit
466
+ # already carries a candidate) is a no-op, so `next` never moves backwards. The schedule and a
467
+ # dispatch still cut main's head. While the cut reads an older sha the checkout is detached there
468
+ # (a release.guard-run reads the working tree) and restored afterwards.
460
469
  - name: Cut a candidate (colab release cut --auto)
461
470
  id: cut
462
471
  if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true' && (env.RETRY_RUN != 'true' || steps.retry.outputs.retry == 'true')
472
+ env:
473
+ EVENT: ${{ github.event_name }}
474
+ RUN_SHA: ${{ github.event.workflow_run.head_sha }}
463
475
  run: |
464
476
  set -uo pipefail
465
477
  eval "$RETRY_TRANSIENT"
466
478
  OUT="$RUNNER_TEMP/cut.json"
467
479
  rc=0
468
480
  DRY=(); [ "${DRY_RUN:-false}" = "true" ] && DRY=(--dry)
469
- retry_transient node "$COLAB" release cut --auto ${DRY[@]+"${DRY[@]}"} --json > "$OUT" || rc=$?
481
+ AT=(); RESTORE=""
482
+ if [ "${EVENT:-}" = "workflow_run" ] && [ -n "${RUN_SHA:-}" ]; then
483
+ if git rev-parse --git-dir > /dev/null 2>&1 && [ "$(git rev-parse HEAD)" != "$RUN_SHA" ]; then
484
+ RESTORE="$(git symbolic-ref --quiet --short HEAD || git rev-parse HEAD)"
485
+ git checkout --quiet --detach "$RUN_SHA" || RESTORE=""
486
+ fi
487
+ # Asked AFTER the detach, of the CLI that will run: a CLI older than #622 (a HANDBOOK_REF no
488
+ # final with --sha has reached yet, or a checkout's own CLI at an older sha) cuts the head.
489
+ if grep -q -- '--sha <sha>' <<< "$(node "$COLAB" release cut --help 2> /dev/null)"; then
490
+ AT=(--sha "$RUN_SHA")
491
+ elif [ -n "$RESTORE" ]; then
492
+ git checkout --quiet "$RESTORE"; RESTORE=""
493
+ fi
494
+ fi
495
+ retry_transient node "$COLAB" release cut --auto ${AT[@]+"${AT[@]}"} ${DRY[@]+"${DRY[@]}"} --json > "$OUT" || rc=$?
496
+ [ -z "$RESTORE" ] || git checkout --quiet "$RESTORE"
470
497
  # A verdict is JSON carrying `ok`; anything else is a run that never decided.
471
498
  if ! jq -e 'has("ok")' "$OUT" > /dev/null 2>&1; then
472
499
  echo "::error::colab release cut produced no verdict (exit $rc)"
package/tools/colab CHANGED
@@ -1252,7 +1252,7 @@ function existingWorktreeFor(repoAbs, wtName, branch) {
1252
1252
  }
1253
1253
 
1254
1254
  const HELP_RELEASE = `colab release <issue> [--repo <path>]
1255
- colab release cut [--repo <path>] [--bump patch|minor --reason "<why>"] [--dry] [--json] (see: colab release cut --help)
1255
+ colab release cut [--repo <path>] [--sha <sha>] [--bump patch|minor --reason "<why>"] [--dry] [--json] (see: colab release cut --help)
1256
1256
  colab release finalize [--repo <path>] [--tag vX.Y.Z-rc.N] [--answered-by <name>] [--dry] [--json] (see: colab release finalize --help)
1257
1257
  colab release npm [--repo <path>] [--json] (see: colab release npm --help)
1258
1258
 
@@ -1284,9 +1284,9 @@ said so. Worktree claims never held the checkout; \`colab worktree rm\` owns the
1284
1284
  // release skill's (#339) and never this command's.
1285
1285
  // ---------------------------------------------------------------------------
1286
1286
 
1287
- const HELP_RELEASE_CUT = `colab release cut [--repo <path>] [--auto | --bump patch|minor --reason "<why>"] [--dry] [--json]
1287
+ const HELP_RELEASE_CUT = `colab release cut [--repo <path>] [--sha <sha>] [--auto | --bump patch|minor --reason "<why>"] [--dry] [--json]
1288
1288
 
1289
- Cut a release CANDIDATE, vX.Y.Z-rc.N, on origin/main's head — only where CONVENTIONS.md §6's release
1289
+ Cut a release CANDIDATE, vX.Y.Z-rc.N, on origin/main's head (or the commit --sha names) — only where CONVENTIONS.md §6's release
1290
1290
  rung lets an agent, and only once every condition below holds on that exact commit. Creates an
1291
1291
  annotated tag (the bump, its reason and every checked condition are recorded in its message) and
1292
1292
  pushes it to origin. NEVER creates a final vX.Y.Z tag — finalizing is the release skill's.
@@ -1370,6 +1370,14 @@ The bump (without --auto) is release-status's semverSuggestion since the last fi
1370
1370
  patch, feat -> minor; a breaking change is a minor pre-1.0 and a refusal from 1.0 on.
1371
1371
  --bump patch|minor override the computed bump — requires --reason, which is recorded on the tag
1372
1372
  --reason "<why>" why the override
1373
+ --sha <sha> (#622) cut at this commit instead of main's head — the qualified sha a busy trunk
1374
+ has already moved past. Every condition above is measured at it; on-trunk
1375
+ requires it on main. One more row when it is not the head:
1376
+ qualified-sha refused (a NO-OP under --auto) when a release tag already names a
1377
+ later commit (the newer candidate stands), on a final route (a
1378
+ final is tagged only on main's head), or --auto under a
1379
+ candidates-per-day cap (the cut is spent on the head)
1380
+ The release workflow passes the sha its triggering CI run tested.
1373
1381
  --dry measure and report; create and push nothing
1374
1382
  --json machine-readable: { ok, tag, created, checks: [{condition, ok, detail}], ... }
1375
1383
  --repo <path> the repo (default: the one you are in)
@@ -1655,10 +1663,11 @@ function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
1655
1663
 
1656
1664
  function cmdReleaseCut(argv) {
1657
1665
  const opts = parseArgs(argv, {
1658
- values: { '--repo': 'repo', '--bump': 'bump', '--reason': 'reason' },
1666
+ values: { '--repo': 'repo', '--bump': 'bump', '--reason': 'reason', '--sha': 'sha' },
1659
1667
  flags: { '--dry': 'dry', '--json': 'json', '--auto': 'auto', '-h': 'help', '--help': 'help' },
1660
1668
  });
1661
1669
  if (opts.help) return print(HELP_RELEASE_CUT);
1670
+ if (opts.sha !== undefined && !/^[0-9a-f]{4,40}$/i.test(String(opts.sha))) throw new UserError(`--sha takes a commit sha (hex, 4–40 chars), got ${JSON.stringify(opts.sha)} — run \`git rev-parse <rev>\` and pass the sha it prints`);
1662
1671
  if (opts._.length) throw new UserError(`release cut takes no positional arguments (got: ${opts._.join(' ')})`);
1663
1672
  if (opts.auto && (opts.bump || opts.reason)) throw new UserError('--auto computes the bump with no human input — --bump/--reason cannot be combined with it');
1664
1673
  if (opts.reason && !opts.bump) throw new UserError('--reason records why --bump overrode the computed bump — pass --bump with it');
@@ -1678,7 +1687,15 @@ function cmdReleaseCut(argv) {
1678
1687
  const trunkFetch = offTrunk && opts.auto ? git.git(['fetch', remote, trunk], repoAbs) : null;
1679
1688
  const shaR = git.git(['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/main^{commit}`], repoAbs);
1680
1689
  if (!shaR.ok || !shaR.stdout) throw new UserError(`no ${remote}/main — candidates are cut from main (CONVENTIONS.md §6: never from dev)`);
1681
- const sha = shaR.stdout;
1690
+ const head = shaR.stdout;
1691
+ // #622: --sha names the commit to cut — a qualified sha a busy trunk has already moved past. Every
1692
+ // condition below is measured at it; on-trunk still requires it to be an ancestor of main.
1693
+ let sha = head;
1694
+ if (opts.sha) {
1695
+ const r = git.git(['rev-parse', '--verify', '--quiet', `${opts.sha}^{commit}`], repoAbs);
1696
+ if (!r.ok || !r.stdout) throw new UserError(`--sha ${opts.sha} is not a commit in this clone (after fetching ${remote}/main) — run \`git log --oneline ${remote}/main\` and pass a sha from it`);
1697
+ sha = r.stdout;
1698
+ }
1682
1699
  const at = `main@${shortSha(sha)}`;
1683
1700
 
1684
1701
  const wf = git.git(['ls-tree', '--name-only', `${sha}:.github/workflows`], repoAbs);
@@ -1695,7 +1712,7 @@ function cmdReleaseCut(argv) {
1695
1712
  const remoteTags = remoteTagSetOrThrow(repoAbs, remote);
1696
1713
  const lastFinal = releaseTag.latestReleaseTag(repoAbs, { ref: `${remote}/main`, onlyTags: remoteTags });
1697
1714
  const suggestion = lastFinal
1698
- ? semverSuggestion(ccSummary(repoAbs, `${lastFinal}..${remote}/main`))
1715
+ ? semverSuggestion(ccSummary(repoAbs, `${lastFinal}..${sha}`)) // #622: the bump reads what the tagged commit carries
1699
1716
  : { bump: null, why: 'no final tag yet' };
1700
1717
  const lines = (r) => (r.ok ? r.stdout.split('\n').map((s) => s.trim()).filter(Boolean) : []);
1701
1718
  const onRemote = (t) => remoteTags.has(t);
@@ -1741,8 +1758,21 @@ function cmdReleaseCut(argv) {
1741
1758
  if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha);
1742
1759
  }
1743
1760
 
1761
+ // #622: a cut below main's head — refused (a no-op under --auto) when a release tag already names a
1762
+ // later commit, on a final route, or under a candidates-per-day cap. Null at the head: today's cut.
1763
+ let qualified = null;
1764
+ if (sha !== head) {
1765
+ const c = git.git(['tag', '--contains', sha], repoAbs);
1766
+ const atSha = new Set(tagsAtSha);
1767
+ const newer = c.ok ? lines(c).filter(onRemote).filter((t) => !atSha.has(t) && /^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[1-9][0-9]*)?$/.test(t)) : null;
1768
+ qualified = releaseCut.qualifiedShaVerdict({
1769
+ sha, head, newer, finalRoute: fast || library, auto: !!opts.auto,
1770
+ capped: policy.effective && policy.effective.candidatesPerDay !== null && policy.effective.candidatesPerDay !== undefined,
1771
+ });
1772
+ }
1773
+
1744
1774
  const verdict = releaseCut.decide({
1745
- policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy,
1775
+ policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy, qualified,
1746
1776
  override: opts.bump ? { bump: opts.bump, reason: opts.reason } : null,
1747
1777
  finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations, migration: libraryMigration,
1748
1778
  trackingIssue: fastFacts.tracking ? fastFacts.tracking.number : null,
@@ -1805,7 +1835,7 @@ function cmdReleaseCut(argv) {
1805
1835
 
1806
1836
  if (opts.json) {
1807
1837
  print(JSON.stringify({
1808
- repo: shortRepo(repoAbs), sha, ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
1838
+ repo: shortRepo(repoAbs), sha, ...(sha !== head ? { head } : {}), ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
1809
1839
  ok: verdict.ok, noop: !!verdict.noop, standing: verdict.standing || [], tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
1810
1840
  overridden: verdict.overridden, signals: verdict.signals ? verdict.signals.lines : null, checks: verdict.checks,
1811
1841
  // #446: present on every route, so the workflow reads one shape — final on deploy-tag-fast and
@@ -1817,7 +1847,7 @@ function cmdReleaseCut(argv) {
1817
1847
  return verdict.ok || verdict.noop ? 0 : 1;
1818
1848
  }
1819
1849
 
1820
- print(`colab release cut${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} at ${at} (last final: ${lastFinal || 'none'})`);
1850
+ print(`colab release cut${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} at ${at}${sha !== head ? ` (main's head: ${shortSha(head)})` : ''} (last final: ${lastFinal || 'none'})`);
1821
1851
  if (verdict.signals) {
1822
1852
  print(' signals:');
1823
1853
  for (const l of verdict.signals.lines) print(` · ${l}`);
@@ -1830,7 +1860,7 @@ function cmdReleaseCut(argv) {
1830
1860
  ? '· no-op — nothing owed, inside release.final-spacing, or main\'s head already carries a final; nothing tagged.'
1831
1861
  : library
1832
1862
  ? '· no-op — nothing owed (the manifest still says the last final), or main\'s head already carries a final; nothing tagged.'
1833
- : '· no-op — nothing owed, inside the route\'s cadence window, or main\'s head is not a promotion of trunk; nothing cut.');
1863
+ : '· no-op — nothing owed, inside the route\'s cadence window, main\'s head is not a promotion of trunk, or a later commit already carries a candidate; nothing cut.');
1834
1864
  return 0;
1835
1865
  }
1836
1866
  if (!verdict.ok) {
@@ -17353,7 +17383,7 @@ Commands:
17353
17383
  release-notes [<range>] [--repo P] [--out F] [--headline "..."] grouped Markdown release summary
17354
17384
  release-status [<repo>...] [--repo P] [--json] merged-but-UNRELEASED lag on tag-gated repos —
17355
17385
  read-only, never tags (#81)
17356
- release cut [--repo P] [--bump patch|minor --reason R] [--dry] [--json] cut a release CANDIDATE
17386
+ release cut [--repo P] [--sha S] [--bump patch|minor --reason R] [--dry] [--json] cut a release CANDIDATE
17357
17387
  vX.Y.Z-rc.N where §6's rung allows it; never a final tag (#338)
17358
17388
  release finalize [--repo P] [--tag RC] [--answered-by N] [--dry] [--json] a candidate's next step:
17359
17389
  testing / held / new candidate owed / human handoff / final
@@ -87,7 +87,7 @@ const BUMPS = Object.freeze(['patch', 'minor']);
87
87
  const RELEASE_BRANCH = 'main';
88
88
 
89
89
  const CONDITIONS = Object.freeze([
90
- 'release-policy', 'cadence', 'spacing', 'promotion', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
90
+ 'release-policy', 'cadence', 'spacing', 'promotion', 'qualified-sha', 'prerelease-trigger', 'version', 'already-candidate', 'already-final',
91
91
  ...releaseTag.PRE_TAG_CONDITIONS,
92
92
  'ci-green', 'full-suite', 'schema-additive', 'switch-dependencies',
93
93
  'final-grant', 'release-hold', 'migration-grant',
@@ -515,6 +515,35 @@ function cadenceVerdict({ candidates, perDay, now }) {
515
515
  return { ok: false, detail: `${recent.length} candidate(s) in the last 24h (${recent.map((c) => c.name).join(', ')}) — release.candidates-per-day caps at ${perDay} a day; the first run from ${nextAt} cuts main's head, never an older commit`, nextAt };
516
516
  }
517
517
 
518
+ // ---- #622: a candidate at a named sha that is not main's head ----------------------------------
519
+
520
+ /**
521
+ * `release cut --sha <sha>` (#622): a busy trunk moves during every long qualifying suite, so the sha
522
+ * that went green is rarely still main's head when its run ends. The cut may name that sha instead —
523
+ * every other condition is already measured at the sha; this verdict answers only what is new about
524
+ * tagging a commit below the head. Null when the sha IS main's head (nothing new: today's cut).
525
+ *
526
+ * newer release tags (candidate or final) on a commit that DESCENDS from the sha — a CI run
527
+ * finishing out of order. A candidate here would move `next` backwards.
528
+ * finalRoute deploy-tag-fast / library-fast: their cut is a FINAL, and #622 is candidates-only —
529
+ * those routes keep tagging main's head.
530
+ * capped --auto under a declared release.candidates-per-day cap: a capped route spends its
531
+ * cut on the head (#443's "never an older commit").
532
+ *
533
+ * Returns { ok, detail, unread }. Not ok is a NO-OP under --auto (the head's own run cuts), a refusal
534
+ * by hand. `newer: null` = the tags could not be read — unread, never "none newer".
535
+ */
536
+ function qualifiedShaVerdict({ sha, head, newer, finalRoute = false, capped = false, auto = false }) {
537
+ const s = String(sha || '').slice(0, 7);
538
+ const h = String(head || '').slice(0, 7);
539
+ if (!sha || !head || sha === head) return null;
540
+ if (finalRoute) return { ok: false, detail: `${s} is not main's head (${h}) — this route's cut is a final, and a final is tagged only on main's head; --sha names a candidate (#622)` };
541
+ if (auto && capped) return { ok: false, detail: `${s} is not main's head (${h}) — under a release.candidates-per-day cap a cut is spent on the head, never an older commit (#443)` };
542
+ if (newer === null || newer === undefined) return { ok: false, unread: true, detail: `the release tags on commits after ${s} could not be read — an unread newer candidate is not an absent one` };
543
+ if (newer.length) return { ok: false, detail: `${newer.join(', ')} already names a commit after ${s} — a candidate here would move \`next\` backwards; the newer one stands` };
544
+ return { ok: true, detail: `${s} is below main's head (${h}) and no release tag names a later commit — the candidate is cut at ${s} (#622)` };
545
+ }
546
+
518
547
  // ---- #446: deploy-tag-fast — spacing and holds ------------------------------------------------
519
548
 
520
549
  /**
@@ -1032,6 +1061,14 @@ function decide(facts) {
1032
1061
  }
1033
1062
  }
1034
1063
 
1064
+ // #622: a cut at a named sha below main's head — only what is new about it; every other row is
1065
+ // already measured at the sha. Null (no row) when the sha is the head or no --sha was given.
1066
+ const q = f.qualified;
1067
+ if (q) {
1068
+ add('qualified-sha', q.ok, q.detail, isUnread(q));
1069
+ if (!q.ok && f.auto && !q.unread) noop = true;
1070
+ }
1071
+
1035
1072
  const trig = f.triggers || [];
1036
1073
  if (trig.length) add('prerelease-trigger', false, `a deploy would fire on a candidate tag: ${trig.map((t) => t.text).join('; ')}`);
1037
1074
  else add('prerelease-trigger', true, 'no deploy workflow fires on a pre-release tag');
@@ -1188,7 +1225,7 @@ module.exports = {
1188
1225
  CONDITIONS, FAST_CONDITIONS, STANDING_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
1189
1226
  isFastRoute, isLibraryRoute, decideManifestVersion, spacingVerdict, holdsVerdict, migrationHandoff,
1190
1227
  parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
1191
- parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
1228
+ parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict, qualifiedShaVerdict,
1192
1229
  fullSuiteVerdict, withoutOwnWorkflow, withoutSkippedOnlyWorkflows, isMigrationPath, schemaVerdict,
1193
1230
  parseSwitchMarkers, switchVerdict,
1194
1231
  promotionVerdict, decide, tagMessage, versionSourceOf,