@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,238 @@
1
+ 'use strict';
2
+ /**
3
+ * Machine identity — #289. `os.hostname()` alone false-refuses a place-claim the instant a Mac's
4
+ * short hostname drifts against its FQDN (`devbox.local` vs `devbox`) or DHCP/mDNS hands out
5
+ * a different label between processes — the SAME machine reads as foreign, and `lib/place.js`'s
6
+ * foreign-host branch (the sync-hazard backstop, CONVENTIONS.md "Place-claims") refuses on it.
7
+ *
8
+ * Two-tier comparison fixes this without weakening the backstop it exists inside:
9
+ * 1. `canonHost` — a cheap, pure string normalization (case, trailing dot, drop every label after
10
+ * the first) that alone resolves the `.local`-vs-FQDN case.
11
+ * 2. A hardware-bound id (`localMachine().id`), when both sides have one — exact and drift-proof,
12
+ * because it does not depend on hostname resolution at all.
13
+ *
14
+ * WHY A HARDWARE ID AND NOT A FILE UNDER `~/.colab`. A generated id persisted there inherits exactly
15
+ * the sync hazard the foreign-host branch exists to backstop (place.js's header, "MACHINE-LOCAL ONLY,
16
+ * DELIBERATELY"): if `~/.colab` itself is synced, two machines would read the SAME generated id and
17
+ * the backstop silently disappears. `ioreg`/`machine-id`/MAC addresses are bound to the hardware they
18
+ * describe and cannot travel over a file sync.
19
+ *
20
+ * BACKWARD COMPATIBLE BY CONSTRUCTION, NO MIGRATION. A record written before this landed has no
21
+ * `machine` field, so `sameMachineWith` falls through to the `canonHost` comparison (branch 3) —
22
+ * strictly MORE permissive than the raw `rec.host !== os.hostname()` check it replaces (a fixed
23
+ * hostname-string match is a special case of a canonicalized one). No record that compared equal
24
+ * before can start comparing unequal now.
25
+ *
26
+ * NEVER THROWS. Every resolution step degrades to the next on any failure (`ioreg` absent, machine-id
27
+ * file unreadable, no non-internal network interface) and the final fallback is `id: null`, at which
28
+ * point `sameMachineWith` falls back to the hostname comparison — never worse than what existed
29
+ * before this module.
30
+ */
31
+
32
+ const crypto = require('crypto');
33
+ const fs = require('fs');
34
+ const os = require('os');
35
+ const { run } = require('./git');
36
+
37
+ /**
38
+ * `String(h).trim()`, drop a trailing `.` (bare or FQDN-style), lowercase, then keep only the FIRST
39
+ * label — `split('.')[0]`. `Devbox.local.`, `devbox.local`, `devbox.hsd1.ca.comcast.net`
40
+ * and `devbox` all canonicalize to `devbox`. Falsy input (`''`, `null`, `undefined`) → `''`.
41
+ */
42
+ function canonHost(h) {
43
+ if (!h) return '';
44
+ const s = String(h).trim().replace(/\.+$/, '').toLowerCase();
45
+ return s.split('.')[0] || '';
46
+ }
47
+
48
+ /** The scheme prefix of a `<scheme>:<value>` machine id, e.g. `iokit` from `iokit:1234-...`. */
49
+ function idScheme(id) {
50
+ const i = String(id || '').indexOf(':');
51
+ return i === -1 ? '' : String(id).slice(0, i);
52
+ }
53
+
54
+ /**
55
+ * darwin: `ioreg -rd1 -c IOPlatformExpertDevice` → the `IOPlatformUUID` line → `iokit:<uuid>`.
56
+ * `run` is injected (same helper `tools/lib/procs.js` spawns `lsof`/`ps` through) so this is testable
57
+ * without actually running on darwin. Any failure — command missing, non-zero exit, no matching
58
+ * line — degrades to `null`, never throws.
59
+ */
60
+ function darwinPlatformId(runFn) {
61
+ try {
62
+ const r = runFn('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice']);
63
+ if (!r || !r.stdout) return null;
64
+ const m = r.stdout.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/);
65
+ return m ? `iokit:${m[1]}` : null;
66
+ } catch (_) {
67
+ return null;
68
+ }
69
+ }
70
+
71
+ /**
72
+ * linux: `/etc/machine-id`, falling back to `/var/lib/dbus/machine-id` → `dbus:<id>`. `readFileFn`
73
+ * is injected for the same testability reason as `darwinPlatformId`.
74
+ */
75
+ function linuxMachineId(readFileFn) {
76
+ for (const p of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {
77
+ try {
78
+ const id = String(readFileFn(p, 'utf8') || '').trim();
79
+ if (id) return `dbus:${id}`;
80
+ } catch (_) {
81
+ // try the next path
82
+ }
83
+ }
84
+ return null;
85
+ }
86
+
87
+ /**
88
+ * Last-resort fallback when neither platform-specific id resolved (an unsupported OS, or the
89
+ * platform call itself failed): a sha1 of every non-internal MAC address `os.networkInterfaces()`
90
+ * reports, sorted so interface enumeration order cannot change the id between runs, truncated to 12
91
+ * hex chars — enough to disambiguate machines, short enough to stay readable in a log line.
92
+ */
93
+ function macFallbackId(networkInterfacesFn) {
94
+ try {
95
+ const ifaces = networkInterfacesFn() || {};
96
+ const macs = [];
97
+ for (const name of Object.keys(ifaces)) {
98
+ for (const iface of ifaces[name] || []) {
99
+ if (iface && iface.mac && iface.mac !== '00:00:00:00:00:00' && !iface.internal) {
100
+ macs.push(iface.mac.toLowerCase());
101
+ }
102
+ }
103
+ }
104
+ if (!macs.length) return null;
105
+ macs.sort();
106
+ const hash = crypto.createHash('sha1').update(macs.join(',')).digest('hex').slice(0, 12);
107
+ return `mac:${hash}`;
108
+ } catch (_) {
109
+ return null;
110
+ }
111
+ }
112
+
113
+ /**
114
+ * The full resolution order as ONE injectable function, so `localMachine()`'s degrade path is
115
+ * testable without mocking `require('./git')`/`require('fs')`/`require('os')` at the module level.
116
+ * Not part of the module's stated public API (which is the four names in `module.exports` the header
117
+ * comment describes) but exported anyway — a private helper with no test seam just moves the
118
+ * untestable surface from here to `localMachine`, it does not remove it.
119
+ */
120
+ function resolveMachineId({
121
+ platform = process.platform,
122
+ runFn = run,
123
+ readFileFn = fs.readFileSync,
124
+ networkInterfacesFn = os.networkInterfaces,
125
+ } = {}) {
126
+ let id = null;
127
+ if (platform === 'darwin') id = darwinPlatformId(runFn);
128
+ else if (platform === 'linux') id = linuxMachineId(readFileFn);
129
+ if (!id) id = macFallbackId(networkInterfacesFn);
130
+ return id;
131
+ }
132
+
133
+ let _cached = null;
134
+
135
+ /**
136
+ * `{ id, host }` for THIS machine, memoized per process — one `ioreg`/file-read spawn no matter how
137
+ * many records `colab doctor` checks in one run. `id` is `null` when every scheme failed (unsupported
138
+ * platform, sandboxed environment, no usable network interface); callers must tolerate that, exactly
139
+ * as `sameMachineWith` does (falls back to the hostname comparison). Never throws.
140
+ */
141
+ function localMachine() {
142
+ if (_cached) return _cached;
143
+ let id = null;
144
+ try {
145
+ id = resolveMachineId();
146
+ } catch (_) {
147
+ id = null;
148
+ }
149
+ let host = '';
150
+ try {
151
+ host = os.hostname() || '';
152
+ } catch (_) {
153
+ host = '';
154
+ }
155
+ _cached = { id: id || null, host };
156
+ return _cached;
157
+ }
158
+
159
+ /**
160
+ * Is `rec` (a place-claim/worktree/claim record carrying `host` and, on records written after
161
+ * #289, `machine`) the SAME machine as `local` (the `{id, host}` shape `localMachine()` returns)?
162
+ * Pure — never touches `os`/`fs`/child processes itself, so this is the part actually under test.
163
+ *
164
+ * 1. Neither side names a machine at all (`!rec.host && !rec.machine`) → `true`. Preserves today's
165
+ * "falsy host skips the check" behaviour (place.js's pre-#289 `rec.host && rec.host !== ...`).
166
+ * 2. Both sides carry a hardware id of the SAME scheme → exact match. Authoritative in both
167
+ * directions for any record written after this landed; immune to hostname drift entirely.
168
+ * 3. Otherwise → canonicalized hostname comparison. This is the branch every legacy record (no
169
+ * `machine` field) takes, and it is strictly more permissive than a raw string `===`.
170
+ */
171
+ function sameMachineWith(rec, local) {
172
+ const r = rec || {};
173
+ const l = local || {};
174
+ if (!r.host && !r.machine) return true;
175
+ if (r.machine && l.id && idScheme(r.machine) === idScheme(l.id)) {
176
+ return r.machine === l.id;
177
+ }
178
+ return sameHostName(r.host, l.host);
179
+ }
180
+
181
+ /** `sameMachineWith(rec, localMachine())` — the impure convenience wrapper every caller reaches for. */
182
+ function isLocal(rec) {
183
+ return sameMachineWith(rec, localMachine());
184
+ }
185
+
186
+ /**
187
+ * The PUBLIC form of a machine id (#327): `m:` + the first 12 hex chars of sha256(id). A claim
188
+ * comment is posted to the tracker — on a public repo, to the internet — and the raw id is a
189
+ * hardware serial (`IOPlatformUUID`, `/etc/machine-id`) that has no business being published. The
190
+ * digest keeps what a comparison needs (equal ids → equal tokens, drift-proof like the id itself)
191
+ * and nothing else. Idempotent: an already-digested token passes through unchanged, so a caller can
192
+ * compare a comment's token against a local record's raw id without knowing which it holds.
193
+ * Falsy/blank input → `''` (no machine known — callers fall back to `canonHost`).
194
+ */
195
+ function machineToken(id) {
196
+ const s = String(id || '').trim();
197
+ if (!s) return '';
198
+ if (/^m:[0-9a-f]{12}$/.test(s)) return s;
199
+ return `m:${crypto.createHash('sha256').update(s).digest('hex').slice(0, 12)}`;
200
+ }
201
+
202
+ const HOST_TOKEN_RE = /^h:[0-9a-f]{12}$/;
203
+
204
+ /**
205
+ * The PUBLIC form of a HOSTNAME (#369) — `h:` + the first 12 hex chars of sha256(canonHost(h)).
206
+ * What a claim/grant/decision comment carries in its `host` field when it lands on a public
207
+ * destination (machine-trailer.js `mayNameHost`): the raw name is an internal hostname, and an
208
+ * issue comment on a public repository publishes it. Hashed AFTER `canonHost`, so every spelling
209
+ * one machine gives itself (`box.local`, `Box.`, `box.lan`) still digests to one token — the same
210
+ * drift-proofing `canonHost` gives the raw comparison. Idempotent on an existing token; blank → ''.
211
+ *
212
+ * Opaque, not secret: a hostname is low-entropy, so a guess can be confirmed against the token.
213
+ * It keeps the name out of the page and out of search, which is what a public comment needs; it
214
+ * is not a defence against someone who already suspects the name.
215
+ */
216
+ function hostToken(h) {
217
+ const s = String(h || '').trim();
218
+ if (!s) return '';
219
+ if (HOST_TOKEN_RE.test(s)) return s;
220
+ const c = canonHost(s);
221
+ if (!c) return '';
222
+ return `h:${crypto.createHash('sha256').update(c).digest('hex').slice(0, 12)}`;
223
+ }
224
+
225
+ /**
226
+ * Do two HOST fields name the same machine (#369)? Either side an `h:` token → compare tokens (a
227
+ * raw name digests to the token a public comment carries, so a redacted comment and a local raw
228
+ * record still match); otherwise the #327 `canonHost` comparison, unchanged. Blank on both sides
229
+ * compares equal, as `'' === ''` always did.
230
+ */
231
+ function sameHostName(a, b) {
232
+ const as = String(a || '').trim();
233
+ const bs = String(b || '').trim();
234
+ if (HOST_TOKEN_RE.test(as) || HOST_TOKEN_RE.test(bs)) return hostToken(as) === hostToken(bs);
235
+ return canonHost(as) === canonHost(bs);
236
+ }
237
+
238
+ module.exports = { canonHost, localMachine, sameMachineWith, isLocal, resolveMachineId, machineToken, hostToken, sameHostName };