@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.10
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 +248 -213
- package/README.vi.md +252 -186
- package/audit/audit.mjs +193 -10
- package/package.json +7 -1
- package/templates/README.md +30 -2
- package/templates/ci-laravel.yml +102 -21
- package/templates/ci-node.yml +61 -3
- package/templates/ci-python.yml +52 -3
- package/templates/deploy-adapter-portainer.mjs +206 -0
- package/templates/deploy-container-run.mjs +368 -0
- package/templates/deploy-container.yml +219 -0
- package/templates/dist-refs.yml +6 -0
- package/templates/docs-lint.mjs +1 -1
- package/templates/npx-launcher.mjs +118 -20
- package/templates/npx-service.mjs +828 -0
- package/templates/release-auto.yml +341 -32
- package/tools/colab +1902 -278
- package/tools/lib/adopt.js +373 -14
- package/tools/lib/branch-name.js +29 -1
- package/tools/lib/ci-cure.js +522 -31
- package/tools/lib/ci-grant.js +289 -22
- package/tools/lib/ci-wait.js +223 -0
- package/tools/lib/claim-comments.js +13 -64
- package/tools/lib/claim-identity.js +42 -7
- package/tools/lib/codec/claim.d.ts +41 -0
- package/tools/lib/codec/claim.js +153 -0
- package/tools/lib/codec/decision.d.ts +29 -0
- package/tools/lib/codec/decision.js +81 -0
- package/tools/lib/codec/grants.d.ts +82 -0
- package/tools/lib/codec/grants.js +268 -0
- package/tools/lib/codec/hold.d.ts +26 -0
- package/tools/lib/codec/hold.js +152 -0
- package/tools/lib/codec/index.d.ts +21 -0
- package/tools/lib/codec/index.js +32 -0
- package/tools/lib/codec/labels.d.ts +65 -0
- package/tools/lib/codec/labels.js +723 -0
- package/tools/lib/codec/markers.d.ts +35 -0
- package/tools/lib/codec/markers.js +138 -0
- package/tools/lib/codec/release.d.ts +17 -0
- package/tools/lib/codec/release.js +69 -0
- package/tools/lib/codec/samples.json +778 -0
- package/tools/lib/codeowners.js +68 -4
- package/tools/lib/container-close.js +38 -0
- package/tools/lib/cure-diff.js +198 -9
- package/tools/lib/decision-record.js +15 -39
- package/tools/lib/docs-only.js +15 -1
- package/tools/lib/exposure-shape.js +42 -8
- package/tools/lib/git.js +324 -42
- package/tools/lib/group-labels.js +65 -0
- package/tools/lib/install-check.js +14 -8
- package/tools/lib/install-route.js +139 -0
- package/tools/lib/instruction-file.js +1 -0
- package/tools/lib/labels.js +22 -647
- package/tools/lib/local-adopt.js +8 -4
- package/tools/lib/migration-grant.js +206 -104
- package/tools/lib/place.js +2 -2
- package/tools/lib/release-cut.js +199 -25
- package/tools/lib/release-finalize.js +111 -23
- package/tools/lib/release-policy.js +130 -22
- package/tools/lib/release-runner.js +125 -0
- package/tools/lib/release-tag.js +3 -1
- package/tools/lib/scratch-dirs.js +118 -0
- package/tools/lib/ship-batch.js +36 -1
- package/tools/lib/ship-human-door.js +76 -0
- package/tools/lib/stamp.js +7 -0
- package/tools/lib/tracker-fake.js +195 -0
- package/tools/lib/tracker-github.js +106 -0
- package/tools/lib/tracker-scenarios.json +206 -0
- package/tools/lib/tracker.js +64 -0
- package/tools/lib/tree-green.js +88 -0
- package/tools/lib/util.js +17 -1
- package/tools/lib/verify-runs.js +104 -0
- package/tools/lib/wake.js +8 -90
- package/tools/lib/workflow-triggers.js +48 -0
package/tools/lib/adopt.js
CHANGED
|
@@ -18,7 +18,8 @@
|
|
|
18
18
|
* listDir(relPath) -> string[] non-recursive listing, [] if unreadable/absent
|
|
19
19
|
* tags() -> string[] | null every git tag, or null if undeterminable
|
|
20
20
|
*
|
|
21
|
-
* Git facts that are NOT plain file reads (trunk, `core.hooksPath
|
|
21
|
+
* Git facts that are NOT plain file reads (trunk, `core.hooksPath`, the fork remote and `git ls-files`
|
|
22
|
+
* for #449) are passed in separately via
|
|
22
23
|
* `extra`, rather than folded into `io` — `detectTrunk()` already lives in `tools/lib/git.js` and
|
|
23
24
|
* belongs to the CLI layer, not duplicated here.
|
|
24
25
|
*
|
|
@@ -36,6 +37,13 @@ const { UserError } = require('./util.js');
|
|
|
36
37
|
|
|
37
38
|
const ROW_NAMES = ['tier', 'room', 'exposure', 'writes', 'channels'];
|
|
38
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
|
+
|
|
39
47
|
// ---------------------------------------------------------------------- descriptor read
|
|
40
48
|
|
|
41
49
|
/** Parsed `.github/project.yml`, or {} when absent/unparseable — never throws. */
|
|
@@ -210,22 +218,201 @@ function deriveConsequences({ exposure, writes, room }) {
|
|
|
210
218
|
|
|
211
219
|
// ---------------------------------------------------------------------- §9 remainder checklist
|
|
212
220
|
|
|
221
|
+
const migrationPaths = require('./migration-paths.js');
|
|
222
|
+
const codeowners = require('./codeowners.js');
|
|
223
|
+
|
|
213
224
|
/**
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
*
|
|
225
|
+
* #483 — on a fork, the CODEOWNERS teams that belong to another org: inherited from the upstream,
|
|
226
|
+
* unable to review here, and therefore ignored by `colab ship`'s core-path reader (CONVENTIONS.md
|
|
227
|
+
* §2, *Core paths*). Adopt names them so the fork owner learns at adoption time, not at the first
|
|
228
|
+
* ship, that the inherited file is inert until the fork writes its own. Null when there is nothing
|
|
229
|
+
* to say: not a fork, the fork's owner unknown, no CODEOWNERS, or no foreign team in it.
|
|
218
230
|
*/
|
|
219
|
-
function
|
|
220
|
-
return
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
231
|
+
function detectInheritedCodeowners(io, fork, ownOrg) {
|
|
232
|
+
if (!fork || !ownOrg) return null;
|
|
233
|
+
for (const p of codeowners.CODEOWNERS_PATHS) {
|
|
234
|
+
const text = io.readFile(p);
|
|
235
|
+
if (text === null || text === undefined) continue;
|
|
236
|
+
const teams = codeowners.foreignTeams(codeowners.parse(text).rules, { fork: true, ownOrg });
|
|
237
|
+
return teams.length ? { path: p, ownOrg, teams } : null;
|
|
238
|
+
}
|
|
239
|
+
return null;
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* #449 — the agent workflow an upstream ships inside the fork: entries under `.claude/skills/`
|
|
244
|
+
* and `.claude/commands/`, plus a committed `AGENTS.md`. Upstream-owned files compete with the
|
|
245
|
+
* `code-*` skills, and deleting or editing them is a fork patch that conflicts on every upstream
|
|
246
|
+
* merge — so adopt only NAMES them, for the precedence line the appended block carries.
|
|
247
|
+
*/
|
|
248
|
+
function detectUpstreamAgentFiles(io) {
|
|
249
|
+
const out = [];
|
|
250
|
+
for (const dir of ['.claude/skills', '.claude/commands']) {
|
|
251
|
+
for (const e of io.listDir(dir).slice().sort()) {
|
|
252
|
+
if (e.startsWith('.')) continue;
|
|
253
|
+
out.push(`${dir}/${e}`);
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
return out;
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
/**
|
|
260
|
+
* #449 — where this repo's migrations might live, beyond what `migrations:` and the two defaults
|
|
261
|
+
* already cover. Two heuristics over `git ls-files`, both CANDIDATES for a human, never written:
|
|
262
|
+
* a `migrations/` directory nothing covers (the audit's own rule, `undeclaredMigrationDirs`), and
|
|
263
|
+
* a directory holding tracked `*.sql` files nothing covers (a fork whose upstream keeps them in
|
|
264
|
+
* `modules/<name>/sql/` — measured: the no-new-migrations gate was blind there). The `.sql` rule
|
|
265
|
+
* over-reports seeds and fixtures on purpose: a false candidate costs a glance, a missed layout
|
|
266
|
+
* leaves a human-only gate seeing nothing.
|
|
267
|
+
*/
|
|
268
|
+
function detectMigrationCandidates(cfg, trackedFiles) {
|
|
269
|
+
const parsed = migrationPaths.parseMigrationPaths(cfg);
|
|
270
|
+
const declared = parsed.paths;
|
|
271
|
+
const files = trackedFiles || [];
|
|
272
|
+
const dirs = new Set(migrationPaths.undeclaredMigrationDirs(files, declared));
|
|
273
|
+
for (const file of files) {
|
|
274
|
+
if (!/\.sql$/i.test(file)) continue;
|
|
275
|
+
const segs = String(file).split('/');
|
|
276
|
+
if (segs.length < 2) continue; // a root-level .sql is not a layout
|
|
277
|
+
if (segs.some((s) => s === 'node_modules' || s === 'vendor')) continue;
|
|
278
|
+
if (migrationPaths.isMigrationPath(file, declared)) continue;
|
|
279
|
+
const dir = `${segs.slice(0, -1).join('/')}/`;
|
|
280
|
+
if ([...dirs].some((d) => dir.startsWith(d))) continue;
|
|
281
|
+
dirs.add(dir);
|
|
282
|
+
}
|
|
283
|
+
return { declared: parsed.declared ? declared : null, candidates: [...dirs].sort() };
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
const MIGRATION_CANDIDATES_SHOWN = 6;
|
|
287
|
+
|
|
288
|
+
/** The step-2 remainder line about `migrations:` — adopt never asks it, so it always reports it. */
|
|
289
|
+
function migrationsStepText(m) {
|
|
290
|
+
const tail = 'project.schema.md `migrations`; `colab adopt` does not ask it, step 2';
|
|
291
|
+
if (m && m.declared && m.declared.length) {
|
|
292
|
+
const extra = m.candidates.length ? ` — still uncovered, check: ${listShort(m.candidates)}` : '';
|
|
293
|
+
return `\`migrations:\` declared (${m.declared.join(', ')})${extra} — ${tail}`;
|
|
294
|
+
}
|
|
295
|
+
if (m && m.candidates.length) {
|
|
296
|
+
return `Declare \`migrations:\` in .github/project.yml — candidate layouts outside database/migrations/ and prisma/migrations/: ${listShort(m.candidates)}. Until declared, the no-new-migrations gate cannot see them — ${tail}`;
|
|
297
|
+
}
|
|
298
|
+
return `Declare \`migrations:\` in .github/project.yml if this repo keeps migrations anywhere but database/migrations/ or prisma/migrations/ (none detected) — ${tail}`;
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
function listShort(items) {
|
|
302
|
+
const shown = items.slice(0, MIGRATION_CANDIDATES_SHOWN).join(', ');
|
|
303
|
+
return items.length > MIGRATION_CANDIDATES_SHOWN ? `${shown} (+${items.length - MIGRATION_CANDIDATES_SHOWN} more)` : shown;
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
/**
|
|
307
|
+
* §9's remainder, as data, not prose, so a caller (a report printer, or a future `handbook-sync`
|
|
308
|
+
* call site) does not grow its own paraphrase of these steps. Adopt writes the descriptor and
|
|
309
|
+
* nothing else (Boundary, #199's plan), so steps 3-9 are always listed.
|
|
310
|
+
*
|
|
311
|
+
* `ctx` (all optional, #449):
|
|
312
|
+
* migrations — `detectMigrationCandidates()`'s result; adds the step-2 `migrations:` line
|
|
313
|
+
* (absent ctx = the pre-#449 list, steps 3-9 only)
|
|
314
|
+
* fork — `{ remote, url, source }` when this repo tracks an upstream it does not own:
|
|
315
|
+
* step 5 becomes the append-only block instead of the thin-shell conversion
|
|
316
|
+
* (CONVENTIONS.md §9, *A fork of an upstream*)
|
|
317
|
+
* upstreamAgentFiles — on a fork, the upstream's own agent workflow, named for the precedence line
|
|
318
|
+
* releaseRung — `releaseRungSteps()`'s result (#492): extra step-6 lines on exposure: released
|
|
319
|
+
*/
|
|
320
|
+
const releasePolicy = require('./release-policy.js');
|
|
321
|
+
|
|
322
|
+
const FINAL_TAG = /^v\d+\.\d+\.\d+$/;
|
|
323
|
+
|
|
324
|
+
/**
|
|
325
|
+
* #492 — on `exposure: released`, step 6 is not only CI: the release rung (CONVENTIONS.md §6) has
|
|
326
|
+
* to be wired at adoption too, or the repo never cuts a candidate until someone notices. Measured:
|
|
327
|
+
* six adopters in one fleet sweep with no `release:` block and no release workflow, several more
|
|
328
|
+
* with the workflow but no first final (`release cut` refuses with no final to bump from).
|
|
329
|
+
*
|
|
330
|
+
* Pure: reads the descriptor and what `io` already exposes. Returns step-6 entries (possibly
|
|
331
|
+
* none). Never decides a route on a human's behalf beyond §6's own derivation — the no-production
|
|
332
|
+
* row's choice is PROPOSED (public room -> public-tool, else rapid-app), and the text says so.
|
|
333
|
+
*
|
|
334
|
+
* `ctx`: { cfg, workflowTexts: { [file]: text }, tags: string[]|null, stackFiles: string[] }
|
|
335
|
+
*/
|
|
336
|
+
function releaseRungSteps(ctx = {}) {
|
|
337
|
+
const cfg = ctx.cfg || {};
|
|
338
|
+
const def = releasePolicy.deriveDefault(cfg);
|
|
339
|
+
const exposure = axisAuthority.axisOfRecord(cfg).exposure;
|
|
340
|
+
if (exposure !== 'released') return [];
|
|
341
|
+
const steps = [];
|
|
342
|
+
const block = cfg.release && typeof cfg.release === 'object' ? cfg.release : null;
|
|
343
|
+
|
|
344
|
+
// 6a — the release: block.
|
|
345
|
+
if (block && block.route) {
|
|
346
|
+
steps.push({ n: 6, text: `Release rung: \`release.route: ${block.route}\` declared — keep it; confirm \`version-source\` (default \`tag\` where the machine cuts the tag, #484), CONVENTIONS.md §6 *Release routes*` });
|
|
347
|
+
} else if (def.row === 'released-tag' || def.row === 'released-manual') {
|
|
348
|
+
steps.push({ n: 6, text: `Release rung: add a nested \`release:\` block to .github/project.yml with \`route: deploy-tag\` and \`version-source: tag\` (block style — the descriptor reader parses no \`{ }\` flow map) — the tag deploys production (deploy: ${cfg.deploy}), so candidates are automatic and every final is a human click (CONVENTIONS.md §6 *Release routes*, #492)` });
|
|
349
|
+
} else if (def.row === 'released-no-production') {
|
|
350
|
+
const proposed = cfg.room === 'public' ? 'public-tool' : 'rapid-app';
|
|
351
|
+
steps.push({ n: 6, text: `Release rung: add a nested \`release:\` block to .github/project.yml with \`route: ${proposed}\` and \`version-source: tag\` (block style) — PROPOSED from room: ${cfg.room || 'undeclared'} (public CLI/handbook adopters install → public-tool; an app or tool with few installers → rapid-app; a library its consumers pin → library-fast) — confirm with the human, CONVENTIONS.md §6 *Release routes* (#492)` });
|
|
352
|
+
} else {
|
|
353
|
+
steps.push({ n: 6, text: 'Release rung: exposure: released but production/deploy match no §6 row — no route derives, a human tags; fix `deploy:`/`production:` before wiring a release workflow (CONVENTIONS.md §6, #492)' });
|
|
354
|
+
return steps;
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
// 6b — the release workflow.
|
|
358
|
+
const texts = ctx.workflowTexts || {};
|
|
359
|
+
const releaseWf = Object.keys(texts).find((f) => /colab release cut/.test(texts[f] || ''));
|
|
360
|
+
if (releaseWf) {
|
|
361
|
+
steps.push({ n: 6, text: `Release workflow present (.github/workflows/${releaseWf}) — check its \`HANDBOOK_REF\` names a ref the handbook carries (#480) and its \`runs-on\` is the self-hosted label on a private repo` });
|
|
362
|
+
} else {
|
|
363
|
+
steps.push({ n: 6, text: 'Copy the release workflow — `colab template release-auto`, then walk its `# EDIT:` points: `HANDBOOK_REF` (a channel or tag the handbook carries, #480), the test-suite workflow `name:`, and on a PRIVATE repo the self-hosted runner label from ci.yml on every job except `npm` (#492)' });
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
// 6c — a deploy template by stack, only where the tag deploys.
|
|
367
|
+
if (def.row === 'released-tag' || def.row === 'released-manual') {
|
|
368
|
+
const files = new Set(ctx.stackFiles || []);
|
|
369
|
+
const deployWf = Object.keys(texts).find((f) => /^deploy/.test(f));
|
|
370
|
+
const php = files.has('composer.json');
|
|
371
|
+
const container = ['Dockerfile', 'compose.yml', 'compose.yaml', 'docker-compose.yml', 'docker-compose.yaml'].some((f) => files.has(f));
|
|
372
|
+
const tpl = php ? 'deploy-xserver' : container ? 'deploy-container' : null;
|
|
373
|
+
if (deployWf) {
|
|
374
|
+
steps.push({ n: 6, text: `Deploy workflow present (.github/workflows/${deployWf}) — nothing to copy` });
|
|
375
|
+
} else if (tpl) {
|
|
376
|
+
steps.push({ n: 6, text: `Copy the deploy template for this stack — \`colab template ${tpl}\` (${php ? 'PHP: composer.json' : 'container: a Dockerfile/compose file'}) — and keep it DISARMED: leave only its \`workflow_dispatch\` trigger until the operator has set its secrets and arms the \`push: tags\` trigger (#492)` });
|
|
377
|
+
} else {
|
|
378
|
+
steps.push({ n: 6, text: 'No deploy template matches this stack (none for it under templates/) — the deploy stays the runbook\'s, by hand (#492)' });
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
// 6d — the first final.
|
|
383
|
+
const tags = ctx.tags;
|
|
384
|
+
if (tags === null || tags === undefined) {
|
|
385
|
+
steps.push({ n: 6, text: 'First final: tags could not be read — check for a `vX.Y.Z` final; `colab release cut` refuses until one exists (#492)' });
|
|
386
|
+
} else if (!tags.some((t) => FINAL_TAG.test(t))) {
|
|
387
|
+
steps.push({ n: 6, text: 'First final: none yet, and `colab release cut` refuses with no final to bump from — the first final is the operator\'s to set (e.g. `git tag -a v0.1.0 -m "v0.1.0" && git push origin v0.1.0`); an agent tags it only when told to (#492)' });
|
|
388
|
+
}
|
|
389
|
+
return steps;
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
function remainingSteps(ctx = {}) {
|
|
393
|
+
const steps = [];
|
|
394
|
+
if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
|
|
395
|
+
steps.push(
|
|
396
|
+
{ n: 3, text: 'Create the full label set (21 names) — `colab labels --ensure`, CONVENTIONS.md §9 step 3 (#206)' },
|
|
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)' },
|
|
398
|
+
);
|
|
399
|
+
if (ctx.fork) {
|
|
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` });
|
|
401
|
+
const agentFiles = ctx.upstreamAgentFiles || [];
|
|
402
|
+
if (agentFiles.length) {
|
|
403
|
+
steps.push({ n: 5, text: `Upstream ships its own agent workflow (${listShort(agentFiles)}): leave it in place, and say in the appended block that fork work runs code-start → code-wrap → code-ship, not that workflow — §9 "A fork of an upstream", step 5` });
|
|
404
|
+
}
|
|
405
|
+
} else {
|
|
406
|
+
steps.push({ n: 5, text: 'Make CLAUDE.md the thin shell — `@AGENTS.md` plus templates/repo-CLAUDE-block.md, repo prose in AGENTS.md (adopt writes both on a new repo, #417), step 5' });
|
|
407
|
+
}
|
|
408
|
+
steps.push(
|
|
224
409
|
{ n: 6, text: "Make sure CI meets §7's outcome — `colab template <name>`, step 6" },
|
|
410
|
+
...(ctx.releaseRung || []),
|
|
225
411
|
{ n: 7, text: 'Register the repo — `colab register`, step 7' },
|
|
226
412
|
{ n: 8, text: 'Leave existing branches alone — nothing to do, step 8' },
|
|
227
413
|
{ n: 9, text: 'Do not create `dev` unless genuinely Tier A or Tier C — nothing to do, step 9' },
|
|
228
|
-
|
|
414
|
+
);
|
|
415
|
+
return steps;
|
|
229
416
|
}
|
|
230
417
|
|
|
231
418
|
// ---------------------------------------------------------------------- row state
|
|
@@ -321,6 +508,24 @@ function detect(io, extra = {}) {
|
|
|
321
508
|
// from a remote's HEAD — tools/colab's adoptGitExtras() is the only place that computes it.
|
|
322
509
|
const trunkSource = (extra && extra.trunkSource) || null;
|
|
323
510
|
|
|
511
|
+
// #449: a repo you own that tracks an upstream you don't. The CLI detects it (a remote named
|
|
512
|
+
// `upstream` whose URL differs from origin's) or takes `--fork`/`--no-fork`; null = not a fork.
|
|
513
|
+
const fork = (extra && extra.fork) || null;
|
|
514
|
+
const upstreamAgentFiles = fork ? detectUpstreamAgentFiles(io) : [];
|
|
515
|
+
const inheritedCodeowners = detectInheritedCodeowners(io, fork, (extra && extra.ownOrg) || null);
|
|
516
|
+
// Only when the CLI handed over `git ls-files` — a pure-io caller without it gets no step-2 line
|
|
517
|
+
// rather than a false "none detected".
|
|
518
|
+
const migrations = extra && Array.isArray(extra.trackedFiles)
|
|
519
|
+
? detectMigrationCandidates(cfg, extra.trackedFiles)
|
|
520
|
+
: null;
|
|
521
|
+
|
|
522
|
+
// #492: on exposure: released, step 6 also wires the release rung.
|
|
523
|
+
const workflowTexts = {};
|
|
524
|
+
for (const f of workflows) workflowTexts[f] = io.readFile(`.github/workflows/${f}`) || '';
|
|
525
|
+
const stackFiles = ['composer.json', 'Dockerfile', 'compose.yml', 'compose.yaml', 'docker-compose.yml', 'docker-compose.yaml']
|
|
526
|
+
.filter((f) => io.readFile(f) !== null);
|
|
527
|
+
const releaseRung = releaseRungSteps({ cfg, workflowTexts, tags: io.tags ? io.tags() : null, stackFiles });
|
|
528
|
+
|
|
324
529
|
return {
|
|
325
530
|
descriptorExists: io.readFile('.github/project.yml') !== null,
|
|
326
531
|
cfg,
|
|
@@ -335,7 +540,12 @@ function detect(io, extra = {}) {
|
|
|
335
540
|
},
|
|
336
541
|
legacyTierLetter,
|
|
337
542
|
consequences,
|
|
338
|
-
|
|
543
|
+
fork,
|
|
544
|
+
upstreamAgentFiles,
|
|
545
|
+
inheritedCodeowners,
|
|
546
|
+
migrations,
|
|
547
|
+
remaining: remainingSteps({ migrations, fork, upstreamAgentFiles, releaseRung }),
|
|
548
|
+
optionalUnanswered: optionalUnanswered(cfg), // #533
|
|
339
549
|
};
|
|
340
550
|
}
|
|
341
551
|
|
|
@@ -578,6 +788,52 @@ function axisMissing(cfg, axis) {
|
|
|
578
788
|
}
|
|
579
789
|
}
|
|
580
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
|
+
|
|
581
837
|
// ---------------------------------------------------------------------- EXPOSURE_SHAPE — the constructor
|
|
582
838
|
|
|
583
839
|
/**
|
|
@@ -747,6 +1003,92 @@ function writesGateVerdict({ writes, effExposure, isTTY, colabHuman, answeredBy
|
|
|
747
1003
|
return { ok: true };
|
|
748
1004
|
}
|
|
749
1005
|
|
|
1006
|
+
const VALID_AUTONOMY = new Set(['manual', 'auto-trunk']);
|
|
1007
|
+
|
|
1008
|
+
/**
|
|
1009
|
+
* #481 — `--autonomy` on `colab adopt`: the maintainer's grant recorded at adoption, so the
|
|
1010
|
+
* descriptor trunk carries from its first commit already says whether an agent may complete
|
|
1011
|
+
* Phase B. `auto-trunk` is the one value that EXPANDS permission (an unattended trunk merge
|
|
1012
|
+
* through `colab ship`), so it carries the same human bar as `writes: direct`; `manual` is the
|
|
1013
|
+
* default and never gated. Append-only like every other answer: a value already on record is
|
|
1014
|
+
* either the same (no-op) or a hand edit, never overwritten here.
|
|
1015
|
+
*
|
|
1016
|
+
* Returns `{ ok, write }` — `write` false when the same value is already declared — or a refusal
|
|
1017
|
+
* `{ ok:false, class, exitCode, message }`. Pure: cmdAdopt passes every fact in.
|
|
1018
|
+
*/
|
|
1019
|
+
function autonomyGateVerdict({ autonomy, current, ceremony, isTTY, colabHuman, answeredBy }) {
|
|
1020
|
+
if (!VALID_AUTONOMY.has(autonomy)) {
|
|
1021
|
+
throw new UserError(`--autonomy must be one of: ${[...VALID_AUTONOMY].join(', ')} (got ${JSON.stringify(autonomy)})`);
|
|
1022
|
+
}
|
|
1023
|
+
if (current !== undefined && current !== null) {
|
|
1024
|
+
if (String(current) === autonomy) return { ok: true, write: false };
|
|
1025
|
+
return {
|
|
1026
|
+
ok: false,
|
|
1027
|
+
class: GATE_CLASS.REPO_SHAPE,
|
|
1028
|
+
exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
|
|
1029
|
+
message: `project.yml already declares autonomy: ${current} — adopt is append-only and never `
|
|
1030
|
+
+ 'rewrites a declared key; change it by hand, as its own reviewed commit',
|
|
1031
|
+
};
|
|
1032
|
+
}
|
|
1033
|
+
if (autonomy !== 'auto-trunk') return { ok: true, write: true };
|
|
1034
|
+
if (ceremony === 'light') {
|
|
1035
|
+
return {
|
|
1036
|
+
ok: false,
|
|
1037
|
+
class: GATE_CLASS.REPO_SHAPE,
|
|
1038
|
+
exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
|
|
1039
|
+
message: 'autonomy: auto-trunk is refused alongside ceremony: light — an unattended merge with '
|
|
1040
|
+
+ 'the ceremony skipped is the one combination the handbook forbids (CONVENTIONS.md §2)',
|
|
1041
|
+
};
|
|
1042
|
+
}
|
|
1043
|
+
if (!(isTTY || (colabHuman && answeredBy))) {
|
|
1044
|
+
return {
|
|
1045
|
+
ok: false,
|
|
1046
|
+
class: GATE_CLASS.HUMAN_GATED,
|
|
1047
|
+
exitCode: EXIT_CODE[GATE_CLASS.HUMAN_GATED],
|
|
1048
|
+
message: 'declaring autonomy: auto-trunk requires a human: answer at an interactive terminal, or '
|
|
1049
|
+
+ 're-run with COLAB_HUMAN=1 and --answered-by "<name>" — it grants agents the trunk merge',
|
|
1050
|
+
};
|
|
1051
|
+
}
|
|
1052
|
+
return { ok: true, write: true };
|
|
1053
|
+
}
|
|
1054
|
+
|
|
1055
|
+
/**
|
|
1056
|
+
* #481 — may `colab adopt --land` commit the descriptor straight to trunk? Landing writes trunk,
|
|
1057
|
+
* so it is the human's act and never an agent's: COLAB_HUMAN=1 AND --answered-by, no TTY
|
|
1058
|
+
* substitute (a TTY proves a terminal, not that this particular write was asked for). It runs only
|
|
1059
|
+
* on a checkout standing ON trunk, never --local (a local descriptor is machine state, never
|
|
1060
|
+
* committed). Pure.
|
|
1061
|
+
*/
|
|
1062
|
+
function landVerdict({ local, colabHuman, answeredBy, trunk, currentBranch }) {
|
|
1063
|
+
if (local) {
|
|
1064
|
+
return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
|
|
1065
|
+
message: '--land cannot combine with --local — a local-only descriptor is never committed (CONVENTIONS.md §9)' };
|
|
1066
|
+
}
|
|
1067
|
+
if (!(colabHuman && answeredBy)) {
|
|
1068
|
+
return { ok: false, class: GATE_CLASS.HUMAN_GATED, exitCode: EXIT_CODE[GATE_CLASS.HUMAN_GATED],
|
|
1069
|
+
message: '--land commits to trunk, which is a human act: re-run with COLAB_HUMAN=1 and --answered-by "<name>"' };
|
|
1070
|
+
}
|
|
1071
|
+
if (!trunk) {
|
|
1072
|
+
return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
|
|
1073
|
+
message: '--land needs a trunk, and none could be determined' };
|
|
1074
|
+
}
|
|
1075
|
+
if (currentBranch !== trunk) {
|
|
1076
|
+
return { ok: false, class: GATE_CLASS.REPO_SHAPE, exitCode: EXIT_CODE[GATE_CLASS.REPO_SHAPE],
|
|
1077
|
+
message: `--land runs on the trunk checkout: this checkout is on ${currentBranch ? JSON.stringify(currentBranch) : 'no branch'}, trunk is ${JSON.stringify(trunk)} — `
|
|
1078
|
+
+ `run it from the checkout standing on ${trunk}` };
|
|
1079
|
+
}
|
|
1080
|
+
return { ok: true };
|
|
1081
|
+
}
|
|
1082
|
+
|
|
1083
|
+
/** The commit message `--land` writes. Conventional, so it is visible in release notes. */
|
|
1084
|
+
function landCommitMessage({ answeredBy, paths }) {
|
|
1085
|
+
return 'chore: adopt the colab-handbook conventions — land the descriptor on trunk\n\n'
|
|
1086
|
+
+ `Committed by \`colab adopt --land\` (COLAB_HUMAN=1, --answered-by ${JSON.stringify(answeredBy)}): `
|
|
1087
|
+
+ 'the maintainer\'s adoption answers, on trunk from its first commit, so the branch that adds '
|
|
1088
|
+
+ 'CI is judged by them.\n\n'
|
|
1089
|
+
+ `Paths: ${paths.join(', ')}\n`;
|
|
1090
|
+
}
|
|
1091
|
+
|
|
750
1092
|
// ---------------------------------------------------------------------- provenance + the append-only write
|
|
751
1093
|
|
|
752
1094
|
/** The comment placed beside a written key — never trusted as identity (see gateVerdict's
|
|
@@ -822,7 +1164,7 @@ function renderDescriptor(rawText, entries) {
|
|
|
822
1164
|
* `tier` may be null (a shape with no legacy letter): the placeholder is then left for a human,
|
|
823
1165
|
* never guessed — the same rule deriveTier itself follows.
|
|
824
1166
|
*/
|
|
825
|
-
function renderClaudeShell(blockTemplate, { version, trunk, tier }) {
|
|
1167
|
+
function renderClaudeShell(blockTemplate, { version, trunk, tier, importAgents = true }) {
|
|
826
1168
|
let block = String(blockTemplate).replace(/^\s*<!--[\s\S]*?-->\s*/, ''); // the paste note
|
|
827
1169
|
block = block.replace('<!-- colab-handbook @ <version> -->', `<!-- colab-handbook @ ${version} -->`);
|
|
828
1170
|
if (trunk) {
|
|
@@ -834,7 +1176,10 @@ function renderClaudeShell(blockTemplate, { version, trunk, tier }) {
|
|
|
834
1176
|
// `<A = … · C = … · B = …>` → the one gloss that applies.
|
|
835
1177
|
block = block.replace(/<A = ([^·>]+?) · C = ([^·>]+?) · B = ([^>]+?)>/, (m, a, c, b) => ({ A: a, B: b, C: c })[tier] || m);
|
|
836
1178
|
}
|
|
837
|
-
|
|
1179
|
+
// #449: a fork with no upstream AGENTS.md gets the block alone — no import of a file adopt
|
|
1180
|
+
// must not create there.
|
|
1181
|
+
const body = block.replace(/\s*$/, '\n');
|
|
1182
|
+
return importAgents ? `@AGENTS.md\n\n${body}` : body;
|
|
838
1183
|
}
|
|
839
1184
|
|
|
840
1185
|
/** The AGENTS.md stub written beside a new shell, only when no AGENTS.md exists. */
|
|
@@ -850,6 +1195,7 @@ function renderAgentsStub() {
|
|
|
850
1195
|
}
|
|
851
1196
|
|
|
852
1197
|
module.exports = {
|
|
1198
|
+
detectInheritedCodeowners,
|
|
853
1199
|
renderClaudeShell,
|
|
854
1200
|
renderAgentsStub,
|
|
855
1201
|
ROW_NAMES,
|
|
@@ -859,6 +1205,9 @@ module.exports = {
|
|
|
859
1205
|
deriveTier,
|
|
860
1206
|
deriveConsequences,
|
|
861
1207
|
remainingSteps,
|
|
1208
|
+
releaseRungSteps,
|
|
1209
|
+
detectUpstreamAgentFiles,
|
|
1210
|
+
detectMigrationCandidates,
|
|
862
1211
|
detect,
|
|
863
1212
|
// commit 2
|
|
864
1213
|
VALID_ROOM,
|
|
@@ -871,12 +1220,22 @@ module.exports = {
|
|
|
871
1220
|
renderMenu,
|
|
872
1221
|
resolveChoice,
|
|
873
1222
|
axisMissing,
|
|
1223
|
+
GATING_ROWS,
|
|
1224
|
+
OPTIONAL_ROWS,
|
|
1225
|
+
axesToAsk,
|
|
1226
|
+
optionalUnanswered,
|
|
1227
|
+
optionalRowsLine,
|
|
1228
|
+
humanAdoptCommand,
|
|
874
1229
|
EXPOSURE_RANK,
|
|
875
1230
|
GATE_CLASS,
|
|
876
1231
|
EXIT_CODE,
|
|
877
1232
|
exposureShapeVerdict,
|
|
878
1233
|
gateVerdict,
|
|
879
1234
|
writesGateVerdict,
|
|
1235
|
+
VALID_AUTONOMY,
|
|
1236
|
+
autonomyGateVerdict,
|
|
1237
|
+
landVerdict,
|
|
1238
|
+
landCommitMessage,
|
|
880
1239
|
provenanceComment,
|
|
881
1240
|
renderDescriptor,
|
|
882
1241
|
};
|
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
|
};
|