@futurelastic/colab-handbook 1.12.0-rc.45 → 1.12.0-rc.46
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 +143 -16
- package/tools/lib/adopt.js +90 -0
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -7473,7 +7473,7 @@ const HELP_ADOPT = `colab adopt [--repo <path>] [--json] [--no-verify] [--axis a
|
|
|
7473
7473
|
[--writes <free|direct|isolated>] [--channels <c1,c2,...>]
|
|
7474
7474
|
[--production <url>|none] [--deploy <push-main|tag|manual|none>]
|
|
7475
7475
|
[--stack "<text>"] [--answered-by <name>] [--reason "<text>"]
|
|
7476
|
-
[--fork | --no-fork]
|
|
7476
|
+
[--fork | --no-fork] [--autonomy <manual|auto-trunk>] [--land]
|
|
7477
7477
|
|
|
7478
7478
|
Detects what a repo already states in .github/project.yml, ASKS a human only what could not be
|
|
7479
7479
|
detected (flags, or a forced multiple-choice menu at a TTY — every row is a numbered choice,
|
|
@@ -7504,7 +7504,32 @@ accepted and reads as free — no adopter's descriptor breaks, and none is re-as
|
|
|
7504
7504
|
named, and a new CLAUDE.md gets no AGENTS.md stub (CONVENTIONS.md §9,
|
|
7505
7505
|
"A fork of an upstream")
|
|
7506
7506
|
|
|
7507
|
-
|
|
7507
|
+
THE AUTONOMY GRANT AND --land (#481) — so a new repo's first branch is not hand-merged:
|
|
7508
|
+
|
|
7509
|
+
--autonomy auto-trunk records the maintainer's grant (project.yml autonomy:) with the same
|
|
7510
|
+
provenance comment as every answer. It EXPANDS permission (an agent may
|
|
7511
|
+
then complete Phase B through \`colab ship\`), so it carries the writes:
|
|
7512
|
+
direct bar: interactive TTY, OR COLAB_HUMAN=1 AND --answered-by <name>
|
|
7513
|
+
(exit 3 otherwise). Refused with ceremony: light (exit 5). manual (the
|
|
7514
|
+
default) is never gated. Append-only: a different value already declared
|
|
7515
|
+
is refused (exit 5) — change it by hand.
|
|
7516
|
+
--land commits what THIS run wrote — the descriptor, plus the thin-shell
|
|
7517
|
+
CLAUDE.md/AGENTS.md when written now — straight to trunk as its own
|
|
7518
|
+
commit, then pushes origin/<trunk>. It is the human's adoption act, not
|
|
7519
|
+
an agent's: COLAB_HUMAN=1 AND --answered-by are required, no TTY
|
|
7520
|
+
substitute (exit 3). It runs only on the checkout standing ON trunk, never
|
|
7521
|
+
with --local, and refuses before writing anything when origin's trunk is
|
|
7522
|
+
ahead (pull first). Run without new answers, it lands a descriptor an
|
|
7523
|
+
earlier adopt left uncommitted. No origin remote: commits only.
|
|
7524
|
+
|
|
7525
|
+
The shape it exists for: \`colab ship\` judges a branch's autonomy by the descriptor trunk
|
|
7526
|
+
carries. Land it first, and the follow-up branch (CI workflow, guards, docs) ships through the
|
|
7527
|
+
normal lane under the grant — no human merge of the adoption branch.
|
|
7528
|
+
|
|
7529
|
+
COLAB_HUMAN=1 colab adopt --exposure self --stack node --autonomy auto-trunk \\
|
|
7530
|
+
--answered-by "<name>" --land
|
|
7531
|
+
|
|
7532
|
+
Any answer flag (--room/--exposure/--writes/--channels/--production/--deploy/--stack/--autonomy) makes the
|
|
7508
7533
|
whole run NON-INTERACTIVE — it never half-prompts. With no answer flags and no TTY, and something
|
|
7509
7534
|
is still missing, this refuses in under a second, naming exactly which flags would answer it —
|
|
7510
7535
|
never hangs waiting on stdin nobody is at.
|
|
@@ -7610,7 +7635,7 @@ files is not an option (CONVENTIONS.md §9, "Working in a repo you don't own"):
|
|
|
7610
7635
|
block, topic, register, autopilot) and why.
|
|
7611
7636
|
|
|
7612
7637
|
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
|
|
7638
|
+
\`colab register\`, and it never commits unless --land asks it to (#481). One exception (#417): on a repo with no descriptor before
|
|
7614
7639
|
the run and no CLAUDE.md, plain adopt also writes the thin-shell CLAUDE.md (\`@AGENTS.md\` + the
|
|
7615
7640
|
filled Conventions block) and an AGENTS.md stub if none exists; an existing CLAUDE.md is never
|
|
7616
7641
|
touched, and --local never writes either. It ends with the machine-readable
|
|
@@ -8099,9 +8124,9 @@ async function cmdAdopt(argv) {
|
|
|
8099
8124
|
'--repo': 'repo', '--axis': 'axis', '--room': 'room', '--exposure': 'exposure',
|
|
8100
8125
|
'--writes': 'writes', '--channels': 'channels', '--production': 'production',
|
|
8101
8126
|
'--deploy': 'deploy', '--stack': 'stack', '--answered-by': 'answeredBy', '--reason': 'reason',
|
|
8102
|
-
'--trunk': 'trunk',
|
|
8127
|
+
'--trunk': 'trunk', '--autonomy': 'autonomy',
|
|
8103
8128
|
},
|
|
8104
|
-
flags: { '--json': 'json', '--no-verify': 'noVerify', '--local': 'local', '--no-labels': 'noLabels', '--fork': 'fork', '--no-fork': 'noFork', '-h': 'help', '--help': 'help' },
|
|
8129
|
+
flags: { '--json': 'json', '--no-verify': 'noVerify', '--local': 'local', '--no-labels': 'noLabels', '--fork': 'fork', '--no-fork': 'noFork', '--land': 'land', '-h': 'help', '--help': 'help' },
|
|
8105
8130
|
});
|
|
8106
8131
|
if (opts.help) return print(HELP_ADOPT);
|
|
8107
8132
|
if (opts.fork && opts.noFork) throw new UserError('--fork and --no-fork contradict each other — pass one');
|
|
@@ -8109,6 +8134,10 @@ async function cmdAdopt(argv) {
|
|
|
8109
8134
|
throw new UserError('--trunk only means something with --local — on an ordinary adoption trunk is DETECTED, never asked (CONVENTIONS.md §9)');
|
|
8110
8135
|
}
|
|
8111
8136
|
if (opts.noLabels && !opts.local) throw new UserError('--no-labels only means something with --local — plain adopt never touches labels');
|
|
8137
|
+
if (opts.land && opts.local) throw new UserError('--land cannot combine with --local — a local-only descriptor is never committed (CONVENTIONS.md §9)');
|
|
8138
|
+
if (opts.autonomy !== undefined && !adopt.VALID_AUTONOMY.has(opts.autonomy)) {
|
|
8139
|
+
throw new UserError(`--autonomy must be one of: ${[...adopt.VALID_AUTONOMY].join(', ')} (got ${JSON.stringify(opts.autonomy)})`);
|
|
8140
|
+
}
|
|
8112
8141
|
|
|
8113
8142
|
// --local (#393): the descriptor is machine state, not a committable source file — it lives in
|
|
8114
8143
|
// the MAIN checkout (where every worktree's `colab` call reads project.yml from, via
|
|
@@ -8139,9 +8168,33 @@ async function cmdAdopt(argv) {
|
|
|
8139
8168
|
const localAnswerFlag = ['room', 'exposure', 'writes', 'channels', 'production', 'deploy', 'stack'].some((k) => opts[k] !== undefined);
|
|
8140
8169
|
if (local && !localAnswerFlag && !requestedAxes.length && axisAuthority.axisOfRecord(cfg).source === 'exposure') axesToAsk = [];
|
|
8141
8170
|
|
|
8171
|
+
const isTTY = !!(process.stdin.isTTY && process.stdout.isTTY);
|
|
8172
|
+
const colabHuman = process.env.COLAB_HUMAN === '1';
|
|
8173
|
+
|
|
8174
|
+
// #481: --land preflight — every refusal here happens BEFORE anything is written, like the gates.
|
|
8175
|
+
let landTrunk = null;
|
|
8176
|
+
if (opts.land) {
|
|
8177
|
+
landTrunk = cfg.trunk ? String(cfg.trunk) : (extra.trunk || null);
|
|
8178
|
+
const cur = git.git(['symbolic-ref', '--short', 'HEAD'], repoAbs);
|
|
8179
|
+
const lv = adopt.landVerdict({ local: !!opts.local, colabHuman, answeredBy: opts.answeredBy || null,
|
|
8180
|
+
trunk: landTrunk, currentBranch: cur.ok && cur.stdout ? cur.stdout : null });
|
|
8181
|
+
if (!lv.ok) { warn(lv.message); return lv.exitCode; }
|
|
8182
|
+
const behind = adoptLandBehind(repoAbs, landTrunk);
|
|
8183
|
+
if (behind) { warn(behind); return 1; }
|
|
8184
|
+
}
|
|
8185
|
+
|
|
8186
|
+
// #481: --autonomy — the maintainer's grant, gated like writes: direct (it expands permission).
|
|
8187
|
+
let autonomyWrite = false;
|
|
8188
|
+
if (opts.autonomy !== undefined) {
|
|
8189
|
+
const av = adopt.autonomyGateVerdict({ autonomy: opts.autonomy, current: cfg.autonomy, ceremony: cfg.ceremony,
|
|
8190
|
+
isTTY, colabHuman, answeredBy: opts.answeredBy || null });
|
|
8191
|
+
if (!av.ok) { warn(av.message); return av.exitCode; }
|
|
8192
|
+
autonomyWrite = av.write;
|
|
8193
|
+
}
|
|
8194
|
+
|
|
8142
8195
|
// Already complete (and nothing forced): report, write nothing, exit 0 — except the one key a
|
|
8143
8196
|
// 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) {
|
|
8197
|
+
if (axesToAsk.length === 0 && opts.stack === undefined && !autonomyWrite) {
|
|
8145
8198
|
const backfill = localOwnerEntry(local, cfg, today());
|
|
8146
8199
|
if (backfill) {
|
|
8147
8200
|
fs.writeFileSync(descriptorFile, adopt.renderDescriptor(rawTextBefore, [backfill]));
|
|
@@ -8149,9 +8202,12 @@ async function cmdAdopt(argv) {
|
|
|
8149
8202
|
}
|
|
8150
8203
|
const verify = opts.noVerify ? null : adoptVerify(repoAbs);
|
|
8151
8204
|
const lf = local ? adoptLocalFinish(repoAbs, local, opts) : undefined;
|
|
8152
|
-
|
|
8205
|
+
const land = opts.land ? adoptLand(repoAbs, landTrunk, ['.github/project.yml'], opts.answeredBy) : undefined;
|
|
8206
|
+
const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
|
|
8207
|
+
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
8208
|
printAdoptReport(report, repoAbs, verify, lf);
|
|
8154
|
-
|
|
8209
|
+
printAdoptLand(land);
|
|
8210
|
+
return rc;
|
|
8155
8211
|
}
|
|
8156
8212
|
|
|
8157
8213
|
// `trunk` is DETECTED, never asked — no answer flag can supply it, and asking a human "what is
|
|
@@ -8166,9 +8222,9 @@ async function cmdAdopt(argv) {
|
|
|
8166
8222
|
return 1;
|
|
8167
8223
|
}
|
|
8168
8224
|
|
|
8169
|
-
|
|
8225
|
+
// --autonomy counts as an answer flag (#481): it makes the run non-interactive, never half-prompted.
|
|
8226
|
+
const answerFlagKeys = ['room', 'exposure', 'writes', 'channels', 'production', 'deploy', 'stack', 'autonomy'];
|
|
8170
8227
|
const anyAnswerFlagGiven = answerFlagKeys.some((k) => opts[k] !== undefined);
|
|
8171
|
-
const isTTY = !!(process.stdin.isTTY && process.stdout.isTTY);
|
|
8172
8228
|
|
|
8173
8229
|
// `stack` is REQUIRED by the audit but free-form, so it cannot always be detected — a
|
|
8174
8230
|
// manifest-less repo (a docs-only repo; this handbook's own shape) has zero candidates.
|
|
@@ -8183,7 +8239,8 @@ async function cmdAdopt(argv) {
|
|
|
8183
8239
|
let stackAnsweredInteractively = false;
|
|
8184
8240
|
if (axesToAsk.length === 0) {
|
|
8185
8241
|
answers = {};
|
|
8186
|
-
} else if (anyAnswerFlagGiven) {
|
|
8242
|
+
} else if (anyAnswerFlagGiven || (opts.land && !isTTY)) {
|
|
8243
|
+
// #481: a bare --land with no terminal lands what is already on disk — it never asks.
|
|
8187
8244
|
// Fully non-interactive: whatever flags were given get applied; anything still missing
|
|
8188
8245
|
// just stays missing (reported in "remaining"), never prompted for — half a prompt is worse
|
|
8189
8246
|
// than none. `stack` is the one exception: it is a required key, not an optional row, so an
|
|
@@ -8325,6 +8382,10 @@ async function cmdAdopt(argv) {
|
|
|
8325
8382
|
comment: `${adopt.provenanceComment('exposure', m)}${reasonSuffix}`,
|
|
8326
8383
|
});
|
|
8327
8384
|
}
|
|
8385
|
+
if (autonomyWrite) {
|
|
8386
|
+
entries.push({ key: 'autonomy', value: opts.autonomy, comment: adopt.provenanceComment('autonomy',
|
|
8387
|
+
{ mode: 'flag', flags: ['--autonomy'], date: nowDate, colabHuman, answeredBy: opts.answeredBy || null }) });
|
|
8388
|
+
}
|
|
8328
8389
|
// Fallback: exposure ends this run still unanswered (declined interactively, or simply not
|
|
8329
8390
|
// among the axes that got an answer this run) and no `tier` already exists — derive one from
|
|
8330
8391
|
// (production, deploy), using the EFFECTIVE values (this run's tier answer, if any, else what
|
|
@@ -8380,9 +8441,12 @@ async function cmdAdopt(argv) {
|
|
|
8380
8441
|
warn('nothing to write — every requested row was already answered, or nothing was supplied to answer it.');
|
|
8381
8442
|
const verify = opts.noVerify ? null : adoptVerify(repoAbs);
|
|
8382
8443
|
const lf = local ? adoptLocalFinish(repoAbs, local, opts) : undefined;
|
|
8383
|
-
|
|
8444
|
+
const land = opts.land ? adoptLand(repoAbs, landTrunk, ['.github/project.yml'], opts.answeredBy) : undefined;
|
|
8445
|
+
const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
|
|
8446
|
+
if (opts.json) { print(JSON.stringify({ repo: repoAbs, ...report, verify, written: [], local: lf, land }, null, 2)); return rc; }
|
|
8384
8447
|
printAdoptReport(report, repoAbs, verify, lf);
|
|
8385
|
-
|
|
8448
|
+
printAdoptLand(land);
|
|
8449
|
+
return rc;
|
|
8386
8450
|
}
|
|
8387
8451
|
|
|
8388
8452
|
const newText = adopt.renderDescriptor(rawTextBefore, entries);
|
|
@@ -8398,9 +8462,16 @@ async function cmdAdopt(argv) {
|
|
|
8398
8462
|
const shell = local || rawTextBefore !== null ? null : adoptWriteShell(repoAbs, after);
|
|
8399
8463
|
const verify = opts.noVerify ? null : adoptVerify(repoAbs);
|
|
8400
8464
|
const lf = local ? adoptLocalFinish(repoAbs, local, opts) : undefined;
|
|
8465
|
+
// #481: --land commits exactly what THIS run wrote — the descriptor, plus the thin shell when
|
|
8466
|
+
// it was written now — never anything else in the working tree.
|
|
8467
|
+
const landPaths = ['.github/project.yml'];
|
|
8468
|
+
if (shell && shell.claude === 'written') landPaths.push(CLAUDE_FILE);
|
|
8469
|
+
if (shell && shell.agents === 'written') landPaths.push('AGENTS.md');
|
|
8470
|
+
const land = opts.land ? adoptLand(repoAbs, landTrunk, landPaths, opts.answeredBy) : undefined;
|
|
8471
|
+
const rc = (lf && !lf.ok) || (land && !land.ok) ? 1 : 0;
|
|
8401
8472
|
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
|
|
8473
|
+
print(JSON.stringify({ repo: repoAbs, ...after, verify, written: entries.map((e) => ({ key: e.key, value: e.value })), ...(shell ? { shell } : {}), local: lf, land }, null, 2));
|
|
8474
|
+
return rc;
|
|
8404
8475
|
}
|
|
8405
8476
|
for (const e of entries) print(`✓ wrote ${e.key}: ${fmtVal(e.value)}`);
|
|
8406
8477
|
if (shell) {
|
|
@@ -8411,7 +8482,63 @@ async function cmdAdopt(argv) {
|
|
|
8411
8482
|
}
|
|
8412
8483
|
print('');
|
|
8413
8484
|
printAdoptReport(after, repoAbs, verify, lf);
|
|
8414
|
-
|
|
8485
|
+
printAdoptLand(land);
|
|
8486
|
+
return rc;
|
|
8487
|
+
}
|
|
8488
|
+
|
|
8489
|
+
/**
|
|
8490
|
+
* #481 — `--land` preflight: is origin's trunk ahead of this checkout? Landing on a stale trunk
|
|
8491
|
+
* would either fail the push or need a merge, and adopt does neither on a human's behalf. Returns a
|
|
8492
|
+
* refusal message, or null. No origin remote, or no trunk there yet (a first push), is not behind.
|
|
8493
|
+
*/
|
|
8494
|
+
function adoptLandBehind(repoAbs, trunk) {
|
|
8495
|
+
if (!git.git(['remote', 'get-url', 'origin'], repoAbs).ok) return null;
|
|
8496
|
+
const f = git.git(['fetch', 'origin', trunk], repoAbs);
|
|
8497
|
+
if (!f.ok) {
|
|
8498
|
+
const remoteHas = git.git(['ls-remote', '--exit-code', '--heads', 'origin', trunk], repoAbs);
|
|
8499
|
+
if (remoteHas.ok) return `--land could not fetch origin/${trunk} — refusing to land on a trunk it cannot see: ${f.stderr || f.stdout}`;
|
|
8500
|
+
return null; // origin has no trunk yet: the landing push creates it
|
|
8501
|
+
}
|
|
8502
|
+
const anc = git.git(['merge-base', '--is-ancestor', 'FETCH_HEAD', 'HEAD'], repoAbs);
|
|
8503
|
+
if (anc.ok) return null;
|
|
8504
|
+
return `--land refuses: origin/${trunk} has commits this checkout does not — pull ${trunk} first, then re-run`;
|
|
8505
|
+
}
|
|
8506
|
+
|
|
8507
|
+
/**
|
|
8508
|
+
* #481 — commit `paths` (only those) onto trunk and push it. Called only after landVerdict passed
|
|
8509
|
+
* (COLAB_HUMAN=1 + --answered-by, standing on trunk), so the pre-push guard's COLAB_HUMAN door is
|
|
8510
|
+
* the one this push walks through — the same env the human set. Nothing staged for these paths
|
|
8511
|
+
* (already committed) is not an error: it still pushes a trunk that is ahead of origin.
|
|
8512
|
+
*/
|
|
8513
|
+
function adoptLand(repoAbs, trunk, paths, answeredBy) {
|
|
8514
|
+
const present = paths.filter((p) => fs.existsSync(path.join(repoAbs, p)));
|
|
8515
|
+
if (!present.length) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: 'no descriptor on disk to land' };
|
|
8516
|
+
const add = git.git(['add', '--', ...present], repoAbs);
|
|
8517
|
+
if (!add.ok) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: `git add failed: ${add.stderr || add.stdout}` };
|
|
8518
|
+
const staged = git.git(['diff', '--cached', '--name-only', '--', ...present], repoAbs);
|
|
8519
|
+
const committed = staged.ok && staged.stdout ? staged.stdout.split('\n').filter(Boolean) : [];
|
|
8520
|
+
if (committed.length) {
|
|
8521
|
+
const c = git.git(['commit', '--only', '-m', adopt.landCommitMessage({ answeredBy, paths: committed }), '--', ...committed], repoAbs);
|
|
8522
|
+
if (!c.ok) return { ok: false, trunk, committed: [], sha: null, pushed: false, error: `git commit failed: ${c.stderr || c.stdout}` };
|
|
8523
|
+
}
|
|
8524
|
+
const head = git.git(['rev-parse', 'HEAD'], repoAbs);
|
|
8525
|
+
const sha = head.ok ? head.stdout : null;
|
|
8526
|
+
if (!git.git(['remote', 'get-url', 'origin'], repoAbs).ok) {
|
|
8527
|
+
return { ok: true, trunk, committed, sha, pushed: false, note: 'no origin remote — committed locally; the first push of trunk carries it' };
|
|
8528
|
+
}
|
|
8529
|
+
const p = git.git(['push', 'origin', `HEAD:refs/heads/${trunk}`], repoAbs);
|
|
8530
|
+
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}` };
|
|
8531
|
+
return { ok: true, trunk, committed, sha, pushed: true };
|
|
8532
|
+
}
|
|
8533
|
+
|
|
8534
|
+
function printAdoptLand(land) {
|
|
8535
|
+
if (!land) return;
|
|
8536
|
+
print('');
|
|
8537
|
+
if (!land.ok) { print(`✗ land: ${land.error}`); return; }
|
|
8538
|
+
const what = land.committed.length ? `committed ${land.committed.join(', ')} as ${shortSha(land.sha)}` : `nothing new to commit (trunk at ${shortSha(land.sha)})`;
|
|
8539
|
+
print(`✓ land: ${what} on ${land.trunk}${land.pushed ? ` — pushed to origin/${land.trunk}` : ''}`);
|
|
8540
|
+
if (land.note) print(` ${land.note}`);
|
|
8541
|
+
print(' The follow-up branch (CI, guards, docs) is judged by this descriptor — ship it through the normal lane.');
|
|
8415
8542
|
}
|
|
8416
8543
|
|
|
8417
8544
|
/**
|
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
|
};
|