@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.1

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 (73) hide show
  1. package/README.md +243 -213
  2. package/README.vi.md +246 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +6 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1691 -254
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +203 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +4 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +151 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +716 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +762 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +303 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +106 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/stamp.js +7 -0
  65. package/tools/lib/tracker-fake.js +195 -0
  66. package/tools/lib/tracker-github.js +106 -0
  67. package/tools/lib/tracker-scenarios.json +206 -0
  68. package/tools/lib/tracker.js +64 -0
  69. package/tools/lib/tree-green.js +88 -0
  70. package/tools/lib/util.js +17 -1
  71. package/tools/lib/verify-runs.js +104 -0
  72. package/tools/lib/wake.js +8 -90
  73. 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) die(`git could not run: ${r.error.message}`);
221
+ if (r.error) throw new Error(`git could not run: ${r.error.message}`);
148
222
  return r;
149
223
  }
150
224
 
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 }) {
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
- die(`could not fetch ${ref} from ${origin} — is ${version} released for ${plat}?\n${(f.stderr || '').trim()}`);
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) 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}`);
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, `.${exe}.part-${process.pid}`);
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:${exe}`], { stdio: ['ignore', fd, 'pipe'] });
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 }); die(`${ref} has no ${exe}`); }
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 }); 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);
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
- function main(argv) {
185
- const pkgDir = packageRoot(here);
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)) install({ origin: t.origin, version: t.version, plat, exe, dir });
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; }