@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.10

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 (74) hide show
  1. package/README.md +248 -213
  2. package/README.vi.md +252 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +7 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1902 -278
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +223 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +42 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +153 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +723 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +778 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +324 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +118 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/ship-human-door.js +76 -0
  65. package/tools/lib/stamp.js +7 -0
  66. package/tools/lib/tracker-fake.js +195 -0
  67. package/tools/lib/tracker-github.js +106 -0
  68. package/tools/lib/tracker-scenarios.json +206 -0
  69. package/tools/lib/tracker.js +64 -0
  70. package/tools/lib/tree-green.js +88 -0
  71. package/tools/lib/util.js +17 -1
  72. package/tools/lib/verify-runs.js +104 -0
  73. package/tools/lib/wake.js +8 -90
  74. package/tools/lib/workflow-triggers.js +48 -0
package/tools/lib/git.js CHANGED
@@ -29,6 +29,15 @@ function run(cmd, args, opts = {}) {
29
29
  };
30
30
  }
31
31
 
32
+ /**
33
+ * Every `gh` spawn in this module goes through the tracker adapter (#500) — the one place the CLI
34
+ * talks to GitHub. Lazy require, deliberately: `module.exports = {…}` below REPLACES the exports
35
+ * object, so a top-level require cycle would hand tracker-github a stale empty `{}`.
36
+ */
37
+ function gh(args, opts = {}) {
38
+ return require('./tracker-github').exec(args, opts);
39
+ }
40
+
32
41
  function git(args, cwd, opts = {}) {
33
42
  return run('git', args, { ...(cwd ? { cwd } : {}), ...opts });
34
43
  }
