@futurelastic/colab-handbook 1.16.0-rc.20 → 1.16.0-rc.21

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/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.16.0-rc.20"
36
+ "version": "1.16.0-rc.21"
37
37
  }
@@ -17,8 +17,8 @@
17
17
  // - myapp-{v}.tgz
18
18
  // - MyApp_{v}_aarch64.dmg
19
19
  // optional: [MyApp_{v}_x64.msi] # published when the Release has it (optional key)
20
- // installers: # repo paths, uploaded to /<app>/ with @DOWNLOADS_URL@ stamped (optional key)
21
- // - scripts/install.sh
20
+ // installers: # repo paths, uploaded to /<app>/ with @DOWNLOADS_URL@ and
21
+ // - scripts/install.sh # @DOWNLOADS_REQUIRES@ stamped (optional key)
22
22
  // manifest: .github/downloads/manifest.json # optional key, this is the default path
23
23
  //
24
24
  // Only that subset of YAML is read here (scalars, `- item` lists, `[a, b]` lists, comments): this script has no
@@ -33,6 +33,12 @@
33
33
  // DOWNLOADS_KNOWN_HOSTS_FILE the known-hosts file the workflow wrote from DOWNLOADS_SSH_KNOWN_HOSTS
34
34
  // DOWNLOADS_RESERVED names the site keeps for itself, refused as an app slug (space/comma list)
35
35
  //
36
+ // THE APPS IT REQUIRES (#653) come from manifest.json's optional `requires`: [{"slug": "<app>", "min": "X.Y.Z"}],
37
+ // other apps on the same site that its installers install first. Before anything is sent, every slug must have a final
38
+ // on the site at >= min, and following the site's manifests from them must never lead back here (a cycle). The list
39
+ // is stamped into each installer as `slug:min slug:min` at @DOWNLOADS_REQUIRES@ — an installer of an app that requires
40
+ // anything must carry that placeholder. The installer side (order, once per run, opt-out) is docs/downloads.md.
41
+ //
36
42
  // THE ORDER ON THE SITE, which is what makes a half-finished run harmless:
37
43
  // 1. <X.Y.Z>/ with every file except SHA256SUMS (rsync --ignore-existing: a published file is never replaced)
38
44
  // 2. every file read back over HTTPS against the SHA256SUMS this build computed
@@ -67,6 +73,8 @@ const FINAL_TAG = /^v(\d+\.\d+\.\d+)$/
67
73
  const SLUG = /^[a-z0-9][a-z0-9-]*$/
68
74
  const PLATFORMS = ['macos', 'windows', 'linux']
69
75
  export const PLACEHOLDER = '@DOWNLOADS_URL@'
76
+ export const REQUIRES_PLACEHOLDER = '@DOWNLOADS_REQUIRES@'
77
+ const VERSION = /^\d+\.\d+\.\d+$/
70
78
  export const DEFAULT_MANIFEST = '.github/downloads/manifest.json'
71
79
  /** Names the script itself writes at the app's root; an installer may not take one. */
72
80
  const ROOT_NAMES = new Set(['latest.json', 'manifest.json'])
@@ -228,7 +236,7 @@ export function validateManifest(m) {
228
236
  const problems = []
229
237
  if (m === null || typeof m !== 'object' || Array.isArray(m)) throw new Error('manifest.json is not a JSON object')
230
238
  for (const k of Object.keys(m))
231
- if (!['schema', 'name', 'summary', 'install'].includes(k)) problems.push(`unknown field "${k}"`)
239
+ if (!['schema', 'name', 'summary', 'install', 'requires'].includes(k)) problems.push(`unknown field "${k}"`)
232
240
  if (m.schema !== undefined && m.schema !== 1) problems.push('schema must be 1')
233
241
  if (!isText(m.name, true)) problems.push('name: a one-line text is required')
234
242
  if (!isText(m.summary, true)) problems.push('summary: a one-line text is required')
@@ -253,10 +261,31 @@ export function validateManifest(m) {
253
261
  problems.push(`install.${os}.prompts: a list of texts`)
254
262
  }
255
263
  }
