@futurelastic/colab-handbook 1.20.4-rc.2 → 1.20.4-rc.4
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/package.json +1 -1
- package/tools/colab +7 -2
- package/tools/lib/container-close.js +42 -2
- package/tools/lib/state.js +150 -8
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -13514,8 +13514,9 @@ function shipMode(repoAbs, target, branch, commits) {
|
|
|
13514
13514
|
* this ship actually closed, read its NATIVE parent and let lib/container-close.js decide; close
|
|
13515
13515
|
* the parent with an evidence comment only on `close`, then ask the same question of ITS parent
|
|
13516
13516
|
* (an epic of epics empties from the bottom up). Every other verdict leaves the parent exactly as
|
|
13517
|
-
* it is; the ones a human should see (`not-container`, `unfiled-items`, `unknown`)
|
|
13518
|
-
* findings.
|
|
13517
|
+
* it is; the ones a human should see (`not-container`, `unfiled-items`, `done-when`, `unknown`)
|
|
13518
|
+
* are printed as findings. `done-when` (#713) also gets a one-line proposal comment on the epic —
|
|
13519
|
+
* every filed child is closed, but the body's `Done when` acceptance is the coordinator's to read. Best-effort like every post-merge write: a failure here warns, never fails the ship —
|
|
13519
13520
|
* the merge already landed. A lagging `subIssuesSummary` reads as `children-open` and is caught by
|
|
13520
13521
|
* the next ship of a sibling or by code-sweep §5, never by guessing.
|
|
13521
13522
|
*/
|
|
@@ -13540,6 +13541,10 @@ function shipCloseSpentContainers(repoAbs, closedIssues, { sha, target } = {}) {
|
|
|
13540
13541
|
if (c.verdict !== 'close') {
|
|
13541
13542
|
const finding = containerClose.containerFinding({ ...c, number: c.number === null ? pnum : c.number });
|
|
13542
13543
|
if (finding) warn(`container ${finding}`);
|
|
13544
|
+
if (c.verdict === 'done-when') {
|
|
13545
|
+
const pc = git.ghIssueComment(repoAbs, pnum, containerClose.containerProposalComment({ child, sha, total: c.total, target }));
|
|
13546
|
+
if (!pc.ok) warnDeferred(`could not post the done-when proposal on #${pnum} — it stays open either way`);
|
|
13547
|
+
}
|
|
13543
13548
|
break;
|
|
13544
13549
|
}
|
|
13545
13550
|
const body = containerClose.containerCloseComment({ child, sha, total: c.total, target });
|
|
@@ -20,6 +20,12 @@
|
|
|
20
20
|
* - its body holds no unticked checklist line. An unticked `- [ ]` on an epic is an item
|
|
21
21
|
* somebody listed and nobody filed as a sub-issue yet — the "two phases whose issues are not
|
|
22
22
|
* written yet" B2c's rule was protecting. It is reported, never closed over;
|
|
23
|
+
* - its body states no `Done when` acceptance (#713). `file-issues` tells a filer to put an
|
|
24
|
+
* epic's end state in a `Done when:` line, never a body checklist — so on an epic written to
|
|
25
|
+
* that convention the unticked check above sees nothing, and a phase epic filed with only its
|
|
26
|
+
* design child (the code children to be filed once the design is approved) read as spent the
|
|
27
|
+
* moment that one child shipped. "Every filed child closed" says nothing about whether the
|
|
28
|
+
* stated end state holds; that reading is the coordinator's, so ship proposes and never closes;
|
|
23
29
|
* - it is not a release tracking record (`<!-- colab:release …` body) — `colab release
|
|
24
30
|
* finalize` owns that record's lifecycle, not a child's ship.
|
|
25
31
|
*
|
|
@@ -36,6 +42,8 @@
|
|
|
36
42
|
* children-open at least one sub-issue is still open — the normal state of a live epic
|
|
37
43
|
* not-container every child closed, but no `epic` label — report for a human
|
|
38
44
|
* unfiled-items every child closed, but the body still lists unticked items — report
|
|
45
|
+
* done-when every child closed, but the body states `Done when` acceptance — ship posts
|
|
46
|
+
* a one-line proposal for the coordinator to check it and close (#713)
|
|
39
47
|
*
|
|
40
48
|
* Fail toward keeping open, the same asymmetry `group-labels.js` states for its own delete: a
|
|
41
49
|
* container closed early buries unwritten work behind a closed issue nobody browses, while one
|
|
@@ -52,6 +60,14 @@ const RELEASE_RECORD_RE = /^\s*<!--\s*colab:release\b/;
|
|
|
52
60
|
/** An UNTICKED GitHub checklist line anywhere in the body — `- [ ] …` / `* [ ] …`. */
|
|
53
61
|
const UNTICKED_RE = /^\s*[-*]\s*\[ \]\s*(.+)$/;
|
|
54
62
|
|
|
63
|
+
/**
|
|
64
|
+
* A `Done when` acceptance statement at the start of a line (#713): a heading (`## Done when`), a
|
|
65
|
+
* label line (`Done when:`, `**Done when:**`, `- Done when: …`), any case, `Done-when` too. Only at
|
|
66
|
+
* a line start, so prose that merely mentions the phrase mid-sentence does not count; a blockquote
|
|
67
|
+
* (`> Done when`) is a quotation, not this epic's own acceptance.
|
|
68
|
+
*/
|
|
69
|
+
const DONE_WHEN_RE = /^\s*(?:#{1,6}\s+)?(?:[-*+]\s+)?(?:\*\*|__)?done[ -]when\b/i;
|
|
70
|
+
|
|
55
71
|
function labelNames(labels) {
|
|
56
72
|
return (labels || []).map((l) => (l && typeof l === 'object' ? l.name : l)).map((n) => String(n));
|
|
57
73
|
}
|
|
@@ -70,6 +86,16 @@ function untickedItems(body) {
|
|
|
70
86
|
return out;
|
|
71
87
|
}
|
|
72
88
|
|
|
89
|
+
/** Does the body state `Done when` acceptance outside fenced code? (#713) */
|
|
90
|
+
function hasDoneWhen(body) {
|
|
91
|
+
let fenced = false;
|
|
92
|
+
for (const line of String(body || '').split('\n')) {
|
|
93
|
+
if (/^\s*(```|~~~)/.test(line)) { fenced = !fenced; continue; }
|
|
94
|
+
if (!fenced && DONE_WHEN_RE.test(line)) return true;
|
|
95
|
+
}
|
|
96
|
+
return false;
|
|
97
|
+
}
|
|
98
|
+
|
|
73
99
|
/**
|
|
74
100
|
* Classify ONE parent issue after a child of it closed.
|
|
75
101
|
*
|
|
@@ -99,6 +125,7 @@ function classifyContainer(parent) {
|
|
|
99
125
|
if (!labelNames(parent.labels).includes(EPIC_LABEL)) return { ...out, verdict: 'not-container' };
|
|
100
126
|
const unticked = untickedItems(parent.body);
|
|
101
127
|
if (unticked.length) return { ...out, unticked, verdict: 'unfiled-items' };
|
|
128
|
+
if (hasDoneWhen(parent.body)) return { ...out, verdict: 'done-when' };
|
|
102
129
|
return { ...out, verdict: 'close' };
|
|
103
130
|
}
|
|
104
131
|
|
|
@@ -120,6 +147,16 @@ function containerCloseComment({ child, sha, total, target }) {
|
|
|
120
147
|
return `📦 Closed by colab ship — ${via}${at}; all ${total} sub-issue(s) are closed and the body lists no unticked item (#371).`;
|
|
121
148
|
}
|
|
122
149
|
|
|
150
|
+
/**
|
|
151
|
+
* The proposal comment posted on an epic whose verdict is `done-when` (#713) — the epic stays OPEN.
|
|
152
|
+
* One line, issue-specific only: which child emptied it, and what the coordinator checks next.
|
|
153
|
+
*/
|
|
154
|
+
function containerProposalComment({ child, sha, total, target }) {
|
|
155
|
+
const via = child ? `its last open sub-issue #${child} shipped` : 'its last open sub-issue closed';
|
|
156
|
+
const at = sha ? ` to ${target || 'trunk'} at ${sha}` : '';
|
|
157
|
+
return `📋 All ${total} sub-issue(s) closed — ${via}${at}. Left open: check \`Done when\` and close if met, or file the remaining work as sub-issues (#713).`;
|
|
158
|
+
}
|
|
159
|
+
|
|
123
160
|
/** One report line for a verdict that is NOT `close` but still worth a human's eye; null otherwise. */
|
|
124
161
|
function containerFinding(c) {
|
|
125
162
|
const n = c.number !== null ? `#${c.number}` : 'parent';
|
|
@@ -128,6 +165,8 @@ function containerFinding(c) {
|
|
|
128
165
|
return `${n}: all ${c.total} sub-issue(s) closed, but it is not labelled \`epic\` — close it by hand if it is a container`;
|
|
129
166
|
case 'unfiled-items':
|
|
130
167
|
return `${n}: all ${c.total} sub-issue(s) closed, but ${c.unticked.length} unticked item(s) remain in its body — file them as sub-issues or tick them, then close`;
|
|
168
|
+
case 'done-when':
|
|
169
|
+
return `${n}: all ${c.total} sub-issue(s) closed, but its body states \`Done when\` — left open for the coordinator to check it`;
|
|
131
170
|
case 'unknown':
|
|
132
171
|
return `${n}: could not read the parent — container close skipped`;
|
|
133
172
|
default:
|
|
@@ -173,7 +212,8 @@ function parentRelationFinding(rel) {
|
|
|
173
212
|
}
|
|
174
213
|
|
|
175
214
|
module.exports = {
|
|
176
|
-
EPIC_LABEL, RELEASE_RECORD_RE,
|
|
215
|
+
EPIC_LABEL, RELEASE_RECORD_RE, DONE_WHEN_RE,
|
|
177
216
|
issueRepoSlug, parentRelation, parentRelationFinding,
|
|
178
|
-
untickedItems, classifyContainer, containerDeliveryLabels, containerCloseComment,
|
|
217
|
+
untickedItems, hasDoneWhen, classifyContainer, containerDeliveryLabels, containerCloseComment,
|
|
218
|
+
containerProposalComment, containerFinding,
|
|
179
219
|
};
|
package/tools/lib/state.js
CHANGED
|
@@ -187,27 +187,168 @@ function sleep(ms) {
|
|
|
187
187
|
while (Date.now() < end) { /* spin */ }
|
|
188
188
|
}
|
|
189
189
|
|
|
190
|
-
|
|
191
|
-
|
|
190
|
+
/*
|
|
191
|
+
* The state lock (#712). `mkdir LOCK_DIR` is still the acquire — atomic, and the same primitive an
|
|
192
|
+
* older colab on this machine uses, so the two still exclude each other. What changed is that the
|
|
193
|
+
* holder now writes LOCK_OWNER inside it, and a waiter uses that record to tell a dead lock from a
|
|
194
|
+
* live one. Before, the directory recorded nothing: a holder that died inside the critical section
|
|
195
|
+
* left it forever, every state write on the machine (claims, worktrees, ports, places, ship) failed
|
|
196
|
+
* with "Lock stuck", and nobody could tell whether removing it by hand was safe.
|
|
197
|
+
*
|
|
198
|
+
* A waiter breaks the lock itself, logging one line, only when the holder is provably gone:
|
|
199
|
+
* - its pid is dead (same host), or
|
|
200
|
+
* - its pid is alive but started at a different time than the record says (pid reused), or
|
|
201
|
+
* - liveness cannot be proven at all — no readable owner (an older colab, or a holder that died
|
|
202
|
+
* between mkdir and writing the record), another host, or a start time `ps` cannot give — AND
|
|
203
|
+
* the lock is older than LOCK_STALE_MS, far above any real critical section (they are
|
|
204
|
+
* synchronous file edits: milliseconds).
|
|
205
|
+
* A live, matching holder is never broken, however old: the waiter gives up with the holder named.
|
|
206
|
+
*
|
|
207
|
+
* Breaking is race-safe in two layers. Breakers serialize on LOCK_BREAK (a second mkdir lock, held
|
|
208
|
+
* for microseconds), and inside it the breaker renames LOCK_DIR to a private name and re-reads the
|
|
209
|
+
* owner from THAT copy: only the exact stale owner it judged (same token) is removed. Anything else
|
|
210
|
+
* — a waiter that acquired a fresh lock in between — is renamed straight back.
|
|
211
|
+
*/
|
|
212
|
+
const LOCK_OWNER = 'owner.json';
|
|
213
|
+
const LOCK_BREAK = LOCK_DIR + '.break';
|
|
214
|
+
const LOCK_STALE_MS = 60 * 1000;
|
|
215
|
+
const PROC_START_MS = Date.now() - Math.round(process.uptime() * 1000);
|
|
216
|
+
const START_TOLERANCE_MS = 3000; // `ps -o lstart` truncates to whole seconds; uptime starts after exec
|
|
217
|
+
|
|
218
|
+
function lockOwnerRecord() {
|
|
219
|
+
return {
|
|
220
|
+
pid: process.pid, host: os.hostname(), start: PROC_START_MS, at: Date.now(),
|
|
221
|
+
token: `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
|
|
222
|
+
};
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** The owner record in `dir`, or null when absent/unreadable (an older colab, or mid-write). */
|
|
226
|
+
function readLockOwner(dir = LOCK_DIR) {
|
|
227
|
+
try {
|
|
228
|
+
const o = JSON.parse(fs.readFileSync(path.join(dir, LOCK_OWNER), 'utf8'));
|
|
229
|
+
return o && Number.isInteger(o.pid) && typeof o.token === 'string' ? o : null;
|
|
230
|
+
} catch (_) { return null; }
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** true = alive, false = no such process, null = cannot tell. */
|
|
234
|
+
function pidAlive(pid) {
|
|
235
|
+
try { process.kill(pid, 0); return true; } catch (e) {
|
|
236
|
+
if (e.code === 'ESRCH') return false;
|
|
237
|
+
if (e.code === 'EPERM') return true; // exists, owned by someone else
|
|
238
|
+
return null;
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** Start time (ms) of a live pid per `ps`, or null when ps cannot say. */
|
|
243
|
+
function pidStartMs(pid) {
|
|
244
|
+
try {
|
|
245
|
+
const out = require('child_process').execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)],
|
|
246
|
+
{ encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }).trim();
|
|
247
|
+
const t = Date.parse(out);
|
|
248
|
+
return Number.isFinite(t) ? t : null;
|
|
249
|
+
} catch (_) { return null; }
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* Judge the lock currently at LOCK_DIR. Returns { stale, owner, ageMs, reason } or null when there
|
|
254
|
+
* is no lock to judge. `startCache` (token -> ps start) keeps `ps` to once per holder per wait.
|
|
255
|
+
*/
|
|
256
|
+
function judgeLock(startCache = new Map(), now = Date.now()) {
|
|
257
|
+
let st;
|
|
258
|
+
try { st = fs.statSync(LOCK_DIR); } catch (_) { return null; }
|
|
259
|
+
const owner = readLockOwner();
|
|
260
|
+
const ageMs = Math.max(0, now - (owner && Number.isFinite(owner.at) ? owner.at : st.mtimeMs));
|
|
261
|
+
const old = ageMs > LOCK_STALE_MS;
|
|
262
|
+
if (!owner) return { stale: old, owner, ageMs, reason: 'no owner record' };
|
|
263
|
+
if (owner.host && owner.host !== os.hostname()) return { stale: old, owner, ageMs, reason: `held from host ${owner.host}` };
|
|
264
|
+
const alive = pidAlive(owner.pid);
|
|
265
|
+
if (alive === false) return { stale: true, owner, ageMs, reason: `pid ${owner.pid} is gone` };
|
|
266
|
+
if (alive === null) return { stale: old, owner, ageMs, reason: `pid ${owner.pid} liveness unknown` };
|
|
267
|
+
if (!startCache.has(owner.token)) startCache.set(owner.token, pidStartMs(owner.pid));
|
|
268
|
+
const psStart = startCache.get(owner.token);
|
|
269
|
+
if (psStart == null || !Number.isFinite(owner.start)) {
|
|
270
|
+
return { stale: old, owner, ageMs, reason: `pid ${owner.pid} alive, start time unverifiable` };
|
|
271
|
+
}
|
|
272
|
+
if (Math.abs(psStart - owner.start) > START_TOLERANCE_MS) {
|
|
273
|
+
return { stale: true, owner, ageMs, reason: `pid ${owner.pid} was reused by another process` };
|
|
274
|
+
}
|
|
275
|
+
return { stale: false, owner, ageMs, reason: `pid ${owner.pid} is alive` };
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
function describeHolder(j) {
|
|
279
|
+
if (!j) return 'holder unknown (lock vanished)';
|
|
280
|
+
const age = `${Math.round(j.ageMs / 1000)}s old`;
|
|
281
|
+
if (!j.owner) return `no owner recorded, ${age}`;
|
|
282
|
+
return `held by pid ${j.owner.pid} on ${j.owner.host || '?'}, ${age} — ${j.reason}`;
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
function rmLockDir(dir) {
|
|
286
|
+
try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) { /* best effort */ }
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* Remove the lock `judged` found stale — but only if it is still that same lock. Returns true when
|
|
291
|
+
* it removed it. Never throws: a failed break just means the waiter keeps waiting.
|
|
292
|
+
*/
|
|
293
|
+
function breakStaleLock(judged, log = (m) => process.stderr.write(m + '\n')) {
|
|
294
|
+
try { fs.mkdirSync(LOCK_BREAK); } catch (e) {
|
|
295
|
+
// Another breaker is at it. A breaker that died mid-break leaves an empty LOCK_BREAK; clear it
|
|
296
|
+
// once it is far older than the microseconds a break takes, and let the next round retry.
|
|
297
|
+
try { if (Date.now() - fs.statSync(LOCK_BREAK).mtimeMs > 10 * 1000) fs.rmdirSync(LOCK_BREAK); } catch (_) { /* gone */ }
|
|
298
|
+
return false;
|
|
299
|
+
}
|
|
300
|
+
try {
|
|
301
|
+
const grave = `${LOCK_DIR}.stale-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
|
|
302
|
+
try { fs.renameSync(LOCK_DIR, grave); } catch (_) { return false; } // released meanwhile
|
|
303
|
+
const now = readLockOwner(grave);
|
|
304
|
+
const same = judged.owner ? (now && now.token === judged.owner.token) : !now;
|
|
305
|
+
if (!same) {
|
|
306
|
+
// A fresh lock replaced the stale one between judging and renaming — put it back untouched.
|
|
307
|
+
try { fs.renameSync(grave, LOCK_DIR); } catch (_) { /* LOCK_DIR re-taken: nothing safe to do */ }
|
|
308
|
+
return false;
|
|
309
|
+
}
|
|
310
|
+
rmLockDir(grave);
|
|
311
|
+
log(`colab: broke a stale state lock ${LOCK_DIR} (${describeHolder(judged)})`);
|
|
312
|
+
return true;
|
|
313
|
+
} finally {
|
|
314
|
+
try { fs.rmdirSync(LOCK_BREAK); } catch (_) { /* gone */ }
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
/** Acquire the state lock, run fn, always release. Returns fn's result. */
|
|
319
|
+
function withLock(fn, { tries = 100, waitMs = 100, log } = {}) {
|
|
192
320
|
ensureDir();
|
|
193
|
-
|
|
321
|
+
const startCache = new Map();
|
|
322
|
+
let me = null;
|
|
323
|
+
let written = false;
|
|
324
|
+
let last = null;
|
|
194
325
|
for (let i = 0; i < tries; i++) {
|
|
195
326
|
try {
|
|
196
327
|
fs.mkdirSync(LOCK_DIR);
|
|
197
|
-
|
|
328
|
+
me = lockOwnerRecord();
|
|
329
|
+
try { fs.writeFileSync(path.join(LOCK_DIR, LOCK_OWNER), JSON.stringify(me) + '\n'); written = true; } catch (_) {
|
|
330
|
+
// Unrecorded is still a held lock — it just ages out like an older colab's would.
|
|
331
|
+
}
|
|
198
332
|
break;
|
|
199
333
|
} catch (e) {
|
|
200
334
|
if (e.code !== 'EEXIST') throw e;
|
|
335
|
+
last = judgeLock(startCache);
|
|
336
|
+
if (last && last.stale && breakStaleLock(last, log)) continue; // retry the mkdir at once
|
|
201
337
|
sleep(waitMs);
|
|
202
338
|
}
|
|
203
339
|
}
|
|
204
|
-
if (!
|
|
205
|
-
|
|
340
|
+
if (!me) {
|
|
341
|
+
const holder = describeHolder(judgeLock(startCache) || last);
|
|
342
|
+
throw new Error(`Lock stuck: ${LOCK_DIR} (${holder}). `
|
|
343
|
+
+ 'A live holder is never broken automatically; remove the directory by hand only if that process is not a colab writer.');
|
|
206
344
|
}
|
|
207
345
|
try {
|
|
208
346
|
return fn();
|
|
209
347
|
} finally {
|
|
210
|
-
|
|
348
|
+
// Release only our own lock: if a waiter judged us dead and broke it, LOCK_DIR is now theirs —
|
|
349
|
+
// including an ownerless one, when we did write our record and it is no longer there.
|
|
350
|
+
const cur = readLockOwner();
|
|
351
|
+
if (cur ? cur.token === me.token : !written) rmLockDir(LOCK_DIR);
|
|
211
352
|
}
|
|
212
353
|
}
|
|
213
354
|
|
|
@@ -257,6 +398,7 @@ function mutate(fn) {
|
|
|
257
398
|
}
|
|
258
399
|
|
|
259
400
|
module.exports = {
|
|
260
|
-
COLAB_DIR, STATE_FILE, CONFIG_FILE, LOCK_DIR, STATE_VERSION, DEFAULT_CONFIG,
|
|
401
|
+
COLAB_DIR, STATE_FILE, CONFIG_FILE, LOCK_DIR, LOCK_OWNER, LOCK_STALE_MS, STATE_VERSION, DEFAULT_CONFIG,
|
|
261
402
|
loadConfig, saveConfig, loadState, saveState, withLock, mutate, emptyState, atomicWrite,
|
|
403
|
+
_lock: { judgeLock, breakStaleLock, readLockOwner }, // for tools/lib/state-lock.test.js
|
|
262
404
|
};
|