@@ -438,8 +447,9 @@ function dirtyAny(wtPath) {
438
447
 
439
448
  /**
440
449
  * #344: is gh usable — and if not, WHY. `{ ok, reason }`, reason `null` | `'missing'` (no gh binary)
441
- * | `'no-credential'` (gh is there, but the credential it would actually use does not work). Cached
442
- * per process.
450
+ * | `'no-credential'` (gh is there, but the credential it would actually use does not work)
451
+ * | `'rate-limited'` (#516: the credential works, its quota is spent — `resetAt` epoch ms or null).
452
+ * Cached per process.
443
453
  *
444
454
  * A bare `gh auth status` is the wrong question: it exits 1 when ANY configured account is broken,
445
455
  * even when the one gh actually uses is fine (measured: a valid `GH_TOKEN` plus an expired, inactive
@@ -453,30 +463,50 @@ function dirtyAny(wtPath) {
453
463
  let _ghState = null;
454
464
  function ghState() {
455
465
  if (_ghState) return _ghState;
456
- if (!run('gh', ['--version']).ok) return (_ghState = { ok: false, reason: 'missing' });
457
- if (run('gh', ['auth', 'status', '--active']).ok) return (_ghState = { ok: true, reason: null });
458
- const who = run('gh', ['api', 'user', '-q', '.login']);
466
+ if (!gh(['--version']).ok) return (_ghState = { ok: false, reason: 'missing' });
467
+ if (gh(['auth', 'status', '--active']).ok) return (_ghState = { ok: true, reason: null });
468
+ const who = gh(['api', 'user', '-q', '.login']);
459
469
  if (who.ok && who.stdout) {
460
470
  if (_ghLogin === undefined) _ghLogin = who.stdout;
461
471
  return (_ghState = { ok: true, reason: null });
462
472
  }
473
+ // #516: a spent QUOTA is not a broken credential. `gh api user` answers 403/429 "API rate limit
474
+ // exceeded" (or a "secondary rate limit") for a token that is perfectly valid — and `gh auth status`
475
+ // then calls it invalid too. Reported as `no-credential`, that sent an operator hunting a broken
476
+ // token when the cure is to wait for the reset or switch account. Classified by the SAME rule
477
+ // ci-wait reads a REST response with (#495), so both name a rate limit identically.
478
+ const status = /\bHTTP (\d{3})\b/.exec(who.stderr || '');
479
+ const cls = require('./ci-wait').classifyResponse({ status: status ? Number(status[1]) : null, stderr: who.stderr || '' });
480
+ if (cls.kind === 'rate-limited') return (_ghState = { ok: false, reason: 'rate-limited', resetAt: ghRateLimitReset() });
463
481
  return (_ghState = { ok: false, reason: 'no-credential' });
464
482
  }
465
483
 
484
+ /**
485
+ * #516: when the REST core quota resets, as epoch ms — or null when it cannot be read or is not the
486
+ * limit in force (quota left means a SECONDARY rate limit, whose end GitHub does not publish).
487
+ * `GET /rate_limit` does not count against the quota, so it answers even while `api user` cannot.
488
+ */
489
+ function ghRateLimitReset() {
490
+ const r = gh(['api', 'rate_limit', '-q', '.resources.core | "\\(.remaining) \\(.reset)"']);
491
+ const m = r.ok ? /^(\d+)\s+(\d+)$/.exec((r.stdout || '').trim()) : null;
492
+ if (!m || Number(m[1]) > 0) return null;
493
+ return Number(m[2]) * 1000;
494
+ }
495
+
466
496
  function ghAvailable() {
467
497
  return ghState().ok;
468
498
  }
469
499
 
470
500
  /** gh issue edit — returns {ok, stderr}. cwd must be inside the repo so gh resolves the remote. */
471
501
  function ghIssueEdit(repo, issueNum, args) {
472
- return run('gh', ['issue', 'edit', String(issueNum), ...args], { cwd: repo });
502
+ return gh(['issue', 'edit', String(issueNum), ...args], { cwd: repo });
473
503
  }
474
504
 
475
505
  /** The current gh user's login (`gh api user`), or null if it can't be determined. Cached. */
476
506
  let _ghLogin;
477
507
  function ghCurrentLogin() {
478
508
  if (_ghLogin !== undefined) return _ghLogin;
479
- const r = run('gh', ['api', 'user', '-q', '.login']);
509
+ const r = gh(['api', 'user', '-q', '.login']);
480
510
  _ghLogin = r.ok && r.stdout ? r.stdout : null;
481
511
  return _ghLogin;
482
512
  }
@@ -484,7 +514,7 @@ function ghCurrentLogin() {
484
514
  /** Raw `gh api` call — returns {ok, stdout, stderr, code}. cwd must be inside the repo so `{owner}`
485
515
  * / `{repo}` placeholders resolve to the right remote. */
486
516
  function ghApi(repo, args) {
487
- return run('gh', ['api', ...args], { cwd: repo });
517
+ return gh(['api', ...args], { cwd: repo });
488
518
  }
489
519
 
490
520
  /**
@@ -562,7 +592,7 @@ function ghIssueRelease(repo, issueNum, opts = {}) {
562
592
  note = 'could not read who holds the claim — unassigned @me only';
563
593
  }
564
594
  }
565
- const r = run('gh', ['issue', 'edit', String(issueNum),
595
+ const r = gh(['issue', 'edit', String(issueNum),
566
596
  '--remove-assignee', ['@me', ...others].join(','), '--remove-label', 'in-progress'], { cwd: repo });
567
597
  if (r.ok || !isGraphqlRateLimit(r.stderr)) return { ...r, others: r.ok ? others : [], caller, note };
568
598
 
@@ -586,7 +616,7 @@ function ghIssueRelease(repo, issueNum, opts = {}) {
586
616
  * bad repo, network, unparseable). Callers treat null as "couldn't read" — never as "empty".
587
617
  */
588
618
  function ghIssueView(repo, issueNum, fields) {
589
- const r = run('gh', ['issue', 'view', String(issueNum), '--json', fields.join(',')], { cwd: repo });
619
+ const r = gh(['issue', 'view', String(issueNum), '--json', fields.join(',')], { cwd: repo });
590
620
  if (!r.ok) return null;
591
621
  try { return JSON.parse(r.stdout); }
592
622
  catch (_) { return null; }
@@ -604,7 +634,7 @@ function ghIssueView(repo, issueNum, fields) {
604
634
  * someone approved it?", so the core-path pause costs one read on the resume path.
605
635
  */
606
636
  function ghPrForBranch(repo, branch) {
607
- const r = run('gh', ['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url,state,author,headRefOid,reviews'], { cwd: repo });
637
+ const r = gh(['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url,state,author,headRefOid,reviews'], { cwd: repo });
608
638
  if (!r.ok) return { error: (r.stderr || '').split('\n')[0] || `gh pr list exited ${r.code}` };
609
639
  try {
610
640
  const list = JSON.parse(r.stdout || '[]');
@@ -618,7 +648,7 @@ function ghPrForBranch(repo, branch) {
618
648
  * tools/lib/machine-trailer.js fails closed on it.
619
649
  */
620
650
  function ghRepoVisibility(repo) {
621
- const r = run('gh', ['repo', 'view', '--json', 'visibility', '-q', '.visibility'], { cwd: repo });
651
+ const r = gh(['repo', 'view', '--json', 'visibility', '-q', '.visibility'], { cwd: repo });
622
652
  if (!r.ok) return null;
623
653
  const v = (r.stdout || '').trim().toUpperCase();
624
654
  return /^[A-Z]+$/.test(v) ? v : null;
@@ -626,18 +656,18 @@ function ghRepoVisibility(repo) {
626
656
 
627
657
  /** #350: open a PR `head` → `base`. Returns {ok, url, stderr}; `url` is gh's printed PR URL. */
628
658
  function ghPrCreate(repo, { base, head, title, body }) {
629
- const r = run('gh', ['pr', 'create', '--base', base, '--head', head, '--title', title, '--body', body], { cwd: repo });
659
+ const r = gh(['pr', 'create', '--base', base, '--head', head, '--title', title, '--body', body], { cwd: repo });
630
660
  const url = (r.stdout || '').split('\n').map((l) => l.trim()).filter(Boolean).pop() || null;
631
661
  return { ok: r.ok, url, stderr: r.stderr };
632
662
  }
633
663
 
634
664
  /** #350: close a PR whose work landed by squash elsewhere, with a comment saying where. */
635
665
  function ghPrClose(repo, num, comment) {
636
- return run('gh', ['pr', 'close', String(num), '--comment', comment], { cwd: repo });
666
+ return gh(['pr', 'close', String(num), '--comment', comment], { cwd: repo });
637
667
  }
638
668
 
639
669
  function ghIssueComment(repo, issueNum, body) {
640
- const r = run('gh', ['issue', 'comment', String(issueNum), '--body', body], { cwd: repo });
670
+ const r = gh(['issue', 'comment', String(issueNum), '--body', body], { cwd: repo });
641
671
  if (r.ok || !isGraphqlRateLimit(r.stderr)) return r;
642
672
  return ghApi(repo, ['-X', 'POST', `repos/{owner}/{repo}/issues/${issueNum}/comments`, '-f', `body=${body}`]);
643
673
  }
@@ -677,7 +707,7 @@ function ghIssueLabelActors(repo, issueNum, label) {
677
707
  * contract as ghIssueView: a caller must not read absence as proof a label is missing.
678
708
  */
679
709
  function ghListLabels(repo) {
680
- const r = run('gh', ['label', 'list', '--limit', '500', '--json', 'name', '-q', '.[].name'], { cwd: repo });
710
+ const r = gh(['label', 'list', '--limit', '500', '--json', 'name', '-q', '.[].name'], { cwd: repo });
681
711
  if (!r.ok) return null;
682
712
  return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
683
713
  }
@@ -688,13 +718,32 @@ function ghListLabels(repo) {
688
718
  * the same contract as ghIssueView; a caller must not read a failed call as "no issues".
689
719
  */
690
720
  function ghIssueListByLabel(repo, label, state, fields) {
691
- const r = run('gh', ['issue', 'list', '--label', label, '--state', state,
721
+ const r = gh(['issue', 'list', '--label', label, '--state', state,
692
722
  '--json', fields.join(','), '--limit', '200'], { cwd: repo });
693
723
  if (!r.ok) return null;
694
724
  try { return JSON.parse(r.stdout); }
695
725
  catch (_) { return null; }
696
726
  }
697
727
 
728
+ /**
729
+ * #448: the open issues carrying `label`, as numbers, read through the REST issues list — NOT
730
+ * search. `gh issue list --label` (ghIssueListByLabel above) is served by GraphQL `search(...)`,
731
+ * whose index can lag a burst of closes and answer "0 open" for a label still on an open issue;
732
+ * this endpoint reads the issues table directly. Pull requests share the endpoint and are dropped.
733
+ * Null on any failure — "could not read", never "none open", same contract as ghIssueListByLabel.
734
+ * Used as the confirming read before a `group:` label is deleted (group-labels.js
735
+ * teardownSpentGroupLabel).
736
+ */
737
+ function ghOpenIssueNumbersByLabel(repo, label) {
738
+ const r = ghApi(repo, [
739
+ '--method', 'GET', '--paginate', 'repos/{owner}/{repo}/issues',
740
+ '-f', `labels=${label}`, '-f', 'state=open', '-f', 'per_page=100',
741
+ '--jq', '.[] | select(.pull_request == null) | .number',
742
+ ]);
743
+ if (!r.ok) return null;
744
+ return String(r.stdout || '').split('\n').map((l) => l.trim()).filter(Boolean).map(Number);
745
+ }
746
+
698
747
  /**
699
748
  * `gh label delete <name> --yes` — returns {ok, stderr}. Deletes the LABEL OBJECT from the
700
749
  * repo's tracker, not one issue's use of it — every issue that carried it loses it. Callers
@@ -702,7 +751,7 @@ function ghIssueListByLabel(repo, label, state, fields) {
702
751
  * instead; this is only for tearing down a spent `group:<key>` label (CONVENTIONS.md §5).
703
752
  */
704
753
  function ghLabelDelete(repo, name) {
705
- return run('gh', ['label', 'delete', name, '--yes'], { cwd: repo });
754
+ return gh(['label', 'delete', name, '--yes'], { cwd: repo });
706
755
  }
707
756
 
708
757
  /**
@@ -715,7 +764,7 @@ function ghLabelDelete(repo, name) {
715
764
  * ghListLabels and only calls this for a name confirmed missing.
716
765
  */
717
766
  function ghLabelCreate(repo, name, color, description) {
718
- return run('gh', ['label', 'create', name, '--color', color, '--description', description], { cwd: repo });
767
+ return gh(['label', 'create', name, '--color', color, '--description', description], { cwd: repo });
719
768
  }
720
769
 
721
770
  /**
@@ -725,7 +774,7 @@ function ghLabelCreate(repo, name, color, description) {
725
774
  * description has drifted from the handbook's (#364).
726
775
  */
727
776
  function ghListLabelsDetailed(repo) {
728
- const r = run('gh', ['label', 'list', '--limit', '500', '--json', 'name,description'], { cwd: repo });
777
+ const r = gh(['label', 'list', '--limit', '500', '--json', 'name,description'], { cwd: repo });
729
778
  if (!r.ok) return null;
730
779
  try {
731
780
  const rows = JSON.parse(r.stdout);
@@ -741,7 +790,7 @@ function ghListLabelsDetailed(repo) {
741
790
  * read with a differing description.
742
791
  */
743
792
  function ghLabelEditDescription(repo, name, description) {
744
- return run('gh', ['label', 'edit', name, '--description', description], { cwd: repo });
793
+ return gh(['label', 'edit', name, '--description', description], { cwd: repo });
745
794
  }
746
795
 
747
796
  /**
@@ -795,12 +844,12 @@ function ghLabelEditDescription(repo, name, description) {
795
844
  * when tools/lib/ci-verdict.js finds the run WEDGED rather than merely slow. Nothing here waits or
796
845
  * polls — it reports what is true at read time and lets the caller decide.
797
846
  */
798
- function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name || 'origin') {
847
+ function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name || 'origin', opts = {}) {
799
848
  const head = run('git', ['ls-remote', remote, `refs/heads/${branch}`], { cwd: repo });
800
849
  if (!head.ok) return null;
801
850
  const sha = (head.stdout.split('\n')[0] || '').split('\t')[0].trim();
802
851
  if (!sha) return null; // branch does not exist on the remote
803
- return ghRunForCommit(repo, branch, sha, limit);
852
+ return ghRunForCommit(repo, branch, sha, limit, opts);
804
853
  }
805
854
 
806
855
  /**
@@ -837,21 +886,38 @@ function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name ||
837
886
  * branch head.
838
887
  */
839
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);
840
893
  if (!sha) return null;
841
894
 
895
+ // #495: one REST call (`actions/runs?head_sha=&branch=`) instead of `gh run list`'s two (runs +
896
+ // workflows), and no `-L` window to fall out of. A rate limit is final — falling back would spend
897
+ // two more calls on a quota that is already gone. Any other failure (an old gh, a test stub that
898
+ // only answers `run list`, a non-GitHub remote) falls through to the `gh run list` read below.
899
+ const rest = ghRunsAtShaRest(repo, sha, branch);
900
+ if (rest.rows) return rest.rows;
901
+ if (rest.rateLimited) return null;
902
+
842
903
  // createdAt + databaseId are additive (#155): a NON-completed pick needs both to let a caller
843
904
  // judge whether it is merely slow or structurally WEDGED (tools/lib/ci-verdict.js) — createdAt for
844
905
  // the age backstop, databaseId to look up its job count (ghRunJobCount, below — a second call, made
845
906
  // lazily by the caller, never here: an ordinary green check must not pay for a read it never needs).
846
- const r = run('gh', ['run', 'list', '--branch', branch, '-L', String(limit),
907
+ const r = gh(['run', 'list', '--branch', branch, '-L', String(limit),
847
908
  // workflowName is additive (#338): `colab release cut`'s full-suite condition groups the rows by
848
909
  // workflow — a workflow whose only run at the sha was cancelled never ran its suite.
849
- '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName'], { cwd: repo });
910
+ // event is additive (#451): summarizeRunsForCommit drops `dynamic` rows (workflows the repo
911
+ // does not own) before it computes a verdict, and can only do that if the row says so.
912
+ // workflowDatabaseId is additive (#510): the cure rule's same-workflow test reads the workflow's
913
+ // id, never its display name; mapped to `workflowId`, the name the REST row (ci-wait restRow) uses.
914
+ '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,workflowDatabaseId,event'], { cwd: repo });
850
915
  if (!r.ok) return null;
851
916
  let runs;
852
917
  try { runs = JSON.parse(r.stdout); } catch (_) { return null; }
853
918
  if (!Array.isArray(runs)) return null;
854
- const forSha = runs.filter((x) => x && x.headSha === sha);
919
+ const forSha = runs.filter((x) => x && x.headSha === sha)
920
+ .map(({ workflowDatabaseId, ...x }) => ({ ...x, workflowId: workflowDatabaseId ?? null }));
855
921
  // #413: an empty filter over a sha that HAS a green run was measured intermittently and never
856
922
  // reproduced. Opt-in trace of what the read actually returned, so the next occurrence says
857
923
  // whether gh answered nothing, answered other shas, or failed in a way that parsed as [].
@@ -863,6 +929,61 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
863
929
  return forSha;
864
930
  }
865
931
 
932
+ /**
933
+ * #495: `gh api -i <path>`, optionally conditional (`If-None-Match: <etag>`). Returns the
934
+ * classified response from tools/lib/ci-wait.js: `{ kind: ok|not-modified|rate-limited|error,
935
+ * status, etag, json?, detail? }`. A 304 does not count against the REST primary rate limit, so a
936
+ * poller that sends its last ETag pays for a read only when something changed. gh exits 1 on a 304
937
+ * and still prints the head to stdout (measured), so the head is parsed whatever the exit code.
938
+ */
939
+ function ghApiConditional(repo, apiPath, etag) {
940
+ const ciWait = require('./ci-wait');
941
+ const args = ['api', '-i', ...(etag ? ['-H', `If-None-Match: ${etag}`] : []), apiPath];
942
+ const r = gh(args, { cwd: repo, timeoutMs: 60000 });
943
+ const http = ciWait.parseHttp(r.stdout);
944
+ return ciWait.classifyResponse({ ...http, stderr: r.stderr });
945
+ }
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
+
963
+ /**
964
+ * Every workflow run at `sha` in ONE REST call (#495) — `actions/runs?head_sha=<sha>[&branch=<b>]`,
965
+ * rows in `gh run list --json` shape. Returns `{ rows }` on success, `{ rateLimited: true }` on a
966
+ * rate limit, `{}` on any other failure (the caller decides whether to fall back).
967
+ */
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
970
+ if (!sha) return {};
971
+ const ciWait = require('./ci-wait');
972
+ const q = `head_sha=${encodeURIComponent(sha)}${branch ? `&branch=${encodeURIComponent(branch)}` : ''}&per_page=100`;
973
+ const r = ghApiConditional(repo, `repos/{owner}/{repo}/actions/runs?${q}`);
974
+ if (r.kind === 'rate-limited') return { rateLimited: true, detail: r.detail };
975
+ if (r.kind !== 'ok' || !r.json || !Array.isArray(r.json.workflow_runs)) return {};
976
+ return { rows: r.json.workflow_runs.map(ciWait.restRow).filter((x) => x.headSha === sha) };
977
+ }
978
+
979
+ /** Is a `gh` binary on PATH (#495)? No API call — cached per process. The credential is proven by
980
+ * the first real read, not by a probe in front of it (`gh auth status` costs a REST + a GraphQL). */
981
+ let _ghInstalled;
982
+ function ghInstalled() {
983
+ if (_ghInstalled === undefined) _ghInstalled = gh(['--version']).ok;
984
+ return _ghInstalled;
985
+ }
986
+
866
987
  /**
867
988
  * Every run on `ref` at `sha`, WITH its `attempt` (#373). A sibling of ghRunsForCommit, not a change
868
989
  * to its field list: batch landing needs the attempt number to enforce "re-run a red:infra ONCE", and
@@ -870,7 +991,7 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
870
991
  */
871
992
  function ghRunsForRef(repo, ref, sha, limit = 20) {
872
993
  if (!sha) return null;
873
- const r = run('gh', ['run', 'list', '--branch', ref, '-L', String(limit),
994
+ const r = gh(['run', 'list', '--branch', ref, '-L', String(limit),
874
995
  '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,attempt'], { cwd: repo });
875
996
  if (!r.ok) return null;
876
997
  let runs;
@@ -879,8 +1000,8 @@ function ghRunsForRef(repo, ref, sha, limit = 20) {
879
1000
  return runs.filter((x) => x && x.headSha === sha);
880
1001
  }
881
1002
 
882
- function ghRunForCommit(repo, branch, sha, limit = 10) {
883
- return summarizeRunsForCommit(ghRunsForCommit(repo, branch, sha, limit), sha);
1003
+ function ghRunForCommit(repo, branch, sha, limit = 10, opts = {}) {
1004
+ return summarizeRunsForCommit(ghRunsForCommit(repo, branch, sha, limit), sha, opts);
884
1005
  }
885
1006
 
886
1007
  /**
@@ -890,7 +1011,7 @@ function ghRunForCommit(repo, branch, sha, limit = 10) {
890
1011
  */
891
1012
  function ghRunsAtCommit(repo, sha, limit = 100) {
892
1013
  if (!sha) return null;
893
- const r = run('gh', ['run', 'list', '--commit', sha, '-L', String(limit),
1014
+ const r = gh(['run', 'list', '--commit', sha, '-L', String(limit),
894
1015
  '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,event'], { cwd: repo });
895
1016
  if (!r.ok) return null;
896
1017
  let runs;
@@ -905,8 +1026,8 @@ function ghRunsAtCommit(repo, sha, limit = 100) {
905
1026
  * empty trunk read `none`: the branch-filtered list was measured returning nothing for a trunk sha
906
1027
  * whose green run existed, and clearing on its own a minute later. Null on failure, as elsewhere.
907
1028
  */
908
- function ghRunForCommitAnyRef(repo, sha, limit = 50) {
909
- return summarizeRunsForCommit(ghRunsAtCommit(repo, sha, limit), sha);
1029
+ function ghRunForCommitAnyRef(repo, sha, limit = 50, opts = {}) {
1030
+ return summarizeRunsForCommit(ghRunsAtCommit(repo, sha, limit), sha, opts);
910
1031
  }
911
1032
 
912
1033
  /**
@@ -928,7 +1049,7 @@ function commitTimeMs(repo, sha) {
928
1049
  * `truncated` is true when the read filled its limit, which a caller must treat as unread.
929
1050
  */
930
1051
  function ghRunsSince(repo, branch, sinceDay, limit = 1000) {
931
- const r = run('gh', ['run', 'list', '--branch', branch, '--created', `>=${sinceDay}`, '-L', String(limit),
1052
+ const r = gh(['run', 'list', '--branch', branch, '--created', `>=${sinceDay}`, '-L', String(limit),
932
1053
  '--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,event'], { cwd: repo });
933
1054
  if (!r.ok) return null;
934
1055
  let runs;
@@ -937,15 +1058,133 @@ function ghRunsSince(repo, branch, sinceDay, limit = 1000) {
937
1058
  return { runs, truncated: runs.length >= limit };
938
1059
  }
939
1060
 
940
- /** ghRunForCommit's pick, over rows already read (null in -> null out). */
941
- function summarizeRunsForCommit(forSha, sha) {
942
- if (forSha === null) return null;
1061
+ /**
1062
+ * #451: a run whose `event` is `dynamic` comes from a workflow the repo does not own — GitHub's
1063
+ * dynamic workflows (Dependabot Updates, code scanning default setup, …), which never execute the
1064
+ * code at the sha they are filed against. Such a row is not evidence about that sha, so it is
1065
+ * dropped before any verdict is computed. A row with no `event` field (an older read, a hand-built
1066
+ * fixture) is kept: absence of the field never excludes anything.
1067
+ */
1068
+ function isRepoOwnedRun(x) {
1069
+ return !(x && x.event === 'dynamic');
1070
+ }
1071
+
1072
+ /** The dropped rows, in the compact shape a verdict detail names them by. */
1073
+ function excludedRunSummary(rows) {
1074
+ return rows.map((x) => ({
1075
+ workflowName: x.workflowName || null, status: x.status || null,
1076
+ conclusion: x.conclusion || null, databaseId: x.databaseId || null,
1077
+ ...(x.setAsideWhy ? { why: x.setAsideWhy } : {}),
1078
+ }));
1079
+ }
1080
+
1081
+ /**
1082
+ * ghRunForCommit's pick, over rows already read (null in -> null out).
1083
+ *
1084
+ * #451: rows from workflows the repo does not own (`event: dynamic`) are dropped first; when any
1085
+ * were, the result carries an additive `excluded` list naming them, so a caller can say what it
1086
+ * did not count. When nothing is left the sha reads `none`, exactly as if no run had existed —
1087
+ * a repo-owned red is never affected, since only `dynamic` rows are dropped.
1088
+ *
1089
+ * #461: the repo-owned rows are then reduced to the newest run per workflow (newestRunPerWorkflow,
1090
+ * below); the rows that reduction set aside ride along as an additive `superseded` list, same shape
1091
+ * as `excluded`, present only when non-empty. Every quantifier below runs over the reduced set.
1092
+ *
1093
+ * #503: `opts.verifying` (a tools/lib/verify-runs.js policy, `{gate, ignore}`) narrows the owned rows
1094
+ * to the runs that VERIFY the code — push / pull-request triggered, or the declared set — BEFORE the
1095
+ * per-workflow reduction; the rest (a `workflow_run` release, a scheduled finalize, a deploy) ride
1096
+ * along as `setAside`, each with its reason. Opt-in: without `opts.verifying` nothing changes, so
1097
+ * readers that never asked (release finalize, the base-ci advisory, ci-grant) read exactly as before.
1098
+ */
1099
+ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1100
+ if (allForSha === null) return null;
1101
+ const dropped = allForSha.filter((x) => !isRepoOwnedRun(x));
1102
+ let owned = dropped.length ? allForSha.filter(isRepoOwnedRun) : allForSha;
1103
+ let setAside = [];
1104
+ if (opts && opts.verifying) {
1105
+ const split = require('./verify-runs').splitVerifying(owned, opts.verifying);
1106
+ owned = split.counted;
1107
+ setAside = split.setAside;
1108
+ }
1109
+ const { heads, superseded } = newestRunPerWorkflow(owned);
1110
+ const extra = {
1111
+ ...(dropped.length ? { excluded: excludedRunSummary(dropped) } : {}),
1112
+ ...(superseded.length ? { superseded: excludedRunSummary(superseded) } : {}),
1113
+ ...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
1114
+ };
1115
+ const r = summarizeRepoOwnedRuns(heads, sha);
1116
+ return { ...r, ...extra };
1117
+ }
1118
+
1119
+ /** Sort key for "which run of one workflow is newer": createdAt, then databaseId; null = unknown. */
1120
+ function runRecency(x) {
1121
+ const t = x && x.createdAt ? Date.parse(x.createdAt) : NaN;
1122
+ const id = x && x.databaseId != null ? Number(x.databaseId) : NaN;
1123
+ return { t: Number.isFinite(t) ? t : null, id: Number.isFinite(id) ? id : null };
1124
+ }
1125
+
1126
+ /** True when `a` is provably newer than `b`; false when older OR when neither key can tell. */
1127
+ function isNewerRun(a, b) {
1128
+ const ra = runRecency(a); const rb = runRecency(b);
1129
+ if (ra.t !== null && rb.t !== null && ra.t !== rb.t) return ra.t > rb.t;
1130
+ if (ra.id !== null && rb.id !== null && ra.id !== rb.id) return ra.id > rb.id;
1131
+ return false;
1132
+ }
1133
+
1134
+ /**
1135
+ * #461: each workflow is judged by its NEWEST run at the sha — an earlier attempt of the SAME
1136
+ * workflow that a later one superseded no longer vetoes it. Measured: a `workflow_run`-triggered
1137
+ * workflow fired once per CI attempt at one trunk sha; the two red CI attempts gave it two
1138
+ * `skipped` runs, the green third attempt a `success`, and the two stale rows held the sha
1139
+ * not-green forever (a re-run replays the original payload and skips again).
1140
+ *
1141
+ * Grouped by `workflowName` ONLY. A row with no workflowName (an older read, a hand-built fixture)
1142
+ * is its own group — absence of the field never collapses anything, so every verdict that could be
1143
+ * computed before #461 without the field is computed identically now. Rows of DIFFERENT workflows
1144
+ * are never reduced: a failing workflow beside a passing one still reads not-green (#146/#162).
1145
+ *
1146
+ * `cancelled` never supersedes: a cancelled run executed nothing and has always been neutral here
1147
+ * (#92), so it cannot stand for its workflow while that workflow has any non-cancelled run at the
1148
+ * sha — otherwise a cancel-in-progress straggler created after the passing run would turn #92's
1149
+ * green back into "every run was cancelled". It still counts when it is all a workflow has.
1150
+ *
1151
+ * Newest = later createdAt, then higher databaseId; when neither key separates two rows, gh's
1152
+ * newest-first order decides (the first row seen is kept). An unfinished newest run still blocks
1153
+ * green (#307): it is the head, so the all-finished quantifier sees it.
1154
+ *
1155
+ * Returns the heads in their original order (callers' newest-first `forSha[0]` pick relies on it)
1156
+ * plus the rows they superseded.
1157
+ */
1158
+ function newestRunPerWorkflow(rows) {
1159
+ const best = new Map();
1160
+ rows.forEach((x, i) => {
1161
+ const name = x && x.workflowName;
1162
+ if (!name) return;
1163
+ const cur = best.get(name);
1164
+ if (cur === undefined) { best.set(name, i); return; }
1165
+ const c = rows[cur];
1166
+ const xCancelled = x.conclusion === 'cancelled';
1167
+ const cCancelled = c.conclusion === 'cancelled';
1168
+ if (xCancelled !== cCancelled) { if (cCancelled) best.set(name, i); return; }
1169
+ if (isNewerRun(x, c)) best.set(name, i);
1170
+ });
1171
+ const heads = []; const superseded = [];
1172
+ rows.forEach((x, i) => {
1173
+ const name = x && x.workflowName;
1174
+ if (!name || best.get(name) === i) heads.push(x); else superseded.push(x);
1175
+ });
1176
+ return { heads, superseded };
1177
+ }
1178
+
1179
+ function summarizeRepoOwnedRuns(forSha, sha) {
943
1180
  if (forSha.length === 0) return { status: 'none', conclusion: null, sha, createdAt: null, databaseId: null, runCount: 0 };
944
1181
 
945
1182
  // runCount (#176) is additive: how many sibling workflow rows exist at this sha, so a caller can
946
1183
  // report "N runs at <sha>: all success" instead of a singular verdict that hides how many
947
1184
  // workflows actually agreed. It is the row count BEFORE any of the picks below, not "how many
948
1185
  // succeeded" — the picked row already tells the caller the conclusion; this tells it the sample size.
1186
+ // Since #461 that is the count of rows JUDGED (one per named workflow, after superseded attempts
1187
+ // are set aside) — "3 runs: all success" must never count two skipped attempts it did not judge.
949
1188
  const runCount = forSha.length;
950
1189
 
951
1190
  // A completed sibling whose conclusion is anything but success or cancelled makes the sha
@@ -988,7 +1227,7 @@ function summarizeRunsForCommit(forSha, sha) {
988
1227
  */
989
1228
  function ghRunJobCount(repo, runDatabaseId) {
990
1229
  if (runDatabaseId === null || runDatabaseId === undefined) return null;
991
- const r = run('gh', ['run', 'view', String(runDatabaseId), '--json', 'jobs', '-q', '.jobs | length'], { cwd: repo });
1230
+ const r = gh(['run', 'view', String(runDatabaseId), '--json', 'jobs', '-q', '.jobs | length'], { cwd: repo });
992
1231
  if (!r.ok) return null;
993
1232
  const n = Number(r.stdout);
994
1233
  return Number.isFinite(n) ? n : null;
@@ -1015,7 +1254,7 @@ function ghRunJobCount(repo, runDatabaseId) {
1015
1254
  */
1016
1255
  function ghRunJobs(repo, runDatabaseId) {
1017
1256
  if (runDatabaseId === null || runDatabaseId === undefined) return null;
1018
- const r = run('gh', ['run', 'view', String(runDatabaseId), '--json', 'jobs'], { cwd: repo });
1257
+ const r = gh(['run', 'view', String(runDatabaseId), '--json', 'jobs'], { cwd: repo });
1019
1258
  if (!r.ok) return null;
1020
1259
  let parsed;
1021
1260
  try { parsed = JSON.parse(r.stdout); } catch (_) { return null; }
@@ -1032,12 +1271,54 @@ function ghRunJobs(repo, runDatabaseId) {
1032
1271
  }));
1033
1272
  }
1034
1273
 
1274
+ /**
1275
+ * Every check run at one commit, flattened for the #493 tree-skip read — `[{id, name, status,
1276
+ * conclusion, suite, annotations}]` (`suite` = check-suite id = one workflow run; `annotations` =
1277
+ * output.annotations_count), or null on a gh/parse failure. One call per green trunk read, made
1278
+ * lazily by readCiVerdict; `{owner}/{repo}` is resolved by gh from the cwd's remote.
1279
+ */
1280
+ function ghCommitCheckRuns(repo, sha) {
1281
+ if (!sha) return null;
1282
+ const r = gh(['api', `repos/{owner}/{repo}/commits/${sha}/check-runs?per_page=100`,
1283
+ '--jq', '[.check_runs[] | {id, name, status, conclusion, suite: .check_suite.id, annotations: .output.annotations_count}]'], { cwd: repo });
1284
+ if (!r.ok) return null;
1285
+ try { const v = JSON.parse(r.stdout); return Array.isArray(v) ? v : null; } catch (_) { return null; }
1286
+ }
1287
+
1288
+ /** One check run's annotations as `[{title, message, level}]`, or null on failure (#493). */
1289
+ function ghCheckRunAnnotations(repo, checkRunId) {
1290
+ if (checkRunId === null || checkRunId === undefined) return null;
1291
+ const r = gh(['api', `repos/{owner}/{repo}/check-runs/${checkRunId}/annotations`,
1292
+ '--jq', '[.[] | {title, message, level: .annotation_level}]'], { cwd: repo });
1293
+ if (!r.ok) return null;
1294
+ try { const v = JSON.parse(r.stdout); return Array.isArray(v) ? v : null; } catch (_) { return null; }
1295
+ }
1296
+
1297
+ /**
1298
+ * Dispatch `workflowFile` on `ref` (#474) — `gh workflow run <file> --ref <ref> -f k=v…`. Returns
1299
+ * `{ok, withInputs, detail}`. If the call with inputs is refused (GitHub can validate inputs against
1300
+ * a workflow file that does not declare them yet), it is retried ONCE without them: the release-auto
1301
+ * template forces dry mode on any ref other than main, so an input-less dispatch of a capable file is
1302
+ * still a dry run. The caller only ever dispatches a file it read as dry-run capable at that ref.
1303
+ * Never waits for the run.
1304
+ */
1305
+ function ghWorkflowDispatch(repo, workflowFile, ref, inputs = {}) {
1306
+ const flags = [];
1307
+ for (const [k, v] of Object.entries(inputs)) flags.push('-f', `${k}=${v}`);
1308
+ const first = gh(['workflow', 'run', workflowFile, '--ref', ref, ...flags], { cwd: repo });
1309
+ if (first.ok) return { ok: true, withInputs: true, detail: '' };
1310
+ if (!flags.length) return { ok: false, withInputs: false, detail: (first.stderr || first.stdout || '').trim().split('\n')[0] || 'gh workflow run failed' };
1311
+ const second = gh(['workflow', 'run', workflowFile, '--ref', ref], { cwd: repo });
1312
+ if (second.ok) return { ok: true, withInputs: false, detail: (first.stderr || '').trim().split('\n')[0] || '' };
1313
+ return { ok: false, withInputs: false, detail: (second.stderr || second.stdout || '').trim().split('\n')[0] || 'gh workflow run failed' };
1314
+ }
1315
+
1035
1316
  /**
1036
1317
  * Issues claimed by the current gh user in a repo = assigned to @me AND labeled in-progress
1037
1318
  * (that pairing is exactly what `colab claim` writes). Returns array of numbers, or null on failure.
1038
1319
  */
1039
1320
  function ghAssignedIssues(repo) {
1040
- const r = run('gh', ['issue', 'list', '--assignee', '@me', '--label', 'in-progress', '--state', 'open',
1321
+ const r = gh(['issue', 'list', '--assignee', '@me', '--label', 'in-progress', '--state', 'open',
1041
1322
  '--json', 'number', '--limit', '200'], { cwd: repo });
1042
1323
  if (!r.ok) return null;
1043
1324
  try { return JSON.parse(r.stdout).map((o) => o.number); }
@@ -1045,14 +1326,15 @@ function ghAssignedIssues(repo) {
1045
1326
  }
1046
1327
 
1047
1328
  module.exports = {
1329
+ ghCommitCheckRuns, ghCheckRunAnnotations,
1048
1330
  run, git, repoRoot, mainRepoRoot, originUrl, remoteInfo, remoteName, remoteFor, remoteUrl, remoteProblem, _resetRemoteCache,
1049
1331
  detectTrunk, branchExists, branchRefs, existingBranchRef,
1050
1332
  claimRemote, remoteHeads,
1051
1333
  worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
1052
1334
  dirtyTracked, dirtyUntracked, dirtyAny,
1053
- ghAvailable, ghState, ghIssueEdit, ghListLabels, ghAssignedIssues,
1054
- ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit,
1055
- ghRunJobCount, ghRunJobs,
1335
+ ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, fullSha, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
1336
+ ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
1337
+ ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
1056
1338
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
1057
1339
  ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
1058
1340
  ghPrForBranch, ghPrCreate, ghPrClose, ghRepoVisibility,