264
+ if (m.requires !== undefined) {
265
+ if (!Array.isArray(m.requires)) problems.push('requires: a list of {"slug", "min"}')
266
+ else {
267
+ const seen = new Set()
268
+ m.requires.forEach((r, i) => {
269
+ const at = `requires[${i}]`
270
+ if (r === null || typeof r !== 'object' || Array.isArray(r)) return problems.push(`${at}: an object {"slug", "min"}`)
271
+ for (const k of Object.keys(r)) if (!['slug', 'min'].includes(k)) problems.push(`${at}.${k}: unknown field`)
272
+ if (typeof r.slug !== 'string' || !SLUG.test(r.slug)) problems.push(`${at}.slug: an app slug, [a-z0-9][a-z0-9-]*`)
273
+ else if (seen.has(r.slug)) problems.push(`${at}.slug: ${r.slug} is listed twice`)
274
+ else seen.add(r.slug)
275
+ if (typeof r.min !== 'string' || !VERSION.test(r.min)) problems.push(`${at}.min: a version X.Y.Z`)
276
+ })
277
+ }
278
+ }
256
279
  if (problems.length) throw new Error(`manifest.json: ${problems.join('; ')}`)
257
280
  return m
258
281
  }
259
282
 
283
+ /** The manifest's `requires`, as given (an empty list when it declares none). */
284
+ export const requiresOf = (manifest) => (Array.isArray(manifest?.requires) ? manifest.requires : [])
285
+
286
+ /** What an installer's @DOWNLOADS_REQUIRES@ becomes: `slug:min slug:min`, in the manifest's order. */
287
+ export const requiresStamp = (manifest) => requiresOf(manifest).map((r) => `${r.slug}:${r.min}`).join(' ')
288
+
260
289
  /** Reads and validates the repo's config + manifest. */
261
290
  export function loadRepo(root, env = {}) {
262
291
  const yml = join(root, '.github', 'project.yml')
@@ -274,11 +303,17 @@ export function loadRepo(root, env = {}) {
274
303
  throw new Error(`${config.manifest} is not JSON: ${error.message}`)
275
304
  }
276
305
  validateManifest(manifest)
306
+ if (requiresOf(manifest).some((r) => r.slug === config.app))
307
+ throw new Error(`${config.manifest}: requires names ${config.app} itself`)
277
308
  for (const p of config.installers) {
278
309
  const f = join(root, p)
279
310
  if (!existsSync(f)) throw new Error(`downloads.installers: ${p} does not exist`)
280
- if (!readFileSync(f, 'utf8').includes(PLACEHOLDER))
281
- throw new Error(`${p} has no ${PLACEHOLDER} to stamp the downloads address into`)
311
+ const text = readFileSync(f, 'utf8')
312
+ if (!text.includes(PLACEHOLDER)) throw new Error(`${p} has no ${PLACEHOLDER} to stamp the downloads address into`)
313
+ if (requiresOf(manifest).length > 0 && !text.includes(REQUIRES_PLACEHOLDER))
314
+ throw new Error(
315
+ `${p} has no ${REQUIRES_PLACEHOLDER}, so it would install ${config.app} without the apps its manifest requires — add the dependency step (docs/downloads.md)`,
316
+ )
282
317
  }
283
318
  return { config, manifest }
284
319
  }
