@futurelastic/colab-handbook 1.12.0-rc.10 → 1.12.0-rc.11

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 CHANGED
@@ -187,6 +187,7 @@ you want.
187
187
  | `--hooks` | Point this clone's git at `.githooks/`, whose `pre-commit` runs every check in `pre-commit.d/` — a gitleaks secret scan, and an identity scan that needs a vocabulary you supply by path and keep outside every repo (see [`templates/README.md`](templates/README.md)). `core.hooksPath` lives in `.git/config`, so it is per-clone, per-machine, and never travels with the repo. |
188
188
  | `--fleet` | Seed `~/.colab/repos.txt` from `audit/repos.txt`, only if it is absent. The seed is format notes and commented placeholders — it registers **nothing**; `colab register <path>` (step 3) is what fills it. That list stays machine-local on purpose: it names your private repos, and this repo is public. |
189
189
  | `--all` | `--tools --hooks --fleet`. |
190
+ | `--notify-url <url>` | Seed `notifyUrl` in `~/.colab/config.json` with a local observer's events URL, only when the key is absent — an existing value is never overwritten. Without the flag, `--tools` seeds it from `~/.colab/notify-endpoint` when a local observer declared its URL there, and otherwise prints that `notifyUrl` is unset and which events that drops. See [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
190
191
  | `--dry` | Print what would happen, change nothing. Combines with all of the above. |
191
192
  | `--check` | **Read-only** health report on what an earlier install left behind — see *Checking an install* below. Takes no other flag; exit 1 on any ✗ row. |
192
193
 
@@ -246,8 +247,9 @@ A frozen copy never breaks — it gets **old**, and an old complete copy answers
246
247
  normally for every command it knows until something asks for one added after it
247
248
  was frozen. `--check` is the report nothing else gives: whether the frozen copy is
248
249
  behind the latest release, **which commands it does not dispatch**, whether the
249
- state file exists, whether anything is registered, and whether both pre-commit
250
- hooklets can actually run (gitleaks, and the identity vocabulary). ✗ means
250
+ state file exists, whether anything is registered, whether both pre-commit
251
+ hooklets can actually run (gitleaks, and the identity vocabulary), and whether
252
+ `notifyUrl` is unset while a local observer declared an endpoint. ✗ means
251
253
  something installed here is stale or unusable; ⚠ means something was never set
252
254
  up, which may be deliberate. It never refreshes anything — re-freezing stays your
253
255
  call: `./install.sh --tools`.
package/README.vi.md CHANGED
@@ -185,6 +185,7 @@ nếu bạn thật sự chỉ cần bấy nhiêu.
185
185
  | `--hooks` | Trỏ git của clone này vào `.githooks/`, ở đó `pre-commit` chạy lần lượt mọi check trong `pre-commit.d/` — quét secret bằng gitleaks, và quét danh tính (identity) vốn cần một danh sách từ khoá do bạn cấp bằng đường dẫn và giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). `core.hooksPath` nằm trong `.git/config` nên là cấu hình per-clone, per-máy, không đi theo repo. |
186
186
  | `--fleet` | Tạo `~/.colab/repos.txt` từ `audit/repos.txt`, chỉ khi file chưa tồn tại. Danh sách đó cố tình nằm ngoài repo: nó ghi tên các repo private của bạn, còn repo này thì public. |
187
187
  | `--all` | `--tools --hooks --fleet`. |
