@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/README.vi.md +2 -2
- package/audit/audit.mjs +90 -10
- package/package.json +1 -1
- package/templates/README.md +18 -3
- package/templates/ci-laravel.yml +360 -40
- package/templates/ci-node.yml +491 -35
- package/templates/ci-python.yml +301 -32
- package/templates/deploy-container-run.mjs +17 -3
- package/templates/deploy-xserver.yml +12 -0
- package/templates/instruction-files.yml +11 -0
- package/templates/pre-commit-instruction-files +55 -0
- package/tools/colab +750 -67
- package/tools/lib/batch-stats.js +66 -43
- package/tools/lib/claim-comments.js +3 -2
- package/tools/lib/codec/decision.d.ts +7 -0
- package/tools/lib/codec/decision.js +54 -0
- package/tools/lib/codec/hold.d.ts +8 -1
- package/tools/lib/codec/hold.js +42 -8
- package/tools/lib/codec/release.js +6 -3
- package/tools/lib/codec/samples.json +45 -0
- package/tools/lib/config-set.js +4 -3
- package/tools/lib/decision-record.js +42 -0
- package/tools/lib/docs-only.js +47 -0
- package/tools/lib/git.js +57 -8
- package/tools/lib/instruction-file.js +49 -0
- package/tools/lib/instruction-gate.js +150 -0
- package/tools/lib/landed-prs.js +58 -0
- package/tools/lib/migration-grant.js +29 -5
- package/tools/lib/owner-policy.js +133 -0
- package/tools/lib/release-finalize.js +66 -5
- package/tools/lib/ship-batch.js +188 -14
- package/tools/lib/ship-handoff.js +174 -0
- package/tools/lib/stamp.js +6 -2
- package/tools/lib/template-trunk.js +80 -0
- package/tools/lib/tree-green.js +21 -4
package/tools/colab
CHANGED
|
@@ -43,6 +43,7 @@ const decisionRecord = require('./lib/decision-record');
|
|
|
43
43
|
const blockedBy = require('./lib/blocked-by');
|
|
44
44
|
const ciGrant = require('./lib/ci-grant');
|
|
45
45
|
const trustHumans = require('./lib/trust-humans');
|
|
46
|
+
const ownerPolicy = require('./lib/owner-policy');
|
|
46
47
|
const ciCure = require('./lib/ci-cure');
|
|
47
48
|
const ciVerdict = require('./lib/ci-verdict');
|
|
48
49
|
const baseCiVerdict = require('./lib/base-ci-verdict');
|
|
@@ -77,11 +78,14 @@ const releaseCut = require('./lib/release-cut');
|
|
|
77
78
|
const releaseFinalize = require('./lib/release-finalize');
|
|
78
79
|
const releaseChannel = require('./lib/release-channel');
|
|
79
80
|
const shippedBranch = require('./lib/shipped-branch');
|
|
81
|
+
const landedPrs = require('./lib/landed-prs');
|
|
80
82
|
const shipRoles = require('./lib/ship-roles'); // #372
|
|
83
|
+
const shipHandoff = require('./lib/ship-handoff'); // #578
|
|
81
84
|
const refsBrake = require('./lib/refs-brake'); // #385
|
|
82
85
|
const localAdopt = require('./lib/local-adopt'); // #393
|
|
83
86
|
const ownerBranch = require('./lib/owner-branch'); // #394
|
|
84
87
|
const humanDoor = require('./lib/ship-human-door'); // #525
|
|
88
|
+
const instructionGate = require('./lib/instruction-gate'); // #588
|
|
85
89
|
const {
|
|
86
90
|
HOST, UserError, normIssueNum, issueTag, claimKey, today, nowISO, hoursSince, humanAge,
|
|
87
91
|
parseArgs, table, shortRepo,
|
|
@@ -2001,7 +2005,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2001
2005
|
const issues = readAllIssuesForSwitches(repoAbs);
|
|
2002
2006
|
const labelNames = (i) => (i.labels || []).map((l) => (typeof l === 'string' ? l : l.name));
|
|
2003
2007
|
const records = (issues || [])
|
|
2004
|
-
.map((i) => ({ number: i.number, url: i.url || null, state: String(i.state || '').toUpperCase(), createdAt: i.createdAt || null, held: labelNames(i).includes(releaseFinalize.HOLD_LABEL), version: releaseFinalize.parseReleaseMarker(i.body) }))
|
|
2008
|
+
.map((i) => ({ number: i.number, url: i.url || null, title: i.title == null ? null : String(i.title), state: String(i.state || '').toUpperCase(), createdAt: i.createdAt || null, held: labelNames(i).includes(releaseFinalize.HOLD_LABEL), version: releaseFinalize.parseReleaseMarker(i.body) }))
|
|
2005
2009
|
.filter((r) => r.version);
|
|
2006
2010
|
const trackingFor = (version, { isCandidate }) => {
|
|
2007
2011
|
if (issues === null) return { error: 'the issue list could not be read (or may be truncated) — the tracking issue cannot be found' };
|
|
@@ -2009,7 +2013,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2009
2013
|
const open = mine.filter((r) => r.state === 'OPEN');
|
|
2010
2014
|
if (open.length > 1) return { error: `${open.length} open tracking issues for ${version} (${open.map((r) => `#${r.number}`).join(', ')}) — one per version; close the duplicate by hand` };
|
|
2011
2015
|
if (open.length === 1) return { ...open[0] };
|
|
2012
|
-
if (isCandidate && mine.length) return { error: `the tracking issue for ${version} (#${mine[0].number}) is closed but ${version} is not final — reopen it; a closed record is never silently replaced` };
|
|
2016
|
+
if (isCandidate && mine.length) return { error: `the tracking issue for ${version} (#${mine[0].number}${mine[0].title ? ` ${JSON.stringify(mine[0].title)}` : ''}) is closed but ${version} is not final — reopen it; a closed record is never silently replaced` };
|
|
2013
2017
|
return { number: null, createdAt: null, held: false, wouldCreate: !opts.dry };
|
|
2014
2018
|
};
|
|
2015
2019
|
const version0 = newest ? newest.version : (selection.version || null);
|
|
@@ -2021,7 +2025,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2021
2025
|
const body = releaseFinalize.trackingBody({ version: version0, row: policy.derived.row, final: policy.effective.final, testPeriodDays: policy.effective.testPeriodDays });
|
|
2022
2026
|
const c = tracker.forRepo(repoAbs).issueCreate({ title: releaseFinalize.trackingTitle(version0), body });
|
|
2023
2027
|
if (!c.number) trackings.set(version0, { error: `could not open the tracking issue for ${version0} (${String(c.stderr || '').split('\n')[0] || 'no issue URL returned'})` });
|
|
2024
|
-
else { trackings.set(version0, { number: c.number, url: c.url, createdAt: now, held: false }); trackingCreated = true; }
|
|
2028
|
+
else { trackings.set(version0, { number: c.number, url: c.url, title: releaseFinalize.trackingTitle(version0), createdAt: now, held: false }); trackingCreated = true; }
|
|
2025
2029
|
}
|
|
2026
2030
|
|
|
2027
2031
|
// #441: an operator-granted automatic final — the decision it names is resolved once per run, from
|
|
@@ -2048,10 +2052,25 @@ function cmdReleaseFinalize(argv) {
|
|
|
2048
2052
|
});
|
|
2049
2053
|
// #566: only the run that CUT the candidate vouches for what it published — read from the rows
|
|
2050
2054
|
// BEFORE the #425 own-workflow filter (the release workflow is the cutter), minus this run itself.
|
|
2051
|
-
const
|
|
2055
|
+
const cutRunOpts = {
|
|
2052
2056
|
tag: cand.tag, cutAt: cand.cutAt, ownRunId: process.env.GITHUB_ACTIONS === 'true' ? process.env.GITHUB_RUN_ID || null : null,
|
|
2053
2057
|
jobCount: (id) => git.ghRunJobCount(repoAbs, id),
|
|
2054
|
-
}
|
|
2058
|
+
};
|
|
2059
|
+
const cutRun = releaseFinalize.cutRunVerdict(rawRows, cutRunOpts);
|
|
2060
|
+
// #565: a run that failed only in its deploy jobs (staging) — the three run-reading conditions
|
|
2061
|
+
// re-read with it counted as passed. decide() uses that reading on a human final only, and names
|
|
2062
|
+
// the failure either way. Jobs are read lazily: only when a condition already failed.
|
|
2063
|
+
let deployReport = null;
|
|
2064
|
+
if (Array.isArray(rawRows) && !(conditions.ci.ok && conditions.suite.ok && cutRun.ok)) {
|
|
2065
|
+
const d = releaseFinalize.deployOnlyFailures(rawRows, (id) => git.ghRunJobs(repoAbs, id));
|
|
2066
|
+
if (d.failures.length) {
|
|
2067
|
+
const at = `${cand.tag}@${shortSha(cand.sha)}`;
|
|
2068
|
+
const lenRows = releaseCut.withoutOwnWorkflow(d.rows); // #425, as readRuns does
|
|
2069
|
+
const run = git.summarizeRunsForCommit(lenRows, cand.sha);
|
|
2070
|
+
const ci = run ? (({ ok, detail }) => ({ ok, detail }))(classifyCiRun(repoAbs, run, at)) : { ok: false, detail: `gh run list failed — cannot confirm CI at ${at}` };
|
|
2071
|
+
deployReport = { failures: d.failures, ci, suite: releaseCut.fullSuiteVerdict(lenRows, at), cutRun: releaseFinalize.cutRunVerdict(d.rows, cutRunOpts) };
|
|
2072
|
+
}
|
|
2073
|
+
}
|
|
2055
2074
|
const suiteWorkflows = [...new Set((rows || []).map((r) => r.workflowName || '(unnamed workflow)'))];
|
|
2056
2075
|
const period = releaseFinalize.periodVerdict({ cutAt: cand.cutAt, trackingCreatedAt: tracking && tracking.createdAt, testPeriodDays: policy.effective.testPeriodDays, now });
|
|
2057
2076
|
// #437: the window is main plus project.yml's trunk: when that is another branch (trunk: dev).
|
|
@@ -2075,7 +2094,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2075
2094
|
}
|
|
2076
2095
|
const verdict = releaseFinalize.decide({
|
|
2077
2096
|
policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
|
|
2078
|
-
ci: conditions.ci, suite: conditions.suite, cutRun, schema: conditions.schema, switches: conditions.switches,
|
|
2097
|
+
ci: conditions.ci, suite: conditions.suite, cutRun, deployReport, schema: conditions.schema, switches: conditions.switches,
|
|
2079
2098
|
manifests, ancestry, tags: tagNames, finalGrant, migrations,
|
|
2080
2099
|
human: { bar: humanBar, answeredBy: opts.answeredBy || null },
|
|
2081
2100
|
});
|
|
@@ -2202,7 +2221,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2202
2221
|
|
|
2203
2222
|
const supersededHeld = records.filter((r) => r.state === 'OPEN' && r.held && r.version !== (cand ? cand.version : version0) && !finals.has(r.version)).map((r) => r.number);
|
|
2204
2223
|
const trackingOut = tracking && !tracking.error
|
|
2205
|
-
? { number: tracking.number || null, url: tracking.url || null, created: trackingCreated && (!cand || cand.version === version0), held: !!tracking.held, supersededHeld }
|
|
2224
|
+
? { number: tracking.number || null, url: tracking.url || null, title: tracking.title || null, created: trackingCreated && (!cand || cand.version === version0), held: !!tracking.held, supersededHeld }
|
|
2206
2225
|
: null;
|
|
2207
2226
|
// #468: why this run made no final, and which candidate finals first — the line the release
|
|
2208
2227
|
// workflow prints, so "no final" never has to be reconstructed from a checklist.
|
|
@@ -3792,7 +3811,8 @@ It is minted only when ALL of these hold, checked before any network call:
|
|
|
3792
3811
|
- the record is well-formed AND passing (approve · checklist pass · escalation clear · CI pass) —
|
|
3793
3812
|
a grant carrying a failing review is a contradiction, so it is refused, not recorded;
|
|
3794
3813
|
- the branch is pushed, and --head (if given) equals origin's tip — the grant binds that tip;
|
|
3795
|
-
- this checkout's project.yml
|
|
3814
|
+
- the policy resolves to \`reviewer\` (#596): this checkout's project.yml \`migration-grant:\` when
|
|
3815
|
+
declared (#398), else the owner-level value (\`colab owner-policy\`), else human;
|
|
3796
3816
|
- checklist-items, when given, is <passed>/${migrationGrant.REVIEW_CHECKLIST_ITEMS} and, with checklist pass, every item
|
|
3797
3817
|
passed (#457) — the record counts against the checklist the migration-review skill walks today.
|
|
3798
3818
|
Then, read from CI after the tracker read and before anything is written (#457):
|
|
@@ -3800,8 +3820,8 @@ Then, read from CI after the tracker read and before anything is written (#457):
|
|
|
3800
3820
|
passed there (the rule ship applies), and --ci-run, when given, is one of the runs at that
|
|
3801
3821
|
head and carries the job. A repo whose CI has no such job cannot mint a reviewer grant at all.
|
|
3802
3822
|
COLAB_HUMAN=1 is still required for every role. The reviewer identity is DECLARED, not attested.
|
|
3803
|
-
\`colab ship\` honours a reviewer grant only when ALL of (#401): P the target
|
|
3804
|
-
|
|
3823
|
+
\`colab ship\` honours a reviewer grant only when ALL of (#401): P the policy at the target resolves to
|
|
3824
|
+
reviewer (its project.yml key, else the owner-level value, else human — #596) · M this record is live, trusted and passing · HEAD its head is the
|
|
3805
3825
|
branch's exact remote head, or its \`migrations\` id equals the id at that head · R the live
|
|
3806
3826
|
"${migrationGrant.ROUNDTRIP_JOB_PREFIX}" CI job passed on the SHIPPED head (re-read by ship, never
|
|
3807
3827
|
taken from the record). Any condition failing → a human runs Phase B.
|
|
@@ -3906,11 +3926,21 @@ function migrationGrantReviewRecord(repoAbs, opts) {
|
|
|
3906
3926
|
|
|
3907
3927
|
// Policy first: under the default (human) a reviewer grant would do nothing and mislead. Read from
|
|
3908
3928
|
// THIS checkout (trunk at rest), never the branch — a branch must not raise its own grant policy.
|
|
3909
|
-
|
|
3929
|
+
// #596: three levels — this checkout's key > the owner-level value > human. The owner record is
|
|
3930
|
+
// read only when the repo key is absent or `human` (the opt-out case needs it to say so).
|
|
3931
|
+
const mintDoc = projectDoc(repoAbs);
|
|
3932
|
+
const pol = migrationGrantPolicyFor(repoAbs, mintDoc, trustHumans.parseTrustHumans(mintDoc));
|
|
3910
3933
|
if (!pol.valid) throw new UserError(`${pol.reason} — fix project.yml before minting a reviewer grant`);
|
|
3911
3934
|
if (pol.policy !== 'reviewer') {
|
|
3935
|
+
if (pol.optedOut) {
|
|
3936
|
+
throw new UserError(`${pol.reason} — no reviewer grant is minted here. A human grant still works: \`COLAB_HUMAN=1 colab migration-grant <N> --branch <branch>\``);
|
|
3937
|
+
}
|
|
3938
|
+
if (pol.ownerNote) {
|
|
3939
|
+
throw new UserError(`this repo's migration-grant policy is "${pol.policy}" (absent = human), and ${pol.ownerNote} — re-run once \`colab owner-policy show\` reads it`);
|
|
3940
|
+
}
|
|
3912
3941
|
throw new UserError(`this repo's migration-grant policy is "${pol.policy}"${pol.declared ? '' : ' (absent = human)'} — a reviewer grant is minted only where project.yml declares migration-grant: reviewer`);
|
|
3913
3942
|
}
|
|
3943
|
+
opts.policyResolved = pol;
|
|
3914
3944
|
|
|
3915
3945
|
// HEAD binding: the grant covers exactly the commit on origin. An unpushed branch has no tip any
|
|
3916
3946
|
// other machine can check against, so it is refused rather than bound to a local-only sha.
|
|
@@ -4041,6 +4071,7 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
|
|
|
4041
4071
|
print(' Bound to that HEAD: any new commit voids it. It expires the moment the issue closes.');
|
|
4042
4072
|
}
|
|
4043
4073
|
print(` colab ship honours it only while the "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" CI job has passed on that HEAD and the policy still says reviewer.`);
|
|
4074
|
+
if (opts.policyResolved && opts.policyResolved.source === 'owner') print(` Policy source: ${opts.policyResolved.reason}.`);
|
|
4044
4075
|
print(` Revoke any time: colab migration-grant ${num} --revoke`);
|
|
4045
4076
|
return 0;
|
|
4046
4077
|
}
|
|
@@ -4113,9 +4144,16 @@ function cmdMigrationGrantList(opts) {
|
|
|
4113
4144
|
grants.push(row);
|
|
4114
4145
|
}
|
|
4115
4146
|
|
|
4147
|
+
// #596: the policy these grants are judged under, with its source (repo | owner | default).
|
|
4148
|
+
const listDoc = projectDoc(repoAbs);
|
|
4149
|
+
const pol = migrationGrantPolicyFor(repoAbs, listDoc, trustHumans.parseTrustHumans(listDoc));
|
|
4150
|
+
const policy = { value: pol.policy, source: pol.source, optedOut: pol.optedOut,
|
|
4151
|
+
...(pol.source === 'owner' ? { owner: pol.owner, by: pol.ownerBy, at: pol.ownerAt } : {}) };
|
|
4116
4152
|
if (opts.json) {
|
|
4117
|
-
return print(JSON.stringify({ repo: shortRepo(repoAbs), label: labels.MIGRATION_GRANT_LABEL, grants, stale }, null, 2));
|
|
4153
|
+
return print(JSON.stringify({ repo: shortRepo(repoAbs), label: labels.MIGRATION_GRANT_LABEL, policy, grants, stale }, null, 2));
|
|
4118
4154
|
}
|
|
4155
|
+
// Prose names the source only where the owner level is in play — otherwise byte-identical.
|
|
4156
|
+
if (pol.source === 'owner' || pol.optedOut || pol.ownerNote) print(`migration-grant policy: ${pol.policy} (source: ${ownerPolicy.sourceLabel(pol)}) — ${pol.reason}`);
|
|
4119
4157
|
|
|
4120
4158
|
if (grants.length === 0 && stale.length === 0) {
|
|
4121
4159
|
print(`no outstanding migration grants in ${shortRepo(repoAbs)}`);
|
|
@@ -4132,6 +4170,162 @@ function cmdMigrationGrantList(opts) {
|
|
|
4132
4170
|
return 0;
|
|
4133
4171
|
}
|
|
4134
4172
|
|
|
4173
|
+
// ---------------------------------------------------------------------------
|
|
4174
|
+
// owner-policy (#596) — an owner-level `migration-grant` value, set once by a human for every repo
|
|
4175
|
+
// the GitHub owner runs. Record + proof rules: tools/lib/owner-policy.js. This section is gh I/O.
|
|
4176
|
+
// Precedence everywhere: the repo's own key > the owner value > human.
|
|
4177
|
+
|
|
4178
|
+
const HELP_OWNER_POLICY = `colab owner-policy [show] [--json] [--repo <path>]
|
|
4179
|
+
COLAB_HUMAN=1 colab owner-policy set migration-grant <human|reviewer|unset> [--repo <path>]
|
|
4180
|
+
|
|
4181
|
+
The owner-level grant policy (#596): ONE value for every repo the GitHub owner runs, so a new repo
|
|
4182
|
+
does not silently start at \`human\` and the owner does not land one project.yml commit per repo.
|
|
4183
|
+
|
|
4184
|
+
Precedence (read by \`colab migration-grant\` when minting and \`colab ship\` when gating):
|
|
4185
|
+
1. the repo's own \`migration-grant:\` in project.yml — \`human\` there opts the repo out
|
|
4186
|
+
2. the owner-level value set here
|
|
4187
|
+
3. the default, \`human\`
|
|
4188
|
+
|
|
4189
|
+
Where it lives: marker comments on the open \`${ownerPolicy.LABEL}\`-labelled issue in the owner's
|
|
4190
|
+
\`${ownerPolicy.RECORD_REPO}\` repo (<owner>/${ownerPolicy.RECORD_REPO}). The latest marker per key whose author
|
|
4191
|
+
is the owner or an org MEMBER — and, where the judged repo declares trust-humans, a listed login —
|
|
4192
|
+
wins. A marker from anyone else is ignored and shown here, never honoured.
|
|
4193
|
+
|
|
4194
|
+
show print the owner value, who set it and when, and what THIS repo resolves to
|
|
4195
|
+
set K V post a new marker. Human-only: refused without COLAB_HUMAN=1, exit 1. Never
|
|
4196
|
+
reachable through \`colab config set\` — migration-grant stays an authority key there.
|
|
4197
|
+
\`unset\` withdraws the owner value. The ${ownerPolicy.RECORD_REPO} repo must exist —
|
|
4198
|
+
colab never creates a repo; the issue and label are created on the first set.
|
|
4199
|
+
|
|
4200
|
+
Only \`migration-grant\` is an owner-level key today. Nothing else about a reviewer grant changes:
|
|
4201
|
+
review record, CI round-trip job, HEAD binding and revoke are exactly as before.
|
|
4202
|
+
`;
|
|
4203
|
+
|
|
4204
|
+
/** The `<owner>/.github` REST paths, with gh's {owner} placeholder — resolved from the repo's remote. */
|
|
4205
|
+
function ownerRecordPath(rest) { return `repos/{owner}/${ownerPolicy.RECORD_REPO}/${rest}`; }
|
|
4206
|
+
|
|
4207
|
+
function ghFirstLine(s) { return String(s || '').trim().split('\n')[0] || 'gh failed'; }
|
|
4208
|
+
|
|
4209
|
+
/**
|
|
4210
|
+
* Locate the owner record issue. Returns { read: 'ok', issue, owner } · { read: 'none', owner? }
|
|
4211
|
+
* (no .github repo, or no labelled open issue — "nothing set", never an error) · { read: 'unread', why }.
|
|
4212
|
+
*/
|
|
4213
|
+
function ownerRecordIssue(repoAbs) {
|
|
4214
|
+
const r = git.ghApi(repoAbs, [ownerRecordPath(`issues?labels=${ownerPolicy.LABEL}&state=open&per_page=100`)]);
|
|
4215
|
+
if (!r.ok) {
|
|
4216
|
+
if (/HTTP 404|Not Found/i.test(r.stderr || '')) return { read: 'none', owner: null, why: `no ${ownerPolicy.RECORD_REPO} repo for this owner` };
|
|
4217
|
+
return { read: 'unread', why: ghFirstLine(r.stderr) };
|
|
4218
|
+
}
|
|
4219
|
+
let list;
|
|
4220
|
+
try { list = JSON.parse(r.stdout); } catch (_) { return { read: 'unread', why: 'unparseable issue list' }; }
|
|
4221
|
+
const issues = (Array.isArray(list) ? list : []).filter((i) => i && !i.pull_request).sort((a, b) => a.number - b.number);
|
|
4222
|
+
if (issues.length === 0) return { read: 'none', owner: null, why: `no open ${ownerPolicy.LABEL} issue` };
|
|
4223
|
+
const m = String(issues[0].repository_url || '').match(/\/repos\/([^/]+)\//);
|
|
4224
|
+
return { read: 'ok', issue: issues[0].number, owner: m ? m[1] : null };
|
|
4225
|
+
}
|
|
4226
|
+
|
|
4227
|
+
/**
|
|
4228
|
+
* #596: the owner-level value for `key`, judged with the reading repo's `trust`. Returns the shape
|
|
4229
|
+
* owner-policy.js resolveGrantPolicy takes: { read, owner, issue, set, value, by, at, ignored, why }.
|
|
4230
|
+
*/
|
|
4231
|
+
function ownerPolicyRead(repoAbs, trust, key = 'migration-grant') {
|
|
4232
|
+
const loc = ownerRecordIssue(repoAbs);
|
|
4233
|
+
if (loc.read !== 'ok') return { ...loc, set: false, value: null, ignored: [] };
|
|
4234
|
+
const c = git.ghApi(repoAbs, ['--paginate', ownerRecordPath(`issues/${loc.issue}/comments?per_page=100`),
|
|
4235
|
+
'--jq', '.[] | {user: {login: .user.login}, author_association, created_at, body}']);
|
|
4236
|
+
if (!c.ok) return { read: 'unread', why: ghFirstLine(c.stderr), set: false, value: null, ignored: [] };
|
|
4237
|
+
const comments = [];
|
|
4238
|
+
for (const line of c.stdout.split('\n')) {
|
|
4239
|
+
if (!line.trim()) continue;
|
|
4240
|
+
try { comments.push(JSON.parse(line)); } catch (_) { return { read: 'unread', why: 'unparseable comment list', set: false, value: null, ignored: [] }; }
|
|
4241
|
+
}
|
|
4242
|
+
return { read: 'ok', owner: loc.owner, issue: loc.issue, ...ownerPolicy.ownerValue(comments, key, trust) };
|
|
4243
|
+
}
|
|
4244
|
+
|
|
4245
|
+
/**
|
|
4246
|
+
* #596: the migration-grant policy for a repo, three levels. `doc` is the project.yml that counts
|
|
4247
|
+
* (the trunk checkout for a mint, the merge target for ship). The owner record is read only when the
|
|
4248
|
+
* repo key is absent or a valid `human` — a declared reviewer needs no lookup.
|
|
4249
|
+
*/
|
|
4250
|
+
function migrationGrantPolicyFor(repoAbs, doc, trust) {
|
|
4251
|
+
const repoPol = migrationGrant.parseGrantPolicy(doc);
|
|
4252
|
+
const needOwner = !repoPol.declared || (repoPol.valid && repoPol.policy === 'human');
|
|
4253
|
+
return ownerPolicy.resolveGrantPolicy(repoPol, needOwner ? ownerPolicyRead(repoAbs, trust) : null);
|
|
4254
|
+
}
|
|
4255
|
+
|
|
4256
|
+
function cmdOwnerPolicy(argv) {
|
|
4257
|
+
const opts = parseArgs(argv, {
|
|
4258
|
+
values: { '--repo': 'repo' },
|
|
4259
|
+
flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
|
|
4260
|
+
});
|
|
4261
|
+
if (opts.help) return print(HELP_OWNER_POLICY);
|
|
4262
|
+
const sub = opts._[0] || 'show';
|
|
4263
|
+
if (sub === 'set') {
|
|
4264
|
+
// HUMAN-ONLY, first — before resolveRepo or any gh call. Same bar as minting a grant.
|
|
4265
|
+
if (process.env.COLAB_HUMAN !== '1') {
|
|
4266
|
+
process.stderr.write('✗ Refusing: setting the owner-level grant policy requires a human.\n');
|
|
4267
|
+
process.stderr.write(' Re-run with COLAB_HUMAN=1. (No field, flag or config value can lower this bar.)\n');
|
|
4268
|
+
return 1;
|
|
4269
|
+
}
|
|
4270
|
+
const [, key, value] = opts._;
|
|
4271
|
+
if (!ownerPolicy.KEYS.includes(key)) throw new UserError(`owner-policy set: key ${JSON.stringify(key)} — expected one of ${ownerPolicy.KEYS.join(' | ')}`);
|
|
4272
|
+
if (!ownerPolicy.isValidValue(key, value)) throw new UserError(`owner-policy set ${key}: value ${JSON.stringify(value)} — expected one of ${[...ownerPolicy.VALUES[key], ownerPolicy.UNSET].join(' | ')}`);
|
|
4273
|
+
const repoAbs = resolveRepoOrCwd(opts);
|
|
4274
|
+
if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
|
|
4275
|
+
if (!isGhUsable(repoAbs)) throw new UserError(`gh not usable here (${ghUnusableWhy(repoAbs)}) — the owner policy lives on the tracker`);
|
|
4276
|
+
return cmdOwnerPolicySet(repoAbs, key, value);
|
|
4277
|
+
}
|
|
4278
|
+
if (sub !== 'show') throw new UserError(`unknown owner-policy subcommand "${sub}" — expected one of show | set`);
|
|
4279
|
+
const repoAbs = resolveRepoOrCwd(opts);
|
|
4280
|
+
if (!repoAbs) throw new UserError('not inside a git repo — pass --repo <path>');
|
|
4281
|
+
if (!isGhUsable(repoAbs)) throw new UserError(`gh not usable here (${ghUnusableWhy(repoAbs)}) — the owner policy lives on the tracker`);
|
|
4282
|
+
const doc = projectDoc(repoAbs);
|
|
4283
|
+
const trust = trustHumans.parseTrustHumans(doc);
|
|
4284
|
+
const owner = ownerPolicyRead(repoAbs, trust);
|
|
4285
|
+
const res = ownerPolicy.resolveGrantPolicy(migrationGrant.parseGrantPolicy(doc), owner);
|
|
4286
|
+
const out = {
|
|
4287
|
+
repo: shortRepo(repoAbs),
|
|
4288
|
+
owner: { read: owner.read, owner: owner.owner || null, issue: owner.issue || null, why: owner.why || null,
|
|
4289
|
+
'migration-grant': owner.set ? { value: owner.value, by: owner.by, at: owner.at } : null, ignored: owner.ignored || [] },
|
|
4290
|
+
resolved: { 'migration-grant': { policy: res.policy, source: res.source, valid: res.valid, optedOut: res.optedOut, reason: res.reason } },
|
|
4291
|
+
};
|
|
4292
|
+
if (opts.json) return print(JSON.stringify(out, null, 2));
|
|
4293
|
+
const where = owner.owner ? `${owner.owner}/${ownerPolicy.RECORD_REPO}#${owner.issue}` : `<owner>/${ownerPolicy.RECORD_REPO}`;
|
|
4294
|
+
if (owner.read === 'unread') warn(`could not read the owner record (${owner.why}) — read as unset`);
|
|
4295
|
+
print(`owner-level migration-grant: ${owner.set ? `${owner.value} — set by ${owner.by} at ${owner.at} (${where})` : `not set (${owner.why || where})`}`);
|
|
4296
|
+
for (const i of owner.ignored || []) warn(`ignored marker ${i.value} by ${i.login || '(unknown)'} at ${i.at}: ${i.reason}`);
|
|
4297
|
+
print(`${shortRepo(repoAbs)} resolves to: ${res.policy} (source: ${ownerPolicy.sourceLabel(res)}) — ${res.reason}`);
|
|
4298
|
+
return 0;
|
|
4299
|
+
}
|
|
4300
|
+
|
|
4301
|
+
function cmdOwnerPolicySet(repoAbs, key, value) {
|
|
4302
|
+
let loc = ownerRecordIssue(repoAbs);
|
|
4303
|
+
if (loc.read === 'unread') throw new UserError(`could not read the owner record (${loc.why}) — nothing was posted; re-run once \`colab owner-policy show\` reads it`);
|
|
4304
|
+
if (loc.read === 'none') {
|
|
4305
|
+
// Is the .github repo there at all? colab never creates a repo — that is the owner's call.
|
|
4306
|
+
const repoR = git.ghApi(repoAbs, [`repos/{owner}/${ownerPolicy.RECORD_REPO}`, '--jq', '.full_name']);
|
|
4307
|
+
if (!repoR.ok) {
|
|
4308
|
+
throw new UserError(`the owner has no ${ownerPolicy.RECORD_REPO} repo (${ghFirstLine(repoR.stderr)}) — nothing was posted. colab never creates a repo: the owner must create <owner>/${ownerPolicy.RECORD_REPO} (GitHub's owner-wide defaults repo), then re-run`);
|
|
4309
|
+
}
|
|
4310
|
+
git.ghApi(repoAbs, ['-X', 'POST', `repos/{owner}/${ownerPolicy.RECORD_REPO}/labels`, '-f', `name=${ownerPolicy.LABEL}`,
|
|
4311
|
+
'-f', 'color=5319E7', '-f', 'description=colab owner-level policy record (#596) — human-set markers only']);
|
|
4312
|
+
const body = 'The owner-level colab policy record. Each value is a marker comment posted by `COLAB_HUMAN=1 colab owner-policy set`; ' +
|
|
4313
|
+
'the latest one from the owner or an org member wins. Do not close this issue — closing it withdraws every owner value.';
|
|
4314
|
+
const created = git.ghApi(repoAbs, ['-X', 'POST', `repos/{owner}/${ownerPolicy.RECORD_REPO}/issues`, '-f', `title=${ownerPolicy.ISSUE_TITLE}`,
|
|
4315
|
+
'-f', `body=${body}`, '-f', `labels[]=${ownerPolicy.LABEL}`, '--jq', '.number']);
|
|
4316
|
+
if (!created.ok) throw new UserError(`could not create the owner record issue (${ghFirstLine(created.stderr)}) — nothing was posted; check write access with \`gh auth status\`, then re-run`);
|
|
4317
|
+
loc = { read: 'ok', issue: Number(created.stdout.trim()), owner: null };
|
|
4318
|
+
}
|
|
4319
|
+
const iso = nowISO();
|
|
4320
|
+
const c = git.ghApi(repoAbs, ['-X', 'POST', ownerRecordPath(`issues/${loc.issue}/comments`),
|
|
4321
|
+
'-f', `body=${ownerPolicy.markerBody(key, value, commentHost(repoAbs), iso)}`]);
|
|
4322
|
+
if (!c.ok) throw new UserError(`could not post the owner policy marker (${ghFirstLine(c.stderr)}) — nothing changed; check write access with \`gh auth status\`, then re-run`);
|
|
4323
|
+
print(`Recorded owner-level ${key}: ${value} on ${loc.owner ? `${loc.owner}/` : '<owner>/'}${ownerPolicy.RECORD_REPO}#${loc.issue} at ${iso}.`);
|
|
4324
|
+
print(` Repos that declare their own ${key}: are unaffected; \`${key}: human\` in a repo opts it out.`);
|
|
4325
|
+
print(' Check what a repo resolves to: colab owner-policy show');
|
|
4326
|
+
return 0;
|
|
4327
|
+
}
|
|
4328
|
+
|
|
4135
4329
|
// ---------------------------------------------------------------------------
|
|
4136
4330
|
// decision (#121, #122) — record a human's answer to a blocking `needs-decision` question as a
|
|
4137
4331
|
// POSITIVE, machine-readable act, never as the label's mere absence. See tools/lib/decision-
|
|
@@ -4169,8 +4363,14 @@ TRUSTED_ASSOCIATIONS, checked on read. Same principle, a different mechanism, be
|
|
|
4169
4363
|
command TRANSCRIBES a decision made elsewhere rather than AUTHORIZING a write that did not exist
|
|
4170
4364
|
before it ran — the flag would assert nothing here that \`--ruled-by\` does not already.
|
|
4171
4365
|
|
|
4172
|
-
\`--answers <ref>\` names the
|
|
4173
|
-
|
|
4366
|
+
\`--answers <ref>\` names the question this decision resolves: an ASK ID (the \`id=\` of an open
|
|
4367
|
+
\`<!-- <tool>:ask id=<id> v=<n> -->\` record a dashboard that tracks asks wrote on the issue), or the
|
|
4368
|
+
\`<!-- decision:options -->\` comment (id or URL). Omit it only when there is neither. --record
|
|
4369
|
+
reads the issue's open asks first (#582) — an ask with no answer record, and no ⚖ record
|
|
4370
|
+
naming it, after its latest version: with ONE open ask and no --answers it prints the ask id
|
|
4371
|
+
and the exact re-run line, and says the ruling will be read as answering that ask; with TWO OR
|
|
4372
|
+
MORE it REFUSES before any write and lists every id, because a nameless ruling cannot say which
|
|
4373
|
+
one it settles.
|
|
4174
4374
|
|
|
4175
4375
|
Reopening removes \`${labels.DECISION_RECORDED_LABEL}\`, re-applies \`${labels.NEEDS_DECISION_LABEL}\`,
|
|
4176
4376
|
and posts a \`${decisionRecord.REOPEN_MARK}\` receipt — every decision on that issue up to this
|
|
@@ -4199,7 +4399,7 @@ Options:
|
|
|
4199
4399
|
and an issue number is present, for the common one-shot case)
|
|
4200
4400
|
--reopen reopen an existing decision instead of recording a new one
|
|
4201
4401
|
--ruled-by <name> required for --record/--reopen — who made this call, never the typist
|
|
4202
|
-
--answers <ref> (--record only) the decision:options comment this answers
|
|
4402
|
+
--answers <ref> (--record only) the open ask id, or the decision:options comment, this answers
|
|
4203
4403
|
--body-file <f> ruling prose (or reopen reason) to append below the marker line
|
|
4204
4404
|
--list list every issue with a live decision right now, instead of recording
|
|
4205
4405
|
--json (with --list) machine-readable output
|
|
@@ -4291,6 +4491,23 @@ function cmdDecisionRecord(repoAbs, num, opts, body) {
|
|
|
4291
4491
|
${pair.fix}`);
|
|
4292
4492
|
}
|
|
4293
4493
|
|
|
4494
|
+
// #582: show the recorder the asks still waiting on this issue, so the ruling names the one it
|
|
4495
|
+
// settles. One open ask + no --answers: a consumer reads the ruling as answering it — say so.
|
|
4496
|
+
// Two or more + no --answers: ambiguous, refuse before any write (same posture as the pair
|
|
4497
|
+
// check above) and list the ids.
|
|
4498
|
+
const asks = decisionRecord.openAsks(info.comments);
|
|
4499
|
+
const shellQuote = (v) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(String(v)) ? String(v) : `'${String(v).replace(/'/g, `'\\''`)}'`);
|
|
4500
|
+
if (asks.length > 0 && !opts.answers) {
|
|
4501
|
+
const rerun = (id) => `colab decision ${num} --record --ruled-by ${shellQuote(opts.ruledBy)} --answers ${shellQuote(id)}${opts.bodyFile ? ` --body-file ${shellQuote(opts.bodyFile)}` : ''}`;
|
|
4502
|
+
const rows = asks.map((a) => ` ${a.id} (v${a.version}, asked ${a.at || 'unknown'})\n ${rerun(a.id)}`).join('\n');
|
|
4503
|
+
if (asks.length > 1) {
|
|
4504
|
+
throw new UserError(`#${num} has ${asks.length} open asks and this record names none — a reader cannot tell which one the ruling settles. Re-run with --answers <ask id>:
|
|
4505
|
+
${rows}`);
|
|
4506
|
+
}
|
|
4507
|
+
warn(`#${num} has one open ask: ${asks[0].id} (v${asks[0].version}, asked ${asks[0].at || 'unknown'}). This ruling will be read as answering it. To name it explicitly, re-run as:
|
|
4508
|
+
${rerun(asks[0].id)}`);
|
|
4509
|
+
}
|
|
4510
|
+
|
|
4294
4511
|
const present = git.ghListLabels(repoAbs);
|
|
4295
4512
|
if (present && !present.includes(labels.DECISION_RECORDED_LABEL)) {
|
|
4296
4513
|
throw new UserError(labels.decisionRecordedMissingLabelHint(present)
|
|
@@ -4474,7 +4691,8 @@ CI grant merges into a repo whose own test suite is known-failing:
|
|
|
4474
4691
|
for the BRANCH's own current head (the same "ask by sha" check \`ship\` itself uses) — a human's
|
|
4475
4692
|
say-so alone is never enough. \`--evidence-run\` is a RECORDING-ONLY pointer for the audit trail;
|
|
4476
4693
|
it can never substitute for the measured run. If the branch has no run yet, open a PR for it
|
|
4477
|
-
(\`gh pr create\`) and let CI finish, then re-run this command.
|
|
4694
|
+
(\`gh pr create\`) and let CI finish, then re-run this command. You do not need to close that
|
|
4695
|
+
PR afterwards: \`colab ship\` closes it once the branch lands (#584).
|
|
4478
4696
|
2. NEVER STACKS. Creating a grant refuses outright if trunk is not currently red (nothing to
|
|
4479
4697
|
exempt), and refuses again if a PRIOR ci-grant already merged something and trunk has been red
|
|
4480
4698
|
continuously since — a second exemption on a still-broken repo is exactly the failure this gate
|
|
@@ -4823,7 +5041,7 @@ function cmdCiGrantCreate(repoAbs, num, opts) {
|
|
|
4823
5041
|
throw new UserError(
|
|
4824
5042
|
`"${opts.branch}" has no completed, successful CI run for its current head (${shortSha(evRun.sha)}) — ` +
|
|
4825
5043
|
`a CI grant requires MEASURED evidence, never a human's say-so alone. Open a PR for it ` +
|
|
4826
|
-
`(\`gh pr create\`) and let CI finish, then re-run this command.`);
|
|
5044
|
+
`(\`gh pr create\`) and let CI finish, then re-run this command — \`colab ship\` closes that PR once the branch lands (#584).`);
|
|
4827
5045
|
}
|
|
4828
5046
|
const evidenceSha = evRun.sha;
|
|
4829
5047
|
|
|
@@ -6290,6 +6508,9 @@ in a cleanup cron.
|
|
|
6290
6508
|
reported but never deleted (a label a triage session just created and has not
|
|
6291
6509
|
applied yet is indistinguishable from one whose members were all transferred
|
|
6292
6510
|
away — the labels API exposes no creation time, so a human decides).
|
|
6511
|
+
Also lists open PRs whose head commit already landed in trunk (#584) — CI-trigger
|
|
6512
|
+
PRs a squash ship left open. Report-only, --prune included: doctor never closes
|
|
6513
|
+
a PR. A PR whose head is not in the local clone is not judged.
|
|
6293
6514
|
`;
|
|
6294
6515
|
|
|
6295
6516
|
const EMPTY_SET = new Set();
|
|
@@ -6374,7 +6595,7 @@ function cmdDoctor(argv) {
|
|
|
6374
6595
|
const report = { deadWorktrees: [], orphanClaims: [], staleClaims: [], stalePlaces: [], unprovablePlaces: [], releasedPlaces: [], orphanPorts: [], brokenRecords: [], prunedPorts: [],
|
|
6375
6596
|
renamedHostRecords: [], unprovenHostRecords: [],
|
|
6376
6597
|
mergedFlips: [], mergedSweep: [], mergedDirty: [], mergedHookFail: [], mergedRemoveFail: [], shippedBranches: [], ghostPorts: [],
|
|
6377
|
-
spentGroupLabels: [], groupLabelsChecked: !!opts.sync, pruned: !!opts.prune };
|
|
6598
|
+
spentGroupLabels: [], groupLabelsChecked: !!opts.sync, landedPrs: [], landedPrsUnread: [], pruned: !!opts.prune };
|
|
6378
6599
|
|
|
6379
6600
|
// One answer per (repo, branch) — pass 5b asks about the same branch from a worktree and from each
|
|
6380
6601
|
// of its claims, and every miss costs two `git rev-parse` calls.
|
|
@@ -6765,6 +6986,28 @@ function cmdDoctor(argv) {
|
|
|
6765
6986
|
}
|
|
6766
6987
|
}
|
|
6767
6988
|
|
|
6989
|
+
// 9b. open PRs whose head already landed (#584) — the CI-trigger PRs a squash ship left open before
|
|
6990
|
+
// ship learned to close them, or that a ship on another machine could not close. Report-only,
|
|
6991
|
+
// --prune included: closing a PR is a write on a shared forge, and a human may still want it.
|
|
6992
|
+
// Behind --sync for the same reason as pass 9 (network). A PR whose head commit is not in this
|
|
6993
|
+
// clone is not judged — the answer would be a guess — so the list is honest, not exhaustive.
|
|
6994
|
+
if (opts.sync && git.ghAvailable()) {
|
|
6995
|
+
const repos = [...new Set([...(config.repos || []), ...knownRepos(config)].map((r) => path.resolve(r)))]
|
|
6996
|
+
.filter((r) => repoLive(r) && git.remoteUrl(r));
|
|
6997
|
+
for (const repo of repos) {
|
|
6998
|
+
const trunk = resolveTrunk(repo, projectDoc(repo));
|
|
6999
|
+
if (!trunk) continue;
|
|
7000
|
+
const listed = git.ghOpenPrs(repo);
|
|
7001
|
+
if (listed.error) { report.landedPrsUnread.push({ repo: shortRepo(repo), error: listed.error }); continue; }
|
|
7002
|
+
for (const pr of listed.prs) {
|
|
7003
|
+
if (!pr.headRefOid || pr.headRefName === trunk) continue;
|
|
7004
|
+
if (!git.git(['cat-file', '-e', `${pr.headRefOid}^{commit}`], repo).ok) continue;
|
|
7005
|
+
if (landed.landedState(repo, trunk, pr.headRefOid).state !== 'landed') continue;
|
|
7006
|
+
report.landedPrs.push({ repo: shortRepo(repo), number: pr.number, url: pr.url || '', branch: pr.headRefName || '', trunk });
|
|
7007
|
+
}
|
|
7008
|
+
}
|
|
7009
|
+
}
|
|
7010
|
+
|
|
6768
7011
|
// 10. notifyUrl against a DECLARED local observer (#414). Read-only, never pruned, never counted in
|
|
6769
7012
|
// the verdict — it is configuration, not state drift. Silent on a machine with no
|
|
6770
7013
|
// <COLAB_HOME>/notify-endpoint: unset is the right default where no observer runs.
|
|
@@ -6914,6 +7157,17 @@ function cmdDoctor(argv) {
|
|
|
6914
7157
|
print(' NOT exhaustive: a branch whose work trunk later rewrote can conflict against trunk');
|
|
6915
7158
|
print(' instead of matching it, and is omitted here rather than risk calling unmerged work spent.');
|
|
6916
7159
|
}
|
|
7160
|
+
// #584 — after the verdict, not counted: an open PR on a landed branch breaks nothing, it reads as
|
|
7161
|
+
// unmerged work on a tracker. Printed only under --sync.
|
|
7162
|
+
if (report.landedPrs.length) {
|
|
7163
|
+
print('');
|
|
7164
|
+
print(`Open PRs whose branch already landed (${report.landedPrs.length}) — the squash left them open:`);
|
|
7165
|
+
for (const p of report.landedPrs) print(` #${p.number} ${p.branch} [${p.repo}] → in ${p.trunk}${p.url ? ` ${p.url}` : ''}`);
|
|
7166
|
+
print(' `colab ship` closes these itself since #584; these predate that, or a ship could not close them.');
|
|
7167
|
+
print(' doctor never closes a PR, --prune included. To close one:');
|
|
7168
|
+
print(` gh pr close ${report.landedPrs[0].number} --comment "Landed on ${report.landedPrs[0].trunk} by squash." # in ${report.landedPrs[0].repo}`);
|
|
7169
|
+
}
|
|
7170
|
+
for (const u of report.landedPrsUnread) warn(`could not list open PRs in ${u.repo} (${u.error}) — landed-PR check skipped there`);
|
|
6917
7171
|
// Also after the verdict, and also not drift: a spent group label breaks nothing, it is picker
|
|
6918
7172
|
// noise on a tracker. Printed only under --sync, so silence here NEVER means "checked, clean" —
|
|
6919
7173
|
// which is why a --sync run that finds nothing says so explicitly below.
|
|
@@ -9302,6 +9556,10 @@ prepended at the top for a *.yml/*.yaml copy, since there is no shebang to prote
|
|
|
9302
9556
|
opens with a \`#!\` shebang (a *.mjs template) gets the same stamp on its SECOND line instead —
|
|
9303
9557
|
using \`//\` there, since a bare \`#\` on any other line is a JS syntax error — so the shebang
|
|
9304
9558
|
still has to be line 1 for the file to run.
|
|
9559
|
+
A ci-* template is also written with this repo's protected refs (#526): the template names
|
|
9560
|
+
\`main\`/\`dev\` in concurrency and the dedupe guard; the copy names the \`trunk:\` declared in
|
|
9561
|
+
.github/project.yml (plus \`main\` where a promotion into main releases), and says what it wrote.
|
|
9562
|
+
It then lists the repo's other workflows that also run on push, for you to keep, merge or delete.
|
|
9305
9563
|
These templates are NEVER called remotely — copy, edit, own. When the audit flags your
|
|
9306
9564
|
copy as behind a changed template, review the diff and re-copy to re-stamp.
|
|
9307
9565
|
`;
|
|
@@ -9391,7 +9649,30 @@ function cmdTemplate(argv) {
|
|
|
9391
9649
|
warn('handbook has no tags yet — stamping @ v0. Tag the handbook, then re-copy to stamp a real version.');
|
|
9392
9650
|
}
|
|
9393
9651
|
|
|
9394
|
-
|
|
9652
|
+
let body = fs.readFileSync(srcFile, 'utf8');
|
|
9653
|
+
// #526: a CI template names its protected refs `main`/`dev` — defaults, not this repo's facts.
|
|
9654
|
+
// Write the repo's declared trunk (and release branch) instead, and say what changed.
|
|
9655
|
+
const trunkNotes = [];
|
|
9656
|
+
let repoForCopy = null;
|
|
9657
|
+
if (ext === 'yml') {
|
|
9658
|
+
try { repoForCopy = git.repoRoot(path.dirname(destFile)) || resolveWorkingRepo(opts); } catch (_) { repoForCopy = null; }
|
|
9659
|
+
}
|
|
9660
|
+
if (ext === 'yml' && /^ci-/.test(stem)) {
|
|
9661
|
+
const tt = require('./lib/template-trunk');
|
|
9662
|
+
let doc = null;
|
|
9663
|
+
if (repoForCopy) doc = repoDescriptorDoc(repoForCopy);
|
|
9664
|
+
const p = tt.protectedRefs(doc);
|
|
9665
|
+
if (!p) {
|
|
9666
|
+
trunkNotes.push(' trunk: no `trunk:` in .github/project.yml — the template\'s main/dev refs are left as is; walk its # EDIT: markers.');
|
|
9667
|
+
} else {
|
|
9668
|
+
const r = tt.substituteTrunk(body, p);
|
|
9669
|
+
body = r.text;
|
|
9670
|
+
trunkNotes.push(r.changes.length
|
|
9671
|
+
? ` trunk: wrote ${p.refs.join(', ')} (from .github/project.yml) into: ${r.changes.join(', ')}.`
|
|
9672
|
+
: ` trunk: ${p.refs.join(', ')} — the template's refs already match .github/project.yml.`);
|
|
9673
|
+
if (r.missed.length) trunkNotes.push(` ⚠ trunk: not found in this template, check by hand: ${r.missed.join(', ')}.`);
|
|
9674
|
+
}
|
|
9675
|
+
}
|
|
9395
9676
|
// A *.yml copy has no shebang to protect, so this is still a plain prepend at line 1 — unchanged
|
|
9396
9677
|
// from before. A *.mjs copy opens with `#!/usr/bin/env node`; insertStamp puts the stamp on line
|
|
9397
9678
|
// 2 instead so the shebang stays first and the file keeps running as a script (#252).
|
|
@@ -9405,6 +9686,23 @@ function cmdTemplate(argv) {
|
|
|
9405
9686
|
// extension) is exactly how a stem collision reads back as a false confirmation (#252).
|
|
9406
9687
|
print(`✓ ${stem}.${ext} @ ${version} → ${destFile}`);
|
|
9407
9688
|
print(' stamped. Walk its # EDIT: markers, declare your toolchain, then commit. You own this file now.');
|
|
9689
|
+
for (const l of trunkNotes) print(l);
|
|
9690
|
+
// #526: a repo adopting a CI template usually has CI already. Both then run on every push —
|
|
9691
|
+
// name them and leave the choice to the person, never decide it here.
|
|
9692
|
+
if (ext === 'yml' && /^ci-/.test(stem) && repoForCopy) {
|
|
9693
|
+
const wfDir = path.join(repoForCopy, '.github', 'workflows');
|
|
9694
|
+
let others = [];
|
|
9695
|
+
try {
|
|
9696
|
+
const wt = require('./lib/workflow-triggers');
|
|
9697
|
+
others = fs.readdirSync(wfDir)
|
|
9698
|
+
.filter((f) => /\.ya?ml$/.test(f) && path.join(wfDir, f) !== destFile)
|
|
9699
|
+
.filter((f) => { const on = wt.parseWorkflowOn(fs.readFileSync(path.join(wfDir, f), 'utf8')); return on.found && on.events.has('push'); });
|
|
9700
|
+
} catch (_) { others = []; }
|
|
9701
|
+
if (others.length) {
|
|
9702
|
+
print(' Other workflows here also run on push — keep each, merge it into this one, or delete it (your call):');
|
|
9703
|
+
for (const f of others) print(` .github/workflows/${f}`);
|
|
9704
|
+
}
|
|
9705
|
+
}
|
|
9408
9706
|
return 0;
|
|
9409
9707
|
}
|
|
9410
9708
|
|
|
@@ -9475,6 +9773,8 @@ function inspectRepo(entry, ctx) {
|
|
|
9475
9773
|
try { wfs = fs.existsSync(wfDir) ? fs.readdirSync(wfDir).filter((f) => /\.ya?ml$/.test(f)).sort() : []; }
|
|
9476
9774
|
catch (_) { wfs = []; }
|
|
9477
9775
|
|
|
9776
|
+
// #526: a CI copy is written with this repo's refs, so pristine means "as colab template renders it here".
|
|
9777
|
+
const descDoc = repoDescriptorDoc(abs);
|
|
9478
9778
|
for (const wf of wfs) {
|
|
9479
9779
|
const rel = `.github/workflows/${wf}`;
|
|
9480
9780
|
const text = read(rel);
|
|
@@ -9483,6 +9783,7 @@ function inspectRepo(entry, ctx) {
|
|
|
9483
9783
|
const c = stamp.classifyStamped({
|
|
9484
9784
|
root: ctx.handbookRoot, hb: ctx.hb, tmplNames: ctx.tmplNames,
|
|
9485
9785
|
templateName: st.name, stampVersion: st.version, localText: text, comparable: true,
|
|
9786
|
+
render: (body) => require('./lib/template-trunk').renderForRepo(st.name, body, descDoc),
|
|
9486
9787
|
});
|
|
9487
9788
|
artifacts.push({ file: rel, template: st.name, applicable: c.state === 'behind', ...c });
|
|
9488
9789
|
} else {
|
|
@@ -9566,10 +9867,17 @@ function entryLabel(entry) {
|
|
|
9566
9867
|
}
|
|
9567
9868
|
|
|
9568
9869
|
/** Rewrite a behind-but-pristine workflow copy as the current template, freshly stamped. */
|
|
9870
|
+
/** A repo's parsed .github/project.yml, or null when absent or unreadable. */
|
|
9871
|
+
function repoDescriptorDoc(repoAbs) {
|
|
9872
|
+
try { return require('./lib/yaml').parse(fs.readFileSync(path.join(repoAbs, '.github', 'project.yml'), 'utf8')) || {}; }
|
|
9873
|
+
catch (_) { return null; }
|
|
9874
|
+
}
|
|
9875
|
+
|
|
9569
9876
|
function refreshArtifact(repo, art, ctx) {
|
|
9570
9877
|
const src = path.join(ctx.templatesDir, `${art.template}.yml`);
|
|
9571
9878
|
if (!fs.existsSync(src)) return { ok: false, err: `template ${art.template}.yml is not in the handbook` };
|
|
9572
|
-
|
|
9879
|
+
// Rendered exactly as `colab template <name> --force` would write it here (#526).
|
|
9880
|
+
const body = require('./lib/template-trunk').renderForRepo(art.template, fs.readFileSync(src, 'utf8'), repoDescriptorDoc(repo.path));
|
|
9573
9881
|
const dest = path.join(repo.path, art.file);
|
|
9574
9882
|
try {
|
|
9575
9883
|
fs.mkdirSync(path.dirname(dest), { recursive: true });
|
|
@@ -10027,7 +10335,11 @@ function shipMigrationGate(repoAbs, gh, target, branch, issues) {
|
|
|
10027
10335
|
/** P, HEAD and the R thunk for shipMigrationGate. The thunk memoises its one verdict on the ctx
|
|
10028
10336
|
* (`roundtripResult`) so the payload can report what R saw without a second read. */
|
|
10029
10337
|
function shipMigrationCtx(repoAbs, gh, target, branch, migrations) {
|
|
10030
|
-
|
|
10338
|
+
// #596: the target's key > the owner-level value > human. `trust` (the target's trust-humans)
|
|
10339
|
+
// also judges who wrote the owner record.
|
|
10340
|
+
const trust = trustAt(repoAbs, target);
|
|
10341
|
+
const pres = migrationGrantPolicyFor(repoAbs, projectDocAt(repoAbs, target), trust);
|
|
10342
|
+
const policy = pres.policy;
|
|
10031
10343
|
const remote = git.remoteInfo(repoAbs).name || 'origin';
|
|
10032
10344
|
const ls = git.git(['ls-remote', remote, `refs/heads/${branch}`], repoAbs);
|
|
10033
10345
|
const remoteSha = ls.ok ? ((ls.stdout.split('\n')[0] || '').split('\t')[0].trim() || null) : null;
|
|
@@ -10037,10 +10349,12 @@ function shipMigrationCtx(repoAbs, gh, target, branch, migrations) {
|
|
|
10037
10349
|
if (!remoteSha) headNote = `${branch} could not be read on ${remote} — CI cannot have run a HEAD nobody can see`;
|
|
10038
10350
|
else if (localSha && localSha !== remoteSha) headNote = `local ${branch} is ${localSha.slice(0, 7)}, ${remote} is ${remoteSha.slice(0, 7)} — push or pull until they agree`;
|
|
10039
10351
|
else headSha = remoteSha;
|
|
10040
|
-
const trust = trustAt(repoAbs, target);
|
|
10041
10352
|
// #508: what the branch's migration files ARE at the shipped head, for a content-bound grant.
|
|
10042
10353
|
const contentId = headSha ? migrationContentAt(repoAbs, migrations, headSha) : null;
|
|
10043
10354
|
const ctx = { policy, headSha, contentId, headNote, roundtripResult: null, trust,
|
|
10355
|
+
policySource: pres.source, policyRes: pres,
|
|
10356
|
+
// Only where the owner level is in play: the default/repo refusal text stays byte-identical.
|
|
10357
|
+
policyReason: pres.source === 'owner' || pres.optedOut || pres.ownerNote ? pres.reason : null,
|
|
10044
10358
|
labelActors: (n) => git.ghIssueLabelActors(repoAbs, n, labels.MIGRATION_GRANT_LABEL) };
|
|
10045
10359
|
ctx.roundtrip = () => {
|
|
10046
10360
|
const d = git.git(['diff', '--name-only', `${target}...${branch}`], repoAbs);
|
|
@@ -10073,6 +10387,10 @@ function migDetail(migrations, grants, target, branch, ctx) {
|
|
|
10073
10387
|
const payload = {
|
|
10074
10388
|
branch, files: [...migrations],
|
|
10075
10389
|
policy: ctx ? ctx.policy : null,
|
|
10390
|
+
// #596: where the policy came from — repo | owner | default — and, for owner, who set it when.
|
|
10391
|
+
policySource: ctx ? ctx.policySource || null : null,
|
|
10392
|
+
policyOwner: ctx && ctx.policyRes && ctx.policyRes.source === 'owner'
|
|
10393
|
+
? { owner: ctx.policyRes.owner, by: ctx.policyRes.ownerBy, at: ctx.policyRes.ownerAt } : null,
|
|
10076
10394
|
headSha: ctx ? ctx.headSha : null,
|
|
10077
10395
|
contentId: ctx ? ctx.contentId || null : null,
|
|
10078
10396
|
// #407: the human list as read from the TARGET — null when undeclared (association class).
|
|
@@ -10086,7 +10404,9 @@ function migDetail(migrations, grants, target, branch, ctx) {
|
|
|
10086
10404
|
if (grants.ok) {
|
|
10087
10405
|
const by = grants.granted.map((g) => (g.role === 'reviewer' ? `#${g.issue} (reviewer ${g.reviewer} @ ${String(g.head).slice(0, 7)}${g.via === 'content' ? `, migration content ${String(g.migrations).slice(0, 12)} unchanged since` : ''}, CI round-trip passed)` : '#' + g.issue)).join(' ');
|
|
10088
10406
|
const roles = [...new Set(grants.granted.map((g) => g.role || 'human'))].join('+');
|
|
10089
|
-
|
|
10407
|
+
const src = ctx && ctx.policySource === 'owner' && grants.granted.some((g) => g.role === 'reviewer')
|
|
10408
|
+
? ` (policy: ${ownerPolicy.sourceLabel(ctx.policyRes)})` : '';
|
|
10409
|
+
return { text: `${migrations.length} present, exempted by a ${roles} grant on ${by} for branch "${branch}"${src} — ${files}`, payload };
|
|
10090
10410
|
}
|
|
10091
10411
|
// Each missing entry already carries its own specific, actionable reason (evaluateShipSet) —
|
|
10092
10412
|
// report those verbatim rather than just an issue tag, so an operator or a scheduled driver's
|
|
@@ -10221,8 +10541,8 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
|
|
|
10221
10541
|
return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}${progressSuffix}`;
|
|
10222
10542
|
}
|
|
10223
10543
|
|
|
10224
|
-
const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
|
|
10225
|
-
colab ship --batch <b1,b2[
|
|
10544
|
+
const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt | --handoff <comment-url>] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
|
|
10545
|
+
colab ship --batch <b1,b2[,…]> [--split] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
|
|
10226
10546
|
|
|
10227
10547
|
The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
|
|
10228
10548
|
CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
|
|
@@ -10317,6 +10637,26 @@ here, or pass --adopt if it genuinely has no issue — the squash then carries a
|
|
|
10317
10637
|
\`Colab-Adopted: origin/<br> @ <sha> on <host> (machine <id>)\` trailer. A LOCAL no-digit branch is
|
|
10318
10638
|
still a legitimate zero. --adopt never bypasses a branch that names issues.
|
|
10319
10639
|
|
|
10640
|
+
A HAND-OFF (#578) is the non-force door for a branch whose claim lives on ANOTHER machine:
|
|
10641
|
+
\`colab ship --branch <br> --handoff <url>\`, where <url> is the executor's hand-off comment
|
|
10642
|
+
(…/issues/<N>#issuecomment-<id>). With zero claims here, ship takes the issue set from the branch
|
|
10643
|
+
name's trailing run once the hand-off proves all of: the comment is on one of THIS repo's issues,
|
|
10644
|
+
one the branch carries; it names the branch and a sha that is the remote branch's CURRENT head (a
|
|
10645
|
+
branch that moved after its hand-off needs a new one — except by base-sync merges, #579, below); and every issue the branch carries has a
|
|
10646
|
+
live \`🔒 Claimed\` comment on that branch, posted by the hand-off's author before it. Nothing is
|
|
10647
|
+
claimed or taken over here: the executor keeps its claim, worktree and branch until it confirms
|
|
10648
|
+
the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <url> @ <sha>\`, and each
|
|
10649
|
+
🚢 comment names the hand-off. Any check failing refuses (exit 1); --force is never involved, and
|
|
10650
|
+
the human takeover (\`colab claim --force\`) stays the only other way in. Not with --adopt,
|
|
10651
|
+
--batch or --direct, and not when this machine already holds a claim on the branch.
|
|
10652
|
+
|
|
10653
|
+
A remote-built branch that fell BEHIND its base (#579) is synced by the lander as usual (B0: merge
|
|
10654
|
+
the base in, push) — and the hand-off still verifies, because the commits between the handed-off
|
|
10655
|
+
sha and the new head are each a PURE base-sync merge: two parents, the second already on the base,
|
|
10656
|
+
and a tree equal to git's own conflict-free merge of the two. A fix-up, a rebase, or a merge whose
|
|
10657
|
+
conflict was resolved by hand is not one, and still needs a new hand-off from the executor. The
|
|
10658
|
+
trailer then reads \`Colab-Handoff: <url> @ <handed-off sha> (synced to <head> by N base merge(s))\`.
|
|
10659
|
+
|
|
10320
10660
|
UNATTACHED CLAIMS (#319). A claim taken with no --worktree and no --branch (\`colab claim <N>
|
|
10321
10661
|
--session <id>\`) is carried by a branch ship only when BOTH hold: its session equals this ship's
|
|
10322
10662
|
(--session / COLAB_SESSION, or the worktree record's), and the branch name's trailing group names
|
|
@@ -10421,7 +10761,7 @@ Every other precondition is unchanged. No flag, env var or project.yml field wid
|
|
|
10421
10761
|
|
|
10422
10762
|
TUNING-ONLY — the second computed exception (#561). Ship also proceeds without the grant when the
|
|
10423
10763
|
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
|
|
10764
|
+
ship-batch-wait, ship-batch-steps, ci-wait-factor, thresholds) and every moved value valid; never with an authority
|
|
10425
10765
|
key (autonomy, promotion, migration-grant, ci-grant, trust-humans, exposure, tier, trunk, deploy,
|
|
10426
10766
|
release, production). It needs no issue. \`colab config set <key> <value> --evidence "<why>"\`
|
|
10427
10767
|
writes such a branch. The row reads "tuning-only (<keys>) — autonomy exception (#561)"; --dry --json
|
|
@@ -10445,9 +10785,11 @@ keeps its claim so a re-run finds it. Cannot be combined with --worktree/--branc
|
|
|
10445
10785
|
--delete-branch/--keep-branch/--keep-worktree/--adopt. \`writes: direct\` is not required. --dry and --dry --json
|
|
10446
10786
|
work as usual (json: \`direct: true\`, \`branch: null\`, \`mode: "evidence-close"\`, \`coreReview\`).
|
|
10447
10787
|
|
|
10448
|
-
BATCH LANDING (--batch, #373) — opt-in per repo: \`ship-batch: <N>\` in project.yml, an integer 1
|
|
10788
|
+
BATCH LANDING (--batch, #373) — opt-in per repo: \`ship-batch: <N>\` in project.yml, an integer 1–${shipBatch.MAX_BATCH};
|
|
10449
10789
|
absent or 1 declines every --batch call. It tests up to N green candidates as ONE combined head, then
|
|
10450
|
-
fast-forwards trunk, so a queue of green work stops draining at one change per trunk-CI cycle
|
|
10790
|
+
fast-forwards trunk, so a queue of green work stops draining at one change per trunk-CI cycle.
|
|
10791
|
+
A batch of ONE is valid (#562): a lone ready member lands the same way, so the combined run — the
|
|
10792
|
+
setups a repo runs only on ship-batch/** and trunk — gates it too, and it needs no sync + re-run:
|
|
10451
10793
|
- each member must be green at its OWN head (or have no run that could ever arrive), pass every
|
|
10452
10794
|
gate its own \`ship --dry --json\` reports, and be an ordinary squash into trunk through the
|
|
10453
10795
|
auto-trunk grant — the docs-only door, a migration, a ci-grant/cure, a core-path review, an
|
|
@@ -10465,15 +10807,24 @@ It never waits: each call reads the remote, takes ONE step and exits —
|
|
|
10465
10807
|
it, bounded (code-ship B1a), and run the SAME command again
|
|
10466
10808
|
4 declined — nothing landed; the last line is "→ SERIAL: colab ship --branch <b1> · …". Causes:
|
|
10467
10809
|
not enabled, no auto-trunk, no workflow fires on ship-batch/** (the run could never arrive),
|
|
10468
|
-
trunk CI red (the cure/grant doors apply per member, never to a batch),
|
|
10469
|
-
|
|
10470
|
-
once; red:finding, or red again after that one re-run → serial
|
|
10810
|
+
trunk CI red (the cure/grant doors apply per member, never to a batch), no member can join,
|
|
10811
|
+
or a batch of ONE whose combined run is red — classify it: red:infra → the printed
|
|
10812
|
+
\`gh run rerun\`, once; red:finding, or red again after that one re-run → serial.
|
|
10813
|
+
A red batch of TWO OR MORE never goes serial (#557): red:infra → re-run once; red:finding →
|
|
10814
|
+
the same command plus --split; red again after the re-run → it splits by itself. A split
|
|
10815
|
+
rebuilds the same ship-batch/<trunk-sha7> with the FIRST half of its members (exit 3); the rest
|
|
10816
|
+
wait for the next batch, and a red half splits again
|
|
10471
10817
|
1 refused (a broken checkout, an unreadable remote) — or the land push was refused while trunk did
|
|
10472
10818
|
NOT move (a local pre-push hook, a remote rejection): the push's own output is echoed, and
|
|
10473
10819
|
re-running hits the same refusal until its cause is fixed (#509)
|
|
10474
10820
|
One batch per base: a batch at this base carrying OTHER members is waited on (exit 3) while its run
|
|
10475
10821
|
is pending or green, but a declined one — its combined run red — is deleted and the batch you asked
|
|
10476
10822
|
for is built in its place, so the survivors of a decline can batch without landing serially first (#391).
|
|
10823
|
+
The batch also holds the trunk LANE (#581): while a ship-batch/<trunk-sha7> ref at trunk's tip has its
|
|
10824
|
+
combined run in flight — or green within ${shipBatch.LANE_GRACE_SEC / 60}m, so its lander can land it — a serial
|
|
10825
|
+
\`colab ship --branch\` into trunk pauses with exit 3 (⏸ BATCH-IN-FLIGHT; its --dry --json row
|
|
10826
|
+
'no batch in flight (#581)' reads self-clearing) instead of moving trunk under it and discarding the run.
|
|
10827
|
+
A red batch, or one with no run / not landed past that grace, holds nothing.
|
|
10477
10828
|
A member that conflicts with the members already in is dropped to the next batch; the rest go on —
|
|
10478
10829
|
unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
|
|
10479
10830
|
regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
|
|
@@ -10483,12 +10834,17 @@ at build, added since) is NOT landed with it — the command names both lists an
|
|
|
10483
10834
|
--dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
|
|
10484
10835
|
locally and printed; a staged green batch prints what would land (members, combined run, target sha).
|
|
10485
10836
|
Consumer CI must opt in: add 'ship-batch/**' to a CI workflow's push: branches:.
|
|
10837
|
+
ADAPTIVE SIZE (#557) — opt-in per repo: \`ship-batch-steps: 2,4,8\` in project.yml, ascending sizes
|
|
10838
|
+
within ship-batch. Absent or malformed: every batch is up to ship-batch, exactly as above. With it,
|
|
10839
|
+
each batch head carries "Ship-Batch-Size: <s>" ("<s> red" on a split half), and the next batch is
|
|
10840
|
+
built at the step above the last landed one's size after a green, the step below after a red, the
|
|
10841
|
+
smallest step when trunk carries none yet.
|
|
10486
10842
|
PARTNER WAIT (#555) — opt-in per repo: \`ship-batch-wait: <duration>\` in project.yml (90s, 6m, 1h; the
|
|
10487
10843
|
unit is required). Absent, zero or malformed: no wait, exactly as above. With it, a call where exactly
|
|
10488
10844
|
ONE member can join pauses (exit 3, "⏸ PARTNER-WAIT", the seconds left) until that window has passed
|
|
10489
10845
|
since the member became ready (its head CI's last update, else its head commit's date) — then the same
|
|
10490
|
-
call
|
|
10491
|
-
--batch with all of them.
|
|
10846
|
+
call builds it as a batch of one (#562). The caller waits, gathers every ready candidate again and
|
|
10847
|
+
calls --batch with all of them. Without the field, a lone member is built at once.
|
|
10492
10848
|
|
|
10493
10849
|
B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
|
|
10494
10850
|
does unasked, however certain it is that the content landed: reporting is safe and reversible,
|
|
@@ -11079,6 +11435,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
|
|
|
11079
11435
|
const ids = treeGreen.treeSkipCheckRuns(checks);
|
|
11080
11436
|
if (!ids || !ids.length) return verdict;
|
|
11081
11437
|
const cites = [];
|
|
11438
|
+
const docs = [];
|
|
11082
11439
|
let unreadable = 0;
|
|
11083
11440
|
const treeOf = (sha) => {
|
|
11084
11441
|
const r = git.git(['rev-parse', '--verify', '--quiet', `${sha}^{tree}`], repoAbs);
|
|
@@ -11086,7 +11443,11 @@ function treeGreenVerdict(repoAbs, run, verdict) {
|
|
|
11086
11443
|
};
|
|
11087
11444
|
const ours = treeOf(run.sha);
|
|
11088
11445
|
for (const id of ids) {
|
|
11089
|
-
const
|
|
11446
|
+
const annotations = git.ghCheckRunAnnotations(repoAbs, id);
|
|
11447
|
+
// #570: a docs-only skip — the guard found every changed path documentation from a green base.
|
|
11448
|
+
const docsSkip = treeGreen.parseDocsSkip(annotations);
|
|
11449
|
+
if (docsSkip) { docs.push(docsSkip); continue; }
|
|
11450
|
+
const cite = treeGreen.parseCitation(annotations);
|
|
11090
11451
|
if (!cite) { unreadable++; continue; }
|
|
11091
11452
|
const theirs = treeOf(cite.head);
|
|
11092
11453
|
if (ours && theirs && ours !== theirs) {
|
|
@@ -11095,7 +11456,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
|
|
|
11095
11456
|
}
|
|
11096
11457
|
cites.push({ ...cite, proof: ours && theirs ? 'verified' : 'unverified' });
|
|
11097
11458
|
}
|
|
11098
|
-
return { ...verdict, detail: verdict.detail + treeGreen.citationNote(cites, unreadable), treeGreen: cites.map((c) => c.url) };
|
|
11459
|
+
return { ...verdict, detail: verdict.detail + treeGreen.citationNote(cites, unreadable, docs), treeGreen: cites.map((c) => c.url) };
|
|
11099
11460
|
}
|
|
11100
11461
|
|
|
11101
11462
|
/**
|
|
@@ -11838,8 +12199,13 @@ function cmdShipDryJson(opts) {
|
|
|
11838
12199
|
const trunk = resolveTrunk(repoAbs, doc);
|
|
11839
12200
|
if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
|
|
11840
12201
|
if (sess.branch === trunk) throw new UserError(`Refusing: --branch is the trunk itself (${trunk}) — nothing to ship. A unit committed straight to ${trunk} closes with \`colab ship --direct\` (#302)`);
|
|
12202
|
+
const handoff = applyShipHandoff(repoAbs, sess, opts, trunk); // #578 — same resolution as the prose path
|
|
11841
12203
|
|
|
11842
12204
|
const checks = [];
|
|
12205
|
+
if (handoff) {
|
|
12206
|
+
checks.push({ name: 'hand-off verified (#578)', ok: handoff.ok, class: handoff.ok ? null : HUMAN_GATED,
|
|
12207
|
+
detail: handoff.ok ? handoffDetail(handoff) : `${handoff.reason}: ${handoff.detail}` });
|
|
12208
|
+
}
|
|
11843
12209
|
let target = null;
|
|
11844
12210
|
// #74/#263: the close-gate split (closeIssues/refsIssues/checklistFindings) is reported
|
|
11845
12211
|
// ALONGSIDE `checks` AS WELL AS folded into it — `closeIssues`/`refsIssues`/`checklistFindings`
|
|
@@ -12114,6 +12480,17 @@ function cmdShipDryJson(opts) {
|
|
|
12114
12480
|
if (coreReviewJson.verdict === 'pending') mode = 'pr-pending';
|
|
12115
12481
|
}
|
|
12116
12482
|
|
|
12483
|
+
// #581: the same lane read as the prose path's table — a squash into trunk while a batch holds the
|
|
12484
|
+
// lane would discard the batch's run. SELF_CLEARING: the batch lands or is declined on its own.
|
|
12485
|
+
// Never for a batch member read (the batch IS the lane) nor for evidence-close (trunk does not move).
|
|
12486
|
+
if (!dryMode.evidenceClose && !opts._batchMember) {
|
|
12487
|
+
const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
|
|
12488
|
+
if (laneJson) {
|
|
12489
|
+
checks.push({ name: 'no batch in flight (#581)', ok: !laneJson.held, class: laneJson.held ? SELF_CLEARING : null,
|
|
12490
|
+
detail: laneJson.detail, ...(laneJson.held ? { batchRef: laneJson.ref } : {}) });
|
|
12491
|
+
}
|
|
12492
|
+
}
|
|
12493
|
+
|
|
12117
12494
|
// #149: the same inherited-closing-keyword scan the prose --dry path runs, mirrored here —
|
|
12118
12495
|
// following #153's own precedent for this function (its comment above: "a caller reading only
|
|
12119
12496
|
// checks[]/ok … used to see NO check at all here"). Without this, the ONE caller class this path
|
|
@@ -12909,6 +13286,72 @@ function autonomyGatePayload(gate) {
|
|
|
12909
13286
|
}
|
|
12910
13287
|
|
|
12911
13288
|
/** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
|
|
13289
|
+
/**
|
|
13290
|
+
* #578 — `--handoff <comment-url>`: verify the executor's recorded hand-off and, when it holds, take
|
|
13291
|
+
* the session's issue set from it (tools/lib/ship-handoff.js says what it must prove). Returns null
|
|
13292
|
+
* without --handoff, the failing verdict on a refusal, the passing one after mutating `sess`.
|
|
13293
|
+
*
|
|
13294
|
+
* Writes nothing locally: no claim record, no worktree record. The executor's claim is the claim;
|
|
13295
|
+
* this ship only lands what it handed off, so B3 has nothing of THIS machine's to release.
|
|
13296
|
+
*/
|
|
13297
|
+
function applyShipHandoff(repoAbs, sess, opts, trunk) {
|
|
13298
|
+
if (!opts.handoff) return null;
|
|
13299
|
+
if (opts.adopt) throw new UserError('--handoff and --adopt contradict each other: --adopt is for a branch with NO issue, --handoff for one whose claim lives on another machine — drop --adopt');
|
|
13300
|
+
if (sess.issues.length) {
|
|
13301
|
+
throw new UserError(`--handoff is the door for a branch with NO claim on this machine, and this machine holds ${sess.issues.map((n) => '#' + n).join(' ')} ` +
|
|
13302
|
+
`for ${sess.branch} — ship it without --handoff`);
|
|
13303
|
+
}
|
|
13304
|
+
const u = shipHandoff.parseHandoffUrl(opts.handoff);
|
|
13305
|
+
let comment = null;
|
|
13306
|
+
if (u) {
|
|
13307
|
+
const r = git.ghApi(repoAbs, [`repos/{owner}/{repo}/issues/comments/${u.commentId}`]);
|
|
13308
|
+
if (r.ok) {
|
|
13309
|
+
try {
|
|
13310
|
+
const j = JSON.parse(r.stdout);
|
|
13311
|
+
comment = { body: j.body || '', login: (j.user && j.user.login) || '', createdAt: j.created_at || '', htmlUrl: j.html_url || '' };
|
|
13312
|
+
} catch (_) { comment = null; }
|
|
13313
|
+
}
|
|
13314
|
+
}
|
|
13315
|
+
// The head check must read the remote as it is NOW, not a tracking ref from whenever this clone last fetched.
|
|
13316
|
+
const remote = git.remoteFor(repoAbs);
|
|
13317
|
+
if (u && comment) git.git(['fetch', '--quiet', remote, `+refs/heads/${sess.branch}:refs/remotes/${remote}/${sess.branch}`], repoAbs);
|
|
13318
|
+
const refs = git.branchRefs(repoAbs, sess.branch, remote);
|
|
13319
|
+
// #579: base-sync merges the lander (B0) stacked on the handed-off head do not void the hand-off.
|
|
13320
|
+
// Read against the base as it is NOW — the merges' second parents must already be on it.
|
|
13321
|
+
let syncChain = [];
|
|
13322
|
+
if (u && comment && refs && refs.remoteSha && trunk) {
|
|
13323
|
+
git.git(['fetch', '--quiet', remote, `+refs/heads/${trunk}:refs/remotes/${remote}/${trunk}`], repoAbs);
|
|
13324
|
+
syncChain = shipHandoff.syncMergeChain((a) => git.git(a, repoAbs), refs.remoteSha, `refs/remotes/${remote}/${trunk}`);
|
|
13325
|
+
}
|
|
13326
|
+
const claimsByIssue = {};
|
|
13327
|
+
if (u && comment) {
|
|
13328
|
+
for (const n of shipguard.branchIssueNumbers(sess.branch)) {
|
|
13329
|
+
const info = git.ghIssueView(repoAbs, n, ['comments']);
|
|
13330
|
+
claimsByIssue[n] = info ? liveClaimComments(info.comments || []).map((c) => ({ ...c })) : null;
|
|
13331
|
+
}
|
|
13332
|
+
}
|
|
13333
|
+
const v = shipHandoff.handoffVerdict({ url: opts.handoff, comment, branch: sess.branch, refs, claimsByIssue, syncChain });
|
|
13334
|
+
if (!v.ok) return v;
|
|
13335
|
+
sess.issues = v.issues;
|
|
13336
|
+
sess.handoff = v;
|
|
13337
|
+
// #372: the implementer is the executor that handed off — name it, never leave it reading as the shipper.
|
|
13338
|
+
const ex = (claimsByIssue[v.issues[0]] || []).find((c) => c.branch === sess.branch && c.login === v.executor.login);
|
|
13339
|
+
if (ex && (ex.session || ex.sessionName)) sess.holder = { session: ex.session || '', sessionName: ex.sessionName || '' };
|
|
13340
|
+
return v;
|
|
13341
|
+
}
|
|
13342
|
+
|
|
13343
|
+
function handoffDetail(v) {
|
|
13344
|
+
const head = v.syncMerges
|
|
13345
|
+
? `${shortSha(v.handedOff)}, under ${v.syncMerges} clean base-sync merge${v.syncMerges === 1 ? '' : 's'} to the remote head ${shortSha(v.sha)} (#579)`
|
|
13346
|
+
: `${shortSha(v.sha)} = the remote head`;
|
|
13347
|
+
return `${v.url} hands off ${head}; executor ${v.executor.login}'s live claim on ${v.issues.map((n) => '#' + n).join(' ')}`;
|
|
13348
|
+
}
|
|
13349
|
+
|
|
13350
|
+
/** The clause the 🚢 comment carries for a hand-off land — the executor still holds its claim. */
|
|
13351
|
+
function handoffEvidence(v) {
|
|
13352
|
+
return v ? ` · landed from the executor's hand-off ${v.url} — its claim and worktree stay until it confirms the land` : '';
|
|
13353
|
+
}
|
|
13354
|
+
|
|
12912
13355
|
function shipRefFor(repoAbs, branch) {
|
|
12913
13356
|
const r = git.branchRefs(repoAbs, branch);
|
|
12914
13357
|
return r.localSha || r.remoteSha || branch;
|
|
@@ -12916,14 +13359,14 @@ function shipRefFor(repoAbs, branch) {
|
|
|
12916
13359
|
|
|
12917
13360
|
function cmdShip(argv) {
|
|
12918
13361
|
const opts = parseArgs(argv, {
|
|
12919
|
-
values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy' },
|
|
13362
|
+
values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff' },
|
|
12920
13363
|
// #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
|
|
12921
13364
|
// `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
|
|
12922
13365
|
// accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
|
|
12923
13366
|
// repeat (`once`), checked here before any git or GitHub call.
|
|
12924
13367
|
lists: { '--refs': 'refs' },
|
|
12925
13368
|
once: true,
|
|
12926
|
-
flags: { '--keep-worktree': 'keepWorktree', '--delete-branch': 'deleteBranch', '--keep-branch': 'keepBranch', '--dry': 'dry', '--json': 'json', '--direct': 'direct', '--adopt': 'adopt', '-h': 'help', '--help': 'help' },
|
|
13369
|
+
flags: { '--keep-worktree': 'keepWorktree', '--delete-branch': 'deleteBranch', '--keep-branch': 'keepBranch', '--dry': 'dry', '--json': 'json', '--direct': 'direct', '--adopt': 'adopt', '--split': 'split', '-h': 'help', '--help': 'help' },
|
|
12927
13370
|
});
|
|
12928
13371
|
if (opts.help) return print(HELP_SHIP);
|
|
12929
13372
|
// --json is scoped to --dry only (#77): a machine-readable READ of the preconditions. Reporting
|
|
@@ -12931,6 +13374,9 @@ function cmdShip(argv) {
|
|
|
12931
13374
|
// — refuse the combination rather than silently ignore --json on a real ship.
|
|
12932
13375
|
if (opts.json && !opts.dry) throw new UserError('--json currently only applies together with --dry — see `colab ship --help`');
|
|
12933
13376
|
if (shippedBranch.conflictingFlags(opts)) throw new UserError('--delete-branch and --keep-branch contradict each other — pass one (see `colab ship --help`, #368)');
|
|
13377
|
+
// #578: a hand-off names ONE branch; batch and trunk-direct have no single branch for it to name.
|
|
13378
|
+
if (opts.handoff && (opts.batch || opts.direct)) throw new UserError(`--handoff applies to one --branch ship — not to ${opts.batch ? '--batch' : '--direct'} (see \`colab ship --help\`)`);
|
|
13379
|
+
if (opts.split && !opts.batch) throw new UserError('--split applies to a red combined run of --batch only (#557) — run `colab ship --batch <b1,b2,…> --split` with the members the red batch carries');
|
|
12934
13380
|
if (opts.batch) return cmdShipBatch(opts); // #373 — its own re-entrant path; nothing below changes
|
|
12935
13381
|
// A fully separate code path, deliberately: the prose/table path below is unchanged by this
|
|
12936
13382
|
// feature (CONVENTIONS/#77 requires it stay byte-identical), so --dry --json does its own
|
|
@@ -12948,6 +13394,17 @@ function cmdShip(argv) {
|
|
|
12948
13394
|
if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
|
|
12949
13395
|
if (sess.branch === trunk) throw new UserError(`Refusing: --branch is the trunk itself (${trunk}) — nothing to ship. A unit committed straight to ${trunk} closes with \`colab ship --direct\` (#302)`);
|
|
12950
13396
|
|
|
13397
|
+
// #578: a remote-built branch's issue set, from its executor's recorded hand-off. Before the
|
|
13398
|
+
// branch-resolves check below: reading the hand-off fetches the branch, which is what makes a
|
|
13399
|
+
// remote-only branch resolve here at all.
|
|
13400
|
+
const handoff = applyShipHandoff(repoAbs, sess, opts, trunk);
|
|
13401
|
+
if (handoff && !handoff.ok) {
|
|
13402
|
+
process.stderr.write(`✗ Refusing --handoff: ${handoff.detail}. Re-run with --handoff <a hand-off naming ${sess.branch} and its current head>, ` +
|
|
13403
|
+
`ship from the executor's machine, or a human takes the claim over (\`colab claim <N> --branch ${sess.branch} --force\`, a human act).\n`);
|
|
13404
|
+
process.stderr.write(' Nothing was claimed or taken over here — the executor\'s claim still stands.\n');
|
|
13405
|
+
return 1;
|
|
13406
|
+
}
|
|
13407
|
+
|
|
12951
13408
|
// ---- the recorded branch must RESOLVE, before anything else is computed ----
|
|
12952
13409
|
// Everything downstream is keyed to this name: the claim lookup above, the migration diff, the
|
|
12953
13410
|
// squash. A worktree record holding a role word or a deleted branch fails all three quietly —
|
|
@@ -13007,6 +13464,7 @@ function cmdShip(argv) {
|
|
|
13007
13464
|
const gh = isGhUsable(repoAbs);
|
|
13008
13465
|
// #345: the gate that passed is the table's first row, so a reader sees WHICH door opened it.
|
|
13009
13466
|
const checks = [['✓', 'autonomy granted', autonomyGate.detail]];
|
|
13467
|
+
if (handoff) checks.push(['✓', 'hand-off verified (#578)', handoffDetail(handoff)]);
|
|
13010
13468
|
|
|
13011
13469
|
// Which claimed issues are REFERENCED (Refs #N), not closed — three sources unioned by
|
|
13012
13470
|
// resolveCloseRefsSplit (#48, #74): --refs, the tracking label, and #74's close gate (an
|
|
@@ -13118,6 +13576,11 @@ function cmdShip(argv) {
|
|
|
13118
13576
|
const coreReview = shipCoreReview(repoAbs, gh, target, sess.branch);
|
|
13119
13577
|
const coreOk = coreReview.verdict !== 'refuse';
|
|
13120
13578
|
checks.push([coreOk ? (coreReview.verdict === 'pending' ? '⏸' : '✓') : '✗', 'core-path review (#350)', coreReview.detail]);
|
|
13579
|
+
|
|
13580
|
+
// #581: a batch in flight at trunk's tip holds the lane. Like the core-path review's 'pending', a
|
|
13581
|
+
// hold is not a failed precondition — it is a pause, taken below once every real one has passed.
|
|
13582
|
+
const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
|
|
13583
|
+
if (lane) checks.push([lane.held ? '⏸' : '✓', 'no batch in flight (#581)', lane.detail]);
|
|
13121
13584
|
for (const w of coreReview.warnings) warn(`${coreReview.codeownersPath}: ${w}`);
|
|
13122
13585
|
|
|
13123
13586
|
// #389: the record this ship will write after the push must be writable NOW.
|
|
@@ -13352,6 +13815,8 @@ function cmdShip(argv) {
|
|
|
13352
13815
|
print(' Plan: no merge, no commit, no push · post evidence comment + CLOSE each issue · ' +
|
|
13353
13816
|
(opts.keepWorktree ? 'keep worktree' : 'worktree rm') + ' (releases claims)');
|
|
13354
13817
|
print(' Gate: every closing issue must already carry an evidence comment — checked at run time.');
|
|
13818
|
+
} else if (lane && lane.held && coreReview.verdict !== 'pending') {
|
|
13819
|
+
print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${lane.ref} holds the ${trunk} lane (#581); run again once it has landed or been declined`);
|
|
13355
13820
|
} else if (coreReview.verdict === 'pending') {
|
|
13356
13821
|
print(` Plan: push ${sess.branch} · ${coreReview.pr ? `PR #${coreReview.pr.number} already open` : 'open a PR → ' + target} · ` +
|
|
13357
13822
|
'PAUSE (⏸ exit 3, no squash) until an account other than the author approves the current head (#350)');
|
|
@@ -13417,6 +13882,9 @@ function cmdShip(argv) {
|
|
|
13417
13882
|
return shipOpenCorePr(repoAbs, coreReview, { target, branch: sess.branch, title, body });
|
|
13418
13883
|
}
|
|
13419
13884
|
|
|
13885
|
+
// ---- (b5) #581: a batch holds the trunk lane — pause before B0, so nothing is synced or merged ----
|
|
13886
|
+
if (lane && lane.held) { printBatchLanePause(lane, trunk); return 3; }
|
|
13887
|
+
|
|
13420
13888
|
// ---- (c) B0: merge the TARGET into the branch (in the worktree, or an ephemeral one) ----
|
|
13421
13889
|
const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
|
|
13422
13890
|
const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
|
|
@@ -13562,6 +14030,10 @@ function cmdShip(argv) {
|
|
|
13562
14030
|
ciGrantForTrailer = ciResultB1.grantVerdict;
|
|
13563
14031
|
}
|
|
13564
14032
|
}
|
|
14033
|
+
// #581: re-read the lane right before the merge — B0 sits between the table and here, and a batch
|
|
14034
|
+
// built in that window is exactly as live as one the table saw.
|
|
14035
|
+
const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) : null;
|
|
14036
|
+
if (laneB1 && laneB1.held) { cleanupEphemeral(); printBatchLanePause(laneB1, trunk); return 3; }
|
|
13565
14037
|
// WHERE the squash happens. Into trunk it is the main checkout, which is on trunk by invariant
|
|
13566
14038
|
// (and was just verified to be). Into a declared line it must NOT be: checking the main checkout
|
|
13567
14039
|
// out onto a long-lived line is the very state that made this axis necessary — everything reading
|
|
@@ -13679,7 +14151,7 @@ function cmdShip(argv) {
|
|
|
13679
14151
|
(publicOmit ? (m) => print(` ${m}`) : warn)(`Machine trailer ${machineTrailerSummary(trailerDecision)}`);
|
|
13680
14152
|
}
|
|
13681
14153
|
const machineLine = trailerDecision.line;
|
|
13682
|
-
const ciTrailerLines = [ciTrailer, adoptTrailer, machineLine].filter(Boolean);
|
|
14154
|
+
const ciTrailerLines = [ciTrailer, adoptTrailer, shipHandoff.handoffTrailer(sess.handoff), machineLine].filter(Boolean);
|
|
13683
14155
|
if (opts.message) {
|
|
13684
14156
|
// --message overrides the subject/body, but Closes is spliced in as its own paragraph — never
|
|
13685
14157
|
// concatenated. Appending it welded ` — Closes #N` onto whatever the message ended with, which
|
|
@@ -13688,7 +14160,7 @@ function cmdShip(argv) {
|
|
|
13688
14160
|
for (const tl of ciTrailerLines) {
|
|
13689
14161
|
if (commitMsg.toLowerCase().includes(tl.toLowerCase())) continue;
|
|
13690
14162
|
const lastLine = commitMsg.split('\n').pop().trim();
|
|
13691
|
-
commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|Colab-Adopted|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
|
|
14163
|
+
commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|Colab-Adopted|Colab-Handoff|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
|
|
13692
14164
|
}
|
|
13693
14165
|
} else {
|
|
13694
14166
|
// Preserve the branch's crafted commit (subject + footers); insert Closes/Refs above the footers.
|
|
@@ -13850,11 +14322,13 @@ function cmdShip(argv) {
|
|
|
13850
14322
|
// a long ship these lines would otherwise scroll off above the `✓ Shipped` line — which is
|
|
13851
14323
|
// exactly how #304's failure went unnoticed in the first place.
|
|
13852
14324
|
deferredCollector = [];
|
|
14325
|
+
let reviewPrHandled = null; // #584: the #350 review PR, already closed (or warned about) above
|
|
13853
14326
|
// #350: the approved PR is spent — its work landed by squash, which the forge cannot see as a merge.
|
|
13854
14327
|
if (coreReview.verdict === 'approved' && coreReview.pr && gh) {
|
|
13855
14328
|
const closed = git.ghPrClose(repoAbs, coreReview.pr.number, `Landed on \`${target}\` as ${sha} by \`colab ship\` (#350), approved by ${coreReview.approval.by}.`);
|
|
13856
14329
|
if (closed.ok) print(` closed PR #${coreReview.pr.number} (landed as ${sha})`);
|
|
13857
14330
|
else warnDeferred(`could not close PR #${coreReview.pr.number} (${(closed.stderr || '').split('\n')[0]}) — it landed as ${sha}; close it by hand`);
|
|
14331
|
+
reviewPrHandled = coreReview.pr.number; // #584: either way the tail's landed-PR close must not touch it again
|
|
13858
14332
|
}
|
|
13859
14333
|
// Only when the target IS the shared checkout. `ephemeralTarget === false` means
|
|
13860
14334
|
// `targetDir === repoAbs` (see #234's note above); a declared integration line merged in a
|
|
@@ -13898,7 +14372,7 @@ function cmdShip(argv) {
|
|
|
13898
14372
|
pushEvent('ship', {
|
|
13899
14373
|
repo: repoAbs, worktree: sess.name, session: sess.session,
|
|
13900
14374
|
issue: sess.issues.length === 1 ? sess.issues[0] : undefined,
|
|
13901
|
-
payload: { state: 'merged', branch: sess.branch, target, sha, issues: sess.issues, ...(adoptInfo ? { adopted: adoptInfo } : {}) },
|
|
14375
|
+
payload: { state: 'merged', branch: sess.branch, target, sha, issues: sess.issues, ...(adoptInfo ? { adopted: adoptInfo } : {}), ...(sess.handoff ? { handoff: { url: sess.handoff.url, sha: sess.handoff.sha } } : {}) },
|
|
13902
14376
|
});
|
|
13903
14377
|
|
|
13904
14378
|
// Then, PER ISSUE, a merge-completion event (#46 §2, following #45 §2). The ship event above is
|
|
@@ -13920,11 +14394,13 @@ function cmdShip(argv) {
|
|
|
13920
14394
|
// window itself now OPENS at the push (e2, #304), not here: post-ship's warnings belong in the
|
|
13921
14395
|
// same block, and re-assigning the collector here would silently discard them.
|
|
13922
14396
|
shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
|
|
13923
|
-
|
|
14397
|
+
skipPrs: reviewPrHandled ? [reviewPrHandled] : [],
|
|
14398
|
+
evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
|
|
13924
14399
|
|
|
13925
14400
|
print('');
|
|
13926
14401
|
print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
|
|
13927
14402
|
if (adoptInfo) print(` adopted from ${adoptInfo.remote || 'origin'}/${adoptInfo.branch} @ ${shortSha(adoptInfo.remoteSha)} — recorded in the Colab-Adopted: trailer (#324)`);
|
|
14403
|
+
if (sess.handoff) print(` landed from the hand-off ${sess.handoff.url} — the executor's claim and worktree stay until it confirms the land (#578)`);
|
|
13928
14404
|
if (target !== trunk) print(` "${target}" is a declared line: this work is NOT in ${trunk} until a human merges the line.`);
|
|
13929
14405
|
// #114: everything deferred since the push (e2, #304) lands here, AFTER the success line — not scattered above it
|
|
13930
14406
|
// where a long ship scrolls it out of view. The merge itself already landed either way; this is
|
|
@@ -13938,6 +14414,38 @@ function cmdShip(argv) {
|
|
|
13938
14414
|
}
|
|
13939
14415
|
|
|
13940
14416
|
|
|
14417
|
+
/**
|
|
14418
|
+
* #584: close every open PR whose head is the branch this ship just landed — the PR a person or an
|
|
14419
|
+
* automation opened only to obtain branch CI. The forge never sees a squash as a merge of that PR, so
|
|
14420
|
+
* without this it stays open forever, reading as unmerged work. Only a PR whose head commit is the
|
|
14421
|
+
* landed tip (or an ancestor of it) is closed; one carrying commits that did not land is kept and
|
|
14422
|
+
* reported. Best-effort throughout: every failure defers a warning, none fails the ship.
|
|
14423
|
+
*/
|
|
14424
|
+
function shipCloseLandedPrs(repoAbs, sess, { target, sha, issues, skip = [] }) {
|
|
14425
|
+
const remoteName = git.remoteInfo(repoAbs).name || 'origin';
|
|
14426
|
+
const tipOf = (ref) => { const r = git.git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], repoAbs); return r.ok ? r.stdout.trim() : null; };
|
|
14427
|
+
const tip = tipOf(`refs/heads/${sess.branch}`) || tipOf(`refs/remotes/${remoteName}/${sess.branch}`);
|
|
14428
|
+
const headLanded = (oid) => {
|
|
14429
|
+
if (!tip) return false;
|
|
14430
|
+
if (oid === tip) return true;
|
|
14431
|
+
return git.git(['merge-base', '--is-ancestor', oid, tip], repoAbs).ok;
|
|
14432
|
+
};
|
|
14433
|
+
const res = landedPrs.closeLandedPrs({
|
|
14434
|
+
prs: git.ghOpenPrsForBranch(repoAbs, sess.branch),
|
|
14435
|
+
headLanded,
|
|
14436
|
+
close: (n, comment) => git.ghPrClose(repoAbs, n, comment),
|
|
14437
|
+
comment: landedPrs.landedPrComment({ target, sha, issues }),
|
|
14438
|
+
skip,
|
|
14439
|
+
});
|
|
14440
|
+
if (res.listError) {
|
|
14441
|
+
warnDeferred(`could not list open PRs for ${sess.branch} (${res.listError}) — any PR opened for its CI is still open; close it by hand (it landed as ${sha})`);
|
|
14442
|
+
return;
|
|
14443
|
+
}
|
|
14444
|
+
for (const n of res.closed) print(` closed PR #${n} — its branch ${sess.branch} landed as ${sha} (#584)`);
|
|
14445
|
+
for (const f of res.failed) warnDeferred(`could not close PR #${f.number} (${f.error}) — ${sess.branch} landed as ${sha}; close it by hand`);
|
|
14446
|
+
for (const k of res.kept) warnDeferred(`kept PR #${k.number} open: ${k.reason} (${sess.branch} landed as ${sha}) — it carries work that did not ship`);
|
|
14447
|
+
}
|
|
14448
|
+
|
|
13941
14449
|
/**
|
|
13942
14450
|
* The post-merge tail every landed branch gets — cmdShip's B3 through i2, moved here unchanged (#373)
|
|
13943
14451
|
* so a batch member gets exactly the same steps in the same order: worktree teardown (B3), the claims
|
|
@@ -13946,7 +14454,13 @@ function cmdShip(argv) {
|
|
|
13946
14454
|
* addition — '' on a serial ship (so its comment is byte-identical), the combined-run clause for a
|
|
13947
14455
|
* batch member.
|
|
13948
14456
|
*/
|
|
13949
|
-
function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '' }) {
|
|
14457
|
+
function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '', skipPrs = [] }) {
|
|
14458
|
+
// #584: the CI-trigger PR(s) this squash left behind. FIRST, while the branch ref still resolves —
|
|
14459
|
+
// B3 below may delete it, and "did the PR's head land?" is answered against that tip.
|
|
14460
|
+
if (gh && sess.branch) {
|
|
14461
|
+
try { shipCloseLandedPrs(repoAbs, sess, { target, sha, issues: closeIssues, skip: skipPrs }); }
|
|
14462
|
+
catch (e) { warnDeferred(`landed-PR close for ${sess.branch} failed (${e.message}) — the ship landed as ${sha}; close any PR for it by hand`); }
|
|
14463
|
+
}
|
|
13950
14464
|
const worktreeKept = !!(sess.name && opts.keepWorktree);
|
|
13951
14465
|
if (sess.name && !opts.keepWorktree) {
|
|
13952
14466
|
print(`B3: removing worktree ${sess.name} …`);
|
|
@@ -13966,7 +14480,8 @@ function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, re
|
|
|
13966
14480
|
// B3 (cont.) — the shipped branch. Kept by default; --delete-branch opts in. MUST come after the
|
|
13967
14481
|
// worktree removal above: git refuses to delete a branch checked out in a worktree.
|
|
13968
14482
|
// #368: a Refs-only ship deletes unless --keep-branch — see tools/lib/shipped-branch.js.
|
|
13969
|
-
|
|
14483
|
+
// #578: a handed-off branch is the executor's until it confirms the land — never deleted for it.
|
|
14484
|
+
const disposition = shippedBranch.shippedBranchDisposition({ closeIssues, refsIssues, deleteBranch: opts.deleteBranch, keepBranch: opts.keepBranch || (!!sess.handoff && !opts.deleteBranch) });
|
|
13970
14485
|
handleShippedBranch(repoAbs, target, sess.branch, { disposition, worktreeKept, integration });
|
|
13971
14486
|
|
|
13972
14487
|
// ---- (g/h) B4 verify + post summary per issue ----
|
|
@@ -14082,6 +14597,46 @@ function shipDryJsonReport(opts) {
|
|
|
14082
14597
|
return { ok: code === 0, body: holder.body || null, error: null };
|
|
14083
14598
|
}
|
|
14084
14599
|
|
|
14600
|
+
/**
|
|
14601
|
+
* #581: is a batch in flight at trunk's current tip? Read by every serial door that moves trunk (the
|
|
14602
|
+
* prose ship's table and B1, `--dry --json`), so a lander told about it waits instead of moving trunk
|
|
14603
|
+
* under the batch — which would throw the batch's green combined run away. The rule is
|
|
14604
|
+
* lib/ship-batch.js laneHold; this only reads the remote.
|
|
14605
|
+
*
|
|
14606
|
+
* Inert (null, no git or gh call) unless project.yml declares ship-batch > 1, the merge target is
|
|
14607
|
+
* trunk, and gh is usable. Out: null, or `{ held, ref, why, released, detail }`.
|
|
14608
|
+
*/
|
|
14609
|
+
function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
|
|
14610
|
+
if (target !== trunk || !gh || shipBatch.parseShipBatch(doc).n <= 1) return null;
|
|
14611
|
+
const remote = git.remoteFor(repoAbs);
|
|
14612
|
+
const ls = git.git(['ls-remote', remote, `refs/heads/${trunk}`, 'refs/heads/ship-batch/*'], repoAbs);
|
|
14613
|
+
if (!ls.ok) return { held: false, released: [], detail: `could not read ${remote} — no batch provably in flight` };
|
|
14614
|
+
const rows = ls.stdout.split('\n').map((l) => l.split('\t')).filter(([sha, ref]) => sha && ref);
|
|
14615
|
+
const trunkNow = ((rows.find(([, ref]) => ref.trim() === `refs/heads/${trunk}`) || [])[0] || '').trim();
|
|
14616
|
+
const atTip = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) }))
|
|
14617
|
+
.filter((x) => x.parsed && trunkNow.startsWith(x.parsed.base7));
|
|
14618
|
+
const batches = atTip.map((x) => {
|
|
14619
|
+
const runs = git.ghRunsForRef(repoAbs, x.parsed.ref, x.sha);
|
|
14620
|
+
let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
|
|
14621
|
+
if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
|
|
14622
|
+
const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
|
|
14623
|
+
return { ref: x.parsed.ref, base7: x.parsed.base7, verdict: shipBatch.combinedVerdict(runs),
|
|
14624
|
+
builtAtMs: Number.isFinite(built) ? built : null, settledAtMs: shipBatch.settledAt(runs) };
|
|
14625
|
+
});
|
|
14626
|
+
const r = shipBatch.laneHold({ batches, trunkNow, nowMs: Date.now() });
|
|
14627
|
+
const detail = r.held
|
|
14628
|
+
? `${r.ref} holds the ${trunk} lane — ${r.why}; landing now would move ${trunk} under it and discard its run`
|
|
14629
|
+
: (r.released.length ? `no batch holds the lane (${r.released.map((x) => `${x.ref}: ${x.why}`).join('; ')})` : `no batch in flight at ${trunk}@${shortSha(trunkNow)}`);
|
|
14630
|
+
return { ...r, trunkNow, detail };
|
|
14631
|
+
}
|
|
14632
|
+
|
|
14633
|
+
/** #581: the pause a serial ship takes while a batch holds the trunk lane — one message, every door. */
|
|
14634
|
+
function printBatchLanePause(lane, trunk) {
|
|
14635
|
+
print(`⏸ BATCH-IN-FLIGHT ${lane.ref} — ${lane.why}. Nothing landed.`);
|
|
14636
|
+
print(` Landing now would move ${trunk} under it and throw its combined run away (#581). Wait for it to land`);
|
|
14637
|
+
print(' or be declined (bounded, B1a — the same wait as any CI run), then run this command again.');
|
|
14638
|
+
}
|
|
14639
|
+
|
|
14085
14640
|
function cmdShipBatch(opts) {
|
|
14086
14641
|
for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ['json', '--json']]) {
|
|
14087
14642
|
if (opts[key]) throw new UserError(`--batch does not combine with ${flag} — each member ships with its own recorded claims and composed message (#373)`);
|
|
@@ -14104,17 +14659,32 @@ function cmdShipBatch(opts) {
|
|
|
14104
14659
|
if (String(doc.autonomy || '') !== 'auto-trunk') {
|
|
14105
14660
|
return serial(`project.yml does not grant autonomy: auto-trunk — batch landing needs it (every member lands in one unattended push)`);
|
|
14106
14661
|
}
|
|
14107
|
-
// #555: a declared ship-batch-wait
|
|
14662
|
+
// #555: a declared ship-batch-wait makes a lone member wait for a partner below.
|
|
14663
|
+
// #562: one named member is a valid batch — it lands through the combined run, never serially.
|
|
14108
14664
|
const waitCfg = shipBatch.parseShipBatchWait(doc);
|
|
14109
14665
|
if (!waitCfg.valid) warn(`${waitCfg.reason} — ignored: a lone member does not wait (fails closed, #555)`);
|
|
14110
|
-
if (members.length <
|
|
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`);
|
|
14666
|
+
if (members.length < 1) return serial('--batch names no branch — name every ready candidate');
|
|
14112
14667
|
|
|
14113
14668
|
const remote = git.remoteFor(repoAbs);
|
|
14114
14669
|
const fetched = git.git(['fetch', '--prune', remote], repoAbs);
|
|
14115
14670
|
if (!fetched.ok) throw new UserError(`could not fetch ${remote}: ${git.gitFailureLine(fetched.stderr)} — a batch is never built from stale refs`);
|
|
14116
14671
|
const trunkRef = `${remote}/${trunk}`;
|
|
14117
14672
|
|
|
14673
|
+
// #557: the size this batch is built at — fixed at ship-batch without steps; with them, one step
|
|
14674
|
+
// above the last landed batch's size after a green, one below after a red, read from trunk alone.
|
|
14675
|
+
const stepsCfg = shipBatch.parseShipBatchSteps(doc);
|
|
14676
|
+
if (!stepsCfg.valid) warn(`${stepsCfg.reason} — ignored: every batch is up to ship-batch: ${cfg.n} (fails closed, #557)`);
|
|
14677
|
+
let lastSize = null;
|
|
14678
|
+
if (stepsCfg.steps) {
|
|
14679
|
+
const lg = git.git(['log', '-1', '--first-parent', `--grep=^${shipBatch.SIZE_TRAILER_KEY}: `, '--format=%B', trunkRef], repoAbs);
|
|
14680
|
+
lastSize = lg.ok ? shipBatch.parseSizeTrailer([lg.stdout]) : null;
|
|
14681
|
+
}
|
|
14682
|
+
const size = shipBatch.adaptiveSize({ n: cfg.n, steps: stepsCfg.steps, last: lastSize });
|
|
14683
|
+
const sizeLabel = stepsCfg.steps
|
|
14684
|
+
? `ship-batch: ${cfg.n} · step ${size} of ${stepsCfg.steps.join(',')}${lastSize ? ` — the last landed batch was ${lastSize.red ? `a split of a red one at ${lastSize.size}` : `green at ${lastSize.size}`}` : ' — no sized batch on trunk yet'}`
|
|
14685
|
+
: `ship-batch: ${cfg.n}`;
|
|
14686
|
+
if (members.length > size) warn(`--batch names ${members.length} branches; ${sizeLabel} caps the batch — the rest wait for the next one`);
|
|
14687
|
+
|
|
14118
14688
|
// ---- (a) wiring: could the combined run ever arrive? Decided BEFORE anything is pushed. ----
|
|
14119
14689
|
const fires = workflowsFiringAt(repoAbs, trunkRef, shipBatch.PROBE_REF);
|
|
14120
14690
|
if (!shipBatch.wiring(fires).wired) {
|
|
@@ -14173,8 +14743,9 @@ function cmdShipBatch(opts) {
|
|
|
14173
14743
|
}
|
|
14174
14744
|
if (!foreignStep) {
|
|
14175
14745
|
const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
|
|
14176
|
-
const matches = heads.length >=
|
|
14177
|
-
existing = { ref: atBase.parsed.ref, base7: atBase.parsed.base7, sha: atBase.sha, members: inBatch, matches
|
|
14746
|
+
const matches = heads.length >= 1 && heads.every((m) => m.now && m.now.startsWith(m.sha));
|
|
14747
|
+
existing = { ref: atBase.parsed.ref, base7: atBase.parsed.base7, sha: atBase.sha, members: inBatch, matches,
|
|
14748
|
+
size: shipBatch.parseSizeTrailer(log.ok ? log.stdout.split('\0') : []) };
|
|
14178
14749
|
// #415: the command line and the staged batch can name different sets. A requested branch the
|
|
14179
14750
|
// staged batch does not carry (over the cap, dropped at build, or added since) does NOT ride
|
|
14180
14751
|
// along — say so, naming both lists, instead of resuming as if the two were the same.
|
|
@@ -14186,7 +14757,10 @@ function cmdShipBatch(opts) {
|
|
|
14186
14757
|
}
|
|
14187
14758
|
}
|
|
14188
14759
|
const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
|
|
14189
|
-
let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount:
|
|
14760
|
+
let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow, verdict, split: !!opts.split });
|
|
14761
|
+
if (opts.split && !(verdict && verdict.state === 'red')) {
|
|
14762
|
+
print(` --split ignored: ${existing ? `${existing.ref} is not red (${verdict ? verdict.state : 'members changed'})` : 'no batch is staged at this base'} — only a red combined run splits (#557)`);
|
|
14763
|
+
}
|
|
14190
14764
|
|
|
14191
14765
|
if (step.step === 'rebuild') {
|
|
14192
14766
|
print(` ${existing.ref} no longer carries the requested members at their current heads — rebuilding`);
|
|
@@ -14208,6 +14782,24 @@ function cmdShipBatch(opts) {
|
|
|
14208
14782
|
print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
|
|
14209
14783
|
return 4;
|
|
14210
14784
|
}
|
|
14785
|
+
if (step.step === 'red-rerun-or-split') {
|
|
14786
|
+
const ids = verdict.runIds.join(', ') || '(id unread)';
|
|
14787
|
+
const cmd = `colab ship --batch ${members.join(',')} --split${opts.repo ? ` --repo ${opts.repo}` : ''}`;
|
|
14788
|
+
print(`✗ ship-batch: the combined run is red at ${existing.ref}@${shortSha(existing.sha)} (${verdict.why}; run ${ids}). Nothing landed.`);
|
|
14789
|
+
print(` ${existing.members.length} members — it splits rather than going serial (#557). Classify it first (CONVENTIONS §4, Branch CI):`);
|
|
14790
|
+
for (const id of verdict.runIds) print(` red:infra → gh run rerun ${id} --failed then run this command again (one re-run only)`);
|
|
14791
|
+
print(` red:finding → ${cmd}`);
|
|
14792
|
+
print(' rebuilds this batch with its first half; the rest wait for the next batch');
|
|
14793
|
+
return 4;
|
|
14794
|
+
}
|
|
14795
|
+
let splitHalf = null;
|
|
14796
|
+
if (step.step === 'split') {
|
|
14797
|
+
const { first, held } = shipBatch.splitHalves(existing.members);
|
|
14798
|
+
splitHalf = { first, held, parentSize: existing.size ? existing.size.size : existing.members.length };
|
|
14799
|
+
print(`✗ ship-batch: the combined run is red at ${existing.ref}@${shortSha(existing.sha)} (${verdict.why}${verdict.attempt >= 2 ? ', after its one re-run' : ''}). Nothing landed.`);
|
|
14800
|
+
print(` splitting (#557): testing ${first.map((m) => m.branch).join(', ')} on the same base; held for the next batch: ${held.map((m) => m.branch).join(', ')}`);
|
|
14801
|
+
step = { step: 'build' };
|
|
14802
|
+
}
|
|
14211
14803
|
if (step.step === 'red-serial') {
|
|
14212
14804
|
print(`✗ ship-batch: the combined run is red again after its one re-run (${verdict.why}) — nothing landed; ${existing.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}.`);
|
|
14213
14805
|
deleteRef(existing.ref);
|
|
@@ -14240,13 +14832,21 @@ function cmdShipBatch(opts) {
|
|
|
14240
14832
|
// #387: a generated path shared by two members is not an overlap — the build regenerates it (below).
|
|
14241
14833
|
const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
|
|
14242
14834
|
const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
|
|
14243
|
-
|
|
14244
|
-
|
|
14835
|
+
// #557: a split builds exactly its first half, in the red batch's order — the pre-sort is not re-run,
|
|
14836
|
+
// or a different subset would be tested and the bisection would not narrow.
|
|
14837
|
+
const { selected, overflow } = splitHalf
|
|
14838
|
+
? (() => {
|
|
14839
|
+
const want = splitHalf.first.map((m) => m.branch);
|
|
14840
|
+
const sel = want.map((b) => eligible.find((e) => e.branch === b)).filter(Boolean);
|
|
14841
|
+
return { selected: sel, overflow: eligible.filter((e) => !sel.includes(e)) };
|
|
14842
|
+
})()
|
|
14843
|
+
: shipBatch.selectMembers(eligible, size, { isGenerated: (f) => isGeneratedPath(f, generated) });
|
|
14844
|
+
print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(trunkNow)} (${splitHalf ? `split of a red batch of ${splitHalf.first.length + splitHalf.held.length}` : sizeLabel})${opts.dry ? ' [DRY RUN]' : ''}`);
|
|
14245
14845
|
print(table(evaluated.map((e) => [e.ok ? (selected.includes(e) ? '✓' : '·') : '✗', e.branch,
|
|
14246
|
-
e.ok && !selected.includes(e) ? `eligible — waits for the next batch (cap ${
|
|
14846
|
+
e.ok && !selected.includes(e) ? (splitHalf ? 'eligible — held by the split for the next batch' : `eligible — waits for the next batch (cap ${size})`) : e.why]), ['', 'MEMBER', 'DETAIL']));
|
|
14247
14847
|
const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
|
|
14248
14848
|
step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
|
|
14249
|
-
if (step.step === '
|
|
14849
|
+
if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf) {
|
|
14250
14850
|
// #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
|
|
14251
14851
|
// member is ready. Wait for a partner until the repo's window, counted from when it became ready.
|
|
14252
14852
|
const lone = selected[0];
|
|
@@ -14256,13 +14856,13 @@ function cmdShipBatch(opts) {
|
|
|
14256
14856
|
if (pw.wait) {
|
|
14257
14857
|
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
14858
|
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
|
|
14859
|
+
print(' then run colab ship --batch with all of them. Past the window, this same call lands it alone, as a batch of one.');
|
|
14260
14860
|
return 3;
|
|
14261
14861
|
}
|
|
14262
14862
|
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
|
-
|
|
14863
|
+
print(` no partner arrived for ${lone.branch} — ${why}; building a batch of one (the combined run still gates it, #562)`);
|
|
14264
14864
|
}
|
|
14265
|
-
if (step.step === 'serial') return serial(
|
|
14865
|
+
if (step.step === 'serial') return serial('no member can join — each one above says why');
|
|
14266
14866
|
|
|
14267
14867
|
// ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
|
|
14268
14868
|
const ref = shipBatch.batchRefName(trunkNow);
|
|
@@ -14337,22 +14937,26 @@ function cmdShipBatch(opts) {
|
|
|
14337
14937
|
for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
|
|
14338
14938
|
// #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
|
|
14339
14939
|
// 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 (≥
|
|
14341
|
-
|
|
14940
|
+
// Only when the batch is built (≥1 member, #562): a build that collapses to serial pushes nothing.
|
|
14941
|
+
// #557: with steps declared (or on a split), the head also carries the size it was built at, so the
|
|
14942
|
+
// next build reads the lane's last outcome from trunk alone.
|
|
14943
|
+
const sizeLine = splitHalf ? shipBatch.sizeTrailer({ size: splitHalf.parentSize, red: true })
|
|
14944
|
+
: (stepsCfg.steps ? shipBatch.sizeTrailer({ size }) : null);
|
|
14945
|
+
if ((dropped.length || sizeLine) && built.length >= 1) {
|
|
14342
14946
|
const last = built[built.length - 1];
|
|
14343
14947
|
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 }));
|
|
14948
|
+
const lines = [...dropped.map((d) => shipBatch.droppedTrailer({ ref, branch: d.branch, sha: d.sha, cls: d.cls })), ...(sizeLine ? [sizeLine] : [])];
|
|
14345
14949
|
const am = cur.ok ? git.run('git', ['commit', '-q', '--amend', '-m', shipBatch.appendTrailers(cur.stdout, lines)], { cwd: dir }) : cur;
|
|
14346
14950
|
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)} —
|
|
14951
|
+
else warn(`could not record the dropped member(s)/size on the batch head: ${git.gitFailureLine(am.stderr)} — they are on this terminal only`);
|
|
14348
14952
|
}
|
|
14349
14953
|
for (const b of built.filter((x) => x.regenerated)) {
|
|
14350
14954
|
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)`);
|
|
14351
14955
|
}
|
|
14352
14956
|
const head = git.git(['rev-parse', 'HEAD'], dir).stdout;
|
|
14353
|
-
if (built.length <
|
|
14957
|
+
if (built.length < 1) {
|
|
14354
14958
|
cleanup();
|
|
14355
|
-
return serial(
|
|
14959
|
+
return serial('no member survived the build', members);
|
|
14356
14960
|
}
|
|
14357
14961
|
if (opts.dry) {
|
|
14358
14962
|
cleanup();
|
|
@@ -14366,7 +14970,7 @@ function cmdShipBatch(opts) {
|
|
|
14366
14970
|
cleanup();
|
|
14367
14971
|
if (!push.ok) throw new UserError(`could not push ${ref}: ${git.gitFailureLine(push.stderr)} — nothing landed`);
|
|
14368
14972
|
print(` pushed ${ref} = ${shortSha(trunkNow)} + ${built.length} commit(s) @ ${shortSha(head)} (${built.map((b) => b.branch).join(', ')})`);
|
|
14369
|
-
if (overflow.length) print(` eligible but over the cap (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
|
|
14973
|
+
if (overflow.length) print(` eligible but ${splitHalf ? 'held by the split' : 'over the cap'} (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
|
|
14370
14974
|
print(`⏸ BATCH-PENDING ${ref}@${shortSha(head)} — wait on the combined run (bounded, B1a), then run this command again. Nothing landed yet.`);
|
|
14371
14975
|
return 3;
|
|
14372
14976
|
}
|
|
@@ -14991,11 +15595,17 @@ its head, trunk runs say when a landing was pushed and when its trunk-CI cycle e
|
|
|
14991
15595
|
Reports:
|
|
14992
15596
|
batches landed, and their fill · combined-run builds: first-attempt green, green after the
|
|
14993
15597
|
one re-run, red, pending
|
|
14994
|
-
red red builds, and how many of their members then landed serially
|
|
15598
|
+
red red builds, and how many of their members then landed alone — serially, or as a
|
|
15599
|
+
batch of one (#580) — the fallback
|
|
14995
15600
|
dropped members dropped at build, by class, and the eviction rate
|
|
14996
15601
|
serial serial landings, and MISSED PARTNERS — another change, landed later, that was
|
|
14997
15602
|
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)
|
|
15603
|
+
this landing's trunk-CI cycle (a near miss; its wait is what ship-batch-wait buys).
|
|
15604
|
+
"serial" means landed through the serial path, and only that
|
|
15605
|
+
alone the same partner scan over every change that landed ALONE — serially or as a batch
|
|
15606
|
+
of one (#580). On a ship-batch repo a lone ready candidate lands as a fill-1 batch,
|
|
15607
|
+
so there serial reads zero either way; alone is the line to tune ship-batch-wait by.
|
|
15608
|
+
Printed only when a batch of one landed (otherwise it equals serial)
|
|
14999
15609
|
queue wait green-at-head → landing, per landed change
|
|
15000
15610
|
|
|
15001
15611
|
No batch history in the window is an answer, not an error: it says so, and still reports the
|
|
@@ -15014,6 +15624,9 @@ function batchStatsSince(v, nowMs) {
|
|
|
15014
15624
|
return Number.isFinite(t) ? t : null;
|
|
15015
15625
|
}
|
|
15016
15626
|
|
|
15627
|
+
/** The trunk log read's buffer (#585); COLAB_BATCH_STATS_MAX_BUFFER overrides it, for a test. */
|
|
15628
|
+
const BATCH_STATS_LOG_MAX_BUFFER = Number(process.env.COLAB_BATCH_STATS_MAX_BUFFER) || 256 * 1024 * 1024;
|
|
15629
|
+
|
|
15017
15630
|
function cmdBatchStats(argv) {
|
|
15018
15631
|
const opts = parseArgs(argv, {
|
|
15019
15632
|
values: { '--repo': 'repo', '--since': 'since' },
|
|
@@ -15034,7 +15647,11 @@ function cmdBatchStats(argv) {
|
|
|
15034
15647
|
const remote = git.remoteFor(repoAbs);
|
|
15035
15648
|
const f = git.git(['fetch', remote, trunk], repoAbs);
|
|
15036
15649
|
if (!f.ok) notes.push(`could not fetch ${remote}/${trunk} (${git.gitFailureLine(f.stderr)}) — read from the local copy, which may be behind`);
|
|
15037
|
-
|
|
15650
|
+
// Full squash bodies over a long window pass spawnSync's 1 MiB default (measured 2026-10-10:
|
|
15651
|
+
// 60 days of one repo's trunk came to 1,061,950 bytes), and ENOBUFS then read as a failed
|
|
15652
|
+
// fetch (#585). The buffer is sized for the read; a spawn error is reported as itself.
|
|
15653
|
+
const log = git.git(['log', `${remote}/${trunk}`, '--first-parent', `--since=${sinceIso}`, '--format=%H%x1f%cI%x1f%B%x1e'], repoAbs, { maxBuffer: BATCH_STATS_LOG_MAX_BUFFER });
|
|
15654
|
+
if (!log.ok && log.error) throw new UserError(`could not read ${remote}/${trunk}: ${git.gitFailureLine(log.stderr)} — pass a shorter --since, then run \`colab batch-stats\` again`);
|
|
15038
15655
|
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
15656
|
const commits = log.stdout.split('\x1e').map((r) => r.replace(/^\n/, '')).filter((r) => r.trim()).map((r) => {
|
|
15040
15657
|
const [sha, iso, body] = r.split('\x1f');
|
|
@@ -15100,12 +15717,17 @@ function cmdBatchStats(argv) {
|
|
|
15100
15717
|
else {
|
|
15101
15718
|
const fill = Object.keys(rep.batches.fill).sort().map((k) => `${rep.batches.fill[k]}×${k}`).join(' · ') || '—';
|
|
15102
15719
|
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.
|
|
15720
|
+
print(` red ${rep.red.builds} build(s) · ${rep.red.members} member(s), ${rep.red.relandedAlone} then landed alone (${rep.red.relandedSerially} serially · ${rep.red.relandedAlone - rep.red.relandedSerially} as a batch of one)`);
|
|
15104
15721
|
const cls = Object.entries(rep.dropped.byClass).map(([k, v]) => `${v} ${k}`).join(', ');
|
|
15105
15722
|
print(` dropped ${rep.dropped.count} of ${rep.dropped.attempted} attempted (${pct(rep.dropped.rate)})${cls ? ` — ${cls}` : ''}`);
|
|
15106
15723
|
}
|
|
15107
15724
|
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
15725
|
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)}`);
|
|
15726
|
+
if (rep.alone.batchOfOne) {
|
|
15727
|
+
// #580: a batch of one landed alone too — the serial line above cannot see it.
|
|
15728
|
+
print(` alone ${rep.alone.landings} landed alone (${rep.alone.landings - rep.alone.batchOfOne} serial · ${rep.alone.batchOfOne} batch of one) · ${rep.alone.withMissedPartner} with a missed partner (already green) · ${rep.alone.withNearMiss} more with a near miss`);
|
|
15729
|
+
if (rep.alone.nearMissWait.samples) print(` near misses (alone) ${q(rep.alone.nearMissWait)}`);
|
|
15730
|
+
}
|
|
15109
15731
|
print(` queue wait green-at-head → landing: ${q(rep.queueWait)}`);
|
|
15110
15732
|
for (const n of rep.notes) print(` ! ${n}`);
|
|
15111
15733
|
return 0;
|
|
@@ -15362,6 +15984,59 @@ Empty output is clean ground ONLY when the fetch succeeded. Exit: 0 answered, 2
|
|
|
15362
15984
|
staleness (fetch skipped or failed, and the result would have been "clean").
|
|
15363
15985
|
`;
|
|
15364
15986
|
|
|
15987
|
+
const HELP_INSTRUCTION_FILES = `colab instruction-files [--base <rev> | --staged] [--repo <path>] [--json]
|
|
15988
|
+
|
|
15989
|
+
Is every tracked CLAUDE.md the thin-shell shape — the \`@AGENTS.md\` import plus tool-managed blocks,
|
|
15990
|
+
with the repo's prose in AGENTS.md (CONVENTIONS.md §9 step 5, #588)? One judgement
|
|
15991
|
+
(tools/lib/instruction-file.js), shared with the audit, the pre-commit hook and the reusable CI
|
|
15992
|
+
workflow \`.github/workflows/instruction-files.yml\`.
|
|
15993
|
+
|
|
15994
|
+
--base <rev> RATCHET against merge-base(<rev>, HEAD). Fails only when a CLAUDE.md does not
|
|
15995
|
+
conform at HEAD AND either a CLAUDE.md/AGENTS.md changed since the merge base, or
|
|
15996
|
+
every CLAUDE.md conformed there. An unmigrated repo whose change leaves both files
|
|
15997
|
+
alone passes. This is what CI runs.
|
|
15998
|
+
--staged judge the INDEX against HEAD, same ratchet (staging a CLAUDE.md/AGENTS.md is
|
|
15999
|
+
touching it). This is what the pre-commit hook runs.
|
|
16000
|
+
(neither) judge every CLAUDE.md at HEAD, no ratchet: any non-conforming file fails.
|
|
16001
|
+
--repo <path> repo to run in (default: cwd)
|
|
16002
|
+
--json { ok, error?, mode, base, fail, reason, files: [{ path, conforming, message }], changed }
|
|
16003
|
+
|
|
16004
|
+
Exit: 0 pass · 1 fail · 2 cannot judge (not a repo, base not fetched — never read as a pass).
|
|
16005
|
+
The fix for a failure is always the same: move the prose to AGENTS.md (handbook-sync's graft step
|
|
16006
|
+
does the move), keeping CLAUDE.md to \`@AGENTS.md\`, blank lines and tool blocks.
|
|
16007
|
+
`;
|
|
16008
|
+
|
|
16009
|
+
function cmdInstructionFiles(argv) {
|
|
16010
|
+
const opts = parseArgs(argv, {
|
|
16011
|
+
values: { '--repo': 'repo', '--base': 'base' },
|
|
16012
|
+
flags: { '--json': 'json', '--staged': 'staged', '-h': 'help', '--help': 'help' },
|
|
16013
|
+
});
|
|
16014
|
+
if (opts.help) return print(HELP_INSTRUCTION_FILES);
|
|
16015
|
+
if (opts.staged && opts.base) throw new UserError('--staged and --base are two different questions — pass one: `colab instruction-files --staged` (a commit) or `colab instruction-files --base <rev>` (a branch)');
|
|
16016
|
+
// The tree you stand in, NOT resolveRepo's main checkout: from inside a linked worktree the hook
|
|
16017
|
+
// and CI must judge that worktree's index and HEAD, never trunk's.
|
|
16018
|
+
const at = opts.repo ? path.resolve(String(opts.repo)) : process.cwd();
|
|
16019
|
+
const cwd = git.repoRoot(at);
|
|
16020
|
+
if (!cwd) throw new UserError(`${at} is not inside a git repo — pass --repo <path>`);
|
|
16021
|
+
const r = instructionGate.gate({ cwd, staged: !!opts.staged, base: opts.base ? String(opts.base) : null });
|
|
16022
|
+
if (opts.json) {
|
|
16023
|
+
print(JSON.stringify(r, null, 2));
|
|
16024
|
+
return !r.ok ? 2 : r.fail ? 1 : 0;
|
|
16025
|
+
}
|
|
16026
|
+
const lines = instructionGate.describe(r);
|
|
16027
|
+
if (!r.ok) {
|
|
16028
|
+
process.stderr.write(`✗ instruction-files: ${lines[0]} — re-run once the base is fetched (\`git fetch origin\`), or run \`colab instruction-files\` with no --base to judge without the ratchet\n`);
|
|
16029
|
+
return 2;
|
|
16030
|
+
}
|
|
16031
|
+
if (r.fail) {
|
|
16032
|
+
process.stderr.write(`✗ instruction-files: CLAUDE.md carries repo prose — move it to AGENTS.md (\`colab instruction-files --help\`)\n`);
|
|
16033
|
+
for (const l of lines) process.stderr.write(` ${l}\n`);
|
|
16034
|
+
return 1;
|
|
16035
|
+
}
|
|
16036
|
+
for (const l of lines) print(r.bad.length ? `! ${l}` : `✓ ${l}`);
|
|
16037
|
+
return 0;
|
|
16038
|
+
}
|
|
16039
|
+
|
|
15365
16040
|
function cmdHolders(argv) {
|
|
15366
16041
|
const opts = parseArgs(argv, {
|
|
15367
16042
|
values: { '--repo': 'repo', '--base': 'base' },
|
|
@@ -15992,6 +16667,8 @@ Commands:
|
|
|
15992
16667
|
blocked <blocked> --by <blocker> [--clear --reason R [--force]] [--repo P]
|
|
15993
16668
|
own the blocked_by dependency-edge write (#251)
|
|
15994
16669
|
migration-grant <issue> --branch B | --revoke | --list [--json] human-only ship migration exemption (#98)
|
|
16670
|
+
owner-policy [show [--json]] | set migration-grant <human|reviewer|unset> owner-level grant policy,
|
|
16671
|
+
every repo the GitHub owner runs; set is human-only (#596)
|
|
15995
16672
|
decision <issue> --record --ruled-by N | --reopen --ruled-by N | --list [--json]
|
|
15996
16673
|
record/reopen a needs-decision answer (#121, #122)
|
|
15997
16674
|
ci-grant <issue> --branch B | --revoke | --list [--json] ship trunk-CI-green exemption: human, or ci-reviewer under opt-in (#105, #504)
|
|
@@ -16028,6 +16705,10 @@ Commands:
|
|
|
16028
16705
|
holders <path> [--base B] [--json] who else is holding <path> — refs that touched it and
|
|
16029
16706
|
have not landed on the base (filters the raw git-log
|
|
16030
16707
|
one-liner through \`landed\`'s content classification)
|
|
16708
|
+
instruction-files [--base B | --staged] [--json]
|
|
16709
|
+
CLAUDE.md is only @AGENTS.md + tool blocks? ratcheted:
|
|
16710
|
+
fails only where the change touches it or would regress
|
|
16711
|
+
a migrated repo (#588) — the hook and CI run this
|
|
16031
16712
|
promote [--repo P] [--message M] [--dry] trunk → main (--no-ff); gated by deploy + promotion; never tags
|
|
16032
16713
|
deliver [--repo P] [--dry] [--json] [--reopen] project.yml owner: only — open/refresh ONE PR
|
|
16033
16714
|
trunk → the owner's branch; never merges it (#394)
|
|
@@ -16100,6 +16781,7 @@ function main(argv) {
|
|
|
16100
16781
|
case 'readiness': return cmdReadiness(rest);
|
|
16101
16782
|
case 'blocked': return cmdBlocked(rest);
|
|
16102
16783
|
case 'migration-grant': return cmdMigrationGrant(rest);
|
|
16784
|
+
case 'owner-policy': return cmdOwnerPolicy(rest);
|
|
16103
16785
|
case 'decision': return cmdDecision(rest);
|
|
16104
16786
|
case 'ci-grant': return cmdCiGrant(rest);
|
|
16105
16787
|
case 'claims': return cmdClaims(rest);
|
|
@@ -16115,6 +16797,7 @@ function main(argv) {
|
|
|
16115
16797
|
case 'trunk-ci': return cmdTrunkCi(rest);
|
|
16116
16798
|
case 'ci-wait': return cmdCiWait(rest);
|
|
16117
16799
|
case 'holders': return cmdHolders(rest);
|
|
16800
|
+
case 'instruction-files': return cmdInstructionFiles(rest);
|
|
16118
16801
|
case 'promote': return cmdPromote(rest);
|
|
16119
16802
|
case 'deliver': return cmdDeliver(rest);
|
|
16120
16803
|
case 'doctor': return cmdDoctor(rest);
|