@futurelastic/colab-handbook 1.12.0-rc.8 → 1.12.0-rc.9

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/README.md CHANGED
@@ -216,14 +216,15 @@ window between a CLI commit and the next tag, and the advertised remedy copies
216
216
  *from* that same working tree — so on a machine developing the handbook it
217
217
  advised services to adopt untagged code.) It never rewrites the copy, not even
218
218
  with `--apply`: that is the toolchain your running services are executing.
219
- `colab --version` says which of the two you are talking to. The frozen copy carries
219
+ `colab --version` says which of the two you are talking to (or `npm package` for an
220
+ `npx`/`npm i` install), and prints that install's version. The frozen copy carries
220
221
  `tools/` only, so `colab template` refuses there — run it from the working tree.
221
222
 
222
223
  **3. Verify, and register your repos.**
223
224
 
224
225
  ```sh
225
226
  colab --help # not found? fix your PATH — step 2 prints the exact line
226
- colab --version # which colab is this: the working tree, or the frozen copy?
227
+ colab --version # which colab is this — working tree, frozen copy, or npm package — and its version
227
228
  colab register /path/to/repo # once per repo — writes repos.txt AND config.json, so they agree
228
229
  node audit/audit.mjs # a conformance report across the whole fleet
229
230
  colab update # stamped copies that fell behind — the frozen CLI included
package/README.vi.md CHANGED
@@ -208,13 +208,14 @@ mọi máy bị đánh dấu cũ suốt quãng từ lúc commit CLI tới tag k
208
208
  phục được quảng cáo lại copy *từ* chính cây làm việc đó — nên trên máy đang phát
209
209
  triển handbook, nó khuyên các service nạp code chưa phát hành.) Nó không bao giờ
210
210
  ghi đè bản copy, kể cả với `--apply`: đó là bộ công cụ mà các service đang chạy
211
- của bạn đang thực thi. `colab --version` cho biết bạn đang nói chuyện với bản nào.
211
+ của bạn đang thực thi. `colab --version` cho biết bạn đang nói chuyện với bản nào (hoặc `npm package` khi
212
+ cài qua `npx`/`npm i`), kèm phiên bản của chính bản đó.
212
213
 
213
214
  **3. Kiểm lại, rồi chỉ cho audit biết phải soi repo nào.**
214
215
 
215
216
  ```sh
216
217
  colab --help # không thấy lệnh? sửa PATH — bước 2 in sẵn dòng cần thêm
217
- colab --version # colab nào đây: bản working tree hay bản đóng băng?
218
+ colab --version # colab nào đây — working tree, bản đóng băng hay npm package — và phiên bản của nó
218
219
  $EDITOR ~/.colab/repos.txt # thay các dòng ví dụ bằng repo của bạn
219
220
  node audit/audit.mjs # báo cáo conformance cho toàn bộ fleet
220
221
  colab update # các bản copy có đóng dấu đã tụt lại — kể cả CLI đóng băng
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.8"
30
+ "version": "1.12.0-rc.9"
31
31
  }
@@ -20,7 +20,7 @@ Starting points you **copy into your own repo**. That is the entire model.
20
20
  | `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node. Includes the sqlite bootstrap + explicit wayfinder step, and a `migrations` job that round-trips the schema (migrate → rollback → seed → migrate, schema compared) on the test engine **and** the deploy engine (a MariaDB/MySQL service container at production's version). Its data-dependent checks need `ROUNDTRIP_SEEDER` — see *Migration round-trip* below. |
21
21
  | `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. |
22
22
  | `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. |
23
- | `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, from a pinned handbook ref (`HANDBOOK_REF`) — 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; 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. |
23
+ | `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, 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. |
24
24
  | `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. |
25
25
  | `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 for a service's `init`. `*.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). |
26
26
  | `deploy-xserver.yml` | `.github/workflows/deploy-xserver.yml` | PHP-framework + Vite apps shipped to **shared hosting over SSH** (no root, no Docker): build on a runner, rsync, migrate on the server | Derived from three independently-written copies. Resolves Node the same way the CI templates do — all three hardcoded it, and one shipped on a different major than its CI built on. Migrates **production**; keeps a **mandatory** smoke test. Does **not** change your tier. |
