@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
|
@@ -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@
|
|
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
|
-
|
|
281
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
#
|