@futurelastic/colab-handbook 1.13.0-rc.2 → 1.13.0-rc.21

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.
@@ -6,6 +6,12 @@
6
6
  * close, ship, worktree new, worktree rm, readiness) each POST one small JSON event as they succeed. Leave it unset
7
7
  * and this module makes no network call of any kind — that is the default and it is absolute.
8
8
  *
9
+ * `notifyUrl` is a string (one receiver) or an array of strings (several — a machine running two
10
+ * local observers side by side, #546). Every event goes to every URL, each through its OWN detached
11
+ * child, so a dead or hanging receiver can never cost another receiver its event. One URL is stored
12
+ * as a plain string, exactly as before the array form existed (`storedNotifyUrl` below), so a
13
+ * single-observer machine's config.json never changes shape.
14
+ *
9
15
  * ── What this is NOT ──────────────────────────────────────────────────────────────────────────
10
16
  * It is not a transport anyone may depend on. The observers this exists for already discover every
11
17
  * one of these facts on their own, by polling ~/.colab/state.json on a timer; the push only sharpens
@@ -123,6 +129,35 @@ function buildEvent(action, fields, ts) {
123
129
  return ev;
124
130
  }
125
131
 
132
+ /**
133
+ * Every configured receiver, in order, deduplicated, trimmed. Accepts the string form (one URL) and
134
+ * the array form (#546); any other shape — a number, an object, a non-string array entry — reads as
135
+ * no receiver rather than a crash, because this sits on the path of commands that already succeeded.
136
+ * Validity (http/https) is NOT filtered here: notify() distinguishes "nothing configured" (silent)
137
+ * from "configured but unusable" (skipped), and a health check needs to see the raw entries.
138
+ */
139
+ function configuredUrls(cfg) {
140
+ const raw = cfg ? cfg.notifyUrl : undefined;
141
+ const list = typeof raw === 'string' ? [raw] : Array.isArray(raw) ? raw : [];
142
+ const out = [];
143
+ for (const u of list) {
144
+ if (typeof u !== 'string') continue;
145
+ const t = u.trim();
146
+ if (t && !out.includes(t)) out.push(t);
147
+ }
148
+ return out;
149
+ }
150
+
151
+ /**
152
+ * The on-disk value for a list of URLs: absent for none, a plain string for one, an array for
153
+ * several. One URL is stored exactly as it always was, so a single-observer machine's config.json is
154
+ * byte-for-byte what it would have been before the array form existed (#546 ask 4).
155
+ */
156
+ function storedNotifyUrl(urls) {
157
+ if (!urls || urls.length === 0) return undefined;
158
+ return urls.length === 1 ? urls[0] : urls.slice();
159
+ }
160
+
126
161
  /**
127
162
  * The script the child runs. Kept as one string, taking url and body from argv rather than being
128
163
  * interpolated into source — the body carries branch and worktree names typed by a user, and
@@ -145,13 +180,18 @@ try {
145
180
  `;
146
181
 
147
182
  /**
148
- * Fire one event. Returns a string saying what happened, for tests and for --json callers; NOTHING
149
- * about the send is reported to the user, because a warning about a secondary signal is noise on
150
- * the output of a command that succeeded.
183
+ * Fire one event at every configured receiver. Returns a string saying what happened, for tests and
184
+ * for --json callers; NOTHING about the send is reported to the user, because a warning about a
185
+ * secondary signal is noise on the output of a command that succeeded.
151
186
  *
152
187
  * 'silent' no notifyUrl configured — not one network call was made
153
- * 'skipped' unknown action, or a URL we will not send to
154
- * 'sent' handed to a detached child; delivery is neither awaited nor known
188
+ * 'skipped' unknown action, or no URL we will send to (every one non-http, or every spawn failed)
189
+ * 'sent' handed to at least one detached child; delivery is neither awaited nor known
190
+ *
191
+ * One child per URL, never one child looping over the list: a child stuck on a hung receiver would
192
+ * then hold every later receiver's request behind it, and a receiver that throws mid-loop would cost
193
+ * the rest their event. Separate children make "a dead receiver never fails the command" hold per
194
+ * receiver too (#546).
155
195
  *
156
196
  * @param {object} cfg loaded config (state.loadConfig())
157
197
  * @param {string} action one of ACTIONS
@@ -161,28 +201,34 @@ try {
161
201
  function notify(cfg, action, fields, deps) {
162
202
  // The unconfigured path must return before anything else can throw, allocate, or resolve a host.
163
203
  // "Absolute silence" is the documented default, so it is checked first and checked cheaply.
164
- const url = cfg && typeof cfg.notifyUrl === 'string' ? cfg.notifyUrl.trim() : '';
165
- if (!url) return 'silent';
166
- if (!/^https?:\/\//i.test(url)) return 'skipped';
204
+ const urls = configuredUrls(cfg);
205
+ if (urls.length === 0) return 'silent';
206
+ const usable = urls.filter((u) => /^https?:\/\//i.test(u));
207
+ if (usable.length === 0) return 'skipped';
167
208
 
168
209
  const ev = buildEvent(action, fields);
169
210
  if (!ev) return 'skipped';
170
211
 
171
212
  const spawnFn = (deps && deps.spawn) || spawn;
172
- try {
173
- const child = spawnFn(process.execPath, ['-e', CHILD_SCRIPT, '--', url, JSON.stringify(ev)], {
174
- detached: true,
175
- stdio: 'ignore',
176
- });
177
- // unref() is what makes this fire-and-forget rather than fire-and-wait: without it the parent's
178
- // event loop would keep the child in its dependants and the exit would block on a hung receiver.
179
- if (child && typeof child.unref === 'function') child.unref();
180
- return 'sent';
181
- } catch (_) {
182
- // Spawning can fail for reasons that have nothing to do with the user's command (EAGAIN under
183
- // process pressure, a locked-down execPath). Swallowing is the whole contract.
184
- return 'skipped';
213
+ const body = JSON.stringify(ev);
214
+ let sent = 0;
215
+ for (const url of usable) {
216
+ try {
217
+ const child = spawnFn(process.execPath, ['-e', CHILD_SCRIPT, '--', url, body], {
218
+ detached: true,
219
+ stdio: 'ignore',
220
+ });
221
+ // unref() is what makes this fire-and-forget rather than fire-and-wait: without it the parent's
222
+ // event loop would keep the child in its dependants and the exit would block on a hung receiver.
223
+ if (child && typeof child.unref === 'function') child.unref();
224
+ sent += 1;
225
+ } catch (_) {
226
+ // Spawning can fail for reasons that have nothing to do with the user's command (EAGAIN under
227
+ // process pressure, a locked-down execPath). Swallowing is the whole contract — and it is
228
+ // per URL, so one failed spawn never costs the next receiver its event.
229
+ }
185
230
  }
231
+ return sent > 0 ? 'sent' : 'skipped';
186
232
  }
187
233
 
188
- module.exports = { notify, buildEvent, ACTION_KIND, ACTIONS, SEND_TIMEOUT_MS };
234
+ module.exports = { notify, buildEvent, configuredUrls, storedNotifyUrl, ACTION_KIND, ACTIONS, SEND_TIMEOUT_MS };
@@ -622,6 +622,42 @@ const LARAVEL_DESTRUCTIVE = /(\b(drop|dropIfExists|dropColumn|dropColumns|dropFo
622
622
  // statements `-- DropIndex`, which is a comment, not a statement.
623
623
  const SQL_DESTRUCTIVE = /\b(DROP\s+(TABLE|COLUMN|INDEX|CONSTRAINT|TYPE|VIEW|SCHEMA)|RENAME\s+(TO|COLUMN)|ALTER\s+COLUMN|TRUNCATE)\b/i;
624
624
 
625
+ // #545: SQL migration tools that keep the rollback in the SAME file mark it with a comment line —
626
+ // sql-migrate `-- +migrate Up|Down`, goose `-- +goose Up|Down`, dbmate `-- migrate:up|down`. The Down
627
+ // section dropping what Up created is the ordinary shape of an additive migration (same reading as
628
+ // Laravel's down() above), so only lines outside a Down section are matched. Measured: one adopting
629
+ // repo's release stalled ~26 h on a purely additive file (six CREATE TABLE in Up, six DROP TABLE IF
630
+ // EXISTS in Down) because the whole file was read. Fails CLOSED: lines before any marker are kept, a
631
+ // file with no marker is read whole, and a second Up marker re-opens reading after a Down.
632
+ const SQL_UP_MARKER = /^\s*--\s*(\+(migrate|goose)\s+up|migrate:up)\b/i;
633
+ const SQL_DOWN_MARKER = /^\s*--\s*(\+(migrate|goose)\s+down|migrate:down)\b/i;
634
+ // golang-migrate and friends put the rollback in its own `<n>_<name>.down.sql` — the whole file is a
635
+ // Down section. Only an ADDED one is exempt; editing or deleting it is still a rewritten migration.
636
+ const SQL_DOWN_FILE = /\.down\.sql$/i;
637
+
638
+ /**
639
+ * The first destructive SQL statement outside a Down section — `{ statement, line, inUp }` (1-based
640
+ * line in the original file; `inUp` = an Up marker opened the section it sits in) — or null. Skipped
641
+ * lines are blanked, not removed, so line numbers stay true and a statement split across lines
642
+ * (`DROP\n TABLE`) still matches, as it did when the whole file was read.
643
+ */
644
+ function sqlDestructive(text) {
645
+ let section = 'pre';
646
+ const sections = [];
647
+ const kept = String(text).split('\n').map((l) => {
648
+ if (SQL_DOWN_MARKER.test(l)) section = 'down';
649
+ else if (SQL_UP_MARKER.test(l)) section = 'up';
650
+ sections.push(section);
651
+ // `--` comment lines (markers included) are blanked too: Prisma labels its statements `-- DropIndex`.
652
+ return section === 'down' || /^\s*--/.test(l) ? '' : l;
653
+ });
654
+ const joined = kept.join('\n');
655
+ const m = SQL_DESTRUCTIVE.exec(joined);
656
+ if (!m) return null;
657
+ const line = joined.slice(0, m.index).split('\n').length;
658
+ return { statement: m[0].replace(/\s+/g, ' '), line, inUp: sections[line - 1] === 'up' };
659
+ }
660
+
625
661
  function laravelUpBody(text) {
626
662
  const up = text.search(/function\s+up\s*\(/);
627
663
  if (up === -1) return text;
@@ -664,9 +700,9 @@ function schemaVerdict(changes, since, declared) {
664
700
  const m = LARAVEL_DESTRUCTIVE.exec(laravelUpBody(text));
665
701
  if (m) findings.push(`${c.path}: \`${m[0].trim()}\` in up()`);
666
702
  } else {
667
- const sql = text.split('\n').filter((l) => !/^\s*--/.test(l)).join('\n');
668
- const m = SQL_DESTRUCTIVE.exec(sql);
669
- if (m) findings.push(`${c.path}: \`${m[0]}\``);
703
+ if (SQL_DOWN_FILE.test(c.path)) continue;
704
+ const m = sqlDestructive(text);
705
+ if (m) findings.push(`${c.path}:${m.line}: \`${m.statement}\`${m.inUp ? ' in the Up section' : ''}`);
670
706
  }
671
707
  }
672
708
  if (findings.length) {
@@ -297,7 +297,10 @@ function whyNoFinal({ state, candidate, checks, period, skipped, now } = {}) {
297
297
 
298
298
  // ---- the test period ----------------------------------------------------------------------------
299
299
 
300
- /** { start, endsAt, elapsed, detail } — start = max(cutAt, trackingCreatedAt). All ISO strings. */
300
+ /**
301
+ * { start, endsAt, days, elapsed, detail } — start = max(cutAt, trackingCreatedAt), ISO strings. `days` 0
302
+ * (#549, human final only) is no test period: elapsed at once, and the detail says so.
303
+ */
301
304
  function periodVerdict({ cutAt, trackingCreatedAt, testPeriodDays, now }) {
302
305
  const cut = Date.parse(cutAt);
303
306
  const created = trackingCreatedAt ? Date.parse(trackingCreatedAt) : NaN;
@@ -310,8 +313,11 @@ function periodVerdict({ cutAt, trackingCreatedAt, testPeriodDays, now }) {
310
313
  return {
311
314
  start: new Date(startMs).toISOString(),
312
315
  endsAt: new Date(endMs).toISOString(),
316
+ days: testPeriodDays,
313
317
  elapsed,
314
- detail: elapsed
318
+ detail: testPeriodDays === 0
319
+ ? 'no test period (release.test-period: 0d, a human final — the human\'s finalize is the test, #549)'
320
+ : elapsed
315
321
  ? `${testPeriodDays}d test period from ${new Date(startMs).toISOString()} ended ${new Date(endMs).toISOString()}`
316
322
  : `${testPeriodDays}d test period from ${new Date(startMs).toISOString()} ends ${new Date(endMs).toISOString()} (${hours}h left)`,
317
323
  };
@@ -590,7 +596,7 @@ function tagMessage(verdict, { candidate, period, actor }) {
590
596
  '',
591
597
  `Candidate: ${candidate.tag}`,
592
598
  `Commit: ${candidate.sha}`,
593
- period ? `Test period: ${period.start} -> ${period.endsAt}` : null,
599
+ period ? (period.days === 0 ? 'Test period: none (release.test-period: 0d — the human final is the test)' : `Test period: ${period.start} -> ${period.endsAt}`) : null,
594
600
  `Finalized by: ${actor}`,
595
601
  verdict.grant ? `Automatic final granted by: release.final-grant -> decision #${verdict.grant.issue}${verdict.grant.ruledBy ? `, ruled by ${verdict.grant.ruledBy}` : ''} (an operator's per-repo grant; deleting it, or final: human, revokes it)` : null,
596
602
  '',
@@ -11,7 +11,7 @@
11
11
  * route: public-tool # none | rapid-app | public-tool | library-fast | deploy-tag | deploy-tag-fast | live
12
12
  * candidates: auto # auto | off
13
13
  * candidates-per-day: 1 # positive integer — an opt-in cap; no route has one by default (#443)
14
- * test-period: 3d # <N>d, never below the route's 3 days
14
+ * test-period: 3d # <N>d, never below the route's 3 days — or 0d where the final is human (#549)
15
15
  * final: auto # auto | human
16
16
  * guard-run: <command> # #422 — a breaking-change detector `release cut --auto` runs
17
17
  * guard-result: <path> # #422 — or the file an earlier CI step wrote its result to
@@ -95,6 +95,8 @@ const FINAL = Object.freeze(['auto', 'human']);
95
95
  // The routes' own test period (CONVENTIONS.md §6: "The test period is 3 days"). A floor, not a
96
96
  // suggestion: a declared period may be longer, never shorter.
97
97
  const TEST_PERIOD_DAYS = 3;
98
+ // #549: the one value below the floor — no test period at all, and only where the final is human.
99
+ const TEST_PERIOD_ZERO = '0d';
98
100
 
99
101
  /**
100
102
  * Each route's own policy — CONVENTIONS.md §6, *Release routes*, row for row.
@@ -369,8 +371,14 @@ function evaluateRelease(cfg) {
369
371
  const days = parseTestPeriod(v);
370
372
  if (days === null) fail(`release.test-period is ${JSON.stringify(v)}, expected a whole number of days like "${TEST_PERIOD_DAYS}d"`);
371
373
  else if (effective.testPeriodDays === null) fail(`release.test-period: ${v} has no period to set — ${route} cuts no candidate, so there is no test period. Remove the key`);
372
- else if (days < effective.testPeriodDays) {
373
- widen('test-period', v, `the test period is ${effective.testPeriodDays}d, and a shorter one finalizes a candidate before the route's own window has passed. Set ${effective.testPeriodDays}d or longer`);
374
+ else if (days === 0 && effective.final === 'human') {
375
+ // #549: a human final may declare no test period — the human's finalize is the test.
376
+ effective.testPeriodDays = 0;
377
+ } else if (days === 0) {
378
+ widen('test-period', v, `the final is automatic here, so the test period is the only look a candidate gets before it becomes a release — no human looked. ${TEST_PERIOD_ZERO} fits only a human final (final: human). Set ${effective.testPeriodDays}d or longer`);
379
+ } else if (days < effective.testPeriodDays) {
380
+ widen('test-period', v, `the test period is ${effective.testPeriodDays}d, and a shorter one finalizes a candidate before the route's own window has passed. Set ${effective.testPeriodDays}d or longer` +
381
+ (effective.final === 'human' ? ` — or ${TEST_PERIOD_ZERO} for no test period, since the final here is a human act` : ''));
374
382
  } else effective.testPeriodDays = days;
375
383
  }
376
384
 
@@ -81,6 +81,18 @@ function excludeLines(env = process.env) {
81
81
  return out;
82
82
  }
83
83
 
84
+ /**
85
+ * #527: the root-anchored exclude line for the worktree subdir (`colab worktree new` creates
86
+ * worktrees INSIDE the clone, `.worktrees/` by default), or null when the configured subdir is
87
+ * absolute or climbs out of the repo. Deliberately NOT part of `excludeLines`: those are scratch
88
+ * (disposable, filtered out of the uncommitted-work gate by `isScratchPath`); a worktree is live
89
+ * work and must never be filtered — it only has to stay out of the main checkout's `git status`,
90
+ * where one habitual `git add -A` would otherwise commit it as an embedded-repo gitlink.
91
+ */
92
+ function worktreeExcludeLine(worktreeSubdir) {
93
+ return anchoredLine(normalise(worktreeSubdir, '.worktrees'));
94
+ }
95
+
84
96
  /**
85
97
  * Is a repo-relative path (as `git status --porcelain` prints it) inside a scratch dir? Used to
86
98
  * keep scratch out of the uncommitted-work gate: a plan or brief left in a worktree is disposable
@@ -102,5 +114,5 @@ function withoutScratch(porcelainText, env = process.env) {
102
114
  module.exports = {
103
115
  DEFAULT_PLANS_DIR, DEFAULT_BRIEFS_DIR, LEGACY_PLANS_DIR, LEGACY_BRIEFS_DIR,
104
116
  plansDirSetting, briefsDirSetting, planWriteDir, briefsWriteDir, planReadDirs,
105
- excludeLines, isScratchPath, withoutScratch,
117
+ excludeLines, worktreeExcludeLine, isScratchPath, withoutScratch,
106
118
  };
@@ -0,0 +1,76 @@
1
+ 'use strict';
2
+ /**
3
+ * #525 — the human door on `colab ship`'s autonomy gate.
4
+ *
5
+ * Without `autonomy: auto-trunk` the gate used to have two answers: docs-only (#345) or refuse.
6
+ * The refusal said "a human must trigger Phase B", but refused that human too, so on the default
7
+ * (`manual`) repo the person meant to give the go had no tool to give it with. Ruling on #525
8
+ * (option 1): a person running `colab ship` IS the go, measured on the bar the CLI already applies
9
+ * to human-only acts (`colab adopt --autonomy`, `colab release finalize`):
10
+ *
11
+ * - an interactive terminal (stdin AND stdout a TTY) outside an agent shell, confirmed by typing
12
+ * at the prompt — `how: 'tty'`; or
13
+ * - `COLAB_HUMAN=1` AND `--answered-by <name>` — `how: 'colab-human'`.
14
+ *
15
+ * An agent never passes on its own: an agent shell (`CLAUDECODE=1` / `AI_AGENT`, the signals
16
+ * `lib/place.js` already reads) does not count as a terminal, and setting `COLAB_HUMAN=1` is
17
+ * governed by the handbook's existing rule — never on the agent's own say-so.
18
+ *
19
+ * Pure: every input is passed in, so the TTY branch is unit-testable without a pty.
20
+ */
21
+
22
+ /** Is this process running inside an agent's shell? Same signals as lib/place.js rule 3. */
23
+ function isAgentShell(env) {
24
+ return env.CLAUDECODE === '1' || !!env.AI_AGENT;
25
+ }
26
+
27
+ /**
28
+ * @returns {{ open: boolean, how: 'tty'|'colab-human'|null, why: string }}
29
+ */
30
+ function humanDoorVerdict({ isTTY, colabHuman, answeredBy, agentShell }) {
31
+ if (colabHuman && answeredBy) {
32
+ return { open: true, how: 'colab-human', why: `COLAB_HUMAN=1, answered by ${answeredBy}` };
33
+ }
34
+ if (colabHuman && !answeredBy) {
35
+ return { open: false, how: null, why: 'COLAB_HUMAN=1 also needs --answered-by "<name>"' };
36
+ }
37
+ if (isTTY && !agentShell) {
38
+ return { open: true, how: 'tty', why: 'a person at an interactive terminal' };
39
+ }
40
+ if (isTTY && agentShell) {
41
+ return { open: false, how: null, why: 'an agent shell is not a person at a terminal' };
42
+ }
43
+ return { open: false, how: null, why: 'unattended (no interactive terminal, no COLAB_HUMAN=1)' };
44
+ }
45
+
46
+ /** Read the door's inputs from a real process. */
47
+ function humanDoorFromProcess(proc, answeredBy) {
48
+ return humanDoorVerdict({
49
+ isTTY: !!(proc.stdin.isTTY && proc.stdout.isTTY),
50
+ colabHuman: proc.env.COLAB_HUMAN === '1',
51
+ answeredBy: answeredBy || null,
52
+ agentShell: isAgentShell(proc.env),
53
+ });
54
+ }
55
+
56
+ /**
57
+ * The exact commands a human runs, for the refusal. `target` is the ship selector the caller
58
+ * used (`--worktree x`, `--branch y`, `--direct`), so the line can be pasted as it stands.
59
+ */
60
+ function humanDoorCommands(selector) {
61
+ const sel = selector ? ` ${selector}` : '';
62
+ return [
63
+ `at your own terminal: colab ship${sel} (asks you to confirm)`,
64
+ `or, non-interactive: COLAB_HUMAN=1 colab ship${sel} --answered-by "<your name>"`,
65
+ ];
66
+ }
67
+
68
+ /** The clause the 🚢 / ✅ evidence comment carries when the human door opened the gate. */
69
+ function humanDoorEvidence(door) {
70
+ if (!door || !door.open) return '';
71
+ return door.how === 'tty'
72
+ ? ' · merged through the human door (#525): a person confirmed at an interactive terminal'
73
+ : ` · merged through the human door (#525): ${door.why}`;
74
+ }
75
+
76
+ module.exports = { isAgentShell, humanDoorVerdict, humanDoorFromProcess, humanDoorCommands, humanDoorEvidence };
@@ -190,10 +190,21 @@ function bodyShaClaims(message) {
190
190
  * an issue that carries no delivery-type label is still covered.
191
191
  */
192
192
  const TOOL_MARKS = ['🔒 Claimed', '✅ Released', '🚢 Shipped', '🔖 Referenced', '↩️ Sent back'];
193
+ /**
194
+ * #535: a comment whose WHOLE body is one signature line (`— <name> · <machine>/<session>`) is
195
+ * not evidence either. Some deployments post one after every comment; it records who spoke, never
196
+ * what was delivered. Only the bare line is excluded — a distill that merely ENDS in a signature
197
+ * still counts, so the test is on the whole trimmed body, single line, no `m` flag.
198
+ */
199
+ const SIGNATURE_ONLY = /^—[^\S\n][^\n]*\S$/;
200
+ function isSignatureOnly(body) {
201
+ return SIGNATURE_ONLY.test(body);
202
+ }
193
203
  function evidenceComments(comments) {
194
204
  return (Array.isArray(comments) ? comments : []).filter((c) => {
195
205
  const body = String((c && c.body) || '').trim();
196
206
  if (!body) return false;
207
+ if (isSignatureOnly(body)) return false;
197
208
  return !TOOL_MARKS.some((mark) => body.startsWith(mark));
198
209
  });
199
210
  }
@@ -312,6 +323,6 @@ function zeroClaimVerdict(issuesCount, branchName, brokenClaimsCount, { remoteOn
312
323
 
313
324
  module.exports = {
314
325
  branchIssueNumbers, commitIssueNumbers, corroborateIssues, branchType,
315
- subjectSanity, bodyShaClaims, evidenceComments, hasEvidence, TOOL_MARKS,
326
+ subjectSanity, bodyShaClaims, evidenceComments, hasEvidence, isSignatureOnly, TOOL_MARKS,
316
327
  closesCoverage, zeroClaimVerdict,
317
328
  };