@@ -69,7 +69,7 @@ a workflow.
69
69
 
70
70
  | File | Copy to | For | Notes |
71
71
  |---|---|---|---|
72
- | `pre-push-guard` | `<hooks>/pre-push` | Every repo with a protected trunk | Refuses a raw push to trunk, a declared integration line, or `main` on a repo that promotes. Reads `project.yml`; missing descriptor → allows, with a warning. |
72
+ | `pre-push-guard` | `<hooks>/pre-push` | Every repo with a protected trunk | Refuses a raw push to trunk, a declared integration line, or `main` on a repo that promotes, and the release channels `next` / `stable`, which only `colab release cut` / `finalize` move (#445). Reads `project.yml`; missing descriptor → allows, with a warning. |
73
73
  | `pre-commit-dispatch` | `<hooks>/pre-commit` | Any repo that needs **more than one** pre-commit check | Runs every hooklet in `pre-commit.d/`, fails if any failed, and **refuses when there is nothing to run**. Read its header before installing — it replaces a hook you already have, and step 2 of its instructions is where your existing check survives. |
74
74
  | `pre-commit-identity` | `<hooks>/pre-commit.d/20-identity` | Any repo that could publish an identity — every public one, and any private one that may ever be opened | Scans staged content against a vocabulary the operator supplies **by path**. Also installs as `commit-msg`. |
75
75
  | `identity-vocabulary.example` | *outside every repo* — e.g. `~/.colab/identity-vocabulary` | The above | Invented entries. **A real one is never committed anywhere**, which is the whole reason the scanner takes a path instead of shipping a list. |
@@ -9,10 +9,14 @@
9
9
  # COLAB_SHIP does NOT open main — ship is trunk/line-only by design.
10
10
  # The guard keys on `trunk != main`, never on the tier letter, so tier C is covered
11
11
  # automatically — main there is what promotion deploys, so it needs the gate most.
12
+ # RELEASE CHANNELS `next` and `stable` (#445): allowed by COLAB_RELEASE=1 (`colab release cut` moves
13
+ # `next`, `colab release finalize` moves `stable`) or COLAB_HUMAN=1. Nothing else writes them —
14
+ # they name the newest candidate and the newest final, and a hand push makes them lie. A repo that
15
+ # uses a branch of either name for something else edits its copy of this hook (copy-and-own).
12
16
  # On tier B (trunk == main) the trunk rule already covers main. Non-protected pushes always pass.
13
17
  # Missing .github/project.yml → degrade to ALLOW (with a warning) rather than block work.
14
18
  #
15
- # The two variables named above are set BY A TOOL (`colab ship`, `colab promote`) or BY A PERSON at
19
+ # The variables named above are set BY A TOOL (`colab ship`, `colab promote`, `colab release`) or BY A PERSON at
16
20
  # the keyboard — never by an agent reading this file or one of the refusals below. COLAB_SHIP is a
17
21
  # process-identity assertion, not a permission: typed by hand it claims preconditions nothing ran.
18
22
  # The refusal messages below therefore name the remedy and not the variable (#322) — this header is
@@ -51,10 +55,13 @@ integration=$(awk '
51
55
  pushing_trunk=0
52
56
  pushing_main=0
53
57
  pushing_line=""
58
+ pushing_channel=""
54
59
  while read -r _localref _localsha remoteref _remotesha; do
55
60
  case "${remoteref:-}" in
56
61
  refs/heads/"$trunk") pushing_trunk=1 ;;
57
62
  refs/heads/main) pushing_main=1 ;;
63
+ refs/heads/next) pushing_channel=next ;;
64
+ refs/heads/stable) pushing_channel=stable ;;
58
65
  esac
59
66
  for line in $integration; do
60
67
  if [ "${remoteref:-}" = "refs/heads/$line" ]; then pushing_line="$line"; fi
