@futurelastic/colab-handbook 1.13.0-rc.18 → 1.13.0-rc.19
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/README.md +2 -2
- package/README.vi.md +3 -3
- package/package.json +1 -1
- package/tools/colab +26 -1
- package/tools/lib/install-check.js +5 -4
- package/tools/lib/journal.js +3 -0
- package/tools/lib/notify-endpoint.js +114 -59
- package/tools/lib/notify.js +68 -22
package/README.md
CHANGED
|
@@ -304,7 +304,7 @@ one file each — that folder is the source for the table above.
|
|
|
304
304
|
| `--hooks` | Point this clone's git at `.githooks/`: a gitleaks secret scan and an identity scan whose vocabulary you keep outside every repo (see [`templates/README.md`](templates/README.md)). |
|
|
305
305
|
| `--fleet` | Seed `~/.colab/repos.txt` with format notes only, if absent. It stays machine-local because it names your private repos; `colab register` fills it. |
|
|
306
306
|
| `--all` | `--tools --hooks --fleet`. |
|
|
307
|
-
| `--notify-url <url>` |
|
|
307
|
+
| `--notify-url <url>` | Add `<url>` to `notifyUrl` in `~/.colab/config.json` if the key lacks it; an existing entry is never removed or rewritten. See [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
|
|
308
308
|
| `--release` | Check this clone out at the newest final release tag, then install. The default for a first install from a fresh clone. |
|
|
309
309
|
| `--trunk` | Check out `main` and install it, unreleased work included — the clone's `@next`. |
|
|
310
310
|
| `--dry` | Print what would happen, change nothing. Combines with the flags above. |
|
|
@@ -338,7 +338,7 @@ colab update # stamped copies that fell behind, the frozen CLI inclu
|
|
|
338
338
|
plus that engine's own caveats (Codex's sandbox network, for instance). It also reports whether the frozen copy is behind the latest release and
|
|
339
339
|
which commands it does not dispatch, whether the state file exists, whether
|
|
340
340
|
anything is registered, whether both pre-commit hooklets can run, and whether
|
|
341
|
-
`notifyUrl` is unset while a local observer declared
|
|
341
|
+
`notifyUrl` is unset, or lacks a URL, while a local observer declared one. ✗ means
|
|
342
342
|
something installed is stale or unusable; ⚠ means something was never set up,
|
|
343
343
|
which may be deliberate or just not done yet — so a correct fresh install, with
|
|
344
344
|
no repo registered and no identity vocabulary, reports ⚠ rows and exits 0. It
|
package/README.vi.md
CHANGED
|
@@ -303,7 +303,7 @@ mỗi engine một file — thư mục đó là nguồn của bảng trên.
|
|
|
303
303
|
| `--hooks` | Trỏ git của clone này vào `.githooks/`: quét secret bằng gitleaks, và quét danh tính với danh sách từ khoá do bạn giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). |
|
|
304
304
|
| `--fleet` | Tạo `~/.colab/repos.txt` chỉ chứa ghi chú định dạng, nếu chưa có. Nó cố tình nằm trên máy vì nó ghi tên các repo private của bạn; `colab register` mới là thứ điền vào. |
|
|
305
305
|
| `--all` | `--tools --hooks --fleet`. |
|
|
306
|
-
| `--notify-url <url>` |
|
|
306
|
+
| `--notify-url <url>` | Thêm `<url>` vào `notifyUrl` trong `~/.colab/config.json` nếu khoá đó chưa có URL này; không bao giờ xoá hay ghi đè mục đã có. Xem [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
|
|
307
307
|
| `--release` | Checkout clone này về tag phát hành chính thức mới nhất, rồi cài. Là mặc định cho lần cài đầu từ một bản clone mới. |
|
|
308
308
|
| `--trunk` | Checkout `main` rồi cài, kể cả phần chưa phát hành — `@next` của bản clone. |
|
|
309
309
|
| `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với các flag trên. |
|
|
@@ -335,8 +335,8 @@ colab update # các bản copy có đóng dấu đã tụt lại, k
|
|
|
335
335
|
`--check` báo theo từng engine: bao nhiêu skill đã link, thiếu hay hỏng, kèm
|
|
336
336
|
các lưu ý riêng của engine đó (ví dụ mạng trong sandbox của Codex). Nó cũng báo bản đóng băng có tụt sau bản phát hành mới nhất không và lệnh nào
|
|
337
337
|
nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
|
|
338
|
-
hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống
|
|
339
|
-
khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
|
|
338
|
+
hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống (hoặc
|
|
339
|
+
thiếu một URL) trong khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
|
|
340
340
|
hoặc không dùng được; ⚠ nghĩa là có thứ chưa từng được cài, có thể là cố ý hoặc
|
|
341
341
|
chỉ là chưa làm tới — nên một bản cài mới đúng, chưa đăng ký repo nào và chưa có
|
|
342
342
|
danh sách từ khoá danh tính, sẽ ra các dòng ⚠ và exit 0. Nó không bao giờ tự làm
|
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -7601,7 +7601,7 @@ function cmdLabels(argv) {
|
|
|
7601
7601
|
// config (show / manage the aggregation inputs)
|
|
7602
7602
|
// ---------------------------------------------------------------------------
|
|
7603
7603
|
|
|
7604
|
-
const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reserved-file <path>|rm-reserved-file <path>|set <key> <value>]
|
|
7604
|
+
const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reserved-file <path>|rm-reserved-file <path>|add-notify-url <url>|rm-notify-url <url>|set <key> <value>]
|
|
7605
7605
|
|
|
7606
7606
|
show print resolved config, file paths, and the aggregated reserved set
|
|
7607
7607
|
add-repo <path> add a repo root to scan for .github/project.yml reserved ports
|
|
@@ -7609,6 +7609,9 @@ const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reser
|
|
|
7609
7609
|
add-reserved-file <path> add a machine-local reserved-ports file (~ is expanded); its ports join
|
|
7610
7610
|
the reserved set (lenient parse: whitespace ints per line, # comments)
|
|
7611
7611
|
rm-reserved-file <path> remove a reserved-ports file
|
|
7612
|
+
add-notify-url <url> add one more event receiver to notifyUrl (a second local observer) —
|
|
7613
|
+
existing entries are kept; one URL stays stored as a plain string
|
|
7614
|
+
rm-notify-url <url> remove one receiver from notifyUrl; removing the last unsets the key
|
|
7612
7615
|
set <key> <value> set claimTTLHours | plannerClaimTTLMinutes | portRange | worktreeSubdir | notifyUrl | journal |
|
|
7613
7616
|
claimIdentity
|
|
7614
7617
|
|
|
@@ -7617,6 +7620,9 @@ an http(s) endpoint and claim / release / ship / worktree new / worktree rm each
|
|
|
7617
7620
|
best-effort JSON event as they succeed — fire-and-forget, never retried, never able to fail or slow
|
|
7618
7621
|
the command that triggered it. Observers already poll this state file; the push only sharpens the
|
|
7619
7622
|
timestamp. Unset it again with: colab config set notifyUrl ""
|
|
7623
|
+
notifyUrl may hold SEVERAL receivers (#546) — every event goes to each, through its own detached
|
|
7624
|
+
child, so one dead receiver never costs another its event. \`set notifyUrl <url>\` replaces the
|
|
7625
|
+
whole value with one URL; add-notify-url / rm-notify-url change one entry and leave the rest alone.
|
|
7620
7626
|
|
|
7621
7627
|
journal is OPTIONAL and off by default: unset, colab writes no journal file at all. Set it and every
|
|
7622
7628
|
state transition and every invocation is appended to ~/.colab/journal.jsonl — one JSON object per
|
|
@@ -7673,6 +7679,25 @@ function cmdConfig(argv) {
|
|
|
7673
7679
|
cfg.reservedFiles = (cfg.reservedFiles || []).filter((f) => f !== argv[1]);
|
|
7674
7680
|
state.saveConfig(cfg); print(`reservedFiles: ${cfg.reservedFiles.join(', ') || '(none)'}`); return 0;
|
|
7675
7681
|
}
|
|
7682
|
+
if (sub === 'add-notify-url' || sub === 'rm-notify-url') {
|
|
7683
|
+
// #546: notifyUrl is a string or a list. These change ONE entry and leave every other exactly as
|
|
7684
|
+
// it was, so a second observer is added without hand-editing JSON and without rewriting the first.
|
|
7685
|
+
const u = (argv[1] || '').trim();
|
|
7686
|
+
if (!u) throw new UserError(`${sub} needs a URL — try: colab config ${sub} http://127.0.0.1:<port>/api/events`);
|
|
7687
|
+
const urls = notify.configuredUrls(cfg);
|
|
7688
|
+
if (sub === 'add-notify-url') {
|
|
7689
|
+
if (!/^https?:\/\//i.test(u)) throw new UserError(`notifyUrl must be an http(s) URL — try: colab config add-notify-url http://${u.replace(/^[a-z]+:\/\//i, '')}`);
|
|
7690
|
+
if (!urls.includes(u)) urls.push(u);
|
|
7691
|
+
} else {
|
|
7692
|
+
if (!urls.includes(u)) throw new UserError(`notifyUrl has no entry ${u} — see the entries with: colab config show`);
|
|
7693
|
+
urls.splice(urls.indexOf(u), 1);
|
|
7694
|
+
}
|
|
7695
|
+
const v = notify.storedNotifyUrl(urls);
|
|
7696
|
+
if (v === undefined) delete cfg.notifyUrl; else cfg.notifyUrl = v;
|
|
7697
|
+
state.saveConfig(cfg);
|
|
7698
|
+
print(`notifyUrl = ${urls.length ? urls.join(', ') : '(unset)'}`);
|
|
7699
|
+
return 0;
|
|
7700
|
+
}
|
|
7676
7701
|
if (sub === 'set') {
|
|
7677
7702
|
const [k, v] = [argv[1], argv[2]];
|
|
7678
7703
|
if (!k || v === undefined) throw new UserError('set needs <key> <value>');
|
|
@@ -306,10 +306,11 @@ function checkNotify({ colabHome }) {
|
|
|
306
306
|
try { cfg = JSON.parse(readText(path.join(colabHome, 'config.json')) || '{}'); } catch (_) { /* reported by colab itself */ }
|
|
307
307
|
const st = notifyEndpoint.status(cfg, colabHome);
|
|
308
308
|
if (st.state === 'unset') return [];
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
return
|
|
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(', ')}` }];
|
|
313
314
|
}
|
|
314
315
|
|
|
315
316
|
function runChecks(opts) {
|
package/tools/lib/journal.js
CHANGED
|
@@ -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.
|
|
19
|
-
*
|
|
20
|
-
*
|
|
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
|
|
24
|
-
*
|
|
25
|
-
*
|
|
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
|
|
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
|
|
52
|
-
* `{ file,
|
|
53
|
-
*
|
|
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
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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; `
|
|
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
|
|
89
|
+
const urls = configuredUrls(cfg);
|
|
78
90
|
const declared = readDeclared(colabHome);
|
|
79
|
-
if (
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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
|
-
/**
|
|
90
|
-
function
|
|
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
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
if (st.state === 'declared-invalid') {
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
if (st.state === 'set'
|
|
99
|
-
|
|
100
|
-
|
|
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
|
-
|
|
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,
|
|
107
|
-
* action 'keep' the key is
|
|
108
|
-
* action 'seed'
|
|
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 =
|
|
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
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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
|
-
|
|
158
|
-
if (
|
|
159
|
-
|
|
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
|
-
|
|
162
|
-
|
|
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
|
-
|
|
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 };
|
package/tools/lib/notify.js
CHANGED
|
@@ -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
|
|
149
|
-
* about the send is reported to the user, because a warning about a
|
|
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
|
|
154
|
-
* 'sent' handed to
|
|
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
|
|
165
|
-
if (
|
|
166
|
-
|
|
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
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
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 };
|