@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.9
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 +310 -3
- package/README.vi.md +280 -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 +13785 -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 +259 -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.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 +481 -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,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 };
|
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* The private-repo / public-npm rule (#432, part of #420).
|
|
4
|
+
*
|
|
5
|
+
* Owner ruling 2026-10-02: `@<org>` on public npm is always public, so a PRIVATE repository
|
|
6
|
+
* never publishes to public npm. Private apps are installed from git
|
|
7
|
+
* (`npx github:<org>/<repo>#<tag>`), where repository access is the access control.
|
|
8
|
+
*
|
|
9
|
+
* This module is pure: it takes a reader and the repository's visibility and returns findings.
|
|
10
|
+
* Visibility comes from the GitHub API at the caller (never a local guess).
|
|
11
|
+
*
|
|
12
|
+
* exposure(...) -> { problems: string[] } every way this repo could reach public npm
|
|
13
|
+
* findings(...) -> [{ level, text }] what the audit reports given visibility
|
|
14
|
+
*
|
|
15
|
+
* Two kinds of problem, both only a finding when the repo is private:
|
|
16
|
+
* 1. a package.json (root or workspace member) without `"private": true`, or whose
|
|
17
|
+
* `publishConfig.registry` is the public registry;
|
|
18
|
+
* 2. a workflow step that publishes to registry.npmjs.org.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
const PUBLIC_REGISTRY = /registry\.(npmjs\.org|yarnpkg\.com)/i;
|
|
22
|
+
|
|
23
|
+
// `npm publish`, `pnpm publish`, `yarn publish`, `yarn npm publish`, `bun publish`.
|
|
24
|
+
const PUBLISH_CMD = /(^|[\s;&|(])(npm|pnpm|bun|yarn(\s+npm)?)\s+publish\b/;
|
|
25
|
+
const PUBLISH_ACTION = /\buses:\s*['"]?[\w.-]*\/?[\w.-]*npm-publish\b/i;
|
|
26
|
+
|
|
27
|
+
function stripComment(line) {
|
|
28
|
+
return line.replace(/(^|\s)#.*$/, '');
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** Workflow lines that publish to the public registry. Returns [{ wf, line, text }]. */
|
|
32
|
+
function workflowPublishes(workflows, readFile) {
|
|
33
|
+
const out = [];
|
|
34
|
+
for (const wf of workflows || []) {
|
|
35
|
+
const text = readFile(`.github/workflows/${wf}`);
|
|
36
|
+
if (!text) continue;
|
|
37
|
+
text.split('\n').forEach((raw, i) => {
|
|
38
|
+
const line = stripComment(raw);
|
|
39
|
+
const isCmd = PUBLISH_CMD.test(line);
|
|
40
|
+
const isAction = PUBLISH_ACTION.test(line);
|
|
41
|
+
if (!isCmd && !isAction) return;
|
|
42
|
+
if (isCmd) {
|
|
43
|
+
if (/--dry-run\b/.test(line)) return; // cannot publish
|
|
44
|
+
const reg = line.match(/--registry[=\s]+(\S+)/);
|
|
45
|
+
if (reg && !PUBLIC_REGISTRY.test(reg[1])) return; // pointed elsewhere
|
|
46
|
+
}
|
|
47
|
+
out.push({ wf, line: i + 1, text: line.trim() });
|
|
48
|
+
});
|
|
49
|
+
}
|
|
50
|
+
return out;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function parseJson(text) {
|
|
54
|
+
try { return JSON.parse(text); } catch (_) { return undefined; }
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function expandPattern(pat, listDir, readFile) {
|
|
58
|
+
const p = String(pat).replace(/^\.\//, '').replace(/\/+$/, '');
|
|
59
|
+
if (!p || p.startsWith('!')) return [];
|
|
60
|
+
if (p.endsWith('/*') || p.endsWith('/**')) {
|
|
61
|
+
const base = p.replace(/\/\*+$/, '');
|
|
62
|
+
return listDir(base)
|
|
63
|
+
.map((d) => `${base}/${d}`)
|
|
64
|
+
.filter((d) => readFile(`${d}/package.json`) != null);
|
|
65
|
+
}
|
|
66
|
+
return readFile(`${p}/package.json`) != null ? [p] : [];
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function workspacePatterns(rootPkg, readFile) {
|
|
70
|
+
const out = [];
|
|
71
|
+
const ws = rootPkg && rootPkg.workspaces;
|
|
72
|
+
if (Array.isArray(ws)) out.push(...ws);
|
|
73
|
+
else if (ws && Array.isArray(ws.packages)) out.push(...ws.packages);
|
|
74
|
+
const pnpm = readFile('pnpm-workspace.yaml');
|
|
75
|
+
if (pnpm) {
|
|
76
|
+
for (const m of pnpm.matchAll(/^\s*-\s*['"]?([^'"#\n]+?)['"]?\s*(#.*)?$/gm)) out.push(m[1]);
|
|
77
|
+
}
|
|
78
|
+
return out;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Every package.json that could be published: root plus workspace members. */
|
|
82
|
+
function manifests(readFile, listDir) {
|
|
83
|
+
const out = [];
|
|
84
|
+
const rootText = readFile('package.json');
|
|
85
|
+
if (rootText == null) return out;
|
|
86
|
+
const root = parseJson(rootText);
|
|
87
|
+
out.push({ path: 'package.json', pkg: root, unparsed: root === undefined });
|
|
88
|
+
const seen = new Set(['package.json']);
|
|
89
|
+
for (const pat of workspacePatterns(root, readFile)) {
|
|
90
|
+
for (const dir of expandPattern(pat, listDir, readFile)) {
|
|
91
|
+
const p = `${dir}/package.json`;
|
|
92
|
+
if (seen.has(p)) continue;
|
|
93
|
+
seen.add(p);
|
|
94
|
+
const pkg = parseJson(readFile(p));
|
|
95
|
+
out.push({ path: p, pkg, unparsed: pkg === undefined });
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
return out;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** Everything in this repo that could reach public npm. */
|
|
102
|
+
function exposure({ readFile, listDir, workflows }) {
|
|
103
|
+
const problems = [];
|
|
104
|
+
for (const m of manifests(readFile, listDir)) {
|
|
105
|
+
if (m.unparsed || !m.pkg || typeof m.pkg !== 'object') continue; // the toolchain check reports unparsable JSON
|
|
106
|
+
if (m.pkg.private !== true) {
|
|
107
|
+
problems.push(`${m.path} lacks "private": true`);
|
|
108
|
+
}
|
|
109
|
+
const reg = m.pkg.publishConfig && m.pkg.publishConfig.registry;
|
|
110
|
+
if (typeof reg === 'string' && PUBLIC_REGISTRY.test(reg)) {
|
|
111
|
+
problems.push(`${m.path} publishConfig.registry points at ${reg}`);
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
for (const p of workflowPublishes(workflows, readFile)) {
|
|
115
|
+
problems.push(`.github/workflows/${p.wf}:${p.line} publishes to public npm (\`${p.text}\`)`);
|
|
116
|
+
}
|
|
117
|
+
return { problems };
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
const RULE = 'a private repository never publishes to public npm — install private apps from git (`npx github:<org>/<repo>#<tag>`) and set "private": true (CONVENTIONS.md, owner ruling 2026-10-02)';
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* @param visibility 'public' | 'private' | 'internal' | null (unknown)
|
|
124
|
+
* Public repos pass. Unknown visibility is reported (warn), never passed — but only when there is
|
|
125
|
+
* something it would matter for, so a repo with no npm surface stays silent.
|
|
126
|
+
*/
|
|
127
|
+
function findings({ readFile, listDir, workflows, visibility }) {
|
|
128
|
+
if (visibility === 'public') return [];
|
|
129
|
+
const { problems } = exposure({ readFile, listDir, workflows });
|
|
130
|
+
if (!problems.length) return [];
|
|
131
|
+
if (visibility === 'private' || visibility === 'internal') {
|
|
132
|
+
return problems.map((t) => ({ level: 'fail', text: `${t} — ${RULE}` }));
|
|
133
|
+
}
|
|
134
|
+
return [{
|
|
135
|
+
level: 'warn',
|
|
136
|
+
text: `repository visibility could not be read, so the private-repo npm rule could not be checked (${problems.length} candidate finding(s): ${problems.join('; ')}) — ${RULE}`,
|
|
137
|
+
}];
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
// ---- #442: GitHub Release assets are not an install path ------------------------------------
|
|
141
|
+
//
|
|
142
|
+
// CONVENTIONS.md §6, *Distribution*: every distributed tool installs with `npx`. A private compiled
|
|
143
|
+
// tool ships its binaries as dist refs in its own repo (templates/dist-refs.yml) and installs with
|
|
144
|
+
// `npx github:<org>/<repo>#vX.Y.Z`; a private repo uploading binaries as Release assets is asking
|
|
145
|
+
// every user for the `gh` CLI (or a token) to install it. Advisory: a Release asset can be a
|
|
146
|
+
// legitimate by-product (an SBOM, a changelog), so this warns and never fails.
|
|
147
|
+
|
|
148
|
+
// Actions that upload Release assets unconditionally, and those that do only with a files key.
|
|
149
|
+
const ASSET_ACTION_ALWAYS = /\buses:\s*['"]?(actions\/upload-release-asset|svenstaro\/upload-release-action)\b/i;
|
|
150
|
+
const ASSET_ACTION_KEYED = [
|
|
151
|
+
{ re: /\buses:\s*['"]?softprops\/action-gh-release\b/i, key: /^\s*files:\s*\S/ },
|
|
152
|
+
{ re: /\buses:\s*['"]?ncipollo\/release-action\b/i, key: /^\s*artifacts:\s*\S/ },
|
|
153
|
+
];
|
|
154
|
+
// `gh release create <tag> [<file>…]` flags that take a value — their value is not a file.
|
|
155
|
+
const GH_VALUE_FLAGS = new Set(['-n', '--notes', '-F', '--notes-file', '-t', '--title', '--target',
|
|
156
|
+
'--discussion-category', '--notes-start-tag', '-R', '--repo', '--fail-on-no-commits']);
|
|
157
|
+
|
|
158
|
+
function shellTokens(line) {
|
|
159
|
+
return (line.match(/"(?:[^"\\]|\\.)*"|'[^']*'|\S+/g) || []);
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
// A positional argument that is a file: a path, a glob, or a name with an extension. A bare
|
|
163
|
+
// expansion like "${KIND[@]}" (an array of flags, in the handbook's own release templates) is not.
|
|
164
|
+
function looksLikeAsset(tok) {
|
|
165
|
+
const t = tok.replace(/^["']|["']$/g, '');
|
|
166
|
+
if (/^\$\{?\w+(\[@\])?\}?$/.test(t)) return false;
|
|
167
|
+
return /[/*]/.test(t) || /\.[A-Za-z0-9]{1,8}(#.*)?$/.test(t);
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
// `files: ${{ env.ATTACH_ARTIFACTS == 'true' && '…' || '' }}` with `ATTACH_ARTIFACTS: "false"`
|
|
171
|
+
// declared in the same file — templates/release-tag.yml's opt-in, as shipped — uploads nothing.
|
|
172
|
+
// Flipping the switch to "true" makes it an upload again, and that is reported.
|
|
173
|
+
function switchedOff(line, text) {
|
|
174
|
+
const m = line.match(/env\.(\w+)\s*==\s*'true'/);
|
|
175
|
+
return !!m && new RegExp(`^\\s*${m[1]}:\\s*["']?false["']?\\s*(#.*)?$`, 'm').test(text);
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/** `gh release create` lines that pass files, after the tag. */
|
|
179
|
+
function ghCreateUploads(line) {
|
|
180
|
+
const toks = shellTokens(line);
|
|
181
|
+
const at = toks.findIndex((t, i) => t === 'create' && toks[i - 1] === 'release' && toks[i - 2] === 'gh');
|
|
182
|
+
if (at === -1) return false;
|
|
183
|
+
const pos = [];
|
|
184
|
+
for (let i = at + 1; i < toks.length; i++) {
|
|
185
|
+
const t = toks[i];
|
|
186
|
+
if (/^[;&|]/.test(t)) break;
|
|
187
|
+
if (t.startsWith('-')) { if (GH_VALUE_FLAGS.has(t)) i++; continue; }
|
|
188
|
+
pos.push(t);
|
|
189
|
+
}
|
|
190
|
+
return pos.slice(1).some(looksLikeAsset);
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** Workflow lines that upload GitHub Release assets. Returns [{ wf, line, text }]. */
|
|
194
|
+
function releaseAssetUploads(workflows, readFile) {
|
|
195
|
+
const out = [];
|
|
196
|
+
for (const wf of workflows || []) {
|
|
197
|
+
const text = readFile(`.github/workflows/${wf}`);
|
|
198
|
+
if (!text) continue;
|
|
199
|
+
const lines = text.split('\n');
|
|
200
|
+
lines.forEach((raw, i) => {
|
|
201
|
+
const line = stripComment(raw);
|
|
202
|
+
let hit = /(^|[\s;&|(])gh\s+release\s+upload\b/.test(line) || ghCreateUploads(line) || ASSET_ACTION_ALWAYS.test(line);
|
|
203
|
+
if (!hit) {
|
|
204
|
+
const keyed = ASSET_ACTION_KEYED.find((k) => k.re.test(line));
|
|
205
|
+
if (keyed) {
|
|
206
|
+
// The step's own lines: until the next list item at this indent or shallower.
|
|
207
|
+
const indent = raw.search(/\S/);
|
|
208
|
+
const stepIndent = /^\s*-\s/.test(raw) ? indent : indent - 2;
|
|
209
|
+
for (let j = i + 1; j < lines.length; j++) {
|
|
210
|
+
const l = lines[j];
|
|
211
|
+
if (!l.trim()) continue;
|
|
212
|
+
const ind = l.search(/\S/);
|
|
213
|
+
if (ind <= stepIndent) break;
|
|
214
|
+
if (keyed.key.test(stripComment(l))) { hit = !switchedOff(l, text); break; }
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
if (hit) out.push({ wf, line: i + 1, text: line.trim() });
|
|
219
|
+
});
|
|
220
|
+
}
|
|
221
|
+
return out;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
const ASSET_RULE = 'GitHub Release assets are not an install path — a private compiled tool pushes its binaries as dist refs (templates/dist-refs.yml) and installs with `npx github:<org>/<repo>#vX.Y.Z` (CONVENTIONS.md §6, Distribution, #442)';
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* Advisory only. Private/internal → one warn per upload site; public → nothing (a public compiled
|
|
228
|
+
* tool's install path is npm platform packages, and the npm job's own rules cover it); unknown
|
|
229
|
+
* visibility → one warn saying the rule could not be checked.
|
|
230
|
+
*/
|
|
231
|
+
function assetFindings({ readFile, workflows, visibility }) {
|
|
232
|
+
if (visibility === 'public') return [];
|
|
233
|
+
const uploads = releaseAssetUploads(workflows, readFile);
|
|
234
|
+
if (!uploads.length) return [];
|
|
235
|
+
const sites = uploads.map((u) => `.github/workflows/${u.wf}:${u.line} (\`${u.text}\`)`);
|
|
236
|
+
if (visibility === 'private' || visibility === 'internal') {
|
|
237
|
+
return sites.map((s) => ({ level: 'warn', text: `${s} uploads a GitHub Release asset — ${ASSET_RULE}` }));
|
|
238
|
+
}
|
|
239
|
+
return [{ level: 'warn', text: `repository visibility could not be read, so the Release-asset install rule could not be checked (${sites.join('; ')}) — ${ASSET_RULE}` }];
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
module.exports = { exposure, findings, workflowPublishes, manifests, releaseAssetUploads, assetFindings };
|