@futurelastic/colab-handbook 1.18.0-rc.12 → 1.18.0-rc.13

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 (2) hide show
  1. package/package.json +1 -1
  2. package/tools/colab +48 -5
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.18.0-rc.12"
36
+ "version": "1.18.0-rc.13"
37
37
  }
package/tools/colab CHANGED
@@ -3950,6 +3950,8 @@ change. Nothing else can produce a grant — no --force on ship, no project.yml
3950
3950
  from an issue's content, age or park count. A human act on the issue is the whole answer.
3951
3951
 
3952
3952
  colab migration-grant <N> --branch <branch> grant #N an exemption, bound to <branch>
3953
+ colab migration-grant <N> --branch vX.Y.Z on a release tracking issue: bound to that version
3954
+ (#677 — the command a release hand-off prints)
3953
3955
  colab migration-grant <N> --revoke revoke #N's grant (idempotent — safe if none exists)
3954
3956
  colab migration-grant --list [--json] list every issue with a live grant right now
3955
3957
 
@@ -3975,6 +3977,13 @@ Revoking removes the label FIRST (the gate is restored the same minute) and post
3975
3977
  grantor — any revoke comment cancels every live grant on that issue, because a safety gate should
3976
3978
  fail toward "closed" if either half only partially lands.
3977
3979
 
3980
+ A RELEASE VERSION (#677). --branch must name a ref (a local branch or origin's copy) — with one
3981
+ exception: a human grant naming a final version \`vX.Y.Z\` that is not a ref, on the issue whose body
3982
+ starts with that version's tracking marker (\`<!-- colab:release version=vX.Y.Z -->\`). That is the
3983
+ grant a release hand-off asks for (\`colab release cut --auto\` on deploy-tag-fast, and a deploy-tag
3984
+ candidate): the version becomes a tag only after the grant, and the release gate reads the grant
3985
+ against the version. Any other version — a typo, or one #N does not track — is refused, nothing posted.
3986
+
3978
3987
  There is deliberately no local-only fallback: without a usable \`gh\`, every subcommand here REFUSES
3979
3988
  rather than write (or read) something invisible to the machine \`ship\` might later run on.
3980
3989
 
@@ -4064,7 +4073,15 @@ function cmdMigrationGrant(argv) {
4064
4073
  if (!opts.revoke && !opts.branch) {
4065
4074
  throw new UserError('--branch <branch> is required — a grant is bound to one branch, never inferred from the current checkout');
4066
4075
  }
4067
- if (!opts.revoke && !git.branchExists(repoAbs, opts.branch)) {
4076
+ // #677: a release version is the one binding name that is not a ref when it is granted — on route
4077
+ // deploy-tag-fast (and a deploy-tag candidate) the grant is what lets `vX.Y.Z` be tagged at all,
4078
+ // and the release gate compares the grant against the computed version, never a ref. So a human
4079
+ // grant naming a canonical final version is deferred here to cmdMigrationGrantCreate, which accepts
4080
+ // it only when #N's tracking marker names exactly that version: a typo is still refused, just one
4081
+ // step later (it needs the tracker). Any other name — and a reviewer grant, which binds a pushed
4082
+ // HEAD — keeps the ref check below, unchanged.
4083
+ if (!opts.revoke) opts.versionBinding = migrationGrantVersionBinding(repoAbs, opts);
4084
+ if (!opts.revoke && !opts.versionBinding && !git.branchExists(repoAbs, opts.branch)) {
4068
4085
  throw new UserError(`branch "${opts.branch}" does not resolve to a ref (locally or on origin) — refusing to bind a grant to a name nothing exists at`);
4069
4086
  }
4070
4087
  // #397: the role, and for a reviewer grant its whole record — all answerable locally, so all
@@ -4085,6 +4102,19 @@ function cmdMigrationGrant(argv) {
4085
4102
  return opts.revoke ? cmdMigrationGrantRevoke(repoAbs, num) : cmdMigrationGrantCreate(repoAbs, num, opts);
4086
4103
  }
4087
4104
 
4105
+ /**
4106
+ * #677: true when this grant binds a release VERSION rather than a branch — a human grant whose
4107
+ * --branch is a canonical final version (`vX.Y.Z`, never an `-rc.N`) that resolves to no ref here.
4108
+ * Local only, so it runs before the gh gate; cmdMigrationGrantCreate then holds it to the issue's
4109
+ * tracking marker (`<!-- colab:release version=vX.Y.Z -->`). A ref of that name wins: the grant is
4110
+ * an ordinary branch grant and nothing about it changes.
4111
+ */
4112
+ function migrationGrantVersionBinding(repoAbs, opts) {
4113
+ if (opts.role !== undefined && String(opts.role) !== 'human') return false;
4114
+ if (!releaseCut.parseVersion(opts.branch)) return false;
4115
+ return !git.branchExists(repoAbs, opts.branch);
4116
+ }
4117
+
4088
4118
  /**
4089
4119
  * #397: resolve the grant's role and, for a reviewer grant, build and check its review record.
4090
4120
  * Returns null for a human grant (the unchanged path). Throws UserError on anything a reviewer
@@ -4205,15 +4235,23 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
4205
4235
  if (!opts.branch) {
4206
4236
  throw new UserError('--branch <branch> is required — a grant is bound to one branch, never inferred from the current checkout');
4207
4237
  }
4208
- if (!git.branchExists(repoAbs, opts.branch)) {
4238
+ if (!opts.versionBinding && !git.branchExists(repoAbs, opts.branch)) {
4209
4239
  throw new UserError(`branch "${opts.branch}" does not resolve to a ref (locally or on origin) — refusing to bind a grant to a name nothing exists at`);
4210
4240
  }
4211
4241
 
4212
- const info = git.ghIssueView(repoAbs, num, ['state', 'labels']);
4242
+ const info = git.ghIssueView(repoAbs, num, opts.versionBinding ? ['state', 'labels', 'body'] : ['state', 'labels']);
4213
4243
  if (!info) throw new UserError(`could not read #${num} from the tracker — refusing to write a grant blind`);
4214
4244
  if (info.state !== 'OPEN') {
4215
4245
  throw new UserError(`#${num} is ${info.state} — a grant expires the instant its issue closes, so granting a closed one would do nothing (CONVENTIONS.md §5, Migration exemption)`);
4216
4246
  }
4247
+ // #677: a version-bound grant stands on the tracking marker in place of a ref — the name must be
4248
+ // exactly the version #N tracks, so a typo still binds nothing.
4249
+ if (opts.versionBinding) {
4250
+ const tracked = releaseFinalize.parseReleaseMarker(info.body);
4251
+ if (tracked !== opts.branch) {
4252
+ throw new UserError(`"${opts.branch}" is not a ref, and #${num} ${tracked ? `tracks ${tracked}, not ${opts.branch}` : 'carries no release tracking marker (<!-- colab:release version=vX.Y.Z -->)'} — a version is granted only on its own tracking issue; nothing was posted. Re-run with the version #${num} tracks, or the branch the migration is on: COLAB_HUMAN=1 colab migration-grant ${num} --branch ${tracked || '<branch>'}`);
4253
+ }
4254
+ }
4217
4255
 
4218
4256
  const present = git.ghListLabels(repoAbs);
4219
4257
  if (present && !present.includes(labels.MIGRATION_GRANT_LABEL)) {
@@ -4253,8 +4291,13 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
4253
4291
  print(` Revoke any time: colab migration-grant ${num} --revoke`);
4254
4292
  return 0;
4255
4293
  }
4256
- print(`Granted #${num} in ${shortRepo(repoAbs)} a migration exemption for branch "${opts.branch}".`);
4257
- print(` This covers ONLY this branch, and expires the moment #${num} closes.`);
4294
+ if (opts.versionBinding) {
4295
+ print(`Granted #${num} in ${shortRepo(repoAbs)} a migration exemption for release ${opts.branch}.`);
4296
+ print(` This covers ONLY that version's final, and expires the moment #${num} closes. The next green release run tags it.`);
4297
+ } else {
4298
+ print(`Granted #${num} in ${shortRepo(repoAbs)} a migration exemption for branch "${opts.branch}".`);
4299
+ print(` This covers ONLY this branch, and expires the moment #${num} closes.`);
4300
+ }
4258
4301
  print(` Revoke any time: colab migration-grant ${num} --revoke`);
4259
4302
  // Deliberately no pushEvent — see HELP_SHIP's JSON note: no receiver-agreed kind exists for
4260
4303
  // this yet, and both markers are already visible on the tracker from any machine.