@futurelastic/colab-handbook 1.12.0-rc.45 → 1.12.0-rc.47
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/tools/colab +149 -17
- package/tools/lib/adopt.js +90 -0
- package/tools/lib/branch-name.js +29 -1
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -470,9 +470,14 @@ function remoteClaimConflicts(st, repoAbs, nums) {
|
|
|
470
470
|
const want = new Set(nums);
|
|
471
471
|
const records = [...Object.values(st.worktrees || {}), ...Object.values(st.claims || {})];
|
|
472
472
|
const ours = (b) => records.some((r) => r && r.repo === repoAbs && r.branch === b && machine.isLocal(r));
|
|
473
|
+
// #485: a dependabot ref, trunk and every declared integration: line are never a session's claim —
|
|
474
|
+
// their trailing digits are a version or an accident of naming. Same filter as code-sweep §1.3.
|
|
475
|
+
const doc = projectDoc(repoAbs);
|
|
476
|
+
const trunk = resolveTrunk(repoAbs, doc) || '';
|
|
477
|
+
const scope = { trunk, integration: trunk ? resolveIntegration(repoAbs, doc, trunk) : [] };
|
|
473
478
|
const conflicts = [];
|
|
474
479
|
for (const h of heads.heads) {
|
|
475
|
-
const carried =
|
|
480
|
+
const carried = branchName.claimIssueNumbers(h.branch, scope).filter((n) => want.has(n));
|
|
476
481
|
if (!carried.length || ours(h.branch)) continue;
|
|
477
482
|
for (const num of carried) conflicts.push({ num, remote, branch: h.branch, sha: h.sha });
|
|
478
483
|
}
|
|
@@ -7473,7 +7478,7 @@ const HELP_ADOPT = `colab adopt [--repo <path>] [--json] [--no-verify] [--axis a
|
|
|
7473
7478
|
[--writes <free|direct|isolated>] [--channels <c1,c2,...>]
|
|
7474
7479
|
[--production <url>|none] [--deploy <push-main|tag|manual|none>]
|
|
7475
7480
|
[--stack "<text>"] [--answered-by <name>] [--reason "<text>"]
|
|
7476
|
-
[--fork | --no-fork]
|
|
7481
|
+
[--fork | --no-fork] [--autonomy <manual|auto-trunk>] [--land]
|
|
7477
7482
|
|
|
7478
7483
|
Detects what a repo already states in .github/project.yml, ASKS a human only what could not be
|
|
7479
7484
|
detected (flags, or a forced multiple-choice menu at a TTY — every row is a numbered choice,
|
|
@@ -7504,7 +7509,32 @@ accepted and reads as free — no adopter's descriptor breaks, and none is re-as
|
|
|
7504
7509
|
named, and a new CLAUDE.md gets no AGENTS.md stub (CONVENTIONS.md §9,
|
|
7505
7510
|
"A fork of an upstream")
|
|
7506
7511
|
|
|
7507
|
-
|
|
7512
|
+
THE AUTONOMY GRANT AND --land (#481) — so a new repo's first branch is not hand-merged:
|
|
7513
|
+
|
|
7514
|
+
--autonomy auto-trunk records the maintainer's grant (project.yml autonomy:) with the same
|
|
7515
|
+
provenance comment as every answer. It EXPANDS permission (an agent may
|
|
7516
|
+
then complete Phase B through \`colab ship\`), so it carries the writes:
|
|
7517
|
+
direct bar: interactive TTY, OR COLAB_HUMAN=1 AND --answered-by <name>
|
|
7518
|
+
(exit 3 otherwise). Refused with ceremony: light (exit 5). manual (the
|
|
7519
|
+
default) is never gated. Append-only: a different value already declared
|
|
7520
|
+
is refused (exit 5) — change it by hand.
|
|
7521
|
+
--land commits what THIS run wrote — the descriptor, plus the thin-shell
|
|
7522
|
+
CLAUDE.md/AGENTS.md when written now — straight to trunk as its own
|
|
7523
|
+
commit, then pushes origin/<trunk>. It is the human's adoption act, not
|
|
7524
|
+
an agent's: COLAB_HUMAN=1 AND --answered-by are required, no TTY
|
|
7525
|
+
substitute (exit 3). It runs only on the checkout standing ON trunk, never
|
|
7526
|
+
with --local, and refuses before writing anything when origin's trunk is
|
|
7527
|
+
ahead (pull first). Run without new answers, it lands a descriptor an
|
|
7528
|
+
earlier adopt left uncommitted. No origin remote: commits only.
|
|
7529
|
+
|
|
7530
|
+
The shape it exists for: \`colab ship\` judges a branch's autonomy by the descriptor trunk
|
|
7531
|
+
carries. Land it first, and the follow-up branch (CI workflow, guards, docs) ships through the
|
|
7532
|
+
normal lane under the grant — no human merge of the adoption branch.
|
|
7533
|
+
|
|
7534
|
+
COLAB_HUMAN=1 colab adopt --exposure self --stack node --autonomy auto-trunk \\
|
|
7535
|
+
--answered-by "<name>" --land
|
|
7536
|
+
|
|
7537
|
+
Any answer flag (--room/--exposure/--writes/--channels/--production/--deploy/--stack/--autonomy) makes the
|
|
7508
7538
|
whole run NON-INTERACTIVE — it never half-prompts. With no answer flags and no TTY, and something
|
|
7509
7539
|
is still missing, this refuses in under a second, naming exactly which flags would answer it —
|
|
7510
7540
|
never hangs waiting on stdin nobody is at.
|
|
@@ -7610,7 +7640,7 @@ files is not an option (CONVENTIONS.md §9, "Working in a repo you don't own"):
|
|
|
7610
7640
|
block, topic, register, autopilot) and why.
|
|
7611
7641
|
|
|
7612
7642
|
Boundary: adopt writes the descriptor and nothing else — no labels, no topic, no CI template, no
|
|
7613
|
-
\`colab register\`, and it never commits. One exception (#417): on a repo with no descriptor before
|
|
7643
|
+
\`colab register\`, and it never commits unless --land asks it to (#481). One exception (#417): on a repo with no descriptor before
|
|
7614
7644
|
the run and no CLAUDE.md, plain adopt also writes the thin-shell CLAUDE.md (\`@AGENTS.md\` + the
|
|
7615
7645
|
filled Conventions block) and an AGENTS.md stub if none exists; an existing CLAUDE.md is never
|
|
7616
7646
|
touched, and --local never writes either. It ends with the machine-readable
|
|
@@ -8099,9 +8129,9 @@ async function cmdAdopt(argv) {
|
|
|
8099
8129
|
'--repo': 'repo', '--axis': 'axis', '--room': 'room', '--exposure': 'exposure',
|
|
8100
8130
|
'--writes': 'writes', '--channels': 'channels', '--production': 'production',
|
|
8101
8131
|
'--deploy': 'deploy', '--stack': 'stack', '--answered-by': 'answeredBy', '--reason': 'reason',
|
|
8102
|
-
'--trunk': 'trunk',
|
|
8132
|
+
'--trunk': 'trunk', '--autonomy': 'autonomy',
|
|
8103
8133
|
},
|
|
8104
|
-
flags: { '--json': 'json', '--no-verify': 'noVerify', '--local': 'local', '--no-labels': 'noLabels', '--fork': 'fork', '--no-fork': 'noFork', '-h': 'help', '--help': 'help' },
|
|
8134
|
+
flags: { '--json': 'json', '--no-verify': 'noVerify', '--local': 'local', '--no-labels': 'noLabels', '--fork': 'fork', '--no-fork': 'noFork', '--land': 'land', '-h': 'help', '--help': 'help' },
|
|
8105
8135
|
});
|
|
8106
8136
|
if (opts.help) return print(HELP_ADOPT);
|
|
8107
8137
|
if (opts.fork && opts.noFork) throw new UserError('--fork and --no-fork contradict each other — pass one');
|
|
@@ -8109,6 +8139,10 @@ async function cmdAdopt(argv) {
|
|
|
8109
8139
|
throw new UserError('--trunk only means something with --local — on an ordinary adoption trunk is DETECTED, never asked (CONVENTIONS.md §9)');
|
|
8110
8140
|
}
|
|
8111
8141
|
if (opts.noLabels && !opts.local) throw new UserError('--no-labels only means something with --local — plain adopt never touches labels');
|
|
8142
|
+
if (opts.land && opts.local) throw new UserError('--land cannot combine with --local — a local-only descriptor is never committed (CONVENTIONS.md §9)');
|
|
8143
|
+
if (opts.autonomy !== undefined && !adopt.VALID_AUTONOMY.has(opts.autonomy)) {
|
|
8144
|
+
throw new UserError(`--autonomy must be one of: ${[...adopt.VALID_AUTONOMY].join(', ')} (got ${JSON.stringify(opts.autonomy)})`);
|
|
8145
|
+
}
|
|
8112
8146
|
|
|
8113
8147
|
// --local (#393): the descriptor is machine state, not a committable source file — it lives in
|
|
8114
8148
|
// the MAIN checkout (where every worktree's `colab` call reads project.yml from, via
|
|
@@ -8139,9 +8173,33 @@ async function cmdAdopt(argv) {
|
|
|
8139
8173
|
const localAnswerFlag = ['room', 'exposure', 'writes', 'channels', 'production', 'deploy', 'stack'].some((k) => opts[k] !== undefined);
|
|
8140
8174
|
if (local && !localAnswerFlag && !requestedAxes.length && axisAuthority.axisOfRecord(cfg).source === 'exposure') axesToAsk = [];
|
|
8141
8175
|
|
|
8176
|
+
const isTTY = !!(process.stdin.isTTY && process.stdout.isTTY);
|
|
8177
|
+
const colabHuman = process.env.COLAB_HUMAN === '1';
|
|
8178
|
+
|
|
8179
|
+
// #481: --land preflight — every refusal here happens BEFORE anything is written, like the gates.
|
|
8180
|
+
let landTrunk = null;
|
|
8181
|
+
if (opts.land) {
|
|
8182
|
+
landTrunk = cfg.trunk ? String(cfg.trunk) : (extra.trunk || null);
|
|
8183
|
+
const cur = git.git(['symbolic-ref', '--short', 'HEAD'], repoAbs);
|
|
8184
|
+
const lv = adopt.landVerdict({ local: !!opts.local, colabHuman, answeredBy: opts.answeredBy || null,
|
|
8185
|
+
trunk: landTrunk, currentBranch: cur.ok && cur.stdout ? cur.stdout : null });
|
|
8186
|
+
if (!lv.ok) { warn(lv.message); return lv.exitCode; }
|
|
8187
|
+
const behind = adoptLandBehind(repoAbs, landTrunk);
|
|
8188
|
+
if (behind) { warn(behind); return 1; }
|
|
8189
|
+
}
|
|
8190
|
+
|
|
8191
|
+
// #481: --autonomy — the maintainer's grant, gated like writes: direct (it expands permission).
|
|
8192
|
+
let autonomyWrite = false;
|
|
8193
|
+
if (opts.autonomy !== undefined) {
|
|
8194
|
+
const av = adopt.autonomyGateVerdict({ autonomy: opts.autonomy, current: cfg.autonomy, ceremony: cfg.ceremony,
|
|
8195
|
+
isTTY, colabHuman, answeredBy: opts.answeredBy || null });
|
|
8196
|
+
if (!av.ok) { warn(av.message); return av.exitCode; }
|
|
8197
|
+
autonomyWrite = av.write;
|
|
8198
|
+
}
|
|
8199
|
+
|
|
8142
8200
|
// Already complete (and nothing forced): report, write nothing, exit 0 — except the one key a
|
|
8143
8201
|
// bare --local re-run still owes (#405): the `owner:` block, for a clone adopted before it existed.
|
|
8144
|
-
if (axesToAsk.length === 0 && opts.stack === undefined) {
|
|
8202
|
+
if (axesToAsk.length === 0 && opts.stack === undefined && !autonomyWrite) {
|
|
8145
8203
|
const backfill = localOwnerEntry(local, cfg, today());
|
|
8146
8204
|
if (backfill) {
|
|
8147
8205
|
fs.writeFileSync(descriptorFile, adopt.renderDescriptor(rawTextBefore, [backfill]));
|
|
@@ -8149,9 +8207,12 @@ async function cmdAdopt(argv) {
|
|
|
8149
8207
|
}
|
|
8150
8208
|
const verify = opts.noVerify ? null : adoptVerify(repoAbs);
|
|
8151
8209
|
const lf = local ? adoptLocalFinish(repoAbs, local, opts) : undefined;
|
|
8152
|
-
|
|
8210
|
+
const land = opts.land ? adoptLand(repoAbs, landTrunk, ['.github/project.yml'], opts.answeredBy) : undefined;
|
|
8211
|
+
const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
|
|
8212
|
+
if (opts.json) { print(JSON.stringify({ repo: repoAbs, ...report, verify, ...(backfill ? { written: [{ key: backfill.key, value: backfill.value }] } : {}), local: lf, land }, null, 2)); return rc; }
|
|
8153
8213
|
printAdoptReport(report, repoAbs, verify, lf);
|
|
8154
|
-
|
|
8214
|
+
printAdoptLand(land);
|
|
8215
|
+
return rc;
|
|
8155
8216
|
}
|
|
8156
8217
|
|
|
8157
8218
|
// `trunk` is DETECTED, never asked — no answer flag can supply it, and asking a human "what is
|
|
@@ -8166,9 +8227,9 @@ async function cmdAdopt(argv) {
|
|
|
8166
8227
|
return 1;
|
|
8167
8228
|
}
|
|
8168
8229
|
|
|
8169
|
-
|
|
8230
|
+
// --autonomy counts as an answer flag (#481): it makes the run non-interactive, never half-prompted.
|
|
8231
|
+
const answerFlagKeys = ['room', 'exposure', 'writes', 'channels', 'production', 'deploy', 'stack', 'autonomy'];
|
|
8170
8232
|
const anyAnswerFlagGiven = answerFlagKeys.some((k) => opts[k] !== undefined);
|
|
8171
|
-
const isTTY = !!(process.stdin.isTTY && process.stdout.isTTY);
|
|
8172
8233
|
|
|
8173
8234
|
// `stack` is REQUIRED by the audit but free-form, so it cannot always be detected — a
|
|
8174
8235
|
// manifest-less repo (a docs-only repo; this handbook's own shape) has zero candidates.
|
|
@@ -8183,7 +8244,8 @@ async function cmdAdopt(argv) {
|
|
|
8183
8244
|
let stackAnsweredInteractively = false;
|
|
8184
8245
|
if (axesToAsk.length === 0) {
|
|
8185
8246
|
answers = {};
|
|
8186
|
-
} else if (anyAnswerFlagGiven) {
|
|
8247
|
+
} else if (anyAnswerFlagGiven || (opts.land && !isTTY)) {
|
|
8248
|
+
// #481: a bare --land with no terminal lands what is already on disk — it never asks.
|
|
8187
8249
|
// Fully non-interactive: whatever flags were given get applied; anything still missing
|
|
8188
8250
|
// just stays missing (reported in "remaining"), never prompted for — half a prompt is worse
|
|
8189
8251
|
// than none. `stack` is the one exception: it is a required key, not an optional row, so an
|
|
@@ -8325,6 +8387,10 @@ async function cmdAdopt(argv) {
|
|
|
8325
8387
|
comment: `${adopt.provenanceComment('exposure', m)}${reasonSuffix}`,
|
|
8326
8388
|
});
|
|
8327
8389
|
}
|
|
8390
|
+
if (autonomyWrite) {
|
|
8391
|
+
entries.push({ key: 'autonomy', value: opts.autonomy, comment: adopt.provenanceComment('autonomy',
|
|
8392
|
+
{ mode: 'flag', flags: ['--autonomy'], date: nowDate, colabHuman, answeredBy: opts.answeredBy || null }) });
|
|
8393
|
+
}
|
|
8328
8394
|
// Fallback: exposure ends this run still unanswered (declined interactively, or simply not
|
|
8329
8395
|
// among the axes that got an answer this run) and no `tier` already exists — derive one from
|
|
8330
8396
|
// (production, deploy), using the EFFECTIVE values (this run's tier answer, if any, else what
|
|
@@ -8380,9 +8446,12 @@ async function cmdAdopt(argv) {
|
|
|
8380
8446
|
warn('nothing to write — every requested row was already answered, or nothing was supplied to answer it.');
|
|
8381
8447
|
const verify = opts.noVerify ? null : adoptVerify(repoAbs);
|
|
8382
8448
|
const lf = local ? adoptLocalFinish(repoAbs, local, opts) : undefined;
|
|
8383
|
-
|
|
8449
|
+
const land = opts.land ? adoptLand(repoAbs, landTrunk, ['.github/project.yml'], opts.answeredBy) : undefined;
|
|
8450
|
+
const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
|
|
8451
|
+
if (opts.json) { print(JSON.stringify({ repo: repoAbs, ...report, verify, written: [], local: lf, land }, null, 2)); return rc; }
|
|
8384
8452
|
printAdoptReport(report, repoAbs, verify, lf);
|
|
8385
|
-
|
|
8453
|
+
printAdoptLand(land);
|
|
8454
|
+
return rc;
|
|
8386
8455
|
}
|
|
8387
8456
|
|
|
8388
8457
|
const newText = adopt.renderDescriptor(rawTextBefore, entries);
|
|
@@ -8398,9 +8467,16 @@ async function cmdAdopt(argv) {
|
|
|
8398
8467
|
const shell = local || rawTextBefore !== null ? null : adoptWriteShell(repoAbs, after);
|
|
8399
8468
|
const verify = opts.noVerify ? null : adoptVerify(repoAbs);
|
|
8400
8469
|
const lf = local ? adoptLocalFinish(repoAbs, local, opts) : undefined;
|
|
8470
|
+
// #481: --land commits exactly what THIS run wrote — the descriptor, plus the thin shell when
|
|
8471
|
+
// it was written now — never anything else in the working tree.
|
|
8472
|
+
const landPaths = ['.github/project.yml'];
|
|
8473
|
+
if (shell && shell.claude === 'written') landPaths.push(CLAUDE_FILE);
|
|
8474
|
+
if (shell && shell.agents === 'written') landPaths.push('AGENTS.md');
|
|
8475
|
+
const land = opts.land ? adoptLand(repoAbs, landTrunk, landPaths, opts.answeredBy) : undefined;
|
|
8476
|
+
const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
|
|
8401
8477
|
if (opts.json) {
|
|
8402
|
-
print(JSON.stringify({ repo: repoAbs, ...after, verify, written: entries.map((e) => ({ key: e.key, value: e.value })), ...(shell ? { shell } : {}), local: lf }, null, 2));
|
|
8403
|
-
return
|
|
8478
|
+
print(JSON.stringify({ repo: repoAbs, ...after, verify, written: entries.map((e) => ({ key: e.key, value: e.value })), ...(shell ? { shell } : {}), local: lf, land }, null, 2));
|
|
8479
|
+
return rc;
|
|
8404
8480
|
}
|
|
8405
8481
|
for (const e of entries) print(`✓ wrote ${e.key}: ${fmtVal(e.value)}`);
|
|
8406
8482
|
if (shell) {
|
|
@@ -8411,7 +8487,63 @@ async function cmdAdopt(argv) {
|
|
|
8411
8487
|
}
|
|
8412
8488
|
print('');
|
|
8413
8489
|
printAdoptReport(after, repoAbs, verify, lf);
|
|
8414
|
-
|
|
8490
|
+
printAdoptLand(land);
|
|
8491
|
+
return rc;
|
|
8492
|
+
}
|
|
8493
|
+
|
|
8494
|
+
/**
|
|
8495
|
+
* #481 — `--land` preflight: is origin's trunk ahead of this checkout? Landing on a stale trunk
|
|
8496
|
+
* would either fail the push or need a merge, and adopt does neither on a human's behalf. Returns a
|
|
8497
|
+
* refusal message, or null. No origin remote, or no trunk there yet (a first push), is not behind.
|
|
8498
|
+
*/
|
|
8499
|
+
function adoptLandBehind(repoAbs, trunk) {
|
|
8500
|
+
if (!git.git(['remote', 'get-url', 'origin'], repoAbs).ok) return null;
|
|
8501
|
+
const f = git.git(['fetch', 'origin', trunk], repoAbs);
|
|
8502
|
+
if (!f.ok) {
|
|
8503
|
+
const remoteHas = git.git(['ls-remote', '--exit-code', '--heads', 'origin', trunk], repoAbs);
|
|
8504
|
+
if (remoteHas.ok) return `--land could not fetch origin/${trunk} — refusing to land on a trunk it cannot see: ${f.stderr || f.stdout}`;
|
|
8505
|
+
return null; // origin has no trunk yet: the landing push creates it
|
|
8506
|
+
}
|
|
8507
|
+
const anc = git.git(['merge-base', '--is-ancestor', 'FETCH_HEAD', 'HEAD'], repoAbs);
|
|
8508
|
+
if (anc.ok) return null;
|
|
8509
|
+
return `--land refuses: origin/${trunk} has commits this checkout does not — pull ${trunk} first, then re-run`;
|
|
8510
|
+
}
|
|
8511
|
+
|
|
8512
|
+
/**
|
|
8513
|
+
* #481 — commit `paths` (only those) onto trunk and push it. Called only after landVerdict passed
|
|
8514
|
+
* (COLAB_HUMAN=1 + --answered-by, standing on trunk), so the pre-push guard's COLAB_HUMAN door is
|
|
8515
|
+
* the one this push walks through — the same env the human set. Nothing staged for these paths
|
|
8516
|
+
* (already committed) is not an error: it still pushes a trunk that is ahead of origin.
|
|
8517
|
+
*/
|
|
8518
|
+
function adoptLand(repoAbs, trunk, paths, answeredBy) {
|
|
8519
|
+
const present = paths.filter((p) => fs.existsSync(path.join(repoAbs, p)));
|
|
8520
|
+
if (!present.length) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: 'no descriptor on disk to land' };
|
|
8521
|
+
const add = git.git(['add', '--', ...present], repoAbs);
|
|
8522
|
+
if (!add.ok) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: `git add failed: ${add.stderr || add.stdout}` };
|
|
8523
|
+
const staged = git.git(['diff', '--cached', '--name-only', '--', ...present], repoAbs);
|
|
8524
|
+
const committed = staged.ok && staged.stdout ? staged.stdout.split('\n').filter(Boolean) : [];
|
|
8525
|
+
if (committed.length) {
|
|
8526
|
+
const c = git.git(['commit', '--only', '-m', adopt.landCommitMessage({ answeredBy, paths: committed }), '--', ...committed], repoAbs);
|
|
8527
|
+
if (!c.ok) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: `git commit failed: ${c.stderr || c.stdout}` };
|
|
8528
|
+
}
|
|
8529
|
+
const head = git.git(['rev-parse', 'HEAD'], repoAbs);
|
|
8530
|
+
const sha = head.ok ? head.stdout : null;
|
|
8531
|
+
if (!git.git(['remote', 'get-url', 'origin'], repoAbs).ok) {
|
|
8532
|
+
return { ok: true, trunk, committed, sha, pushed: false, note: 'no origin remote — committed locally; the first push of trunk carries it' };
|
|
8533
|
+
}
|
|
8534
|
+
const p = git.git(['push', 'origin', `HEAD:refs/heads/${trunk}`], repoAbs);
|
|
8535
|
+
if (!p.ok) return { ok: false, trunk, committed, sha, pushed: false, error: `committed ${shortSha(sha)} on ${trunk}, but the push failed: ${p.stderr || p.stdout}` };
|
|
8536
|
+
return { ok: true, trunk, committed, sha, pushed: true };
|
|
8537
|
+
}
|
|
8538
|
+
|
|
8539
|
+
function printAdoptLand(land) {
|
|
8540
|
+
if (!land) return;
|
|
8541
|
+
print('');
|
|
8542
|
+
if (!land.ok) { print(`✗ land: ${land.error}`); return; }
|
|
8543
|
+
const what = land.committed.length ? `committed ${land.committed.join(', ')} as ${shortSha(land.sha)}` : `nothing new to commit (trunk at ${shortSha(land.sha)})`;
|
|
8544
|
+
print(`✓ land: ${what} on ${land.trunk}${land.pushed ? ` — pushed to origin/${land.trunk}` : ''}`);
|
|
8545
|
+
if (land.note) print(` ${land.note}`);
|
|
8546
|
+
print(' The follow-up branch (CI, guards, docs) is judged by this descriptor — ship it through the normal lane.');
|
|
8415
8547
|
}
|
|
8416
8548
|
|
|
8417
8549
|
/**
|
package/tools/lib/adopt.js
CHANGED
|
@@ -847,6 +847,92 @@ function writesGateVerdict({ writes, effExposure, isTTY, colabHuman, answeredBy
|
|
|
847
847
|
return { ok: true };
|
|
848
848
|
}
|
|
849
849
|
|
|
850
|
+
const VALID_AUTONOMY = new Set(['manual', 'auto-trunk']);
|
|
851
|
+
|
|
852
|
+
/**
|
|
853
|
+
* #481 — `--autonomy` on `colab adopt`: the maintainer's grant recorded at adoption, so the
|
|
854
|
+
* descriptor trunk carries from its first commit already says whether an agent may complete
|
|
855
|
+
* Phase B. `auto-trunk` is the one value that EXPANDS permission (an unattended trunk merge
|
|
856
|
+
* through `colab ship`), so it carries the same human bar as `writes: direct`; `manual` is the
|
|
857
|
+
* default and never gated. Append-only like every other answer: a value already on record is
|
|
858
|
+
* either the same (no-op) or a hand edit, never overwritten here.
|
|
859
|
+
*
|
|
860
|
+
* Returns `{ ok, write }` — `write` false when the same value is already declared — or a refusal
|
|
861
|
+
* `{ ok:false, class, exitCode, message }`. Pure: cmdAdopt passes every fact in.
|
|
862
|
+
*/
|
|
863
|
+
function autonomyGateVerdict({ autonomy, current, ceremony, isTTY, colabHuman, answeredBy }) {
|
|
864
|
+
if (!VALID_AUTONOMY.has(autonomy)) {
|
|
865
|
+
throw new UserError(`--autonomy must be one of: ${[...VALID_AUTONOMY].join(', ')} (got ${JSON.stringify(autonomy)})`);
|
|
866
|
+
}
|
|
867
|
+
if (current !== undefined && current !== null) {
|
|
868
|
+
if (String(current) === autonomy) return { ok: true, write: false };
|
|
869
|
+
return {
|
|
870
|
+
ok: false,
|
|
871
|
+
class: GATE_CLASS.REPO_SHAPE,
|
|
872
|
+
exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
|
|
873
|
+
message: `project.yml already declares autonomy: ${current} — adopt is append-only and never `
|
|
874
|
+
+ 'rewrites a declared key; change it by hand, as its own reviewed commit',
|
|
875
|
+
};
|
|
876
|
+
}
|
|
877
|
+
if (autonomy !== 'auto-trunk') return { ok: true, write: true };
|
|
878
|
+
if (ceremony === 'light') {
|
|
879
|
+
return {
|
|
880
|
+
ok: false,
|
|
881
|
+
class: GATE_CLASS.REPO_SHAPE,
|
|
882
|
+
exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
|
|
883
|
+
message: 'autonomy: auto-trunk is refused alongside ceremony: light — an unattended merge with '
|
|
884
|
+
+ 'the ceremony skipped is the one combination the handbook forbids (CONVENTIONS.md §2)',
|
|
885
|
+
};
|
|
886
|
+
}
|
|
887
|
+
if (!(isTTY || (colabHuman && answeredBy))) {
|
|
888
|
+
return {
|
|
889
|
+
ok: false,
|
|
890
|
+
class: GATE_CLASS.HUMAN_GATED,
|
|
891
|
+
exitCode: EXIT_CODE[GATE_CLASS.HUMAN_GATED],
|
|
892
|
+
message: 'declaring autonomy: auto-trunk requires a human: answer at an interactive terminal, or '
|
|
893
|
+
+ 're-run with COLAB_HUMAN=1 and --answered-by "<name>" — it grants agents the trunk merge',
|
|
894
|
+
};
|
|
895
|
+
}
|
|
896
|
+
return { ok: true, write: true };
|
|
897
|
+
}
|
|
898
|
+
|
|
899
|
+
/**
|
|
900
|
+
* #481 — may `colab adopt --land` commit the descriptor straight to trunk? Landing writes trunk,
|
|
901
|
+
* so it is the human's act and never an agent's: COLAB_HUMAN=1 AND --answered-by, no TTY
|
|
902
|
+
* substitute (a TTY proves a terminal, not that this particular write was asked for). It runs only
|
|
903
|
+
* on a checkout standing ON trunk, never --local (a local descriptor is machine state, never
|
|
904
|
+
* committed). Pure.
|
|
905
|
+
*/
|
|
906
|
+
function landVerdict({ local, colabHuman, answeredBy, trunk, currentBranch }) {
|
|
907
|
+
if (local) {
|
|
908
|
+
return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
|
|
909
|
+
message: '--land cannot combine with --local — a local-only descriptor is never committed (CONVENTIONS.md §9)' };
|
|
910
|
+
}
|
|
911
|
+
if (!(colabHuman && answeredBy)) {
|
|
912
|
+
return { ok: false, class: GATE_CLASS.HUMAN_GATED, exitCode: EXIT_CODE[GATE_CLASS.HUMAN_GATED],
|
|
913
|
+
message: '--land commits to trunk, which is a human act: re-run with COLAB_HUMAN=1 and --answered-by "<name>"' };
|
|
914
|
+
}
|
|
915
|
+
if (!trunk) {
|
|
916
|
+
return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
|
|
917
|
+
message: '--land needs a trunk, and none could be determined' };
|
|
918
|
+
}
|
|
919
|
+
if (currentBranch !== trunk) {
|
|
920
|
+
return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
|
|
921
|
+
message: `--land runs on the trunk checkout: this checkout is on ${currentBranch ? JSON.stringify(currentBranch) : 'no branch'}, trunk is ${JSON.stringify(trunk)} — `
|
|
922
|
+
+ `run it from the checkout standing on ${trunk}` };
|
|
923
|
+
}
|
|
924
|
+
return { ok: true };
|
|
925
|
+
}
|
|
926
|
+
|
|
927
|
+
/** The commit message `--land` writes. Conventional, so it is visible in release notes. */
|
|
928
|
+
function landCommitMessage({ answeredBy, paths }) {
|
|
929
|
+
return 'chore: adopt the colab-handbook conventions — land the descriptor on trunk\n\n'
|
|
930
|
+
+ `Committed by \`colab adopt --land\` (COLAB_HUMAN=1, --answered-by ${JSON.stringify(answeredBy)}): `
|
|
931
|
+
+ 'the maintainer\'s adoption answers, on trunk from its first commit, so the branch that adds '
|
|
932
|
+
+ 'CI is judged by them.\n\n'
|
|
933
|
+
+ `Paths: ${paths.join(', ')}\n`;
|
|
934
|
+
}
|
|
935
|
+
|
|
850
936
|
// ---------------------------------------------------------------------- provenance + the append-only write
|
|
851
937
|
|
|
852
938
|
/** The comment placed beside a written key — never trusted as identity (see gateVerdict's
|
|
@@ -982,6 +1068,10 @@ module.exports = {
|
|
|
982
1068
|
exposureShapeVerdict,
|
|
983
1069
|
gateVerdict,
|
|
984
1070
|
writesGateVerdict,
|
|
1071
|
+
VALID_AUTONOMY,
|
|
1072
|
+
autonomyGateVerdict,
|
|
1073
|
+
landVerdict,
|
|
1074
|
+
landCommitMessage,
|
|
985
1075
|
provenanceComment,
|
|
986
1076
|
renderDescriptor,
|
|
987
1077
|
};
|
package/tools/lib/branch-name.js
CHANGED
|
@@ -54,6 +54,34 @@ function branchIssueNumbers(branchName) {
|
|
|
54
54
|
return m[1].split('-').map(Number).filter((n) => Number.isInteger(n) && n > 0);
|
|
55
55
|
}
|
|
56
56
|
|
|
57
|
+
/**
|
|
58
|
+
* Ref-name prefixes owned by a dependency bot, never by a session (#485). Dependabot names its
|
|
59
|
+
* branches after the version it bumps to — `dependabot/github_actions/actions/github-script-9` —
|
|
60
|
+
* so the trailing run is a MAJOR VERSION, not an issue number, and reading it as one makes an
|
|
61
|
+
* unrelated issue look held. `code-sweep` §1.3 drops the same prefix with `grep -v '^dependabot/'`;
|
|
62
|
+
* keep the two in step.
|
|
63
|
+
*/
|
|
64
|
+
const BOT_BRANCH_PREFIXES = ['dependabot/'];
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Issue numbers a branch carries AS A CLAIM — `branchIssueNumbers`, minus every ref that can only
|
|
68
|
+
* be a false positive (#485): a dependency bot's branch (`BOT_BRANCH_PREFIXES`), `HEAD`, the
|
|
69
|
+
* declared trunk, and any declared `integration:` line. Those are long-lived lines or tool-owned
|
|
70
|
+
* refs whose trailing digits mean something else; a match against one would refuse a claim that
|
|
71
|
+
* nobody holds and teach the session to reach for `--force` — the one flag that also bypasses a
|
|
72
|
+
* real holder. Returns [] for an excluded ref, exactly like a name with no trailing run.
|
|
73
|
+
*
|
|
74
|
+
* `branchIssueNumbers` itself stays unfiltered on purpose: ship's harvest reads the session's OWN
|
|
75
|
+
* branch, which can never be one of these.
|
|
76
|
+
*/
|
|
77
|
+
function claimIssueNumbers(branchName, { trunk = '', integration = [] } = {}) {
|
|
78
|
+
const b = String(branchName || '');
|
|
79
|
+
if (!b || b === 'HEAD' || (trunk && b === trunk)) return [];
|
|
80
|
+
if (BOT_BRANCH_PREFIXES.some((p) => b.startsWith(p))) return [];
|
|
81
|
+
if ((integration || []).includes(b)) return [];
|
|
82
|
+
return branchIssueNumbers(b);
|
|
83
|
+
}
|
|
84
|
+
|
|
57
85
|
/**
|
|
58
86
|
* A §4-conforming name → `{ login, machine, type, rest, slug, issues, prefixed }`, or `null` when the
|
|
59
87
|
* name conforms to neither shape. `rest` is `<slug>-<N…>` (everything after the type); `slug` is
|
|
@@ -133,5 +161,5 @@ function worktreeName(branch) {
|
|
|
133
161
|
|
|
134
162
|
module.exports = {
|
|
135
163
|
TYPES, BRANCH_RE_SOURCE, BRANCH_RE,
|
|
136
|
-
branchIssueNumbers, parse, format, machineLabel, sessionBranch, worktreeName,
|
|
164
|
+
branchIssueNumbers, claimIssueNumbers, BOT_BRANCH_PREFIXES, parse, format, machineLabel, sessionBranch, worktreeName,
|
|
137
165
|
};
|