@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.
Files changed (95) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +312 -3
  3. package/README.vi.md +281 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13806 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +278 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify-endpoint.js +170 -0
  63. package/tools/lib/notify.js +188 -0
  64. package/tools/lib/npm-publish-guard.js +242 -0
  65. package/tools/lib/orphan-worktree.js +127 -0
  66. package/tools/lib/owner-branch.js +182 -0
  67. package/tools/lib/place.js +782 -0
  68. package/tools/lib/ports.js +167 -0
  69. package/tools/lib/procs.js +185 -0
  70. package/tools/lib/readiness.js +240 -0
  71. package/tools/lib/records.js +185 -0
  72. package/tools/lib/refs-brake.js +95 -0
  73. package/tools/lib/release-channel.js +99 -0
  74. package/tools/lib/release-cut.js +822 -0
  75. package/tools/lib/release-finalize.js +521 -0
  76. package/tools/lib/release-policy.js +358 -0
  77. package/tools/lib/release-tag.js +225 -0
  78. package/tools/lib/ship-batch.js +277 -0
  79. package/tools/lib/ship-roles.js +71 -0
  80. package/tools/lib/ship-target-sync.js +181 -0
  81. package/tools/lib/shipguard.js +317 -0
  82. package/tools/lib/shipped-branch.js +56 -0
  83. package/tools/lib/solo.js +213 -0
  84. package/tools/lib/squash.js +515 -0
  85. package/tools/lib/stale-base.js +70 -0
  86. package/tools/lib/stamp.js +740 -0
  87. package/tools/lib/state.js +262 -0
  88. package/tools/lib/teardown.js +83 -0
  89. package/tools/lib/trust-humans.js +104 -0
  90. package/tools/lib/util.js +98 -0
  91. package/tools/lib/wake.js +188 -0
  92. package/tools/lib/workflow-triggers.js +273 -0
  93. package/tools/lib/writes-authority.js +237 -0
  94. package/tools/lib/yaml.js +101 -0
  95. 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 };