@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.10

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.
Files changed (94) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +310 -3
  3. package/README.vi.md +280 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13790 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +259 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify.js +188 -0
  63. package/tools/lib/npm-publish-guard.js +242 -0
  64. package/tools/lib/orphan-worktree.js +127 -0
  65. package/tools/lib/owner-branch.js +182 -0
  66. package/tools/lib/place.js +782 -0
  67. package/tools/lib/ports.js +167 -0
  68. package/tools/lib/procs.js +185 -0
  69. package/tools/lib/readiness.js +240 -0
  70. package/tools/lib/records.js +185 -0
  71. package/tools/lib/refs-brake.js +95 -0
  72. package/tools/lib/release-channel.js +99 -0
  73. package/tools/lib/release-cut.js +822 -0
  74. package/tools/lib/release-finalize.js +521 -0
  75. package/tools/lib/release-policy.js +358 -0
  76. package/tools/lib/release-tag.js +225 -0
  77. package/tools/lib/ship-batch.js +277 -0
  78. package/tools/lib/ship-roles.js +71 -0
  79. package/tools/lib/ship-target-sync.js +181 -0
  80. package/tools/lib/shipguard.js +317 -0
  81. package/tools/lib/shipped-branch.js +56 -0
  82. package/tools/lib/solo.js +213 -0
  83. package/tools/lib/squash.js +515 -0
  84. package/tools/lib/stale-base.js +70 -0
  85. package/tools/lib/stamp.js +740 -0
  86. package/tools/lib/state.js +262 -0
  87. package/tools/lib/teardown.js +83 -0
  88. package/tools/lib/trust-humans.js +104 -0
  89. package/tools/lib/util.js +98 -0
  90. package/tools/lib/wake.js +188 -0
  91. package/tools/lib/workflow-triggers.js +273 -0
  92. package/tools/lib/writes-authority.js +237 -0
  93. package/tools/lib/yaml.js +101 -0
  94. package/bin/cli.js +0 -3