@@ -105,6 +112,19 @@ if [ -n "$pushing_line" ] && [ "${COLAB_SHIP:-}" != "1" ] && [ "${COLAB_HUMAN:-}
105
112
  exit 1
106
113
  fi
107
114
 
115
+ # RELEASE-CHANNEL guard (#445) — `next` / `stable` move only with a release, forward only.
116
+ if [ -n "$pushing_channel" ] && [ "${COLAB_RELEASE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
117
+ echo "pre-push-guard: refusing raw push to release channel '$pushing_channel'." >&2
118
+ echo " It names the newest $( [ "$pushing_channel" = next ] && echo candidate || echo final ) and moves only with one:" >&2
119
+ if [ "$pushing_channel" = next ]; then
120
+ echo " colab release cut # a new candidate fast-forwards 'next'" >&2
121
+ else
122
+ echo " colab release finalize # a new final fast-forwards 'stable'" >&2
123
+ fi
124
+ echo " To follow a different version, pin its tag where you consume it; the channel stays where it is." >&2
125
+ exit 1
126
+ fi
127
+
108
128
  # MAIN guard — only on tier A and C (trunk != main). COLAB_SHIP intentionally does NOT open main.
109
129
  if [ "$trunk" != "main" ] && [ "$pushing_main" -eq 1 ] && [ "${COLAB_PROMOTE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
110
130
  echo "pre-push-guard: refusing raw push to 'main' (promotion target)." >&2
@@ -124,9 +124,14 @@ concurrency:
124
124
  permissions: {}
125
125
 
126
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"
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"
130
135
  HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
131
136
 
132
137
  jobs:
package/tools/colab CHANGED
@@ -63,6 +63,7 @@ const releasePolicy = require('./lib/release-policy');
63
63
  const workflowTriggers = require('./lib/workflow-triggers');
64
64
  const releaseCut = require('./lib/release-cut');
65
65
  const releaseFinalize = require('./lib/release-finalize');
66
+ const releaseChannel = require('./lib/release-channel');
66
67
  const shippedBranch = require('./lib/shipped-branch');
67
68
  const shipRoles = require('./lib/ship-roles'); // #372
68
69
  const refsBrake = require('./lib/refs-brake'); // #385
@@ -1244,6 +1245,11 @@ Every cut also publishes the candidate's GitHub pre-release (#443): notes = the
1244
1245
  since the last final plus the tag message. Best-effort — a failure warns (--json published.ok false)
1245
1246
  and never undoes the pushed tag.
1246
1247
 
1248
+ Every cut also fast-forwards the release channel \`next\` — a branch, always the newest candidate
1249
+ (#445) — to the candidate's commit, pushed with COLAB_RELEASE=1 (what pre-push-guard lets through).
1250
+ Forward only, never forced: a \`next\` that is not an ancestor of the candidate is reported and left
1251
+ alone. Best-effort like the pre-release (--json channel.ok false); the tag stands either way.
1252
+
1247
1253
  Needs origin reachable (the tag is recorded there) and gh usable (CI, suite and switch markers are
1248
1254
  read from GitHub). Exit code: 0 when a candidate was cut (or, with --dry, would be), or an --auto
1249
1255
  no-op; 1 when refused.
@@ -1508,11 +1514,16 @@ function cmdReleaseCut(argv) {
1508
1514
  created = true;
1509
1515
  published = publishPrerelease(repoAbs, { tag: verdict.tag, lastFinal, message });
1510
1516
  }
1517
+ // #445: the `next` channel names the newest candidate — fast-forwarded in the run that pushed it.
1518
+ // Best-effort like the pre-release: the tag already stands, so a channel that cannot move is reported.
1519
+ const channel = verdict.ok && verdict.tag
1520
+ ? releaseChannel.moveChannel(repoAbs, { remote, channel: releaseChannel.CHANNELS.next, sha, label: verdict.tag, dry: !!opts.dry })
1521
+ : null;
1511
1522
 
1512
1523
  if (opts.json) {
1513
1524
  print(JSON.stringify({
1514
1525
  repo: shortRepo(repoAbs), sha, ...(offTrunk ? { trunk } : {}), lastFinal, suggestion, dry: !!opts.dry, auto: !!opts.auto,
1515
- ok: verdict.ok, noop: !!verdict.noop, tag: verdict.tag, created, published, version: verdict.version, bump: verdict.bump,
1526
+ ok: verdict.ok, noop: !!verdict.noop, tag: verdict.tag, created, published, channel, version: verdict.version, bump: verdict.bump,
1516
1527
  overridden: verdict.overridden, signals: verdict.signals ? verdict.signals.lines : null, checks: verdict.checks,
1517
1528
  }, null, 2));
1518
1529
  return verdict.ok || verdict.noop ? 0 : 1;
@@ -1534,12 +1545,14 @@ function cmdReleaseCut(argv) {
1534
1545
  print(`✗ refused — ${verdict.refusals.length} condition(s) failed; nothing cut.`);
1535
1546
  return 1;
1536
1547
  }
1537
- if (opts.dry) print(`[--dry] would create ${verdict.tag} on ${at}, push it to ${remote} and publish its GitHub pre-release. Nothing created.`);
1548
+ if (opts.dry) print(`[--dry] would create ${verdict.tag} on ${at}, push it to ${remote}, publish its GitHub pre-release and move the next channel. Nothing created.`);
1538
1549
  else {
1539
1550
  print(`✓ cut ${verdict.tag} on ${at} and pushed it to ${remote} — a candidate, not a release; finalizing it is the release skill's.`);
1540
1551
  if (published && published.ok) print(`✓ ${published.detail}`);
1541
1552
  else if (published) warn(`${published.detail} — the tag stands; publish it by hand: gh release create ${verdict.tag} --verify-tag --prerelease --latest=false`);
1542
1553
  }
1554
+ if (channel && channel.ok) print(`${opts.dry ? '·' : '✓'} ${channel.detail}`);
1555
+ else if (channel) warn(`${channel.detail} — the tag stands`);
1543
1556
  return 0;
1544
1557
  }
1545
1558
 
@@ -1627,6 +1640,10 @@ under CONVENTIONS.md §6's release rung, re-checking everything at the moment it
1627
1640
  in a commit since the previous final) gets one comment: "Released in vX.Y.Z"
