@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.10
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 +310 -3
- package/README.vi.md +280 -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 +13790 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +259 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-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,167 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* Port helpers: reserved-set aggregation, liveness check, allocation.
|
|
4
|
+
*
|
|
5
|
+
* DESIGN: reserved ports (a project's trunk dev server) are NOT kept in one hand-maintained central
|
|
6
|
+
* file any more. Each repo declares its own in `.github/project.yml` as `ports: [5220]`. `colab`
|
|
7
|
+
* aggregates the reserved set across every repo it knows about (config.repos) plus the current repo,
|
|
8
|
+
* plus config.extraReserved for non-repo services. A reserved port is NEVER handed to a worktree,
|
|
9
|
+
* even when that trunk server is currently down.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
const fs = require('fs');
|
|
13
|
+
const os = require('os');
|
|
14
|
+
const path = require('path');
|
|
15
|
+
const { spawnSync } = require('child_process');
|
|
16
|
+
const yaml = require('./yaml');
|
|
17
|
+
|
|
18
|
+
/** Expand a leading ~ (or ~/) to the home directory. Leaves other paths untouched. */
|
|
19
|
+
function expandHome(p) {
|
|
20
|
+
if (p === '~') return os.homedir();
|
|
21
|
+
if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
|
|
22
|
+
return p;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** Read `ports:` from a repo's .github/project.yml. Returns [] if absent/unparseable. */
|
|
26
|
+
function repoReservedPorts(repoRoot) {
|
|
27
|
+
const file = path.join(repoRoot, '.github', 'project.yml');
|
|
28
|
+
let text;
|
|
29
|
+
try { text = fs.readFileSync(file, 'utf8'); }
|
|
30
|
+
catch (_) { return []; }
|
|
31
|
+
let doc;
|
|
32
|
+
try { doc = yaml.parse(text); }
|
|
33
|
+
catch (_) { return []; }
|
|
34
|
+
const p = doc && doc.ports;
|
|
35
|
+
if (Array.isArray(p)) return p.map(Number).filter((n) => Number.isInteger(n));
|
|
36
|
+
if (Number.isInteger(p)) return [p];
|
|
37
|
+
return [];
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Read `worktreePorts: [lo, hi]` from a repo's .github/project.yml — the window worktrees of THIS
|
|
42
|
+
* repo allocate from. Returns [lo, hi] or null (absent / malformed / hi < lo). Distinct from
|
|
43
|
+
* `ports:` (reserved trunk ports).
|
|
44
|
+
*/
|
|
45
|
+
function repoWorktreePorts(repoRoot) {
|
|
46
|
+
const file = path.join(repoRoot, '.github', 'project.yml');
|
|
47
|
+
let text;
|
|
48
|
+
try { text = fs.readFileSync(file, 'utf8'); }
|
|
49
|
+
catch (_) { return null; }
|
|
50
|
+
let doc;
|
|
51
|
+
try { doc = yaml.parse(text); }
|
|
52
|
+
catch (_) { return null; }
|
|
53
|
+
const w = doc && doc.worktreePorts;
|
|
54
|
+
if (Array.isArray(w) && w.length === 2) {
|
|
55
|
+
const lo = Number(w[0]), hi = Number(w[1]);
|
|
56
|
+
if (Number.isInteger(lo) && Number.isInteger(hi) && hi >= lo) return [lo, hi];
|
|
57
|
+
}
|
|
58
|
+
return null;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Parse a lenient reserved-ports file: whitespace-separated port numbers per line, `#` starts a
|
|
63
|
+
* comment, any non-numeric token is ignored. A missing/unreadable file yields []. This is the
|
|
64
|
+
* pre-handbook `~/code/.claude/ports.reserved` shape — machine-local, referenced via
|
|
65
|
+
* config.reservedFiles, so the handbook itself stays generic.
|
|
66
|
+
*/
|
|
67
|
+
function parseReservedFile(filePath) {
|
|
68
|
+
let text;
|
|
69
|
+
try { text = fs.readFileSync(expandHome(filePath), 'utf8'); }
|
|
70
|
+
catch (_) { return []; }
|
|
71
|
+
const out = [];
|
|
72
|
+
for (const line of text.split(/\r?\n/)) {
|
|
73
|
+
for (const tok of line.replace(/#.*$/, '').split(/\s+/)) {
|
|
74
|
+
if (/^\d+$/.test(tok)) out.push(parseInt(tok, 10));
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
return out;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Aggregate the reserved set across all known repos + extras.
|
|
82
|
+
* Returns a Map port -> source label (for good error messages).
|
|
83
|
+
*/
|
|
84
|
+
function reservedSet(config, extraRepos = []) {
|
|
85
|
+
const map = new Map();
|
|
86
|
+
const roots = new Set([...(config.repos || []), ...extraRepos].filter(Boolean));
|
|
87
|
+
for (const root of roots) {
|
|
88
|
+
for (const port of repoReservedPorts(root)) {
|
|
89
|
+
if (!map.has(port)) map.set(port, path.basename(root));
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
for (const port of config.extraReserved || []) {
|
|
93
|
+
if (!map.has(Number(port))) map.set(Number(port), 'config.extraReserved');
|
|
94
|
+
}
|
|
95
|
+
// Machine-local reserved-port files (e.g. a pre-handbook ~/code/.claude/ports.reserved) —
|
|
96
|
+
// ports of repos NOT registered with colab, aggregated so they can't be handed to a worktree.
|
|
97
|
+
for (const f of config.reservedFiles || []) {
|
|
98
|
+
for (const port of parseReservedFile(f)) {
|
|
99
|
+
if (!map.has(port)) map.set(port, `file:${path.basename(expandHome(f))}`);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
return map;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Exact-pin availability check for `--at`. Returns the list of conflicts [{port, reason}] — a port
|
|
107
|
+
* is refused when it is reserved or already allocated in state (same refusal semantics as reserved
|
|
108
|
+
* ports). Listening is NOT a hard block here: the caller asked for these exact ports on purpose.
|
|
109
|
+
*/
|
|
110
|
+
function checkExact(portList, state, reserved) {
|
|
111
|
+
const allocated = allocatedSet(state);
|
|
112
|
+
const conflicts = [];
|
|
113
|
+
for (const p of portList) {
|
|
114
|
+
if (reserved.has(p)) conflicts.push({ port: p, reason: `reserved (${reserved.get(p)})` });
|
|
115
|
+
else if (allocated.has(p)) conflicts.push({ port: p, reason: 'already allocated in state' });
|
|
116
|
+
}
|
|
117
|
+
return conflicts;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** True if a TCP port is currently being LISTENed on (uses lsof; falls back to "not listening"). */
|
|
121
|
+
function isListening(port) {
|
|
122
|
+
const r = spawnSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN'], { encoding: 'utf8' });
|
|
123
|
+
if (r.error) return false; // lsof missing → can't tell, assume free (state/reserved still guard)
|
|
124
|
+
return r.status === 0 && !!(r.stdout || '').trim();
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** Ports currently recorded as allocated in state. */
|
|
128
|
+
function allocatedSet(state) {
|
|
129
|
+
return new Set(Object.keys(state.ports || {}).map(Number));
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* A port is available iff: not reserved, not already allocated in state, not currently LISTENing.
|
|
134
|
+
* `reserved` is a Set/Map of reserved ports.
|
|
135
|
+
*/
|
|
136
|
+
function isAvailable(port, state, reserved) {
|
|
137
|
+
if (reserved.has ? reserved.has(port) : false) return false;
|
|
138
|
+
if (allocatedSet(state).has(port)) return false;
|
|
139
|
+
if (isListening(port)) return false;
|
|
140
|
+
return true;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
function parseRange(rangeStr) {
|
|
144
|
+
const m = String(rangeStr).match(/^(\d+)\s*-\s*(\d+)$/);
|
|
145
|
+
if (!m) throw new Error(`Bad --range "${rangeStr}" (expected A-B, e.g. 5200-5999)`);
|
|
146
|
+
const lo = parseInt(m[1], 10), hi = parseInt(m[2], 10);
|
|
147
|
+
if (hi < lo) throw new Error(`Bad --range "${rangeStr}" (A must be <= B)`);
|
|
148
|
+
return [lo, hi];
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/** Find `count` consecutive available ports within [lo,hi]. Returns array or null. */
|
|
152
|
+
function findConsecutive(count, rangeStr, state, reserved) {
|
|
153
|
+
const [lo, hi] = parseRange(rangeStr);
|
|
154
|
+
for (let p = lo; p <= hi - count + 1; p++) {
|
|
155
|
+
let ok = true;
|
|
156
|
+
for (let i = 0; i < count; i++) {
|
|
157
|
+
if (!isAvailable(p + i, state, reserved)) { ok = false; break; }
|
|
158
|
+
}
|
|
159
|
+
if (ok) return Array.from({ length: count }, (_, i) => p + i);
|
|
160
|
+
}
|
|
161
|
+
return null;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
module.exports = {
|
|
165
|
+
repoReservedPorts, repoWorktreePorts, parseReservedFile, expandHome,
|
|
166
|
+
reservedSet, isListening, isAvailable, parseRange, findConsecutive, allocatedSet, checkExact,
|
|
167
|
+
};
|
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* Finding the processes a directory owns, and the ports they hold.
|
|
4
|
+
*
|
|
5
|
+
* Worktree teardown used to treat port release as pure bookkeeping: it deleted the registry entry
|
|
6
|
+
* and never asked whether anything was still bound. A dev server started from inside a worktree
|
|
7
|
+
* therefore survived `worktree rm`, kept listening, and kept serving out of a checkout that no
|
|
8
|
+
* longer existed — so what it returned was a stale or broken app on a URL that still looked
|
|
9
|
+
* legitimate. Every obvious diagnostic passes in that state: the build is fine, the registry says
|
|
10
|
+
* the port is free, and `git worktree list` shows nothing.
|
|
11
|
+
*
|
|
12
|
+
* OWNERSHIP IS DECIDED BY cwd, NEVER BY PORT. "Kill whatever is listening on the port I am about
|
|
13
|
+
* to free" is unsafe in precisely the case that matters: if the registry is stale, that kills an
|
|
14
|
+
* unrelated process legitimately holding the port. A process whose cwd is inside the directory
|
|
15
|
+
* being removed is positive proof the directory owns it. Ports cannot prove ownership; cwd can.
|
|
16
|
+
*
|
|
17
|
+
* No dependencies. Everything degrades to "found nothing" when lsof is missing or unusable, so a
|
|
18
|
+
* machine without it loses the check but never breaks teardown.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
const path = require('path');
|
|
22
|
+
const { run } = require('./git');
|
|
23
|
+
|
|
24
|
+
/** True when `child` is `dir` itself or lives underneath it. */
|
|
25
|
+
function isInside(dir, child) {
|
|
26
|
+
if (!dir || !child) return false;
|
|
27
|
+
const d = path.resolve(dir);
|
|
28
|
+
const c = path.resolve(child);
|
|
29
|
+
return c === d || c.startsWith(d + path.sep);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Parse `lsof -a -d cwd -F pn` output into [{pid, cwd}] for processes whose cwd is inside `dir`.
|
|
34
|
+
*
|
|
35
|
+
* lsof's field format is a stream of prefixed lines, NOT one record per line: a `p<pid>` line
|
|
36
|
+
* applies to every following field line until the next `p`. Split on lines and you get pids with
|
|
37
|
+
* no paths. Exported separately from the lsof call so the parsing is testable without spawning
|
|
38
|
+
* anything or depending on what happens to be running on the machine.
|
|
39
|
+
*/
|
|
40
|
+
function parseLsofCwd(stdout, dir) {
|
|
41
|
+
const out = [];
|
|
42
|
+
let pid = null;
|
|
43
|
+
for (const line of String(stdout || '').split('\n')) {
|
|
44
|
+
if (!line) continue;
|
|
45
|
+
const tag = line[0];
|
|
46
|
+
const val = line.slice(1).trim();
|
|
47
|
+
if (tag === 'p') pid = val;
|
|
48
|
+
else if (tag === 'n' && pid && isInside(dir, val)) out.push({ pid, cwd: val });
|
|
49
|
+
}
|
|
50
|
+
return out;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** TCP ports a pid is LISTENING on (numbers, deduped). */
|
|
54
|
+
function listeningPorts(pid) {
|
|
55
|
+
const r = run('lsof', ['-p', String(pid), '-a', '-iTCP', '-sTCP:LISTEN', '-P', '-F', 'n']);
|
|
56
|
+
if (!r.ok) return [];
|
|
57
|
+
const set = new Set();
|
|
58
|
+
for (const line of r.stdout.split('\n')) {
|
|
59
|
+
if (line[0] !== 'n') continue;
|
|
60
|
+
const m = line.slice(1).trim().match(/:(\d+)$/);
|
|
61
|
+
if (m) set.add(Number(m[1]));
|
|
62
|
+
}
|
|
63
|
+
return [...set].sort((a, b) => a - b);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** A pid's cwd, or '' when lsof cannot say. A cwd that no longer exists is the orphan's signature. */
|
|
67
|
+
function cwdOf(pid) {
|
|
68
|
+
const r = run('lsof', ['-p', String(pid), '-a', '-d', 'cwd', '-F', 'n']);
|
|
69
|
+
if (!r.stdout) return '';
|
|
70
|
+
for (const line of r.stdout.split('\n')) if (line[0] === 'n') return line.slice(1).trim();
|
|
71
|
+
return '';
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** Best-effort command line for a pid, trimmed for display. */
|
|
75
|
+
function commandOf(pid) {
|
|
76
|
+
const r = run('ps', ['-p', String(pid), '-o', 'command=']);
|
|
77
|
+
if (!r.ok || !r.stdout) return '(unknown)';
|
|
78
|
+
const cmd = r.stdout.split('\n')[0].trim();
|
|
79
|
+
return cmd.length > 70 ? cmd.slice(0, 69) + '…' : cmd;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Processes whose cwd is inside `dir`, enriched with command and listening ports.
|
|
84
|
+
* Returns [] on any platform or environment where lsof cannot answer — never throws.
|
|
85
|
+
*/
|
|
86
|
+
function processesInDir(dir) {
|
|
87
|
+
if (!dir || process.platform === 'win32') return [];
|
|
88
|
+
const r = run('lsof', ['-a', '-d', 'cwd', '-F', 'pn']);
|
|
89
|
+
// lsof exits non-zero when *some* descriptors are unreadable, which is normal for an
|
|
90
|
+
// unprivileged sweep — so trust the output whenever there is any, not the exit code.
|
|
91
|
+
if (!r.stdout) return [];
|
|
92
|
+
const self = String(process.pid);
|
|
93
|
+
return parseLsofCwd(r.stdout, dir)
|
|
94
|
+
.filter((p) => p.pid !== self)
|
|
95
|
+
.map((p) => ({ ...p, ports: listeningPorts(p.pid), command: commandOf(p.pid) }));
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Every TCP listener on the machine as [{pid, port}], from ONE lsof call.
|
|
100
|
+
*
|
|
101
|
+
* Deliberately not per-port: the allocation window is ~800 ports wide, and probing each one
|
|
102
|
+
* separately turns a diagnostic into a minute of spawning. Same field-format parsing rule as
|
|
103
|
+
* `parseLsofCwd` — `p<pid>` applies until the next `p`.
|
|
104
|
+
*/
|
|
105
|
+
function listeners() {
|
|
106
|
+
const r = run('lsof', ['-iTCP', '-sTCP:LISTEN', '-P', '-F', 'pn']);
|
|
107
|
+
if (!r.stdout) return [];
|
|
108
|
+
const out = [];
|
|
109
|
+
let pid = null;
|
|
110
|
+
for (const line of r.stdout.split('\n')) {
|
|
111
|
+
if (!line) continue;
|
|
112
|
+
if (line[0] === 'p') pid = line.slice(1).trim();
|
|
113
|
+
else if (line[0] === 'n' && pid) {
|
|
114
|
+
const m = line.slice(1).trim().match(/:(\d+)$/);
|
|
115
|
+
if (m) out.push({ pid, port: Number(m[1]) });
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
return out;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** Is anything LISTENING on this TCP port right now? Used to verify a port really got freed. */
|
|
122
|
+
function portIsBound(port) {
|
|
123
|
+
const r = run('lsof', ['-iTCP:' + port, '-sTCP:LISTEN', '-P', '-F', 'p']);
|
|
124
|
+
return !!(r.stdout && /^p\d+/m.test(r.stdout));
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Is this pid alive right now? `kill(pid, 0)` sends no signal — it only asks the kernel whether
|
|
129
|
+
* the pid exists and is ours to signal. Extracted (#136) so callers other than `terminate` — the
|
|
130
|
+
* place-claim's read-time liveness check among them — share one implementation instead of each
|
|
131
|
+
* writing their own `try { kill(pid, 0) } catch` copy, which is exactly the duplication #86 was
|
|
132
|
+
* filed about for a different pair of functions in this same file.
|
|
133
|
+
*/
|
|
134
|
+
function alive(pid) {
|
|
135
|
+
try { process.kill(Number(pid), 0); return true; } catch (_) { return false; }
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Terminate a pid politely, then forcibly. Returns true if it is gone afterwards.
|
|
140
|
+
* SIGTERM first so a dev server can close its listeners; SIGKILL only for what ignores it.
|
|
141
|
+
*/
|
|
142
|
+
function terminate(pid, waitMs = 2000) {
|
|
143
|
+
try { process.kill(Number(pid), 'SIGTERM'); } catch (_) { return true; } // already gone
|
|
144
|
+
const deadline = Date.now() + waitMs;
|
|
145
|
+
while (Date.now() < deadline) {
|
|
146
|
+
if (!alive(pid)) return true;
|
|
147
|
+
// Busy-wait in 50ms slices: this runs at most a couple of seconds during teardown, and a
|
|
148
|
+
// sync sleep keeps the whole command synchronous like the rest of the CLI.
|
|
149
|
+
run('sleep', ['0.05']);
|
|
150
|
+
}
|
|
151
|
+
try { process.kill(Number(pid), 'SIGKILL'); } catch (_) { /* raced to exit */ }
|
|
152
|
+
return !alive(pid);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Does `of` (default: this process) descend from `candidate` — i.e. is `candidate` an ancestor,
|
|
157
|
+
* reached by walking `ppid` links? #288: this is what turns "an env var NAMES a pid" into "this pid
|
|
158
|
+
* PROVABLY contains this invocation" — `place.js`'s `resolveAnchor` only trusts `CLAUDE_PID` after
|
|
159
|
+
* this passes, precisely because a stale/reused/forged env value is otherwise indistinguishable from
|
|
160
|
+
* a real one.
|
|
161
|
+
*
|
|
162
|
+
* `hops` bounds the walk (default 10 — deep enough for any real shell/agent process tree, shallow
|
|
163
|
+
* enough that a `ppid` cycle from bad `ps` output cannot spin). Same never-throw discipline as the
|
|
164
|
+
* rest of this file: `ps` missing, a pid that has already exited mid-walk, malformed output — all
|
|
165
|
+
* degrade to `false` (not an ancestor), never an exception. `false` on "cannot tell" is deliberately
|
|
166
|
+
* fail-closed here — the caller (`resolveAnchor`) falls through to the fail-closed `'invocation'`
|
|
167
|
+
* anchor kind on a `false`, so an unprovable ancestry claim never gets treated as proven.
|
|
168
|
+
*/
|
|
169
|
+
function isAncestor(candidate, of = process.pid, hops = 10) {
|
|
170
|
+
const target = String(candidate);
|
|
171
|
+
if (!target || Number.isNaN(Number(target))) return false;
|
|
172
|
+
let pid = Number(of);
|
|
173
|
+
for (let i = 0; i < hops; i++) {
|
|
174
|
+
if (!pid || Number.isNaN(pid) || pid <= 1) return false;
|
|
175
|
+
const r = run('ps', ['-o', 'ppid=', '-p', String(pid)]);
|
|
176
|
+
if (!r.ok || !r.stdout) return false;
|
|
177
|
+
const ppid = parseInt(r.stdout.trim(), 10);
|
|
178
|
+
if (!ppid || Number.isNaN(ppid)) return false;
|
|
179
|
+
if (String(ppid) === target) return true;
|
|
180
|
+
pid = ppid;
|
|
181
|
+
}
|
|
182
|
+
return false;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
module.exports = { isInside, parseLsofCwd, listeningPorts, commandOf, cwdOf, processesInDir, listeners, portIsBound, alive, terminate, isAncestor };
|
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* "Can this issue start right now?" — the one shared answer, so every consumer of the dependency
|
|
4
|
+
* graph stops re-deriving it, and stops deriving it as a boolean.
|
|
5
|
+
*
|
|
6
|
+
* THE TRAP. "Open ∧ unclaimed ∧ no open blocker" evaluates the third term as a yes/no, and that
|
|
7
|
+
* yes/no covers two situations that are not alike:
|
|
8
|
+
*
|
|
9
|
+
* - a blocker nobody has started — no code exists anywhere;
|
|
10
|
+
* - a blocker whose code is written, pushed, and stopped at the human merge gate.
|
|
11
|
+
*
|
|
12
|
+
* For the second, "blocked" is false in practice: the thing being waited for already exists, and
|
|
13
|
+
* only a merge stands between it and the trunk. A dependent told "blocked" there is parked for no
|
|
14
|
+
* reason. So readiness has THREE values, not two:
|
|
15
|
+
*
|
|
16
|
+
* blocked · ready-with-a-note (the dependency exists, unmerged) · ready
|
|
17
|
+
*
|
|
18
|
+
* WHERE THE MIDDLE STATE LIVES, which is the part with no obvious answer. Not in the graph. The
|
|
19
|
+
* relationship stays recorded exactly as it is true — `blocked_by` says *this waits for that*, and
|
|
20
|
+
* that fact does not stop being true because the blocker grew a branch. The middle state is
|
|
21
|
+
* COMPUTED here, at read time, from the relationship PLUS the blocker's state.
|
|
22
|
+
*
|
|
23
|
+
* Two alternatives were considered and rejected, and the rejections are the load-bearing half:
|
|
24
|
+
* - A NEW MARKER for the soft case (a label). It is derived state, so it is stale the moment the
|
|
25
|
+
* blocker moves — the identical hazard the `deps-checked` marker already carries, now with a
|
|
26
|
+
* second label to keep fresh and two markers free to disagree.
|
|
27
|
+
* - DELETING the `blocked_by` edge once the blocker's code is written. This destroys a true fact
|
|
28
|
+
* for a display's convenience, and does not survive the blocker being reverted: the dependency
|
|
29
|
+
* returns, the edge does not, and nothing is left that knows the two are related.
|
|
30
|
+
* A relationship is a fact; readiness is a judgement. Recording a judgement where the facts live is
|
|
31
|
+
* how the two start contradicting each other, and the graph is what everything else trusts.
|
|
32
|
+
*
|
|
33
|
+
* AN ACTIVE SESSION IS NOT EVIDENCE, and this module will not be talked into treating it as any.
|
|
34
|
+
* `session` is accepted on a blocker and deliberately ignored — accepted so a caller passing it
|
|
35
|
+
* learns from the verdict that it did not count, rather than believing it did. Measured: a session
|
|
36
|
+
* open ten minutes was already dead, having never claimed the issue it was opened for. A dependent
|
|
37
|
+
* started on that evidence waits for something that never arrives. An open session is intent. A
|
|
38
|
+
* pushed branch with real commits is evidence. Only the second moves a verdict.
|
|
39
|
+
*
|
|
40
|
+
* UNPUSHED IS NOT EVIDENCE EITHER, for the same reason claims are authoritative only when they are
|
|
41
|
+
* visible from any machine: a branch that exists on one laptop cannot be seen, reviewed or merged
|
|
42
|
+
* by the session that would depend on it.
|
|
43
|
+
*
|
|
44
|
+
* WHICH DIRECTION THIS FAILS IN — the opposite one from landed.js, which is why they are two
|
|
45
|
+
* functions and not one. There, an unmeasurable branch must never read `landed`, because telling
|
|
46
|
+
* someone their unmerged work is spent destroys it. Here, an unmeasurable blocker must never read
|
|
47
|
+
* `ready`, because starting into a wall wastes a session. Both refuse to be optimistic; optimism
|
|
48
|
+
* just points elsewhere. Absent or malformed facts therefore yield `blocked`, never `ready`.
|
|
49
|
+
*
|
|
50
|
+
* WHY THIS REUSES landed.classify() RATHER THAN ASKING ITS OWN QUESTION. "Is the blocker's code
|
|
51
|
+
* written but unmerged?" is "does the blocker's branch still carry cargo?", asked from the other
|
|
52
|
+
* side. A second evidence classifier would be a second commit-counting rule to get wrong — the
|
|
53
|
+
* exact failure landed.js documents, which took two skills two tries. This module supplies the
|
|
54
|
+
* mapping and none of the git reasoning.
|
|
55
|
+
*
|
|
56
|
+
* PURE BY CONSTRUCTION: signals in, verdict out. No git, no network, no `gh`. The caller gathers
|
|
57
|
+
* (the graph edge, the blocker's open/closed state, its branch facts) and this decides. That is
|
|
58
|
+
* what lets a consumer outside this repo — a dashboard, a vendored copy — reach the same verdict
|
|
59
|
+
* from facts it collected its own way.
|
|
60
|
+
*
|
|
61
|
+
* MECHANICAL READINESS (#69) is a SEPARATE, WEAKER claim layered on top of `depsChecked`, not a
|
|
62
|
+
* second way to reach the same `ready` verdict. `depsChecked` means a reasoning session looked —
|
|
63
|
+
* including at prose a blocker might only be described in, never encoded as an edge. `graphEmpty`
|
|
64
|
+
* means an authoritative API read found the encoded graph empty; it says nothing about prose, so
|
|
65
|
+
* it must never be allowed to produce `ready` on its own. An empty blocker list with `graphEmpty`
|
|
66
|
+
* true and `depsChecked` false reads `unchecked-mechanical` — still not `isStartable()` by
|
|
67
|
+
* default. A consumer that has decided the faster, weaker lane is worth the risk opts in
|
|
68
|
+
* explicitly via `isStartableMechanical()`; every existing conservative consumer is unaffected by
|
|
69
|
+
* this fact merely being available.
|
|
70
|
+
*/
|
|
71
|
+
|
|
72
|
+
const landed = require('./landed.js');
|
|
73
|
+
|
|
74
|
+
/** The five verdicts. `UNCHECKED` and `UNCHECKED_MECHANICAL` are not kinds of ready — the first
|
|
75
|
+
* is "nobody looked"; the second is "an API said the graph is empty, nobody has judged it yet". */
|
|
76
|
+
const READY = 'ready';
|
|
77
|
+
const SOFT = 'ready-with-a-note'; // a real blocker, whose code is already written and pushed
|
|
78
|
+
const BLOCKED = 'blocked';
|
|
79
|
+
const UNCHECKED = 'unchecked';
|
|
80
|
+
const UNCHECKED_MECHANICAL = 'unchecked-mechanical'; // graph reads empty; no reasoning session yet (#69)
|
|
81
|
+
|
|
82
|
+
/** Per-blocker verdicts, in increasing order of how much they stop you. */
|
|
83
|
+
const CLEAR = 'clear'; // this one does not block: closed, or its work is already on the base
|
|
84
|
+
const SOFT_BLOCK = 'soft'; // the dependency exists as pushed, unmerged code
|
|
85
|
+
const HARD_BLOCK = 'hard'; // no code exists, or we cannot tell
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* One blocker, judged on its state rather than on the existence of the edge.
|
|
89
|
+
*
|
|
90
|
+
* Input: {
|
|
91
|
+
* number, // for the note; not used in the judgement
|
|
92
|
+
* open, // boolean — false/absent means closed
|
|
93
|
+
* branch, // null, or { pushed, commitsAhead, diffEmpty, containment }
|
|
94
|
+
* session, // ACCEPTED AND IGNORED, on purpose — see the header
|
|
95
|
+
* }
|
|
96
|
+
*
|
|
97
|
+
* Returns { state: 'clear'|'soft'|'hard', why }.
|
|
98
|
+
*/
|
|
99
|
+
function classifyBlocker(blocker) {
|
|
100
|
+
if (!blocker || typeof blocker !== 'object') {
|
|
101
|
+
return { state: HARD_BLOCK, why: 'blocker facts missing — treat as blocking' };
|
|
102
|
+
}
|
|
103
|
+
if (!blocker.open) {
|
|
104
|
+
return { state: CLEAR, why: 'blocker is closed' };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
const branch = blocker.branch;
|
|
108
|
+
if (!branch || typeof branch !== 'object') {
|
|
109
|
+
return { state: HARD_BLOCK, why: 'open, and no branch: no code exists yet' };
|
|
110
|
+
}
|
|
111
|
+
if (branch.pushed !== true) {
|
|
112
|
+
return {
|
|
113
|
+
state: HARD_BLOCK,
|
|
114
|
+
why: 'open, and its branch is not pushed — work nobody else can see is not evidence',
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
const verdict = landed.classify({
|
|
119
|
+
commitsAhead: branch.commitsAhead,
|
|
120
|
+
diffEmpty: branch.diffEmpty,
|
|
121
|
+
containment: branch.containment,
|
|
122
|
+
});
|
|
123
|
+
|
|
124
|
+
if (verdict.state === 'landed') {
|
|
125
|
+
// GUARD, and it closes a real fail-open hole. `landed` also comes back for a branch that is
|
|
126
|
+
// ahead by nothing — a branch pushed and never committed to introduces no content, so it reads
|
|
127
|
+
// exactly like a squash-merged one. Merged work and an empty branch are opposite facts about
|
|
128
|
+
// whether the dependency exists; only the first clears anything.
|
|
129
|
+
if (!(Number.isInteger(branch.commitsAhead) && branch.commitsAhead > 0)) {
|
|
130
|
+
return {
|
|
131
|
+
state: HARD_BLOCK,
|
|
132
|
+
why: 'its branch is pushed but carries no commits — an empty branch is not code',
|
|
133
|
+
};
|
|
134
|
+
}
|
|
135
|
+
return {
|
|
136
|
+
state: CLEAR,
|
|
137
|
+
why: `its work is already on the base (${verdict.why}); the open issue is tracker lag`,
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
if (verdict.state === 'cargo') {
|
|
141
|
+
return { state: SOFT_BLOCK, why: 'its code is written and pushed, waiting at the merge gate' };
|
|
142
|
+
}
|
|
143
|
+
return { state: HARD_BLOCK, why: `cannot tell whether its work exists (${verdict.why})` };
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* The whole verdict for one issue.
|
|
148
|
+
*
|
|
149
|
+
* Input: {
|
|
150
|
+
* blockers, // array of blocker facts. undefined/null means NOBODY LOOKED — not "none".
|
|
151
|
+
* depsChecked, // the marker meaning a REASONING SESSION verified an empty blocker list —
|
|
152
|
+
* // including blockers described only in prose, never encoded as an edge.
|
|
153
|
+
* graphEmpty, // the marker meaning an AUTHORITATIVE API READ found the encoded graph empty
|
|
154
|
+
* // (#69). Strictly weaker than depsChecked — it cannot see a prose-only
|
|
155
|
+
* // blocker — so it can promote UNCHECKED to UNCHECKED_MECHANICAL and no
|
|
156
|
+
* // further; only depsChecked (or a clear blocker list) reaches READY.
|
|
157
|
+
* }
|
|
158
|
+
*
|
|
159
|
+
* Returns { state, why, notes: [{ number, why }], hard: [{ number, why }] }.
|
|
160
|
+
*/
|
|
161
|
+
function classify({ blockers, depsChecked, graphEmpty } = {}) {
|
|
162
|
+
if (!Array.isArray(blockers)) {
|
|
163
|
+
return {
|
|
164
|
+
state: UNCHECKED,
|
|
165
|
+
why: 'no dependency data — an absent blocker list means nobody looked, not that none exist',
|
|
166
|
+
notes: [],
|
|
167
|
+
hard: [],
|
|
168
|
+
};
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
const judged = blockers.map((b) => ({ number: b && b.number, ...classifyBlocker(b) }));
|
|
172
|
+
const hard = judged.filter((j) => j.state === HARD_BLOCK);
|
|
173
|
+
const notes = judged.filter((j) => j.state === SOFT_BLOCK);
|
|
174
|
+
|
|
175
|
+
if (hard.length) {
|
|
176
|
+
return {
|
|
177
|
+
state: BLOCKED,
|
|
178
|
+
why: hard.map((j) => `#${j.number}: ${j.why}`).join('; '),
|
|
179
|
+
notes,
|
|
180
|
+
hard,
|
|
181
|
+
};
|
|
182
|
+
}
|
|
183
|
+
if (notes.length) {
|
|
184
|
+
return {
|
|
185
|
+
state: SOFT,
|
|
186
|
+
why: notes.map((j) => `#${j.number}: ${j.why}`).join('; '),
|
|
187
|
+
notes,
|
|
188
|
+
hard: [],
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
if (blockers.length === 0 && !depsChecked) {
|
|
192
|
+
if (graphEmpty) {
|
|
193
|
+
return {
|
|
194
|
+
state: UNCHECKED_MECHANICAL,
|
|
195
|
+
why: 'blocker list is empty and an API read confirms it — but nobody has judged prose blockers',
|
|
196
|
+
notes: [],
|
|
197
|
+
hard: [],
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
return {
|
|
201
|
+
state: UNCHECKED,
|
|
202
|
+
why: 'blocker list is empty and unverified — "none" and "nobody checked" look identical',
|
|
203
|
+
notes: [],
|
|
204
|
+
hard: [],
|
|
205
|
+
};
|
|
206
|
+
}
|
|
207
|
+
return {
|
|
208
|
+
state: READY,
|
|
209
|
+
why: blockers.length ? 'every blocker is closed or already landed' : 'checked: no blockers',
|
|
210
|
+
notes: [],
|
|
211
|
+
hard: [],
|
|
212
|
+
};
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* Callers act on this, not on `state`: work may begin on a positive `ready` or `ready-with-a-note`
|
|
217
|
+
* and on nothing else. `unchecked` is not startable — that is the distinction the marker exists for.
|
|
218
|
+
* `unchecked-mechanical` ALSO reads not-startable here, on purpose: this is the conservative
|
|
219
|
+
* default every existing consumer already gets, unaffected by #69's weaker signal existing.
|
|
220
|
+
*/
|
|
221
|
+
function isStartable(verdict) {
|
|
222
|
+
return Boolean(verdict) && (verdict.state === READY || verdict.state === SOFT);
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/**
|
|
226
|
+
* The OPT-IN, weaker lane (#69): a consumer that has decided a mechanically-confirmed-empty
|
|
227
|
+
* graph is worth starting on, without waiting for a reasoning session, calls this instead of
|
|
228
|
+
* `isStartable`. It accepts everything `isStartable` does, plus `unchecked-mechanical`. Nothing
|
|
229
|
+
* in this repo's own triage or scheduled-driver path calls this — adopting it is a per-consumer
|
|
230
|
+
* decision, exactly as `graph-empty` is a per-repo opt-in label (CONVENTIONS.md §5).
|
|
231
|
+
*/
|
|
232
|
+
function isStartableMechanical(verdict) {
|
|
233
|
+
return Boolean(verdict) && (verdict.state === READY || verdict.state === SOFT || verdict.state === UNCHECKED_MECHANICAL);
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
module.exports = {
|
|
237
|
+
classify, classifyBlocker, isStartable, isStartableMechanical,
|
|
238
|
+
READY, SOFT, BLOCKED, UNCHECKED, UNCHECKED_MECHANICAL,
|
|
239
|
+
CLEAR, SOFT_BLOCK, HARD_BLOCK,
|
|
240
|
+
};
|