@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.8
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/LICENSE +21 -0
- package/README.md +309 -3
- package/README.vi.md +279 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +117 -0
- package/templates/release-auto.yml +470 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13746 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +259 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +481 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +703 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* Write-time validation for the fields of ~/.colab/state.json that other commands later RESOLVE
|
|
4
|
+
* AGAINST GIT: a worktree's `branch` and `path`, and a claim's `branch`.
|
|
5
|
+
*
|
|
6
|
+
* WHY THIS MODULE EXISTS. A worktree/claim pair was once found recorded as
|
|
7
|
+
* `{"branch": "trunk", "path": null}`. The real branch existed and was healthy; only the record was
|
|
8
|
+
* wrong — and it failed silently in three places at once: `landed` could not resolve the ref and
|
|
9
|
+
* answered `unknown`, `doctor` did not classify it as drift (a null path is not a *missing*
|
|
10
|
+
* directory), and `ship` matched claims to the branch BY NAME, found none, and merged with no
|
|
11
|
+
* `Closes #N` — the failure CONVENTIONS.md §4 measured at 26/30 issues, reached by a path nothing
|
|
12
|
+
* checked.
|
|
13
|
+
*
|
|
14
|
+
* THE TRIGGER WAS NOT EXOTIC. `colab claim <N> --worktree <name>` — the first command in code-start —
|
|
15
|
+
* defaulted `--branch` to the literal string `trunk` and stubbed the not-yet-created worktree with
|
|
16
|
+
* `path: null`. `trunk` is a ROLE (the branch sessions merge into: `main` or `dev`), never a branch
|
|
17
|
+
* name; the conventions forbid creating one so named. It was being used as a SENTINEL for "no
|
|
18
|
+
* branch — working on the trunk checkout", stored in the same value space as real branch names, and
|
|
19
|
+
* every consumer read it as a name.
|
|
20
|
+
*
|
|
21
|
+
* So the absence of a branch is now `null`. Null is not a name: nothing can try to resolve it and
|
|
22
|
+
* quietly get a wrong answer, and a `null` branch cannot match a real one in `ship`'s claim lookup.
|
|
23
|
+
*
|
|
24
|
+
* ONLY NEW PROBLEMS ARE REFUSED. Records already on disk in the bad shape must not turn every later
|
|
25
|
+
* `colab` invocation into a crash — that state is precisely what a person runs `colab doctor` to
|
|
26
|
+
* find out about. So this refuses the write that INTRODUCES a problem and passes through one a
|
|
27
|
+
* record already carried, which is what keeps `doctor`'s own writes (flipping a status, repairing a
|
|
28
|
+
* path) working on the very records it exists to fix.
|
|
29
|
+
*/
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Words that name a ROLE rather than a branch. `main` and `dev` are absent on purpose: those are
|
|
33
|
+
* real branch names that a record SHOULD hold. `trunk` never is — it is the word for "whichever of
|
|
34
|
+
* those this repo merges into", and a repo's `project.yml` says which.
|
|
35
|
+
*/
|
|
36
|
+
const ROLE_WORDS = new Set(['trunk']);
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* The one status a worktree record may carry with no path: a stub written by `colab claim
|
|
40
|
+
* --worktree <name>` for a worktree that does not exist yet. It exists so the claim is not read as
|
|
41
|
+
* an orphan (doctor prunes claims whose worktree is not in state); `colab worktree new` replaces it
|
|
42
|
+
* with the real record. Every other status asserts a directory on disk.
|
|
43
|
+
*/
|
|
44
|
+
const PENDING = 'pending';
|
|
45
|
+
|
|
46
|
+
function statusOf(rec) { return (rec && rec.status) || 'running'; }
|
|
47
|
+
|
|
48
|
+
/** Problem with a branch VALUE, or null. `null`/absent is legitimate and means "no branch". */
|
|
49
|
+
function branchProblem(branch) {
|
|
50
|
+
if (branch === null || branch === undefined) return null;
|
|
51
|
+
if (typeof branch !== 'string') return `branch must be a string or null (got ${typeof branch})`;
|
|
52
|
+
const b = branch.trim();
|
|
53
|
+
if (!b) return 'branch is an empty string — write null for "no branch", never ""';
|
|
54
|
+
if (ROLE_WORDS.has(b.toLowerCase())) {
|
|
55
|
+
return `"${branch}" is a ROLE, not a branch name (CONVENTIONS.md §4) — it resolves to no ref, ` +
|
|
56
|
+
'so `landed` cannot classify it and `ship` matches no claims. Use null for "no branch".';
|
|
57
|
+
}
|
|
58
|
+
return null;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Problem with a worktree record's `path`/`status` pairing, or null. */
|
|
62
|
+
function pathProblem(rec) {
|
|
63
|
+
const status = statusOf(rec);
|
|
64
|
+
if (rec.path === null || rec.path === undefined) {
|
|
65
|
+
if (status === PENDING) return null;
|
|
66
|
+
return `path is null while status is "${status}" — only a ${PENDING} claim stub may claim no ` +
|
|
67
|
+
'directory. A record nothing can act on should not be writable.';
|
|
68
|
+
}
|
|
69
|
+
if (typeof rec.path !== 'string' || !rec.path.trim()) {
|
|
70
|
+
return `path must be a non-empty absolute path (got ${JSON.stringify(rec.path)})`;
|
|
71
|
+
}
|
|
72
|
+
return null;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Every problem a worktree record currently has, as {code, message}. The CODE is what the guard
|
|
77
|
+
* compares across a mutation — message text carries the current status and would read as a fresh
|
|
78
|
+
* problem the moment doctor flipped `running` → `merged` on an already-broken record, which is the
|
|
79
|
+
* one case the guard must stay out of the way for.
|
|
80
|
+
*/
|
|
81
|
+
function worktreeProblems(rec) {
|
|
82
|
+
const out = [];
|
|
83
|
+
const b = branchProblem(rec && rec.branch);
|
|
84
|
+
if (b) out.push({ code: 'branch', message: b });
|
|
85
|
+
const p = pathProblem(rec || {});
|
|
86
|
+
if (p) out.push({ code: 'path', message: p });
|
|
87
|
+
return out;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function claimProblems(rec) {
|
|
91
|
+
const b = branchProblem(rec && rec.branch);
|
|
92
|
+
return b ? [{ code: 'branch', message: b }] : [];
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* A place-claim's (#136) `branch` field carries the SAME representation a claim's does — `null`
|
|
97
|
+
* for "the trunk checkout", a real name for a worktree, never the role word `trunk` — so it is
|
|
98
|
+
* validated through the identical `branchProblem` rather than inventing a second check.
|
|
99
|
+
*/
|
|
100
|
+
function placeProblems(rec) {
|
|
101
|
+
const b = branchProblem(rec && rec.branch);
|
|
102
|
+
return b ? [{ code: 'branch', message: b }] : [];
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* The problem CODES each record carries right now — the "before" picture the guard compares
|
|
107
|
+
* against. Cheap enough to take on every mutation, and it holds no values, so a mutation is free to
|
|
108
|
+
* rewrite anything as long as it does not make a record worse.
|
|
109
|
+
*/
|
|
110
|
+
function snapshot(st) {
|
|
111
|
+
const out = { worktrees: {}, claims: {}, places: {} };
|
|
112
|
+
if (!st) return out;
|
|
113
|
+
for (const [k, w] of Object.entries(st.worktrees || {})) out.worktrees[k] = worktreeProblems(w).map((p) => p.code);
|
|
114
|
+
for (const [k, c] of Object.entries(st.claims || {})) out.claims[k] = claimProblems(c).map((p) => p.code);
|
|
115
|
+
for (const [k, p] of Object.entries(st.places || {})) out.places[k] = placeProblems(p).map((x) => x.code);
|
|
116
|
+
return out;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Problems this mutation INTRODUCED: a record that is new, or that has acquired a problem it did
|
|
121
|
+
* not have before. Everything a record was already carrying passes through untouched — that is
|
|
122
|
+
* `colab doctor`'s to report, and refusing it here would mean a legacy-bad record makes every later
|
|
123
|
+
* command fail, including the ones trying to repair it. Returns human-readable strings.
|
|
124
|
+
*/
|
|
125
|
+
function changedProblems(before, afterState) {
|
|
126
|
+
const out = [];
|
|
127
|
+
const prevW = (before && before.worktrees) || {};
|
|
128
|
+
const prevC = (before && before.claims) || {};
|
|
129
|
+
|
|
130
|
+
for (const [name, rec] of Object.entries((afterState && afterState.worktrees) || {})) {
|
|
131
|
+
const had = new Set(prevW[name] || []);
|
|
132
|
+
const isNew = !Object.prototype.hasOwnProperty.call(prevW, name);
|
|
133
|
+
for (const p of worktreeProblems(rec)) {
|
|
134
|
+
if (isNew || !had.has(p.code)) out.push(`worktree "${name}": ${p.message}`);
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
for (const [key, rec] of Object.entries((afterState && afterState.claims) || {})) {
|
|
138
|
+
const had = new Set(prevC[key] || []);
|
|
139
|
+
const isNew = !Object.prototype.hasOwnProperty.call(prevC, key);
|
|
140
|
+
for (const p of claimProblems(rec)) {
|
|
141
|
+
if (isNew || !had.has(p.code)) out.push(`claim ${key}: ${p.message}`);
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
const prevP = (before && before.places) || {};
|
|
145
|
+
for (const [key, rec] of Object.entries((afterState && afterState.places) || {})) {
|
|
146
|
+
const had = new Set(prevP[key] || []);
|
|
147
|
+
const isNew = !Object.prototype.hasOwnProperty.call(prevP, key);
|
|
148
|
+
for (const p of placeProblems(rec)) {
|
|
149
|
+
if (isNew || !had.has(p.code)) out.push(`place ${key}: ${p.message}`);
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
return out;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Problems that applying `patch` to one worktree record would INTRODUCE — the same codes-compared
|
|
157
|
+
* rule `changedProblems` applies to a whole-state mutation, asked ahead of time about a single write.
|
|
158
|
+
* Returns human-readable strings; empty means the write would pass the state guard.
|
|
159
|
+
*
|
|
160
|
+
* WHY (#389): `colab ship` flips its worktree to `status: merged` only AFTER the push to trunk, and
|
|
161
|
+
* that write goes through the guard. A `pending` stub with `path: null` passes every precondition
|
|
162
|
+
* and then refuses exactly that flip ("path is null while status is merged") — with trunk already
|
|
163
|
+
* moved, so every bookkeeping step after the push was skipped. A write the real run would refuse
|
|
164
|
+
* must be a failed precondition, measured before anything irreversible, so it is asked here.
|
|
165
|
+
*/
|
|
166
|
+
function flipProblems(name, rec, patch) {
|
|
167
|
+
if (!rec) return [];
|
|
168
|
+
const had = new Set(worktreeProblems(rec).map((p) => p.code));
|
|
169
|
+
return worktreeProblems({ ...rec, ...patch })
|
|
170
|
+
.filter((p) => !had.has(p.code))
|
|
171
|
+
.map((p) => `worktree "${name}": ${p.message}`);
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/** The refusal text for a non-empty changedProblems() list. */
|
|
175
|
+
function refusalMessage(problems) {
|
|
176
|
+
return ['Refusing to write ~/.colab/state.json — the change would record something nothing can act on:']
|
|
177
|
+
.concat(problems.map((p) => ` • ${p}`))
|
|
178
|
+
.concat([' (a record that cannot be resolved makes `landed` answer unknown and `ship` merge with no Closes)'])
|
|
179
|
+
.join('\n');
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
module.exports = {
|
|
183
|
+
ROLE_WORDS, PENDING, statusOf, branchProblem, pathProblem,
|
|
184
|
+
worktreeProblems, claimProblems, placeProblems, snapshot, changedProblems, flipProblems, refusalMessage,
|
|
185
|
+
};
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* The `--refs` brake reminder (#385). PURE — labels/body in, finding out; all `gh` I/O stays in
|
|
4
|
+
* the CLI, same split as `lib/checklist.js`.
|
|
5
|
+
*
|
|
6
|
+
* THE INCIDENT. A ship landed an issue's code with `colab ship --refs #N`, deliberately keeping
|
|
7
|
+
* it open: its only unticked "done when" items were a live end-to-end proof no code session can
|
|
8
|
+
* produce. After the merge the issue was open, `deps-checked`, unclaimed and carried no hold, so
|
|
9
|
+
* it was startable again AS CODE WORK. An implementer session picked it up, found nothing to do,
|
|
10
|
+
* and sat holding a concurrency slot for about an hour until a human-side watch parked it.
|
|
11
|
+
*
|
|
12
|
+
* `--refs` is a deliberate choice and stays ungated (CONVENTIONS.md §4, #263). What it did not do
|
|
13
|
+
* is ask for the other half of that choice: an issue kept open for a non-code leftover has to say
|
|
14
|
+
* "do not start me" in a form a scheduler reads — a hold label (§5, *Disposition* / *Holds*).
|
|
15
|
+
* This module decides when to remind. It never refuses, and never writes the label itself: which
|
|
16
|
+
* hold, whose wake and which date are the shipper's judgement, the same authorship argument #263
|
|
17
|
+
* made for not auto-filing a `Remainder: #M`.
|
|
18
|
+
*
|
|
19
|
+
* WHEN IT FIRES — all three:
|
|
20
|
+
* 1. the issue was kept open by the `--refs` FLAG (the caller filters; the `tracking` label and
|
|
21
|
+
* the checklist gate are not this path);
|
|
22
|
+
* 2. its body still has at least one unticked `- [ ]` box ANYWHERE — not only under `## Plan`.
|
|
23
|
+
* The incident's leftovers sat under a "Done when" heading, which the close gate's parser
|
|
24
|
+
* (Plan-only, on purpose) cannot see. A reminder may over-fire; a gate may not.
|
|
25
|
+
* 3. it carries NOTHING that already stops a start (`brakeLabel` below).
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
const labels = require('./labels');
|
|
29
|
+
|
|
30
|
+
/** A GitHub checklist line, same shape as checklist.js ITEM_RE. */
|
|
31
|
+
const ITEM_RE = /^\s*[-*]\s*\[([ xX])\]\s*\S/;
|
|
32
|
+
|
|
33
|
+
/** Count checklist boxes anywhere in a body. */
|
|
34
|
+
function countBoxes(body) {
|
|
35
|
+
let total = 0, unticked = 0;
|
|
36
|
+
for (const line of String(body || '').split('\n')) {
|
|
37
|
+
const m = ITEM_RE.exec(line);
|
|
38
|
+
if (!m) continue;
|
|
39
|
+
total++;
|
|
40
|
+
if (m[1] === ' ') unticked++;
|
|
41
|
+
}
|
|
42
|
+
return { total, unticked };
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function names(present) {
|
|
46
|
+
return (present || []).map((n) => (n && typeof n === 'object' ? n.name : n)).filter((n) => n !== undefined && n !== null).map(String);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* The first label already stopping a start, or `null`. Recognised:
|
|
51
|
+
* - `deferred:*` a park (CONVENTIONS.md §5, *Disposition*)
|
|
52
|
+
* - `needs-decision` waiting on a human ruling
|
|
53
|
+
* - a non-code `delivery:*` value routed, not started (`labels.isRouteNotStart`)
|
|
54
|
+
* - `tracking` long-lived memory, referenced by design
|
|
55
|
+
* - any label declared under `holds:` (§5, *Holds*, #360) — passed in as `declaredHolds`
|
|
56
|
+
*/
|
|
57
|
+
function brakeLabel(present, declaredHolds) {
|
|
58
|
+
const have = names(present);
|
|
59
|
+
const declared = new Set((Array.isArray(declaredHolds) ? declaredHolds : []).map(String));
|
|
60
|
+
for (const n of have) {
|
|
61
|
+
if (n.startsWith(labels.DEFERRED_LABEL_PREFIX)) return n;
|
|
62
|
+
if (n === labels.NEEDS_DECISION_LABEL) return n;
|
|
63
|
+
if (n === labels.TRACKING_LABEL) return n;
|
|
64
|
+
if (declared.has(n)) return n;
|
|
65
|
+
}
|
|
66
|
+
if (labels.isRouteNotStart(present)) return have.find((n) => n.startsWith('delivery:')) || 'delivery:*';
|
|
67
|
+
return null;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* The finding for one `--refs`'d issue, or `null` when no reminder is due.
|
|
72
|
+
* Shape: `{ issue, unticked, total, reason }`.
|
|
73
|
+
*/
|
|
74
|
+
function refsBrakeFinding({ issue, body, labels: present, declaredHolds } = {}) {
|
|
75
|
+
const { total, unticked } = countBoxes(body);
|
|
76
|
+
if (unticked === 0) return null;
|
|
77
|
+
if (brakeLabel(present, declaredHolds)) return null;
|
|
78
|
+
return {
|
|
79
|
+
issue, unticked, total,
|
|
80
|
+
reason: `kept open by --refs with ${unticked}/${total} unticked box(es) and no hold — it reads as startable code work after this ship`,
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** The operator-facing lines for one finding — the two shapes §4 offers, in order of preference. */
|
|
85
|
+
function reminderLines(f) {
|
|
86
|
+
return [
|
|
87
|
+
`#${f.issue}: ${f.reason}.`,
|
|
88
|
+
` Leftover is NOT code (a live proof, an ops check, a measurement)? Park it in the same step:`,
|
|
89
|
+
` gh issue edit ${f.issue} --add-label deferred:<date|measurement|external-party> --add-label review-by:<YYYY-MM-DD>`,
|
|
90
|
+
` + one comment: "Hold: deferred:<kind> — owner: <who posts it> — wake: <wake>" / "Because: <what is left>"`,
|
|
91
|
+
` Leftover IS code? Prefer \`Remainder: #M\` on #${f.issue} over --refs, and let it close.`,
|
|
92
|
+
];
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
module.exports = { countBoxes, brakeLabel, refsBrakeFinding, reminderLines };
|