@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.11
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 +312 -3
- package/README.vi.md +281 -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 +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13806 -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 +278 -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-endpoint.js +170 -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-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +521 -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 +740 -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,230 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* "Has this branch landed?" — the one shared answer, so code-sweep and code-ship stop
|
|
4
|
+
* deciding it by eye.
|
|
5
|
+
*
|
|
6
|
+
* THE TRAP, which is why this is a rule and not a habit. The obvious test is "how many commits is
|
|
7
|
+
* the branch ahead?", and it is wrong for every branch we have ever shipped:
|
|
8
|
+
*
|
|
9
|
+
* still-has-cargo = (git log <base>..<branch> non-empty) AND (git diff <base> <branch> non-empty)
|
|
10
|
+
*
|
|
11
|
+
* BOTH conditions, never either. A squash-merge mints a NEW commit with a NEW sha, so the branch's
|
|
12
|
+
* original commits are never ancestors of the base — a commit-count rule calls finished work
|
|
13
|
+
* unfinished forever, and invites re-merging it. The mirror failure is just as real: zero commits
|
|
14
|
+
* ahead but a non-empty diff, because the base moved on underneath. When this was measured on live
|
|
15
|
+
* worktrees there was one of each, and seven branches in this very repo reported 2–4 commits ahead
|
|
16
|
+
* of a base that already contained all of their content.
|
|
17
|
+
*
|
|
18
|
+
* THE HOLE THE TWO-SIGNAL RULE DOES NOT CLOSE, and how this closes it. Squash-merged AND the base
|
|
19
|
+
* advanced afterwards satisfies both conditions — commits ahead, and a diff that now describes the
|
|
20
|
+
* base's later work in reverse — so the rule says "cargo" about work that shipped. The fix is to
|
|
21
|
+
* stop asking about shas and diffs and ask the actual question:
|
|
22
|
+
*
|
|
23
|
+
* does merging this branch into its base change the base's tree at all?
|
|
24
|
+
*
|
|
25
|
+
* `git merge-tree --write-tree <base> <branch>` answers exactly that without touching the working
|
|
26
|
+
* tree, the index, or the network. Tree equal to the base's tree ⇒ the branch introduces nothing
|
|
27
|
+
* ⇒ it has landed, however it was merged and however far the base has moved since.
|
|
28
|
+
*
|
|
29
|
+
* WHY NOT `git cherry` / patch-id, which is the intuitive way to close the same hole: it only works
|
|
30
|
+
* when the branch had exactly ONE commit. A squash of n>1 commits has no patch-id in common with any
|
|
31
|
+
* of them — the squash's patch is their sum — so `git cherry` marks every one `+` (unmerged). We
|
|
32
|
+
* measured it: single-commit squash `-`, two-commit squash `+ +`. It would close the hole for the
|
|
33
|
+
* smallest branches and stay silently wrong for the rest, which is worse than not closing it.
|
|
34
|
+
*
|
|
35
|
+
* WHAT IS STILL NOT COVERED, stated precisely rather than rounded up. If the base has REWRITTEN the
|
|
36
|
+
* branch's work (the same lines, differently), the merge conflicts, so no tree comes back and no
|
|
37
|
+
* content answer is possible. That is reported as `unknown`, never as `landed`. Callers must treat
|
|
38
|
+
* `unknown` as cargo: telling someone their unmerged work is spent costs work, telling them to look
|
|
39
|
+
* again costs a minute. `hasCargo()` encodes that asymmetry so no caller has to remember it.
|
|
40
|
+
*
|
|
41
|
+
* BASE, not trunk. The question is asked against the branch's base — trunk for an ordinary session,
|
|
42
|
+
* a declared `integration:` line for a session cut from one (project.schema.md). A branch cut from a
|
|
43
|
+
* long-lived line and measured against trunk reads as enormous cargo that must never be shipped to
|
|
44
|
+
* trunk. Resolving the base is the caller's job; this module only ever compares the two refs it is
|
|
45
|
+
* given, and never defaults one of them to `main`.
|
|
46
|
+
*
|
|
47
|
+
* No network. Every command here is local; a stale `origin/<base>` is the caller's problem to fetch.
|
|
48
|
+
*
|
|
49
|
+
* WHY THIS EXISTS AS CODE *AND* AS PROSE (CONVENTIONS.md §4), which is normally the duplication this
|
|
50
|
+
* handbook warns about. The two carry different things and neither substitutes:
|
|
51
|
+
* - Prose alone was the status quo, and the status quo is what produced the wrong rule twice in
|
|
52
|
+
* two skills. A rule stated in English is re-derived by whoever reads it, and "count the commits
|
|
53
|
+
* ahead" is what people derive.
|
|
54
|
+
* - Code alone cannot be adopted by a repo that vendors its own copy rather than depending on this
|
|
55
|
+
* one — which a consumer deliberately did, precisely because depending on us means depending on
|
|
56
|
+
* a working tree. They need the RULE, not our implementation of it.
|
|
57
|
+
* So the prose states the rule and its limit, this file is the executable reference, and the tests
|
|
58
|
+
* are what keep them from drifting apart. What the prose must never become is a second, subtly
|
|
59
|
+
* different algorithm — it describes this one.
|
|
60
|
+
*
|
|
61
|
+
* A HAZARD WORTH KNOWING when editing anything executable here: installs symlink into the working
|
|
62
|
+
* TREE (see install.sh). Checking this repo out onto a branch changes the rule for every session on
|
|
63
|
+
* the machine, immediately. Hence: work in a worktree, leave the main checkout on trunk, and keep
|
|
64
|
+
* the fixed corpus in lib/landed.test.js green — it is the only thing standing between a
|
|
65
|
+
* half-finished edit here and every consumer's teardown decision.
|
|
66
|
+
*/
|
|
67
|
+
|
|
68
|
+
const git = require('./git.js');
|
|
69
|
+
|
|
70
|
+
/** Content relationship between a branch and its base. */
|
|
71
|
+
const CONTAINED = 'contained'; // merging the branch would not change the base's tree
|
|
72
|
+
const DIVERGED = 'diverged'; // it would
|
|
73
|
+
const UNKNOWN = 'unknown'; // cannot tell: missing ref, conflict, git too old
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* The pure half — signals in, verdict out, so CI can test the rule without building repositories
|
|
77
|
+
* for every case. `containment` is authoritative when it has an answer; the two-signal rule is the
|
|
78
|
+
* fallback for a git too old for `merge-tree --write-tree` (< 2.38) and is documented as such in
|
|
79
|
+
* the verdict, because a caller reading `method: 'two-signal'` is being told which hole is open.
|
|
80
|
+
*
|
|
81
|
+
* Returns { state: 'landed'|'cargo'|'unknown', method, why }.
|
|
82
|
+
*/
|
|
83
|
+
function classify({ commitsAhead, diffEmpty, containment }) {
|
|
84
|
+
if (containment === CONTAINED) {
|
|
85
|
+
return { state: 'landed', method: 'content', why: 'merging the branch would not change the base tree' };
|
|
86
|
+
}
|
|
87
|
+
if (containment === DIVERGED) {
|
|
88
|
+
return { state: 'cargo', method: 'content', why: 'merging the branch would change the base tree' };
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// containment === UNKNOWN → the two-signal rule, with its hole named.
|
|
92
|
+
//
|
|
93
|
+
// Guard the inputs FIRST. This function is exported as the pure half precisely so a repo that
|
|
94
|
+
// vendors its own copy can feed it facts it gathered itself, and a fact that failed to compute
|
|
95
|
+
// arrives here as undefined/null rather than as an error. Unguarded, `undefined > 0` is false,
|
|
96
|
+
// so "I could not measure this branch" would classify as `landed` — the one direction this
|
|
97
|
+
// module exists to never fail in. Absent facts mean no answer, not a clean one.
|
|
98
|
+
const factsUsable = Number.isInteger(commitsAhead) && commitsAhead >= 0 && typeof diffEmpty === 'boolean';
|
|
99
|
+
if (!factsUsable) {
|
|
100
|
+
return {
|
|
101
|
+
state: 'unknown',
|
|
102
|
+
method: 'none',
|
|
103
|
+
why: 'no content answer, and the two-signal facts are missing or malformed ' +
|
|
104
|
+
`(commitsAhead=${JSON.stringify(commitsAhead)}, diffEmpty=${JSON.stringify(diffEmpty)}) — treat as cargo`,
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const cargo = commitsAhead > 0 && !diffEmpty;
|
|
109
|
+
if (!cargo) {
|
|
110
|
+
return {
|
|
111
|
+
state: 'landed',
|
|
112
|
+
method: 'two-signal',
|
|
113
|
+
why: commitsAhead === 0
|
|
114
|
+
? 'no commits ahead of the base'
|
|
115
|
+
: 'commits ahead, but no diff against the base (squash-merged)',
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
return {
|
|
119
|
+
state: 'unknown',
|
|
120
|
+
method: 'two-signal',
|
|
121
|
+
why: 'commits ahead AND a diff, but no content answer — a squash followed by base movement ' +
|
|
122
|
+
'looks identical to genuine cargo under this rule; treat as cargo and check by hand',
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/** Callers act on this, not on `state`: anything short of a positive `landed` keeps its cargo. */
|
|
127
|
+
function hasCargo(verdict) {
|
|
128
|
+
return !verdict || verdict.state !== 'landed';
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* The git half. `base` and `branch` are ref names (`dev`, `origin/dev`, `feat/x-12`) — no defaulting
|
|
133
|
+
* happens here for `base`; a caller that cannot resolve it must fail rather than guess `main`.
|
|
134
|
+
*
|
|
135
|
+
* `branch` gets ONE deliberate exception (#189): a bare name absent locally falls back to
|
|
136
|
+
* `origin/<branch>` when that resolves — see `resolveBranchRef` above for why and its limits. When
|
|
137
|
+
* the fallback fires, `facts.branch` is the ref that actually answered (not the bare name given),
|
|
138
|
+
* and the verdict's `why` says so explicitly — so neither the table nor `--json` output is ever
|
|
139
|
+
* silently about a different ref than the caller named.
|
|
140
|
+
*
|
|
141
|
+
* Returns { state, method, why, base, branch, commitsAhead, diffEmpty, containment }.
|
|
142
|
+
*/
|
|
143
|
+
function landedState(repoAbs, base, branch) {
|
|
144
|
+
const facts = { base, branch, commitsAhead: null, diffEmpty: null, containment: UNKNOWN };
|
|
145
|
+
|
|
146
|
+
if (!base || !branch || base === branch) {
|
|
147
|
+
return { ...classifyUnresolvable('base and branch must be two different refs'), ...facts };
|
|
148
|
+
}
|
|
149
|
+
const haveBase = git.git(['rev-parse', '--verify', '--quiet', base], repoAbs).ok;
|
|
150
|
+
const resolved = resolveBranchRef(repoAbs, branch);
|
|
151
|
+
if (resolved.viaRemote) facts.branch = resolved.ref; // the ref that answered — visible everywhere facts.branch is read
|
|
152
|
+
|
|
153
|
+
if (!haveBase || !resolved.ok) {
|
|
154
|
+
const missing = [!haveBase ? base : null, !resolved.ok ? branch : null].filter(Boolean).join(', ');
|
|
155
|
+
return { ...classifyUnresolvable(`ref not found: ${missing}`), ...facts };
|
|
156
|
+
}
|
|
157
|
+
const askRef = resolved.ref;
|
|
158
|
+
|
|
159
|
+
const count = git.git(['rev-list', '--count', `${base}..${askRef}`], repoAbs);
|
|
160
|
+
facts.commitsAhead = count.ok ? parseInt(count.stdout, 10) || 0 : 0;
|
|
161
|
+
// `diff --quiet` exits 0 when identical, 1 when they differ. Any other code is an error, and an
|
|
162
|
+
// error must not read as "identical" — that is the direction that loses work.
|
|
163
|
+
const diff = git.git(['diff', '--quiet', base, askRef], repoAbs);
|
|
164
|
+
facts.diffEmpty = diff.code === 0;
|
|
165
|
+
|
|
166
|
+
facts.containment = containmentOf(repoAbs, base, askRef);
|
|
167
|
+
const verdict = classify(facts);
|
|
168
|
+
if (resolved.viaRemote) {
|
|
169
|
+
verdict.why = `resolved "${branch}" → "${askRef}" (no local ref, but the remote one does) — ${verdict.why}`;
|
|
170
|
+
}
|
|
171
|
+
return { ...verdict, ...facts };
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* `git merge-tree --write-tree` exit codes, verified rather than assumed:
|
|
176
|
+
* 0 → clean merge; stdout's first line is the resulting tree (equal to the base's tree ⇒ contained)
|
|
177
|
+
* 1 → CONFLICT. Not "a clean merge with changes" — a clean merge with changes also exits 0, with a
|
|
178
|
+
* different tree. A conflict yields no usable tree, so the honest answer is UNKNOWN.
|
|
179
|
+
* other → the flag is unsupported (git < 2.38) or the invocation failed → UNKNOWN.
|
|
180
|
+
*/
|
|
181
|
+
function containmentOf(repoAbs, base, branch) {
|
|
182
|
+
const baseTree = git.git(['rev-parse', `${base}^{tree}`], repoAbs);
|
|
183
|
+
if (!baseTree.ok) return UNKNOWN;
|
|
184
|
+
const mt = git.git(['merge-tree', '--write-tree', base, branch], repoAbs);
|
|
185
|
+
if (mt.code !== 0) return UNKNOWN;
|
|
186
|
+
const mergedTree = mt.stdout.split('\n')[0].trim();
|
|
187
|
+
if (!/^[0-9a-f]{40,64}$/.test(mergedTree)) return UNKNOWN;
|
|
188
|
+
return mergedTree === baseTree.stdout ? CONTAINED : DIVERGED;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
function classifyUnresolvable(why) {
|
|
192
|
+
return { state: 'unknown', method: 'none', why };
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* Resolve `branch` against local refs first; fall back to `origin/<branch>` when the local ref is
|
|
197
|
+
* absent and the remote one resolves (#189).
|
|
198
|
+
*
|
|
199
|
+
* WHY THIS EXISTS: every other surface in this toolchain — worktree records, `git branch -r`
|
|
200
|
+
* stripped of its remote, `colab`'s own tables — hands this module a BARE name, never an
|
|
201
|
+
* `origin/`-qualified one. For a branch that only ever reached the remote (pushed, then the local
|
|
202
|
+
* ref pruned or never fetched), the bare name used to resolve to nothing and report `ref not found`
|
|
203
|
+
* — the one form that gave a useless answer, in exactly the sweep this fallback exists for: stale
|
|
204
|
+
* REMOTE branches, where that is every candidate.
|
|
205
|
+
*
|
|
206
|
+
* Never fires for a name that already names a remote explicitly (`origin/...`, `refs/...`) —
|
|
207
|
+
* resolving THAT further would silently answer about a third ref the caller never asked for. A
|
|
208
|
+
* genuinely missing ref (absent both locally and on `origin`) keeps its current honest `ref not
|
|
209
|
+
* found` — this only widens which local absence still has an answer.
|
|
210
|
+
*
|
|
211
|
+
* Returns `{ ok, ref, viaRemote }`. `ref` is the one to actually run git against; `viaRemote` is
|
|
212
|
+
* true only when the fallback fired, so the caller can say — in the verdict, not just in this
|
|
213
|
+
* function — that the answer came from the remote ref, not the one named.
|
|
214
|
+
*/
|
|
215
|
+
function resolveBranchRef(repoAbs, branch, remote = git.remoteInfo(repoAbs).name || 'origin') {
|
|
216
|
+
if (typeof branch !== 'string' || !branch) return { ok: false, ref: branch, viaRemote: false };
|
|
217
|
+
if (git.git(['rev-parse', '--verify', '--quiet', branch], repoAbs).ok) {
|
|
218
|
+
return { ok: true, ref: branch, viaRemote: false };
|
|
219
|
+
}
|
|
220
|
+
if (branch.startsWith(`${remote}/`) || branch.startsWith('refs/')) {
|
|
221
|
+
return { ok: false, ref: branch, viaRemote: false }; // already remote-qualified — no further guessing
|
|
222
|
+
}
|
|
223
|
+
const remoteRef = `${remote}/${branch}`; // #301: the resolved remote — `origin` in an origin repo
|
|
224
|
+
if (git.git(['rev-parse', '--verify', '--quiet', remoteRef], repoAbs).ok) {
|
|
225
|
+
return { ok: true, ref: remoteRef, viaRemote: true };
|
|
226
|
+
}
|
|
227
|
+
return { ok: false, ref: branch, viaRemote: false };
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
module.exports = { classify, landedState, hasCargo, containmentOf, resolveBranchRef, CONTAINED, DIVERGED, UNKNOWN };
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* Local-only adoption (#393) — the pure half of `colab adopt --local`, and the one definition of
|
|
4
|
+
* the "adopted locally, not committed" state the audit and handbook-sync recognise.
|
|
5
|
+
*
|
|
6
|
+
* The shape (CONVENTIONS.md §9, "Working in a repo you don't own"): a repo whose owner has not
|
|
7
|
+
* adopted this handbook and reviews and merges changes himself. Committing handbook files there
|
|
8
|
+
* is not an option, so everything the fleet needs stays OUT of his history:
|
|
9
|
+
*
|
|
10
|
+
* - `.github/project.yml` lives in the local clone only. Every reader (colab's own
|
|
11
|
+
* `projectDoc()`/ports reader, adopt, code-start's `cat`, the audit's local source) reads the
|
|
12
|
+
* WORKING TREE, not git — so an untracked file is as good as a committed one to them.
|
|
13
|
+
* - It is hidden by `.git/info/exclude`, never `.gitignore`: a `.gitignore` entry is itself a
|
|
14
|
+
* tracked file, which is exactly the commit we are avoiding. `git status --porcelain -uall`
|
|
15
|
+
* does not report an excluded file, so the dirty-checkout and drift checks stay quiet.
|
|
16
|
+
* - `trunk:` names the FLEET's own integration branch, never the owner's default branch — so
|
|
17
|
+
* claims, worktrees, grading and `colab ship` land there unchanged, and the owner's trunk is
|
|
18
|
+
* only ever reached by a pull request he merges.
|
|
19
|
+
*
|
|
20
|
+
* Everything here is pure (text in, text/verdict out); tools/colab does the IO.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Paths hidden by `.git/info/exclude`, root-anchored (a leading `/`) so they match only at the
|
|
25
|
+
* repo root — `CLAUDE.local.md` in a subdirectory the owner commits must stay visible.
|
|
26
|
+
* `.claude/plans/` is the plan-file scratch dir code-start already excludes the same way.
|
|
27
|
+
*/
|
|
28
|
+
const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md', '/.claude/plans/'];
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* LOCAL_EXCLUDE_PATHS plus the worktree subdir (`colab worktree new` creates worktrees INSIDE the
|
|
32
|
+
* clone, `.worktrees/` by default). An adopted repo hides that dir in its own committed
|
|
33
|
+
* `.gitignore`; the owner's repo does not, so without this line every worktree shows up in the
|
|
34
|
+
* main checkout's `git status` — measured on the #393 fixture the moment the first one was cut.
|
|
35
|
+
*/
|
|
36
|
+
function localExcludePaths(worktreeSubdir) {
|
|
37
|
+
const sub = String(worktreeSubdir || '.worktrees').replace(/^\/+|\/+$/g, '');
|
|
38
|
+
return [...LOCAL_EXCLUDE_PATHS, `/${sub}/`];
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const EXCLUDE_HEADER = '# colab-handbook: local-only adoption (#393) — handbook files this clone keeps out of the owner\'s history';
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Which of LOCAL_EXCLUDE_PATHS `existingText` (the current `info/exclude`, or null) does not
|
|
45
|
+
* already carry. A line counts as present written with or without the leading `/` — an operator
|
|
46
|
+
* who hand-added `.github/project.yml` is not handed a duplicate.
|
|
47
|
+
*/
|
|
48
|
+
function missingExcludeLines(existingText, paths = localExcludePaths()) {
|
|
49
|
+
const have = new Set(
|
|
50
|
+
String(existingText || '').split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'))
|
|
51
|
+
.map((l) => l.replace(/^\//, '')),
|
|
52
|
+
);
|
|
53
|
+
return paths.filter((p) => !have.has(p.replace(/^\//, '')));
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** The text to append to `info/exclude` — '' when nothing is missing (idempotent re-run). */
|
|
57
|
+
function excludeAppendText(existingText, paths = localExcludePaths()) {
|
|
58
|
+
const missing = missingExcludeLines(existingText, paths);
|
|
59
|
+
if (!missing.length) return '';
|
|
60
|
+
const lead = existingText && !String(existingText).endsWith('\n') ? '\n' : '';
|
|
61
|
+
return `${lead}${EXCLUDE_HEADER}\n${missing.join('\n')}\n`;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* The stub CLAUDE.local.md — the operating note that carries the rules the owner's repo cannot.
|
|
66
|
+
* Written only when absent; never overwritten (it is the operator's to edit from here on).
|
|
67
|
+
*/
|
|
68
|
+
function claudeLocalStub({ trunk, ownerTrunk }) {
|
|
69
|
+
const owner = ownerTrunk || '<the owner\'s default branch>';
|
|
70
|
+
return `# CLAUDE.local.md — local-only, never committed
|
|
71
|
+
|
|
72
|
+
This clone works in a repository the fleet does **not** own (colab-handbook CONVENTIONS.md §9,
|
|
73
|
+
"Working in a repo you don't own"). Its handbook files — \`.github/project.yml\` and this note —
|
|
74
|
+
are hidden by \`.git/info/exclude\` and must never be committed here.
|
|
75
|
+
|
|
76
|
+
## Where work lands
|
|
77
|
+
|
|
78
|
+
- **Our trunk is \`${trunk}\`** — the fleet's integration branch. Sessions branch off it and
|
|
79
|
+
\`colab ship\` merges into it, exactly as on any adopted repo.
|
|
80
|
+
- **\`${owner}\` is the owner's trunk. Never push to it, merge into it, or open work on it
|
|
81
|
+
directly.** It is reached only by a pull request from \`${trunk}\` that the owner reviews and
|
|
82
|
+
merges himself — \`colab deliver --dry\` shows what is pending, \`COLAB_HUMAN=1 colab deliver\`
|
|
83
|
+
opens (or refreshes) that one PR (needs \`owner: { branch: ${owner} }\` in the local
|
|
84
|
+
\`.github/project.yml\`, which \`colab adopt --local\` writes when it detects the branch).
|
|
85
|
+
|
|
86
|
+
## What stays off
|
|
87
|
+
|
|
88
|
+
- **Scheduled autopilot stays OFF for this repo.** It would triage and start the owner's own
|
|
89
|
+
issues, not only ours — there is no way today to scope it to the fleet's issues.
|
|
90
|
+
- No CI templates, CODEOWNERS, CLAUDE.md conventions block or repo topic: nothing gates on them,
|
|
91
|
+
and each would be a commit the owner never asked for.
|
|
92
|
+
|
|
93
|
+
## Owner's rules
|
|
94
|
+
|
|
95
|
+
<!-- Add whatever the owner asked for: review expectations, branches he uses, contacts. -->
|
|
96
|
+
`;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** What `adopt --local` deliberately does NOT do, and why — printed so the gap is a decision on
|
|
100
|
+
* record, never a step someone assumes was skipped by accident. */
|
|
101
|
+
const NOT_DONE = [
|
|
102
|
+
{ what: 'CI templates (.github/workflows/)', why: 'a commit to the owner\'s repo. colab ship still gates on CI at the integration branch\'s head: if none of the owner\'s workflows runs on that branch, every ship is human-gated (a ci-granted exemption per branch) — find out which it is before the first ship' },
|
|
103
|
+
{ what: 'CODEOWNERS', why: 'a commit to the owner\'s repo; nothing gates on it' },
|
|
104
|
+
{ what: 'CLAUDE.md conventions block', why: 'a commit to the owner\'s repo; CLAUDE.local.md carries the local rules instead' },
|
|
105
|
+
{ what: 'repo topic', why: 'a change to the owner\'s repo settings; it only feeds fleet-wide discovery' },
|
|
106
|
+
{ what: 'the full label set', why: 'only the load-bearing four were ensured (colab labels --ensure --minimal); the rest are opt-in by use' },
|
|
107
|
+
{ what: 'colab register / the dashboard\'s repo scan', why: 'machine-local; register it yourself if you want it listed, and refresh the dashboard\'s cached scan — it does not pick a new repo up on its own' },
|
|
108
|
+
{ what: 'scheduled autopilot', why: 'must stay OFF here — it would triage and start the owner\'s issues, not only the fleet\'s' },
|
|
109
|
+
];
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* The adoption state of a checkout, from three facts the caller measures:
|
|
113
|
+
* exists — `.github/project.yml` is in the working tree
|
|
114
|
+
* tracked — git tracks it (`git ls-files --error-unmatch`); null when not a git checkout
|
|
115
|
+
* ignored — git ignores it (`git check-ignore`); null when not a git checkout
|
|
116
|
+
*
|
|
117
|
+
* Returns one of:
|
|
118
|
+
* 'none' no descriptor at all
|
|
119
|
+
* 'committed' tracked — the ordinary adopted repo (or not a git checkout: nothing to say)
|
|
120
|
+
* 'local' untracked AND ignored — adopted locally, not committed (#393)
|
|
121
|
+
* 'untracked' untracked and NOT ignored — a descriptor about to be committed by accident
|
|
122
|
+
* (or simply not committed yet); `git status` shows it
|
|
123
|
+
*/
|
|
124
|
+
function localAdoptionState({ exists, tracked, ignored }) {
|
|
125
|
+
if (!exists) return 'none';
|
|
126
|
+
if (tracked === null || tracked === undefined || tracked) return 'committed';
|
|
127
|
+
return ignored ? 'local' : 'untracked';
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
module.exports = {
|
|
131
|
+
LOCAL_EXCLUDE_PATHS, localExcludePaths, EXCLUDE_HEADER, missingExcludeLines, excludeAppendText,
|
|
132
|
+
claudeLocalStub, NOT_DONE, localAdoptionState,
|
|
133
|
+
};
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* "This merge changed a dependency lockfile — the checkout it landed in has NOT re-installed"
|
|
4
|
+
* (#304).
|
|
5
|
+
*
|
|
6
|
+
* Measured shape. A session squash-merges a branch that adds a Composer package whose service
|
|
7
|
+
* provider registers routes. The merge lands in the SHARED TRUNK CHECKOUT — `colab ship` commits
|
|
8
|
+
* there directly when the target is trunk, not in a throwaway worktree — so afterwards:
|
|
9
|
+
* `composer.lock` on trunk lists the new package, `vendor/` does not contain it (merging a branch
|
|
10
|
+
* does not run `composer install`), the provider never loads, `php artisan route:list` reports the
|
|
11
|
+
* package's routes as absent, and an always-on trunk dev server regenerating route bindings from
|
|
12
|
+
* that list DELETES nine previously-committed output files. The trunk checkout is now dirty, and
|
|
13
|
+
* ship's "trunk checkout ready" precondition blocks EVERY other session's merge — including one
|
|
14
|
+
* whose diff never touched anything related.
|
|
15
|
+
*
|
|
16
|
+
* So one merge that adds a dependency can silently brick every other session's ship, and the
|
|
17
|
+
* session that discovers it discovers it as an unexplained "9 files deleted" diff.
|
|
18
|
+
*
|
|
19
|
+
* This module is the DETECTOR half: given the paths a merge commit changed, which of them are
|
|
20
|
+
* dependency lockfiles, and what would a human run to reconcile the checkout. It decides nothing
|
|
21
|
+
* else — the caller (tools/colab) chooses between handing the repo's own `.colab/hooks/post-ship`
|
|
22
|
+
* the job and printing a warning.
|
|
23
|
+
*
|
|
24
|
+
* PURE BY CONSTRUCTION, same posture as dirty-owner.js / base-ci-verdict.js / shipguard.js: plain
|
|
25
|
+
* data in, a verdict out. No git, no gh, no fs, no clock, no subprocess — the caller does the
|
|
26
|
+
* `git diff --name-only` and hands the result over. Every branch is directly reachable from
|
|
27
|
+
* `node --test`, which is the whole reason logic lives here and not inline in `tools/colab`.
|
|
28
|
+
*
|
|
29
|
+
* `install` IS ADVICE TEXT PRINTED TO A HUMAN — never a string this repo executes. Running
|
|
30
|
+
* `composer install` on a shared checkout is a side effect the CLI has no standing to perform:
|
|
31
|
+
* the trunk checkout may carry local platform config, a partially-migrated database, or a
|
|
32
|
+
* dev server mid-request. HELP_WORKTREE's hooks contract already rules on this class ("the
|
|
33
|
+
* portable core does only universal steps; machine-specific steps — DB cloning, dependency
|
|
34
|
+
* symlinking, dev-server restarts — live in OPTIONAL repo hooks, not here"), and dependency
|
|
35
|
+
* installation is squarely that. The escape hatch is `.colab/hooks/post-ship`, three lines of
|
|
36
|
+
* shell the adopting repo owns.
|
|
37
|
+
*
|
|
38
|
+
* ADVISORY ONLY, and it has no choice: detection is only possible AFTER the squash is pushed, so
|
|
39
|
+
* there is nothing left to refuse. Nothing here is wired into any precondition, and a wrong
|
|
40
|
+
* answer costs a misleading line, never a merge.
|
|
41
|
+
*/
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The lockfiles this recognises, most-specific first. HONEST, NOT EXHAUSTIVE — stated plainly
|
|
45
|
+
* because a list that quietly under-reports is worse than no list at all: a repo whose lockfile is
|
|
46
|
+
* missing here gets no warning and no hint that one was owed. That is an accepted, escapable gap
|
|
47
|
+
* (`.colab/hooks/post-ship` fires regardless of what this table knows), not a bug to hide.
|
|
48
|
+
*
|
|
49
|
+
* `install` favours the reproducible, lockfile-respecting form of each manager where one exists
|
|
50
|
+
* (`npm ci` over `npm install`), because reconciling a checkout to a lockfile is exactly the job
|
|
51
|
+
* those forms are for.
|
|
52
|
+
*/
|
|
53
|
+
const LOCKFILES = [
|
|
54
|
+
{ file: 'composer.lock', manager: 'composer', install: 'composer install' },
|
|
55
|
+
{ file: 'package-lock.json', manager: 'npm', install: 'npm ci' },
|
|
56
|
+
{ file: 'pnpm-lock.yaml', manager: 'pnpm', install: 'pnpm install --frozen-lockfile' },
|
|
57
|
+
{ file: 'yarn.lock', manager: 'yarn', install: 'yarn install --immutable' },
|
|
58
|
+
{ file: 'bun.lockb', manager: 'bun', install: 'bun install --frozen-lockfile' },
|
|
59
|
+
{ file: 'Gemfile.lock', manager: 'bundler', install: 'bundle install' },
|
|
60
|
+
{ file: 'Cargo.lock', manager: 'cargo', install: 'cargo fetch' },
|
|
61
|
+
{ file: 'poetry.lock', manager: 'poetry', install: 'poetry install --sync' },
|
|
62
|
+
{ file: 'uv.lock', manager: 'uv', install: 'uv sync --frozen' },
|
|
63
|
+
{ file: 'go.sum', manager: 'go', install: 'go mod download' },
|
|
64
|
+
];
|
|
65
|
+
|
|
66
|
+
/** Escape a literal filename for embedding in a RegExp source. */
|
|
67
|
+
function esc(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Which of `paths` are dependency lockfiles?
|
|
71
|
+
*
|
|
72
|
+
* @param {string[]} paths repo-relative paths, as `git diff --name-only` prints them.
|
|
73
|
+
* @returns {{path: string, manager: string, install: string}[]} one entry per matching path,
|
|
74
|
+
* in the order the paths arrived, de-duplicated by path.
|
|
75
|
+
*
|
|
76
|
+
* Anchored `(^|\/)`, matching `newMigrations`' idiom in tools/colab, so a monorepo's
|
|
77
|
+
* `packages/api/composer.lock` counts — the skew this detects is per-installed-tree, and a
|
|
78
|
+
* workspace package has its own. A path that merely CONTAINS a lockfile's name
|
|
79
|
+
* (`composer.lock.bak`, `docs/package-lock.json.md`) is not one, so the match is anchored at both
|
|
80
|
+
* ends: separator-or-start before, end-of-string after.
|
|
81
|
+
*/
|
|
82
|
+
function changedLockfiles(paths) {
|
|
83
|
+
if (!Array.isArray(paths)) return [];
|
|
84
|
+
const out = [];
|
|
85
|
+
const seen = new Set();
|
|
86
|
+
for (const raw of paths) {
|
|
87
|
+
if (typeof raw !== 'string') continue;
|
|
88
|
+
const p = raw.trim();
|
|
89
|
+
if (!p || seen.has(p)) continue;
|
|
90
|
+
for (const lf of LOCKFILES) {
|
|
91
|
+
if (new RegExp(`(^|/)${esc(lf.file)}$`).test(p)) {
|
|
92
|
+
seen.add(p);
|
|
93
|
+
out.push({ path: p, manager: lf.manager, install: lf.install });
|
|
94
|
+
break;
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
return out;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* The human-facing warning for a drift nobody handled — one string, so the wording lives next to
|
|
103
|
+
* the detector that decided it rather than being reassembled at each call site.
|
|
104
|
+
*
|
|
105
|
+
* Names the lockfile AND the command, because the measured failure is not "someone forgot to run
|
|
106
|
+
* an install" — it is that the NEXT session meets a checkout deleting committed files and has no
|
|
107
|
+
* way to connect that to a merge that already scrolled past.
|
|
108
|
+
*/
|
|
109
|
+
function driftWarning(hits) {
|
|
110
|
+
if (!hits || !hits.length) return null;
|
|
111
|
+
const each = hits.map((h) => `${h.path} → \`${h.install}\``).join('; ');
|
|
112
|
+
return `${hits.length} dependency lockfile(s) changed in this merge and this checkout was NOT re-installed: ${each}. ` +
|
|
113
|
+
'Until someone does, anything regenerating committed output from the installed tree (a route/binding ' +
|
|
114
|
+
'generator, an always-on dev server) can DELETE those files and leave the checkout dirty — which blocks ' +
|
|
115
|
+
"every other session's ship, not just this one (#304). Repos that want this done automatically add " +
|
|
116
|
+
'`.colab/hooks/post-ship`.';
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
module.exports = { changedLockfiles, driftWarning, LOCKFILES };
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* #367: whether a squash `colab ship` lands may name the machine that landed it.
|
|
4
|
+
*
|
|
5
|
+
* #350 writes `Machine: <label>` on every squash so cross-machine conflicts are measurable from
|
|
6
|
+
* git alone. The label is a normalised HOSTNAME, and a commit message is the one artifact that can
|
|
7
|
+
* never be edited after it is pushed. On a private repository that is the traceability #350 wanted;
|
|
8
|
+
* on a PUBLIC one it publishes an internal hostname permanently, once per ship. The same goes for
|
|
9
|
+
* the `on <host> (machine <id>)` tail of #324's `Colab-Adopted:` trailer.
|
|
10
|
+
*
|
|
11
|
+
* So the decision reads the destination, not the machine:
|
|
12
|
+
*
|
|
13
|
+
* 1. the forge says PUBLIC → omit (the measured fact wins)
|
|
14
|
+
* 2. project.yml declares `room: public` → omit (the repo's own marker — covers a repo that
|
|
15
|
+
* is private today but declared for publication,
|
|
16
|
+
* whose history goes public with it)
|
|
17
|
+
* 3. the forge says PRIVATE / INTERNAL → include (#350 unchanged)
|
|
18
|
+
* 4. the forge could not be read, and `room:` is `solo` or `team`
|
|
19
|
+
* → include (the declared room is the fallback)
|
|
20
|
+
* 5. the forge could not be read, no `room:` → OMIT, and say so — FAIL CLOSED. A missing trailer
|
|
21
|
+
* costs one traceability line; a published hostname
|
|
22
|
+
* cannot be taken back. Declaring `room:` restores it.
|
|
23
|
+
*
|
|
24
|
+
* Pure: no git, no network. The caller hands in the host label, the visibility it read (or null),
|
|
25
|
+
* and the descriptor's `room:` value.
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
const VISIBLE = new Set(['PUBLIC']);
|
|
29
|
+
const HIDDEN = new Set(['PRIVATE', 'INTERNAL']);
|
|
30
|
+
const PRIVATE_ROOMS = new Set(['solo', 'team']);
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* @param {{ label: string|null, visibility: string|null, room: string|null|undefined }} input
|
|
34
|
+
* @returns {{ include: boolean, line: string|null, visibility: string|null, room: string|null,
|
|
35
|
+
* reason: string, failClosed: boolean }}
|
|
36
|
+
*/
|
|
37
|
+
function decide({ label, visibility, room }) {
|
|
38
|
+
const d = mayNameHost({ visibility, room });
|
|
39
|
+
const base = { visibility: d.visibility, room: d.room, failClosed: d.failClosed };
|
|
40
|
+
if (!d.include) {
|
|
41
|
+
return { ...base, include: false, line: null, reason: d.failClosed
|
|
42
|
+
? `${d.reason} — omitted, failing closed (#367); declare room: solo|team to keep it`
|
|
43
|
+
: `${d.reason} — a hostname in a squash would be ${d.visibility === 'PUBLIC' ? 'published permanently' : 'published with it'} (#367)` };
|
|
44
|
+
}
|
|
45
|
+
if (!label) {
|
|
46
|
+
return { ...base, include: false, line: null, reason: `${d.reason}, but no machine label could be derived from the host name` };
|
|
47
|
+
}
|
|
48
|
+
return { ...base, include: true, line: `Machine: ${label}`, reason: `${d.reason} — the squash names the machine that landed it (#350)` };
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* #369: the destination rule on its own, for every writer that is not a squash trailer — claim,
|
|
53
|
+
* grant, decision and receipt comments on an issue, and `colab adopt`'s provenance comments in
|
|
54
|
+
* `.github/project.yml`. Same five rows as `decide` above, same order, same fail-closed default;
|
|
55
|
+
* what a caller does with `include: false` is its own (a comment writes an opaque `h:` token in the
|
|
56
|
+
* host field, a provenance comment drops the host). Pure.
|
|
57
|
+
*
|
|
58
|
+
* @returns {{ include: boolean, visibility: string|null, room: string|null, failClosed: boolean, reason: string }}
|
|
59
|
+
*/
|
|
60
|
+
function mayNameHost({ visibility, room }) {
|
|
61
|
+
const vis = visibility ? String(visibility).toUpperCase() : null;
|
|
62
|
+
const rm = room === undefined || room === null || room === '' ? null : String(room);
|
|
63
|
+
const base = { visibility: vis, room: rm, failClosed: false };
|
|
64
|
+
if (vis && VISIBLE.has(vis)) return { ...base, include: false, reason: 'repository is public' };
|
|
65
|
+
if (rm === 'public') return { ...base, include: false, reason: 'project.yml declares room: public' };
|
|
66
|
+
if (vis && HIDDEN.has(vis)) return { ...base, include: true, reason: `repository is ${vis.toLowerCase()}` };
|
|
67
|
+
if (rm && PRIVATE_ROOMS.has(rm)) return { ...base, include: true, reason: `visibility unreadable; project.yml declares room: ${rm}` };
|
|
68
|
+
return { ...base, include: false, failClosed: true,
|
|
69
|
+
reason: `visibility ${vis ? `"${vis}" not recognised` : 'could not be read'} and project.yml declares no private room:` };
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* #324 + #367: the `Colab-Adopted:` trailer. The branch and sha are the audit trail and always stay;
|
|
74
|
+
* the `on <host> (machine <id>)` tail is written only where the Machine: trailer itself may be.
|
|
75
|
+
*/
|
|
76
|
+
function adoptedTrailer(adopt, decision) {
|
|
77
|
+
if (!adopt) return null;
|
|
78
|
+
const head = `Colab-Adopted: ${adopt.remote || 'origin'}/${adopt.branch} @ ${adopt.remoteSha}`;
|
|
79
|
+
if (!decision || !decision.include) return head;
|
|
80
|
+
return `${head} on ${adopt.host} (machine ${adopt.machine || 'unknown'})`;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
module.exports = { decide, mayNameHost, adoptedTrailer };
|