@@ -0,0 +1,55 @@
1
+ # docs-lint (Advisory) — TEMPLATE. Copy me into your repo at
2
+ # .github/workflows/docs-lint.yml. Copy-and-own, exactly like every other
3
+ # workflow template in this directory — nothing calls this workflow remotely,
4
+ # and nothing here updates itself. See templates/README.md.
5
+ #
6
+ # Pairs with templates/docs-lint.mjs, which must ALSO be copied into the repo
7
+ # (see that file's own header for what it checks and why). This workflow does
8
+ # not vendor the script — it runs whatever copy you committed.
9
+ #
10
+ # ADVISORY BY DESIGN (colab-handbook #249): the lint step below runs with
11
+ # `continue-on-error: true`, so a structural finding NEVER blocks a merge on
12
+ # its own — only the annotation step surfaces it as a visible warning on the
13
+ # run. Promoting this to a hard gate is a deliberate, per-repo decision you
14
+ # make later, once you've run it for a while and trust the signal: delete the
15
+ # `continue-on-error: true` line (and, if you want the annotation step to stop
16
+ # being redundant, delete that step too). Do not remove it preemptively — the
17
+ # Issue that specced this job explicitly wants the pilot period first.
18
+ #
19
+ # EDIT POINTS are marked `# EDIT:`.
20
+
21
+ name: docs-lint
22
+
23
+ on:
24
+ push:
25
+ # EDIT: keep only the branches this repo actually has (same note as
26
+ # templates/ci-node.yml — do not drop the trunk branch on a Tier A/C repo).
27
+ branches: [main, dev]
28
+ pull_request:
29
+ branches: [main, dev]
30
+
31
+ jobs:
32
+ docs-lint:
33
+ name: docs-lint (advisory)
34
+ # EDIT: private repo with an org self-hosted runner? Use it instead —
35
+ # see templates/README.md "Runner policy". Public repos stay on
36
+ # ubuntu-latest always (a fork PR must never execute on your own runner).
37
+ runs-on: ubuntu-latest
38
+ steps:
39
+ - uses: actions/checkout@v4
40
+
41
+ - name: Run docs-lint
42
+ id: lint
43
+ # ADVISORY — see the header note above. This is the one line that
44
+ # decides whether a finding can block a merge.
45
+ continue-on-error: true
46
+ # EDIT: path to wherever you copied docs-lint.mjs (defaults to the
47
+ # same relative path this template ships at).
48
+ run: node docs-lint.mjs --repo .
49
+
50
+ - name: Surface the result
51
+ if: always()
52
+ run: |
53
+ if [ "${{ steps.lint.outcome }}" = "failure" ]; then
54
+ echo "::warning::docs-lint found a structural finding — advisory only, review the job log above for detail"
55
+ fi
@@ -0,0 +1,41 @@
1
+ # `docs/gotchas.d/` — one file per gotcha
2
+
3
+ This directory holds long-lived gotchas (bites again, not tied to one
4
+ feature) — one file per gotcha, never a single growing document. That is the
5
+ whole design: no shared counter to collide on, no citation to break when
6
+ something gets renumbered.
7
+
8
+ ## Naming
9
+
10
+ `<issue-number>-<slug>.md` — the issue that surfaced the gotcha, then a short
11
+ slug. Example: `142-worktree-stash-collision.md`.
12
+
13
+ The issue number is the stable id. Citations elsewhere in the repo reference
14
+ the gotcha by this filename (or by issue number), never by a position/section
15
+ number — a filename never needs renumbering when a neighbour is added or
16
+ removed.
17
+
18
+ ## Writing an entry
19
+
20
+ One file, one gotcha. Say what broke, the measured evidence (a number, an
21
+ incident, a specific failure), and the fix or the rule it produced. Keep it
22
+ short enough that the filename plus the first line already tells a reader
23
+ whether it's the one they're looking for.
24
+
25
+ **Append-only.** A new gotcha is a new file — never edit another entry's file
26
+ to extend it, and never insert into the *middle* of the directory's implied
27
+ order (there isn't one; filenames sort however they sort). Two branches
28
+ adding a gotcha each touch a different file, so they never conflict at merge.
29
+
30
+ ## `docs/gotchas.md`, if this repo has one
31
+
32
+ An existing `docs/gotchas.md` is optional and orthogonal to this directory —
33
+ a **curated, hand-maintained topical guide** that points *into* entries here
34
+ (`See docs/gotchas.d/142-slug.md`), grouped however reads best for a human
35
+ skimming for a topic. It is never a second copy of an entry: don't paste a
36
+ gotcha's content into both places. If it drifts out of date, that's a stale
37
+ index, not two wrong documents — the entries in `gotchas.d/` stay the source
38
+ of truth either way.
39
+
40
+ Migration is lazy: an existing `docs/gotchas.md` is not split apart on
41
+ adoption. Only new gotchas from here on go into `gotchas.d/`.
@@ -0,0 +1,58 @@
1
+ # identity-vocabulary — EXAMPLE. Every entry below is invented.
2
+ #
3
+ # ⚠ COPY THIS FILE OUT OF THE REPOSITORY BEFORE YOU EDIT IT.
4
+ # cp templates/identity-vocabulary.example ~/.colab/identity-vocabulary
5
+ # chmod 600 ~/.colab/identity-vocabulary # it is a list of things you consider sensitive
6
+ #
7
+ # A filled-in vocabulary is a precise index of what an organisation does not want found. It
8
+ # is more useful to a reader than any single one of the strings in it, so it never belongs in
9
+ # a repository — public or private, tracked or "just for now". The scanner takes it BY PATH
10
+ # for exactly this reason (templates/pre-commit-identity), and the audit's metadata check
11
+ # reads it the same way.
12
+ #
13
+ # FORMAT
14
+ # • One term per line. Leading and trailing whitespace is ignored.
15
+ # • Blank lines, and lines whose first non-space character is `#`, are comments. A `#`
16
+ # inside a term is part of the term — comments are whole-line only.
17
+ # • Matching is CASE-INSENSITIVE and by SUBSTRING. `build-box-01` matches
18
+ # `ssh://build-box-01.example.invalid/`, and it also matches `my-build-box-01x`.
19
+ # Substring is the deliberate choice: a hostname or handle appears inside URLs, paths
20
+ # and identifiers with no word boundary anywhere near it, and over-blocking has a
21
+ # one-command override while under-blocking has none.
22
+ # • A term shorter than 3 characters is refused as a mistake — it would match everything.
23
+ # • A line starting with `re:` is an extended regular expression, matched against the
24
+ # lower-cased line. Use it for shapes rather than strings; prefer plain terms otherwise.
25
+ #
26
+ # WHAT BELONGS HERE — the classes a secret scanner cannot catch, because none of them is a
27
+ # credential: machine and host names, internal domains, account handles, absolute home
28
+ # paths, customer and partner names, internal service or project code names.
29
+ #
30
+ # WHAT DOES NOT BELONG HERE: passwords, tokens, keys. Those are secrets — your secret
31
+ # scanner already finds them by shape, without being told, and writing one down here to
32
+ # "make sure" copies it into a second file that is easier to forget about.
33
+
34
+ # --- machines and internal hosts -----------------------------------------------------
35
+ build-box-01
36
+ build-box-02
37
+ db-primary.corp.invalid
38
+ vpn.corp.invalid
39
+
40
+ # --- internal domains ----------------------------------------------------------------
41
+ corp.invalid
42
+ intranet.example
43
+
44
+ # --- account handles -----------------------------------------------------------------
45
+ j-doe-ops
46
+ release-bot-7
47
+
48
+ # --- customers and partners (a commercial disclosure, not a technical one) ------------
49
+ Northwind Freight
50
+ Blue Harbour Logistics
51
+
52
+ # --- absolute home paths, as a shape rather than a list ------------------------------
53
+ # Matches /Users/<anyone>/ and /home/<anyone>/ — an absolute path names the person as
54
+ # surely as their handle does, and it is the single most-copied thing in an error message.
55
+ re:/(users|home)/[a-z0-9._-]+/
56
+
57
+ # --- an internal project code name ---------------------------------------------------
58
+ project-lighthouse
@@ -0,0 +1,213 @@
1
+ #!/usr/bin/env node
2
+ // npx launcher — TEMPLATE. Copy me into your repo (e.g. `colab template npx-launcher.mjs --dest
3
+ // bin/launch.mjs`) and point your root package.json's `bin` at the copy. YOU OWN THE COPY.
4
+ //
5
+ // WHAT IT IS FOR. CONVENTIONS.md §6, *Distribution* (#442): every distributed tool installs with
6
+ // `npx`. A PRIVATE repo shipping a COMPILED tool installs as
7
+ //
8
+ // npx github:<org>/<repo>#vX.Y.Z [args…]
9
+ //
10
+ // npx clones the repo at that tag (with the user's own git credentials) and runs this file. This
11
+ // file then: resolves the platform → fetches the one dist ref `refs/tags/dist/vX.Y.Z/<os>-<arch>`
12
+ // (pushed by templates/dist-refs.yml) from the same origin, with the same git, so the same
13
+ // credentials → verifies the binary against that ref's SHA256SUMS → installs it to a stable
14
+ // per-user path → execs it with the arguments it was given. Repository read access is the only
15
+ // lock, exactly as for the source.
16
+ //
17
+ // Node >= 18, zero dependencies, needs `git` on PATH (npx already needed it to clone the repo).
18
+ //
19
+ // WHERE THE VERSION AND ORIGIN COME FROM, in order:
20
+ // 1. env <TOOL>_DIST_VERSION / <TOOL>_DIST_ORIGIN (TOOL upper-cased, non-alnum → `_`)
21
+ // 2. the installing project's record of THIS package: its package.json dependency spec gives
22
+ // the `#vX.Y.Z` committish, and its package-lock.json `resolved` gives the exact git URL
23
+ // npm fetched from — under npx that is the npx cache dir two levels up from this package.
24
+ // A candidate (`#vX.Y.Z-rc.N`) installs the candidate's binaries this way, which a
25
+ // manifest version (`X.Y.Z` for both) could not tell apart.
26
+ // 3. this package's own package.json: `version` → `v<version>`, `repository.url` → origin.
27
+ // Nothing found → it refuses and says which variable to set. It never guesses a version.
28
+ //
29
+ // The checksum lives in the same ref as the binary, so it proves the bytes arrived whole and are
30
+ // the bytes the release run pushed — not that the release run was honest. The trust anchor is
31
+ // write access to the repository, as it is for the source npx just ran.
32
+ //
33
+ // A long-running tool must not run from npx's cache (npm may prune it under a live process).
34
+ // This launcher never does: the binary always runs from the stable install path below, and
35
+ // `--print-path` (consumed by the launcher, never passed on) prints that path so an `init` /
36
+ // `install` step can wire a service to it.
37
+
38
+ import { spawnSync } from 'node:child_process';
39
+ import { createHash } from 'node:crypto';
40
+ import {
41
+ chmodSync, closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, renameSync, rmSync,
42
+ } from 'node:fs';
43
+ import { homedir, tmpdir } from 'node:os';
44
+ import { dirname, join, resolve } from 'node:path';
45
+ import { fileURLToPath } from 'node:url';
46
+
47
+ // EDIT: the binary's name inside each dist ref (dist-refs.yml's `bin` input). null = this
48
+ // package's name without its scope.
49
+ const BIN = null;
50
+
51
+ const VERSION_RE = /^v\d+\.\d+\.\d+(-rc\.\d+)?$/;
52
+ const here = dirname(fileURLToPath(import.meta.url));
53
+
54
+ function die(msg) {
55
+ process.stderr.write(`npx-launcher: ${msg}\n`);
56
+ process.exit(1);
57
+ }
58
+
59
+ function readJson(p) {
60
+ try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
61
+ }
62
+
63
+ /** This package's root: the nearest directory upward holding a package.json. */
64
+ export function packageRoot(start) {
65
+ let d = start;
66
+ for (;;) {
67
+ if (existsSync(join(d, 'package.json'))) return d;
68
+ const up = dirname(d);
69
+ if (up === d) return null;
70
+ d = up;
71
+ }
72
+ }
73
+
74
+ /** The project that installed `pkgDir`: the directory holding the node_modules it lives in. */
75
+ export function installerRoot(pkgDir, name) {
76
+ const parts = name.split('/').length; // @scope/name sits one level deeper
77
+ let d = pkgDir;
78
+ for (let i = 0; i < parts; i++) d = dirname(d);
79
+ return d.endsWith('node_modules') ? dirname(d) : null;
80
+ }
81
+
82
+ /** `git+ssh://…#sha` → `ssh://…`; git itself does not take the `git+` prefix or the committish. */
83
+ export function gitUrl(spec) {
84
+ if (!spec || typeof spec !== 'string') return null;
85
+ let u = spec.replace(/#.*$/, '');
86
+ if (u.startsWith('git+')) u = u.slice(4);
87
+ const gh = u.match(/^(?:github:)?([\w.-]+)\/([\w.-]+?)(?:\.git)?$/); // github:o/r, o/r
88
+ if (gh && !u.includes('://') && !u.includes('@')) return `https://github.com/${gh[1]}/${gh[2]}.git`;
89
+ return u;
90
+ }
91
+
92
+ /** Version + origin, from env, then the installer's record, then this package. Pure but for reads. */
93
+ export function resolveTarget({ env, pkgDir, pkg, read = readJson }) {
94
+ const tool = BIN || String(pkg.name || '').replace(/^@[^/]+\//, '');
95
+ if (!tool) return { error: 'no binary name — set BIN in the launcher or `name` in package.json' };
96
+ const envKey = tool.toUpperCase().replace(/[^A-Z0-9]/g, '_') + '_DIST';
97
+ let version = env[`${envKey}_VERSION`] || null;
98
+ let origin = env[`${envKey}_ORIGIN`] || null;
99
+
100
+ const inst = pkg.name ? installerRoot(pkgDir, pkg.name) : null;
101
+ if (inst) {
102
+ const ipkg = read(join(inst, 'package.json')) || {};
103
+ const spec = (ipkg.dependencies || {})[pkg.name] || (ipkg.devDependencies || {})[pkg.name];
104
+ const committish = typeof spec === 'string' && spec.includes('#') ? spec.slice(spec.lastIndexOf('#') + 1) : null;
105
+ if (!version && committish && VERSION_RE.test(committish)) version = committish;
106
+ const lock = read(join(inst, 'package-lock.json')) || {};
107
+ const entry = (lock.packages || {})[`node_modules/${pkg.name}`];
108
+ if (!origin && entry && entry.resolved) origin = gitUrl(entry.resolved);
109
+ if (!origin && spec) origin = gitUrl(spec);
110
+ }
111
+ if (!version && pkg.version) version = `v${pkg.version}`;
112
+ if (!origin && pkg.repository) origin = gitUrl(typeof pkg.repository === 'string' ? pkg.repository : pkg.repository.url);
113
+
114
+ if (!version || !VERSION_RE.test(version)) {
115
+ return { error: `cannot tell which release to run (got ${version || 'nothing'}) — install with \`npx github:<org>/<repo>#vX.Y.Z\`, or set ${envKey}_VERSION=vX.Y.Z` };
116
+ }
117
+ if (!origin) return { error: `cannot tell which repository to fetch from — set ${envKey}_ORIGIN to its git URL` };
118
+ return { tool, version, origin, envKey };
119
+ }
120
+
121
+ export function platformKey(p = process.platform, a = process.arch) {
122
+ return `${p}-${a}`;
123
+ }
124
+
125
+ export function installDir({ env, tool, version, plat, platform = process.platform }) {
126
+ const base = platform === 'win32'
127
+ ? (env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'))
128
+ : (env.XDG_DATA_HOME || join(homedir(), '.local', 'share'));
129
+ return join(base, tool, version, plat);
130
+ }
131
+
132
+ /** The expected sha256 of `file` in a SHA256SUMS text (`<hex> <name>` or `<hex> *<name>`). */
133
+ export function expectedSum(sumsText, file) {
134
+ for (const line of String(sumsText).split('\n')) {
135
+ const m = line.match(/^([0-9a-f]{64}) [ *](.+)$/);
136
+ if (m && m[2] === file) return m[1];
137
+ }
138
+ return null;
139
+ }
140
+
141
+ function sha256(path) {
142
+ return createHash('sha256').update(readFileSync(path)).digest('hex');
143
+ }
144
+
145
+ function git(args, opts = {}) {
146
+ const r = spawnSync('git', args, { encoding: 'utf8', ...opts });
147
+ if (r.error) die(`git could not run: ${r.error.message}`);
148
+ return r;
149
+ }
150
+
151
+ /** Fetch the dist ref into a throwaway repo, verify, install atomically. Returns the binary path. */
152
+ export function install({ origin, version, plat, exe, dir }) {
153
+ const ref = `refs/tags/dist/${version}/${plat}`;
154
+ const tmp = mkdtempSync(join(tmpdir(), 'npx-launcher-'));
155
+ try {
156
+ git(['init', '-q', '--bare', tmp]);
157
+ const f = git(['-C', tmp, 'fetch', '-q', '--depth', '1', '--no-tags', origin, ref]);
158
+ if (f.status !== 0) {
159
+ die(`could not fetch ${ref} from ${origin} — is ${version} released for ${plat}?\n${(f.stderr || '').trim()}`);
160
+ }
161
+ const sums = git(['-C', tmp, 'cat-file', 'blob', `FETCH_HEAD:SHA256SUMS`]);
162
+ if (sums.status !== 0) die(`${ref} carries no SHA256SUMS — refusing an unverifiable binary`);
163
+ const want = expectedSum(sums.stdout, exe);
164
+ if (!want) die(`${ref}'s SHA256SUMS has no line for ${exe}`);
165
+
166
+ mkdirSync(dir, { recursive: true });
167
+ const part = join(dir, `.${exe}.part-${process.pid}`);
168
+ const fd = openSync(part, 'w');
169
+ let r;
170
+ try {
171
+ r = spawnSync('git', ['-C', tmp, 'cat-file', 'blob', `FETCH_HEAD:${exe}`], { stdio: ['ignore', fd, 'pipe'] });
172
+ } finally { closeSync(fd); }
173
+ if (r.error || r.status !== 0) { rmSync(part, { force: true }); die(`${ref} has no ${exe}`); }
174
+ const got = sha256(part);
175
+ if (got !== want) { rmSync(part, { force: true }); die(`checksum mismatch for ${exe} in ${ref}: expected ${want}, got ${got}`); }
176
+ chmodSync(part, 0o755);
177
+ renameSync(part, join(dir, exe));
178
+ return join(dir, exe);
179
+ } finally {
180
+ rmSync(tmp, { recursive: true, force: true });
181
+ }
182
+ }
183
+
184
+ function main(argv) {
185
+ const pkgDir = packageRoot(here);
186
+ const pkg = (pkgDir && readJson(join(pkgDir, 'package.json'))) || die('cannot find this package\'s package.json');
187
+ const t = resolveTarget({ env: process.env, pkgDir, pkg });
188
+ if (t.error) die(t.error);
189
+ const plat = platformKey();
190
+ const exe = process.platform === 'win32' ? `${t.tool}.exe` : t.tool;
191
+ const dir = installDir({ env: process.env, tool: t.tool, version: t.version, plat });
192
+ const bin = join(dir, exe);
193
+
194
+ // Installed already? A release's dist ref never moves, so an existing binary is that release's
195
+ // — re-fetching on every run would make every invocation a network round-trip.
196
+ if (!existsSync(bin)) install({ origin: t.origin, version: t.version, plat, exe, dir });
197
+
198
+ const args = argv.filter((a) => a !== '--print-path');
199
+ if (args.length !== argv.length) { process.stdout.write(`${bin}\n`); return 0; }
200
+ const r = spawnSync(bin, args, { stdio: 'inherit' });
201
+ if (r.error) die(`could not run ${bin}: ${r.error.message}`);
202
+ if (r.signal) process.kill(process.pid, r.signal);
203
+ return r.status ?? 1;
204
+ }
205
+
206
+ // Run only as the entry point, so a test can import the helpers above. realpath, because npm
207
+ // runs a bin through a symlink in node_modules/.bin.
208
+ function isEntry() {
209
+ try { return realpathSync(resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
210
+ }
211
+ if (process.argv[1] && isEntry()) {
212
+ process.exit(main(process.argv.slice(2)));
213
+ }
@@ -0,0 +1,88 @@
1
+ #!/bin/sh
2
+ # pre-commit-dispatch — run EVERY hooklet in `pre-commit.d/`, in lexical order, and refuse
3
+ # the commit if any of them refused.
4
+ #
5
+ # WHY A DISPATCHER AND NOT ONE MORE LINE IN YOUR EXISTING HOOK. A repo that already guards
6
+ # secrets has a `pre-commit` hook, and the obvious way to add a second check is to append a
7
+ # line to it. That fails in a way nobody notices:
8
+ #
9
+ # - The usual secret-scan hook EXITS EARLY when its scanner is not installed ("gitleaks is
10
+ # not installed — skipping"). Anything appended below that line is skipped with it. The
11
+ # machine that is least protected — no scanner installed — is exactly the machine that
12
+ # silently loses the second check too.
13
+ # - `sh -e`, or `cmd || exit 1` style chaining, stops at the FIRST failure. You fix one
14
+ # finding, commit again, and get blocked by the second. Two round trips to learn what one
15
+ # run already knew.
16
+ # - Every added check makes one file longer and more entangled, so eventually somebody
17
+ # edits it wrongly and the repo *looks* configured while running less than it claims.
18
+ #
19
+ # A directory of independent hooklets fixes all three: each one runs regardless of what the
20
+ # others did, this file collects the statuses and fails if ANY failed, and adding or removing
21
+ # a check is adding or removing a file. Ordering is by filename (`10-`, `20-`, …) and is
22
+ # purely cosmetic — since nothing short-circuits, it only decides the order of the output.
23
+ #
24
+ # IT REFUSES WHEN IT HAS NOTHING TO DISPATCH. An empty (or missing) `pre-commit.d` blocks the
25
+ # commit with instructions instead of passing. A hook that quietly does nothing is the precise
26
+ # failure this whole mechanism exists to prevent: `core.hooksPath` is set, the file is there,
27
+ # the repo looks guarded, and nothing runs. The one moment that state is cheap to fix is the
28
+ # first commit after installing it.
29
+ #
30
+ # INSTALL — into a repo that ALREADY has a pre-commit hook (the normal case):
31
+ # 1. mkdir -p <hooks>/pre-commit.d
32
+ # 2. git mv/cp your existing hook's BODY to <hooks>/pre-commit.d/10-secrets (keep it —
33
+ # it is yours, copy-and-own; this dispatcher never replaces a check, only sequences it)
34
+ # 3. cp templates/pre-commit-dispatch <hooks>/pre-commit
35
+ # 4. cp templates/pre-commit-identity <hooks>/pre-commit.d/20-identity
36
+ # 5. chmod +x <hooks>/pre-commit <hooks>/pre-commit.d/*
37
+ # <hooks> is `git config core.hooksPath` if you set one, else `.git/hooks`. If you use a
38
+ # tracked hooks directory, remember the executable bit is per-clone for anything git does
39
+ # not track — ship an install script that chmods, as this handbook does.
40
+ #
41
+ # ARGUMENT: an optional hooklet directory. With none, it uses `pre-commit.d` beside this
42
+ # file. (The handbook itself passes one, so its own hook can exec the template rather than
43
+ # keep a second copy of it.)
44
+ #
45
+ # EXIT: 0 when every hooklet passed, 1 when any refused or could not be run.
46
+
47
+ set -u
48
+
49
+ self_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
50
+ dir="${1:-$self_dir/pre-commit.d}"
51
+
52
+ if [ ! -d "$dir" ]; then
53
+ printf '%s\n' "❌ pre-commit: no hooklet directory at $dir — commit BLOCKED." >&2
54
+ printf '%s\n' " This dispatcher runs the checks in <hooks>/pre-commit.d/. There are none," >&2
55
+ printf '%s\n' " so nothing would have been checked. See templates/pre-commit-dispatch for" >&2
56
+ printf '%s\n' " the install steps, or restore the hook you replaced." >&2
57
+ exit 1
58
+ fi
59
+
60
+ status=0
61
+ ran=0
62
+
63
+ for hooklet in "$dir"/*; do
64
+ [ -e "$hooklet" ] || continue # unmatched glob
65
+ [ -f "$hooklet" ] || continue # directories, sockets — not ours to run
66
+ case "${hooklet##*/}" in
67
+ .*|*.sample|*.disabled|*.md|*~) continue ;;
68
+ esac
69
+ if [ ! -x "$hooklet" ]; then
70
+ printf '%s\n' "❌ pre-commit: $hooklet is not executable — it would be skipped silently." >&2
71
+ printf '%s\n' " chmod +x it, or rename it to *.disabled if you meant to switch it off." >&2
72
+ status=1
73
+ continue
74
+ fi
75
+ ran=$((ran + 1))
76
+ if ! "$hooklet"; then
77
+ status=1
78
+ fi
79
+ done
80
+
81
+ if [ "$ran" -eq 0 ] && [ "$status" -eq 0 ]; then
82
+ printf '%s\n' "❌ pre-commit: $dir contains no runnable hooklet — commit BLOCKED." >&2
83
+ printf '%s\n' " Nothing was checked. A hook that does nothing is worse than no hook: the" >&2
84
+ printf '%s\n' " repo looks configured. Add your checks there (see templates/pre-commit-dispatch)." >&2
85
+ exit 1
86
+ fi
87
+
88
+ exit "$status"