@futurelastic/colab-handbook 1.12.0-rc.68 → 1.12.0-rc.70
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 +23 -14
- package/README.vi.md +22 -14
- package/audit/audit.mjs +13 -4
- package/package.json +1 -1
- package/tools/colab +116 -19
- package/tools/lib/adopt.js +61 -1
- package/tools/lib/exposure-shape.js +42 -8
package/README.md
CHANGED
|
@@ -133,18 +133,24 @@ it end to end.
|
|
|
133
133
|
|
|
134
134
|
## The five questions
|
|
135
135
|
|
|
136
|
-
Adopting means answering these about your repo
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
|
143
|
-
|
|
|
144
|
-
|
|
|
145
|
-
|
|
|
146
|
-
|
|
147
|
-
|
|
136
|
+
Adopting means answering these about your repo into `.github/project.yml`.
|
|
137
|
+
`colab adopt` asks only the two that change a gate (1 and 3), as numbered menus;
|
|
138
|
+
the other three are optional and can be answered any time later:
|
|
139
|
+
|
|
140
|
+
| # | Question | Writes | At adoption |
|
|
141
|
+
|---|---|---|---|
|
|
142
|
+
| 1 | Does a deploy target exist **today** (not "soon"), and how is it reached — a tag, the promotion itself, a human running a runbook, or nothing yet? | `production` + `deploy` | asked |
|
|
143
|
+
| 2 | Who else works here — just you, a team, or the public? | `room` | optional — `colab adopt --axis room` |
|
|
144
|
+
| 3 | What would break if you merged something wrong here — nothing, only people already in the room, users via the next promotion, or users and adopters via a released artifact? | `exposure` | asked — a human's answer |
|
|
145
|
+
| 4 | May a human commit straight to trunk alongside worktree sessions — freely, with declared intent, or never? | `writes` | optional — `colab adopt --axis writes` |
|
|
146
|
+
| 5 | By what path does a commit reach the thing that runs it — a CI workflow, a git hook, a documented procedure, a live checkout, a published artifact, another system's data, or none yet? | `channels` | optional — `colab adopt --axis channels` |
|
|
147
|
+
|
|
148
|
+
**Answering question 3 is a human's act** when the answer is "nothing" or "only
|
|
149
|
+
people already in the room". An agent can drive everything else; when it gets
|
|
150
|
+
there, `colab adopt` prints, as its first line, the one command the human runs.
|
|
151
|
+
|
|
152
|
+
Nothing is asked that the repo already states — its default branch (`trunk`,
|
|
153
|
+
kept as it is: a `master` default is fine, nothing needs renaming),
|
|
148
154
|
its toolchain, its ports are detected. Gate count, release ritual and whether a
|
|
149
155
|
branch is mandatory are derived from the answers. What each answer resolves to,
|
|
150
156
|
and why: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) and
|
|
@@ -163,7 +169,7 @@ edits.
|
|
|
163
169
|
By hand, the same steps (full checklist:
|
|
164
170
|
[`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
|
|
165
171
|
|
|
166
|
-
1. `colab adopt` — answers the
|
|
172
|
+
1. `colab adopt` — answers the two gating questions and writes
|
|
167
173
|
`.github/project.yml`. It stops there and prints the remaining steps.
|
|
168
174
|
2. `colab labels --ensure` — the convention labels do not exist by default. A
|
|
169
175
|
check whose label was never created can never fire.
|
|
@@ -198,7 +204,10 @@ extra check before wrap? Do not fork the skill: a fork stops receiving handbook
|
|
|
198
204
|
updates. Write the difference in `.colab/skills/<skill>.md` (for example
|
|
199
205
|
`.colab/skills/code-wrap.md`), in plain prose. Every skill reads that file
|
|
200
206
|
before its own steps, and what it says wins over the skill's text for that repo.
|
|
201
|
-
It never loosens a `colab` gate: a refused claim or merge stays refused.
|
|
207
|
+
It never loosens a `colab` gate: a refused claim or merge stays refused. Name
|
|
208
|
+
the step you are refining by its number (`code-ship` B1c, `code-sweep` §3): a
|
|
209
|
+
large skill is a short core plus reference files, and the core keeps every
|
|
210
|
+
step's number.
|
|
202
211
|
|
|
203
212
|
Claude Code loads the file into the skill automatically. Other engines get a
|
|
204
213
|
plain sentence in each skill telling the agent to read the file, which works
|
package/README.vi.md
CHANGED
|
@@ -132,18 +132,24 @@ còn lại của `CONVENTIONS.md` là tài liệu tra cứu — cần gì tra n
|
|
|
132
132
|
|
|
133
133
|
## Năm câu hỏi
|
|
134
134
|
|
|
135
|
-
Adopt nghĩa là trả lời mấy câu này về repo của bạn
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
|
142
|
-
|
|
|
143
|
-
|
|
|
144
|
-
|
|
|
145
|
-
|
|
146
|
-
|
|
135
|
+
Adopt nghĩa là trả lời mấy câu này về repo của bạn vào `.github/project.yml`.
|
|
136
|
+
`colab adopt` chỉ hỏi hai câu làm thay đổi cổng (1 và 3), dưới dạng menu đánh
|
|
137
|
+
số; ba câu còn lại là tuỳ chọn, trả lời lúc nào sau này cũng được:
|
|
138
|
+
|
|
139
|
+
| # | Câu hỏi | Ghi vào | Lúc adopt |
|
|
140
|
+
|---|---|---|---|
|
|
141
|
+
| 1 | **Hôm nay** (chứ không phải "sắp") đã có đích deploy chưa, và đến đó bằng đường nào — một tag, chính cú promote, một người chạy runbook, hay chưa có gì? | `production` + `deploy` | có hỏi |
|
|
142
|
+
| 2 | Còn ai khác làm ở đây — một mình bạn, một team, hay có cả người ngoài? | `room` | tuỳ chọn — `colab adopt --axis room` |
|
|
143
|
+
| 3 | Merge nhầm thì cái gì hỏng — không gì cả, chỉ những người đang có mặt, người dùng qua lần promote kế tiếp, hay người dùng/người adopt qua một artifact đã phát hành? | `exposure` | có hỏi — người thật trả lời |
|
|
144
|
+
| 4 | Một người có được commit thẳng vào trunk song song với các phiên worktree không — tự do, có khai ý định, hay không bao giờ? | `writes` | tuỳ chọn — `colab adopt --axis writes` |
|
|
145
|
+
| 5 | Code đi tới chỗ nó chạy bằng đường nào — một workflow CI, một git hook, một quy trình tay có ghi lại, một checkout đang sống, một artifact phát hành, dữ liệu của hệ thống khác, hay chưa có đường nào? | `channels` | tuỳ chọn — `colab adopt --axis channels` |
|
|
146
|
+
|
|
147
|
+
**Trả lời câu 3 là việc của người thật** khi câu trả lời là "không gì cả" hoặc
|
|
148
|
+
"chỉ những người đang có mặt". Agent làm được mọi phần còn lại; tới bước đó,
|
|
149
|
+
`colab adopt` in ra, ngay dòng đầu tiên, đúng một lệnh để người thật chạy.
|
|
150
|
+
|
|
151
|
+
Không câu nào hỏi cái repo đã tự nói sẵn — nhánh mặc định (`trunk`, giữ nguyên
|
|
152
|
+
như đang có: nhánh mặc định tên `master` vẫn hợp lệ, không cần đổi tên), toolchain,
|
|
147
153
|
port đều được tự dò. Số cổng, nghi thức release và việc có bắt buộc phải có
|
|
148
154
|
nhánh hay không đều suy ra từ câu trả lời. Mỗi câu trả lời quy về đâu, và vì
|
|
149
155
|
sao: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) và
|
|
@@ -161,7 +167,7 @@ nhất mà không làm mất phần bạn đã sửa.
|
|
|
161
167
|
Làm bằng tay thì cũng đúng các bước đó (checklist đầy đủ:
|
|
162
168
|
[`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
|
|
163
169
|
|
|
164
|
-
1. `colab adopt` — trả lời
|
|
170
|
+
1. `colab adopt` — trả lời hai câu hỏi về cổng và ghi `.github/project.yml`. Nó dừng ở
|
|
165
171
|
đó và in ra các bước còn lại.
|
|
166
172
|
2. `colab labels --ensure` — các label quy ước không có sẵn. Một check mà label
|
|
167
173
|
của nó chưa từng được tạo thì không bao giờ chạy được.
|
|
@@ -197,7 +203,9 @@ từ handbook. Hãy viết phần khác biệt vào `.colab/skills/<skill>.md` (
|
|
|
197
203
|
`.colab/skills/code-wrap.md`), bằng văn xuôi thường. Mỗi skill đọc file đó
|
|
198
204
|
trước các bước của chính nó, và nội dung file thắng phần chữ của skill trong
|
|
199
205
|
repo đó. Nó không bao giờ nới một cổng của `colab`: claim hay merge đã bị từ
|
|
200
|
-
chối thì vẫn bị từ chối.
|
|
206
|
+
chối thì vẫn bị từ chối. Hãy gọi bước bạn muốn chỉnh theo số của nó (`code-ship`
|
|
207
|
+
B1c, `code-sweep` §3): một skill lớn gồm một phần lõi ngắn cộng các file tham
|
|
208
|
+
chiếu, và phần lõi giữ số của mọi bước.
|
|
201
209
|
|
|
202
210
|
Claude Code tự nạp file vào skill. Các engine khác có một câu thường trong mỗi
|
|
203
211
|
skill bảo agent đọc file, cách này chạy được mà không cần engine hỗ trợ gì.
|
package/audit/audit.mjs
CHANGED
|
@@ -82,7 +82,7 @@ const {
|
|
|
82
82
|
// encode the VALIDATOR half (report every violation) separately from `colab adopt`'s CONSTRUCTOR
|
|
83
83
|
// half (does declaring this exposure value stay possible at all?). Same install.sh-freezes-
|
|
84
84
|
// tools/lib/ reasoning as the other requires on this page.
|
|
85
|
-
const { evaluateExposure } = require("../tools/lib/exposure-shape.js");
|
|
85
|
+
const { evaluateExposure, singleTrunkViolation } = require("../tools/lib/exposure-shape.js");
|
|
86
86
|
// #208's `writes` split precedence ladder — same shared-module reasoning as axisAuthority
|
|
87
87
|
// above, reused for a second axis rather than a bespoke second mechanism.
|
|
88
88
|
const writesAuthority = require("../tools/lib/writes-authority.js");
|
|
@@ -1100,6 +1100,10 @@ function renderDuration(age) {
|
|
|
1100
1100
|
|
|
1101
1101
|
function auditRepo(target, ctx) {
|
|
1102
1102
|
const src = makeSource(target);
|
|
1103
|
+
// #522: the branch list is read by the single-trunk rule (tier B / exposure none|released) AND the
|
|
1104
|
+
// trunk-exists check below — one read, so a remote target costs one API listing, not three.
|
|
1105
|
+
let branchesMemo;
|
|
1106
|
+
const branchList = () => (branchesMemo === undefined ? (branchesMemo = src.branches()) : branchesMemo);
|
|
1103
1107
|
const findings = []; // { level: 'fail'|'warn', text }
|
|
1104
1108
|
// `self` = this target IS the handbook, not one of its consumers. Surfaced in the
|
|
1105
1109
|
// report (and in --json) so the row reads as source-of-truth rather than clean-by-luck:
|
|
@@ -1608,7 +1612,12 @@ function auditRepo(target, ctx) {
|
|
|
1608
1612
|
? `tier A with deploy: tag requires trunk "dev" or "main", found ${JSON.stringify(trunk)}`
|
|
1609
1613
|
: `tier A requires trunk "dev", found ${JSON.stringify(trunk)} — only a tag-gated A (deploy: tag) may run a single trunk "main"`);
|
|
1610
1614
|
}
|
|
1611
|
-
|
|
1615
|
+
// #522: B is the single-trunk shape — one long-lived branch, any spelling. `master` (or
|
|
1616
|
+
// whatever an existing repo's default is) conforms; a "main" beside a non-main trunk does not.
|
|
1617
|
+
if (tier === "B") {
|
|
1618
|
+
const single = singleTrunkViolation(trunk, branchList());
|
|
1619
|
+
if (single) fail(`tier B requires a single trunk — ${single}`);
|
|
1620
|
+
}
|
|
1612
1621
|
// C uses A's two-branch split: main = what is live, trunk = where sessions land. #205:
|
|
1613
1622
|
// this validates the SPLIT, not the spelling — trunk is a declared setting (default
|
|
1614
1623
|
// "dev", proposed by colab adopt and the templates), never required to literally be
|
|
@@ -1817,7 +1826,7 @@ function auditRepo(target, ctx) {
|
|
|
1817
1826
|
// construction (CONVENTIONS.md §2: no mechanism rule applies to it, not even trunk shape).
|
|
1818
1827
|
// A `runbook`-kind entry defers to `checkRunbook` here (this file can read the repo and tell
|
|
1819
1828
|
// "missing" from "unreadable via the API"); every other entry is a ready `fail` message.
|
|
1820
|
-
const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow: inRepoDeploy, deployWorkflowNames: [...deployWorkflows, ...fastDeployers] };
|
|
1829
|
+
const shapeCtx = { trunk, hasProduction, deploy, hasDeployWorkflow: inRepoDeploy, deployWorkflowNames: [...deployWorkflows, ...fastDeployers], branches: branchList() };
|
|
1821
1830
|
for (const entry of evaluateExposure(exp, shapeCtx)) {
|
|
1822
1831
|
if (entry.kind === "runbook") checkRunbook(src, runbook, fail, warn, entry.why);
|
|
1823
1832
|
else fail(entry.message);
|
|
@@ -1825,7 +1834,7 @@ function auditRepo(target, ctx) {
|
|
|
1825
1834
|
}
|
|
1826
1835
|
|
|
1827
1836
|
// ---- declared trunk actually exists -------------------------------------
|
|
1828
|
-
const branches =
|
|
1837
|
+
const branches = branchList();
|
|
1829
1838
|
if (trunk && branches === null) {
|
|
1830
1839
|
warn(`cannot list branches (not a git checkout, or gh unavailable) — trunk "${trunk}" unverified`);
|
|
1831
1840
|
} else if (trunk && branches && !branches.includes(trunk)) {
|
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -7718,6 +7718,18 @@ answered by its number OR its literal value), DERIVES the rest, and WRITES the d
|
|
|
7718
7718
|
act — append-only, never touching a byte already there. A complete descriptor just reports
|
|
7719
7719
|
(write nothing, exit 0); re-answer one row on purpose with --axis.
|
|
7720
7720
|
|
|
7721
|
+
ONLY THE GATING ROWS ARE ASKED (#533): deploy/production and exposure. room, writes and channels
|
|
7722
|
+
are optional and legal absent — never prompted for; the report names them in one line with the
|
|
7723
|
+
\`--axis\` command that answers each later, and their own flag still answers one in the same run.
|
|
7724
|
+
After deploy: none, production is not asked again (null follows; --deploy none alone implies it).
|
|
7725
|
+
|
|
7726
|
+
A SINGLE TRUNK, ANY SPELLING (#522): exposure none (and released with production null, and the
|
|
7727
|
+
legacy tier B) need ONE long-lived branch, not one named "main" — an existing master default
|
|
7728
|
+
adopts as-is. A "main" beside a non-main trunk is the two-branch shape and is refused (exit 5).
|
|
7729
|
+
At a terminal the exposure answer is checked against that shape when given, and re-asked with
|
|
7730
|
+
the reason. When a human must finish (the gate below), the FIRST line printed is the one
|
|
7731
|
+
command to run, every answer this run had already filled in.
|
|
7732
|
+
|
|
7721
7733
|
--writes accepts free (coexistence, the default), direct (an attended human may commit straight
|
|
7722
7734
|
to trunk; DECLARED today, its runtime is DEFERRED — see CONVENTIONS.md §2, "writes: direct —
|
|
7723
7735
|
declared today, runtime deferred"), or isolated (vetoes trunk-direct outright, human or not).
|
|
@@ -7914,7 +7926,26 @@ function adoptGitExtras(repoAbs, opts = {}) {
|
|
|
7914
7926
|
// #483: the fork's own owner, from origin's URL — what an inherited CODEOWNERS team is compared to.
|
|
7915
7927
|
const originUrl = git.git(['remote', 'get-url', 'origin'], repoAbs);
|
|
7916
7928
|
const ownOrg = originUrl.ok ? codeowners.remoteOwner(originUrl.stdout) : null;
|
|
7917
|
-
return { trunk, trunkSource, hooksPath, hooksDirFiles, trackedFiles, fork: adoptDetectFork(repoAbs, opts), ownOrg };
|
|
7929
|
+
return { trunk, trunkSource, hooksPath, hooksDirFiles, trackedFiles, fork: adoptDetectFork(repoAbs, opts), ownOrg, branches: adoptBranchList(repoAbs) };
|
|
7930
|
+
}
|
|
7931
|
+
|
|
7932
|
+
/** #522: every branch name visible here — refs/heads ∪ refs/remotes/<any>/<name> — the same union
|
|
7933
|
+
* audit/audit.mjs's `branches()` reads, so the single-trunk rule (tools/lib/exposure-shape.js
|
|
7934
|
+
* `singleTrunkViolation`) answers identically on both sides: adopt never writes what the audit
|
|
7935
|
+
* then fails. null when git cannot list refs (the rule then fails closed to trunk "main"). */
|
|
7936
|
+
function adoptBranchList(repoAbs) {
|
|
7937
|
+
const r = git.git(['for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/remotes'], repoAbs);
|
|
7938
|
+
if (!r.ok) return null;
|
|
7939
|
+
const names = new Set();
|
|
7940
|
+
for (const ref of r.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
|
|
7941
|
+
if (ref.startsWith('refs/heads/')) names.add(ref.slice('refs/heads/'.length));
|
|
7942
|
+
else if (ref.startsWith('refs/remotes/')) {
|
|
7943
|
+
const rest = ref.slice('refs/remotes/'.length);
|
|
7944
|
+
const name = rest.slice(rest.indexOf('/') + 1);
|
|
7945
|
+
if (rest.includes('/') && name && name !== 'HEAD') names.add(name);
|
|
7946
|
+
}
|
|
7947
|
+
}
|
|
7948
|
+
return [...names];
|
|
7918
7949
|
}
|
|
7919
7950
|
|
|
7920
7951
|
/**
|
|
@@ -8187,6 +8218,8 @@ function printAdoptReport(report, repoAbs, verify, localFinish) {
|
|
|
8187
8218
|
print(`detected trunk: ${t.detected || '(unknown)'}${trunkSourceNote}${t.declared !== null ? ` (declared: ${t.declared}${t.agree === false ? ' ⚠ disagrees with detected' : ''})` : ''}`);
|
|
8188
8219
|
print(`stack candidates: ${report.detected.stackCandidates.length ? report.detected.stackCandidates.join(', ') : '(none found)'}`);
|
|
8189
8220
|
print(`declared ports: ${fmtVal(report.detected.ports)}`);
|
|
8221
|
+
const optLine = adopt.optionalRowsLine(report.optionalUnanswered); // #533
|
|
8222
|
+
if (optLine) print(optLine);
|
|
8190
8223
|
if (report.fork) print(`fork of an upstream: yes — ${report.fork.source === 'flag' ? '--fork' : `remote "${report.fork.remote}" ${report.fork.url}`} (step 5 is the append-only block, §9 "A fork of an upstream")`);
|
|
8191
8224
|
if (report.inheritedCodeowners) {
|
|
8192
8225
|
const ic = report.inheritedCodeowners;
|
|
@@ -8262,6 +8295,8 @@ function adoptAnswersFromFlags(opts, cfg, axesToAsk, forcedAxes) {
|
|
|
8262
8295
|
if (!adopt.VALID_DEPLOY.has(opts.deploy)) throw new UserError(`--deploy must be one of: ${[...adopt.VALID_DEPLOY].join(', ')}`);
|
|
8263
8296
|
values.deploy = opts.deploy;
|
|
8264
8297
|
flags.push('--deploy');
|
|
8298
|
+
// #533: deploy: none already says nothing is live — production: null follows, never re-asked.
|
|
8299
|
+
if (opts.deploy === 'none' && opts.production === undefined && eligible('production', 'tier')) values.production = null;
|
|
8265
8300
|
}
|
|
8266
8301
|
if (flags.length) answers.tier = { values, mode: 'flag', flags };
|
|
8267
8302
|
}
|
|
@@ -8325,7 +8360,7 @@ async function askMenu(rl, axis, promptFn) {
|
|
|
8325
8360
|
* URL itself asked only on "yes" — this keeps every axis forced-choice-shaped without pretending
|
|
8326
8361
|
* a URL belongs to an enum.
|
|
8327
8362
|
*/
|
|
8328
|
-
async function adoptAskInteractive(rl, axesToAsk, cfg) {
|
|
8363
|
+
async function adoptAskInteractive(rl, axesToAsk, cfg, checkExposure) {
|
|
8329
8364
|
const answers = {};
|
|
8330
8365
|
for (const axis of axesToAsk) {
|
|
8331
8366
|
const q = adopt.QUESTIONS.find((x) => x.axis === axis);
|
|
@@ -8336,13 +8371,16 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
|
|
|
8336
8371
|
process.stdout.write(`${adopt.renderMenu('tier')}\n`);
|
|
8337
8372
|
return rlAsk(rl, ' deploy: ');
|
|
8338
8373
|
});
|
|
8339
|
-
process.stdout.write(' 1) no deploy target exists today\n 2) yes — enter the URL\n');
|
|
8340
|
-
const existsRaw = (await rlAsk(rl, ' production: ')).trim();
|
|
8341
8374
|
let prod = null;
|
|
8342
|
-
|
|
8343
|
-
|
|
8344
|
-
|
|
8345
|
-
|
|
8375
|
+
// #533: deploy: none already answered "nothing is live" — asking production again is noise.
|
|
8376
|
+
if (depChoice.value !== 'none') {
|
|
8377
|
+
process.stdout.write(' 1) no deploy target exists today\n 2) yes — enter the URL\n');
|
|
8378
|
+
const existsRaw = (await rlAsk(rl, ' production: ')).trim();
|
|
8379
|
+
if (existsRaw === '2' || existsRaw === 'yes') {
|
|
8380
|
+
prod = (await rlAsk(rl, ' URL: ')).trim() || null;
|
|
8381
|
+
} else if (existsRaw !== '1' && existsRaw !== 'no') {
|
|
8382
|
+
throw new UserError('production: choose 1 (no deploy target exists today) or 2 (yes — enter the URL)');
|
|
8383
|
+
}
|
|
8346
8384
|
}
|
|
8347
8385
|
answers.tier = { values: { production: prod, deploy: depChoice.value }, mode: 'interactive' };
|
|
8348
8386
|
} else if (axis === 'channels') {
|
|
@@ -8352,12 +8390,22 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
|
|
|
8352
8390
|
});
|
|
8353
8391
|
answers.channels = { values: { channels: resolved.value }, mode: 'interactive' };
|
|
8354
8392
|
} else if (axis === 'exposure') {
|
|
8355
|
-
|
|
8356
|
-
|
|
8357
|
-
|
|
8358
|
-
|
|
8359
|
-
|
|
8360
|
-
|
|
8393
|
+
// #522: the repo-shape check runs HERE, at answer time — a refusal re-asks with its reason,
|
|
8394
|
+
// instead of surfacing after every other question with nothing written.
|
|
8395
|
+
let chosen = null;
|
|
8396
|
+
for (let attempt = 0; attempt < 2 && !chosen; attempt++) {
|
|
8397
|
+
const resolved = await askMenu(rl, 'exposure', () => {
|
|
8398
|
+
process.stdout.write(`${adopt.renderMenu('exposure')}\n`);
|
|
8399
|
+
return rlAsk(rl, ' choice: ');
|
|
8400
|
+
});
|
|
8401
|
+
if (resolved.skip) { chosen = resolved; break; }
|
|
8402
|
+
const problem = checkExposure ? checkExposure(resolved.value, answers) : null;
|
|
8403
|
+
if (!problem) { chosen = resolved; break; }
|
|
8404
|
+
process.stdout.write(` ✗ ${problem}\n choose again (or skip):\n`);
|
|
8405
|
+
}
|
|
8406
|
+
if (!chosen) throw new UserError('exposure: no answer this repo\'s shape supports after one re-prompt');
|
|
8407
|
+
if (chosen.skip) continue; // decline — the fallback tier derivation picks this up
|
|
8408
|
+
answers.exposure = { values: { exposure: chosen.value }, mode: 'interactive' };
|
|
8361
8409
|
} else {
|
|
8362
8410
|
// room, writes — plain single-choice menus, no skip.
|
|
8363
8411
|
const resolved = await askMenu(rl, axis, () => {
|
|
@@ -8370,11 +8418,41 @@ async function adoptAskInteractive(rl, axesToAsk, cfg) {
|
|
|
8370
8418
|
return answers;
|
|
8371
8419
|
}
|
|
8372
8420
|
|
|
8421
|
+
/** #522: this run's answers as the ordered flag list `adopt.humanAdoptCommand` prints — what the
|
|
8422
|
+
* human pastes to finish the same adoption with the gate satisfied. */
|
|
8423
|
+
function adoptReplayFlags(opts, answers) {
|
|
8424
|
+
const flags = [];
|
|
8425
|
+
if (opts.repo !== undefined) flags.push(['--repo', opts.repo]);
|
|
8426
|
+
const t = answers.tier && answers.tier.values;
|
|
8427
|
+
if (t && 'production' in t) flags.push(['--production', t.production === null ? 'none' : t.production]);
|
|
8428
|
+
if (t && 'deploy' in t) flags.push(['--deploy', t.deploy]);
|
|
8429
|
+
if (answers.exposure) flags.push(['--exposure', answers.exposure.values.exposure]);
|
|
8430
|
+
if (answers.room) flags.push(['--room', answers.room.values.room]);
|
|
8431
|
+
if (answers.writes) flags.push(['--writes', answers.writes.values.writes]);
|
|
8432
|
+
if (answers.channels) flags.push(['--channels', answers.channels.values.channels.join(',')]);
|
|
8433
|
+
if (opts.stack !== undefined) flags.push(['--stack', opts.stack]);
|
|
8434
|
+
if (opts.autonomy !== undefined) flags.push(['--autonomy', opts.autonomy]);
|
|
8435
|
+
if (opts.reason !== undefined) flags.push(['--reason', opts.reason]);
|
|
8436
|
+
if (opts.answeredBy) flags.push(['--answered-by', opts.answeredBy]);
|
|
8437
|
+
if (opts.land) flags.push(['--land', true]);
|
|
8438
|
+
return flags;
|
|
8439
|
+
}
|
|
8440
|
+
|
|
8441
|
+
/** #522: the same command shape for a run that had no answers at all — placeholders per asked row. */
|
|
8442
|
+
function adoptAskedFlagPlaceholders(axesToAsk, stackUnresolvable) {
|
|
8443
|
+
const flags = [];
|
|
8444
|
+
if (axesToAsk.includes('tier')) flags.push(['--production', '<url>|none'], ['--deploy', '<none|tag|manual|push-main>']);
|
|
8445
|
+
if (axesToAsk.includes('exposure')) flags.push(['--exposure', '<none|self|live|released>']);
|
|
8446
|
+
for (const a of ['room', 'writes', 'channels']) if (axesToAsk.includes(a)) flags.push([`--${a}`, `<${a}>`]);
|
|
8447
|
+
if (stackUnresolvable) flags.push(['--stack', '<text>']);
|
|
8448
|
+
return flags;
|
|
8449
|
+
}
|
|
8450
|
+
|
|
8373
8451
|
/** The `EXPOSURE_SHAPE`/falsifier context, built from EFFECTIVE production/deploy — accounting
|
|
8374
8452
|
* for a `tier`-axis answer resolved in THIS SAME run, not only what was already on record, so
|
|
8375
8453
|
* declaring production+deploy and exposure together in one invocation validates against each
|
|
8376
8454
|
* other rather than the pre-write snapshot. */
|
|
8377
|
-
function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io) {
|
|
8455
|
+
function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io, branches) {
|
|
8378
8456
|
const effProduction = tierAnswer ? tierAnswer.values.production : (Object.prototype.hasOwnProperty.call(cfg, 'production') ? cfg.production : null);
|
|
8379
8457
|
const effDeploy = tierAnswer ? tierAnswer.values.deploy : (Object.prototype.hasOwnProperty.call(cfg, 'deploy') ? cfg.deploy : null);
|
|
8380
8458
|
const evidence = consumerEvidence.consumerEvidence(io, workflows);
|
|
@@ -8382,7 +8460,7 @@ function adoptShapeCtx(cfg, tierAnswer, trunk, workflows, io) {
|
|
|
8382
8460
|
const hasProduction = effProduction !== null && effProduction !== undefined && effProduction !== '';
|
|
8383
8461
|
const runbook = Object.prototype.hasOwnProperty.call(cfg, 'runbook') ? cfg.runbook : null;
|
|
8384
8462
|
const hasRunbook = !!(runbook && io.readFile(String(runbook).trim().replace(/^\.\//, '')) !== null);
|
|
8385
|
-
return { trunk, hasProduction, deploy: effDeploy, hasDeployWorkflow, hasRunbook, effProduction, effDeploy };
|
|
8463
|
+
return { trunk, hasProduction, deploy: effDeploy, hasDeployWorkflow, hasRunbook, effProduction, effDeploy, branches: branches === undefined ? null : branches };
|
|
8386
8464
|
}
|
|
8387
8465
|
|
|
8388
8466
|
async function cmdAdopt(argv) {
|
|
@@ -8428,7 +8506,12 @@ async function cmdAdopt(argv) {
|
|
|
8428
8506
|
if (!adopt.ROW_NAMES.includes(a)) throw new UserError(`Unknown --axis "${a}" — expected one of: ${adopt.ROW_NAMES.join(', ')}`);
|
|
8429
8507
|
}
|
|
8430
8508
|
const forcedAxes = new Set(requestedAxes);
|
|
8431
|
-
|
|
8509
|
+
// #533: a fresh adoption asks only the rows that change a gate (production/deploy, exposure);
|
|
8510
|
+
// room/writes/channels are asked only when forced (--axis) or answered by their flag.
|
|
8511
|
+
const flagAxes = new Set();
|
|
8512
|
+
if (opts.production !== undefined || opts.deploy !== undefined) flagAxes.add('tier');
|
|
8513
|
+
for (const a of ['room', 'exposure', 'writes', 'channels']) if (opts[a] !== undefined) flagAxes.add(a);
|
|
8514
|
+
let axesToAsk = adopt.axesToAsk(cfg, forcedAxes, flagAxes);
|
|
8432
8515
|
// --local re-run (#393): once exposure is on record, a bare `adopt --local` (no answer flags, no
|
|
8433
8516
|
// --axis) is the idempotent re-apply — exclude lines, stub, labels, checkout — never a prompt for
|
|
8434
8517
|
// the optional rows (room/writes/channels), which --local leaves to the operator by design.
|
|
@@ -8522,7 +8605,11 @@ async function cmdAdopt(argv) {
|
|
|
8522
8605
|
} else if (isTTY) {
|
|
8523
8606
|
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
|
|
8524
8607
|
try {
|
|
8525
|
-
|
|
8608
|
+
const shapeWorkflows = io.listDir('.github/workflows').filter((f) => /\.ya?ml$/.test(f));
|
|
8609
|
+
answers = await adoptAskInteractive(rl, axesToAsk, cfg, (exposure, sofar) => {
|
|
8610
|
+
const v = adopt.exposureShapeVerdict(exposure, adoptShapeCtx(cfg, sofar.tier, extra.trunk, shapeWorkflows, io, extra.branches));
|
|
8611
|
+
return v.ok ? null : v.reason;
|
|
8612
|
+
});
|
|
8526
8613
|
if (needsStack && opts.stack === undefined) {
|
|
8527
8614
|
process.stdout.write('\nNo manifest recognised (package.json/composer.json/pyproject.toml/'
|
|
8528
8615
|
+ '.python-version) — the audit requires stack: as a literal key.\n');
|
|
@@ -8537,6 +8624,12 @@ async function cmdAdopt(argv) {
|
|
|
8537
8624
|
} else {
|
|
8538
8625
|
const hints = axesToAsk.map(adoptAxisFlagHint).join(' ');
|
|
8539
8626
|
const stackHint = stackUnresolvable ? ' --stack "<text>"' : '';
|
|
8627
|
+
// #522: the human step goes FIRST — answering exposure none/self is a human's act, so the one
|
|
8628
|
+
// command that finishes the adoption leads, and the explanation follows it.
|
|
8629
|
+
if (axesToAsk.includes('exposure')) {
|
|
8630
|
+
warn('a human finishes this adoption — run at an interactive terminal: colab adopt (or, non-interactively:)');
|
|
8631
|
+
warn(` ${adopt.humanAdoptCommand(adoptAskedFlagPlaceholders(axesToAsk, stackUnresolvable))}`);
|
|
8632
|
+
}
|
|
8540
8633
|
warn(`${axesToAsk.length} unanswered §9 row(s) (${axesToAsk.join(', ')}) — no TTY and no answer flags, so there is no way to ask. Re-run with: ${hints}${stackHint}`);
|
|
8541
8634
|
return 1;
|
|
8542
8635
|
}
|
|
@@ -8561,7 +8654,7 @@ async function cmdAdopt(argv) {
|
|
|
8561
8654
|
// written, per "nothing partially written on refusal".
|
|
8562
8655
|
if (answers.exposure) {
|
|
8563
8656
|
const proposedExposure = answers.exposure.values.exposure;
|
|
8564
|
-
const shapeCtx = adoptShapeCtx(cfg, answers.tier, trunk, workflows, io);
|
|
8657
|
+
const shapeCtx = adoptShapeCtx(cfg, answers.tier, trunk, workflows, io, extra.branches);
|
|
8565
8658
|
const evidence = consumerEvidence.consumerEvidence(io, workflows);
|
|
8566
8659
|
const currentExposure = axisAuthority.axisOfRecord(cfg).exposure;
|
|
8567
8660
|
const verdict = adopt.gateVerdict({
|
|
@@ -8575,6 +8668,10 @@ async function cmdAdopt(argv) {
|
|
|
8575
8668
|
reason: opts.reason || null,
|
|
8576
8669
|
});
|
|
8577
8670
|
if (!verdict.ok) {
|
|
8671
|
+
if (verdict.class === adopt.GATE_CLASS.HUMAN_GATED) {
|
|
8672
|
+
// #522: lead with the one command a human runs, every answer this run had filled in.
|
|
8673
|
+
warn(`a human finishes this adoption — run: ${adopt.humanAdoptCommand(adoptReplayFlags(opts, answers))}`);
|
|
8674
|
+
}
|
|
8578
8675
|
warn(verdict.message);
|
|
8579
8676
|
return verdict.exitCode;
|
|
8580
8677
|
}
|
package/tools/lib/adopt.js
CHANGED
|
@@ -37,6 +37,13 @@ const { UserError } = require('./util.js');
|
|
|
37
37
|
|
|
38
38
|
const ROW_NAMES = ['tier', 'room', 'exposure', 'writes', 'channels'];
|
|
39
39
|
|
|
40
|
+
/** #533: the rows that change a gate — the only ones a fresh adoption ASKS. `tier` here is the
|
|
41
|
+
* production/deploy pair; `exposure` sets the gate count. The other three are optional in the
|
|
42
|
+
* schema and legal absent (room → trail verbosity, writes → `free` is the default, channels →
|
|
43
|
+
* descriptive), so adoption leaves them unanswered and names the `--axis` command instead. */
|
|
44
|
+
const GATING_ROWS = Object.freeze(['tier', 'exposure']);
|
|
45
|
+
const OPTIONAL_ROWS = Object.freeze(['room', 'writes', 'channels']);
|
|
46
|
+
|
|
40
47
|
// ---------------------------------------------------------------------- descriptor read
|
|
41
48
|
|
|
42
49
|
/** Parsed `.github/project.yml`, or {} when absent/unparseable — never throws. */
|
|
@@ -387,7 +394,7 @@ function remainingSteps(ctx = {}) {
|
|
|
387
394
|
if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
|
|
388
395
|
steps.push(
|
|
389
396
|
{ n: 3, text: 'Create the full label set (21 names) — `colab labels --ensure`, CONVENTIONS.md §9 step 3 (#206)' },
|
|
390
|
-
{ n: 4, text: '
|
|
397
|
+
{ n: 4, text: 'Optional: add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4. Needs repo ADMIN (push access alone gets `HTTP 404 …/topics`); nothing in colab or the audit reads it, so skip it when you are not one (#522)' },
|
|
391
398
|
);
|
|
392
399
|
if (ctx.fork) {
|
|
393
400
|
steps.push({ n: 5, text: `Fork of an upstream (${ctx.fork.source === 'flag' ? '--fork' : `remote "${ctx.fork.remote}"`}): do NOT make CLAUDE.md the thin shell — append templates/repo-CLAUDE-block.md at the END of the upstream's CLAUDE.md (create it only if upstream has none), record that append as a fork patch, leave AGENTS.md and the upstream prose untouched; CONVENTIONS.md §9 "A fork of an upstream", step 5` });
|
|
@@ -538,6 +545,7 @@ function detect(io, extra = {}) {
|
|
|
538
545
|
inheritedCodeowners,
|
|
539
546
|
migrations,
|
|
540
547
|
remaining: remainingSteps({ migrations, fork, upstreamAgentFiles, releaseRung }),
|
|
548
|
+
optionalUnanswered: optionalUnanswered(cfg), // #533
|
|
541
549
|
};
|
|
542
550
|
}
|
|
543
551
|
|
|
@@ -780,6 +788,52 @@ function axisMissing(cfg, axis) {
|
|
|
780
788
|
}
|
|
781
789
|
}
|
|
782
790
|
|
|
791
|
+
/**
|
|
792
|
+
* #533: which rows this run asks. A gating row is asked when it is still missing; an optional row
|
|
793
|
+
* (room/writes/channels) only when the caller forced it (`--axis`) or supplied its answer flag —
|
|
794
|
+
* a fresh adoption never prompts for it. `flagAxes` — the rows an answer flag was given for.
|
|
795
|
+
*/
|
|
796
|
+
function axesToAsk(cfg, forcedAxes, flagAxes) {
|
|
797
|
+
const forced = forcedAxes instanceof Set ? forcedAxes : new Set(forcedAxes || []);
|
|
798
|
+
const flagged = flagAxes instanceof Set ? flagAxes : new Set(flagAxes || []);
|
|
799
|
+
return ROW_NAMES.filter((a) => forced.has(a)
|
|
800
|
+
|| (axisMissing(cfg, a) && (GATING_ROWS.includes(a) || flagged.has(a))));
|
|
801
|
+
}
|
|
802
|
+
|
|
803
|
+
/** #533: the optional rows still unanswered after a run — reported in one line, never asked. */
|
|
804
|
+
function optionalUnanswered(cfg) {
|
|
805
|
+
return OPTIONAL_ROWS.filter((a) => axisMissing(cfg, a));
|
|
806
|
+
}
|
|
807
|
+
|
|
808
|
+
/** The one line naming them and the command that answers each later (#533). null when none. */
|
|
809
|
+
function optionalRowsLine(rows) {
|
|
810
|
+
if (!rows || !rows.length) return null;
|
|
811
|
+
return `not asked (optional, legal absent): ${rows.join(', ')} — answer later with \`colab adopt --axis ${rows.join(',')}\``;
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
/** Shell-quote one argument only when it needs it — the printed command must paste and run. */
|
|
815
|
+
function shellArg(v) {
|
|
816
|
+
const t = String(v);
|
|
817
|
+
return /^[A-Za-z0-9_@%+=:,./-]+$/.test(t) ? t : `"${t.replace(/(["\\$`])/g, '\\$1')}"`;
|
|
818
|
+
}
|
|
819
|
+
|
|
820
|
+
/**
|
|
821
|
+
* #522: the ONE command a human runs to finish an adoption an agent could not — printed as the
|
|
822
|
+
* first line of a human-gated refusal, answers already filled in. `flags` is an ordered list of
|
|
823
|
+
* `[flag, value]` pairs (value undefined/null for a bare flag); `--answered-by` is appended as a
|
|
824
|
+
* placeholder when absent, because the human bar needs it alongside COLAB_HUMAN=1.
|
|
825
|
+
*/
|
|
826
|
+
function humanAdoptCommand(flags) {
|
|
827
|
+
const parts = ['COLAB_HUMAN=1', 'colab', 'adopt'];
|
|
828
|
+
let hasAnsweredBy = false;
|
|
829
|
+
for (const [flag, value] of flags || []) {
|
|
830
|
+
if (flag === '--answered-by') hasAnsweredBy = true;
|
|
831
|
+
parts.push(value === undefined || value === null || value === true ? flag : `${flag} ${shellArg(value)}`);
|
|
832
|
+
}
|
|
833
|
+
if (!hasAnsweredBy) parts.push('--answered-by "<your name>"');
|
|
834
|
+
return parts.join(' ');
|
|
835
|
+
}
|
|
836
|
+
|
|
783
837
|
// ---------------------------------------------------------------------- EXPOSURE_SHAPE — the constructor
|
|
784
838
|
|
|
785
839
|
/**
|
|
@@ -1166,6 +1220,12 @@ module.exports = {
|
|
|
1166
1220
|
renderMenu,
|
|
1167
1221
|
resolveChoice,
|
|
1168
1222
|
axisMissing,
|
|
1223
|
+
GATING_ROWS,
|
|
1224
|
+
OPTIONAL_ROWS,
|
|
1225
|
+
axesToAsk,
|
|
1226
|
+
optionalUnanswered,
|
|
1227
|
+
optionalRowsLine,
|
|
1228
|
+
humanAdoptCommand,
|
|
1169
1229
|
EXPOSURE_RANK,
|
|
1170
1230
|
GATE_CLASS,
|
|
1171
1231
|
EXIT_CODE,
|
|
@@ -53,7 +53,8 @@
|
|
|
53
53
|
* Context shape both sides build (identically named, audit.mjs and adopt.js each computing the
|
|
54
54
|
* booleans from their own sources — a real git checkout for one, a `git status`-aware `io` for
|
|
55
55
|
* the other):
|
|
56
|
-
* { trunk, hasProduction, deploy, hasDeployWorkflow, hasRunbook, deployWorkflowNames? }
|
|
56
|
+
* { trunk, hasProduction, deploy, hasDeployWorkflow, hasRunbook, deployWorkflowNames?, branches? }
|
|
57
|
+
* `branches` (#522) is what `singleTrunkViolation` reads — omitting it fails closed to trunk "main".
|
|
57
58
|
* `deployWorkflowNames` is OPTIONAL and cosmetic only (the `none` violation names which
|
|
58
59
|
* workflow(s) contradict it) — omitting it (as adopt.js's ctx does) only drops the parenthetical
|
|
59
60
|
* from the message, never changes which entries fire.
|
|
@@ -74,13 +75,45 @@ function evaluateExposure(exposure, ctx) {
|
|
|
74
75
|
}
|
|
75
76
|
}
|
|
76
77
|
|
|
78
|
+
/**
|
|
79
|
+
* #522: the single-trunk invariant shared by every shape with no release branch — `exposure: none`,
|
|
80
|
+
* `exposure: released` with `production: null`, and the legacy `tier: B` (audit/audit.mjs). It is
|
|
81
|
+
* about HOW MANY long-lived branches exist, never how the one branch is spelled: an existing repo
|
|
82
|
+
* whose default branch is `master` (or anything else) adopts as-is, with nothing renamed.
|
|
83
|
+
*
|
|
84
|
+
* What it refuses is the two-branch shape wearing a single-trunk label: a `main` branch sitting
|
|
85
|
+
* beside a trunk that is not `main` is the live/released split (main = what ships, trunk = where
|
|
86
|
+
* sessions land), and declaring "nothing consumes this" over it would hide the release branch.
|
|
87
|
+
*
|
|
88
|
+
* `branches` — every branch name the caller can see (local ∪ remote-tracking), or null/undefined
|
|
89
|
+
* when it cannot list them. Unknown FAILS CLOSED to the old spelling rule (trunk "main"): a
|
|
90
|
+
* non-main trunk is accepted only when a readable branch list proves no `main` sits beside it.
|
|
91
|
+
*
|
|
92
|
+
* Returns null when the invariant holds, else the reason text (no prefix — each caller names its
|
|
93
|
+
* own shape in front of it).
|
|
94
|
+
*/
|
|
95
|
+
function singleTrunkViolation(trunk, branches) {
|
|
96
|
+
if (!trunk) return `no trunk declared, found ${JSON.stringify(trunk)}`;
|
|
97
|
+
if (trunk === 'main') return null;
|
|
98
|
+
if (!Array.isArray(branches)) {
|
|
99
|
+
return `trunk ${JSON.stringify(trunk)} can stand in for "main" only when the branch list is readable `
|
|
100
|
+
+ 'and shows no "main" beside it, and the branch list could not be read';
|
|
101
|
+
}
|
|
102
|
+
if (branches.includes('main')) {
|
|
103
|
+
return `trunk is ${JSON.stringify(trunk)} and a "main" branch exists beside it — that is the `
|
|
104
|
+
+ 'two-branch (live/released) shape, not a single trunk';
|
|
105
|
+
}
|
|
106
|
+
return null;
|
|
107
|
+
}
|
|
108
|
+
|
|
77
109
|
function evaluateNone(ctx) {
|
|
78
110
|
const out = [];
|
|
79
|
-
|
|
111
|
+
const single = singleTrunkViolation(ctx.trunk, ctx.branches);
|
|
112
|
+
if (single) {
|
|
80
113
|
out.push({
|
|
81
114
|
kind: 'fail',
|
|
82
|
-
message: `exposure: none requires trunk
|
|
83
|
-
+ '
|
|
115
|
+
message: `exposure: none requires a single trunk — ${single} — nothing consumes this repo, `
|
|
116
|
+
+ 'so there is no release branch to speak of',
|
|
84
117
|
});
|
|
85
118
|
}
|
|
86
119
|
if (ctx.hasDeployWorkflow) {
|
|
@@ -131,11 +164,12 @@ function evaluateLive(ctx) {
|
|
|
131
164
|
|
|
132
165
|
function evaluateReleasedNoProduction(ctx) {
|
|
133
166
|
const out = [];
|
|
134
|
-
|
|
167
|
+
const single = singleTrunkViolation(ctx.trunk, ctx.branches);
|
|
168
|
+
if (single) {
|
|
135
169
|
out.push({
|
|
136
170
|
kind: 'fail',
|
|
137
|
-
message: `exposure: released with production: null requires trunk
|
|
138
|
-
+
|
|
171
|
+
message: `exposure: released with production: null requires a single trunk — ${single} — `
|
|
172
|
+
+ 'nothing is live, so there is no release branch to speak of',
|
|
139
173
|
});
|
|
140
174
|
}
|
|
141
175
|
if (ctx.deploy !== null && ctx.deploy !== undefined && ctx.deploy !== 'none') {
|
|
@@ -204,4 +238,4 @@ function evaluateReleasedWithProduction(ctx) {
|
|
|
204
238
|
return out;
|
|
205
239
|
}
|
|
206
240
|
|
|
207
|
-
module.exports = { evaluateExposure };
|
|
241
|
+
module.exports = { evaluateExposure, singleTrunkViolation };
|