@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,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 };
|