@futurelastic/colab-handbook 1.13.0-rc.9 → 1.13.0
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/README.md +50 -20
- package/README.vi.md +53 -23
- package/audit/audit.mjs +116 -15
- package/package.json +1 -1
- package/templates/README.md +1 -1
- package/templates/ci-laravel.yml +72 -5
- package/templates/ci-node.yml +74 -6
- package/templates/ci-python.yml +74 -6
- package/templates/release-auto.yml +68 -4
- package/tools/colab +784 -91
- package/tools/lib/batch-history.js +104 -0
- package/tools/lib/batch-stats.js +277 -0
- package/tools/lib/ci-profile.js +195 -0
- package/tools/lib/ci-verdict.js +13 -5
- package/tools/lib/ci-wait.js +6 -1
- package/tools/lib/codec/claim.js +6 -3
- package/tools/lib/config-set.js +319 -0
- package/tools/lib/disposition.js +9 -6
- package/tools/lib/docs-only.js +1 -1
- package/tools/lib/engines.js +52 -0
- package/tools/lib/git.js +70 -15
- package/tools/lib/install-check.js +77 -5
- package/tools/lib/journal.js +3 -0
- package/tools/lib/notify-endpoint.js +114 -59
- package/tools/lib/notify.js +68 -22
- package/tools/lib/release-cut.js +39 -3
- package/tools/lib/release-finalize.js +110 -15
- package/tools/lib/release-policy.js +11 -3
- package/tools/lib/ship-batch.js +109 -2
- package/tools/lib/shipguard.js +12 -1
- package/tools/lib/thresholds.js +110 -0
- package/tools/lib/verify-runs.js +117 -4
package/tools/colab
CHANGED
|
@@ -49,6 +49,8 @@ const baseCiVerdict = require('./lib/base-ci-verdict');
|
|
|
49
49
|
const treeGreen = require('./lib/tree-green');
|
|
50
50
|
const verifyRuns = require('./lib/verify-runs');
|
|
51
51
|
const ciWait = require('./lib/ci-wait'); // #495
|
|
52
|
+
const ciProfile = require('./lib/ci-profile'); // #559
|
|
53
|
+
const thresholdsLib = require('./lib/thresholds'); // #560
|
|
52
54
|
const staleBase = require('./lib/stale-base');
|
|
53
55
|
const dirtyOwner = require('./lib/dirty-owner');
|
|
54
56
|
const scratchDirs = require('./lib/scratch-dirs');
|
|
@@ -63,8 +65,10 @@ const codec = require('./lib/codec');
|
|
|
63
65
|
const machine = require('./lib/machine');
|
|
64
66
|
const targetSync = require('./lib/ship-target-sync');
|
|
65
67
|
const shipBatch = require('./lib/ship-batch');
|
|
68
|
+
const batchStats = require('./lib/batch-stats');
|
|
66
69
|
const conflictMarkers = require('./lib/conflict-markers');
|
|
67
70
|
const docsOnly = require('./lib/docs-only');
|
|
71
|
+
const configSet = require('./lib/config-set'); // #561
|
|
68
72
|
const cureDiff = require('./lib/cure-diff');
|
|
69
73
|
const codeowners = require('./lib/codeowners');
|
|
70
74
|
const releasePolicy = require('./lib/release-policy');
|
|
@@ -283,8 +287,9 @@ function commentHost(repoAbs) {
|
|
|
283
287
|
function myMachineId() { return machine.localMachine().id || null; }
|
|
284
288
|
|
|
285
289
|
/**
|
|
286
|
-
* Resolve the
|
|
287
|
-
* a DERIVED person identity (#528) > '' (absent, never an error). Free-form —
|
|
290
|
+
* Resolve the session id for this invocation: --session flag > COLAB_SESSION env >
|
|
291
|
+
* a DERIVED person identity (#528) > '' (absent, never an error). Free-form — any stable id for
|
|
292
|
+
* the session (a URL, a uuid…).
|
|
288
293
|
*
|
|
289
294
|
* The derived step exists for a person at a plain terminal, who has no session runtime and so no
|
|
290
295
|
* id to pass: without it their first trunk `colab claim` refused (#242's gate), `worktree new`
|
|
@@ -390,7 +395,7 @@ function warnWeakIdentity(session, sessionName, what, ref) {
|
|
|
390
395
|
warn(`no --session or --session-name given — this ${what} will carry NO holder identity.`);
|
|
391
396
|
warn(` A live hold's refusal can then only point at its process id, and this acquire will`);
|
|
392
397
|
warn(` not be recognized as your own on a later re-acquire without one.`);
|
|
393
|
-
if (ref) warn(` Repair once you have an identity: colab worktree tag ${ref} --session <
|
|
398
|
+
if (ref) warn(` Repair once you have an identity: colab worktree tag ${ref} --session <id>`);
|
|
394
399
|
return;
|
|
395
400
|
}
|
|
396
401
|
// #326: a planner intent id is a deliberate, documented non-URL value — not a mistyped name.
|
|
@@ -401,16 +406,16 @@ function warnWeakIdentity(session, sessionName, what, ref) {
|
|
|
401
406
|
// refused the caller's own hold when they later presented their REAL url. Warn, never
|
|
402
407
|
// refuse: `requirePlaceIdentity` promises `<url-or-any-stable-id>`, so a bare stable id is
|
|
403
408
|
// a blessed value and rejecting it would break that contract and every adopter using one.
|
|
404
|
-
warn(`--session "${session}" does not look like a session URL
|
|
409
|
+
warn(`--session "${session}" does not look like a session id (a URL, a uuid, a session_… token) — this ${what}`);
|
|
405
410
|
warn(` will record it verbatim. That is allowed (any stable id works), but if this is your`);
|
|
406
411
|
warn(` session NAME you probably meant --session-name: a later 'colab place release'`);
|
|
407
|
-
warn(` presenting your real
|
|
412
|
+
warn(` presenting your real id will NOT match this value and will be refused (#306).`);
|
|
408
413
|
return;
|
|
409
414
|
}
|
|
410
415
|
if (!sessionName || session) return;
|
|
411
|
-
warn(`session name "${sessionName}" recorded with NO session
|
|
412
|
-
warn(` but cannot be traced to a session. The name is display text; the
|
|
413
|
-
if (ref) warn(` Repair once you have it: colab worktree tag ${ref} --session <
|
|
416
|
+
warn(`session name "${sessionName}" recorded with NO session id — this ${what} will read as owned`);
|
|
417
|
+
warn(` but cannot be traced to a session. The name is display text; the id is the join key.`);
|
|
418
|
+
if (ref) warn(` Repair once you have it: colab worktree tag ${ref} --session <id>`);
|
|
414
419
|
}
|
|
415
420
|
|
|
416
421
|
/**
|
|
@@ -469,8 +474,8 @@ function identityCell(sessionName, session) {
|
|
|
469
474
|
/** Print the `(!)` legend under a table, only when at least one row carries a half-identity. */
|
|
470
475
|
function identityLegend(entries) {
|
|
471
476
|
if (!entries.some((e) => e && e.sessionName && !e.session)) return;
|
|
472
|
-
print(' (!) session NAME with no session
|
|
473
|
-
print(' Repair: colab worktree tag <worktree> --session <
|
|
477
|
+
print(' (!) session NAME with no session id — reads as owned, links to nothing.');
|
|
478
|
+
print(' Repair: colab worktree tag <worktree> --session <id>');
|
|
474
479
|
}
|
|
475
480
|
|
|
476
481
|
/**
|
|
@@ -521,8 +526,9 @@ function localClaimConflicts(st, repoAbs, nums, wtName) {
|
|
|
521
526
|
|
|
522
527
|
/**
|
|
523
528
|
* #325 — the claim record every machine can read, whatever the tracker: a branch on the remote whose
|
|
524
|
-
* name carries the issue number (CONVENTIONS.md §4 puts the numbers in the trailing run
|
|
525
|
-
*
|
|
529
|
+
* name carries the issue number (CONVENTIONS.md §4 puts the numbers in the trailing run), or — since
|
|
530
|
+
* #550 — the claim ref `refs/claims/<branch>` that `colab worktree new` pushes the moment it cuts
|
|
531
|
+
* (a ref no CI trigger watches; the branch itself follows at code-wrap). Asked of the remote directly (`ls-remote`, no fetch), so a
|
|
526
532
|
* clone that has never fetched sees exactly what a fresh one would.
|
|
527
533
|
*
|
|
528
534
|
* `mode`:
|
|
@@ -557,7 +563,7 @@ function remoteClaimConflicts(st, repoAbs, nums) {
|
|
|
557
563
|
for (const h of heads.heads) {
|
|
558
564
|
const carried = branchName.claimIssueNumbers(h.branch, scope).filter((n) => want.has(n));
|
|
559
565
|
if (!carried.length || ours(h.branch)) continue;
|
|
560
|
-
for (const num of carried) conflicts.push({ num, remote, branch: h.branch, sha: h.sha });
|
|
566
|
+
for (const num of carried) conflicts.push({ num, remote, branch: h.branch, sha: h.sha, claimRef: !!h.claimRef });
|
|
561
567
|
}
|
|
562
568
|
return { mode: 'ok', remote, conflicts };
|
|
563
569
|
}
|
|
@@ -666,13 +672,18 @@ function ghClaimConflicts(repoAbs, nums, myLogin, myHost, mySession, comps, myMa
|
|
|
666
672
|
function printRefusal(localConf, ghConf, remoteConf = []) {
|
|
667
673
|
process.stderr.write('✗ Refusing — one or more issues are already claimed:\n');
|
|
668
674
|
for (const c of remoteConf) {
|
|
669
|
-
process.stderr.write(
|
|
675
|
+
process.stderr.write(c.claimRef
|
|
676
|
+
? ` #${c.num} remote: claim ref ${c.remote} ${git.claimRef(c.branch)} @ ${c.sha} carries it (branch not pushed yet), and it is not this machine's (#325, #550)\n`
|
|
677
|
+
: ` #${c.num} remote: branch ${c.remote}/${c.branch} @ ${c.sha} carries it, and it is not this machine's (#325)\n`);
|
|
670
678
|
}
|
|
671
679
|
if (remoteConf.length) {
|
|
672
680
|
const c = remoteConf[0];
|
|
673
|
-
process.stderr.write(
|
|
674
|
-
process.stderr.write(
|
|
681
|
+
process.stderr.write(` That ${c.claimRef ? 'claim ref' : 'branch'} IS the claim — continue it rather than open a second one:\n`);
|
|
682
|
+
process.stderr.write(c.claimRef
|
|
683
|
+
? ` git fetch ${c.remote} ${git.claimRef(c.branch)}:refs/heads/${c.branch} && git worktree add <path> ${c.branch}\n`
|
|
684
|
+
: ` git fetch ${c.remote} ${c.branch} && git worktree add <path> ${c.branch}\n`);
|
|
675
685
|
process.stderr.write(` colab claim ${c.num} --worktree <name> --branch ${c.branch} --session <id> --force\n`);
|
|
686
|
+
if (c.claimRef) process.stderr.write(` A claim ref whose session is gone is stale — delete it: git push ${c.remote} --delete ${git.claimRef(c.branch)}\n`);
|
|
676
687
|
}
|
|
677
688
|
for (const c of localConf) {
|
|
678
689
|
const h = c.holder;
|
|
@@ -709,7 +720,7 @@ function halfClaimText(c) {
|
|
|
709
720
|
/** Announce exactly what --force overrides (a takeover is visible, never silent). */
|
|
710
721
|
function printTakeover(localConf, ghConf, remoteConf = []) {
|
|
711
722
|
for (const c of remoteConf) {
|
|
712
|
-
print(` --force: taking over #${c.num} although branch ${c.remote}/${c.branch} @ ${c.sha} carries it (not this machine's)`);
|
|
723
|
+
print(` --force: taking over #${c.num} although ${c.claimRef ? `claim ref ${c.remote} ${git.claimRef(c.branch)}` : `branch ${c.remote}/${c.branch}`} @ ${c.sha} carries it (not this machine's)`);
|
|
713
724
|
}
|
|
714
725
|
for (const c of localConf) {
|
|
715
726
|
const h = c.holder;
|
|
@@ -876,7 +887,8 @@ const HELP_CLAIM = `colab claim <issue> [<issue> ...] [options]
|
|
|
876
887
|
|
|
877
888
|
Claim one or more GitHub issues so parallel sessions/agents don't collide.
|
|
878
889
|
The claim RECORD every machine reads is a branch on the git remote carrying the issue number
|
|
879
|
-
(\`colab worktree new\`
|
|
890
|
+
(\`colab worktree new\` records it the moment it is cut as the claim ref refs/claims/<branch>,
|
|
891
|
+
which no CI trigger watches — #325, #550). Also writes local state (fast path)
|
|
880
892
|
and the tracker (the copy people read):
|
|
881
893
|
gh issue edit N --add-assignee @me --add-label in-progress
|
|
882
894
|
Remote unreachable → REFUSED (fail closed). Tracker unreachable → the claim stands and its tracker
|
|
@@ -918,7 +930,8 @@ Options:
|
|
|
918
930
|
--branch <name> branch these claims are worked on. Default: none (null) — a claim held on
|
|
919
931
|
the trunk checkout has no branch. Never the word "trunk": that is a role,
|
|
920
932
|
and a record holding it resolves to no ref (refused, exit 1)
|
|
921
|
-
--session <
|
|
933
|
+
--session <id> any stable id for this session (a URL, a uuid…), recorded on the claim + comment
|
|
934
|
+
(default: COLAB_SESSION env).
|
|
922
935
|
MANDATORY when no --worktree is given (#242): a claim with no worktree takes
|
|
923
936
|
the trunk-checkout place-claim, and a blank session can never be recognized
|
|
924
937
|
as its own later re-acquire — refused (exit 1) before anything is read/written.
|
|
@@ -1842,7 +1855,8 @@ const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto |
|
|
|
1842
1855
|
Take the newest release CANDIDATE (a vX.Y.Z-rc.N tag made by \`colab release cut\`) one step further
|
|
1843
1856
|
under CONVENTIONS.md §6's release rung, re-checking everything at the moment it runs. Every run:
|
|
1844
1857
|
|
|
1845
|
-
1. fetches tags, picks the newest open candidate (never a hand-made or
|
|
1858
|
+
1. fetches tags, picks the newest open candidate — or the one --tag names (never a hand-made or
|
|
1859
|
+
off-main one);
|
|
1846
1860
|
2. finds — or, without --dry, opens — the version's tracking issue, "release: vX.Y.Z", whose body
|
|
1847
1861
|
starts <!-- colab:release version=vX.Y.Z --> (one per version, never per candidate);
|
|
1848
1862
|
3. measures, and ends in exactly one state:
|
|
@@ -1868,14 +1882,17 @@ under CONVENTIONS.md §6's release rung, re-checking everything at the moment it
|
|
|
1868
1882
|
|
|
1869
1883
|
Conditions (--json checks[].condition; required:false means reported, not blocking, on this row):
|
|
1870
1884
|
release-policy candidate tracking-issue release-hold regressions test-period trunk-green
|
|
1871
|
-
ci-green full-suite schema-additive switch-dependencies final-grant migration-grant human
|
|
1885
|
+
ci-green full-suite cut-run schema-additive switch-dependencies final-grant migration-grant human
|
|
1872
1886
|
|
|
1873
1887
|
regressions blocked_by edges on the tracking issue: open -> refused; closed after the period
|
|
1874
1888
|
began -> needs-new-candidate. Record one with: colab blocked <tracking> --by <issue>
|
|
1875
1889
|
test-period from max(candidate tag date, tracking issue creation), release: test-period long
|
|
1890
|
+
cut-run the run that cut the candidate (in progress at the tag's date) concluded success — a
|
|
1891
|
+
cancelled publish refuses; an earlier green run at the commit that cut nothing never
|
|
1892
|
+
vouches for it (#566)
|
|
1876
1893
|
trunk-green every run since the period began on main — and on project.yml's trunk: when that is
|
|
1877
1894
|
another branch (trunk: dev, #437) — of the workflows that ran at the candidate,
|
|
1878
|
-
none red — required only where the final is automatic
|
|
1895
|
+
none red — required only where the final is automatic, or for an older --tag (#548)
|
|
1879
1896
|
|
|
1880
1897
|
manifest-version on-trunk outranks-final — #424's pre-tag checks, required before any final:
|
|
1881
1898
|
the final equals every declared manifest version, its commit is on main (a shallow
|
|
@@ -1897,9 +1914,15 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
|
|
|
1897
1914
|
never tags: it stops at candidate-ready and posts the one command, number
|
|
1898
1915
|
pre-filled. Never combines with --tag/--answered-by. testing / no-candidate /
|
|
1899
1916
|
already-final exit 0 (nothing to do yet is the ordinary output)
|
|
1900
|
-
--tag <rc> pin the candidate a human reviewed
|
|
1917
|
+
--tag <rc> pin the candidate a human reviewed — the newest one, or any OLDER open candidate
|
|
1918
|
+
(#548). An older one is judged on its own clock exactly as --auto judges it: its
|
|
1919
|
+
own test period must have elapsed and trunk-green is read over its own window, on
|
|
1920
|
+
every row; release-hold and regressions as always. Newer candidates stay open
|
|
1921
|
+
for the next version — only versions below the final are closed as superseded
|
|
1901
1922
|
--answered-by <n> with COLAB_HUMAN=1 and --tag: the human bar for a final that is a human act.
|
|
1902
|
-
No field, flag or project.yml value lowers it, and it never shortens a test period
|
|
1923
|
+
No field, flag or project.yml value lowers it, and it never shortens a test period.
|
|
1924
|
+
Where the final is a human act the period is informational anyway, and
|
|
1925
|
+
release.test-period: 0d declares none at all (#549)
|
|
1903
1926
|
--dry measure and report; open, post, tag and close nothing
|
|
1904
1927
|
--json { repo, row, route, final, testPeriodDays, lastFinal, dry, auto, candidate, tracking,
|
|
1905
1928
|
periodStart, periodEndsAt, state, tagged, finalTag, checks, handoff,
|
|
@@ -1971,6 +1994,8 @@ function cmdReleaseFinalize(argv) {
|
|
|
1971
1994
|
const newest = selection.kind === 'candidate' ? selection.candidate : null;
|
|
1972
1995
|
// #423: on a route whose final is automatic, --auto judges every open candidate on its own clock.
|
|
1973
1996
|
const walk = opts.auto && policy.effective.final === 'auto' && newest;
|
|
1997
|
+
// #548: --tag naming an older open candidate — judged on its own clock, as the walk judges it.
|
|
1998
|
+
const ownClock = walk || (selection.kind === 'candidate' && !!selection.older);
|
|
1974
1999
|
|
|
1975
2000
|
// ---- the tracking records (one issue read for the whole run) ----
|
|
1976
2001
|
const issues = readAllIssuesForSwitches(repoAbs);
|
|
@@ -2013,14 +2038,20 @@ function cmdReleaseFinalize(argv) {
|
|
|
2013
2038
|
if (!trackings.has(cand.version)) trackings.set(cand.version, trackingFor(cand.version, { isCandidate: true }));
|
|
2014
2039
|
const tracking = trackings.get(cand.version);
|
|
2015
2040
|
const supersededHeld = records.filter((r) => r.state === 'OPEN' && r.held && r.version !== cand.version && !finals.has(r.version)).map((r) => r.number);
|
|
2016
|
-
let rows;
|
|
2041
|
+
let rows; let rawRows;
|
|
2017
2042
|
const conditions = measureCandidateConditions(repoAbs, {
|
|
2018
2043
|
sha: cand.sha,
|
|
2019
2044
|
lastFinal: releaseTag.latestReleaseTag(repoAbs, { ref: cand.sha }),
|
|
2020
2045
|
at: `${cand.tag}@${shortSha(cand.sha)}`,
|
|
2021
|
-
readRuns: () => {
|
|
2046
|
+
readRuns: () => { rawRows = git.ghRunsAtCommit(repoAbs, cand.sha); rows = releaseCut.withoutOwnWorkflow(rawRows); return rows; }, // #425
|
|
2022
2047
|
issues,
|
|
2023
2048
|
});
|
|
2049
|
+
// #566: only the run that CUT the candidate vouches for what it published — read from the rows
|
|
2050
|
+
// BEFORE the #425 own-workflow filter (the release workflow is the cutter), minus this run itself.
|
|
2051
|
+
const cutRun = releaseFinalize.cutRunVerdict(rawRows, {
|
|
2052
|
+
tag: cand.tag, cutAt: cand.cutAt, ownRunId: process.env.GITHUB_ACTIONS === 'true' ? process.env.GITHUB_RUN_ID || null : null,
|
|
2053
|
+
jobCount: (id) => git.ghRunJobCount(repoAbs, id),
|
|
2054
|
+
});
|
|
2024
2055
|
const suiteWorkflows = [...new Set((rows || []).map((r) => r.workflowName || '(unnamed workflow)'))];
|
|
2025
2056
|
const period = releaseFinalize.periodVerdict({ cutAt: cand.cutAt, trackingCreatedAt: tracking && tracking.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
|
|
2026
2057
|
// #437: the window is main plus project.yml's trunk: when that is another branch (trunk: dev).
|
|
@@ -2029,7 +2060,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2029
2060
|
return { branch, read: raw ? { ...raw, runs: releaseCut.withoutOwnWorkflow(raw.runs) } : null }; // #425
|
|
2030
2061
|
}));
|
|
2031
2062
|
const trunk = releaseFinalize.trunkGreenVerdict(since ? since.runs : null, {
|
|
2032
|
-
periodStart: period.start, periodEnd:
|
|
2063
|
+
periodStart: period.start, periodEnd: ownClock ? period.endsAt : null, suiteWorkflows, truncated: !!(since && since.truncated), branches: windowBranches,
|
|
2033
2064
|
});
|
|
2034
2065
|
const regressions = releaseFinalize.regressionVerdict(tracking && tracking.number ? readRegressionEdges(repoAbs, tracking.number) : [], { periodStart: period.start });
|
|
2035
2066
|
const { manifests, ancestry } = measurePreTag(repoAbs, cand.sha, `${remote}/main`); // #424
|
|
@@ -2044,7 +2075,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2044
2075
|
}
|
|
2045
2076
|
const verdict = releaseFinalize.decide({
|
|
2046
2077
|
policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
|
|
2047
|
-
ci: conditions.ci, suite: conditions.suite, schema: conditions.schema, switches: conditions.switches,
|
|
2078
|
+
ci: conditions.ci, suite: conditions.suite, cutRun, schema: conditions.schema, switches: conditions.switches,
|
|
2048
2079
|
manifests, ancestry, tags: tagNames, finalGrant, migrations,
|
|
2049
2080
|
human: { bar: humanBar, answeredBy: opts.answeredBy || null },
|
|
2050
2081
|
});
|
|
@@ -2108,7 +2139,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2108
2139
|
const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
|
|
2109
2140
|
if (!opts.dry) {
|
|
2110
2141
|
if (verdict.state === 'finalized') {
|
|
2111
|
-
const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1)` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}`;
|
|
2142
|
+
const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1)` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}${selection.older ? `, an older candidate clean on its own clock (--tag; newest open: ${selection.newest})` : ''}`;
|
|
2112
2143
|
const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor });
|
|
2113
2144
|
const t = git.git(['tag', '-a', '--cleanup=verbatim', cand.version, cand.sha, '-m', message], repoAbs);
|
|
2114
2145
|
if (!t.ok) throw new UserError(`git tag ${cand.version} failed: ${(t.stderr || '').split('\n')[0]}`);
|
|
@@ -2130,7 +2161,9 @@ function cmdReleaseFinalize(argv) {
|
|
|
2130
2161
|
const tNew = version0 ? trackings.get(version0) : null;
|
|
2131
2162
|
if (newest && tNew && tNew.number) {
|
|
2132
2163
|
const pNew = releaseFinalize.periodVerdict({ cutAt: newest.cutAt, trackingCreatedAt: tNew.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
|
|
2133
|
-
comment(tNew.number, { candidate: newest.tag },
|
|
2164
|
+
comment(tNew.number, { candidate: newest.tag }, pNew.days === 0
|
|
2165
|
+
? `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — no test period on this repo (\`release.test-period: 0d\`, #549): the human's finalize is the test.`
|
|
2166
|
+
: ownClock
|
|
2134
2167
|
? `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its own test period runs ${pNew.start} → ${pNew.endsAt}. A newer candidate does not restart an older one's clock: the newest candidate clean for its own period is finalized (\`--auto\`).`
|
|
2135
2168
|
: `Candidate **${newest.tag}** (\`${shortSha(newest.sha)}\`) picked up — its test period runs ${pNew.start} → ${pNew.endsAt}. A new candidate restarts it.`);
|
|
2136
2169
|
}
|
|
@@ -2147,12 +2180,14 @@ function cmdReleaseFinalize(argv) {
|
|
|
2147
2180
|
// #426: every issue the final carries hears which version has it — on the run that tags, and on
|
|
2148
2181
|
// the already-final resume (a run that died between the tag push and these comments finishes them).
|
|
2149
2182
|
if (tagged) announced = announceRelease(cand.version, cand.sha);
|
|
2150
|
-
// Superseded records
|
|
2151
|
-
//
|
|
2152
|
-
//
|
|
2153
|
-
|
|
2183
|
+
// Superseded records: only versions BELOW one just tagged, on every path (#548). Before #548 a run
|
|
2184
|
+
// without --auto closed every other open version at once, because only the newest candidate could
|
|
2185
|
+
// ever be finalized; now `--tag` may finalize any open candidate, so an older version's record has
|
|
2186
|
+
// to stay open until a final above it exists — closing it earlier refuses that --tag ("closed but
|
|
2187
|
+
// not final"). A newer version's candidates are still on their own clocks either way.
|
|
2188
|
+
if (cand && tagged) {
|
|
2154
2189
|
for (const r of records.filter((x) => x.state === 'OPEN' && !x.held && x.version !== cand.version && !finals.has(x.version)
|
|
2155
|
-
&&
|
|
2190
|
+
&& releaseFinalize.compareVersions(x.version, cand.version) < 0)) {
|
|
2156
2191
|
comment(r.number, { state: 'superseded', by: cand.version }, `Superseded by ${cand.version} — no final is owed for ${r.version}.`);
|
|
2157
2192
|
close(r.number);
|
|
2158
2193
|
}
|
|
@@ -2798,7 +2833,7 @@ function cmdGateHermetic(argv) {
|
|
|
2798
2833
|
// neither, so there is nothing else in state.json a second solo attempt could collide with.
|
|
2799
2834
|
// ---------------------------------------------------------------------------
|
|
2800
2835
|
|
|
2801
|
-
const HELP_SOLO = `colab solo [--repo <path>] [--force] [--session <
|
|
2836
|
+
const HELP_SOLO = `colab solo [--repo <path>] [--force] [--session <id>] [--session-name <name>]
|
|
2802
2837
|
colab solo --done [--repo <path>]
|
|
2803
2838
|
|
|
2804
2839
|
Entry gate for solo flow (CONVENTIONS.md, Solo flow) — requires BOTH: this repo does not declare
|
|
@@ -3073,7 +3108,7 @@ function cmdSoloDone(repoAbs, doc) {
|
|
|
3073
3108
|
// exactly `writes: isolated` — see writes-authority.js's `trunkDirectVetoed`)
|
|
3074
3109
|
// ---------------------------------------------------------------------------
|
|
3075
3110
|
|
|
3076
|
-
const HELP_PLACE = `colab place <acquire|check|release> <path> [--repo P] [--session
|
|
3111
|
+
const HELP_PLACE = `colab place <acquire|check|release> <path> [--repo P] [--session ID] [--session-name N] [--force]
|
|
3077
3112
|
|
|
3078
3113
|
Path-scoped, machine-local hold on ONE checkout (CONVENTIONS.md, Place-claims) — what a shared
|
|
3079
3114
|
trunk checkout needs on any repo that does not declare \`writes: isolated\` (the veto), and a
|
|
@@ -3891,12 +3926,26 @@ function migrationGrantReviewRecord(repoAbs, opts) {
|
|
|
3891
3926
|
// #508: bind what was reviewed — the branch's migration files at the tip, by content. Same path
|
|
3892
3927
|
// rule the ship gate fires on (newMigrations), against origin's trunk. A branch with no migration
|
|
3893
3928
|
// to review gets no id and stays HEAD-bound.
|
|
3929
|
+
//
|
|
3930
|
+
// #563: and never silently fall back to HEAD binding. A grant posted without `migrations:` for a
|
|
3931
|
+
// branch that HAS migrations is voided by the very trunk sync ship demands — the cost #508 removed.
|
|
3932
|
+
// So every way this can fail to answer refuses instead: no trunk to diff against, a diff git
|
|
3933
|
+
// cannot compute (base or tip object missing here), or a tree it cannot read at the tip.
|
|
3894
3934
|
const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
|
|
3935
|
+
if (!trunk) {
|
|
3936
|
+
throw new UserError("cannot resolve this repo's trunk from project.yml — a reviewer grant binds the branch's migration content against trunk, so nothing was posted. Declare `trunk:` in .github/project.yml, then re-run `colab migration-grant`");
|
|
3937
|
+
}
|
|
3895
3938
|
const remote = git.remoteInfo(repoAbs).name || 'origin';
|
|
3896
|
-
let base =
|
|
3897
|
-
if (
|
|
3898
|
-
const migrations =
|
|
3939
|
+
let base = `${remote}/${trunk}`;
|
|
3940
|
+
if (!git.git(['rev-parse', '--verify', '--quiet', `${base}^{commit}`], repoAbs).ok) base = trunk;
|
|
3941
|
+
const migrations = newMigrationsOrNull(repoAbs, base, tip);
|
|
3942
|
+
if (migrations === null) {
|
|
3943
|
+
throw new UserError(`cannot list "${opts.branch}"'s files against ${base} (git diff ${base}...${tip.slice(0, 12)} failed) — without that list the grant could not bind the migration content and would be voided by the next trunk sync; nothing was posted. Run \`git fetch ${remote} ${trunk} ${opts.branch}\`, then re-run \`colab migration-grant\``);
|
|
3944
|
+
}
|
|
3899
3945
|
const contentId = migrationContentAt(repoAbs, migrations, tip);
|
|
3946
|
+
if (migrations.length > 0 && !contentId) {
|
|
3947
|
+
throw new UserError(`"${opts.branch}" carries ${migrations.length} migration file(s) (${migrations.join(', ')}) but their content id could not be computed at ${tip.slice(0, 12)} (git ls-tree failed) — a grant without it binds the HEAD alone and the next trunk sync voids it; nothing was posted. Run \`git fetch ${remote} ${opts.branch}\`, then re-run \`colab migration-grant\``);
|
|
3948
|
+
}
|
|
3900
3949
|
|
|
3901
3950
|
const rec = {
|
|
3902
3951
|
v: '1', role, reviewer: opts.reviewer, head: tip,
|
|
@@ -5235,7 +5284,8 @@ dependency symlinking, dev-server restarts) live in OPTIONAL repo hooks, not her
|
|
|
5235
5284
|
<type>/, prefix or not; else the branch after its first '/')
|
|
5236
5285
|
--trunk <name> override trunk branch
|
|
5237
5286
|
--repo <path> repo root (default: git root of cwd)
|
|
5238
|
-
--session <
|
|
5287
|
+
--session <id> any stable id for this session (a URL, a uuid…), recorded on the worktree +
|
|
5288
|
+
its claims (env COLAB_SESSION)
|
|
5239
5289
|
--session-name <s> short human label for tables/messages (env COLAB_SESSION_NAME)
|
|
5240
5290
|
--pid <n|none> the new worktree's place-claim liveness anchor (#288) — same meaning as
|
|
5241
5291
|
\`colab claim\`'s --pid; default: auto-detect (env COLAB_PLACE_PID too)
|
|
@@ -5262,7 +5312,7 @@ dependency symlinking, dev-server restarts) live in OPTIONAL repo hooks, not her
|
|
|
5262
5312
|
and state record in place for a retry, unless --force. Refuses if there are
|
|
5263
5313
|
uncommitted TRACKED changes unless --force.
|
|
5264
5314
|
|
|
5265
|
-
colab worktree tag <name> --session <
|
|
5315
|
+
colab worktree tag <name> --session <id> [--session-name <s>] [--branch <b>]
|
|
5266
5316
|
REPAIR session identity, and/or the recorded branch, on a worktree that already
|
|
5267
5317
|
exists — and on every claim attached to it (claims hold their own copy of each
|
|
5268
5318
|
field, and claims are what \`doctor\` reports and what \`ship\` unions by). Pass any
|
|
@@ -5580,23 +5630,30 @@ function cmdWorktreeNew(argv) {
|
|
|
5580
5630
|
// rejected instead of overwriting. With issues to claim, a failed push takes nothing: the worktree
|
|
5581
5631
|
// and the zero-commit branch this invocation just made are removed again, so no half-claim exists
|
|
5582
5632
|
// anywhere. With no issues there is no claim to protect, and a failed push only warns.
|
|
5633
|
+
//
|
|
5634
|
+
// #550: what is pushed is the CLAIM REF `refs/claims/<branch>`, not the branch. A branch push fires
|
|
5635
|
+
// every CI `push` trigger, and at cut the branch IS trunk's commit — so each cut re-ran a suite
|
|
5636
|
+
// trunk had already passed (~27 % of one org's runs). A claim ref triggers nothing, and every
|
|
5637
|
+
// claim reader (`remoteHeads`) lists it beside the branches. The branch itself is first pushed at
|
|
5638
|
+
// code-wrap, when it has commits worth testing. The claim ref is deleted at `worktree rm`.
|
|
5583
5639
|
const pushRemote = git.claimRemote(repoAbs);
|
|
5584
5640
|
let pushed = false;
|
|
5585
5641
|
if (pushRemote) {
|
|
5586
|
-
const
|
|
5642
|
+
const claimRef = git.claimRef(branch);
|
|
5643
|
+
const push = git.pushClaimRef(repoAbs, pushRemote, branch);
|
|
5587
5644
|
if (push.ok) {
|
|
5588
5645
|
pushed = true;
|
|
5589
|
-
print(` pushed ${
|
|
5646
|
+
print(` pushed ${claimRef} → ${pushRemote} (the claim record other machines read; not a branch, so no CI runs — the branch is pushed at code-wrap)`);
|
|
5590
5647
|
} else {
|
|
5591
5648
|
const why = String(push.stderr || '').split('\n').filter(Boolean).slice(-1)[0] || `exit ${push.code}`;
|
|
5592
5649
|
if (issues.length) {
|
|
5593
5650
|
git.git(['worktree', 'remove', '--force', wtPath], repoAbs);
|
|
5594
5651
|
git.git(['branch', '-D', branch], repoAbs);
|
|
5595
|
-
throw new UserError(`git push ${pushRemote} ${
|
|
5596
|
-
'were removed again. The pushed
|
|
5597
|
-
|
|
5652
|
+
throw new UserError(`git push ${pushRemote} ${claimRef} failed (${why}) — claim NOT taken: the worktree and branch ` +
|
|
5653
|
+
'were removed again. The pushed claim ref is the record other machines read (#325, #550); fix the push ' +
|
|
5654
|
+
`(access, network, or a claim ref of that name another machine just created — \`git ls-remote ${pushRemote} ${claimRef}\`) and re-run.`);
|
|
5598
5655
|
}
|
|
5599
|
-
warn(`git push ${pushRemote} ${
|
|
5656
|
+
warn(`git push ${pushRemote} ${claimRef} failed (${why}) — worktree created, no claim ref on the remote`);
|
|
5600
5657
|
}
|
|
5601
5658
|
}
|
|
5602
5659
|
|
|
@@ -5618,14 +5675,14 @@ function cmdWorktreeNew(argv) {
|
|
|
5618
5675
|
}
|
|
5619
5676
|
|
|
5620
5677
|
// 3. allocate ports + record worktree + claims (atomic)
|
|
5621
|
-
// #325: if recording fails after the push above, take the pushed
|
|
5678
|
+
// #325: if recording fails after the push above, take the pushed claim ref back off the remote —
|
|
5622
5679
|
// otherwise it would stand there as a claim record nothing on any machine owns, refusing every
|
|
5623
5680
|
// later claim on these issues. (The local worktree is left as before this change.)
|
|
5624
5681
|
let alloc;
|
|
5625
5682
|
try {
|
|
5626
5683
|
alloc = allocWorktreeRecord();
|
|
5627
5684
|
} catch (e) {
|
|
5628
|
-
if (pushed) git.
|
|
5685
|
+
if (pushed) git.deleteClaimRef(repoAbs, pushRemote, branch);
|
|
5629
5686
|
throw e;
|
|
5630
5687
|
}
|
|
5631
5688
|
function allocWorktreeRecord() { return state.mutate((st) => {
|
|
@@ -5854,6 +5911,19 @@ function cmdWorktreeRm(argv) {
|
|
|
5854
5911
|
|
|
5855
5912
|
print(`✓ Removed worktree "${name}"`);
|
|
5856
5913
|
if (removal.action === 'rm-rf') print(' (directory was a husk from an earlier interrupted removal — cleaned up directly)');
|
|
5914
|
+
// #550: the claim ref `worktree new` pushed is this worktree's claim record on the remote — release
|
|
5915
|
+
// it with the claims, or it would stand there refusing every later claim on these issue numbers from
|
|
5916
|
+
// another machine. Best effort: an absent ref is fine (never pushed, a pre-#550 worktree, or already
|
|
5917
|
+
// gone), a failed delete only warns with the command, and nothing above is undone for it.
|
|
5918
|
+
if (wt.branch) {
|
|
5919
|
+
let claimRemoteName = null;
|
|
5920
|
+
try { claimRemoteName = git.claimRemote(repoAbs); } catch { claimRemoteName = null; }
|
|
5921
|
+
if (claimRemoteName) {
|
|
5922
|
+
const d = git.deleteClaimRef(repoAbs, claimRemoteName, wt.branch);
|
|
5923
|
+
if (d.ok && !d.absent) print(` deleted claim ref ${claimRemoteName} ${git.claimRef(wt.branch)}`);
|
|
5924
|
+
else if (!d.ok) warnDeferred(`could not delete claim ref ${claimRemoteName} ${git.claimRef(wt.branch)} (${String(d.stderr || '').split('\n')[0]}) — delete it by hand: git push ${claimRemoteName} --delete ${git.claimRef(wt.branch)}`);
|
|
5925
|
+
}
|
|
5926
|
+
}
|
|
5857
5927
|
// #114: this line used to report `removed.claims` — the LOCAL registry mutation, which cannot
|
|
5858
5928
|
// fail for a network reason and so always read as full success. Report what the tracker actually
|
|
5859
5929
|
// did instead, and name what it didn't.
|
|
@@ -5886,7 +5956,7 @@ function cmdWorktreeRm(argv) {
|
|
|
5886
5956
|
}
|
|
5887
5957
|
|
|
5888
5958
|
/**
|
|
5889
|
-
* `colab worktree tag <name> --session <
|
|
5959
|
+
* `colab worktree tag <name> --session <id> [--session-name <s>] [--branch <b>]` — repair
|
|
5890
5960
|
* session identity, and/or the recorded branch, on an ALREADY-created worktree. Before this, the
|
|
5891
5961
|
* only fix was hand-editing ~/.colab/state.json.
|
|
5892
5962
|
*
|
|
@@ -5920,7 +5990,7 @@ function cmdWorktreeTag(argv) {
|
|
|
5920
5990
|
const sessionName = String(opts.sessionName || '').trim();
|
|
5921
5991
|
const branch = String(opts.branch || '').trim();
|
|
5922
5992
|
if (!session && !sessionName && !branch) {
|
|
5923
|
-
throw new UserError('Nothing to tag — pass --session <
|
|
5993
|
+
throw new UserError('Nothing to tag — pass --session <id>, --session-name <s>, and/or --branch <b>');
|
|
5924
5994
|
}
|
|
5925
5995
|
if (!state.loadState().worktrees[name]) {
|
|
5926
5996
|
throw new UserError(`No worktree "${name}" in state (list them with: colab worktrees)`);
|
|
@@ -7598,7 +7668,7 @@ function cmdLabels(argv) {
|
|
|
7598
7668
|
// config (show / manage the aggregation inputs)
|
|
7599
7669
|
// ---------------------------------------------------------------------------
|
|
7600
7670
|
|
|
7601
|
-
const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reserved-file <path>|rm-reserved-file <path>|set <key> <value>]
|
|
7671
|
+
const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reserved-file <path>|rm-reserved-file <path>|add-notify-url <url>|rm-notify-url <url>|set <key> <value>]
|
|
7602
7672
|
|
|
7603
7673
|
show print resolved config, file paths, and the aggregated reserved set
|
|
7604
7674
|
add-repo <path> add a repo root to scan for .github/project.yml reserved ports
|
|
@@ -7606,14 +7676,24 @@ const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reser
|
|
|
7606
7676
|
add-reserved-file <path> add a machine-local reserved-ports file (~ is expanded); its ports join
|
|
7607
7677
|
the reserved set (lenient parse: whitespace ints per line, # comments)
|
|
7608
7678
|
rm-reserved-file <path> remove a reserved-ports file
|
|
7679
|
+
add-notify-url <url> add one more event receiver to notifyUrl (a second local observer) —
|
|
7680
|
+
existing entries are kept; one URL stays stored as a plain string
|
|
7681
|
+
rm-notify-url <url> remove one receiver from notifyUrl; removing the last unsets the key
|
|
7609
7682
|
set <key> <value> set claimTTLHours | plannerClaimTTLMinutes | portRange | worktreeSubdir | notifyUrl | journal |
|
|
7610
7683
|
claimIdentity
|
|
7684
|
+
set <tuning-key> <value> --evidence "<why>"
|
|
7685
|
+
a kebab-case key is this REPO's .github/project.yml, not this machine (#561):
|
|
7686
|
+
one tuning value, committed on a short branch, shippable with no issue —
|
|
7687
|
+
see: colab config set ship-batch --help
|
|
7611
7688
|
|
|
7612
7689
|
notifyUrl is OPTIONAL and off by default: unset, colab makes no network call of its own. Set it to
|
|
7613
7690
|
an http(s) endpoint and claim / release / ship / worktree new / worktree rm each push one small
|
|
7614
7691
|
best-effort JSON event as they succeed — fire-and-forget, never retried, never able to fail or slow
|
|
7615
7692
|
the command that triggered it. Observers already poll this state file; the push only sharpens the
|
|
7616
7693
|
timestamp. Unset it again with: colab config set notifyUrl ""
|
|
7694
|
+
notifyUrl may hold SEVERAL receivers (#546) — every event goes to each, through its own detached
|
|
7695
|
+
child, so one dead receiver never costs another its event. \`set notifyUrl <url>\` replaces the
|
|
7696
|
+
whole value with one URL; add-notify-url / rm-notify-url change one entry and leave the rest alone.
|
|
7617
7697
|
|
|
7618
7698
|
journal is OPTIONAL and off by default: unset, colab writes no journal file at all. Set it and every
|
|
7619
7699
|
state transition and every invocation is appended to ~/.colab/journal.jsonl — one JSON object per
|
|
@@ -7632,6 +7712,91 @@ changes on resume makes that session's own earlier claim comment read as a diffe
|
|
|
7632
7712
|
it will yield to itself. Unset it again with: colab config set claimIdentity ""
|
|
7633
7713
|
`;
|
|
7634
7714
|
|
|
7715
|
+
// config set <tuning-key> (#561) — one TUNING value of this repo's .github/project.yml, committed on
|
|
7716
|
+
// a short branch without touching any checkout, shippable by `colab ship` with no issue.
|
|
7717
|
+
const HELP_CONFIG_SET_DESCRIPTOR = `colab config set <tuning-key> <value> --evidence "<why>" [--repo <path>] [--no-push] [--dry]
|
|
7718
|
+
|
|
7719
|
+
Change ONE tuning value of this repo's .github/project.yml (#561). Tuning keys:
|
|
7720
|
+
${configSet.TUNING_KEYS.filter((k) => k !== 'thresholds').join(', ')}, thresholds.<name>
|
|
7721
|
+
|
|
7722
|
+
The value is validated by the parser every reader of that key uses (the same verdict \`colab ship\`
|
|
7723
|
+
computes), then committed on top of a freshly fetched <remote>/<trunk> as branch
|
|
7724
|
+
chore/tune-<key> — with no checkout touched and no issue. The subject is
|
|
7725
|
+
\`chore(project): <key> <old> → <new>\`; --evidence (required) goes in the body, which the squash
|
|
7726
|
+
carries, so the reason for the number lives in trunk's history.
|
|
7727
|
+
|
|
7728
|
+
Then: wait for the branch's CI (\`colab ci-wait --sha <sha> --branch <branch>\`) and
|
|
7729
|
+
\`colab ship --branch <branch>\`. Ship computes the TUNING-ONLY class from the diff — it is never
|
|
7730
|
+
asserted — and, like docs-only (#345), it opens the autonomy gate on a repo without auto-trunk.
|
|
7731
|
+
Every other precondition still applies.
|
|
7732
|
+
|
|
7733
|
+
Never on this path (they grant authority or change what deploys): ${configSet.AUTHORITY_KEYS.join(', ')}.
|
|
7734
|
+
|
|
7735
|
+
--evidence <text> the measurement behind the number (required)
|
|
7736
|
+
--no-push create the branch locally only
|
|
7737
|
+
--dry print the edit and the verdict; create nothing`;
|
|
7738
|
+
|
|
7739
|
+
function cmdConfigSetDescriptor(argv) {
|
|
7740
|
+
const opts = parseArgs(argv, {
|
|
7741
|
+
values: { '--repo': 'repo', '--evidence': 'evidence' },
|
|
7742
|
+
flags: { '--no-push': 'noPush', '--dry': 'dry', '-h': 'help', '--help': 'help' },
|
|
7743
|
+
});
|
|
7744
|
+
if (opts.help) return print(HELP_CONFIG_SET_DESCRIPTOR);
|
|
7745
|
+
const [key, value] = opts._ || [];
|
|
7746
|
+
if (!key || value === undefined) throw new UserError('config set needs <tuning-key> <value> — see: colab config set ship-batch --help');
|
|
7747
|
+
const kp = configSet.parseKeyPath(key);
|
|
7748
|
+
if (kp.problem) throw new UserError(kp.problem);
|
|
7749
|
+
if (!opts.dry && !String(opts.evidence || '').trim()) {
|
|
7750
|
+
throw new UserError('--evidence "<why>" is required — the measurement behind the number goes in the commit body (#561); re-run with --evidence "<what you measured>"');
|
|
7751
|
+
}
|
|
7752
|
+
const repoAbs = resolveRepo(opts);
|
|
7753
|
+
const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
|
|
7754
|
+
if (!trunk) throw new UserError('could not determine trunk — add `trunk:` to .github/project.yml (or run `colab adopt`), then re-run');
|
|
7755
|
+
const remote = git.remoteFor(repoAbs);
|
|
7756
|
+
const f = git.git(['fetch', remote, trunk], repoAbs);
|
|
7757
|
+
if (!f.ok) throw new UserError(`could not fetch ${remote}/${trunk} — nothing created (${f.stderr.split('\n')[0]}); re-run once \`git fetch ${remote} ${trunk}\` succeeds`);
|
|
7758
|
+
const baseRef = `${remote}/${trunk}`;
|
|
7759
|
+
const baseSha = (git.git(['rev-parse', `refs/remotes/${baseRef}`], repoAbs).stdout || '').trim();
|
|
7760
|
+
if (!baseSha) throw new UserError(`${baseRef} does not resolve after the fetch — check \`git ls-remote ${remote} ${trunk}\` and re-run`);
|
|
7761
|
+
const text = configSet.descriptorAt(repoAbs, baseSha);
|
|
7762
|
+
if (text === null) throw new UserError(`could not read ${configSet.DESCRIPTOR} at ${baseRef} — see why with \`git show ${baseRef}:${configSet.DESCRIPTOR}\``);
|
|
7763
|
+
if (text === '') throw new UserError(`${baseRef} has no ${configSet.DESCRIPTOR} — adopt the handbook first: \`colab adopt\``);
|
|
7764
|
+
const edit = configSet.editText(text, kp, value);
|
|
7765
|
+
if (edit.problem) throw new UserError(edit.problem);
|
|
7766
|
+
const name = [kp.top, kp.sub].filter(Boolean).join('.');
|
|
7767
|
+
if (edit.text === text) { print(`${name} is already ${value} on ${baseRef} — nothing to change`); return 0; }
|
|
7768
|
+
// The SAME verdict ship will compute on this diff — so a value ship would refuse is refused here.
|
|
7769
|
+
const verdict = configSet.classify({
|
|
7770
|
+
entries: [{ path: configSet.DESCRIPTOR, oldMode: '100644', newMode: '100644', binary: false }],
|
|
7771
|
+
baseText: text, headText: edit.text,
|
|
7772
|
+
});
|
|
7773
|
+
if (!verdict.tuning) throw new UserError(`refused: ${verdict.reason} — pick a valid value (\`colab config set ${name} --help\`)`);
|
|
7774
|
+
const branch = configSet.branchName(kp);
|
|
7775
|
+
if (git.branchExists(repoAbs, branch, remote)) {
|
|
7776
|
+
throw new UserError(`branch ${branch} already exists — ship it with \`colab ship --branch ${branch}\`, or delete it with \`git push ${remote} --delete ${branch}\` and \`git branch -D ${branch}\``);
|
|
7777
|
+
}
|
|
7778
|
+
const message = configSet.commitMessage(kp, edit.old, value, opts.evidence || '(dry run)');
|
|
7779
|
+
print(`config set ${shortRepo(repoAbs)} · ${name}: ${edit.old === null ? '(unset)' : edit.old} → ${value}`);
|
|
7780
|
+
print(` verdict: ${verdict.reason}`);
|
|
7781
|
+
print(` branch: ${branch} (base ${baseRef} @ ${shortSha(baseSha)})`);
|
|
7782
|
+
if (opts.dry) { print(' [DRY RUN] nothing created.'); return 0; }
|
|
7783
|
+
const c = configSet.commitOnBranch(repoAbs, { baseSha, text: edit.text, message, branch });
|
|
7784
|
+
if (!c.ok) throw new UserError(`could not create the commit: ${c.error} — nothing was created; a human must read the git error above before re-running`);
|
|
7785
|
+
print(` commit: ${shortSha(c.sha)} ${message.split('\n')[0]}`);
|
|
7786
|
+
if (opts.noPush) {
|
|
7787
|
+
print(` not pushed (--no-push). Push it, wait for CI, then: colab ship --branch ${branch}`);
|
|
7788
|
+
return 0;
|
|
7789
|
+
}
|
|
7790
|
+
const p = git.git(['push', remote, `refs/heads/${branch}:refs/heads/${branch}`], repoAbs);
|
|
7791
|
+
if (!p.ok) {
|
|
7792
|
+
warn(`push failed — the branch exists locally only: ${p.stderr.split('\n')[0]}`);
|
|
7793
|
+
return 1;
|
|
7794
|
+
}
|
|
7795
|
+
print(` pushed: ${remote}/${branch}`);
|
|
7796
|
+
print(`Next: colab ci-wait --sha ${c.sha} --branch ${branch} && colab ship --branch ${branch}`);
|
|
7797
|
+
return 0;
|
|
7798
|
+
}
|
|
7799
|
+
|
|
7635
7800
|
function cmdConfig(argv) {
|
|
7636
7801
|
const sub = argv[0];
|
|
7637
7802
|
const cfg = state.loadConfig();
|
|
@@ -7670,6 +7835,26 @@ function cmdConfig(argv) {
|
|
|
7670
7835
|
cfg.reservedFiles = (cfg.reservedFiles || []).filter((f) => f !== argv[1]);
|
|
7671
7836
|
state.saveConfig(cfg); print(`reservedFiles: ${cfg.reservedFiles.join(', ') || '(none)'}`); return 0;
|
|
7672
7837
|
}
|
|
7838
|
+
if (sub === 'add-notify-url' || sub === 'rm-notify-url') {
|
|
7839
|
+
// #546: notifyUrl is a string or a list. These change ONE entry and leave every other exactly as
|
|
7840
|
+
// it was, so a second observer is added without hand-editing JSON and without rewriting the first.
|
|
7841
|
+
const u = (argv[1] || '').trim();
|
|
7842
|
+
if (!u) throw new UserError(`${sub} needs a URL — try: colab config ${sub} http://127.0.0.1:<port>/api/events`);
|
|
7843
|
+
const urls = notify.configuredUrls(cfg);
|
|
7844
|
+
if (sub === 'add-notify-url') {
|
|
7845
|
+
if (!/^https?:\/\//i.test(u)) throw new UserError(`notifyUrl must be an http(s) URL — try: colab config add-notify-url http://${u.replace(/^[a-z]+:\/\//i, '')}`);
|
|
7846
|
+
if (!urls.includes(u)) urls.push(u);
|
|
7847
|
+
} else {
|
|
7848
|
+
if (!urls.includes(u)) throw new UserError(`notifyUrl has no entry ${u} — see the entries with: colab config show`);
|
|
7849
|
+
urls.splice(urls.indexOf(u), 1);
|
|
7850
|
+
}
|
|
7851
|
+
const v = notify.storedNotifyUrl(urls);
|
|
7852
|
+
if (v === undefined) delete cfg.notifyUrl; else cfg.notifyUrl = v;
|
|
7853
|
+
state.saveConfig(cfg);
|
|
7854
|
+
print(`notifyUrl = ${urls.length ? urls.join(', ') : '(unset)'}`);
|
|
7855
|
+
return 0;
|
|
7856
|
+
}
|
|
7857
|
+
if (sub === 'set' && argv[1] && configSet.isDescriptorKey(argv[1])) return cmdConfigSetDescriptor(argv.slice(1)); // #561
|
|
7673
7858
|
if (sub === 'set') {
|
|
7674
7859
|
const [k, v] = [argv[1], argv[2]];
|
|
7675
7860
|
if (!k || v === undefined) throw new UserError('set needs <key> <value>');
|
|
@@ -9776,8 +9961,14 @@ function trustAt(repoAbs, ref) {
|
|
|
9776
9961
|
* gated by it, and a branch that deletes trunk's declaration is still gated by trunk's.
|
|
9777
9962
|
*/
|
|
9778
9963
|
function newMigrations(mainRoot, trunk, branch) {
|
|
9964
|
+
return newMigrationsOrNull(mainRoot, trunk, branch) || [];
|
|
9965
|
+
}
|
|
9966
|
+
|
|
9967
|
+
/** newMigrations, but null — not [] — when git cannot compute the diff (#563): the grant write path
|
|
9968
|
+
* must tell "no migrations" from "could not look", and refuses on the second. */
|
|
9969
|
+
function newMigrationsOrNull(mainRoot, trunk, branch) {
|
|
9779
9970
|
const r = git.git(['diff', '--name-only', `${trunk}...${branch}`], mainRoot);
|
|
9780
|
-
if (!r.ok) return
|
|
9971
|
+
if (!r.ok) return null;
|
|
9781
9972
|
const declared = migrationPaths.unionPaths(projectDoc(mainRoot), projectDocAt(mainRoot, trunk), projectDocAt(mainRoot, branch));
|
|
9782
9973
|
return r.stdout.split('\n').filter(Boolean).filter((f) => migrationPaths.isMigrationPath(f, declared));
|
|
9783
9974
|
}
|
|
@@ -10051,6 +10242,7 @@ promotes is an integration event of the same weight as a promotion, and stays hu
|
|
|
10051
10242
|
|
|
10052
10243
|
Sequence (each step gated; any failure aborts before the push — the target is never half-shipped):
|
|
10053
10244
|
a. autonomy gate repo must grant auto-trunk (no --force override) — or the diff is docs-only (#345)
|
|
10245
|
+
or tuning-only (#561)
|
|
10054
10246
|
— or a person runs ship through the human door (#525): a confirmed interactive
|
|
10055
10247
|
terminal, or COLAB_HUMAN=1 + --answered-by <name>. An agent shell is no terminal.
|
|
10056
10248
|
b. preconditions target CI alive+green (UNLESS the branch proves the CURE RULE, #281 — no
|
|
@@ -10227,6 +10419,14 @@ auto-trunk). The row reads "docs-only (N files) — autonomy exception", and --d
|
|
|
10227
10419
|
\`autonomyGate: { via, docsOnly }\`. After B0 sync the diff is measured again before the squash.
|
|
10228
10420
|
Every other precondition is unchanged. No flag, env var or project.yml field widens the list.
|
|
10229
10421
|
|
|
10422
|
+
TUNING-ONLY — the second computed exception (#561). Ship also proceeds without the grant when the
|
|
10423
|
+
diff changes .github/project.yml ALONE, every changed line inside a tuning key (ship-batch,
|
|
10424
|
+
ship-batch-wait, ci-wait-factor, thresholds) and every moved value valid; never with an authority
|
|
10425
|
+
key (autonomy, promotion, migration-grant, ci-grant, trust-humans, exposure, tier, trunk, deploy,
|
|
10426
|
+
release, production). It needs no issue. \`colab config set <key> <value> --evidence "<why>"\`
|
|
10427
|
+
writes such a branch. The row reads "tuning-only (<keys>) — autonomy exception (#561)"; --dry --json
|
|
10428
|
+
adds \`autonomyGate.tuning\`. Re-measured after B0 sync like docs-only.
|
|
10429
|
+
|
|
10230
10430
|
TRUNK-DIRECT — \`colab ship --direct\` (#302). A unit committed straight to trunk has no branch and
|
|
10231
10431
|
no worktree, so neither door above can find it, and evidence-close's own detection cannot fire
|
|
10232
10432
|
(\`landed\` is \`unknown\` when base === branch). --direct is its close path: the claims are this
|
|
@@ -10283,6 +10483,12 @@ at build, added since) is NOT landed with it — the command names both lists an
|
|
|
10283
10483
|
--dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
|
|
10284
10484
|
locally and printed; a staged green batch prints what would land (members, combined run, target sha).
|
|
10285
10485
|
Consumer CI must opt in: add 'ship-batch/**' to a CI workflow's push: branches:.
|
|
10486
|
+
PARTNER WAIT (#555) — opt-in per repo: \`ship-batch-wait: <duration>\` in project.yml (90s, 6m, 1h; the
|
|
10487
|
+
unit is required). Absent, zero or malformed: no wait, exactly as above. With it, a call where exactly
|
|
10488
|
+
ONE member can join pauses (exit 3, "⏸ PARTNER-WAIT", the seconds left) until that window has passed
|
|
10489
|
+
since the member became ready (its head CI's last update, else its head commit's date) — then the same
|
|
10490
|
+
call declines it to serial (exit 4). The caller waits, gathers every ready candidate again and calls
|
|
10491
|
+
--batch with all of them. A single named branch is accepted only when the field is set.
|
|
10286
10492
|
|
|
10287
10493
|
B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
|
|
10288
10494
|
does unasked, however certain it is that the content landed: reporting is safe and reversible,
|
|
@@ -10754,6 +10960,37 @@ function noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch) {
|
|
|
10754
10960
|
detail: `none — ${at} has no repo-owned workflow (#482), so the branch's own run decides, and ${ownAt} ${why}${excludedRunsNote(r.run)}` };
|
|
10755
10961
|
}
|
|
10756
10962
|
|
|
10963
|
+
/**
|
|
10964
|
+
* The verifying-runs policy every CI read uses (#503), plus the lost-push rescue's resolver (#567):
|
|
10965
|
+
* the names of the workflows whose definition AT THAT SHA is triggered by a branch push or a pull
|
|
10966
|
+
* request. Lazy — called only when a `workflow_dispatch` run has no push sibling — and fail-closed:
|
|
10967
|
+
* a sha that is not local, or a tree that cannot be read, yields null and the run stays set aside.
|
|
10968
|
+
*/
|
|
10969
|
+
function verifyingPolicy(repoAbs) {
|
|
10970
|
+
return { ...verifyRuns.parsePolicy(projectDoc(repoAbs)), dispatchVerifies: (sha) => pushVerifiedWorkflowsAt(repoAbs, sha) };
|
|
10971
|
+
}
|
|
10972
|
+
|
|
10973
|
+
function pushVerifiedWorkflowsAt(repoAbs, sha) {
|
|
10974
|
+
if (!sha) return null;
|
|
10975
|
+
if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) {
|
|
10976
|
+
// Not local yet (another machine landed it): one fetch of that commit, then fail closed.
|
|
10977
|
+
git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
|
|
10978
|
+
if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
|
|
10979
|
+
}
|
|
10980
|
+
const ls = git.git(['ls-tree', '--name-only', `${sha}:.github/workflows`], repoAbs);
|
|
10981
|
+
if (!ls.ok) return null;
|
|
10982
|
+
const names = [];
|
|
10983
|
+
for (const f of ls.stdout.split('\n').map((x) => x.trim()).filter((x) => /\.ya?ml$/.test(x))) {
|
|
10984
|
+
const rel = `.github/workflows/${f}`;
|
|
10985
|
+
const show = git.git(['show', `${sha}:${rel}`], repoAbs);
|
|
10986
|
+
if (!show.ok) continue;
|
|
10987
|
+
const t = verifyRuns.workflowTriggers(show.stdout);
|
|
10988
|
+
// GitHub names a workflow with no `name:` by its file path.
|
|
10989
|
+
if (t && t.verifiesBranches) names.push(t.name || rel);
|
|
10990
|
+
}
|
|
10991
|
+
return names;
|
|
10992
|
+
}
|
|
10993
|
+
|
|
10757
10994
|
/** Number of workflow files in `.github/workflows` at `sha`, or null when the tree cannot be read. */
|
|
10758
10995
|
function trunkWorkflowFiles(repoAbs, sha) {
|
|
10759
10996
|
if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
|
|
@@ -10784,7 +11021,7 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
|
|
|
10784
11021
|
if (!gh) return { run: null, final: true, verdict: { ok: false, class: SELF_CLEARING, detail: `gh not usable (${ghUnusableWhy(repoAbs)}) — cannot confirm CI` } };
|
|
10785
11022
|
// #503: only runs that VERIFY the code count — a post-CI release/deploy run at the same sha is set
|
|
10786
11023
|
// aside and named, never a red and never a reason to wait (tools/lib/verify-runs.js).
|
|
10787
|
-
const readOpts = { verifying:
|
|
11024
|
+
const readOpts = { verifying: verifyingPolicy(repoAbs) };
|
|
10788
11025
|
let run = git.ghRunForSha(repoAbs, target, undefined, undefined, readOpts);
|
|
10789
11026
|
let via = target;
|
|
10790
11027
|
if (run && run.status === 'none' && target !== trunk) {
|
|
@@ -10810,10 +11047,11 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
|
|
|
10810
11047
|
// (a ship reading trunk right after another ship landed it). That clears on its own: SELF_CLEARING,
|
|
10811
11048
|
// never HUMAN_GATED, until the grace window has passed. Age unknown keeps the old class.
|
|
10812
11049
|
if (run.status === 'none' && target === trunk) {
|
|
10813
|
-
|
|
11050
|
+
// #559: the grace is the repo's measured push→run lag when there is one — read from cache, never fetched here.
|
|
11051
|
+
const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha), { graceSec: ciProfileFor(repoAbs).th.emptyReadGraceSec });
|
|
10814
11052
|
if (fresh.fresh) {
|
|
10815
11053
|
verdict = { ok: false, class: SELF_CLEARING,
|
|
10816
|
-
detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${
|
|
11054
|
+
detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${Math.round(fresh.graceMinutes * 10) / 10}m grace; retry later${excludedRunsNote(run)}${verifyRuns.setAsideNote(run.setAside)}` };
|
|
10817
11055
|
}
|
|
10818
11056
|
}
|
|
10819
11057
|
// #373: trunk's own run not there yet or still in flight (never a finished red) — a batch that landed
|
|
@@ -10884,7 +11122,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
|
|
|
10884
11122
|
*/
|
|
10885
11123
|
function classifyCiRun(repoAbs, run, at) {
|
|
10886
11124
|
const v = classifyCiRunRaw(repoAbs, run, at);
|
|
10887
|
-
return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) };
|
|
11125
|
+
return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) + verifyRuns.dispatchCountedNote(run && run.dispatchCounted) };
|
|
10888
11126
|
}
|
|
10889
11127
|
|
|
10890
11128
|
/**
|
|
@@ -10926,7 +11164,9 @@ function classifyCiRunRaw(repoAbs, run, at) {
|
|
|
10926
11164
|
// Non-completed, non-none: running/queued/etc. Ordinarily SELF_CLEARING — but #155's wedged
|
|
10927
11165
|
// shape (queued, zero jobs, unmoving for hours) can never clear on its own, so check for it.
|
|
10928
11166
|
const jobCount = run.databaseId != null ? git.ghRunJobCount(repoAbs, run.databaseId) : null;
|
|
10929
|
-
|
|
11167
|
+
// #559: wedge age and zero-jobs floor follow the repo's measured CI (cached profile; bootstrap = 6h / 2m).
|
|
11168
|
+
const th = ciProfileFor(repoAbs).th;
|
|
11169
|
+
const wedge = ciVerdict.wedgedVerdict({ status: run.status, createdAt: run.createdAt, jobCount }, { wedgeAgeSec: th.wedgeAgeSec, zeroJobsFloorSec: th.zeroJobsFloorSec });
|
|
10930
11170
|
if (wedge.wedged) {
|
|
10931
11171
|
return { ok: false, class: HUMAN_GATED, detail: `run for ${at}: status=${run.status} — WEDGED (${wedge.reason}); a human must look, not retry` };
|
|
10932
11172
|
}
|
|
@@ -11695,7 +11935,8 @@ function cmdShipDryJson(opts) {
|
|
|
11695
11935
|
|
|
11696
11936
|
// ---- (a) AUTONOMY GATE — does NOT short-circuit here; an unattended caller wants the whole table ----
|
|
11697
11937
|
const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
|
|
11698
|
-
humanDoor.humanDoorFromProcess(process, opts.answeredBy)
|
|
11938
|
+
humanDoor.humanDoorFromProcess(process, opts.answeredBy), // #525
|
|
11939
|
+
() => configSet.branchTuning(git, repoAbs, target, shipRefFor(repoAbs, sess.branch))); // #561
|
|
11699
11940
|
autonomyGatePayloadVal = autonomyGatePayload(autonomyGate);
|
|
11700
11941
|
checks.push({ name: 'autonomy granted', ok: autonomyGate.ok, class: autonomyGate.ok ? null : HUMAN_GATED, detail: autonomyGate.detail });
|
|
11701
11942
|
|
|
@@ -12576,23 +12817,33 @@ function shipOpenCorePr(repoAbs, cr, { target, branch, title, body }) {
|
|
|
12576
12817
|
* caller asserts nothing. `readDocsOnly` is a thunk, so an auto-trunk repo never pays for the
|
|
12577
12818
|
* diff read. Every other precondition is untouched — this relaxes the autonomy gate, not the checks.
|
|
12578
12819
|
*
|
|
12579
|
-
*
|
|
12820
|
+
* #561 adds the TUNING-ONLY class beside it: a diff `lib/config-set.js` classifies as one or more
|
|
12821
|
+
* tuning keys of .github/project.yml with valid values, and nothing else. `readTuning` is a thunk
|
|
12822
|
+
* too, consulted only when the change is not docs-only; a branchless (trunk-direct) door passes none.
|
|
12823
|
+
*
|
|
12824
|
+
* Returns `{ ok, via: 'auto-trunk'|'docs-only'|'tuning'|'human'|null, declared, docsOnly: verdict|null,
|
|
12825
|
+
* tuning: verdict|null, detail }`.
|
|
12580
12826
|
*/
|
|
12581
|
-
function shipAutonomyGate(doc, readDocsOnly, door = null) {
|
|
12827
|
+
function shipAutonomyGate(doc, readDocsOnly, door = null, readTuning = null) {
|
|
12582
12828
|
const declared = doc.autonomy ? String(doc.autonomy) : 'absent';
|
|
12583
|
-
if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, human: null, detail: 'auto-trunk' };
|
|
12829
|
+
if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, tuning: null, human: null, detail: 'auto-trunk' };
|
|
12584
12830
|
const verdict = readDocsOnly();
|
|
12585
12831
|
if (verdict.docsOnly) {
|
|
12586
|
-
return { ok: true, via: 'docs-only', declared, docsOnly: verdict, human: null, detail: `${verdict.reason} — autonomy exception` };
|
|
12832
|
+
return { ok: true, via: 'docs-only', declared, docsOnly: verdict, tuning: null, human: null, detail: `${verdict.reason} — autonomy exception` };
|
|
12833
|
+
}
|
|
12834
|
+
const tuning = readTuning ? readTuning() : null;
|
|
12835
|
+
if (tuning && tuning.tuning) {
|
|
12836
|
+
return { ok: true, via: 'tuning', declared, docsOnly: verdict, tuning, human: null, detail: `${tuning.reason} — autonomy exception (#561)` };
|
|
12587
12837
|
}
|
|
12588
12838
|
// #525: the human door — the person running ship IS the go (ruling on #525, option 1). Checked
|
|
12589
|
-
// after docs-only, so
|
|
12839
|
+
// after docs-only and tuning, so either keeps its own (agent-usable) door and record.
|
|
12590
12840
|
if (door && door.open) {
|
|
12591
|
-
return { ok: true, via: 'human', declared, docsOnly: verdict, human: door,
|
|
12841
|
+
return { ok: true, via: 'human', declared, docsOnly: verdict, tuning, human: door,
|
|
12592
12842
|
detail: `human door (#525): ${door.why} — project.yml autonomy: ${declared}` };
|
|
12593
12843
|
}
|
|
12594
|
-
return { ok: false, via: null, declared, docsOnly: verdict, human: door,
|
|
12595
|
-
detail: `project.yml autonomy: ${declared} — a human must trigger Phase B (not docs-only: ${verdict.reason};
|
|
12844
|
+
return { ok: false, via: null, declared, docsOnly: verdict, tuning, human: door,
|
|
12845
|
+
detail: `project.yml autonomy: ${declared} — a human must trigger Phase B (not docs-only: ${verdict.reason}; ` +
|
|
12846
|
+
`${tuning ? `not tuning-only: ${tuning.reason}; ` : ''}human door closed: ${door ? door.why : 'not offered'})` };
|
|
12596
12847
|
}
|
|
12597
12848
|
|
|
12598
12849
|
/** #525: the human-door refusal lines — what a person runs, never just "a human must". */
|
|
@@ -12651,8 +12902,10 @@ function shipHumanDoorGo(gate, opts, what) {
|
|
|
12651
12902
|
function autonomyGatePayload(gate) {
|
|
12652
12903
|
// #525: `human` is additive and present only when the human door was consulted, so an
|
|
12653
12904
|
// auto-trunk / docs-only payload stays byte-identical to before.
|
|
12654
|
-
|
|
12655
|
-
|
|
12905
|
+
// #561: `tuning` likewise — present only when the tuning class was consulted.
|
|
12906
|
+
const base = { via: gate.via, docsOnly: gate.docsOnly };
|
|
12907
|
+
if (gate.tuning) base.tuning = gate.tuning;
|
|
12908
|
+
return gate.human ? { ...base, human: { open: gate.human.open, how: gate.human.how, why: gate.human.why } } : base;
|
|
12656
12909
|
}
|
|
12657
12910
|
|
|
12658
12911
|
/** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
|
|
@@ -12739,11 +12992,13 @@ function cmdShip(argv) {
|
|
|
12739
12992
|
// ---- (a) AUTONOMY GATE — granted by the repo file, never by the caller ----
|
|
12740
12993
|
// #345: …or the branch's diff is documentation only, computed here from git — never asserted.
|
|
12741
12994
|
const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
|
|
12742
|
-
humanDoor.humanDoorFromProcess(process, opts.answeredBy)
|
|
12995
|
+
humanDoor.humanDoorFromProcess(process, opts.answeredBy), // #525
|
|
12996
|
+
() => configSet.branchTuning(git, repoAbs, target, shipRefFor(repoAbs, sess.branch))); // #561
|
|
12743
12997
|
if (!autonomyGate.ok) {
|
|
12744
12998
|
process.stderr.write(`✗ ${shortRepo(repoAbs)} does not grant auto-trunk (project.yml autonomy: ${autonomyGate.declared}).\n`);
|
|
12745
12999
|
process.stderr.write(' A human must trigger Phase B. (Autonomy is granted by the repo, not by a flag — --force cannot override.)\n');
|
|
12746
13000
|
process.stderr.write(` The docs-only exception (#345) does not apply either: ${autonomyGate.docsOnly.reason}.\n`);
|
|
13001
|
+
if (autonomyGate.tuning) process.stderr.write(` Nor the tuning-only class (#561): ${autonomyGate.tuning.reason}.\n`);
|
|
12747
13002
|
process.stderr.write(shipHumanDoorRefusal(autonomyGate, shipSelector(opts, sess)));
|
|
12748
13003
|
return 1;
|
|
12749
13004
|
}
|
|
@@ -13236,6 +13491,14 @@ function cmdShip(argv) {
|
|
|
13236
13491
|
return 1;
|
|
13237
13492
|
}
|
|
13238
13493
|
}
|
|
13494
|
+
if (autonomyGate.via === 'tuning') {
|
|
13495
|
+
const again = configSet.branchTuning(git, repoAbs, mergeRef, sess.branch);
|
|
13496
|
+
if (!again.tuning) {
|
|
13497
|
+
cleanupEphemeral();
|
|
13498
|
+
process.stderr.write(`✗ B1: the tuning-only class (#561) no longer holds after B0 sync — ${again.reason}. A human must trigger Phase B. Nothing pushed.\n`);
|
|
13499
|
+
return 1;
|
|
13500
|
+
}
|
|
13501
|
+
}
|
|
13239
13502
|
|
|
13240
13503
|
// #350: B0 may have brought in paths (a pre-ship hook's regenerated files). The approval covered
|
|
13241
13504
|
// the core paths the table listed; a core path it did not list was never reviewed.
|
|
@@ -13841,7 +14104,10 @@ function cmdShipBatch(opts) {
|
|
|
13841
14104
|
if (String(doc.autonomy || '') !== 'auto-trunk') {
|
|
13842
14105
|
return serial(`project.yml does not grant autonomy: auto-trunk — batch landing needs it (every member lands in one unattended push)`);
|
|
13843
14106
|
}
|
|
13844
|
-
|
|
14107
|
+
// #555: a declared ship-batch-wait lets ONE named member through — it may wait for a partner below.
|
|
14108
|
+
const waitCfg = shipBatch.parseShipBatchWait(doc);
|
|
14109
|
+
if (!waitCfg.valid) warn(`${waitCfg.reason} — ignored: a lone member does not wait (fails closed, #555)`);
|
|
14110
|
+
if (members.length < 2 && !(members.length === 1 && waitCfg.sec > 0)) return serial(`--batch names ${members.length} branch(es) — a batch needs at least two`);
|
|
13845
14111
|
if (members.length > cfg.n) warn(`--batch names ${members.length} branches; ship-batch: ${cfg.n} caps the batch — the rest wait for the next one`);
|
|
13846
14112
|
|
|
13847
14113
|
const remote = git.remoteFor(repoAbs);
|
|
@@ -13980,6 +14246,22 @@ function cmdShipBatch(opts) {
|
|
|
13980
14246
|
e.ok && !selected.includes(e) ? `eligible — waits for the next batch (cap ${cfg.n})` : e.why]), ['', 'MEMBER', 'DETAIL']));
|
|
13981
14247
|
const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
|
|
13982
14248
|
step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
|
|
14249
|
+
if (step.step === 'serial' && selected.length === 1 && waitCfg.sec > 0) {
|
|
14250
|
+
// #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
|
|
14251
|
+
// member is ready. Wait for a partner until the repo's window, counted from when it became ready.
|
|
14252
|
+
const lone = selected[0];
|
|
14253
|
+
const commitIso = git.git(['log', '-1', '--format=%cI', lone.sha], repoAbs);
|
|
14254
|
+
const since = shipBatch.readySince(git.ghRunsForCommit(repoAbs, lone.branch, lone.sha), commitIso.ok ? commitIso.stdout.trim() : null);
|
|
14255
|
+
const pw = shipBatch.partnerWait({ n: cfg.n, waitSec: waitCfg.sec, eligibleCount: 1, readySinceMs: since, nowMs: Date.now() });
|
|
14256
|
+
if (pw.wait) {
|
|
14257
|
+
print(`⏸ PARTNER-WAIT ${lone.branch} — the only ready member; ${waitCfg.reason}, ready since ${new Date(since).toISOString()}, ${ciWait.fmtDuration(pw.leftSec * 1000)} left. Nothing landed.`);
|
|
14258
|
+
print(` Wait up to ${pw.leftSec}s (a wait on another candidate's run counts toward it), gather EVERY ready candidate again,`);
|
|
14259
|
+
print(' then run colab ship --batch with all of them. Past the window, this same call lands it alone (serial).');
|
|
14260
|
+
return 3;
|
|
14261
|
+
}
|
|
14262
|
+
const why = { 'window-elapsed': `${waitCfg.reason} has elapsed since it became ready`, 'ready-time-unread': 'its ready time could not be read, so it does not wait' }[pw.reason] || pw.reason;
|
|
14263
|
+
return serial(`1 member can join and no partner arrived — ${why}`);
|
|
14264
|
+
}
|
|
13983
14265
|
if (step.step === 'serial') return serial(`${selected.length} member(s) can join — a batch needs at least two`);
|
|
13984
14266
|
|
|
13985
14267
|
// ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
|
|
@@ -14001,9 +14283,9 @@ function cmdShipBatch(opts) {
|
|
|
14001
14283
|
// regenerated by .colab/hooks/pre-ship, never hand-merged and never a reason to leave the batch.
|
|
14002
14284
|
// Only an overlap outside `generated:` (or no hook to regenerate with) drops the member.
|
|
14003
14285
|
const nonGen = unmerged.filter((f) => !isGeneratedPath(f, generated));
|
|
14004
|
-
let why = null;
|
|
14005
|
-
if (nonGen.length) why = `conflicts with the members already in (${nonGen.join(', ')}) — next batch`;
|
|
14006
|
-
else if (!hasPreShip) why = `conflicts with the members already in only in generated file(s) (${unmerged.join(', ')}), but there is no .colab/hooks/pre-ship to regenerate them — next batch`;
|
|
14286
|
+
let why = null, cls = null;
|
|
14287
|
+
if (nonGen.length) { why = `conflicts with the members already in (${nonGen.join(', ')}) — next batch`; cls = 'conflict'; }
|
|
14288
|
+
else if (!hasPreShip) { cls = 'generated-no-hook'; why = `conflicts with the members already in only in generated file(s) (${unmerged.join(', ')}), but there is no .colab/hooks/pre-ship to regenerate them — next batch`; }
|
|
14007
14289
|
else {
|
|
14008
14290
|
const hk = runHook(repoAbs, 'pre-ship', {
|
|
14009
14291
|
wtPath: dir, name: m.branch, branch: m.branch, ports: [], trunk, base: trunk,
|
|
@@ -14014,24 +14296,26 @@ function cmdShipBatch(opts) {
|
|
|
14014
14296
|
// state, so `left` reads empty — read the staged content itself before trusting it.
|
|
14015
14297
|
const markers = hk.ran && hk.ok && !left.length ? stagedConflictMarkers(dir, unmerged) : [];
|
|
14016
14298
|
if (!hk.ran || !hk.ok || left.length) {
|
|
14299
|
+
cls = 'hook-failed';
|
|
14017
14300
|
why = `.colab/hooks/pre-ship could not regenerate ${unmerged.join(', ')} on the combined head${left.length && hk.ok ? ` (still unmerged: ${left.join(', ')})` : ''} — next batch`;
|
|
14018
14301
|
} else if (markers.length) {
|
|
14302
|
+
cls = 'hook-markers';
|
|
14019
14303
|
why = `.colab/hooks/pre-ship exited 0 but left conflict markers staged in ${conflictMarkers.describe(markers)} on the combined head — treated as a failing hook, next batch`;
|
|
14020
14304
|
} else regenerated = unmerged;
|
|
14021
14305
|
}
|
|
14022
14306
|
if (why) {
|
|
14023
14307
|
git.git(['reset', '--hard', 'HEAD'], dir);
|
|
14024
|
-
dropped.push({ branch: m.branch, why });
|
|
14308
|
+
dropped.push({ branch: m.branch, sha: m.sha, cls, why });
|
|
14025
14309
|
continue;
|
|
14026
14310
|
}
|
|
14027
14311
|
} else if (!sq.ok) {
|
|
14028
14312
|
git.git(['reset', '--hard', 'HEAD'], dir);
|
|
14029
|
-
dropped.push({ branch: m.branch, why: `squash failed: ${git.gitFailureLine(sq.stderr)}` });
|
|
14313
|
+
dropped.push({ branch: m.branch, sha: m.sha, cls: 'squash-failed', why: `squash failed: ${git.gitFailureLine(sq.stderr)}` });
|
|
14030
14314
|
continue;
|
|
14031
14315
|
}
|
|
14032
14316
|
if (!git.git(['diff', '--cached', '--name-only'], dir).stdout.trim()) {
|
|
14033
14317
|
git.git(['reset', '--hard', 'HEAD'], dir);
|
|
14034
|
-
dropped.push({ branch: m.branch, why: 'stages nothing on top of the members already in' });
|
|
14318
|
+
dropped.push({ branch: m.branch, sha: m.sha, cls: 'empty', why: 'stages nothing on top of the members already in' });
|
|
14035
14319
|
continue;
|
|
14036
14320
|
}
|
|
14037
14321
|
const closeIssues = m.report.closeIssues || [];
|
|
@@ -14043,14 +14327,25 @@ function cmdShipBatch(opts) {
|
|
|
14043
14327
|
const inherited = msg && refsIssues.length ? squash.inheritedClosingKeywordConflicts(msg, refsIssues) : [];
|
|
14044
14328
|
if (!msg || !coverage.ok || inherited.length) {
|
|
14045
14329
|
git.git(['reset', '--hard', 'HEAD'], dir);
|
|
14046
|
-
dropped.push({ branch: m.branch, why: !msg ? 'no commit of its own to take a squash subject from' : 'its composed message does not close exactly what it claims — ship it alone to see why' });
|
|
14330
|
+
dropped.push({ branch: m.branch, sha: m.sha, cls: 'message', why: !msg ? 'no commit of its own to take a squash subject from' : 'its composed message does not close exactly what it claims — ship it alone to see why' });
|
|
14047
14331
|
continue;
|
|
14048
14332
|
}
|
|
14049
14333
|
const c = git.run('git', ['commit', '-q', '-m', msg], { cwd: dir });
|
|
14050
|
-
if (!c.ok) { git.git(['reset', '--hard', 'HEAD'], dir); dropped.push({ branch: m.branch, why: `commit failed: ${git.gitFailureLine(c.stderr)}` }); continue; }
|
|
14334
|
+
if (!c.ok) { git.git(['reset', '--hard', 'HEAD'], dir); dropped.push({ branch: m.branch, sha: m.sha, cls: 'commit-failed', why: `commit failed: ${git.gitFailureLine(c.stderr)}` }); continue; }
|
|
14051
14335
|
built.push({ ...m, regenerated, commit: git.git(['rev-parse', 'HEAD'], dir).stdout });
|
|
14052
14336
|
}
|
|
14053
14337
|
for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
|
|
14338
|
+
// #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
|
|
14339
|
+
// batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
|
|
14340
|
+
// Only when the batch is built (≥2 members): a build that collapses to serial pushes nothing.
|
|
14341
|
+
if (dropped.length && built.length >= 2) {
|
|
14342
|
+
const last = built[built.length - 1];
|
|
14343
|
+
const cur = git.git(['log', '-1', '--format=%B'], dir);
|
|
14344
|
+
const lines = dropped.map((d) => shipBatch.droppedTrailer({ ref, branch: d.branch, sha: d.sha, cls: d.cls }));
|
|
14345
|
+
const am = cur.ok ? git.run('git', ['commit', '-q', '--amend', '-m', shipBatch.appendTrailers(cur.stdout, lines)], { cwd: dir }) : cur;
|
|
14346
|
+
if (am.ok) last.commit = git.git(['rev-parse', 'HEAD'], dir).stdout;
|
|
14347
|
+
else warn(`could not record the dropped member(s) on the batch head: ${git.gitFailureLine(am.stderr)} — the drop is on this terminal only`);
|
|
14348
|
+
}
|
|
14054
14349
|
for (const b of built.filter((x) => x.regenerated)) {
|
|
14055
14350
|
print(` ↻ ${b.branch}: combined despite a generated-file overlap — ${b.regenerated.join(', ')} regenerated by .colab/hooks/pre-ship on the combined head (the combined run is the gate)`);
|
|
14056
14351
|
}
|
|
@@ -14330,7 +14625,8 @@ function cmdTrunkCi(argv) {
|
|
|
14330
14625
|
if (verdict === 'UNREADABLE' && gh && !git.ghState().ok) detail += ` (${ghUnusableWhy(repoAbs)})`;
|
|
14331
14626
|
out = { verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail,
|
|
14332
14627
|
...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}),
|
|
14333
|
-
...(r.run && Array.isArray(r.run.setAside) && r.run.setAside.length ? { setAside: r.run.setAside } : {})
|
|
14628
|
+
...(r.run && Array.isArray(r.run.setAside) && r.run.setAside.length ? { setAside: r.run.setAside } : {}),
|
|
14629
|
+
...(r.run && Array.isArray(r.run.dispatchCounted) && r.run.dispatchCounted.length ? { dispatchCounted: r.run.dispatchCounted } : {}) };
|
|
14334
14630
|
if (key && verdict !== 'UNREADABLE' && sha === headSha) cache.put(key, out);
|
|
14335
14631
|
}
|
|
14336
14632
|
if (opts.json) {
|
|
@@ -14384,6 +14680,110 @@ function trunkCiCache(repoAbs) {
|
|
|
14384
14680
|
};
|
|
14385
14681
|
}
|
|
14386
14682
|
|
|
14683
|
+
// ---- ci-profile (#559) ------------------------------------------------------------------------
|
|
14684
|
+
// Every CI wait bound derives from the repo's own measured CI duration (tools/lib/ci-profile.js).
|
|
14685
|
+
// The profile is cached per checkout in `<git common dir>/colab-ci-profile.json` for a day; the
|
|
14686
|
+
// thresholds are NOT cached — they are recomputed from the cached profile and the CURRENT
|
|
14687
|
+
// `ci-wait-factor`, so editing the factor applies at once with no refetch.
|
|
14688
|
+
const CI_PROFILE_TTL_DEFAULT_SEC = 24 * 3600;
|
|
14689
|
+
const CI_PROFILE_CACHE_V = 1;
|
|
14690
|
+
|
|
14691
|
+
function ciProfileTtlSec() {
|
|
14692
|
+
const env = process.env.COLAB_CI_PROFILE_TTL;
|
|
14693
|
+
return env !== undefined && env !== '' && Number.isFinite(Number(env)) ? Number(env) : CI_PROFILE_TTL_DEFAULT_SEC;
|
|
14694
|
+
}
|
|
14695
|
+
|
|
14696
|
+
function ciProfileCacheFile(repoAbs) {
|
|
14697
|
+
const dir = git.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoAbs);
|
|
14698
|
+
return dir.ok && dir.stdout ? path.join(dir.stdout.trim(), 'colab-ci-profile.json') : null;
|
|
14699
|
+
}
|
|
14700
|
+
|
|
14701
|
+
/**
|
|
14702
|
+
* The repo's completed CI runs in the profile window — up to 3 pages of the whole list plus one page
|
|
14703
|
+
* of trunk pushes, so a branch-heavy repo still yields trunk samples. Returns `{ rows, runsRead }`,
|
|
14704
|
+
* or `{ error }` when the list cannot be read (the caller falls back, never fails a wait on it).
|
|
14705
|
+
*/
|
|
14706
|
+
function fetchCiProfileRows(repoAbs, trunk, sinceIso) {
|
|
14707
|
+
const jq = '.workflow_runs[] | [.id, .head_branch, .head_sha, .event, .name, .status, .conclusion, .run_attempt, .created_at, .updated_at, .head_commit.timestamp] | @json';
|
|
14708
|
+
const day = sinceIso.slice(0, 10);
|
|
14709
|
+
const paths = [1, 2, 3].map((n) => `repos/{owner}/{repo}/actions/runs?per_page=100&status=completed&created=%3E%3D${day}&page=${n}`);
|
|
14710
|
+
paths.push(`repos/{owner}/{repo}/actions/runs?per_page=100&status=completed&created=%3E%3D${day}&branch=${encodeURIComponent(trunk)}&event=push`);
|
|
14711
|
+
const seen = new Map();
|
|
14712
|
+
for (let i = 0; i < paths.length; i++) {
|
|
14713
|
+
const r = git.ghApi(repoAbs, [paths[i], '--jq', jq]);
|
|
14714
|
+
if (!r.ok) return { error: git.gitFailureLine(r.stderr) || 'gh api failed' };
|
|
14715
|
+
let n = 0;
|
|
14716
|
+
for (const line of String(r.stdout || '').split('\n')) {
|
|
14717
|
+
if (!line.trim()) continue;
|
|
14718
|
+
let a; try { a = JSON.parse(line); } catch (_) { continue; }
|
|
14719
|
+
n++;
|
|
14720
|
+
seen.set(a[0], {
|
|
14721
|
+
id: a[0], branch: a[1], sha: a[2], event: a[3], workflowName: a[4], status: a[5], conclusion: a[6],
|
|
14722
|
+
attempt: a[7], createdMs: Date.parse(a[8]), updatedMs: Date.parse(a[9]), headCommitMs: a[10] ? Date.parse(a[10]) : null,
|
|
14723
|
+
});
|
|
14724
|
+
}
|
|
14725
|
+
if (i < 3 && n < 100) i = 2; // a short page ends the paged list; the trunk page still runs
|
|
14726
|
+
}
|
|
14727
|
+
return { rows: [...seen.values()], runsRead: seen.size };
|
|
14728
|
+
}
|
|
14729
|
+
|
|
14730
|
+
const ciProfileMemo = new Map();
|
|
14731
|
+
|
|
14732
|
+
/**
|
|
14733
|
+
* The one reader: `{ profile, th, factor, kindTrunk, cache: { state, ageSec, fetchedAt }, notes }`.
|
|
14734
|
+
* `fetch`: 'never' (ship's hot path — never blocks a verdict on a history read) · 'if-stale' ·
|
|
14735
|
+
* 'always'. A stale cache is still used when a refetch fails: old measured data beats bootstrap.
|
|
14736
|
+
* TTL 0 (`COLAB_CI_PROFILE_TTL=0`) means no cache and no fetch — the bootstrap everywhere.
|
|
14737
|
+
*/
|
|
14738
|
+
function ciProfileFor(repoAbs, { fetch = 'never' } = {}) {
|
|
14739
|
+
const memoKey = `${repoAbs}\u0000${fetch}`;
|
|
14740
|
+
if (ciProfileMemo.has(memoKey)) return ciProfileMemo.get(memoKey);
|
|
14741
|
+
const doc = projectDoc(repoAbs);
|
|
14742
|
+
const factor = ciProfile.parseFactor(doc);
|
|
14743
|
+
const trunk = resolveTrunk(repoAbs, doc);
|
|
14744
|
+
const notes = [];
|
|
14745
|
+
if (!factor.valid) notes.push(factor.reason);
|
|
14746
|
+
const ttl = ciProfileTtlSec();
|
|
14747
|
+
const file = ttl > 0 ? ciProfileCacheFile(repoAbs) : null;
|
|
14748
|
+
let entry = null;
|
|
14749
|
+
if (file) {
|
|
14750
|
+
try { entry = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { entry = null; }
|
|
14751
|
+
if (entry && (entry.v !== CI_PROFILE_CACHE_V || entry.trunk !== trunk || !entry.profile)) entry = null;
|
|
14752
|
+
}
|
|
14753
|
+
const ageSec = entry ? Math.max(0, Math.floor((Date.now() - entry.fetchedAt) / 1000)) : null;
|
|
14754
|
+
let state = entry ? (ageSec < ttl ? 'fresh' : 'stale') : 'none';
|
|
14755
|
+
const want = file && trunk && (fetch === 'always' || (fetch === 'if-stale' && state !== 'fresh'));
|
|
14756
|
+
if (want) {
|
|
14757
|
+
if (!isGhUsable(repoAbs)) notes.push(`gh not usable (${ghUnusableWhy(repoAbs)}) — CI history not read`);
|
|
14758
|
+
else {
|
|
14759
|
+
const nowMs = Date.now();
|
|
14760
|
+
const sinceMs = nowMs - ciProfile.WINDOW_DAYS * 86_400_000;
|
|
14761
|
+
const got = fetchCiProfileRows(repoAbs, trunk, new Date(sinceMs).toISOString());
|
|
14762
|
+
if (got.error) notes.push(`could not read CI history (${got.error}) — ${entry ? 'using the stale cached profile' : 'using the bootstrap bounds'}`);
|
|
14763
|
+
else {
|
|
14764
|
+
const policy = verifyRuns.parsePolicy(doc);
|
|
14765
|
+
const prof = ciProfile.profile(ciProfile.shaDurations(got.rows, { trunk, policy }), { sinceMs });
|
|
14766
|
+
entry = { v: CI_PROFILE_CACHE_V, trunk, fetchedAt: nowMs, since: new Date(sinceMs).toISOString(), runsRead: got.runsRead, profile: prof };
|
|
14767
|
+
state = 'fetched';
|
|
14768
|
+
try {
|
|
14769
|
+
const tmp = `${file}.${process.pid}.tmp`;
|
|
14770
|
+
fs.writeFileSync(tmp, JSON.stringify(entry));
|
|
14771
|
+
fs.renameSync(tmp, file);
|
|
14772
|
+
} catch (_) { /* no cache, not an error */ }
|
|
14773
|
+
}
|
|
14774
|
+
}
|
|
14775
|
+
}
|
|
14776
|
+
const profile = entry ? entry.profile : null;
|
|
14777
|
+
const out = {
|
|
14778
|
+
trunk, factor, profile, th: ciProfile.thresholds(profile, factor.value),
|
|
14779
|
+
cache: { state, ageSec: state === 'fetched' ? 0 : ageSec, fetchedAt: entry ? new Date(entry.fetchedAt).toISOString() : null,
|
|
14780
|
+
since: entry ? entry.since : null, runsRead: entry ? entry.runsRead : null },
|
|
14781
|
+
notes,
|
|
14782
|
+
};
|
|
14783
|
+
ciProfileMemo.set(memoKey, out);
|
|
14784
|
+
return out;
|
|
14785
|
+
}
|
|
14786
|
+
|
|
14387
14787
|
// ci-wait — THE way to wait for CI (#495). Agents' hand-rolled `sleep N; gh run …` loops spent ~88%
|
|
14388
14788
|
// of a shared identity's REST quota in one measured hour; this waits with backoff, conditional
|
|
14389
14789
|
// requests, a deadline, and a distinct exit code for every way a wait can end.
|
|
@@ -14399,9 +14799,13 @@ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand
|
|
|
14399
14799
|
with no run yet counts as pending until the deadline. An abbreviated sha is
|
|
14400
14800
|
resolved in the repo first, and refused (exit 2) when it does not resolve — #529
|
|
14401
14801
|
--branch <b> narrow --sha to runs on that branch
|
|
14402
|
-
--timeout <d> deadline:
|
|
14802
|
+
--timeout <d> deadline: 90s, 15m, 1h, or seconds. Default: this repo's CI wait bound, derived
|
|
14803
|
+
from its measured CI duration (\`colab ci-profile\`, #559) — the trunk bound
|
|
14804
|
+
when the target is trunk, the branch bound for any other branch, the larger
|
|
14805
|
+
for a bare run id; 15m while the repo has no CI history. Skills omit it.
|
|
14403
14806
|
|
|
14404
|
-
Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline
|
|
14807
|
+
Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline (a repo whose CI bound is past 15m
|
|
14808
|
+
gets the same schedule stretched in proportion — never a faster one). Every poll after the first is a
|
|
14405
14809
|
conditional request (If-None-Match); a 304 is not counted against the REST rate limit. After two
|
|
14406
14810
|
304s in a row, and on the last poll before the deadline, it re-reads unconditionally: a stale ETag
|
|
14407
14811
|
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.
|
|
@@ -14416,7 +14820,8 @@ Exit codes — branch on these, never on the text:
|
|
|
14416
14820
|
6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
|
|
14417
14821
|
|
|
14418
14822
|
It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
|
|
14419
|
-
--json { outcome, exit, target, polls, notModified, forced, waitedSec,
|
|
14823
|
+
--json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
|
|
14824
|
+
detail, status, conclusion, url }`;
|
|
14420
14825
|
|
|
14421
14826
|
function cmdCiWait(argv) {
|
|
14422
14827
|
const opts = parseArgs(argv, {
|
|
@@ -14429,8 +14834,10 @@ function cmdCiWait(argv) {
|
|
|
14429
14834
|
warn('ci-wait takes exactly one of <run-id> (numeric) or --sha <sha> [--branch <b>]');
|
|
14430
14835
|
return ciWait.EXIT.USAGE;
|
|
14431
14836
|
}
|
|
14432
|
-
|
|
14433
|
-
if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try
|
|
14837
|
+
let deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
|
|
14838
|
+
if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 15m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
|
|
14839
|
+
let deadlineBasis = opts.timeout !== undefined ? '--timeout' : 'bootstrap';
|
|
14840
|
+
let schedule = ciWait.DEFAULT_SCHEDULE_SEC;
|
|
14434
14841
|
const repoAbs = resolveRepo(opts);
|
|
14435
14842
|
if (opts.sha) {
|
|
14436
14843
|
// #529: the API reports a 40-hex head_sha and the rows are matched by equality, so an
|
|
@@ -14457,7 +14864,24 @@ function cmdCiWait(argv) {
|
|
|
14457
14864
|
return ciWait.EXIT.ALREADY_WAITING;
|
|
14458
14865
|
}
|
|
14459
14866
|
|
|
14460
|
-
|
|
14867
|
+
// #559: no --timeout → the repo's own bound, one source with every skill (they omit the flag). Read
|
|
14868
|
+
// after the lock, so a refused second waiter never spends a history fetch; a failed read is a note.
|
|
14869
|
+
if (opts.timeout === undefined) {
|
|
14870
|
+
const cp = ciProfileFor(repoAbs, { fetch: 'if-stale' });
|
|
14871
|
+
let onTrunk = null;
|
|
14872
|
+
if (!runId && !opts.branch && cp.trunk) {
|
|
14873
|
+
const remote = git.remoteFor(repoAbs);
|
|
14874
|
+
onTrunk = git.git(['merge-base', '--is-ancestor', opts.sha, `${remote}/${cp.trunk}`], repoAbs).ok;
|
|
14875
|
+
}
|
|
14876
|
+
const kind = ciProfile.kindFor({ branch: opts.branch || null, trunk: cp.trunk, onTrunk });
|
|
14877
|
+
deadlineSec = cp.th.ciWaitDefaultSec[kind];
|
|
14878
|
+
schedule = cp.th.scheduleSec[kind];
|
|
14879
|
+
const b = kind === 'any' ? (cp.th.basis.branchWait === 'measured' || cp.th.basis.trunkWait === 'measured' ? 'measured' : 'bootstrap') : cp.th.basis[`${kind}Wait`];
|
|
14880
|
+
deadlineBasis = `${kind === 'any' ? 'larger' : kind} bound, ${b}`;
|
|
14881
|
+
if (!opts.json) for (const n of cp.notes) process.stderr.write(`ci-wait: ${n}\n`);
|
|
14882
|
+
}
|
|
14883
|
+
|
|
14884
|
+
const verifyPolicy = verifyingPolicy(repoAbs);
|
|
14461
14885
|
const poll = (etag) => {
|
|
14462
14886
|
const r = git.ghApiConditional(repoAbs, apiPath, etag);
|
|
14463
14887
|
if (r.kind !== 'ok') return r;
|
|
@@ -14476,11 +14900,11 @@ function cmdCiWait(argv) {
|
|
|
14476
14900
|
return { ...r, summary, state: ciWait.runState(summary) };
|
|
14477
14901
|
};
|
|
14478
14902
|
|
|
14479
|
-
if (!opts.json) process.stderr.write(`ci-wait: waiting on ${target} (deadline ${ciWait.fmtDuration(deadlineSec * 1000)}; polls at +0s,
|
|
14903
|
+
if (!opts.json) process.stderr.write(`ci-wait: waiting on ${target} (deadline ${ciWait.fmtDuration(deadlineSec * 1000)}, ${deadlineBasis}; polls at +0s, +${schedule[0]}s, +${schedule[1]}s, then every ${schedule[2]}s)\n`);
|
|
14480
14904
|
let res;
|
|
14481
14905
|
try {
|
|
14482
14906
|
res = ciWait.waitLoop({
|
|
14483
|
-
poll, sleep: ciWait.sleepSync, deadlineSec,
|
|
14907
|
+
poll, sleep: ciWait.sleepSync, deadlineSec, schedule,
|
|
14484
14908
|
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`); },
|
|
14485
14909
|
});
|
|
14486
14910
|
} finally {
|
|
@@ -14490,14 +14914,15 @@ function cmdCiWait(argv) {
|
|
|
14490
14914
|
const code = ciWait.EXIT[res.outcome];
|
|
14491
14915
|
const out = {
|
|
14492
14916
|
outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified, forced: res.forced,
|
|
14493
|
-
waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
|
|
14917
|
+
waitedSec: Math.round(res.waitedMs / 1000), deadlineSec, deadlineBasis, detail: res.detail || null,
|
|
14494
14918
|
status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
|
|
14495
14919
|
...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
|
|
14920
|
+
...(Array.isArray(s.dispatchCounted) && s.dispatchCounted.length ? { dispatchCounted: s.dispatchCounted } : {}),
|
|
14496
14921
|
};
|
|
14497
14922
|
if (opts.json) print(JSON.stringify(out, null, 2));
|
|
14498
14923
|
else {
|
|
14499
14924
|
print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
|
|
14500
|
-
`${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}`);
|
|
14925
|
+
`${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}`);
|
|
14501
14926
|
}
|
|
14502
14927
|
return code;
|
|
14503
14928
|
}
|
|
@@ -14551,6 +14976,264 @@ function landedBaseTrunk(repoAbs) {
|
|
|
14551
14976
|
'gets measured against the wrong one.)');
|
|
14552
14977
|
}
|
|
14553
14978
|
|
|
14979
|
+
const HELP_BATCH_STATS = `colab batch-stats [--repo <path>] [--since <30d | 12h | YYYY-MM-DD>] [--json]
|
|
14980
|
+
|
|
14981
|
+
How batch landing (#373) actually performs in this repo — read-only, derived from GitHub so it
|
|
14982
|
+
answers the same on any machine (#554). It is how a repo tunes its batch knobs: ship-batch: <N>
|
|
14983
|
+
and ship-batch-wait: <duration> have no handbook default (CONVENTIONS §4, Batch landing).
|
|
14984
|
+
|
|
14985
|
+
Sources: trunk's first-parent log since --since (default 30d) — Ship-Batch: trailers mark batch
|
|
14986
|
+
members, Ship-Batch-Dropped: trailers mark members dropped at build, anything else with a
|
|
14987
|
+
Closes #N is a serial landing — and the repo's CI runs in the same window (REST, paginated):
|
|
14988
|
+
ship-batch/** runs are the combined runs, feature-branch runs say when a branch went green at
|
|
14989
|
+
its head, trunk runs say when a landing was pushed and when its trunk-CI cycle ended.
|
|
14990
|
+
|
|
14991
|
+
Reports:
|
|
14992
|
+
batches landed, and their fill · combined-run builds: first-attempt green, green after the
|
|
14993
|
+
one re-run, red, pending
|
|
14994
|
+
red red builds, and how many of their members then landed serially (the fallback)
|
|
14995
|
+
dropped members dropped at build, by class, and the eviction rate
|
|
14996
|
+
serial serial landings, and MISSED PARTNERS — another change, landed later, that was
|
|
14997
|
+
already green when this one landed alone (could have joined) or went green inside
|
|
14998
|
+
this landing's trunk-CI cycle (a near miss; its wait is what ship-batch-wait buys)
|
|
14999
|
+
queue wait green-at-head → landing, per landed change
|
|
15000
|
+
|
|
15001
|
+
No batch history in the window is an answer, not an error: it says so, and still reports the
|
|
15002
|
+
serial side — missed partners are the evidence for turning ship-batch on at all. Not the optional
|
|
15003
|
+
machine-local journal: that is off by default and per-machine, so it cannot be the source.
|
|
15004
|
+
--json is the input for an audit; its shape is batch-stats.js derive()'s return value.
|
|
15005
|
+
Exit 0 on a report (empty or not); 1 when trunk's log cannot be read.
|
|
15006
|
+
`;
|
|
15007
|
+
|
|
15008
|
+
/** `--since`: `<N>d` / `<N>h` / `<N>m` back from now, or an ISO date. → epoch ms, or null. */
|
|
15009
|
+
function batchStatsSince(v, nowMs) {
|
|
15010
|
+
const s = String(v || '30d').trim();
|
|
15011
|
+
const rel = /^(\d+)([dhm])$/.exec(s);
|
|
15012
|
+
if (rel) return nowMs - Number(rel[1]) * ({ d: 86400, h: 3600, m: 60 })[rel[2]] * 1000;
|
|
15013
|
+
const t = Date.parse(s);
|
|
15014
|
+
return Number.isFinite(t) ? t : null;
|
|
15015
|
+
}
|
|
15016
|
+
|
|
15017
|
+
function cmdBatchStats(argv) {
|
|
15018
|
+
const opts = parseArgs(argv, {
|
|
15019
|
+
values: { '--repo': 'repo', '--since': 'since' },
|
|
15020
|
+
flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
|
|
15021
|
+
});
|
|
15022
|
+
if (opts.help) return print(HELP_BATCH_STATS);
|
|
15023
|
+
const repoAbs = resolveRepo(opts);
|
|
15024
|
+
if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo — pass --repo <path> to a clone`);
|
|
15025
|
+
const doc = projectDoc(repoAbs);
|
|
15026
|
+
const trunk = resolveTrunk(repoAbs, doc);
|
|
15027
|
+
if (!trunk) throw new UserError('Could not determine trunk branch — add `trunk: <branch>` to .github/project.yml, then run `colab batch-stats` again');
|
|
15028
|
+
const nowMs = Date.now();
|
|
15029
|
+
const sinceMs = batchStatsSince(opts.since, nowMs);
|
|
15030
|
+
if (sinceMs === null) throw new UserError(`--since ${JSON.stringify(opts.since)}: expected 30d, 12h, 90m or an ISO date`);
|
|
15031
|
+
const sinceIso = new Date(sinceMs).toISOString();
|
|
15032
|
+
const notes = [];
|
|
15033
|
+
|
|
15034
|
+
const remote = git.remoteFor(repoAbs);
|
|
15035
|
+
const f = git.git(['fetch', remote, trunk], repoAbs);
|
|
15036
|
+
if (!f.ok) notes.push(`could not fetch ${remote}/${trunk} (${git.gitFailureLine(f.stderr)}) — read from the local copy, which may be behind`);
|
|
15037
|
+
const log = git.git(['log', `${remote}/${trunk}`, '--first-parent', `--since=${sinceIso}`, '--format=%H%x1f%cI%x1f%B%x1e'], repoAbs);
|
|
15038
|
+
if (!log.ok) throw new UserError(`could not read ${remote}/${trunk}: ${git.gitFailureLine(log.stderr)} — run \`git fetch ${remote} ${trunk}\`, then run this again`);
|
|
15039
|
+
const commits = log.stdout.split('\x1e').map((r) => r.replace(/^\n/, '')).filter((r) => r.trim()).map((r) => {
|
|
15040
|
+
const [sha, iso, body] = r.split('\x1f');
|
|
15041
|
+
return { sha: sha.trim(), dateMs: Date.parse(iso), body: body || '' };
|
|
15042
|
+
});
|
|
15043
|
+
|
|
15044
|
+
let runs = [];
|
|
15045
|
+
const builds = {};
|
|
15046
|
+
if (!isGhUsable(repoAbs)) {
|
|
15047
|
+
notes.push(`gh not usable (${ghUnusableWhy(repoAbs)}) — trunk commits only: no combined runs, no green times, no partner matching`);
|
|
15048
|
+
} else {
|
|
15049
|
+
const jq = '.workflow_runs[] | [.id, .head_branch, .head_sha, .event, .status, .conclusion, .run_attempt, .created_at, .updated_at, (if ((.head_branch // "") | startswith("ship-batch/")) then .head_commit.message else null end)] | @json';
|
|
15050
|
+
// One query per UTC day: GitHub answers at most 1000 rows for a filtered run list, and a busy
|
|
15051
|
+
// repo passes that inside a fortnight. A day that still hits the cap is named, never hidden.
|
|
15052
|
+
const days = [];
|
|
15053
|
+
for (let d = Date.parse(sinceIso.slice(0, 10)); d <= nowMs; d += 86_400_000) days.push(new Date(d).toISOString().slice(0, 10));
|
|
15054
|
+
let failed = null;
|
|
15055
|
+
const capped = [];
|
|
15056
|
+
for (const day of days) {
|
|
15057
|
+
const r = git.ghApi(repoAbs, ['--paginate', `repos/{owner}/{repo}/actions/runs?per_page=100&created=${day}`, '--jq', jq]);
|
|
15058
|
+
if (!r.ok) { failed = git.gitFailureLine(r.stderr); break; }
|
|
15059
|
+
let n = 0;
|
|
15060
|
+
for (const line of String(r.stdout || '').split('\n')) {
|
|
15061
|
+
if (!line.trim()) continue;
|
|
15062
|
+
let a; try { a = JSON.parse(line); } catch (_) { continue; }
|
|
15063
|
+
n++;
|
|
15064
|
+
runs.push({ id: a[0], branch: a[1], sha: a[2], event: a[3], status: a[4], conclusion: a[5], attempt: a[6], createdMs: Date.parse(a[7]), updatedMs: Date.parse(a[8]), message: a[9] });
|
|
15065
|
+
}
|
|
15066
|
+
if (n >= 1000) capped.push(day);
|
|
15067
|
+
}
|
|
15068
|
+
if (failed) { notes.push(`could not list CI runs (${failed}) — trunk commits only`); runs = []; }
|
|
15069
|
+
else {
|
|
15070
|
+
if (capped.length) notes.push(`GitHub caps a filtered run list at 1000 and ${capped.join(', ')} hit it — those days are incomplete`);
|
|
15071
|
+
// An unlanded combined run's ref is usually gone: read every commit of the build, so a red
|
|
15072
|
+
// batch's members and its drops are known, not just its head commit's.
|
|
15073
|
+
const landedShas = new Set(commits.map((c) => c.sha));
|
|
15074
|
+
const unlanded = [...new Set(runs.filter((x) => String(x.branch || '').startsWith(shipBatch.REF_PREFIX) && !landedShas.has(x.sha)).map((x) => `${x.branch} ${x.sha}`))];
|
|
15075
|
+
for (const k of unlanded) {
|
|
15076
|
+
const [ref, sha] = k.split(' ');
|
|
15077
|
+
const base7 = (shipBatch.parseBatchRef(ref) || {}).base7;
|
|
15078
|
+
if (!base7) continue;
|
|
15079
|
+
const c = git.ghApi(repoAbs, [`repos/{owner}/{repo}/compare/${base7}...${sha}`, '--jq', '[.commits[].commit.message]']);
|
|
15080
|
+
if (c.ok) { try { builds[sha] = JSON.parse(c.stdout); } catch (_) { /* head message only */ } }
|
|
15081
|
+
}
|
|
15082
|
+
}
|
|
15083
|
+
}
|
|
15084
|
+
|
|
15085
|
+
const cfg = shipBatch.parseShipBatch(doc);
|
|
15086
|
+
const waitCfg = shipBatch.parseShipBatchWait(doc);
|
|
15087
|
+
const rep = batchStats.derive({ commits, runs, builds, trunk, config: { n: cfg.n, waitSec: waitCfg.sec } });
|
|
15088
|
+
rep.repo = shortRepo(repoAbs);
|
|
15089
|
+
rep.since = sinceIso;
|
|
15090
|
+
rep.until = new Date(nowMs).toISOString();
|
|
15091
|
+
rep.notes = [...notes, ...rep.notes];
|
|
15092
|
+
if (opts.json) { print(JSON.stringify(rep, null, 2)); return 0; }
|
|
15093
|
+
|
|
15094
|
+
const pct = (x) => (x === null ? '—' : `${Math.round(x * 100)}%`);
|
|
15095
|
+
const dur = (s) => (s === null ? '—' : ciWait.fmtDuration(s * 1000));
|
|
15096
|
+
const q = (w) => (w.samples ? `p50 ${dur(w.p50Sec)} · p90 ${dur(w.p90Sec)} · max ${dur(w.maxSec)} (${w.samples})` : 'no samples');
|
|
15097
|
+
print(`batch-stats ${rep.repo} → ${trunk} ${rep.since.slice(0, 10)} … ${rep.until.slice(0, 10)} (ship-batch: ${cfg.n}${waitCfg.sec ? ` · ship-batch-wait: ${dur(waitCfg.sec)}` : ''})`);
|
|
15098
|
+
print(` landings ${rep.landings.total} (${rep.landings.batch} batch · ${rep.landings.serial} serial)`);
|
|
15099
|
+
if (!rep.history) print(' batches no batch history in this window — nothing has landed or been built through colab ship --batch');
|
|
15100
|
+
else {
|
|
15101
|
+
const fill = Object.keys(rep.batches.fill).sort().map((k) => `${rep.batches.fill[k]}×${k}`).join(' · ') || '—';
|
|
15102
|
+
print(` batches ${rep.batches.landed} landed (fill ${fill}) · ${rep.batches.builds} combined-run build(s): ${rep.batches.firstAttemptGreen} first-attempt green (${pct(rep.batches.firstAttemptGreenRate)}), ${rep.batches.greenAfterRerun} after a re-run, ${rep.batches.red} red, ${rep.batches.pending} pending`);
|
|
15103
|
+
print(` red ${rep.red.builds} build(s) · ${rep.red.members} member(s), ${rep.red.relandedSerially} then landed serially`);
|
|
15104
|
+
const cls = Object.entries(rep.dropped.byClass).map(([k, v]) => `${v} ${k}`).join(', ');
|
|
15105
|
+
print(` dropped ${rep.dropped.count} of ${rep.dropped.attempted} attempted (${pct(rep.dropped.rate)})${cls ? ` — ${cls}` : ''}`);
|
|
15106
|
+
}
|
|
15107
|
+
print(` serial ${rep.serial.landings} landed alone · ${rep.serial.withMissedPartner} with a missed partner (already green) · ${rep.serial.withNearMiss} more with a near miss (green within its trunk-CI cycle)`);
|
|
15108
|
+
if (rep.serial.nearMissWait.samples) print(` near misses per pair, the wait from the lone change's own green that would have caught its partner: ${q(rep.serial.nearMissWait)}`);
|
|
15109
|
+
print(` queue wait green-at-head → landing: ${q(rep.queueWait)}`);
|
|
15110
|
+
for (const n of rep.notes) print(` ! ${n}`);
|
|
15111
|
+
return 0;
|
|
15112
|
+
}
|
|
15113
|
+
|
|
15114
|
+
// ci-profile (#559) — the repo's measured CI duration and every wait bound derived from it.
|
|
15115
|
+
const HELP_CI_PROFILE = `colab ci-profile [--repo <path>] [--json] [--refresh]
|
|
15116
|
+
|
|
15117
|
+
This repo's measured CI duration, and every CI wait bound derived from it (#559). One source:
|
|
15118
|
+
\`colab ci-wait\` with no --timeout, and \`colab ship\`'s wedged-run and empty-read verdicts, read
|
|
15119
|
+
these same numbers — no skill hard-codes a wait.
|
|
15120
|
+
|
|
15121
|
+
Measured: per sha, the wall time from the first verifying run's creation to the last one's
|
|
15122
|
+
finish, over clean first-attempt green shas in the last ${ciProfile.WINDOW_DAYS} days — split into branch runs and trunk
|
|
15123
|
+
runs — plus the push → run lag on trunk. A kind with fewer than ${ciProfile.MIN_SAMPLES} samples stays on its
|
|
15124
|
+
bootstrap value, which is today's fleet value exactly (15m waits, 6h wedge, 10m grace, 2m floor).
|
|
15125
|
+
|
|
15126
|
+
Declared: only \`ci-wait-factor: <number ≥ 1>\` in .github/project.yml (default ${ciProfile.DEFAULT_FACTOR}) — how many times
|
|
15127
|
+
the measured p95 a repo will wait. Every bound:
|
|
15128
|
+
branch / trunk wait 2m + factor × p95 of that kind, rounded up to the minute
|
|
15129
|
+
wedged-run age factor × the longer wait, never above 6h
|
|
15130
|
+
empty-read grace factor × push→run p95, never below 2m
|
|
15131
|
+
zero-jobs floor 2m (not measurable from the run list)
|
|
15132
|
+
poll backoff 30/60/120s, stretched in proportion to a wait past 15m — never faster
|
|
15133
|
+
|
|
15134
|
+
The profile is cached per checkout for a day (<git common dir>/colab-ci-profile.json;
|
|
15135
|
+
COLAB_CI_PROFILE_TTL seconds overrides, 0 = no cache and no read: the bootstrap). The bounds are
|
|
15136
|
+
recomputed from it on every read, so a changed ci-wait-factor applies at once.
|
|
15137
|
+
|
|
15138
|
+
--refresh re-read the CI history now, whatever the cache's age
|
|
15139
|
+
--json { repo, trunk, source, factor, cache, measured: { branch, trunk, lag }, thresholds, notes }`;
|
|
15140
|
+
|
|
15141
|
+
function cmdCiProfile(argv) {
|
|
15142
|
+
const opts = parseArgs(argv, {
|
|
15143
|
+
values: { '--repo': 'repo' },
|
|
15144
|
+
flags: { '--json': 'json', '--refresh': 'refresh', '-h': 'help', '--help': 'help' },
|
|
15145
|
+
});
|
|
15146
|
+
if (opts.help) return print(HELP_CI_PROFILE);
|
|
15147
|
+
const repoAbs = resolveRepo(opts);
|
|
15148
|
+
if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo — pass --repo <path> to a clone, then run \`colab ci-profile\` again`);
|
|
15149
|
+
const cp = ciProfileFor(repoAbs, { fetch: opts.refresh ? 'always' : 'if-stale' });
|
|
15150
|
+
if (!cp.trunk) throw new UserError('Could not determine trunk branch — add `trunk: <branch>` to .github/project.yml, then run `colab ci-profile` again');
|
|
15151
|
+
const p = cp.profile || ciProfile.profile([]);
|
|
15152
|
+
const th = cp.th;
|
|
15153
|
+
const source = cp.profile ? cp.profile.source : 'bootstrap';
|
|
15154
|
+
if (opts.json) {
|
|
15155
|
+
print(JSON.stringify({
|
|
15156
|
+
repo: shortRepo(repoAbs), trunk: cp.trunk, source, factor: cp.factor, cache: cp.cache,
|
|
15157
|
+
measured: { branch: p.branch, trunk: p.trunk, lag: p.lag }, thresholds: th, notes: cp.notes,
|
|
15158
|
+
}, null, 2));
|
|
15159
|
+
return 0;
|
|
15160
|
+
}
|
|
15161
|
+
const dur = (s) => (s === null || s === undefined ? '—' : ciWait.fmtDuration(s * 1000));
|
|
15162
|
+
const cacheTxt = cp.cache.state === 'fetched' ? 'read now'
|
|
15163
|
+
: cp.cache.state === 'none' ? 'no history read' : `read ${dur(cp.cache.ageSec)} ago (cache${cp.cache.state === 'stale' ? ', stale' : ''})`;
|
|
15164
|
+
print(`ci-profile ${shortRepo(repoAbs)} → ${cp.trunk} ${source.toUpperCase()} · ${cacheTxt} · ${cp.factor.valid ? cp.factor.reason : `${ciProfile.FACTOR_KEY}: ${ciProfile.DEFAULT_FACTOR} (declared value invalid)`}`);
|
|
15165
|
+
if (source !== 'measured') print(` ${source === 'bootstrap' ? 'every bound is' : 'unmeasured bounds are'} the bootstrap — fewer than ${ciProfile.MIN_SAMPLES} clean green shas per kind in ${ciProfile.WINDOW_DAYS}d`);
|
|
15166
|
+
const k = (name, x) => print(` ${name.padEnd(11)} ${x.source} · ${x.samples} sha(s)${x.samples ? ` · p50 ${dur(x.p50Sec)} · p95 ${dur(x.p95Sec)} · max ${dur(x.maxSec)}` : ''}`);
|
|
15167
|
+
k('branch', p.branch);
|
|
15168
|
+
k('trunk', p.trunk);
|
|
15169
|
+
print(` ${'push→run'.padEnd(11)} ${p.lag.source} · ${p.lag.samples} sample(s)${p.lag.samples ? ` · p95 ${dur(p.lag.p95Sec)}` : ''}`);
|
|
15170
|
+
const row = (name, sec, basis, how, boot) => print(` ${name.padEnd(11)} ${dur(sec).padEnd(7)} ${basis === 'measured' ? how : basis === 'default' ? how : 'bootstrap'}${basis === 'measured' && boot ? ` (bootstrap ${boot})` : ''}`);
|
|
15171
|
+
row('branch wait', th.branchWaitSec, th.basis.branchWait, `2m + ${th.factor} × p95`, '15m');
|
|
15172
|
+
row('trunk wait', th.trunkWaitSec, th.basis.trunkWait, `2m + ${th.factor} × p95`, '15m');
|
|
15173
|
+
print(` ${'ci-wait'.padEnd(11)} ${dur(th.ciWaitDefaultSec.branch)} branch · ${dur(th.ciWaitDefaultSec.trunk)} trunk · ${dur(th.ciWaitDefaultSec.any)} run id (its default with no --timeout)`);
|
|
15174
|
+
row('wedged age', th.wedgeAgeSec, th.basis.wedgeAge, `${th.factor} × the longer wait, ≤ 6h`, '6h');
|
|
15175
|
+
row('empty read', th.emptyReadGraceSec, th.basis.emptyReadGrace, `${th.factor} × push→run p95, ≥ 2m`, '10m');
|
|
15176
|
+
row('zero jobs', th.zeroJobsFloorSec, th.basis.zeroJobsFloor, 'default — not measurable from the run list');
|
|
15177
|
+
print(` ${'backoff'.padEnd(11)} branch ${th.scheduleSec.branch.map((x) => `${x}s`).join('/')} · trunk ${th.scheduleSec.trunk.map((x) => `${x}s`).join('/')}`);
|
|
15178
|
+
for (const n of cp.notes) print(` ! ${n}`);
|
|
15179
|
+
return 0;
|
|
15180
|
+
}
|
|
15181
|
+
|
|
15182
|
+
// thresholds (#560) — the advisory thresholds this repo applies: its declared values, else the defaults.
|
|
15183
|
+
const HELP_THRESHOLDS = `colab thresholds [--repo <path>] [--json] [<name>]
|
|
15184
|
+
|
|
15185
|
+
The advisory thresholds this repo applies (#560): the value of each, and whether it is this
|
|
15186
|
+
repo's declared value or the handbook default. A repo overrides one in .github/project.yml:
|
|
15187
|
+
|
|
15188
|
+
thresholds:
|
|
15189
|
+
hot-file-count: 4
|
|
15190
|
+
|
|
15191
|
+
Nothing changes for a repo that declares nothing. Skills cite these by name — code-triage's
|
|
15192
|
+
hot-file count and dependents band, code-wrap's gate.smoke target — and read them here, so no
|
|
15193
|
+
skill hard-codes a number a repo may have changed. A malformed entry falls back to the default
|
|
15194
|
+
and is listed under problems; the audit and the CI templates' descriptor check fail it.
|
|
15195
|
+
|
|
15196
|
+
The batch-* names (#556) have NO default: undeclared, they read "—" and the audit's
|
|
15197
|
+
--batch-history shows the measurement without judging it. Percents are bounded at 100.
|
|
15198
|
+
|
|
15199
|
+
<name> print only that threshold's value (a bare number, for a script or a skill;
|
|
15200
|
+
an empty line for an undeclared no-default name)
|
|
15201
|
+
--json { repo, thresholds: { <name>: { value, default, declared, what, where } }, problems }`;
|
|
15202
|
+
|
|
15203
|
+
function cmdThresholds(argv) {
|
|
15204
|
+
const opts = parseArgs(argv, {
|
|
15205
|
+
values: { '--repo': 'repo' },
|
|
15206
|
+
flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
|
|
15207
|
+
});
|
|
15208
|
+
if (opts.help) return print(HELP_THRESHOLDS);
|
|
15209
|
+
const repoAbs = resolveRepo(opts);
|
|
15210
|
+
const r = thresholdsLib.parseThresholds(projectDoc(repoAbs));
|
|
15211
|
+
const name = opts._ && opts._[0];
|
|
15212
|
+
if (name !== undefined) {
|
|
15213
|
+
if (!thresholdsLib.SPEC[name]) throw new UserError(`unknown threshold ${name} — expected one of: ${Object.keys(thresholdsLib.SPEC).join(', ')} (run \`colab thresholds\` to list them)`);
|
|
15214
|
+
for (const p of r.problems) process.stderr.write(`! ${p}\n`);
|
|
15215
|
+
print(r.values[name] === null ? '' : String(r.values[name])); // #556: empty = undeclared, no default
|
|
15216
|
+
return 0;
|
|
15217
|
+
}
|
|
15218
|
+
const rows = Object.fromEntries(Object.entries(thresholdsLib.SPEC).map(([k, s]) => [k, {
|
|
15219
|
+
value: r.values[k], default: s.def, declared: !!r.declared[k], what: s.what, where: s.where,
|
|
15220
|
+
}]));
|
|
15221
|
+
if (opts.json) {
|
|
15222
|
+
print(JSON.stringify({ repo: shortRepo(repoAbs), thresholds: rows, problems: r.problems }, null, 2));
|
|
15223
|
+
return 0;
|
|
15224
|
+
}
|
|
15225
|
+
print(`thresholds ${shortRepo(repoAbs)}`);
|
|
15226
|
+
const w = Math.max(...Object.keys(rows).map((k) => k.length));
|
|
15227
|
+
for (const [k, row] of Object.entries(rows)) {
|
|
15228
|
+
// #556: a no-default key (batch-*) shows `—` and "not declared" — nothing judges it until it is.
|
|
15229
|
+
const shown = row.value === null ? '—' : String(row.value);
|
|
15230
|
+
const src = row.declared ? `declared (default ${row.default === null ? 'none' : row.default})` : (row.default === null ? 'not declared' : 'default');
|
|
15231
|
+
print(` ${k.padEnd(w)} ${shown.padStart(5)} ${src.padEnd(20)} ${row.what}`);
|
|
15232
|
+
}
|
|
15233
|
+
for (const p of r.problems) print(` ! ${p}`);
|
|
15234
|
+
return 0;
|
|
15235
|
+
}
|
|
15236
|
+
|
|
14554
15237
|
function cmdLanded(argv) {
|
|
14555
15238
|
const opts = parseArgs(argv, {
|
|
14556
15239
|
values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--base': 'base' },
|
|
@@ -15335,6 +16018,13 @@ Commands:
|
|
|
15335
16018
|
landed [--worktree N | --branch B | --all] [--base B] [--json] has this work already landed?
|
|
15336
16019
|
(the shared rule behind code-sweep's buckets — correct
|
|
15337
16020
|
across squash merges, where "commits ahead" is not)
|
|
16021
|
+
batch-stats [--since 30d] [--json] how batch landing performs here, from git + CI history —
|
|
16022
|
+
fill, first-attempt green, drops, missed partners, queue
|
|
16023
|
+
wait; how a repo tunes ship-batch / ship-batch-wait (#554)
|
|
16024
|
+
ci-profile [--json] [--refresh] this repo's measured CI duration and every CI wait bound
|
|
16025
|
+
derived from it — ci-wait's default deadline (#559)
|
|
16026
|
+
thresholds [<name>] [--json] the advisory thresholds this repo applies — declared in
|
|
16027
|
+
project.yml thresholds:, else the default (#560)
|
|
15338
16028
|
holders <path> [--base B] [--json] who else is holding <path> — refs that touched it and
|
|
15339
16029
|
have not landed on the base (filters the raw git-log
|
|
15340
16030
|
one-liner through \`landed\`'s content classification)
|
|
@@ -15419,6 +16109,9 @@ function main(argv) {
|
|
|
15419
16109
|
case 'worktrees': return cmdWorktrees(rest);
|
|
15420
16110
|
case 'ship': return cmdShip(rest);
|
|
15421
16111
|
case 'landed': return cmdLanded(rest);
|
|
16112
|
+
case 'batch-stats': return cmdBatchStats(rest);
|
|
16113
|
+
case 'ci-profile': return cmdCiProfile(rest);
|
|
16114
|
+
case 'thresholds': return cmdThresholds(rest);
|
|
15422
16115
|
case 'trunk-ci': return cmdTrunkCi(rest);
|
|
15423
16116
|
case 'ci-wait': return cmdCiWait(rest);
|
|
15424
16117
|
case 'holders': return cmdHolders(rest);
|