@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.8
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 +309 -3
- package/README.vi.md +279 -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 +117 -0
- package/templates/release-auto.yml +470 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13746 -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-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 +703 -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,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"
|