@futurelastic/colab-handbook 1.12.0 → 1.13.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.
- package/README.md +248 -213
- package/README.vi.md +252 -186
- package/audit/audit.mjs +193 -10
- package/package.json +7 -1
- package/templates/README.md +30 -2
- package/templates/ci-laravel.yml +102 -21
- package/templates/ci-node.yml +61 -3
- package/templates/ci-python.yml +52 -3
- package/templates/deploy-adapter-portainer.mjs +206 -0
- package/templates/deploy-container-run.mjs +368 -0
- package/templates/deploy-container.yml +219 -0
- package/templates/dist-refs.yml +6 -0
- package/templates/docs-lint.mjs +1 -1
- package/templates/npx-launcher.mjs +118 -20
- package/templates/npx-service.mjs +828 -0
- package/templates/release-auto.yml +341 -32
- package/tools/colab +1902 -278
- package/tools/lib/adopt.js +373 -14
- package/tools/lib/branch-name.js +29 -1
- package/tools/lib/ci-cure.js +522 -31
- package/tools/lib/ci-grant.js +289 -22
- package/tools/lib/ci-wait.js +223 -0
- package/tools/lib/claim-comments.js +13 -64
- package/tools/lib/claim-identity.js +42 -7
- package/tools/lib/codec/claim.d.ts +41 -0
- package/tools/lib/codec/claim.js +153 -0
- package/tools/lib/codec/decision.d.ts +29 -0
- package/tools/lib/codec/decision.js +81 -0
- package/tools/lib/codec/grants.d.ts +82 -0
- package/tools/lib/codec/grants.js +268 -0
- package/tools/lib/codec/hold.d.ts +26 -0
- package/tools/lib/codec/hold.js +152 -0
- package/tools/lib/codec/index.d.ts +21 -0
- package/tools/lib/codec/index.js +32 -0
- package/tools/lib/codec/labels.d.ts +65 -0
- package/tools/lib/codec/labels.js +723 -0
- package/tools/lib/codec/markers.d.ts +35 -0
- package/tools/lib/codec/markers.js +138 -0
- package/tools/lib/codec/release.d.ts +17 -0
- package/tools/lib/codec/release.js +69 -0
- package/tools/lib/codec/samples.json +778 -0
- package/tools/lib/codeowners.js +68 -4
- package/tools/lib/container-close.js +38 -0
- package/tools/lib/cure-diff.js +198 -9
- package/tools/lib/decision-record.js +15 -39
- package/tools/lib/docs-only.js +15 -1
- package/tools/lib/exposure-shape.js +42 -8
- package/tools/lib/git.js +324 -42
- package/tools/lib/group-labels.js +65 -0
- package/tools/lib/install-check.js +14 -8
- package/tools/lib/install-route.js +139 -0
- package/tools/lib/instruction-file.js +1 -0
- package/tools/lib/labels.js +22 -647
- package/tools/lib/local-adopt.js +8 -4
- package/tools/lib/migration-grant.js +206 -104
- package/tools/lib/place.js +2 -2
- package/tools/lib/release-cut.js +199 -25
- package/tools/lib/release-finalize.js +111 -23
- package/tools/lib/release-policy.js +130 -22
- package/tools/lib/release-runner.js +125 -0
- package/tools/lib/release-tag.js +3 -1
- package/tools/lib/scratch-dirs.js +118 -0
- package/tools/lib/ship-batch.js +36 -1
- package/tools/lib/ship-human-door.js +76 -0
- package/tools/lib/stamp.js +7 -0
- package/tools/lib/tracker-fake.js +195 -0
- package/tools/lib/tracker-github.js +106 -0
- package/tools/lib/tracker-scenarios.json +206 -0
- package/tools/lib/tracker.js +64 -0
- package/tools/lib/tree-green.js +88 -0
- package/tools/lib/util.js +17 -1
- package/tools/lib/verify-runs.js +104 -0
- package/tools/lib/wake.js +8 -90
- package/tools/lib/workflow-triggers.js +48 -0
|
@@ -26,6 +26,14 @@
|
|
|
26
26
|
// 3. this package's own package.json: `version` → `v<version>`, `repository.url` → origin.
|
|
27
27
|
// Nothing found → it refuses and says which variable to set. It never guesses a version.
|
|
28
28
|
//
|
|
29
|
+
// A RELEASE CHANNEL instead of a version (#465): `npx github:<org>/<repo>#stable` (or `#next`,
|
|
30
|
+
// the channel branches of CONVENTIONS.md §6, #445). A channel is never an install key — dist
|
|
31
|
+
// refs are keyed by version. The launcher asks the same origin, with the same git, which release
|
|
32
|
+
// tag sits on the commit npx installed (the sha in the lockfile's `resolved`; the channel's live
|
|
33
|
+
// tip only when no sha is recorded) and installs exactly that version: `stable` → the highest
|
|
34
|
+
// final there, `next` → the highest release tag there. No release tag on that commit → it
|
|
35
|
+
// refuses. Any other branch committish (`#main`) still refuses, as before.
|
|
36
|
+
//
|
|
29
37
|
// The checksum lives in the same ref as the binary, so it proves the bytes arrived whole and are
|
|
30
38
|
// the bytes the release run pushed — not that the release run was honest. The trust anchor is
|
|
31
39
|
// write access to the repository, as it is for the source npx just ran.
|
|
@@ -33,7 +41,8 @@
|
|
|
33
41
|
// A long-running tool must not run from npx's cache (npm may prune it under a live process).
|
|
34
42
|
// This launcher never does: the binary always runs from the stable install path below, and
|
|
35
43
|
// `--print-path` (consumed by the launcher, never passed on) prints that path so an `init` /
|
|
36
|
-
// `install` step can wire a service to it.
|
|
44
|
+
// `install` step can wire a service to it. A per-machine SERVICE uses templates/npx-service.mjs,
|
|
45
|
+
// which imports this file as a library for its `init` / `update` / `rollback` verbs (#465).
|
|
37
46
|
|
|
38
47
|
import { spawnSync } from 'node:child_process';
|
|
39
48
|
import { createHash } from 'node:crypto';
|
|
@@ -41,14 +50,15 @@ import {
|
|
|
41
50
|
chmodSync, closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, renameSync, rmSync,
|
|
42
51
|
} from 'node:fs';
|
|
43
52
|
import { homedir, tmpdir } from 'node:os';
|
|
44
|
-
import { dirname, join, resolve } from 'node:path';
|
|
53
|
+
import { basename, dirname, join, resolve } from 'node:path';
|
|
45
54
|
import { fileURLToPath } from 'node:url';
|
|
46
55
|
|
|
47
56
|
// EDIT: the binary's name inside each dist ref (dist-refs.yml's `bin` input). null = this
|
|
48
57
|
// package's name without its scope.
|
|
49
58
|
const BIN = null;
|
|
50
59
|
|
|
51
|
-
const VERSION_RE = /^v\d+\.\d+\.\d+(-rc\.\d+)?$/;
|
|
60
|
+
export const VERSION_RE = /^v\d+\.\d+\.\d+(-rc\.\d+)?$/;
|
|
61
|
+
export const CHANNELS = ['next', 'stable'];
|
|
52
62
|
const here = dirname(fileURLToPath(import.meta.url));
|
|
53
63
|
|
|
54
64
|
function die(msg) {
|
|
@@ -96,6 +106,8 @@ export function resolveTarget({ env, pkgDir, pkg, read = readJson }) {
|
|
|
96
106
|
const envKey = tool.toUpperCase().replace(/[^A-Z0-9]/g, '_') + '_DIST';
|
|
97
107
|
let version = env[`${envKey}_VERSION`] || null;
|
|
98
108
|
let origin = env[`${envKey}_ORIGIN`] || null;
|
|
109
|
+
let channel = null;
|
|
110
|
+
let sha = null;
|
|
99
111
|
|
|
100
112
|
const inst = pkg.name ? installerRoot(pkgDir, pkg.name) : null;
|
|
101
113
|
if (inst) {
|
|
@@ -103,11 +115,22 @@ export function resolveTarget({ env, pkgDir, pkg, read = readJson }) {
|
|
|
103
115
|
const spec = (ipkg.dependencies || {})[pkg.name] || (ipkg.devDependencies || {})[pkg.name];
|
|
104
116
|
const committish = typeof spec === 'string' && spec.includes('#') ? spec.slice(spec.lastIndexOf('#') + 1) : null;
|
|
105
117
|
if (!version && committish && VERSION_RE.test(committish)) version = committish;
|
|
118
|
+
if (!version && committish && CHANNELS.includes(committish)) channel = committish;
|
|
106
119
|
const lock = read(join(inst, 'package-lock.json')) || {};
|
|
107
120
|
const entry = (lock.packages || {})[`node_modules/${pkg.name}`];
|
|
121
|
+
if (entry && typeof entry.resolved === 'string') {
|
|
122
|
+
const m = entry.resolved.match(/#([0-9a-f]{40})$/);
|
|
123
|
+
if (m) sha = m[1];
|
|
124
|
+
}
|
|
108
125
|
if (!origin && entry && entry.resolved) origin = gitUrl(entry.resolved);
|
|
109
126
|
if (!origin && spec) origin = gitUrl(spec);
|
|
110
127
|
}
|
|
128
|
+
// A channel is resolved to a version later, against the origin (resolveChannel) — never from
|
|
129
|
+
// the manifest, whose version names the final even at `#next`.
|
|
130
|
+
if (!version && channel) {
|
|
131
|
+
if (!origin) return { error: `cannot tell which repository to fetch from — set ${envKey}_ORIGIN to its git URL` };
|
|
132
|
+
return { tool, channel, sha, origin, envKey };
|
|
133
|
+
}
|
|
111
134
|
if (!version && pkg.version) version = `v${pkg.version}`;
|
|
112
135
|
if (!origin && pkg.repository) origin = gitUrl(typeof pkg.repository === 'string' ? pkg.repository : pkg.repository.url);
|
|
113
136
|
|
|
@@ -138,54 +161,127 @@ export function expectedSum(sumsText, file) {
|
|
|
138
161
|
return null;
|
|
139
162
|
}
|
|
140
163
|
|
|
164
|
+
/** `git ls-remote` output → { heads: {name: sha}, tags: {name: sha} }, annotated tags peeled. */
|
|
165
|
+
export function parseLsRemote(text) {
|
|
166
|
+
const heads = {};
|
|
167
|
+
const tags = {};
|
|
168
|
+
for (const line of String(text || '').split('\n')) {
|
|
169
|
+
const m = line.match(/^([0-9a-f]{40})\s+refs\/(heads|tags)\/(.+)$/);
|
|
170
|
+
if (!m) continue;
|
|
171
|
+
const [, sha, kind, name] = m;
|
|
172
|
+
if (kind === 'heads') { heads[name] = sha; continue; }
|
|
173
|
+
if (name.endsWith('^{}')) tags[name.slice(0, -3)] = sha; // the peeled line wins
|
|
174
|
+
else if (!(name in tags)) tags[name] = sha;
|
|
175
|
+
}
|
|
176
|
+
return { heads, tags };
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** SemVer order over release tags: a final outranks its own candidates. */
|
|
180
|
+
export function compareVersions(a, b) {
|
|
181
|
+
const p = (v) => {
|
|
182
|
+
const m = String(v).match(/^v(\d+)\.(\d+)\.(\d+)(?:-rc\.(\d+))?$/);
|
|
183
|
+
return m ? [+m[1], +m[2], +m[3], m[4] === undefined ? Infinity : +m[4]] : [-1, -1, -1, -1];
|
|
184
|
+
};
|
|
185
|
+
const x = p(a); const y = p(b);
|
|
186
|
+
for (let i = 0; i < 4; i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
|
|
187
|
+
return 0;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* Which release a channel names. `at` = the commit to read (the sha npx installed); absent, the
|
|
192
|
+
* channel branch's tip. `stable` → highest final tagged there; `next` → highest release tag there.
|
|
193
|
+
* Returns { version, sha } or { error } — never a guess.
|
|
194
|
+
*/
|
|
195
|
+
export function channelVersion(lsText, channel, at = null) {
|
|
196
|
+
if (!CHANNELS.includes(channel)) return { error: `${channel} is not a release channel (${CHANNELS.join(', ')})` };
|
|
197
|
+
const { heads, tags } = parseLsRemote(lsText);
|
|
198
|
+
const sha = at || heads[channel];
|
|
199
|
+
if (!sha) return { error: `the origin has no \`${channel}\` channel branch — install a version (#vX.Y.Z) instead` };
|
|
200
|
+
const here = Object.keys(tags)
|
|
201
|
+
.filter((t) => tags[t] === sha && VERSION_RE.test(t))
|
|
202
|
+
.filter((t) => channel === 'next' || !t.includes('-rc.'))
|
|
203
|
+
.sort(compareVersions);
|
|
204
|
+
if (!here.length) return { error: `\`${channel}\` is at ${sha.slice(0, 12)}, which carries no ${channel === 'stable' ? 'final ' : ''}release tag — refusing to guess a version` };
|
|
205
|
+
return { version: here[here.length - 1], sha };
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/** Ask the origin (same git, same URL, so the same credentials) which version a channel names. */
|
|
209
|
+
export function resolveChannel({ origin, channel, at = null, run = git }) {
|
|
210
|
+
const r = run(['ls-remote', origin, `refs/heads/${channel}`, 'refs/tags/v*']);
|
|
211
|
+
if (r.status !== 0) return { error: `could not read ${origin}: ${(r.stderr || '').trim()}` };
|
|
212
|
+
return channelVersion(r.stdout, channel, at);
|
|
213
|
+
}
|
|
214
|
+
|
|
141
215
|
function sha256(path) {
|
|
142
216
|
return createHash('sha256').update(readFileSync(path)).digest('hex');
|
|
143
217
|
}
|
|
144
218
|
|
|
145
219
|
function git(args, opts = {}) {
|
|
146
220
|
const r = spawnSync('git', args, { encoding: 'utf8', ...opts });
|
|
147
|
-
if (r.error)
|
|
221
|
+
if (r.error) throw new Error(`git could not run: ${r.error.message}`);
|
|
148
222
|
return r;
|
|
149
223
|
}
|
|
150
224
|
|
|
151
|
-
/**
|
|
152
|
-
|
|
225
|
+
/**
|
|
226
|
+
* Fetch ONE file out of the dist ref `refs/tags/dist/<version>/<plat>` into a throwaway repo,
|
|
227
|
+
* verify it against that ref's SHA256SUMS, and move it into place at `dest` atomically. Returns
|
|
228
|
+
* `dest`. Throws on any refusal. `plat` is `<os>-<arch>` for a binary, or `any` for a
|
|
229
|
+
* platform-neutral artifact (a prebuilt JS app's tarball — templates/npx-service.mjs KIND 'dist').
|
|
230
|
+
*/
|
|
231
|
+
export function fetchDistFile({ origin, version, plat, file, dest, mode = 0o755 }) {
|
|
153
232
|
const ref = `refs/tags/dist/${version}/${plat}`;
|
|
233
|
+
const fail = (msg) => { throw new Error(msg); };
|
|
154
234
|
const tmp = mkdtempSync(join(tmpdir(), 'npx-launcher-'));
|
|
155
235
|
try {
|
|
156
236
|
git(['init', '-q', '--bare', tmp]);
|
|
157
237
|
const f = git(['-C', tmp, 'fetch', '-q', '--depth', '1', '--no-tags', origin, ref]);
|
|
158
238
|
if (f.status !== 0) {
|
|
159
|
-
|
|
239
|
+
fail(`could not fetch ${ref} from ${origin} — is ${version} released for ${plat}?\n${(f.stderr || '').trim()}`);
|
|
160
240
|
}
|
|
161
241
|
const sums = git(['-C', tmp, 'cat-file', 'blob', `FETCH_HEAD:SHA256SUMS`]);
|
|
162
|
-
if (sums.status !== 0)
|
|
163
|
-
const want = expectedSum(sums.stdout,
|
|
164
|
-
if (!want)
|
|
242
|
+
if (sums.status !== 0) fail(`${ref} carries no SHA256SUMS — refusing an unverifiable download`);
|
|
243
|
+
const want = expectedSum(sums.stdout, file);
|
|
244
|
+
if (!want) fail(`${ref}'s SHA256SUMS has no line for ${file}`);
|
|
165
245
|
|
|
246
|
+
const dir = dirname(dest);
|
|
166
247
|
mkdirSync(dir, { recursive: true });
|
|
167
|
-
const part = join(dir, `.${
|
|
248
|
+
const part = join(dir, `.${basename(dest)}.part-${process.pid}`);
|
|
168
249
|
const fd = openSync(part, 'w');
|
|
169
250
|
let r;
|
|
170
251
|
try {
|
|
171
|
-
r = spawnSync('git', ['-C', tmp, 'cat-file', 'blob', `FETCH_HEAD:${
|
|
252
|
+
r = spawnSync('git', ['-C', tmp, 'cat-file', 'blob', `FETCH_HEAD:${file}`], { stdio: ['ignore', fd, 'pipe'] });
|
|
172
253
|
} finally { closeSync(fd); }
|
|
173
|
-
if (r.error || r.status !== 0) { rmSync(part, { force: true });
|
|
254
|
+
if (r.error || r.status !== 0) { rmSync(part, { force: true }); fail(`${ref} has no ${file}`); }
|
|
174
255
|
const got = sha256(part);
|
|
175
|
-
if (got !== want) { rmSync(part, { force: true });
|
|
176
|
-
chmodSync(part,
|
|
177
|
-
renameSync(part,
|
|
178
|
-
return
|
|
256
|
+
if (got !== want) { rmSync(part, { force: true }); fail(`checksum mismatch for ${file} in ${ref}: expected ${want}, got ${got}`); }
|
|
257
|
+
chmodSync(part, mode);
|
|
258
|
+
renameSync(part, dest);
|
|
259
|
+
return dest;
|
|
179
260
|
} finally {
|
|
180
261
|
rmSync(tmp, { recursive: true, force: true });
|
|
181
262
|
}
|
|
182
263
|
}
|
|
183
264
|
|
|
184
|
-
|
|
185
|
-
|
|
265
|
+
/**
|
|
266
|
+
* Fetch the platform's binary from its dist ref, verify, install atomically. Returns the binary
|
|
267
|
+
* path. Throws on any refusal (main() turns that into a message + exit 1; the service template
|
|
268
|
+
* reports it).
|
|
269
|
+
*/
|
|
270
|
+
export function install({ origin, version, plat, exe, dir }) {
|
|
271
|
+
return fetchDistFile({ origin, version, plat, file: exe, dest: join(dir, exe) });
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
export function main(argv, start = here) {
|
|
275
|
+
const pkgDir = packageRoot(start);
|
|
186
276
|
const pkg = (pkgDir && readJson(join(pkgDir, 'package.json'))) || die('cannot find this package\'s package.json');
|
|
187
277
|
const t = resolveTarget({ env: process.env, pkgDir, pkg });
|
|
188
278
|
if (t.error) die(t.error);
|
|
279
|
+
if (!t.version) {
|
|
280
|
+
let c;
|
|
281
|
+
try { c = resolveChannel({ origin: t.origin, channel: t.channel, at: t.sha }); } catch (e) { die(e.message); }
|
|
282
|
+
if (c.error) die(c.error);
|
|
283
|
+
t.version = c.version;
|
|
284
|
+
}
|
|
189
285
|
const plat = platformKey();
|
|
190
286
|
const exe = process.platform === 'win32' ? `${t.tool}.exe` : t.tool;
|
|
191
287
|
const dir = installDir({ env: process.env, tool: t.tool, version: t.version, plat });
|
|
@@ -193,7 +289,9 @@ function main(argv) {
|
|
|
193
289
|
|
|
194
290
|
// Installed already? A release's dist ref never moves, so an existing binary is that release's
|
|
195
291
|
// — re-fetching on every run would make every invocation a network round-trip.
|
|
196
|
-
if (!existsSync(bin))
|
|
292
|
+
if (!existsSync(bin)) {
|
|
293
|
+
try { install({ origin: t.origin, version: t.version, plat, exe, dir }); } catch (e) { die(e.message); }
|
|
294
|
+
}
|
|
197
295
|
|
|
198
296
|
const args = argv.filter((a) => a !== '--print-path');
|
|
199
297
|
if (args.length !== argv.length) { process.stdout.write(`${bin}\n`); return 0; }
|