@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 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/LICENSE +21 -0
- package/README.md +312 -3
- package/README.vi.md +281 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13806 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +278 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify-endpoint.js +170 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +521 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/migration-paths.js — where a repo's migrations live (#383): the ONE rule every
|
|
4
|
+
* migration detector reads, so no consumer keeps its own regex.
|
|
5
|
+
*
|
|
6
|
+
* Before this, `colab ship`'s no-new-migrations gate and `release cut`'s schema-additive check each
|
|
7
|
+
* hard-coded two layouts (Laravel `database/migrations/`, Prisma `prisma/migrations/`). A repo whose
|
|
8
|
+
* migrations live anywhere else — a Node service's `backend/migrations/`, a Go service's
|
|
9
|
+
* `migrations/` — was invisible to both: `colab ship --dry` reported `no new migrations ✓` on a
|
|
10
|
+
* branch adding a production data backfill, so the human-only grant (#98) never engaged.
|
|
11
|
+
*
|
|
12
|
+
* `migrations:` in `.github/project.yml` names the extra places, as repo-relative prefixes:
|
|
13
|
+
*
|
|
14
|
+
* migrations: [backend/migrations/]
|
|
15
|
+
*
|
|
16
|
+
* The declared list is ADDED to the two defaults, never a replacement for them: a declaration can
|
|
17
|
+
* only make the gate see more. There is deliberately no opt-out of the defaults — an opt-out can
|
|
18
|
+
* only make a human-only gate see LESS, and weakening one should wait for a repo that genuinely
|
|
19
|
+
* needs it (a `database/migrations/` that is not migrations), not be built ahead of one.
|
|
20
|
+
*
|
|
21
|
+
* Pure: strings in, strings out — no fs, no git. Same posture as ship-batch.js.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
// Matched ANYWHERE in the path — `(^|/)` — so a monorepo's `api/database/migrations/` counts, as it
|
|
25
|
+
// always has. Declared prefixes are matched from the repo root only (they are repo-relative paths).
|
|
26
|
+
const DEFAULT_MIGRATION_PATHS = Object.freeze(['database/migrations/', 'prisma/migrations/']);
|
|
27
|
+
|
|
28
|
+
// Dependency trees a repo commits but does not author. A `vendor/foo/migrations/` is a library's
|
|
29
|
+
// migrations, run (if at all) through the library — not an undeclared layout of this repo's own.
|
|
30
|
+
const FOREIGN_TREE_SEGMENTS = new Set(['node_modules', 'vendor']);
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* One declared entry → its normalised prefix (`a/b/`), or `{ problem }`. Rejected, not guessed:
|
|
34
|
+
* absolute paths and `..` (not repo-relative), globs (a prefix match would silently match nothing
|
|
35
|
+
* for `*`), and empties.
|
|
36
|
+
*/
|
|
37
|
+
function normalizeEntry(raw) {
|
|
38
|
+
if (typeof raw !== 'string') return { problem: `${JSON.stringify(raw)} is not a path` };
|
|
39
|
+
let p = raw.trim();
|
|
40
|
+
if (p === '') return { problem: 'an empty entry is not a path' };
|
|
41
|
+
if (p.startsWith('/')) return { problem: `"${p}" is absolute — declare a repo-relative prefix (e.g. "backend/migrations/")` };
|
|
42
|
+
if (/[*?[\]{}]/.test(p)) return { problem: `"${p}" is a glob — declare a plain directory prefix; entries are matched by prefix, not by pattern` };
|
|
43
|
+
p = p.replace(/^(\.\/)+/, '').replace(/\/{2,}/g, '/');
|
|
44
|
+
if (p === '' || p === '.') return { problem: `"${raw}" names the repo root — every file would be a migration` };
|
|
45
|
+
if (p.split('/').includes('..')) return { problem: `"${p}" climbs out of the repo — declare a repo-relative prefix` };
|
|
46
|
+
if (!p.endsWith('/')) p += '/';
|
|
47
|
+
return { path: p };
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* `migrations:` from a parsed project.yml → `{ declared, paths, problems, notes, reason }`.
|
|
52
|
+
* `problems` are invalid shapes/entries (the audit fails them); `notes` are harmless redundancy — an
|
|
53
|
+
* empty list, a default restated, a duplicate — which the audit only warns about.
|
|
54
|
+
*
|
|
55
|
+
* - absent / null → declared: false, paths: [] (the defaults alone — today's behaviour)
|
|
56
|
+
* - a list → every entry that normalises; the rest land in `problems`
|
|
57
|
+
* - a bare scalar string → read as a one-entry list, with a problem saying so: the reader is
|
|
58
|
+
* lenient in the direction that makes the gate STRICTER (it still sees
|
|
59
|
+
* the path the author obviously meant); the audit fails the shape.
|
|
60
|
+
*
|
|
61
|
+
* `paths` never includes the defaults — `isMigrationPath` always applies those itself.
|
|
62
|
+
*/
|
|
63
|
+
function parseMigrationPaths(doc) {
|
|
64
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, 'migrations');
|
|
65
|
+
if (!has || doc.migrations === null || doc.migrations === undefined) {
|
|
66
|
+
return { declared: false, paths: [], problems: [], notes: [], reason: 'migrations absent — defaults only' };
|
|
67
|
+
}
|
|
68
|
+
const v = doc.migrations;
|
|
69
|
+
const problems = [];
|
|
70
|
+
const notes = [];
|
|
71
|
+
let entries;
|
|
72
|
+
if (Array.isArray(v)) entries = v;
|
|
73
|
+
else if (typeof v === 'string' && v.trim() !== '') {
|
|
74
|
+
entries = [v];
|
|
75
|
+
problems.push(`migrations is a bare string ${JSON.stringify(v)}, expected a list (e.g. [${v.trim()}])`);
|
|
76
|
+
} else {
|
|
77
|
+
return { declared: true, paths: [], problems: [`migrations is ${JSON.stringify(v)}, expected a list of repo-relative prefixes (e.g. [backend/migrations/])`], notes, reason: 'migrations malformed — defaults only' };
|
|
78
|
+
}
|
|
79
|
+
if (Array.isArray(v) && v.length === 0) {
|
|
80
|
+
notes.push('migrations is an empty list — omit the key for the defaults alone');
|
|
81
|
+
}
|
|
82
|
+
const paths = [];
|
|
83
|
+
for (const raw of entries) {
|
|
84
|
+
const r = normalizeEntry(raw);
|
|
85
|
+
if (r.problem) { problems.push(`migrations: ${r.problem}`); continue; }
|
|
86
|
+
if (DEFAULT_MIGRATION_PATHS.includes(r.path)) {
|
|
87
|
+
notes.push(`migrations: "${r.path}" is already a default — it need not be declared`);
|
|
88
|
+
continue;
|
|
89
|
+
}
|
|
90
|
+
if (paths.includes(r.path)) { notes.push(`migrations: "${r.path}" is declared twice`); continue; }
|
|
91
|
+
paths.push(r.path);
|
|
92
|
+
}
|
|
93
|
+
return { declared: true, paths, problems, notes, reason: paths.length ? `migrations: [${paths.join(', ')}] + defaults` : 'defaults only' };
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Union of several docs' declared prefixes (trunk's + the branch's) — the gate sees every one. */
|
|
97
|
+
function unionPaths(...docs) {
|
|
98
|
+
const out = [];
|
|
99
|
+
for (const d of docs) for (const p of parseMigrationPaths(d).paths) if (!out.includes(p)) out.push(p);
|
|
100
|
+
return out;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** Is `file` (repo-relative, `/`-separated) a migration under the defaults or a declared prefix? */
|
|
104
|
+
function isMigrationPath(file, declared) {
|
|
105
|
+
const f = String(file || '');
|
|
106
|
+
for (const d of DEFAULT_MIGRATION_PATHS) {
|
|
107
|
+
if (f.startsWith(d) || f.includes(`/${d}`)) return true;
|
|
108
|
+
}
|
|
109
|
+
for (const p of declared || []) if (f.startsWith(p)) return true;
|
|
110
|
+
return false;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Directories named `migrations` in a tracked-file list that NO rule covers — the likely
|
|
115
|
+
* undeclared layout the audit reports. `files` is `git ls-files` output (repo-relative). Returns the
|
|
116
|
+
* outermost such directory per path (`x/migrations/`), sorted, deduped. Paths inside a committed
|
|
117
|
+
* dependency tree (`node_modules/`, `vendor/`) are skipped.
|
|
118
|
+
*/
|
|
119
|
+
function undeclaredMigrationDirs(files, declared) {
|
|
120
|
+
const out = new Set();
|
|
121
|
+
for (const file of files || []) {
|
|
122
|
+
const segs = String(file).split('/');
|
|
123
|
+
if (segs.some((s) => FOREIGN_TREE_SEGMENTS.has(s))) continue;
|
|
124
|
+
// Directory segments only — a FILE named `migrations` is not a layout.
|
|
125
|
+
const idx = segs.slice(0, -1).indexOf('migrations');
|
|
126
|
+
if (idx === -1) continue;
|
|
127
|
+
if (isMigrationPath(file, declared)) continue;
|
|
128
|
+
out.add(`${segs.slice(0, idx + 1).join('/')}/`);
|
|
129
|
+
}
|
|
130
|
+
return [...out].sort();
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
module.exports = {
|
|
134
|
+
DEFAULT_MIGRATION_PATHS, parseMigrationPaths, unionPaths, isMigrationPath, undeclaredMigrationDirs,
|
|
135
|
+
};
|
|
@@ -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 };
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* notify.js — OPTIONAL, best-effort event push to an external observer.
|
|
4
|
+
*
|
|
5
|
+
* Configure `notifyUrl` in ~/.colab/config.json and the state-changing commands (claim, release,
|
|
6
|
+
* close, ship, worktree new, worktree rm, readiness) each POST one small JSON event as they succeed. Leave it unset
|
|
7
|
+
* and this module makes no network call of any kind — that is the default and it is absolute.
|
|
8
|
+
*
|
|
9
|
+
* ── What this is NOT ──────────────────────────────────────────────────────────────────────────
|
|
10
|
+
* It is not a transport anyone may depend on. The observers this exists for already discover every
|
|
11
|
+
* one of these facts on their own, by polling ~/.colab/state.json on a timer; the push only sharpens
|
|
12
|
+
* the timestamp from "within a tick" to "the second it happened", and records which host did it. So
|
|
13
|
+
* there is deliberately no retry, no queue, no response-body read, and no error surfaced. Anything
|
|
14
|
+
* that would make the push load-bearing — a caller that waits on it, a receiver that needs it — is a
|
|
15
|
+
* design error upstream, not a missing feature here.
|
|
16
|
+
*
|
|
17
|
+
* ── What a dropped event actually costs — and it is NOT one tick for every kind ────────────────
|
|
18
|
+
* For a COLAB-LOCAL fact (a worktree, a port, a claim — all in ~/.colab/state.json) the fallback is
|
|
19
|
+
* that state file, polled on a timer, so a lost event costs one tick and nothing else. But some
|
|
20
|
+
* events report a PROVIDER-SIDE fact colab does not keep locally: a label it wrote (deps-checked,
|
|
21
|
+
* in-progress), an issue it closed. There the fallback is not state.json — it is re-reading the
|
|
22
|
+
* provider, which is eventually consistent: measured on a live fleet, a label written via the REST
|
|
23
|
+
* API was still absent from a fresh GraphQL read EIGHT MINUTES later. So a dropped event for a
|
|
24
|
+
* provider-side fact costs minutes of staleness, not a tick. This is still acceptable under
|
|
25
|
+
* best-effort — the push is a latency optimisation, never the system of record — but the cost is
|
|
26
|
+
* "the provider's read-after-write lag", not "one poll", and a receiver must be built for that.
|
|
27
|
+
*
|
|
28
|
+
* ── Why a detached child process, and not just fetch() ────────────────────────────────────────
|
|
29
|
+
* The CLI's process exits as soon as the event loop drains after main() returns — nothing here
|
|
30
|
+
* awaits the parent process, so an in-flight request has no guarantee of surviving to completion.
|
|
31
|
+
* An un-awaited fetch would therefore be silently dropped for exactly the operations worth
|
|
32
|
+
* reporting, and awaiting it would mean plumbing async through a fully synchronous CLI *and*
|
|
33
|
+
* letting a hung endpoint delay a command that has already done its real work. A detached, unref'd
|
|
34
|
+
* child owns the request instead: the parent's cost is the spawn call, the child outlives the
|
|
35
|
+
* parent's exit, and a receiver that hangs is the child's problem — bounded by SEND_TIMEOUT_MS,
|
|
36
|
+
* invisible to the user.
|
|
37
|
+
*
|
|
38
|
+
* ── The kind vocabulary is the receiver's, and it is CLOSED ───────────────────────────────────
|
|
39
|
+
* Receivers reject an unrecognised `kind` with 400 and write nothing. That rejection is correct and
|
|
40
|
+
* we do not work around it: a journal read by machine counts events by kind, so two names for one
|
|
41
|
+
* fact makes every future count quietly half-right. Hence ACTION_KIND below is a fixed map, not a
|
|
42
|
+
* string built at the call site. Adding an action means agreeing a kind with the receiver first.
|
|
43
|
+
*/
|
|
44
|
+
|
|
45
|
+
const { spawn } = require('child_process');
|
|
46
|
+
|
|
47
|
+
/** Request timeout inside the child. Bounds a hung receiver; never observed by the parent. */
|
|
48
|
+
const SEND_TIMEOUT_MS = 200;
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* colab action → the receiver's event kind. Deliberately not 1:1 with command names.
|
|
52
|
+
*
|
|
53
|
+
* `ship` maps to worktree.state-changed because no ship-shaped kind exists and inventing one is the
|
|
54
|
+
* failure the closed vocabulary prevents. The observer's `intent.*` kinds describe ITS OWN button
|
|
55
|
+
* lifecycle — an event claiming to be an intent while originating out here would be a false record.
|
|
56
|
+
*/
|
|
57
|
+
const ACTION_KIND = Object.freeze({
|
|
58
|
+
'claim': 'claim.appeared',
|
|
59
|
+
'release': 'claim.released',
|
|
60
|
+
'ship': 'worktree.state-changed',
|
|
61
|
+
'worktree-new': 'worktree.appeared',
|
|
62
|
+
'worktree-rm': 'worktree.removed',
|
|
63
|
+
// readiness reports a PROVIDER-SIDE fact (the deps-checked label colab now writes, #45), so a
|
|
64
|
+
// dropped event costs the provider's read-after-write lag, not one tick. The receiver has agreed
|
|
65
|
+
// this kind and ingests it as an optimistic "ready" hint that bridges that lag (#46); payload is
|
|
66
|
+
// { state: 'checked' | 'unchecked' } — 'unchecked' (--clear) drops the hint, 'checked' applies it.
|
|
67
|
+
'readiness': 'readiness.marked',
|
|
68
|
+
// issue-merged is the PER-ISSUE companion to ship (#46 §2). `ship` reports one worktree state
|
|
69
|
+
// change carrying every issue in its payload; this fires once per issue so the receiver can flip a
|
|
70
|
+
// single issue to done the instant its merge lands, ahead of the eventually-consistent read. The
|
|
71
|
+
// sha (a payload field) is the evidence; repo and issue ride the envelope. Agreed one-per-issue,
|
|
72
|
+
// not a fan-out — the shape the receiver ingests.
|
|
73
|
+
'issue-merged': 'issue.merged',
|
|
74
|
+
// issue-filed reports work APPEARING rather than finishing (#102) — the gap the other two kinds
|
|
75
|
+
// leave: a session that files, labels, and rewires several issues in a row has no event at all
|
|
76
|
+
// today, so the receiver only learns about them when its own snapshot TTL expires. There is no
|
|
77
|
+
// colab command that creates an issue (every call site still runs a raw `gh issue create`), so
|
|
78
|
+
// this kind is pushed by a standalone command (`colab issue-filed`) run right after, rather than
|
|
79
|
+
// falling out of a write colab already owns the way `readiness` and `issue-merged` do. Payload
|
|
80
|
+
// carries nothing beyond repo + issue — the receiver's response is the same refresh either way.
|
|
81
|
+
'issue-filed': 'issue.filed',
|
|
82
|
+
// gate-recorded reports a PROVIDER-INDEPENDENT fact: code-wrap's own A3 step ("run the repo's
|
|
83
|
+
// quality gate") already knows its verdict the moment the gate finishes, so this fires right after
|
|
84
|
+
// that run rather than falling out of a write colab already owns (#116). It backs one mark on the
|
|
85
|
+
// receiver's per-branch hand-off checklist — "does this branch have a recorded quality-gate
|
|
86
|
+
// result?" — which reads "unknown" until an event with a matching sha arrives; a stale event (an
|
|
87
|
+
// old sha behind the branch's current HEAD) collapses back to "unknown" rather than being trusted.
|
|
88
|
+
// Payload is { ok: boolean, sha: string }; repo + worktree ride the envelope as the join key, and
|
|
89
|
+
// worktree must match exactly what `colab worktrees` lists for it.
|
|
90
|
+
'gate-recorded': 'gate.recorded',
|
|
91
|
+
// issue-closed reports a close colab performed OUTSIDE a ship (#381, `colab close`): a `Refs #N`
|
|
92
|
+
// issue whose follow-up finished, a spent container, a claim-only sweep bucket. `ship` already
|
|
93
|
+
// tells the receiver about the closes it performs (`issue.merged`, and the `ship` event's issue
|
|
94
|
+
// list on evidence-close); a close anywhere else used to be a bare `gh issue close` the receiver
|
|
95
|
+
// never heard about, so it kept offering the closed issue as startable until its own cache
|
|
96
|
+
// expired (~10 minutes, measured). Provider-side fact, same staleness class as `readiness`.
|
|
97
|
+
// Payload is { reason: 'completed' | 'not-planned' }; repo + issue ride the envelope. Sender-first
|
|
98
|
+
// is safe: until the receiver adds this kind to its vocabulary it 400s and drops it, inertly.
|
|
99
|
+
'issue-closed': 'issue.closed',
|
|
100
|
+
});
|
|
101
|
+
|
|
102
|
+
/** Actions this module knows how to report. Exported so a caller can be checked against it. */
|
|
103
|
+
const ACTIONS = Object.freeze(Object.keys(ACTION_KIND));
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Build the event body for an action. Pure — no I/O — so the shape is testable without a receiver.
|
|
107
|
+
* Returns null for an unknown action, which is how an unrecognised kind is prevented from ever
|
|
108
|
+
* being sent rather than being sent and 400'd.
|
|
109
|
+
*
|
|
110
|
+
* Absent fields are omitted, not sent as null: the receiver coerces missing to null itself, and an
|
|
111
|
+
* explicit null in a payload reads like a measured absence rather than a field we never had.
|
|
112
|
+
*/
|
|
113
|
+
function buildEvent(action, fields, ts) {
|
|
114
|
+
const kind = ACTION_KIND[action];
|
|
115
|
+
if (!kind) return null;
|
|
116
|
+
const f = fields || {};
|
|
117
|
+
const ev = { kind, ts: ts || new Date().toISOString() };
|
|
118
|
+
if (f.repo) ev.repo = String(f.repo);
|
|
119
|
+
if (Number.isInteger(f.issue) && f.issue > 0) ev.issue = f.issue;
|
|
120
|
+
if (f.worktree) ev.worktree = String(f.worktree);
|
|
121
|
+
if (f.session) ev.session = String(f.session);
|
|
122
|
+
if (f.payload != null) ev.payload = f.payload;
|
|
123
|
+
return ev;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* The script the child runs. Kept as one string, taking url and body from argv rather than being
|
|
128
|
+
* interpolated into source — the body carries branch and worktree names typed by a user, and
|
|
129
|
+
* building code out of them is how a quoting bug becomes code execution. spawn() with an argv array
|
|
130
|
+
* never involves a shell, so nothing here is re-parsed.
|
|
131
|
+
*/
|
|
132
|
+
const CHILD_SCRIPT = `
|
|
133
|
+
const url = process.argv[1], body = process.argv[2];
|
|
134
|
+
try {
|
|
135
|
+
const lib = require(url.startsWith('https:') ? 'https' : 'http');
|
|
136
|
+
const req = lib.request(url, {
|
|
137
|
+
method: 'POST',
|
|
138
|
+
headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) },
|
|
139
|
+
timeout: ${SEND_TIMEOUT_MS},
|
|
140
|
+
}, (res) => { res.resume(); });
|
|
141
|
+
req.on('error', () => {});
|
|
142
|
+
req.on('timeout', () => req.destroy());
|
|
143
|
+
req.end(body);
|
|
144
|
+
} catch (_) { /* best-effort: a malformed URL is silence, never a crash */ }
|
|
145
|
+
`;
|
|
146
|
+
|
|
147
|
+
/**
|
|
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.
|
|
151
|
+
*
|
|
152
|
+
* '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
|
|
155
|
+
*
|
|
156
|
+
* @param {object} cfg loaded config (state.loadConfig())
|
|
157
|
+
* @param {string} action one of ACTIONS
|
|
158
|
+
* @param {object} fields { repo, issue, worktree, session, payload }
|
|
159
|
+
* @param {object} [deps] { spawn } — injectable so tests never open a socket
|
|
160
|
+
*/
|
|
161
|
+
function notify(cfg, action, fields, deps) {
|
|
162
|
+
// The unconfigured path must return before anything else can throw, allocate, or resolve a host.
|
|
163
|
+
// "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';
|
|
167
|
+
|
|
168
|
+
const ev = buildEvent(action, fields);
|
|
169
|
+
if (!ev) return 'skipped';
|
|
170
|
+
|
|
171
|
+
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';
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
module.exports = { notify, buildEvent, ACTION_KIND, ACTIONS, SEND_TIMEOUT_MS };
|