@futurelastic/colab-handbook 1.13.0-rc.9 → 1.13.0

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.
@@ -27,6 +27,7 @@ const path = require('path');
27
27
  const { execFileSync } = require('child_process');
28
28
  const stamp = require('./stamp');
29
29
  const notifyEndpoint = require('./notify-endpoint');
30
+ const engines = require('./engines');
30
31
 
31
32
  const OK = 'ok';
32
33
  const WARN = 'warn';
@@ -141,6 +142,75 @@ function checkFrozen({ root, colabHome }) {
141
142
  return rows;
142
143
  }
143
144
 
145
+ /**
146
+ * The skills, per engine (#530). For every engine in engines/ with a folder of its own, plus every
147
+ * folder an earlier --skills-dir remembered: how many of this clone's skills are linked there, which
148
+ * are missing (a skill added since the install — re-run it), which links are broken (they point into
149
+ * this clone's skills/ at a folder that no longer exists — ✗, installed and now unusable), and which
150
+ * names something else holds (⚠, possibly a deliberate local variant; install.sh never clobbers it).
151
+ *
152
+ * An engine with nothing linked is "not installed for it" — one ✓ line naming them, because a
153
+ * Claude-only machine is a correct machine. Only when NO engine has the skills is that a ⚠.
154
+ * The engine's own `caveat:` lines become ⚠ rows while it is installed: they are what the user must
155
+ * do there for the skills to work (a sandbox with no network, say), and they stay true until done.
156
+ */
157
+ function checkSkills({ root, home, colabHome }) {
158
+ const src = path.join(root, 'skills');
159
+ let skills = [];
160
+ try { skills = fs.readdirSync(src, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort(); } catch (_) { /* none */ }
161
+ const all = engines.listEngines(root);
162
+ const byId = Object.fromEntries(all.map((e) => [e.id, e]));
163
+ const targets = all.filter((e) => e.skills_dir).map((e) => ({ e, dir: engines.expandHome(e.skills_dir, home) }));
164
+ for (const dir of engines.rememberedDirs(colabHome)) {
165
+ if (!targets.some((t) => t.dir === dir)) targets.push({ e: byId.generic || { id: 'generic', label: 'another engine', note: [], caveat: [] }, dir });
166
+ }
167
+
168
+ const rows = [];
169
+ const notInstalled = [];
170
+ for (const { e, dir } of targets) {
171
+ const linked = []; const missing = []; const broken = []; const foreign = [];
172
+ for (const name of skills) {
173
+ const dest = path.join(dir, name);
174
+ let st;
175
+ try { st = fs.lstatSync(dest); } catch (_) { missing.push(name); continue; }
176
+ if (!st.isSymbolicLink()) { foreign.push(name); continue; }
177
+ const to = path.resolve(dir, fs.readlinkSync(dest));
178
+ if (to === path.join(src, name)) linked.push(name);
179
+ else foreign.push(name);
180
+ }
181
+ // Links into this clone's skills/ whose target is gone: a skill removed or renamed upstream.
182
+ let entries = [];
183
+ try { entries = fs.readdirSync(dir); } catch (_) { /* folder absent */ }
184
+ for (const n of entries) {
185
+ const p = path.join(dir, n);
186
+ try {
187
+ if (!fs.lstatSync(p).isSymbolicLink()) continue;
188
+ const to = path.resolve(dir, fs.readlinkSync(p));
189
+ if (to.startsWith(src + path.sep) && !fs.existsSync(to)) broken.push(n);
190
+ } catch (_) { /* unreadable entry — not ours to judge */ }
191
+ }
192
+ const who = `${e.id} (${e.label || e.id}) ${dir}`;
193
+ if (!linked.length && !broken.length) { notInstalled.push(e.id === 'generic' ? dir : `${e.id} (${e.label || e.id})`); continue; }
194
+ const parts = [`${linked.length}/${skills.length} linked`];
195
+ if (missing.length) parts.push(`missing ${missing.join(', ')} — re-run ./install.sh${e.id === 'generic' ? '' : ` --engine ${e.id}`}`);
196
+ if (foreign.length) parts.push(`held by something else (left as is): ${foreign.join(', ')}`);
197
+ if (broken.length) parts.push(`BROKEN links to skills that no longer exist: ${broken.join(', ')} — remove them: ${broken.map((b) => `rm '${path.join(dir, b)}'`).join('; ')}`);
198
+ rows.push({
199
+ area: 'skills',
200
+ severity: broken.length ? FAIL : (missing.length || foreign.length) ? WARN : OK,
201
+ text: `${who}: ${parts.join('; ')}`,
202
+ });
203
+ for (const c of e.caveat || []) rows.push({ area: 'skills', severity: WARN, text: `${e.id}: ${c}` });
204
+ if (e.verified && /^no\b/.test(e.verified)) rows.push({ area: 'skills', severity: WARN, text: `${e.id}: engine file not verified by a run yet — ${e.verified.replace(/^no\s*[—-]?\s*/, '')}` });
205
+ }
206
+ if (!rows.length) {
207
+ rows.push({ area: 'skills', severity: WARN, text: `not linked for any engine — ./install.sh asks which (or --engine <id> / --skills-dir <path>)` });
208
+ } else if (notInstalled.length) {
209
+ rows.push({ area: 'skills', severity: OK, text: `not installed for: ${notInstalled.join(', ')} — fine if deliberate; ./install.sh --engine <id> adds one` });
210
+ }
211
+ return rows;
212
+ }
213
+
144
214
  /** The state file. The CLI creates it lazily, so a consumer reading it early saw an error, not an empty fleet. */
145
215
  function checkState({ root, colabHome, home }) {
146
216
  const file = path.join(colabHome, 'state.json');
@@ -236,15 +306,17 @@ function checkNotify({ colabHome }) {
236
306
  try { cfg = JSON.parse(readText(path.join(colabHome, 'config.json')) || '{}'); } catch (_) { /* reported by colab itself */ }
237
307
  const st = notifyEndpoint.status(cfg, colabHome);
238
308
  if (st.state === 'unset') return [];
239
- if (st.state === 'set' && !st.declared) {
240
- return [{ area: 'notify', severity: OK, text: `notifyUrl = ${st.url}` }];
241
- }
242
- return [{ area: 'notify', severity: WARN, text: notifyEndpoint.healthLine(st) }];
309
+ // One ⚠ row per problem — each declared URL the key lacks is its own row (#546), so a machine
310
+ // running two observers sees which one is going without, not a single blended line.
311
+ const problems = notifyEndpoint.healthLines(st);
312
+ if (problems.length) return problems.map((text) => ({ area: 'notify', severity: WARN, text }));
313
+ return [{ area: 'notify', severity: OK, text: `notifyUrl = ${st.urls.join(', ')}` }];
243
314
  }
244
315
 
245
316
  function runChecks(opts) {
246
317
  const o = { env: process.env, ...opts };
247
318
  return [
319
+ ...checkSkills(o),
248
320
  checkLink(o),
249
321
  ...checkFrozen(o),
250
322
  checkState(o),
@@ -280,5 +352,5 @@ if (require.main === module) {
280
352
 
281
353
  module.exports = {
282
354
  OK, WARN, FAIL,
283
- dispatchedCommands, checkLink, checkFrozen, checkState, checkFleet, checkHooks, checkNotify, runChecks, render,
355
+ dispatchedCommands, checkSkills, checkLink, checkFrozen, checkState, checkFleet, checkHooks, checkNotify, runChecks, render,
284
356
  };
@@ -392,6 +392,9 @@ function repoRootOf(dir) {
392
392
  function safeArgv(argv) {
393
393
  const a = (argv || []).map(String);
394
394
  if (a[0] === 'config' && a[1] === 'set' && a.length > 3) return [...a.slice(0, 3), '<redacted>'];
395
+ // add-notify-url / rm-notify-url carry the same kind of value as `set notifyUrl` — a URL that can
396
+ // hold a token (#546) — so it is redacted the same way.
397
+ if (a[0] === 'config' && (a[1] === 'add-notify-url' || a[1] === 'rm-notify-url') && a.length > 2) return [...a.slice(0, 2), '<redacted>'];
395
398
  return a;
396
399
  }
397
400
 
@@ -15,17 +15,20 @@
15
15
  *
16
16
  * 1. an explicit URL a human passes to `install.sh --notify-url <url>`;
17
17
  * 2. the DECLARED ENDPOINT FILE, `<COLAB_HOME>/notify-endpoint` — the convention by which a local
18
- * observer announces itself. The observer writes its own events URL there (one http(s) URL on
19
- * the first non-comment line); colab only reads it. No port is probed and no well-known URL is
20
- * hard-coded: an observer's address is the observer's fact, not the handbook's.
18
+ * observer announces itself. Each observer writes its own events URL there on its OWN line (one
19
+ * http(s) URL per non-comment line, #546 — a machine may run two observers side by side, and
20
+ * neither may overwrite the other's line); colab only reads it. A one-line file is the
21
+ * one-observer case and stays valid. No port is probed and no well-known URL is hard-coded: an
22
+ * observer's address is the observer's fact, not the handbook's.
21
23
  *
22
24
  * What reads this:
23
- * - install.sh seeds `notifyUrl` from (1), else (2), ONLY when the key is absent — an existing
24
- * value is someone's deliberate choice and is never overwritten. When nothing seeds it, install
25
- * says plainly that the key is unset and what that costs.
25
+ * - install.sh ADDS to `notifyUrl` every URL from (1) and (2) that the key lacks, and never
26
+ * removes or rewrites an entry already there — an existing value is someone's deliberate choice.
27
+ * With one URL the key is written as a plain string, exactly as before the list form (#546).
28
+ * When nothing seeds it, install says plainly that the key is unset and what that costs.
26
29
  * - `install.sh --check` and `colab doctor` report `notifyUrl: unset` when (2) exists and the key
27
- * does not. No declared endpoint → nothing is reported: silence stays right for a machine with
28
- * no observer.
30
+ * does not, and name EACH declared URL the key lacks when it is set. No declared endpoint →
31
+ * nothing is reported: silence stays right for a machine with no observer.
29
32
  *
30
33
  * CommonJS, zero dependencies. Runnable as a script (install.sh's entry):
31
34
  * node tools/lib/notify-endpoint.js seed --colab-home <dir> [--url <url>] [--dry]
@@ -36,6 +39,7 @@
36
39
 
37
40
  const fs = require('fs');
38
41
  const path = require('path');
42
+ const { configuredUrls, storedNotifyUrl } = require('./notify');
39
43
 
40
44
  const ENDPOINT_FILE = 'notify-endpoint';
41
45
  const HTTP_RE = /^https?:\/\//i;
@@ -48,84 +52,113 @@ function endpointFile(colabHome) {
48
52
  }
49
53
 
50
54
  /**
51
- * Read the declared endpoint. Returns null when no file exists (the common, silent case), else
52
- * `{ file, url }` for a usable URL or `{ file, invalid }` naming what is wrong with it — a declared
53
- * endpoint that cannot be used is reported, never silently treated as absent.
55
+ * Read the declared endpoints. Returns null when no file exists (the common, silent case), else
56
+ * `{ file, urls, bad }`: every usable URL in file order (deduplicated), and every non-comment line
57
+ * that is not one. When no line is usable it also carries `invalid`, naming what is wrong — a
58
+ * declared endpoint that cannot be used is reported, never silently treated as absent. `url` is the
59
+ * first usable URL, kept for readers that predate the list form.
54
60
  */
55
61
  function readDeclared(colabHome) {
56
62
  const file = endpointFile(colabHome);
57
63
  let raw;
58
64
  try { raw = fs.readFileSync(file, 'utf8'); } catch (_) { return null; }
59
- const line = raw.split(/\r?\n/).map((l) => l.replace(/#.*$/, '').trim()).find(Boolean);
60
- if (!line) return { file, invalid: 'empty — no URL on any non-comment line' };
61
- if (!HTTP_RE.test(line)) return { file, invalid: `not an http(s) URL: ${line}` };
62
- return { file, url: line };
63
- }
64
-
65
- function configuredUrl(cfg) {
66
- return cfg && typeof cfg.notifyUrl === 'string' ? cfg.notifyUrl.trim() : '';
65
+ const lines = raw.split(/\r?\n/).map((l) => l.replace(/#.*$/, '').trim()).filter(Boolean);
66
+ const urls = [];
67
+ const bad = [];
68
+ for (const l of lines) {
69
+ if (!HTTP_RE.test(l)) bad.push(l);
70
+ else if (!urls.includes(l)) urls.push(l);
71
+ }
72
+ if (urls.length === 0) {
73
+ const invalid = lines.length === 0 ? 'empty — no URL on any non-comment line' : `not an http(s) URL: ${bad[0]}`;
74
+ return { file, urls, bad, invalid };
75
+ }
76
+ return { file, urls, bad, url: urls[0] };
67
77
  }
68
78
 
69
79
  /**
70
80
  * The read-only verdict both health checks print. `state`:
71
- * 'set' notifyUrl is configured (payload: url; `declared` when the file names another)
81
+ * 'set' notifyUrl is configured (payload: url, urls; `missing` lists each declared URL
82
+ * the key lacks — the observers that receive nothing — empty when none)
72
83
  * 'unset-declared' notifyUrl absent while an observer declared an endpoint — the outage case
73
84
  * 'declared-invalid' notifyUrl absent and the declared file is unusable
74
85
  * 'unset' neither — a machine with no observer; callers stay silent
86
+ * `declared` rides along whenever the file exists.
75
87
  */
76
88
  function status(cfg, colabHome) {
77
- const url = configuredUrl(cfg);
89
+ const urls = configuredUrls(cfg);
78
90
  const declared = readDeclared(colabHome);
79
- if (url) {
80
- return declared && declared.url && declared.url !== url
81
- ? { state: 'set', url, declared }
82
- : { state: 'set', url };
91
+ if (urls.length) {
92
+ const st = { state: 'set', url: urls[0], urls, missing: declared ? declared.urls.filter((u) => !urls.includes(u)) : [] };
93
+ if (declared) st.declared = declared;
94
+ return st;
83
95
  }
84
96
  if (!declared) return { state: 'unset' };
85
97
  if (declared.invalid) return { state: 'declared-invalid', declared };
86
98
  return { state: 'unset-declared', declared };
87
99
  }
88
100
 
89
- /** One human line for a status, or null when the right output is silence. */
90
- function healthLine(st) {
101
+ /** The fix command for one or several URLs a key lacks. One URL on an unset key: the same `set` as ever. */
102
+ function fixFor(urls, keyIsSet) {
103
+ if (!keyIsSet && urls.length === 1) return `colab config set notifyUrl ${urls[0]}`;
104
+ return urls.map((u) => `colab config add-notify-url ${u}`).join(' && ');
105
+ }
106
+
107
+ /** Human lines for a status — one per problem — or [] when the right output is silence. */
108
+ function healthLines(st) {
109
+ const out = [];
110
+ const d = st.declared;
91
111
  if (st.state === 'unset-declared') {
92
- return `notifyUrl: unset — ${st.declared.file} declares a local observer at ${st.declared.url}, ` +
93
- `which receives no events (${PUSH_ONLY_KINDS.join(', ')}). Fix: colab config set notifyUrl ${st.declared.url}`;
94
- }
95
- if (st.state === 'declared-invalid') {
96
- return `notifyUrl: unset — ${st.declared.file} is ${st.declared.invalid}, so nothing could be seeded from it`;
97
- }
98
- if (st.state === 'set' && st.declared) {
99
- return `notifyUrl: ${st.url} — differs from the endpoint declared in ${st.declared.file} (${st.declared.url}); ` +
100
- 'left as configured, check which one the local observer listens on';
112
+ const where = d.urls.length === 1 ? `a local observer at ${d.urls[0]}, which receives` : `${d.urls.length} local observers (${d.urls.join(', ')}), which receive`;
113
+ out.push(`notifyUrl: unset — ${d.file} declares ${where} no events (${PUSH_ONLY_KINDS.join(', ')}). ` +
114
+ `Fix: ${fixFor(d.urls, false)}`);
115
+ } else if (st.state === 'declared-invalid') {
116
+ out.push(`notifyUrl: unset — ${d.file} is ${d.invalid}, so nothing could be seeded from it`);
117
+ return out;
118
+ } else if (st.state === 'set') {
119
+ for (const u of st.missing || []) {
120
+ out.push(`notifyUrl: lacks ${u} — declared in ${d.file} by a local observer, which receives no events ` +
121
+ `(${PUSH_ONLY_KINDS.join(', ')}). Fix: ${fixFor([u], true)}`);
122
+ }
101
123
  }
102
- return null;
124
+ for (const b of (d && d.bad) || []) out.push(`notifyUrl: ${d.file} has a line that is not an http(s) URL — ignored: ${b}`);
125
+ return out;
126
+ }
127
+
128
+ /** The lines above joined, or null when the right output is silence. Kept for one-string readers. */
129
+ function healthLine(st) {
130
+ const lines = healthLines(st);
131
+ return lines.length ? lines.join('\n') : null;
103
132
  }
104
133
 
105
134
  /**
106
- * Decide what install.sh does. Pure: returns `{ action, url?, source?, lines[] }` and writes nothing.
107
- * action 'keep' the key is already set — never overwritten
108
- * action 'seed' write `url` (from the flag, else the declared file)
135
+ * Decide what install.sh does. Pure: returns `{ action, add?, lines[] }` and writes nothing.
136
+ * action 'keep' the key already holds every URL there is to add — left exactly as it is
137
+ * action 'seed' add each `{ url, source }` in `add` (from the flag and the declared file) that the
138
+ * key lacks; existing entries are never removed or rewritten
109
139
  * action 'none' nothing to seed — the lines say plainly the key is unset and what it costs
140
+ * action 'error' a non-http --notify-url
141
+ * The flag is one more "an observer lives here" source, added beside the declared ones rather than
142
+ * winning over them: since #546 a second receiver is an addition, never a replacement.
110
143
  */
111
144
  function plan({ cfg, colabHome, flagUrl }) {
112
- const current = configuredUrl(cfg);
145
+ const current = configuredUrls(cfg);
113
146
  const declared = readDeclared(colabHome);
114
147
  if (flagUrl && !HTTP_RE.test(flagUrl)) {
115
148
  return { action: 'error', lines: [`--notify-url must be an http(s) URL, got: ${flagUrl}`] };
116
149
  }
117
- if (current) {
118
- const lines = [`✓ notifyUrl = ${current} (already set → left untouched)`];
119
- if (flagUrl && flagUrl !== current) {
120
- lines.push(`⚠ --notify-url ${flagUrl} NOT applied: an existing value is never overwritten. ` +
121
- `To change it: colab config set notifyUrl ${flagUrl}`);
122
- }
123
- const hl = healthLine(status(cfg, colabHome));
124
- if (hl) lines.push(`⚠ ${hl}`);
125
- return { action: 'keep', lines };
150
+ const candidates = [];
151
+ if (flagUrl) candidates.push({ url: flagUrl, source: '--notify-url' });
152
+ for (const u of (declared && declared.urls) || []) candidates.push({ url: u, source: declared.file });
153
+ const add = [];
154
+ for (const c of candidates) {
155
+ if (!current.includes(c.url) && !add.some((a) => a.url === c.url)) add.push(c);
156
+ }
157
+ const badLines = ((declared && declared.bad) || []).map((b) => `⚠ ${declared.file} has a line that is not an http(s) URL — ignored: ${b}`);
158
+ if (add.length) return { action: 'seed', add, lines: badLines };
159
+ if (current.length) {
160
+ return { action: 'keep', lines: [`✓ notifyUrl = ${current.join(', ')} (already set → left untouched)`, ...badLines] };
126
161
  }
127
- if (flagUrl) return { action: 'seed', url: flagUrl, source: '--notify-url', lines: [] };
128
- if (declared && declared.url) return { action: 'seed', url: declared.url, source: declared.file, lines: [] };
129
162
  const lines = [];
130
163
  if (declared && declared.invalid) lines.push(`⚠ ${declared.file} is ${declared.invalid} — ignored.`);
131
164
  lines.push(
@@ -137,6 +170,16 @@ function plan({ cfg, colabHome, flagUrl }) {
137
170
  return { action: 'none', lines };
138
171
  }
139
172
 
173
+ /**
174
+ * The config value after adding `add` to `cfg`'s current list — existing entries first, untouched and
175
+ * in order, new ones appended. Pure; used by the seed entry right before it writes.
176
+ */
177
+ function merged(cfg, add) {
178
+ const urls = configuredUrls(cfg);
179
+ for (const a of add) if (!urls.includes(a.url)) urls.push(a.url);
180
+ return storedNotifyUrl(urls);
181
+ }
182
+
140
183
  function main(argv) {
141
184
  const sub = argv[0];
142
185
  const val = (flag) => {
@@ -154,17 +197,29 @@ function main(argv) {
154
197
  const p = plan({ cfg, colabHome, flagUrl: val('--url') });
155
198
  const out = (l) => process.stdout.write(` ${l}\n`);
156
199
  if (p.action === 'error') { process.stderr.write(` ✗ ${p.lines[0]}\n`); return 2; }
157
- if (p.action !== 'seed') { p.lines.forEach(out); return 0; }
158
- if (argv.includes('--dry')) { out(`[dry] seed notifyUrl = ${p.url} (from ${p.source})`); return 0; }
159
- // Re-read inside the write: a key set between plan and write is still never overwritten.
200
+ p.lines.forEach(out);
201
+ if (p.action !== 'seed') return 0;
202
+ const hadAny = configuredUrls(cfg).length > 0;
203
+ if (argv.includes('--dry')) {
204
+ for (const a of p.add) out(`[dry] ${hadAny ? 'add to' : 'seed'} notifyUrl ${a.url} (from ${a.source})`);
205
+ return 0;
206
+ }
207
+ // Re-read inside the write: an entry added between plan and write is kept, never rewritten or
208
+ // removed, and a URL someone else just added is not added twice.
160
209
  const fresh = state.loadConfig();
161
- if (configuredUrl(fresh)) { out(`✓ notifyUrl = ${configuredUrl(fresh)} (already set → left untouched)`); return 0; }
162
- fresh.notifyUrl = p.url;
210
+ const before = configuredUrls(fresh);
211
+ const add = p.add.filter((a) => !before.includes(a.url));
212
+ if (!add.length) { out(`✓ notifyUrl = ${before.join(', ')} (already set → left untouched)`); return 0; }
213
+ fresh.notifyUrl = merged(fresh, add);
163
214
  state.saveConfig(fresh);
164
- out(`📡 notifyUrl seeded: ${p.url} (from ${p.source}) — colab now pushes its events there`);
215
+ for (const a of add) {
216
+ out(before.length
217
+ ? `📡 notifyUrl: added ${a.url} (from ${a.source}) — existing entries left untouched`
218
+ : `📡 notifyUrl seeded: ${a.url} (from ${a.source}) — colab now pushes its events there`);
219
+ }
165
220
  return 0;
166
221
  }
167
222
 
168
223
  if (require.main === module) process.exitCode = main(process.argv.slice(2));
169
224
 
170
- module.exports = { ENDPOINT_FILE, PUSH_ONLY_KINDS, endpointFile, readDeclared, status, healthLine, plan, main };
225
+ module.exports = { ENDPOINT_FILE, PUSH_ONLY_KINDS, endpointFile, readDeclared, status, healthLines, healthLine, plan, merged, main };
@@ -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) {