@@ -340,7 +375,8 @@ export async function stage({ tag, assetsDir, outDir, baseUrl, root, config, man
340
375
  const rootFiles = []
341
376
  for (const p of config.installers) {
342
377
  const source = readFileSync(join(root, p), 'utf8')
343
- writeFileSync(join(outDir, basename(p)), source.split(PLACEHOLDER).join(base))
378
+ const stamped = source.split(PLACEHOLDER).join(base).split(REQUIRES_PLACEHOLDER).join(requiresStamp(manifest))
379
+ writeFileSync(join(outDir, basename(p)), stamped)
344
380
  rootFiles.push(basename(p))
345
381
  }
346
382
  writeFileSync(join(outDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
@@ -404,6 +440,49 @@ export async function assertResolves(baseUrl, resolver = lookup) {
404
440
  }
405
441
  }
406
442
 
443
+ /**
444
+ * Checks, reading the site only, that every app `manifest` requires can be installed from it: each slug has a final
445
+ * (`latest.json`) at >= its min and a valid manifest, and following those manifests' own `requires` never leads back
446
+ * to `app` or round any other loop. Throws naming the slug and the reason; returns the slugs visited, in order.
447
+ */
448
+ export async function checkRequires({ app, manifest, baseUrl, fetchImpl = fetch }) {
449
+ const base = siteRoot(baseUrl)
450
+ const visited = []
451
+ const done = new Set()
452
+ async function walk(requires, chain) {
453
+ for (const { slug, min } of requires) {
454
+ const via = chain.join(' → ')
455
+ if (chain.includes(slug)) throw new Error(`requires: a cycle — ${via} → ${slug}; nothing was published`)
456
+ const latest = await readBytes(fetchImpl, `${base}/${slug}/latest.json`)
457
+ if (latest === null) throw new Error(`requires: ${slug} (required by ${via}) has no final on the site — publish it first; nothing was published`)
458
+ let version = null
459
+ try {
460
+ version = JSON.parse(latest.toString('utf8')).version
461
+ } catch {
462
+ version = null
463
+ }
464
+ if (typeof version !== 'string' || !VERSION.test(version))
465
+ throw new Error(`requires: ${base}/${slug}/latest.json names no version; nothing was published`)
466
+ if (compareVersions(version, min) < 0)
467
+ throw new Error(`requires: ${via} needs ${slug} >= ${min}, and the site's newest final of it is ${version}; nothing was published`)
468
+ if (done.has(slug)) continue
469
+ done.add(slug)
470
+ visited.push(slug)
471
+ const raw = await readBytes(fetchImpl, `${base}/${slug}/manifest.json`)
472
+ if (raw === null) throw new Error(`requires: ${slug} has no manifest.json on the site; nothing was published`)
473
+ let theirs
474
+ try {
475
+ theirs = validateManifest(JSON.parse(raw.toString('utf8')))
476
+ } catch (error) {
477
+ throw new Error(`requires: ${slug}'s manifest.json on the site is not valid (${error.message}); nothing was published`)
478
+ }
479
+ await walk(requiresOf(theirs), [...chain, slug])
480
+ }
481
+ }
482
+ await walk(requiresOf(manifest), [app])
483
+ return visited
484
+ }
485
+
407
486
  /**
408
487
  * Uploads a staged tree (see `stage`) in the order the header gives. `dest` is the rsync destination (`user@host:`
409
488
  * in production — the account's root is the app's folder), `sshArgs` the `-e` command line.
@@ -426,9 +505,14 @@ export async function publish({
426
505
  const rootFiles = readdirSync(outDir).filter((n) => n !== 'latest.json' && n !== version && n !== 'manifest.json')
427
506
  rootFiles.sort()
428
507
  rootFiles.push('manifest.json') // installers first, manifest after them, latest.json last
429
- const out = { version, uploaded: [], unchanged: [], skippedLatest: false, dryRun }
508
+ const out = { version, uploaded: [], unchanged: [], skippedLatest: false, dryRun, requires: [] }
430
509
  const slash = /[/:]$/.test(dest) ? '' : '/'
431
510
 
511
+ // Every app this one requires must be installable from the site before anything of this one is on it.
512
+ const manifest = JSON.parse(readFileSync(join(outDir, 'manifest.json'), 'utf8'))
513
+ out.requires = await checkRequires({ app, manifest, baseUrl, fetchImpl })
514
+ if (out.requires.length) log(`requires: ${out.requires.join(', ')} — each on the site at the version needed`)
515
+
432
516
  const remoteSums = await readBytes(fetchImpl, `${root}/${version}/SHA256SUMS`)
433
517
  if (remoteSums !== null && !remoteSums.equals(localSums)) {
434
518
  throw new Error(
@@ -534,7 +618,8 @@ async function main(argv, env) {
534
618
  if (!['check', 'names', 'publish'].includes(command)) throw new Error(usage)
535
619
  const { config, manifest } = loadRepo(root, env)
536
620
  if (command === 'check') {
537
- console.log(`downloads: ${config.app} — ${config.files.length} file(s), ${config.optional.length} optional, ${config.installers.length} installer(s), manifest ${config.manifest} valid`)
621
+ const req = requiresOf(manifest).length ? `, requires ${requiresStamp(manifest)}` : ''
622
+ console.log(`downloads: ${config.app} — ${config.files.length} file(s), ${config.optional.length} optional, ${config.installers.length} installer(s), manifest ${config.manifest} valid${req}`)
538
623
  return 0
539
624
  }
540
625
  if (command === 'names') {
@@ -17,7 +17,8 @@
17
17
  # WHAT IT DOES for a final tag vX.Y.Z whose files are on its GitHub Release: uploads them with rsync over SSH
18
18
  # in the order that keeps a half-finished run harmless — the version folder (with a combined SHA256SUMS last
19
19
  # inside it, written only after every file read back over HTTPS against it), then the installers with the
20
- # site address stamped in, then manifest.json, then latest.json LAST — and reads it all back. A published
20
+ # site address and the manifest's `requires` stamped in (each required app checked on the site first, #653),
21
+ # then manifest.json, then latest.json LAST — and reads it all back. A published
21
22
  # version is immutable: nothing is ever replaced, and a build whose SHA256SUMS differs from the published
22
23
  # one is refused. A re-run of a complete version verifies and sends nothing. NEVER a candidate (-rc.N).
23
24
  #