1628
1641
  (with --dry: every check passed, nothing written)
1629
1642
 
1643
+ A final also fast-forwards the release channel \`stable\` — a branch, always the newest final (#445)
1644
+ — to its commit; already-final repairs a \`stable\` a dead run left behind. Forward only, never
1645
+ forced, best-effort (--json channel); the final tag stands either way.
1646
+
1630
1647
  Conditions (--json checks[].condition; required:false means reported, not blocking, on this row):
1631
1648
  release-policy candidate tracking-issue release-hold regressions test-period trunk-green
1632
1649
  ci-green full-suite schema-additive switch-dependencies final-grant migration-grant human
@@ -1664,6 +1681,7 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
1664
1681
  --json { repo, row, route, final, testPeriodDays, lastFinal, dry, auto, candidate, tracking,
1665
1682
  periodStart, periodEndsAt, state, tagged, finalTag, checks, handoff,
1666
1683
  skipped (--auto: [{tag, state, detail?}] — the other open candidates),
1684
+ channel (null, or {channel, ok, action, detail} — the stable move, #445),
1667
1685
  announced (null, or {range, issues, posted, skipped} — the "Released in" comments),
1668
1686
  grant (null, or {issue, ruledBy} — the operator grant that made this final automatic) }
1669
1687
 
@@ -1838,6 +1856,7 @@ function cmdReleaseFinalize(argv) {
1838
1856
 
1839
1857
  // ---- writes ----
1840
1858
  let tagged = false;
1859
+ let channel = null; // #445: { channel, ok, action, detail } once `stable` was (or could not be) moved
1841
1860
  const comment = (num, fields, text) => {
1842
1861
  const view = git.ghIssueView(repoAbs, num, ['comments']);
1843
1862
  if (view && releaseFinalize.hasEvent(view.comments, fields)) return;
@@ -1880,6 +1899,13 @@ function cmdReleaseFinalize(argv) {
1880
1899
  }
1881
1900
  tagged = true;
1882
1901
  }
1902
+ // #445: the `stable` channel names the newest final — moved by the run that tags it, and repaired
1903
+ // on the already-final resume (a run that died between the tag push and the move finishes it).
1904
+ if (tagged) channel = releaseChannel.moveChannel(repoAbs, { remote, channel: releaseChannel.CHANNELS.stable, sha: cand.sha, label: cand.version });
1905
+ else if (verdict.state === 'already-final' && version0) {
1906
+ const finalTag = tags.find((t) => t.name === version0);
1907
+ if (finalTag) channel = releaseChannel.moveChannel(repoAbs, { remote, channel: releaseChannel.CHANNELS.stable, sha: finalTag.sha, label: version0 });
1908
+ }
1883
1909
  // The newest candidate is announced on its version's issue — on --auto with its own clock.
1884
1910
  const tNew = version0 ? trackings.get(version0) : null;
1885
1911
  if (newest && tNew && tNew.number) {
@@ -1929,7 +1955,7 @@ function cmdReleaseFinalize(argv) {
1929
1955
  lastFinal, dry: !!opts.dry, auto: !!opts.auto, candidate: cand, tracking: trackingOut,
1930
1956
  periodStart: period ? period.start : null, periodEndsAt: period ? period.endsAt : null,
1931
1957
  state: verdict.state, tagged, finalTag: verdict.finalTag, checks: verdict.checks, handoff: verdict.handoff,
1932
- skipped: walk ? skipped : undefined, announced, grant: verdict.grant || null,
1958
+ skipped: walk ? skipped : undefined, announced, grant: verdict.grant || null, channel,
1933
1959
  }, null, 2));
1934
1960
  } else {
1935
1961
  print(`colab release finalize${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} (last final: ${lastFinal || 'none'}${cand ? `, candidate: ${cand.tag}` : ''})`);
@@ -1942,6 +1968,8 @@ function cmdReleaseFinalize(argv) {
1942
1968
  print('');
1943
1969
  print(`state: ${verdict.state}${opts.dry ? ' [--dry: nothing written]' : ''}${tagged ? ` — tagged ${verdict.finalTag} and pushed it to ${remote}` : ''}`);
1944
1970
  if (announced && announced.issues.length) print(`released in ${verdict.finalTag || version0}: told ${announced.posted.length ? announced.posted.map((n) => `#${n}`).join(', ') : 'nobody new'} (carried: ${announced.issues.map((n) => `#${n}`).join(', ')}${announced.skipped.length ? `; unreadable: ${announced.skipped.map((n) => `#${n}`).join(', ')}` : ''})`);
1971
+ if (channel && channel.ok) print(`✓ ${channel.detail}`);
1972
+ else if (channel) warn(`${channel.detail} — the final tag stands`);
1945
1973
  if (verdict.handoff) print(`\nThe final is a human act here. The one command, for a human to run:\n ${verdict.handoff}`);
1946
1974
  }
1947
1975
  // #423: on --auto, "nothing to do yet" (still testing, no candidate) is the workflow's ordinary output.
@@ -8187,20 +8215,31 @@ function readFrozenStamp(dir) {
8187
8215
  function selfProvenance() {
8188
8216
  const st = readFrozenStamp(__dirname);
8189
8217
  if (st && st.name === stamp.FROZEN_STAMP_NAME) {
8190
- return { frozen: true, version: st.version, source: __dirname, branch: null };
8218
+ return { kind: 'frozen', frozen: true, version: st.version, source: __dirname, branch: null };
8191
8219
  }
8192
8220
  const { root } = handbookPaths();
8221
+ // A registry install (npx, npm i) — before the git read below, which has no repo of its own to
8222
+ // answer from there and would walk up into whatever repo the npx cache happens to sit inside (#444).
8223
+ const pkg = stamp.npmPackageInfo(root);
8224
+ if (pkg) return { kind: 'npm', frozen: false, version: pkg.version, source: root, branch: null };
8193
8225
  const hb = stamp.handbookInfo(root);
8194
8226
  const br = stamp.gitIn(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
8195
- return { frozen: false, version: hb.version, source: root, branch: br.ok && br.out ? br.out : null };
8227
+ return { kind: 'working-tree', frozen: false, version: hb.version, source: root, branch: br.ok && br.out ? br.out : null };
8228
+ }
8229
+
8230
+ /**
8231
+ * One version, from whichever provenance applies — there used to be a second, hard-coded
8232
+ * `colab 1.0.0` in front of it that no release ever moved (#444).
8233
+ */
8234
+ function versionLine(self) {
8235
+ const where = self.kind === 'frozen' ? `frozen copy: ${self.source}`
8236
+ : self.kind === 'npm' ? `npm package: ${self.source}`
8237
+ : `working tree: ${self.source}${self.branch ? `, branch ${self.branch}` : ''}`;
8238
+ return `colab ${self.version} (${where})`;
8196
8239
  }
8197
8240
 
8198
8241
  function cmdVersion() {
8199
- const self = selfProvenance();
8200
- const where = self.frozen
8201
- ? `frozen copy: ${self.source}`
8202
- : `working tree: ${self.source}${self.branch ? `, branch ${self.branch}` : ''}`;
8203
- return print(`colab 1.0.0 — colab-handbook ${self.version} (${where})`);
8242
+ return print(versionLine(selfProvenance()));
8204
8243
  }
8205
8244
 
8206
8245
  /** Current handbook version = nearest RELEASE tag (pre-releases skipped, #334); 'v0' before the first one. */
@@ -0,0 +1,99 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/release-channel.js — the release CHANNELS `next` and `stable` (#445).
4
+ *
5
+ * Adopters follow a channel, not a hand-bumped pin:
6
+ *
7
+ * next always the newest CANDIDATE (vX.Y.Z-rc.N) — moved by `colab release cut`
8
+ * stable always the newest FINAL (vX.Y.Z) — moved by `colab release finalize`
9
+ *
10
+ * They are BRANCHES, not tags. A moving tag is refused by every clone that already fetched it
11
+ * (`would clobber existing tag`), and a non-semver tag can be read as "the newest version" by tag
12
+ * readers (`git describe --tags`, stamps). A branch moves cleanly and no tag reader sees it. Version
13
+ * tags stay immutable.
14
+ *
15
+ * Forward only. A channel is fast-forwarded to the commit the tag names, never forced: a channel
16
+ * that is not an ancestor of that commit is a finding (somebody moved it by hand, or a branch of the
17
+ * same name means something else in this repo) and is reported, never overwritten. `stable` lagging
18
+ * behind `next` is the design, not drift — they are two channels, each moving forward on its own.
19
+ *
20
+ * Best-effort, like the GitHub pre-release (#443): the tag is already on the remote when a channel
21
+ * moves, so a channel that could not move is reported (warning, --json `channel.ok: false`) and
22
+ * never a reason to undo the tag. The next cut / finalize retries, and finalize's already-final path
23
+ * repairs a `stable` a dead run left behind.
24
+ *
25
+ * The push carries COLAB_RELEASE=1 — the process-identity assertion templates/pre-push-guard reads
26
+ * for these two refs, the COLAB_SHIP precedent. Nothing else writes them.
27
+ *
28
+ * Two halves: decideMove is pure (facts in, an action out); moveChannel measures and writes through
29
+ * git, on the remote it is given.
30
+ */
31
+
32
+ const git = require('./git');
33
+
34
+ const CHANNELS = Object.freeze({ next: 'next', stable: 'stable' });
35
+ /** The env a release command pushes a channel with — what pre-push-guard lets through. */
36
+ const RELEASE_ENV = 'COLAB_RELEASE';
37
+
38
+ /**
39
+ * What to do with `channel`, given where it is now and where it should be.
40
+ *
41
+ * current the channel's commit on the remote, or null when the branch does not exist
42
+ * target the commit the tag names
43
+ * currentIsAncestor current is an ancestor of target (a fast-forward)
44
+ * targetIsAncestor target is an ancestor of current (the channel is already past it)
45
+ *
46
+ * Returns { action: 'create' | 'move' | 'noop' | 'refuse', detail }.
47
+ */
48
+ function decideMove({ channel, current, target, label, currentIsAncestor, targetIsAncestor }) {
49
+ const at = label ? `${label} (${short(target)})` : short(target);
50
+ if (!target) return { action: 'refuse', detail: `${channel}: no target commit` };
51
+ if (!current) return { action: 'create', detail: `${channel} created at ${at}` };
52
+ if (current === target) return { action: 'noop', detail: `${channel} already at ${at}` };
53
+ if (currentIsAncestor) return { action: 'move', detail: `${channel} fast-forwarded ${short(current)} -> ${at}` };
54
+ if (targetIsAncestor) return { action: 'noop', detail: `${channel} already past ${at} (at ${short(current)}) — a channel only moves forward` };
55
+ return {
56
+ action: 'refuse',
57
+ detail: `${channel} NOT moved: it is at ${short(current)}, which is not an ancestor of ${at} — a channel only fast-forwards; find out who moved it before moving it back by hand`,
58
+ };
59
+ }
60
+
61
+ function short(sha) { return sha ? String(sha).slice(0, 7) : '—'; }
62
+
63
+ /**
64
+ * Move `channel` on `remote` to `sha` (the commit `label`, a tag, names). Forward only, never forced.
65
+ * Returns { channel, ok, action, detail } — ok is false only on a refusal or a failed push/read.
66
+ * With `dry`, measures and reports what it would do, writing nothing.
67
+ */
68
+ function moveChannel(repoAbs, { remote, channel, sha, label, dry = false, env = process.env }) {
69
+ const fail = (detail) => ({ channel, ok: false, action: 'refuse', detail });
70
+ const ls = git.git(['ls-remote', '--heads', remote, `refs/heads/${channel}`], repoAbs);
71
+ if (!ls.ok) return fail(`${channel} NOT moved: could not read it on ${remote} (${(ls.stderr || '').split('\n')[0] || ls.code})`);
72
+ const line = ls.stdout.split('\n').find((l) => l.endsWith(`\trefs/heads/${channel}`));
73
+ const current = line ? line.split('\t')[0] : null;
74
+
75
+ let currentIsAncestor = false;
76
+ let targetIsAncestor = false;
77
+ if (current && current !== sha) {
78
+ // The channel's commit is not necessarily local yet (a clone that never fetched the branch).
79
+ const have = git.git(['cat-file', '-e', `${current}^{commit}`], repoAbs);
80
+ if (!have.ok) {
81
+ const f = git.git(['fetch', '--quiet', remote, `refs/heads/${channel}`], repoAbs);
82
+ if (!f.ok) return fail(`${channel} NOT moved: could not fetch it from ${remote} to check it only moves forward (${(f.stderr || '').split('\n')[0] || f.code})`);
83
+ }
84
+ currentIsAncestor = git.git(['merge-base', '--is-ancestor', current, sha], repoAbs).ok;
85
+ if (!currentIsAncestor) targetIsAncestor = git.git(['merge-base', '--is-ancestor', sha, current], repoAbs).ok;
86
+ }
87
+
88
+ const d = decideMove({ channel, current, target: sha, label, currentIsAncestor, targetIsAncestor });
89
+ if (d.action === 'refuse') return { channel, ok: false, ...d };
90
+ if (d.action === 'noop' || dry) return { channel, ok: true, ...d, ...(dry && d.action !== 'noop' ? { detail: `[--dry] would be: ${d.detail}` } : {}) };
91
+
92
+ // No --force, no lease: git itself refuses a non-fast-forward, so a channel moved meanwhile is
93
+ // refused here too rather than overwritten.
94
+ const push = git.run('git', ['push', remote, `${sha}:refs/heads/${channel}`], { cwd: repoAbs, env: { ...env, [RELEASE_ENV]: '1' } });
95
+ if (!push.ok) return fail(`${channel} NOT moved: git push ${remote} ${short(sha)}:refs/heads/${channel} failed (${(push.stderr || '').split('\n').filter(Boolean).pop() || push.code})`);
96
+ return { channel, ok: true, ...d };
97
+ }
98
+
99
+ module.exports = { CHANNELS, RELEASE_ENV, decideMove, moveChannel };
@@ -86,6 +86,43 @@ function packageVersion(root) {
86
86
  }
87
87
  }
88
88
 
89
+ /** The npm name this CLI publishes under — must equal the root package.json's `name` (a test pins it). */
90
+ const PACKAGE_NAME = '@futurelastic/colab-handbook';
91
+
92
+ /** True when `root` is its own git checkout — the toplevel git finds IS `root`, not an enclosing repo. */
93
+ function ownsGit(root) {
94
+ const top = gitIn(root, ['rev-parse', '--show-toplevel']);
95
+ return top.ok && realPath(top.out) === realPath(require('path').resolve(root));
96
+ }
97
+
98
+ /**
99
+ * `{ root, version }` when `root` is THIS CLI installed from the npm registry, else null (#444).
100
+ *
101
+ * Three conditions, all required:
102
+ * - no git of its own (an enclosing repo does not count — see handbookInfo);
103
+ * - `<root>/package.json` names this package, so an unrelated package.json never qualifies;
104
+ * - `root` sits under a `node_modules/` directory. Without this, a handbook working tree that is
105
+ * file-synced to another machine with its `.git` deliberately left behind would pass the first
106
+ * two and be reported as a registry install. npx, `npm i` and `npm i -g` all install there.
107
+ *
108
+ * `version` is package.json's verbatim — a candidate's `1.12.0-rc.8` included. That is the point:
109
+ * this answers "which build is running", where handbookInfo answers "what may I stamp with", and a
110
+ * candidate is never the latter (#334) — so its stricter packageVersion is right for it, wrong here.
111
+ */
112
+ function npmPackageInfo(root) {
113
+ const p = require('path');
114
+ if (!p.resolve(root).split(p.sep).includes('node_modules')) return null;
115
+ let j;
116
+ try {
117
+ j = JSON.parse(require('fs').readFileSync(p.join(root, 'package.json'), 'utf8'));
118
+ } catch (_) {
119
+ return null;
120
+ }
121
+ if (!j || j.name !== PACKAGE_NAME || typeof j.version !== 'string' || !j.version) return null;
122
+ if (ownsGit(root)) return null;
123
+ return { root, version: j.version };
124
+ }
125
+
89
126
  /**
90
127
  * The handbook's own identity: { root, hasGit, untagged, version }.
91
128
  * Before the first tag exists the version is 'v0' and `untagged` is true, which DEACTIVATES stamp
@@ -693,7 +730,7 @@ module.exports = {
693
730
  FROZEN_STAMP_NAME, FROZEN_STAMP_FILE, FROZEN_SOURCES, classifyFrozen,
694
731
  AUTHORITY_FLIP_VERSION,
695
732
  gitIn, gitCommonDir, isHandbookItself,
696
- handbookInfo, freezeVersion, templateNames, templateFiles, templateChangedSince, templateAt,
733
+ handbookInfo, PACKAGE_NAME, npmPackageInfo, freezeVersion, templateNames, templateFiles, templateChangedSince, templateAt,
697
734
  AXES, axesPredating,
698
735
  WRITES_VETO_MARKER, writesRulingKnownAt,
699
736
  stampLine, stampCommentPrefix, insertStamp, parseWorkflowStamp, parseClaudeStamp,