@futurelastic/colab-handbook 1.17.0-rc.4 → 1.17.1-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.17.0-rc.4"
36
+ "version": "1.17.1-rc.1"
37
37
  }
package/tools/colab CHANGED
@@ -1763,8 +1763,8 @@ function cmdReleaseCut(argv) {
1763
1763
  let heavy = null;
1764
1764
  if (fast || library) {
1765
1765
  const lane = heavyLaneAt(repoAbs, doc, sha);
1766
- heavy = integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `main@${shortSha(sha)}`, ref: 'main' });
1767
- if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha);
1766
+ heavy = integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `main@${shortSha(sha)}`, ref: 'main', inputs: lane.inputs });
1767
+ if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha, lane.inputs);
1768
1768
  }
1769
1769
 
1770
1770
  // #622: a cut below main's head — refused (a no-op under --auto) when a release tag already names a
@@ -2084,7 +2084,7 @@ function readRegressionEdges(repoAbs, num) {
2084
2084
  */
2085
2085
  function releaseHeavyFact(repoAbs, doc, cand) {
2086
2086
  const lane = heavyLaneAt(repoAbs, doc, cand.sha);
2087
- return integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `${cand.tag}@${shortSha(cand.sha)}`, ref: cand.tag });
2087
+ return integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `${cand.tag}@${shortSha(cand.sha)}`, ref: cand.tag, inputs: lane.inputs });
2088
2088
  }
2089
2089
 
