@futurelastic/colab-handbook 1.13.0-rc.1 → 1.13.0-rc.2

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
@@ -32,5 +32,5 @@
32
32
  "engines": {
33
33
  "node": ">=18"
34
34
  },
35
- "version": "1.13.0-rc.1"
35
+ "version": "1.13.0-rc.2"
36
36
  }
package/tools/colab CHANGED
@@ -14222,13 +14222,15 @@ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand
14222
14222
  --sha <sha> wait for EVERY repo-owned workflow at the sha (the verdict colab ship reads:
14223
14223
  newest run per workflow, dynamic workflows dropped — #451/#461; only runs that
14224
14224
  verify the code, so a post-CI release/deploy run is set aside — #503); a sha
14225
- with no run yet counts as pending until the deadline
14225
+ with no run yet counts as pending until the deadline. An abbreviated sha is
14226
+ resolved in the repo first, and refused (exit 2) when it does not resolve — #529
14226
14227
  --branch <b> narrow --sha to runs on that branch
14227
14228
  --timeout <d> deadline: 45m (default), 90s, 1h, or seconds
14228
14229
 
14229
14230
  Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline. Every poll after the first is a
14230
- conditional request (If-None-Match); a 304 is not counted against the REST rate limit. A 15-minute
14231
- run costs about 10 requests. One wait per run per checkout: a second waiter is refused.
14231
+ conditional request (If-None-Match); a 304 is not counted against the REST rate limit. After two
14232
+ 304s in a row, and on the last poll before the deadline, it re-reads unconditionally: a stale ETag
14233
+ can cost one paid call, never the whole wait (#505). A 15-minute run costs about 10 requests. One wait per run per checkout: a second waiter is refused.
14232
14234
 
14233
14235
  Exit codes — branch on these, never on the text:
14234
14236
  0 GREEN the run (every judged run at the sha) succeeded
@@ -14240,7 +14242,7 @@ Exit codes — branch on these, never on the text:
14240
14242
  6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
14241
14243
 
14242
14244
  It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
14243
- --json { outcome, exit, target, polls, notModified, waitedSec, detail, status, conclusion, url }`;
14245
+ --json { outcome, exit, target, polls, notModified, forced, waitedSec, detail, status, conclusion, url }`;
14244
14246
 
14245
14247
  function cmdCiWait(argv) {
14246
14248
  const opts = parseArgs(argv, {
@@ -14256,6 +14258,17 @@ function cmdCiWait(argv) {
14256
14258
  const deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
14257
14259
  if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 45m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
14258
14260
  const repoAbs = resolveRepo(opts);
14261
+ if (opts.sha) {
14262
+ // #529: the API reports a 40-hex head_sha and the rows are matched by equality, so an
14263
+ // abbreviated --sha would match nothing and wait out the whole deadline as "pending" — on a run
14264
+ // that finished green in minutes. Resolve it here, or refuse; never poll with it.
14265
+ const full = git.fullSha(repoAbs, opts.sha);
14266
+ if (!full) {
14267
+ warn(`--sha ${opts.sha}: not a full 40-hex sha and it does not resolve to one commit in ${repoAbs} — pass the full sha (\`git rev-parse <sha>\`), or fetch first`);
14268
+ return ciWait.EXIT.USAGE;
14269
+ }
14270
+ opts.sha = full;
14271
+ }
14259
14272
  if (!git.ghInstalled()) { warn('gh is not installed — cannot read CI'); return ciWait.EXIT.UNKNOWN; }
14260
14273
 
14261
14274
  const target = runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}`;
@@ -14294,7 +14307,7 @@ function cmdCiWait(argv) {
14294
14307
  try {
14295
14308
  res = ciWait.waitLoop({
14296
14309
  poll, sleep: ciWait.sleepSync, deadlineSec,
14297
- onPoll: (p) => { if (!opts.json) process.stderr.write(`ci-wait: poll ${p.poll} at +${ciWait.fmtDuration(p.elapsedMs)} — ${p.state}${p.notModified ? ' (304, not counted)' : ''}\n`); },
14310
+ onPoll: (p) => { if (!opts.json) process.stderr.write(`ci-wait: poll ${p.poll} at +${ciWait.fmtDuration(p.elapsedMs)} — ${p.state}${p.notModified ? ' (304, not counted)' : ''}${p.forced ? ' (unconditional re-read — #505)' : ''}\n`); },
14298
14311
  });
14299
14312
  } finally {
14300
14313
  lock.release();
@@ -14302,7 +14315,7 @@ function cmdCiWait(argv) {
14302
14315
  const s = (res.last && res.last.summary) || {};
14303
14316
  const code = ciWait.EXIT[res.outcome];
14304
14317
  const out = {
14305
- outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified,
14318
+ outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified, forced: res.forced,
14306
14319
  waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
14307
14320
  status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
14308
14321
  ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
@@ -13,7 +13,8 @@
13
13
  * run costs ~10 polls instead of ~180 at `sleep 5`;
14
14
  * - conditional requests: every poll after the first sends `If-None-Match`, and a `304 Not
15
15
  * Modified` is not counted against the primary rate limit (GitHub REST docs, "conditional
16
- * requests");
16
+ * requests") — capped (#505): after two 304s in a row, and on the deadline's poll, it re-reads
17
+ * unconditionally, because a validator that never changes would otherwise pin a stale state;
17
18
  * - a rate limit (403 with remaining 0, or 429) ENDS the wait with its own outcome — never a retry;
18
19
  * - an unreadable or unrecognised state ends it too (UNKNOWN), never "keep waiting";
19
20
  * - one wait per run per checkout: a second waiter on the same key is refused (ALREADY_WAITING).
@@ -112,19 +113,32 @@ function runState(s) {
112
113
  return 'unknown';
113
114
  }
114
115
 
116
+ /**
117
+ * #505: how many 304s in a row may stand for the state before the next poll re-reads without
118
+ * `If-None-Match`. Measured: the runs-list read kept answering 304 for ten minutes while every run
119
+ * at the sha had completed green — the validator never changed, so a loop that trusted it would
120
+ * have reported TIMEOUT on a green sha. A cap of 2 bounds that to one paid call per three polls.
121
+ */
122
+ const DEFAULT_MAX_NOT_MODIFIED = 2;
123
+
115
124
  /**
116
125
  * The wait loop. `poll(etag)` returns a classifyResponse() result, plus `state` (runState) and
117
- * `summary` on `ok`. `sleep(ms)` blocks; `now()` is epoch ms. A 304 keeps the previous state.
126
+ * `summary` on `ok`. `sleep(ms)` blocks; `now()` is epoch ms. A 304 keeps the previous state — but
127
+ * only for `maxNotModified` polls in a row, and never on the last poll before the deadline: those
128
+ * polls send no ETag (`poll(null)`), so a stale validator costs one paid read, not the wait (#505).
118
129
  *
119
- * Returns `{ outcome, polls, notModified, waitedMs, last, detail }`, outcome one of the EXIT keys.
130
+ * Returns `{ outcome, polls, notModified, forced, waitedMs, last, detail }`, outcome one of the
131
+ * EXIT keys; `forced` counts the unconditional re-reads #505 added.
120
132
  */
121
133
  function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_SEC,
122
- schedule = DEFAULT_SCHEDULE_SEC, onPoll = () => {} }) {
134
+ schedule = DEFAULT_SCHEDULE_SEC, maxNotModified = DEFAULT_MAX_NOT_MODIFIED, onPoll = () => {} }) {
123
135
  const start = now();
124
136
  let etag = null;
125
137
  let last = null;
126
138
  let polls = 0;
127
139
  let notModified = 0;
140
+ let streak = 0; // consecutive 304s
141
+ let forced = 0;
128
142
  for (let i = 0; ; i++) {
129
143
  const d = delayFor(i, schedule) * 1000;
130
144
  if (d) {
@@ -132,25 +146,31 @@ function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_
132
146
  if (left <= 0) return done('TIMEOUT', `still ${last ? last.state : 'unread'} at the ${fmtDuration(deadlineSec * 1000)} deadline`);
133
147
  sleep(Math.min(d, left));
134
148
  }
135
- const r = poll(etag);
149
+ // The poll that lands on the deadline is the last one: it must read the truth, not a 304.
150
+ const final = now() - start >= deadlineSec * 1000;
151
+ const force = Boolean(etag) && (streak >= maxNotModified || final);
152
+ if (force) forced++;
153
+ const r = poll(force ? null : etag);
136
154
  polls++;
137
155
  if (r.kind === 'rate-limited') return done('RATE_LIMITED', r.detail + (r.resetAt ? ` — quota resets ${new Date(r.resetAt).toISOString()}` : ''), r);
138
156
  if (r.kind === 'error') return done('UNKNOWN', `read failed: ${r.detail}`, r);
139
157
  if (r.kind === 'not-modified') {
140
158
  notModified++;
159
+ streak++;
141
160
  if (!last) return done('UNKNOWN', '304 on the first read — nothing to compare against', r);
142
161
  } else {
162
+ streak = 0;
143
163
  etag = r.etag || etag;
144
164
  last = r;
145
165
  }
146
- onPoll({ poll: polls, state: last.state, notModified: r.kind === 'not-modified', elapsedMs: now() - start });
166
+ onPoll({ poll: polls, state: last.state, notModified: r.kind === 'not-modified', forced: force, elapsedMs: now() - start });
147
167
  if (last.state === 'green') return done('GREEN', null);
148
168
  if (last.state === 'red') return done('RED', null);
149
169
  if (last.state !== 'pending') return done('UNKNOWN', `unrecognised state (${JSON.stringify(last.summary || null)})`);
150
170
  if (now() - start >= deadlineSec * 1000) return done('TIMEOUT', `still pending at the ${fmtDuration(deadlineSec * 1000)} deadline`);
151
171
  }
152
172
  function done(outcome, detail, r) {
153
- return { outcome, polls, notModified, waitedMs: now() - start, last: last || r || null, detail };
173
+ return { outcome, polls, notModified, forced, waitedMs: now() - start, last: last || r || null, detail };
154
174
  }
155
175
  }
156
176
 
@@ -197,7 +217,7 @@ function sleepSync(ms) {
197
217
  }
198
218
 
199
219
  module.exports = {
200
- EXIT, DEFAULT_SCHEDULE_SEC, DEFAULT_DEADLINE_SEC,
220
+ EXIT, DEFAULT_SCHEDULE_SEC, DEFAULT_DEADLINE_SEC, DEFAULT_MAX_NOT_MODIFIED,
201
221
  delayFor, parseHttp, classifyResponse, restRow, runState, waitLoop, fmtDuration, parseDuration,
202
222
  acquireLock, sleepSync,
203
223
  };
package/tools/lib/git.js CHANGED
@@ -886,6 +886,10 @@ function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name ||
886
886
  * branch head.
887
887
  */
888
888
  function ghRunsForCommit(repo, branch, sha, limit = 10) {
889
+ // #529: every row filter below is strict equality against a 40-hex head_sha. An abbreviated sha
890
+ // would filter to [] — read by every caller as "no runs yet" — so resolve it, and when it cannot
891
+ // be resolved answer null ("the read failed"), never an empty set.
892
+ sha = fullSha(repo, sha);
889
893
  if (!sha) return null;
890
894
 
891
895
  // #495: one REST call (`actions/runs?head_sha=&branch=`) instead of `gh run list`'s two (runs +
@@ -940,12 +944,29 @@ function ghApiConditional(repo, apiPath, etag) {
940
944
  return ciWait.classifyResponse({ ...http, stderr: r.stderr });
941
945
  }
942
946
 
947
+ /**
948
+ * #529: `sha` as the full 40-hex object name the Actions API reports as `head_sha`, or null. A
949
+ * 40-hex value passes through (lowercased) without a local lookup — the commit may exist only on
950
+ * the remote. Anything shorter is resolved with `git rev-parse --verify <sha>^{commit}` in `repo`;
951
+ * unresolvable (unknown here, or ambiguous) is null. Never a prefix match: a short sha can be
952
+ * ambiguous across runs, and a match against the wrong run is worse than a refusal.
953
+ */
954
+ function fullSha(repo, sha) {
955
+ const s = String(sha || '').trim();
956
+ if (/^[0-9a-f]{40}$/i.test(s)) return s.toLowerCase();
957
+ if (!/^[0-9a-f]{4,39}$/i.test(s)) return null;
958
+ const r = git(['rev-parse', '--verify', '--quiet', `${s}^{commit}`], repo);
959
+ const out = r.ok ? r.stdout.trim() : '';
960
+ return /^[0-9a-f]{40}$/.test(out) ? out : null;
961
+ }
962
+
943
963
  /**
944
964
  * Every workflow run at `sha` in ONE REST call (#495) — `actions/runs?head_sha=<sha>[&branch=<b>]`,
945
965
  * rows in `gh run list --json` shape. Returns `{ rows }` on success, `{ rateLimited: true }` on a
946
966
  * rate limit, `{}` on any other failure (the caller decides whether to fall back).
947
967
  */
948
968
  function ghRunsAtShaRest(repo, sha, branch) {
969
+ sha = fullSha(repo, sha); // #529: the API's head_sha is 40-hex; an abbreviated one matches no row
949
970
  if (!sha) return {};
950
971
  const ciWait = require('./ci-wait');
951
972
  const q = `head_sha=${encodeURIComponent(sha)}${branch ? `&branch=${encodeURIComponent(branch)}` : ''}&per_page=100`;
@@ -1311,7 +1332,7 @@ module.exports = {
1311
1332
  claimRemote, remoteHeads,
1312
1333
  worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
1313
1334
  dirtyTracked, dirtyUntracked, dirtyAny,
1314
- ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
1335
+ ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, fullSha, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
1315
1336
  ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
1316
1337
  ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
1317
1338
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,