188
+ | `--notify-url <url>` | Ghi `notifyUrl` vào `~/.colab/config.json` bằng URL nhận event của một observer chạy trên máy, chỉ khi khoá đó chưa có — giá trị đang có không bao giờ bị ghi đè. Không truyền flag thì `--tools` lấy URL từ `~/.colab/notify-endpoint` nếu observer trên máy đã khai ở đó; không có thì in rõ `notifyUrl` đang trống và sẽ mất những event nào. Xem [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
188
189
  | `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với mọi flag trên. |
189
190
 
190
191
  **Service luôn-bật phải gọi `~/.colab/bin/colab`.** Bản CLI symlink chạy theo
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.10"
30
+ "version": "1.12.0-rc.11"
31
31
  }
package/tools/colab CHANGED
@@ -22,6 +22,7 @@ const squash = require('./lib/squash');
22
22
  const procs = require('./lib/procs');
23
23
  const landed = require('./lib/landed');
24
24
  const notify = require('./lib/notify');
25
+ const notifyEndpoint = require('./lib/notify-endpoint'); // #414
25
26
  const journal = require('./lib/journal');
26
27
  const labels = require('./lib/labels');
27
28
  const records = require('./lib/records');
@@ -5713,6 +5714,11 @@ claims from.
5713
5714
  "contained in trunk" between releases BY CONSTRUCTION, which this heuristic would otherwise
5714
5715
  misread as spent and advise deleting, silently breaking GitOps deploys (#63).
5715
5716
 
5717
+ - \`notifyUrl: unset\` is reported (read-only, never pruned, not part of the verdict) when a
5718
+ local observer declared its events URL in <COLAB_HOME>/notify-endpoint and notifyUrl is not
5719
+ set — that observer then receives no issue.merged / issue.closed / readiness.marked /
5720
+ gate.recorded event (#414). No declared endpoint, no line: unset is the right default there.
5721
+
5716
5722
  This exists because claims made without a worktree were never auto-healed before, and a
5717
5723
  real repo accumulated 17 stale same-day claims. Run \`colab doctor\` regularly; \`--prune\`
5718
5724
  in a cleanup cron.
@@ -6203,6 +6209,11 @@ function cmdDoctor(argv) {
6203
6209
  }
6204
6210
  }
6205
6211
 
6212
+ // 10. notifyUrl against a DECLARED local observer (#414). Read-only, never pruned, never counted in
6213
+ // the verdict — it is configuration, not state drift. Silent on a machine with no
6214
+ // <COLAB_HOME>/notify-endpoint: unset is the right default where no observer runs.
6215
+ report.notify = notifyEndpoint.status(config, state.COLAB_DIR);
6216
+
6206
6217
  if (opts.json) { print(JSON.stringify(report, null, 2)); return 0; }
6207
6218
 
6208
6219
  const verb = opts.prune ? 'Pruned' : 'Found';
@@ -6407,6 +6418,11 @@ function cmdDoctor(argv) {
6407
6418
  print(' which also stops colab handing it to a worktree. A "cwd DELETED" line above is the real');
6408
6419
  print(' orphan and wants killing, not reserving.');
6409
6420
  }
6421
+ const notifyLine = notifyEndpoint.healthLine(report.notify);
6422
+ if (notifyLine) {
6423
+ print('');
6424
+ print(notifyLine);
6425
+ }
6410
6426
  return 0;
6411
6427
  }
6412
6428
 
@@ -25,6 +25,7 @@ const fs = require('fs');
25
25
  const path = require('path');
26
26
  const { execFileSync } = require('child_process');
27
27
  const stamp = require('./stamp');
28
+ const notifyEndpoint = require('./notify-endpoint');
28
29
 
29
30
  const OK = 'ok';
30
31
  const WARN = 'warn';
@@ -218,6 +219,23 @@ function checkHooks({ root, colabHome, home, env }) {
218
219
  return rows;
219
220
  }
220
221
 
222
+ /**
223
+ * notifyUrl against a DECLARED local observer (#414). Silent unless something says an observer runs
224
+ * here: a machine with no <COLAB_HOME>/notify-endpoint gets no row at all — unset is the right default
225
+ * there, and a ⚠ on every such machine would teach people to ignore the row. ⚠ rather than ✗: the
226
+ * key is something never set up, not something installed that went stale.
227
+ */
228
+ function checkNotify({ colabHome }) {
229
+ let cfg = {};
230
+ try { cfg = JSON.parse(readText(path.join(colabHome, 'config.json')) || '{}'); } catch (_) { /* reported by colab itself */ }
231
+ const st = notifyEndpoint.status(cfg, colabHome);
232
+ if (st.state === 'unset') return [];
233
+ if (st.state === 'set' && !st.declared) {
234
+ return [{ area: 'notify', severity: OK, text: `notifyUrl = ${st.url}` }];
235
+ }
236
+ return [{ area: 'notify', severity: WARN, text: notifyEndpoint.healthLine(st) }];
237
+ }
238
+
221
239
  function runChecks(opts) {
222
240
  const o = { env: process.env, ...opts };
223
241
  return [
@@ -226,6 +244,7 @@ function runChecks(opts) {
226
244
  checkState(o),
227
245
  ...checkFleet(o),
228
246
  ...checkHooks(o),
247
+ ...checkNotify(o),
229
248
  ];
230
249
  }
231
250
 
@@ -255,5 +274,5 @@ if (require.main === module) {
255
274
 
256
275
  module.exports = {
257
276
  OK, WARN, FAIL,
258
- dispatchedCommands, checkLink, checkFrozen, checkState, checkFleet, checkHooks, runChecks, render,
277
+ dispatchedCommands, checkLink, checkFrozen, checkState, checkFleet, checkHooks, checkNotify, runChecks, render,
259
278
  };
@@ -0,0 +1,170 @@
1
+ 'use strict';
2
+ /**
3
+ * notify-endpoint.js — is this machine's `notifyUrl` set, and SHOULD it be? (#414)
4
+ *
5
+ * `notifyUrl` is optional by design (lib/notify.js): unset means colab makes no network call of its
6
+ * own, and silence is the right behaviour on a machine with no observer. But a machine that DOES run
7
+ * a local observer (a companion dashboard ingesting `issue.merged`, `issue.closed`,
8
+ * `readiness.marked`, `gate.recorded`) depends on the push for the kinds it cannot recover by
9
+ * polling state.json, and an unset key there is a silent outage. Measured on a two-machine fleet
10
+ * running the same observer: the machine set up by hand had recorded 2 292 `issue.merged` events;
11
+ * the one set up a month later with install.sh had 0, and nothing said so until someone asked for
12
+ * lead time.
13
+ *
14
+ * Two inputs answer "should it be set", and colab guesses neither:
15
+ *
16
+ * 1. an explicit URL a human passes to `install.sh --notify-url <url>`;
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.
21
+ *
22
+ * 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.
26
+ * - `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.
29
+ *
30
+ * CommonJS, zero dependencies. Runnable as a script (install.sh's entry):
31
+ * node tools/lib/notify-endpoint.js seed --colab-home <dir> [--url <url>] [--dry]
32
+ * It writes config.json through lib/state.js, the CLI's own writer, so the file's shape cannot drift
33
+ * from what `colab config set` produces. state.js reads COLAB_HOME at require time, so the entry
34
+ * sets it from --colab-home before requiring it.
35
+ */
36
+
37
+ const fs = require('fs');
38
+ const path = require('path');
39
+
40
+ const ENDPOINT_FILE = 'notify-endpoint';
41
+ const HTTP_RE = /^https?:\/\//i;
42
+
43
+ /** The event kinds a local observer only learns of by push — named in the "unset" line. */
44
+ const PUSH_ONLY_KINDS = Object.freeze(['issue.merged', 'issue.closed', 'readiness.marked', 'gate.recorded']);
45
+
46
+ function endpointFile(colabHome) {
47
+ return path.join(colabHome, ENDPOINT_FILE);
48
+ }
49
+
50
+ /**
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.
54
+ */
55
+ function readDeclared(colabHome) {
56
+ const file = endpointFile(colabHome);
57
+ let raw;
58
+ 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() : '';
67
+ }
68
+
69
+ /**
70
+ * The read-only verdict both health checks print. `state`:
71
+ * 'set' notifyUrl is configured (payload: url; `declared` when the file names another)
72
+ * 'unset-declared' notifyUrl absent while an observer declared an endpoint — the outage case
73
+ * 'declared-invalid' notifyUrl absent and the declared file is unusable
74
+ * 'unset' neither — a machine with no observer; callers stay silent
75
+ */
76
+ function status(cfg, colabHome) {
77
+ const url = configuredUrl(cfg);
78
+ const declared = readDeclared(colabHome);
79
+ if (url) {
80
+ return declared && declared.url && declared.url !== url
81
+ ? { state: 'set', url, declared }
82
+ : { state: 'set', url };
83
+ }
84
+ if (!declared) return { state: 'unset' };
85
+ if (declared.invalid) return { state: 'declared-invalid', declared };
86
+ return { state: 'unset-declared', declared };
87
+ }
88
+
89
+ /** One human line for a status, or null when the right output is silence. */
90
+ function healthLine(st) {
91
+ 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';
101
+ }
102
+ return null;
103
+ }
104
+
105
+ /**
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)
109
+ * action 'none' nothing to seed — the lines say plainly the key is unset and what it costs
110
+ */
111
+ function plan({ cfg, colabHome, flagUrl }) {
112
+ const current = configuredUrl(cfg);
113
+ const declared = readDeclared(colabHome);
114
+ if (flagUrl && !HTTP_RE.test(flagUrl)) {
115
+ return { action: 'error', lines: [`--notify-url must be an http(s) URL, got: ${flagUrl}`] };
116
+ }
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 };
126
+ }
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
+ const lines = [];
130
+ if (declared && declared.invalid) lines.push(`⚠ ${declared.file} is ${declared.invalid} — ignored.`);
131
+ lines.push(
132
+ '⚠ notifyUrl is UNSET — colab pushes no events from this machine.',
133
+ ` A local observer (e.g. a companion dashboard) here will never receive ${PUSH_ONLY_KINDS.join(', ')}.`,
134
+ ' Observer on this machine? Re-run with --notify-url <its events URL>, or: colab config set notifyUrl <url>',
135
+ ' No observer here? Nothing to do — unset is the right default.',
136
+ );
137
+ return { action: 'none', lines };
138
+ }
139
+
140
+ function main(argv) {
141
+ const sub = argv[0];
142
+ const val = (flag) => {
143
+ const i = argv.indexOf(flag);
144
+ return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : undefined;
145
+ };
146
+ const colabHome = val('--colab-home') || process.env.COLAB_HOME || path.join(require('os').homedir(), '.colab');
147
+ if (sub !== 'seed') {
148
+ process.stderr.write('usage: notify-endpoint.js seed --colab-home <dir> [--url <url>] [--dry]\n');
149
+ return 2;
150
+ }
151
+ process.env.COLAB_HOME = colabHome; // before state.js computes its paths
152
+ const state = require('./state');
153
+ const cfg = state.loadConfig();
154
+ const p = plan({ cfg, colabHome, flagUrl: val('--url') });
155
+ const out = (l) => process.stdout.write(` ${l}\n`);
156
+ 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.
160
+ const fresh = state.loadConfig();
161
+ if (configuredUrl(fresh)) { out(`✓ notifyUrl = ${configuredUrl(fresh)} (already set → left untouched)`); return 0; }
162
+ fresh.notifyUrl = p.url;
163
+ state.saveConfig(fresh);
164
+ out(`📡 notifyUrl seeded: ${p.url} (from ${p.source}) — colab now pushes its events there`);
165
+ return 0;
166
+ }
167
+
168
+ if (require.main === module) process.exitCode = main(process.argv.slice(2));
169
+
170
+ module.exports = { ENDPOINT_FILE, PUSH_ONLY_KINDS, endpointFile, readDeclared, status, healthLine, plan, main };