@futurelastic/colab-handbook 1.12.0-rc.56 → 1.12.0-rc.57
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 +1 -1
- package/tools/colab +185 -10
- package/tools/lib/ci-wait.js +201 -0
- package/tools/lib/git.js +47 -1
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -46,6 +46,7 @@ const ciCure = require('./lib/ci-cure');
|
|
|
46
46
|
const ciVerdict = require('./lib/ci-verdict');
|
|
47
47
|
const baseCiVerdict = require('./lib/base-ci-verdict');
|
|
48
48
|
const treeGreen = require('./lib/tree-green');
|
|
49
|
+
const ciWait = require('./lib/ci-wait'); // #495
|
|
49
50
|
const staleBase = require('./lib/stale-base');
|
|
50
51
|
const dirtyOwner = require('./lib/dirty-owner');
|
|
51
52
|
const scratchDirs = require('./lib/scratch-dirs');
|
|
@@ -13648,7 +13649,8 @@ function shipBatchMemberTail({ repoAbs, doc, trunk, sess, sha, closeIssues, refs
|
|
|
13648
13649
|
// trunk nobody owns" check and §5's "Trunk CI is alive" bullet call this instead of keeping a
|
|
13649
13650
|
// `gh run list` filter of their own — two rules for one question disagreed, and the red went
|
|
13650
13651
|
// unowned (a sha with CI green and a release workflow red read GREEN to triage, not-green to ship).
|
|
13651
|
-
const
|
|
13652
|
+
const TRUNK_CI_TTL_DEFAULT_SEC = 45;
|
|
13653
|
+
const HELP_TRUNK_CI = `colab trunk-ci [--repo <path>] [--fresh] [--json]
|
|
13652
13654
|
|
|
13653
13655
|
Print the trunk-CI verdict \`colab ship\` would compute for the trunk's CURRENT remote head —
|
|
13654
13656
|
the same read (shipCiCheck's readCiVerdict): by branch, re-read by commit when empty, runs from
|
|
@@ -13670,7 +13672,15 @@ A GREEN whose suite the CI guard skipped because a green run of the same workflo
|
|
|
13670
13672
|
passed an identical tree (#493) names that run in its detail ("relied on <url>"). If the cited
|
|
13671
13673
|
head is local and its tree differs from trunk's, the read is RED: trunk is untested.
|
|
13672
13674
|
|
|
13673
|
-
|
|
13675
|
+
Cost (#495): one REST read of the runs at the sha (\`actions/runs?head_sha=\`), plus one
|
|
13676
|
+
check-runs read on a GREEN. No auth probe in front of it — the read is the probe, and an
|
|
13677
|
+
UNREADABLE explains which credential/remote condition failed. The verdict is cached per
|
|
13678
|
+
trunk+sha for ${TRUNK_CI_TTL_DEFAULT_SEC}s in the repo's git dir, shared by every session on the
|
|
13679
|
+
checkout (COLAB_TRUNK_CI_TTL=<sec> overrides, 0 disables; --fresh skips the cache for one read).
|
|
13680
|
+
To WAIT for CI, use \`colab ci-wait\` — never a loop around this command.
|
|
13681
|
+
|
|
13682
|
+
--fresh ignore a cached verdict (still refreshes the cache)
|
|
13683
|
+
--json { verdict, sha, ok, class, detail, trunk[, cited: [<run url>…] on a #493 skip][, cachedAgeSec] }
|
|
13674
13684
|
Exit 0 whenever a verdict was read (whatever it is); 2 on UNREADABLE.`;
|
|
13675
13685
|
|
|
13676
13686
|
/** Map readCiVerdict's result to the closed trunk-ci vocabulary. Pure — exported for tests. */
|
|
@@ -13686,22 +13696,182 @@ function trunkCiToken(r) {
|
|
|
13686
13696
|
function cmdTrunkCi(argv) {
|
|
13687
13697
|
const opts = parseArgs(argv, {
|
|
13688
13698
|
values: { '--repo': 'repo' },
|
|
13689
|
-
flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
|
|
13699
|
+
flags: { '--json': 'json', '--fresh': 'fresh', '-h': 'help', '--help': 'help' },
|
|
13690
13700
|
});
|
|
13691
13701
|
if (opts.help) return print(HELP_TRUNK_CI);
|
|
13692
13702
|
const repoAbs = resolveRepo(opts);
|
|
13693
13703
|
if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo`);
|
|
13694
13704
|
const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
|
|
13695
13705
|
if (!trunk) throw new UserError('cannot resolve trunk — no `trunk:` in .github/project.yml and no origin/HEAD');
|
|
13696
|
-
|
|
13697
|
-
|
|
13698
|
-
|
|
13706
|
+
|
|
13707
|
+
// #495: the cache key is the trunk's CURRENT remote head — read with `git ls-remote`, which is the
|
|
13708
|
+
// git protocol, not the REST quota — so a new push is never answered from an older sha's verdict.
|
|
13709
|
+
const cache = trunkCiCache(repoAbs);
|
|
13710
|
+
const headSha = remoteHeadSha(repoAbs, trunk);
|
|
13711
|
+
const key = headSha ? `${trunk}@${headSha}` : null;
|
|
13712
|
+
let out = key && !opts.fresh ? cache.get(key) : null;
|
|
13713
|
+
if (!out) {
|
|
13714
|
+
// #495: no `gh auth status` probe in front of the read (it costs a REST + a GraphQL call per
|
|
13715
|
+
// process, and trunk-ci runs as a fresh process each time). The read itself proves the credential;
|
|
13716
|
+
// only an UNREADABLE pays for the explanation.
|
|
13717
|
+
const gh = git.ghInstalled() && !!git.remoteUrl(repoAbs);
|
|
13718
|
+
const r = readCiVerdict(repoAbs, gh, trunk, trunk);
|
|
13719
|
+
const verdict = trunkCiToken(r);
|
|
13720
|
+
const sha = r.run ? r.run.sha || null : null;
|
|
13721
|
+
let detail = r.verdict.detail;
|
|
13722
|
+
if (verdict === 'UNREADABLE' && gh && !git.ghState().ok) detail += ` (${ghUnusableWhy(repoAbs)})`;
|
|
13723
|
+
out = { verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail, ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}) };
|
|
13724
|
+
if (key && verdict !== 'UNREADABLE' && sha === headSha) cache.put(key, out);
|
|
13725
|
+
}
|
|
13699
13726
|
if (opts.json) {
|
|
13700
|
-
print(JSON.stringify(
|
|
13727
|
+
print(JSON.stringify(out, null, 2));
|
|
13701
13728
|
} else {
|
|
13702
|
-
|
|
13729
|
+
const age = out.cachedAgeSec !== undefined ? ` (cached ${out.cachedAgeSec}s ago)` : '';
|
|
13730
|
+
print(`${out.verdict} ${trunk}${out.sha ? `@${shortSha(out.sha)}` : ''} — ${out.detail}${age}`);
|
|
13731
|
+
}
|
|
13732
|
+
return out.verdict === 'UNREADABLE' ? 2 : 0;
|
|
13733
|
+
}
|
|
13734
|
+
|
|
13735
|
+
/** `git ls-remote <remote> refs/heads/<branch>` → sha, or null. Git protocol — no REST quota. */
|
|
13736
|
+
function remoteHeadSha(repoAbs, branch) {
|
|
13737
|
+
const remote = git.remoteInfo(repoAbs).name || 'origin';
|
|
13738
|
+
const r = git.git(['ls-remote', remote, `refs/heads/${branch}`], repoAbs);
|
|
13739
|
+
if (!r.ok) return null;
|
|
13740
|
+
return (r.stdout.split('\n')[0] || '').split('\t')[0].trim() || null;
|
|
13741
|
+
}
|
|
13742
|
+
|
|
13743
|
+
/**
|
|
13744
|
+
* #495: the trunk-ci verdict cache — `<git common dir>/colab-trunk-ci.json`, so every session and
|
|
13745
|
+
* worktree on one checkout shares it. Keyed by `<trunk>@<sha>`; an entry older than the TTL is a
|
|
13746
|
+
* miss. Best effort both ways: an unreadable/unwritable file is simply no cache.
|
|
13747
|
+
*/
|
|
13748
|
+
function trunkCiCache(repoAbs) {
|
|
13749
|
+
const env = process.env.COLAB_TRUNK_CI_TTL;
|
|
13750
|
+
const ttl = env !== undefined && env !== '' && Number.isFinite(Number(env)) ? Number(env) : TRUNK_CI_TTL_DEFAULT_SEC;
|
|
13751
|
+
const dir = git.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoAbs);
|
|
13752
|
+
const file = dir.ok && dir.stdout ? path.join(dir.stdout.trim(), 'colab-trunk-ci.json') : null;
|
|
13753
|
+
const load = () => { try { return JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch (_) { return {}; } };
|
|
13754
|
+
return {
|
|
13755
|
+
get(key) {
|
|
13756
|
+
if (!file || ttl <= 0) return null;
|
|
13757
|
+
const e = load()[key];
|
|
13758
|
+
if (!e || !e.at || !e.out) return null;
|
|
13759
|
+
const age = Math.floor((Date.now() - e.at) / 1000);
|
|
13760
|
+
return age >= 0 && age < ttl ? { ...e.out, cachedAgeSec: age } : null;
|
|
13761
|
+
},
|
|
13762
|
+
put(key, out) {
|
|
13763
|
+
if (!file || ttl <= 0) return;
|
|
13764
|
+
const now = Date.now();
|
|
13765
|
+
const all = load();
|
|
13766
|
+
for (const k of Object.keys(all)) if (!all[k] || now - all[k].at > ttl * 1000) delete all[k];
|
|
13767
|
+
all[key] = { at: now, out };
|
|
13768
|
+
try {
|
|
13769
|
+
const tmp = `${file}.${process.pid}.tmp`;
|
|
13770
|
+
fs.writeFileSync(tmp, JSON.stringify(all));
|
|
13771
|
+
fs.renameSync(tmp, file);
|
|
13772
|
+
} catch (_) { /* no cache, not an error */ }
|
|
13773
|
+
},
|
|
13774
|
+
};
|
|
13775
|
+
}
|
|
13776
|
+
|
|
13777
|
+
// ci-wait — THE way to wait for CI (#495). Agents' hand-rolled `sleep N; gh run …` loops spent ~88%
|
|
13778
|
+
// of a shared identity's REST quota in one measured hour; this waits with backoff, conditional
|
|
13779
|
+
// requests, a deadline, and a distinct exit code for every way a wait can end.
|
|
13780
|
+
const HELP_CI_WAIT = `colab ci-wait <run-id> | --sha <sha> [--branch <b>] [--repo <path>] [--timeout <dur>] [--json]
|
|
13781
|
+
|
|
13782
|
+
Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand-roll a
|
|
13783
|
+
\`sleep N; gh run view\` loop, never run two waits for the same run, never hide gh's stderr.
|
|
13784
|
+
|
|
13785
|
+
<run-id> wait for one workflow run (actions/runs/<id>)
|
|
13786
|
+
--sha <sha> wait for EVERY repo-owned workflow at the sha (the verdict colab ship reads:
|
|
13787
|
+
newest run per workflow, dynamic workflows dropped — #451/#461); a sha with no
|
|
13788
|
+
run yet counts as pending until the deadline
|
|
13789
|
+
--branch <b> narrow --sha to runs on that branch
|
|
13790
|
+
--timeout <d> deadline: 45m (default), 90s, 1h, or seconds
|
|
13791
|
+
|
|
13792
|
+
Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline. Every poll after the first is a
|
|
13793
|
+
conditional request (If-None-Match); a 304 is not counted against the REST rate limit. A 15-minute
|
|
13794
|
+
run costs about 10 requests. One wait per run per checkout: a second waiter is refused.
|
|
13795
|
+
|
|
13796
|
+
Exit codes — branch on these, never on the text:
|
|
13797
|
+
0 GREEN the run (every judged run at the sha) succeeded
|
|
13798
|
+
1 RED completed and did not succeed
|
|
13799
|
+
2 usage bad arguments
|
|
13800
|
+
3 TIMEOUT the deadline passed while still pending
|
|
13801
|
+
4 RATE_LIMITED GitHub refused for quota (403/429) — the wait ENDS, it does not retry
|
|
13802
|
+
5 UNKNOWN a read failed or returned a state it cannot classify
|
|
13803
|
+
6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
|
|
13804
|
+
|
|
13805
|
+
It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
|
|
13806
|
+
--json { outcome, exit, target, polls, notModified, waitedSec, detail, status, conclusion, url }`;
|
|
13807
|
+
|
|
13808
|
+
function cmdCiWait(argv) {
|
|
13809
|
+
const opts = parseArgs(argv, {
|
|
13810
|
+
values: { '--repo': 'repo', '--sha': 'sha', '--branch': 'branch', '--timeout': 'timeout' },
|
|
13811
|
+
flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
|
|
13812
|
+
});
|
|
13813
|
+
if (opts.help) return print(HELP_CI_WAIT);
|
|
13814
|
+
const runId = opts._ && opts._[0];
|
|
13815
|
+
if ((runId ? 1 : 0) + (opts.sha ? 1 : 0) !== 1 || (runId && !/^\d+$/.test(runId)) || (opts.branch && !opts.sha)) {
|
|
13816
|
+
warn('ci-wait takes exactly one of <run-id> (numeric) or --sha <sha> [--branch <b>]');
|
|
13817
|
+
return ciWait.EXIT.USAGE;
|
|
13818
|
+
}
|
|
13819
|
+
const deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
|
|
13820
|
+
if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 45m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
|
|
13821
|
+
const repoAbs = resolveRepo(opts);
|
|
13822
|
+
if (!git.ghInstalled()) { warn('gh is not installed — cannot read CI'); return ciWait.EXIT.UNKNOWN; }
|
|
13823
|
+
|
|
13824
|
+
const target = runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}`;
|
|
13825
|
+
const apiPath = runId
|
|
13826
|
+
? `repos/{owner}/{repo}/actions/runs/${runId}`
|
|
13827
|
+
: `repos/{owner}/{repo}/actions/runs?head_sha=${encodeURIComponent(opts.sha)}${opts.branch ? `&branch=${encodeURIComponent(opts.branch)}` : ''}&per_page=100`;
|
|
13828
|
+
|
|
13829
|
+
const gitDir = git.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoAbs);
|
|
13830
|
+
const lock = gitDir.ok ? ciWait.acquireLock(path.join(gitDir.stdout.trim(), 'colab-ci-wait'), runId || `${opts.sha}-${opts.branch || ''}`) : { ok: true, release: () => {} };
|
|
13831
|
+
if (!lock.ok) {
|
|
13832
|
+
warn(`another ci-wait (pid ${lock.holder}) is already waiting on ${target} in this checkout — read its result, do not start a second wait`);
|
|
13833
|
+
return ciWait.EXIT.ALREADY_WAITING;
|
|
13834
|
+
}
|
|
13835
|
+
|
|
13836
|
+
const poll = (etag) => {
|
|
13837
|
+
const r = git.ghApiConditional(repoAbs, apiPath, etag);
|
|
13838
|
+
if (r.kind !== 'ok') return r;
|
|
13839
|
+
let summary;
|
|
13840
|
+
if (runId) {
|
|
13841
|
+
summary = { status: r.json.status, conclusion: r.json.conclusion || null, url: r.json.html_url || null };
|
|
13842
|
+
} else {
|
|
13843
|
+
const rows = Array.isArray(r.json.workflow_runs) ? r.json.workflow_runs.map(ciWait.restRow).filter((x) => x.headSha === opts.sha) : null;
|
|
13844
|
+
if (!rows) return { kind: 'error', status: r.status, detail: 'response has no workflow_runs' };
|
|
13845
|
+
summary = git.summarizeRunsForCommit(rows, opts.sha);
|
|
13846
|
+
const pick = rows.find((x) => x.databaseId === summary.databaseId);
|
|
13847
|
+
summary = { ...summary, url: pick ? pick.url : null };
|
|
13848
|
+
}
|
|
13849
|
+
return { ...r, summary, state: ciWait.runState(summary) };
|
|
13850
|
+
};
|
|
13851
|
+
|
|
13852
|
+
if (!opts.json) process.stderr.write(`ci-wait: waiting on ${target} (deadline ${ciWait.fmtDuration(deadlineSec * 1000)}; polls at +0s, +30s, +60s, then every 120s)\n`);
|
|
13853
|
+
let res;
|
|
13854
|
+
try {
|
|
13855
|
+
res = ciWait.waitLoop({
|
|
13856
|
+
poll, sleep: ciWait.sleepSync, deadlineSec,
|
|
13857
|
+
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`); },
|
|
13858
|
+
});
|
|
13859
|
+
} finally {
|
|
13860
|
+
lock.release();
|
|
13861
|
+
}
|
|
13862
|
+
const s = (res.last && res.last.summary) || {};
|
|
13863
|
+
const code = ciWait.EXIT[res.outcome];
|
|
13864
|
+
const out = {
|
|
13865
|
+
outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified,
|
|
13866
|
+
waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
|
|
13867
|
+
status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
|
|
13868
|
+
};
|
|
13869
|
+
if (opts.json) print(JSON.stringify(out, null, 2));
|
|
13870
|
+
else {
|
|
13871
|
+
print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
|
|
13872
|
+
`${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}`);
|
|
13703
13873
|
}
|
|
13704
|
-
return
|
|
13874
|
+
return code;
|
|
13705
13875
|
}
|
|
13706
13876
|
|
|
13707
13877
|
const HELP_LANDED = `colab landed [--repo <path>] [--worktree <name> | --branch <br>] [--base <br>] [--all] [--json]
|
|
@@ -14527,8 +14697,12 @@ Commands:
|
|
|
14527
14697
|
code-wrap Phase B → the branch's recorded base (trunk, or a
|
|
14528
14698
|
declared line). --json (--dry only): machine-readable
|
|
14529
14699
|
preconditions with a closed refusal-class vocabulary (#77)
|
|
14530
|
-
trunk-ci [--json]
|
|
14700
|
+
trunk-ci [--fresh] [--json] the trunk-CI verdict ship computes, read-only (#463):
|
|
14531
14701
|
GREEN | RED | PENDING | WEDGED | NONE | UNREADABLE
|
|
14702
|
+
(cached per sha ~45s in .git — #495)
|
|
14703
|
+
ci-wait <run-id> | --sha S [--branch B] [--timeout D] [--json]
|
|
14704
|
+
WAIT for CI with backoff + conditional requests (#495);
|
|
14705
|
+
exit 0 green · 1 red · 3 timeout · 4 rate-limited · 5 unknown
|
|
14532
14706
|
landed [--worktree N | --branch B | --all] [--base B] [--json] has this work already landed?
|
|
14533
14707
|
(the shared rule behind code-sweep's buckets — correct
|
|
14534
14708
|
across squash merges, where "commits ahead" is not)
|
|
@@ -14617,6 +14791,7 @@ function main(argv) {
|
|
|
14617
14791
|
case 'ship': return cmdShip(rest);
|
|
14618
14792
|
case 'landed': return cmdLanded(rest);
|
|
14619
14793
|
case 'trunk-ci': return cmdTrunkCi(rest);
|
|
14794
|
+
case 'ci-wait': return cmdCiWait(rest);
|
|
14620
14795
|
case 'holders': return cmdHolders(rest);
|
|
14621
14796
|
case 'promote': return cmdPromote(rest);
|
|
14622
14797
|
case 'deliver': return cmdDeliver(rest);
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* #495 — one CI-wait primitive, so no agent hand-rolls a `sleep N; gh run …` loop again.
|
|
4
|
+
*
|
|
5
|
+
* Measured over one hour on one fleet: ~88% of ~4,500 REST calls on a shared agent identity were
|
|
6
|
+
* agents waiting for CI in their own shell loops — `sleep 5`–`sleep 20` around `gh run view` /
|
|
7
|
+
* `gh run list` / `colab trunk-ci`, two loops on the same run, one orphaned loop polling for 5½ h
|
|
8
|
+
* with its stderr thrown away, and a loop that read a rate-limit error as "keep waiting". The quota
|
|
9
|
+
* (5,000/h) ran out and every agent's `gh` call failed for the rest of the hour.
|
|
10
|
+
*
|
|
11
|
+
* What this module fixes, by construction:
|
|
12
|
+
* - backoff, not a fixed interval: 30 s → 60 s → 120 s, then 120 s until a deadline. A 15-minute
|
|
13
|
+
* run costs ~10 polls instead of ~180 at `sleep 5`;
|
|
14
|
+
* - conditional requests: every poll after the first sends `If-None-Match`, and a `304 Not
|
|
15
|
+
* Modified` is not counted against the primary rate limit (GitHub REST docs, "conditional
|
|
16
|
+
* requests");
|
|
17
|
+
* - a rate limit (403 with remaining 0, or 429) ENDS the wait with its own outcome — never a retry;
|
|
18
|
+
* - an unreadable or unrecognised state ends it too (UNKNOWN), never "keep waiting";
|
|
19
|
+
* - one wait per run per checkout: a second waiter on the same key is refused (ALREADY_WAITING).
|
|
20
|
+
*
|
|
21
|
+
* The loop is pure over injected `poll` / `sleep` / `now`, so the cost of a 15-minute wait is a
|
|
22
|
+
* unit test, not a guess. The `gh` transport lives in git.js (`ghApiConditional`).
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
const fs = require('fs');
|
|
26
|
+
const path = require('path');
|
|
27
|
+
|
|
28
|
+
/** Exit codes of `colab ci-wait` — one per outcome, so a caller branches on `$?`, never on text. */
|
|
29
|
+
const EXIT = Object.freeze({
|
|
30
|
+
GREEN: 0,
|
|
31
|
+
RED: 1,
|
|
32
|
+
USAGE: 2,
|
|
33
|
+
TIMEOUT: 3,
|
|
34
|
+
RATE_LIMITED: 4,
|
|
35
|
+
UNKNOWN: 5,
|
|
36
|
+
ALREADY_WAITING: 6,
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
const DEFAULT_SCHEDULE_SEC = Object.freeze([30, 60, 120]);
|
|
40
|
+
const DEFAULT_DEADLINE_SEC = 45 * 60;
|
|
41
|
+
|
|
42
|
+
/** Seconds to sleep before poll number `i` (0-based, i ≥ 1); the last step repeats. */
|
|
43
|
+
function delayFor(i, schedule = DEFAULT_SCHEDULE_SEC) {
|
|
44
|
+
if (i <= 0) return 0;
|
|
45
|
+
return schedule[Math.min(i - 1, schedule.length - 1)];
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Parse `gh api -i` stdout: status line, headers, blank line, body. gh prints the head to stdout
|
|
50
|
+
* on a non-2xx too (a 304 exits 1 with `gh: HTTP 304` on stderr — measured), so this is read
|
|
51
|
+
* whatever the exit code. Returns `{ status, headers, body }`; status null when no head was found.
|
|
52
|
+
*/
|
|
53
|
+
function parseHttp(stdout) {
|
|
54
|
+
const text = String(stdout || '');
|
|
55
|
+
const m = /^HTTP\/[\d.]+\s+(\d{3})[^\n]*\n/.exec(text);
|
|
56
|
+
if (!m) return { status: null, headers: {}, body: text };
|
|
57
|
+
const rest = text.slice(m[0].length);
|
|
58
|
+
const split = rest.search(/\r?\n\r?\n/);
|
|
59
|
+
const head = split === -1 ? rest : rest.slice(0, split);
|
|
60
|
+
const body = split === -1 ? '' : rest.slice(split).replace(/^\r?\n\r?\n/, '');
|
|
61
|
+
const headers = {};
|
|
62
|
+
for (const line of head.split(/\r?\n/)) {
|
|
63
|
+
const i = line.indexOf(':');
|
|
64
|
+
if (i > 0) headers[line.slice(0, i).trim().toLowerCase()] = line.slice(i + 1).trim();
|
|
65
|
+
}
|
|
66
|
+
return { status: Number(m[1]), headers, body };
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Classify one response: `ok` (2xx, body parsed) · `not-modified` (304) · `rate-limited` (429, or
|
|
71
|
+
* 403 with `x-ratelimit-remaining: 0`, or gh's own "rate limit" text) · `error` (anything else).
|
|
72
|
+
*/
|
|
73
|
+
function classifyResponse({ status, headers = {}, body, stderr = '' }) {
|
|
74
|
+
const remaining = headers['x-ratelimit-remaining'];
|
|
75
|
+
const resetAt = headers['x-ratelimit-reset'] ? Number(headers['x-ratelimit-reset']) * 1000 : null;
|
|
76
|
+
if (status === 429 || (status === 403 && (remaining === '0' || /rate limit/i.test(String(body) + stderr)))
|
|
77
|
+
|| (status === null && /rate limit/i.test(stderr))) {
|
|
78
|
+
return { kind: 'rate-limited', status, resetAt, detail: firstLine(stderr) || `HTTP ${status}` };
|
|
79
|
+
}
|
|
80
|
+
if (status === 304) return { kind: 'not-modified', status, etag: headers.etag || null };
|
|
81
|
+
if (status !== null && status >= 200 && status < 300) {
|
|
82
|
+
let json;
|
|
83
|
+
try { json = JSON.parse(body); } catch (_) { return { kind: 'error', status, detail: 'unparseable body' }; }
|
|
84
|
+
return { kind: 'ok', status, etag: headers.etag || null, json };
|
|
85
|
+
}
|
|
86
|
+
return { kind: 'error', status, detail: firstLine(stderr) || (status ? `HTTP ${status}` : 'no response') };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
function firstLine(s) { return String(s || '').split('\n').map((x) => x.trim()).find(Boolean) || ''; }
|
|
90
|
+
|
|
91
|
+
/** A REST workflow-run object → the row shape git.summarizeRunsForCommit reads (`gh run list --json`). */
|
|
92
|
+
function restRow(x) {
|
|
93
|
+
return {
|
|
94
|
+
headSha: x.head_sha, status: x.status, conclusion: x.conclusion || null,
|
|
95
|
+
createdAt: x.created_at || null, databaseId: x.id, workflowName: x.name || null,
|
|
96
|
+
event: x.event || null, url: x.html_url || null,
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The state of what is being waited on, from a summarized run (`{status, conclusion}`):
|
|
102
|
+
* `green` · `red` · `pending` · `unknown`. `none` (no run at the sha yet) is pending: runs appear
|
|
103
|
+
* seconds after a push, and the deadline bounds the wait if they never do.
|
|
104
|
+
*/
|
|
105
|
+
function runState(s) {
|
|
106
|
+
if (!s) return 'unknown';
|
|
107
|
+
if (s.status === 'none') return 'pending';
|
|
108
|
+
if (s.status === 'completed') return s.conclusion === 'success' ? 'green' : 'red';
|
|
109
|
+
if (['queued', 'in_progress', 'waiting', 'requested', 'pending'].includes(s.status)) return 'pending';
|
|
110
|
+
return 'unknown';
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* The wait loop. `poll(etag)` returns a classifyResponse() result, plus `state` (runState) and
|
|
115
|
+
* `summary` on `ok`. `sleep(ms)` blocks; `now()` is epoch ms. A 304 keeps the previous state.
|
|
116
|
+
*
|
|
117
|
+
* Returns `{ outcome, polls, notModified, waitedMs, last, detail }`, outcome one of the EXIT keys.
|
|
118
|
+
*/
|
|
119
|
+
function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_SEC,
|
|
120
|
+
schedule = DEFAULT_SCHEDULE_SEC, onPoll = () => {} }) {
|
|
121
|
+
const start = now();
|
|
122
|
+
let etag = null;
|
|
123
|
+
let last = null;
|
|
124
|
+
let polls = 0;
|
|
125
|
+
let notModified = 0;
|
|
126
|
+
for (let i = 0; ; i++) {
|
|
127
|
+
const d = delayFor(i, schedule) * 1000;
|
|
128
|
+
if (d) {
|
|
129
|
+
const left = start + deadlineSec * 1000 - now();
|
|
130
|
+
if (left <= 0) return done('TIMEOUT', `still ${last ? last.state : 'unread'} at the ${fmtDuration(deadlineSec * 1000)} deadline`);
|
|
131
|
+
sleep(Math.min(d, left));
|
|
132
|
+
}
|
|
133
|
+
const r = poll(etag);
|
|
134
|
+
polls++;
|
|
135
|
+
if (r.kind === 'rate-limited') return done('RATE_LIMITED', r.detail + (r.resetAt ? ` — quota resets ${new Date(r.resetAt).toISOString()}` : ''), r);
|
|
136
|
+
if (r.kind === 'error') return done('UNKNOWN', `read failed: ${r.detail}`, r);
|
|
137
|
+
if (r.kind === 'not-modified') {
|
|
138
|
+
notModified++;
|
|
139
|
+
if (!last) return done('UNKNOWN', '304 on the first read — nothing to compare against', r);
|
|
140
|
+
} else {
|
|
141
|
+
etag = r.etag || etag;
|
|
142
|
+
last = r;
|
|
143
|
+
}
|
|
144
|
+
onPoll({ poll: polls, state: last.state, notModified: r.kind === 'not-modified', elapsedMs: now() - start });
|
|
145
|
+
if (last.state === 'green') return done('GREEN', null);
|
|
146
|
+
if (last.state === 'red') return done('RED', null);
|
|
147
|
+
if (last.state !== 'pending') return done('UNKNOWN', `unrecognised state (${JSON.stringify(last.summary || null)})`);
|
|
148
|
+
if (now() - start >= deadlineSec * 1000) return done('TIMEOUT', `still pending at the ${fmtDuration(deadlineSec * 1000)} deadline`);
|
|
149
|
+
}
|
|
150
|
+
function done(outcome, detail, r) {
|
|
151
|
+
return { outcome, polls, notModified, waitedMs: now() - start, last: last || r || null, detail };
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
function fmtDuration(ms) {
|
|
156
|
+
const s = Math.round(ms / 1000);
|
|
157
|
+
const m = Math.floor(s / 60);
|
|
158
|
+
return m ? `${m}m${String(s % 60).padStart(2, '0')}s` : `${s}s`;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** Parse `--timeout`: `45m`, `90s`, `1h`, or bare seconds. Null when unparseable. */
|
|
162
|
+
function parseDuration(v) {
|
|
163
|
+
const m = /^(\d+)\s*([smh]?)$/.exec(String(v || '').trim());
|
|
164
|
+
if (!m) return null;
|
|
165
|
+
return Number(m[1]) * ({ '': 1, s: 1, m: 60, h: 3600 })[m[2]];
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* One wait per key per checkout. The lock is `<dir>/ci-wait-<key>.lock` holding the waiter's pid;
|
|
170
|
+
* a lock whose pid is dead is taken over. Returns `{ ok, holder, release }`.
|
|
171
|
+
*/
|
|
172
|
+
function acquireLock(dir, key, pid = process.pid, alive = pidAlive) {
|
|
173
|
+
const file = path.join(dir, `ci-wait-${String(key).replace(/[^A-Za-z0-9._-]/g, '_')}.lock`);
|
|
174
|
+
try { fs.mkdirSync(dir, { recursive: true }); } catch (_) { /* best effort */ }
|
|
175
|
+
for (let attempt = 0; attempt < 2; attempt++) {
|
|
176
|
+
try {
|
|
177
|
+
fs.writeFileSync(file, String(pid), { flag: 'wx' });
|
|
178
|
+
return { ok: true, file, release: () => { try { fs.unlinkSync(file); } catch (_) {} } };
|
|
179
|
+
} catch (e) {
|
|
180
|
+
if (e.code !== 'EEXIST') return { ok: true, file: null, release: () => {} }; // cannot lock: do not block the wait
|
|
181
|
+
const holder = Number(String(safeRead(file)).trim());
|
|
182
|
+
if (holder && holder !== pid && alive(holder)) return { ok: false, holder, file, release: () => {} };
|
|
183
|
+
try { fs.unlinkSync(file); } catch (_) {}
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
return { ok: true, file: null, release: () => {} };
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
function safeRead(f) { try { return fs.readFileSync(f, 'utf8'); } catch (_) { return ''; } }
|
|
190
|
+
function pidAlive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } }
|
|
191
|
+
|
|
192
|
+
/** Blocking sleep without a busy loop — the CLI's main() is synchronous. */
|
|
193
|
+
function sleepSync(ms) {
|
|
194
|
+
if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
module.exports = {
|
|
198
|
+
EXIT, DEFAULT_SCHEDULE_SEC, DEFAULT_DEADLINE_SEC,
|
|
199
|
+
delayFor, parseHttp, classifyResponse, restRow, runState, waitLoop, fmtDuration, parseDuration,
|
|
200
|
+
acquireLock, sleepSync,
|
|
201
|
+
};
|
package/tools/lib/git.js
CHANGED
|
@@ -858,6 +858,14 @@ function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name ||
|
|
|
858
858
|
function ghRunsForCommit(repo, branch, sha, limit = 10) {
|
|
859
859
|
if (!sha) return null;
|
|
860
860
|
|
|
861
|
+
// #495: one REST call (`actions/runs?head_sha=&branch=`) instead of `gh run list`'s two (runs +
|
|
862
|
+
// workflows), and no `-L` window to fall out of. A rate limit is final — falling back would spend
|
|
863
|
+
// two more calls on a quota that is already gone. Any other failure (an old gh, a test stub that
|
|
864
|
+
// only answers `run list`, a non-GitHub remote) falls through to the `gh run list` read below.
|
|
865
|
+
const rest = ghRunsAtShaRest(repo, sha, branch);
|
|
866
|
+
if (rest.rows) return rest.rows;
|
|
867
|
+
if (rest.rateLimited) return null;
|
|
868
|
+
|
|
861
869
|
// createdAt + databaseId are additive (#155): a NON-completed pick needs both to let a caller
|
|
862
870
|
// judge whether it is merely slow or structurally WEDGED (tools/lib/ci-verdict.js) — createdAt for
|
|
863
871
|
// the age backstop, databaseId to look up its job count (ghRunJobCount, below — a second call, made
|
|
@@ -884,6 +892,44 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
|
|
|
884
892
|
return forSha;
|
|
885
893
|
}
|
|
886
894
|
|
|
895
|
+
/**
|
|
896
|
+
* #495: `gh api -i <path>`, optionally conditional (`If-None-Match: <etag>`). Returns the
|
|
897
|
+
* classified response from tools/lib/ci-wait.js: `{ kind: ok|not-modified|rate-limited|error,
|
|
898
|
+
* status, etag, json?, detail? }`. A 304 does not count against the REST primary rate limit, so a
|
|
899
|
+
* poller that sends its last ETag pays for a read only when something changed. gh exits 1 on a 304
|
|
900
|
+
* and still prints the head to stdout (measured), so the head is parsed whatever the exit code.
|
|
901
|
+
*/
|
|
902
|
+
function ghApiConditional(repo, apiPath, etag) {
|
|
903
|
+
const ciWait = require('./ci-wait');
|
|
904
|
+
const args = ['api', '-i', ...(etag ? ['-H', `If-None-Match: ${etag}`] : []), apiPath];
|
|
905
|
+
const r = run('gh', args, { cwd: repo, timeoutMs: 60000 });
|
|
906
|
+
const http = ciWait.parseHttp(r.stdout);
|
|
907
|
+
return ciWait.classifyResponse({ ...http, stderr: r.stderr });
|
|
908
|
+
}
|
|
909
|
+
|
|
910
|
+
/**
|
|
911
|
+
* Every workflow run at `sha` in ONE REST call (#495) — `actions/runs?head_sha=<sha>[&branch=<b>]`,
|
|
912
|
+
* rows in `gh run list --json` shape. Returns `{ rows }` on success, `{ rateLimited: true }` on a
|
|
913
|
+
* rate limit, `{}` on any other failure (the caller decides whether to fall back).
|
|
914
|
+
*/
|
|
915
|
+
function ghRunsAtShaRest(repo, sha, branch) {
|
|
916
|
+
if (!sha) return {};
|
|
917
|
+
const ciWait = require('./ci-wait');
|
|
918
|
+
const q = `head_sha=${encodeURIComponent(sha)}${branch ? `&branch=${encodeURIComponent(branch)}` : ''}&per_page=100`;
|
|
919
|
+
const r = ghApiConditional(repo, `repos/{owner}/{repo}/actions/runs?${q}`);
|
|
920
|
+
if (r.kind === 'rate-limited') return { rateLimited: true, detail: r.detail };
|
|
921
|
+
if (r.kind !== 'ok' || !r.json || !Array.isArray(r.json.workflow_runs)) return {};
|
|
922
|
+
return { rows: r.json.workflow_runs.map(ciWait.restRow).filter((x) => x.headSha === sha) };
|
|
923
|
+
}
|
|
924
|
+
|
|
925
|
+
/** Is a `gh` binary on PATH (#495)? No API call — cached per process. The credential is proven by
|
|
926
|
+
* the first real read, not by a probe in front of it (`gh auth status` costs a REST + a GraphQL). */
|
|
927
|
+
let _ghInstalled;
|
|
928
|
+
function ghInstalled() {
|
|
929
|
+
if (_ghInstalled === undefined) _ghInstalled = run('gh', ['--version']).ok;
|
|
930
|
+
return _ghInstalled;
|
|
931
|
+
}
|
|
932
|
+
|
|
887
933
|
/**
|
|
888
934
|
* Every run on `ref` at `sha`, WITH its `attempt` (#373). A sibling of ghRunsForCommit, not a change
|
|
889
935
|
* to its field list: batch landing needs the attempt number to enforce "re-run a red:infra ONCE", and
|
|
@@ -1218,7 +1264,7 @@ module.exports = {
|
|
|
1218
1264
|
claimRemote, remoteHeads,
|
|
1219
1265
|
worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
|
|
1220
1266
|
dirtyTracked, dirtyUntracked, dirtyAny,
|
|
1221
|
-
ghAvailable, ghState, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
|
|
1267
|
+
ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
|
|
1222
1268
|
ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
|
|
1223
1269
|
ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
|
|
1224
1270
|
ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
|