2090
2090
  function cmdReleaseFinalize(argv) {
@@ -14402,7 +14402,7 @@ function cmdShip(argv) {
14402
14402
  // ---- (b6) #610: gated — the heavy lane must be green at the branch head before trunk moves ----
14403
14403
  if (heavyGate && !heavyGate.ok) {
14404
14404
  print(`⏸ HEAVY-PENDING ${sess.branch} — ${heavyGate.detail}. Nothing landed.`);
14405
- if (heavyGate.action === 'dispatch' && gh) dispatchHeavyLane(repoAbs, heavyGate.file, sess.branch, heavyGate.sha);
14405
+ if (heavyGate.action === 'dispatch' && gh) dispatchHeavyLane(repoAbs, heavyGate.file, sess.branch, heavyGate.sha, heavyGate.inputs);
14406
14406
  else print(' Wait on the heavy run (bounded, B1a), then run this command again.');
14407
14407
  return 3;
14408
14408
  }
@@ -15189,7 +15189,7 @@ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
15189
15189
  function heavyLaneAt(repoAbs, doc, sha) {
15190
15190
  const file = integrationProfile.parseHeavyWorkflow(doc).file;
15191
15191
  const rel = `.github/workflows/${file}`;
15192
- let present = false, name = rel;
15192
+ let present = false, name = rel, inputs = null;
15193
15193
  if (sha) {
15194
15194
  if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
15195
15195
  const show = git.git(['show', `${sha}:${rel}`], repoAbs);
@@ -15197,11 +15197,12 @@ function heavyLaneAt(repoAbs, doc, sha) {
15197
15197
  present = true;
15198
15198
  const t = verifyRuns.workflowTriggers(show.stdout);
15199
15199
  if (t && t.name) name = t.name; // GitHub names a workflow with no `name:` by its file path
15200
+ inputs = workflowTriggers.workflowDispatchInputs(show.stdout); // #660: which -f flags it accepts
15200
15201
  }
15201
15202
  }
15202
15203
  const rows = present ? git.ghRunsAtCommit(repoAbs, sha) : [];
15203
15204
  const heavyRows = Array.isArray(rows) ? rows.filter((r) => (r.workflowName || '') === name) : null;
15204
- return { file, name, present, verdict: integrationProfile.heavyVerdict(heavyRows) };
15205
+ return { file, name, present, inputs, verdict: integrationProfile.heavyVerdict(heavyRows) };
15205
15206
  }
15206
15207
 
15207
15208
  /**
@@ -15221,14 +15222,18 @@ function shipHeavyGate(repoAbs, doc, branch, { docsOnlyApplies = false, batchMem
15221
15222
  }
15222
15223
  const lane = heavyLaneAt(repoAbs, doc, sha);
15223
15224
  const gate = integrationProfile.landingGate({ profile, heavyPresent: lane.present, verdict: lane.verdict, file: lane.file, at });
15224
- return { ...gate, sha, file: lane.file, name: lane.name };
15225
+ return { ...gate, sha, file: lane.file, name: lane.name, inputs: lane.inputs };
15225
15226
  }
15226
15227
 
15227
- /** #610: start the heavy lane at `sha` on `ref` — the real path only, never --dry. Never waits. */
15228
- function dispatchHeavyLane(repoAbs, file, ref, sha) {
15229
- const d = git.ghWorkflowDispatch(repoAbs, file, ref, { ref: sha });
15228
+ /**
15229
+ * #610: start the heavy lane at `sha` on `ref` — the real path only, never --dry. Never waits.
15230
+ * #660: `-f ref=<sha>` only where the workflow declares a `ref` dispatch input (`inputs`, read at the
15231
+ * sha by heavyLaneAt); a repo's own copy may not, and GitHub answers an undeclared input with a 422.
15232
+ */
15233
+ function dispatchHeavyLane(repoAbs, file, ref, sha, inputs) {
15234
+ const d = git.ghWorkflowDispatch(repoAbs, file, ref, integrationProfile.takesRefInput(inputs) ? { ref: sha } : {});
15230
15235
  if (d.ok) print(` ↻ dispatched ${file} on ${ref} at ${shortSha(sha)} (#610) — wait with \`gh run watch\` (bounded, B1a), then run this command again.`);
15231
- else warn(` ${file} could NOT be dispatched (${d.detail}) — run it yourself: gh workflow run ${file} --ref ${ref} -f ref=${sha}`);
15236
+ else warn(` ${file} could NOT be dispatched (${d.detail}) — run it yourself: ${integrationProfile.heavyStartCommand({ file, ref, input: sha, inputs })}`);
15232
15237
  return d.ok;
15233
15238
  }
15234
15239
 
@@ -15549,7 +15554,7 @@ function cmdShipBatch(opts) {
15549
15554
  }
15550
15555
  if (step.step === 'wait-run') {
15551
15556
  print(`⏸ BATCH-PENDING ${existing.ref}@${shortSha(existing.sha)} — combined run ${verdict && verdict.runIds.length ? verdict.runIds.join(', ') + ' ' : ''}${verdict ? verdict.why : ''}.`);
15552
- if (verdict && verdict.heavyMissing && heavyWave && !opts.dry) dispatchHeavyLane(repoAbs, heavyWave.file, existing.ref, existing.sha); // #610
15557
+ if (verdict && verdict.heavyMissing && heavyWave && !opts.dry) dispatchHeavyLane(repoAbs, heavyWave.file, existing.ref, existing.sha, heavyWave.inputs); // #610
15553
15558
  print(` Wait on it (bounded, B1a: gh run watch <id>), then run this command again. Nothing landed.`);
15554
15559
  return 3;
15555
15560
  }
@@ -17339,7 +17344,7 @@ function cmdPromote(argv) {
17339
17344
  if (!lane) { heavyOk = false; detail = `${remote}/${trunk} could not be read`; }
17340
17345
  else if (!lane.present) { heavyOk = false; detail = `no .github/workflows/${lane.file} at ${at} — integration-profile: promote gates the promotion on the heavy lane, and there is none`; }
17341
17346
  else if (lane.verdict.state === 'green') detail = `heavy lane green at ${at}${lane.verdict.url ? ` (${lane.verdict.url})` : ''}`;
17342
- else { heavyOk = false; detail = `heavy lane ${lane.verdict.state} at ${at} (${lane.verdict.why})${lane.verdict.state === 'none' ? ` — start it: gh workflow run ${lane.file} --ref ${trunk} -f ref=${tip}` : ''}`; }
17347
+ else { heavyOk = false; detail = `heavy lane ${lane.verdict.state} at ${at} (${lane.verdict.why})${lane.verdict.state === 'none' ? ` — start it: ${integrationProfile.heavyStartCommand({ file: lane.file, ref: trunk, input: tip, inputs: lane.inputs })}` : ''}`; }
17343
17348
  checks.push([heavyOk ? '✓' : '✗', 'heavy lane green (integration-profile: promote, #610)', detail]);
17344
17349
  }
17345
17350
 
@@ -134,6 +134,27 @@ function waveVerdict(light, heavy) {
134
134
  return { ...light, state: 'pending', heavyMissing: heavy.state === 'none', why: `light green; heavy lane: ${heavy.why}` };
135
135
  }
136
136
 
137
+ /**
138
+ * #660: does the heavy workflow take a `ref` dispatch input? `inputs` is the list of names its
139
+ * `on: workflow_dispatch: inputs:` declares at the ref being dispatched (workflow-triggers.js
140
+ * workflowDispatchInputs). The template declares `ref`, but a repo owns its copy and may not: passing
141
+ * `-f ref=` to a workflow without that input is a hard `HTTP 422: Unexpected inputs provided`. Not an
142
+ * array → the file was not read, so the template's shape is assumed (the pre-#660 behaviour).
143
+ */
144
+ function takesRefInput(inputs) {
145
+ return !Array.isArray(inputs) || inputs.includes('ref');
146
+ }
147
+
148
+ /**
149
+ * #660: the command that starts the heavy lane on `ref` — `-f ref=<input>` only where the workflow
150
+ * declares that input (`input` defaults to `ref`). Without it, `--ref` alone is what checks out the
151
+ * code, which for a tag or a branch head is the same commit.
152
+ */
153
+ function heavyStartCommand({ file, ref, input, inputs }) {
154
+ const base = `gh workflow run ${file} --ref ${ref}`;
155
+ return takesRefInput(inputs) ? `${base} -f ref=${input || ref}` : base;
156
+ }
157
+
137
158
  /**
138
159
  * The final release's heavy-lane condition — under EVERY profile (#610). A repo with no heavy lane at
139
160
  * the candidate has nothing to gate (#607's templates say the same: "no heavy lane here → no gate"),
@@ -143,11 +164,11 @@ function waveVerdict(light, heavy) {
143
164
  * candidate; by hand: the printed command).
144
165
  * → { ok, pending, detail }
145
166
  */
146
- function releaseHeavyCondition({ present, file, verdict, at, ref }) {
167
+ function releaseHeavyCondition({ present, file, verdict, at, ref, inputs }) {
147
168
  if (!present) return { ok: true, pending: false, detail: `no .github/workflows/${file} at ${at} — no heavy lane in this repo, nothing to gate` };
148
169
  const v = verdict || { state: 'unread', why: 'not read' };
149
170
  const link = v.url ? ` (${v.url})` : '';
150
- const start = `gh workflow run ${file} --ref ${ref || '<the candidate tag>'} -f ref=${ref || '<the candidate tag>'}`;
171
+ const start = heavyStartCommand({ file, ref: ref || '<the candidate tag>', inputs });
151
172
  if (v.state === 'green') return { ok: true, pending: false, detail: `heavy lane green at ${at}${link}` };
152
173
  if (v.state === 'red') return { ok: false, pending: false, detail: `heavy lane red at ${at}${link} — a final needs it green at this exact sha: re-run it green, or cut a new candidate` };
153
174
  if (v.state === 'pending') return { ok: false, pending: true, detail: `heavy lane still running at ${at}${link} — no final until it is green` };
@@ -158,4 +179,5 @@ function releaseHeavyCondition({ present, file, verdict, at, ref }) {
158
179
  module.exports = {
159
180
  KEY, HEAVY_KEY, PROFILES, DEFAULT_PROFILE, DEFAULT_HEAVY_WORKFLOW,
160
181
  parseProfile, parseHeavyWorkflow, heavyVerdict, liveRestriction, landingGate, waveVerdict, releaseHeavyCondition,
182
+ takesRefInput, heavyStartCommand,
161
183
  };