@futurelastic/colab-handbook 1.16.0-rc.2 → 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.
@@ -0,0 +1,659 @@
1
+ #!/usr/bin/env node
2
+ // Publish one FINAL version's files to a self-hosted downloads site — TEMPLATE (colab-handbook #648).
3
+ // Copy me into your repo beside the workflow (`colab template publish-downloads.mjs --dest
4
+ // .github/downloads/publish-downloads.mjs`); from then on YOU OWN THIS FILE. Node >= 18, zero dependencies,
5
+ // shells out to `rsync` (and `ssh` through it). Docs: docs/downloads.md in the handbook.
6
+ //
7
+ // node publish-downloads.mjs check validate the downloads: block and the manifest
8
+ // node publish-downloads.mjs names vX.Y.Z the Release files this publishes, one per line
9
+ // node publish-downloads.mjs publish vX.Y.Z <assetsDir> [--dry-run] stage, upload, read back
10
+ // (every command also takes --root <repo root>, default the current directory)
11
+ //
12
+ // WHAT IS PUBLISHED comes from the repo's `.github/project.yml`:
13
+ //
14
+ // downloads:
15
+ // app: myapp # the app's folder on the site: [a-z0-9][a-z0-9-]*
16
+ // files: # every final carries these; {v} is X.Y.Z
17
+ // - myapp-{v}.tgz
18
+ // - MyApp_{v}_aarch64.dmg
19
+ // optional: [MyApp_{v}_x64.msi] # published when the Release has it (optional key)
20
+ // installers: # repo paths, uploaded to /<app>/ with @DOWNLOADS_URL@ and
21
+ // - scripts/install.sh # @DOWNLOADS_REQUIRES@ stamped (optional key)
22
+ // manifest: .github/downloads/manifest.json # optional key, this is the default path
23
+ //
24
+ // Only that subset of YAML is read here (scalars, `- item` lists, `[a, b]` lists, comments): this script has no
25
+ // YAML library on purpose, and refuses — naming the line — anything else inside the block.
26
+ //
27
+ // EVERYTHING ABOUT THE SITE COMES FROM THE ENVIRONMENT; nothing about it is written in the repository:
28
+ //
29
+ // DOWNLOADS_URL the site's root address (a repo variable); /<app> is appended here
30
+ // DOWNLOADS_SSH_HOST/PORT/USER where rsync goes (repo secrets). The account is restricted to the app's
31
+ // folder server-side and cannot delete: its root IS /<app>/
32
+ // DOWNLOADS_KEY_FILE the private key file the workflow wrote from DOWNLOADS_SSH_KEY
33
+ // DOWNLOADS_KNOWN_HOSTS_FILE the known-hosts file the workflow wrote from DOWNLOADS_SSH_KNOWN_HOSTS
34
+ // DOWNLOADS_RESERVED names the site keeps for itself, refused as an app slug (space/comma list)
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
+ //
42
+ // THE ORDER ON THE SITE, which is what makes a half-finished run harmless:
43
+ // 1. <X.Y.Z>/ with every file except SHA256SUMS (rsync --ignore-existing: a published file is never replaced)
44
+ // 2. every file read back over HTTPS against the SHA256SUMS this build computed
45
+ // 3. <X.Y.Z>/SHA256SUMS (its presence = the folder is complete)
46
+ // 4. the installers (address stamped in), then manifest.json
47
+ // 5. latest.json LAST (unless the site already names a newer version)
48
+ // 6. SHA256SUMS and every file sent in 4–5 read back from the site
49
+ // A published version is immutable: a folder whose SHA256SUMS differs from this build's is an error and nothing is
50
+ // changed. A complete folder is verified and left alone; a partial one gets only its missing files. Installers,
51
+ // manifest.json and latest.json are sent only when the site's copy differs, so a re-run is a verified no-op.
52
+ // Never a candidate: the tag must be `vX.Y.Z`.
53
+ import { spawnSync } from 'node:child_process'
54
+ import { createHash } from 'node:crypto'
55
+ import { lookup } from 'node:dns/promises'
56
+ import {
57
+ copyFileSync,
58
+ createReadStream,
59
+ existsSync,
60
+ mkdirSync,
61
+ mkdtempSync,
62
+ readFileSync,
63
+ readdirSync,
64
+ realpathSync,
65
+ statSync,
66
+ writeFileSync,
67
+ } from 'node:fs'
68
+ import { tmpdir } from 'node:os'
69
+ import { basename, join, resolve } from 'node:path'
70
+ import { pathToFileURL } from 'node:url'
71
+
72
+ const FINAL_TAG = /^v(\d+\.\d+\.\d+)$/
73
+ const SLUG = /^[a-z0-9][a-z0-9-]*$/
74
+ const PLATFORMS = ['macos', 'windows', 'linux']
75
+ export const PLACEHOLDER = '@DOWNLOADS_URL@'
76
+ export const REQUIRES_PLACEHOLDER = '@DOWNLOADS_REQUIRES@'
77
+ const VERSION = /^\d+\.\d+\.\d+$/
78
+ export const DEFAULT_MANIFEST = '.github/downloads/manifest.json'
79
+ /** Names the script itself writes at the app's root; an installer may not take one. */
80
+ const ROOT_NAMES = new Set(['latest.json', 'manifest.json'])
81
+
82
+ /** The version of a final tag. A candidate (`vX.Y.Z-rc.N`) and anything else is refused. */
83
+ export function finalVersion(tag) {
84
+ const m = typeof tag === 'string' ? FINAL_TAG.exec(tag) : null
85
+ if (!m)
86
+ throw new Error(
87
+ `${JSON.stringify(tag)} is not a final tag: expected vX.Y.Z (a candidate is never published)`,
88
+ )
89
+ return m[1]
90
+ }
91
+
92
+ // ── the downloads: block ─────────────────────────────────────────────────────────────────────────
93
+
94
+ function scalar(raw, where) {
95
+ let s = raw.trim()
96
+ if (s.startsWith('"') || s.startsWith("'")) {
97
+ const q = s[0]
98
+ const end = s.indexOf(q, 1)
99
+ if (end < 0) throw new Error(`${where}: unterminated quote`)
100
+ const rest = s.slice(end + 1).trim()
101
+ if (rest && !rest.startsWith('#')) throw new Error(`${where}: text after the closing quote`)
102
+ return s.slice(1, end)
103
+ }
104
+ const hash = s.search(/\s#/)
105
+ if (hash >= 0) s = s.slice(0, hash).trim()
106
+ if (s.startsWith('#')) s = ''
107
+ return s
108
+ }
109
+
110
+ function flowList(raw, where) {
111
+ const s = scalar(raw.replace(/\s+#.*$/, ''), where)
112
+ if (!s.startsWith('[') || !s.endsWith(']')) return null
113
+ const inner = s.slice(1, -1).trim()
114
+ return inner ? inner.split(',').map((x) => scalar(x, where)) : []
115
+ }
116
+
117
+ /**
118
+ * The `downloads:` block of project.yml text, as a plain object — or null when the repo declares none. Reads the
119
+ * subset documented in the header and throws, naming the line, on anything else inside the block.
120
+ */
121
+ export function parseDownloadsBlock(text) {
122
+ const lines = text.split(/\r?\n/)
123
+ const start = lines.findIndex((l) => /^downloads:\s*(#.*)?$/.test(l))
124
+ if (start < 0) {
125
+ const inline = lines.findIndex((l) => /^downloads:\s*\S/.test(l))
126
+ if (inline >= 0)
127
+ throw new Error(
128
+ `project.yml line ${inline + 1}: write downloads: as a block (one key per line), not inline`,
129
+ )
130
+ return null
131
+ }
132
+ const out = {}
133
+ let keyIndent = null
134
+ let listKey = null
135
+ for (let i = start + 1; i < lines.length; i++) {
136
+ const line = lines[i]
137
+ const where = `project.yml line ${i + 1}`
138
+ if (/^\s*(#.*)?$/.test(line)) continue
139
+ const indent = line.match(/^ */)[0].length
140
+ if (indent === 0) break // the next top-level key ends the block
141
+ if (line.includes('\t')) throw new Error(`${where}: a tab in the downloads: block`)
142
+ const body = line.slice(indent)
143
+ if (keyIndent === null) keyIndent = indent
144
+ if (indent > keyIndent && listKey && body.startsWith('- ')) {
145
+ out[listKey].push(scalar(body.slice(2), where))
146
+ continue
147
+ }
148
+ if (indent === keyIndent && listKey && body.startsWith('- ')) {
149
+ // `- item` at the key's own indent is valid YAML for a list under that key
150
+ out[listKey].push(scalar(body.slice(2), where))
151
+ continue
152
+ }
153
+ const m = indent === keyIndent ? /^([a-z][a-z-]*):(.*)$/.exec(body) : null
154
+ if (!m) throw new Error(`${where}: not a form this script reads inside downloads: (see its header)`)
155
+ const [, key, rest] = m
156
+ if (key in out) throw new Error(`${where}: downloads.${key} is given twice`)
157
+ const value = scalar(rest, where)
158
+ if (value === '') {
159
+ out[key] = []
160
+ listKey = key
161
+ continue
162
+ }
163
+ listKey = null
164
+ const list = flowList(rest, where)
165
+ out[key] = list ?? value
166
+ }
167
+ return out
168
+ }
169
+
170
+ const KEYS = ['app', 'files', 'optional', 'installers', 'manifest']
171
+
172
+ function fileName(pattern, where) {
173
+ if (typeof pattern !== 'string' || pattern === '') throw new Error(`${where}: an empty name`)
174
+ if (/[/\\]/.test(pattern) || pattern.startsWith('.') || pattern === 'SHA256SUMS')
175
+ throw new Error(`${where}: ${JSON.stringify(pattern)} is not a plain file name`)
176
+ return pattern
177
+ }
178
+
179
+ /** Validates a parsed block (see parseDownloadsBlock) and returns it normalised. */
180
+ export function readConfig(block, { reserved = [] } = {}) {
181
+ if (!block) throw new Error('.github/project.yml has no downloads: block — this repo publishes nothing')
182
+ for (const k of Object.keys(block))
183
+ if (!KEYS.includes(k)) throw new Error(`downloads.${k} is not a key (known: ${KEYS.join(', ')})`)
184
+ const app = block.app
185
+ if (typeof app !== 'string' || app === '') throw new Error('downloads.app is required')
186
+ if (app.startsWith('_')) throw new Error(`downloads.app ${JSON.stringify(app)}: names starting with _ belong to the site`)
187
+ if (!SLUG.test(app)) throw new Error(`downloads.app ${JSON.stringify(app)} is not a slug: [a-z0-9][a-z0-9-]*`)
188
+ if (reserved.includes(app)) throw new Error(`downloads.app ${JSON.stringify(app)} is a name the site reserves for itself`)
189
+ const list = (k, required) => {
190
+ const v = block[k]
191
+ if (v === undefined && !required) return []
192
+ if (!Array.isArray(v) || (required && v.length === 0))
193
+ throw new Error(`downloads.${k} must be a ${required ? 'non-empty ' : ''}list`)
194
+ return v
195
+ }
196
+ const files = list('files', true).map((p) => fileName(p, 'downloads.files'))
197
+ const optional = list('optional', false).map((p) => fileName(p, 'downloads.optional'))
198
+ const all = [...files, ...optional]
199
+ const dup = all.find((n, i) => all.indexOf(n) !== i)
200
+ if (dup) throw new Error(`downloads: ${dup} is listed twice`)
201
+ const installers = list('installers', false)
202
+ const seen = new Set()
203
+ for (const p of installers) {
204
+ const b = basename(String(p))
205
+ if (!p || p.startsWith('/') || String(p).split(/[/\\]/).includes('..'))
206
+ throw new Error(`downloads.installers: ${JSON.stringify(p)} is not a path inside the repo`)
207
+ if (ROOT_NAMES.has(b) || /^\d+\.\d+\.\d+$/.test(b) || seen.has(b))
208
+ throw new Error(`downloads.installers: ${b} would collide with another file at the app's root`)
209
+ seen.add(b)
210
+ }
211
+ const manifest = block.manifest ?? DEFAULT_MANIFEST
212
+ if (typeof manifest !== 'string' || manifest.startsWith('/') || manifest.split(/[/\\]/).includes('..'))
213
+ throw new Error('downloads.manifest must be a path inside the repo')
214
+ return { app, files, optional, installers, manifest }
215
+ }
216
+
217
+ export const namesFor = (patterns, v) => patterns.map((p) => p.split('{v}').join(v))
218
+
219
+ // ── manifest.json ────────────────────────────────────────────────────────────────────────────────
220
+
221
+ /** A text the portal shows: a string, or one string per language code (`{"en": "…", "vi": "…"}`). */
222
+ function isText(v, oneLine = false) {
223
+ const ok = (s) => typeof s === 'string' && s.trim() !== '' && (!oneLine || !/[\r\n]/.test(s))
224
+ if (typeof v === 'string') return ok(v)
225
+ return (
226
+ v !== null &&
227
+ typeof v === 'object' &&
228
+ !Array.isArray(v) &&
229
+ Object.keys(v).length > 0 &&
230
+ Object.entries(v).every(([k, s]) => /^[a-z]{2}(-[A-Z]{2})?$/.test(k) && ok(s))
231
+ )
232
+ }
233
+
234
+ /** Throws naming every problem with a manifest object; returns it unchanged when valid. Fields: docs/downloads.md. */
235
+ export function validateManifest(m) {
236
+ const problems = []
237
+ if (m === null || typeof m !== 'object' || Array.isArray(m)) throw new Error('manifest.json is not a JSON object')
238
+ for (const k of Object.keys(m))
239
+ if (!['schema', 'name', 'summary', 'install', 'requires'].includes(k)) problems.push(`unknown field "${k}"`)
240
+ if (m.schema !== undefined && m.schema !== 1) problems.push('schema must be 1')
241
+ if (!isText(m.name, true)) problems.push('name: a one-line text is required')
242
+ if (!isText(m.summary, true)) problems.push('summary: a one-line text is required')
243
+ const inst = m.install
244
+ if (inst === null || typeof inst !== 'object' || Array.isArray(inst) || Object.keys(inst).length === 0) {
245
+ problems.push(`install: an object keyed by platform (${PLATFORMS.join(', ')}) is required`)
246
+ } else {
247
+ for (const [os, how] of Object.entries(inst)) {
248
+ if (!PLATFORMS.includes(os)) {
249
+ problems.push(`install.${os}: not a platform (${PLATFORMS.join(', ')})`)
250
+ continue
251
+ }
252
+ if (how === null || typeof how !== 'object' || Array.isArray(how)) {
253
+ problems.push(`install.${os}: an object with steps (and optional prompts)`)
254
+ continue
255
+ }
256
+ for (const k of Object.keys(how))
257
+ if (!['steps', 'prompts'].includes(k)) problems.push(`install.${os}.${k}: unknown field`)
258
+ if (!Array.isArray(how.steps) || how.steps.length === 0 || !how.steps.every((s) => isText(s)))
259
+ problems.push(`install.${os}.steps: a non-empty list of texts`)
260
+ if (how.prompts !== undefined && (!Array.isArray(how.prompts) || !how.prompts.every((s) => isText(s))))
261
+ problems.push(`install.${os}.prompts: a list of texts`)
262
+ }
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
+ }
279
+ if (problems.length) throw new Error(`manifest.json: ${problems.join('; ')}`)
280
+ return m
281
+ }
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
+
289
+ /** Reads and validates the repo's config + manifest. */
290
+ export function loadRepo(root, env = {}) {
291
+ const yml = join(root, '.github', 'project.yml')
292
+ if (!existsSync(yml)) throw new Error(`${yml} does not exist`)
293
+ const reserved = String(env.DOWNLOADS_RESERVED ?? '')
294
+ .split(/[\s,]+/)
295
+ .filter(Boolean)
296
+ const config = readConfig(parseDownloadsBlock(readFileSync(yml, 'utf8')), { reserved })
297
+ const mPath = join(root, config.manifest)
298
+ if (!existsSync(mPath)) throw new Error(`${config.manifest} does not exist — every app on the site carries a manifest`)
299
+ let manifest
300
+ try {
301
+ manifest = JSON.parse(readFileSync(mPath, 'utf8'))
302
+ } catch (error) {
303
+ throw new Error(`${config.manifest} is not JSON: ${error.message}`)
304
+ }
305
+ validateManifest(manifest)
306
+ if (requiresOf(manifest).some((r) => r.slug === config.app))
307
+ throw new Error(`${config.manifest}: requires names ${config.app} itself`)
308
+ for (const p of config.installers) {
309
+ const f = join(root, p)
310
+ if (!existsSync(f)) throw new Error(`downloads.installers: ${p} does not exist`)
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
+ )
317
+ }
318
+ return { config, manifest }
319
+ }
320
+
321
+ // ── staging ──────────────────────────────────────────────────────────────────────────────────────
322
+
323
+ export function sha256File(path) {
324
+ return new Promise((resolveHash, reject) => {
325
+ const h = createHash('sha256')
326
+ createReadStream(path)
327
+ .on('data', (c) => h.update(c))
328
+ .on('error', reject)
329
+ .on('end', () => resolveHash(h.digest('hex')))
330
+ })
331
+ }
332
+
333
+ /** Compares X.Y.Z versions: negative when a < b. */
334
+ export function compareVersions(a, b) {
335
+ const pa = a.split('.').map(Number)
336
+ const pb = b.split('.').map(Number)
337
+ for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] - pb[i]
338
+ return 0
339
+ }
340
+
341
+ export function siteRoot(baseUrl) {
342
+ if (typeof baseUrl !== 'string' || !/^https:\/\/[^\s'"\\]+$/.test(baseUrl)) {
343
+ throw new Error('DOWNLOADS_URL must be an https address (the repo variable is missing or malformed)')
344
+ }
345
+ return baseUrl.replace(/\/+$/, '')
346
+ }
347
+
348
+ /**
349
+ * Lays out what goes to the site under `outDir`: `<X.Y.Z>/` (the files + a combined SHA256SUMS), the installers with
350
+ * the site root stamped in, manifest.json and latest.json. Throws, uploading nothing, when a required file is missing.
351
+ */
352
+ export async function stage({ tag, assetsDir, outDir, baseUrl, root, config, manifest }) {
353
+ const version = finalVersion(tag)
354
+ const base = siteRoot(baseUrl)
355
+ const present = new Set(readdirSync(assetsDir))
356
+ const missing = namesFor(config.files, version).filter((n) => !present.has(n))
357
+ if (missing.length > 0) {
358
+ throw new Error(
359
+ `the Release of ${tag} lacks ${missing.join(', ')} — nothing was published; finish the builds, then dispatch the publish again`,
360
+ )
361
+ }
362
+ const names = [...namesFor(config.files, version), ...namesFor(config.optional, version).filter((n) => present.has(n))]
363
+ const folder = join(outDir, version)
364
+ mkdirSync(folder, { recursive: true })
365
+ const files = {}
366
+ for (const name of names) {
367
+ copyFileSync(join(assetsDir, name), join(folder, name))
368
+ files[name] = { sha256: await sha256File(join(folder, name)), size: statSync(join(folder, name)).size }
369
+ }
370
+ const sums = Object.keys(files)
371
+ .sort()
372
+ .map((n) => `${files[n].sha256} ${n}\n`)
373
+ .join('')
374
+ writeFileSync(join(folder, 'SHA256SUMS'), sums)
375
+ const rootFiles = []
376
+ for (const p of config.installers) {
377
+ const source = readFileSync(join(root, p), 'utf8')
378
+ const stamped = source.split(PLACEHOLDER).join(base).split(REQUIRES_PLACEHOLDER).join(requiresStamp(manifest))
379
+ writeFileSync(join(outDir, basename(p)), stamped)
380
+ rootFiles.push(basename(p))
381
+ }
382
+ writeFileSync(join(outDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
383
+ rootFiles.push('manifest.json')
384
+ writeFileSync(join(outDir, 'latest.json'), `${JSON.stringify({ version, files }, null, 2)}\n`)
385
+ return { version, files, sums, rootFiles }
386
+ }
387
+
388
+ // ── the site ─────────────────────────────────────────────────────────────────────────────────────
389
+
390
+ function runRsync({ rsync, sshArgs, args, log }) {
391
+ const full = [...(sshArgs ? ['-e', sshArgs] : []), ...args]
392
+ log(`$ rsync ${full.join(' ')}`)
393
+ const r = spawnSync(rsync, full, { encoding: 'utf8' })
394
+ if (r.status !== 0) throw new Error(`rsync failed (${r.status ?? r.signal}): ${(r.stderr || r.stdout || '').trim()}`)
395
+ }
396
+
397
+ async function get(fetchImpl, url, attempts = 3) {
398
+ let last
399
+ for (let i = 0; i < attempts; i++) {
400
+ try {
401
+ const res = await fetchImpl(url, { headers: { 'cache-control': 'no-cache' } })
402
+ if (res.status < 500) return res
403
+ last = new Error(`${url} answered ${res.status}`)
404
+ } catch (error) {
405
+ last = new Error(`${url} could not be read (${error.cause?.code ?? error.message}) — is the site reachable from this runner?`)
406
+ }
407
+ if (i + 1 < attempts) await new Promise((r) => setTimeout(r, 1000 * (i + 1)))
408
+ }
409
+ throw last
410
+ }
411
+
412
+ /** The bytes at `url`, or null on 404. Any other failure throws. */
413
+ async function readBytes(fetchImpl, url) {
414
+ const res = await get(fetchImpl, url)
415
+ if (res.status === 404) return null
416
+ if (!res.ok) throw new Error(`${url} answered ${res.status}`)
417
+ return Buffer.from(await res.arrayBuffer())
418
+ }
419
+
420
+ async function hashUrl(fetchImpl, url) {
421
+ const res = await get(fetchImpl, url)
422
+ if (!res.ok) return { status: res.status }
423
+ const h = createHash('sha256')
424
+ for await (const chunk of res.body) h.update(chunk)
425
+ return { status: res.status, sha256: h.digest('hex') }
426
+ }
427
+
428
+ /**
429
+ * Fails clearly, before anything else is tried, when the site's host does not resolve from this runner — the site
430
+ * may be reachable only on a private network, and only a runner on it can publish and read back.
431
+ */
432
+ export async function assertResolves(baseUrl, resolver = lookup) {
433
+ const host = new URL(siteRoot(baseUrl)).hostname
434
+ try {
435
+ await resolver(host)
436
+ } catch (error) {
437
+ throw new Error(
438
+ `${host} does not resolve from this runner (${error.code ?? error.message}) — the site may be private-network only: run the job on a runner that can reach it (the workflow's runs-on input)`,
439
+ )
440
+ }
441
+ }
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
+
486
+ /**
487
+ * Uploads a staged tree (see `stage`) in the order the header gives. `dest` is the rsync destination (`user@host:`
488
+ * in production — the account's root is the app's folder), `sshArgs` the `-e` command line.
489
+ */
490
+ export async function publish({
491
+ outDir,
492
+ app,
493
+ dest,
494
+ sshArgs,
495
+ baseUrl,
496
+ dryRun = false,
497
+ rsync = 'rsync',
498
+ fetchImpl = fetch,
499
+ log = console.log,
500
+ }) {
501
+ const root = `${siteRoot(baseUrl)}/${app}`
502
+ const latestBytes = readFileSync(join(outDir, 'latest.json'))
503
+ const { version, files } = JSON.parse(latestBytes.toString('utf8'))
504
+ const localSums = readFileSync(join(outDir, version, 'SHA256SUMS'))
505
+ const rootFiles = readdirSync(outDir).filter((n) => n !== 'latest.json' && n !== version && n !== 'manifest.json')
506
+ rootFiles.sort()
507
+ rootFiles.push('manifest.json') // installers first, manifest after them, latest.json last
508
+ const out = { version, uploaded: [], unchanged: [], skippedLatest: false, dryRun, requires: [] }
509
+ const slash = /[/:]$/.test(dest) ? '' : '/'
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
+
516
+ const remoteSums = await readBytes(fetchImpl, `${root}/${version}/SHA256SUMS`)
517
+ if (remoteSums !== null && !remoteSums.equals(localSums)) {
518
+ throw new Error(
519
+ `${version} is already published and its SHA256SUMS differs from this build's — versions are immutable, nothing was changed; publish a new version instead`,
520
+ )
521
+ }
522
+ log(remoteSums === null ? `${version}: not complete on the site yet` : `${version}: complete on the site — verifying only`)
523
+
524
+ const remoteLatest = await readBytes(fetchImpl, `${root}/latest.json`)
525
+ let remoteVersion = null
526
+ if (remoteLatest !== null) {
527
+ try {
528
+ const v = JSON.parse(remoteLatest.toString('utf8')).version
529
+ if (typeof v === 'string' && /^\d+\.\d+\.\d+$/.test(v)) remoteVersion = v
530
+ } catch {
531
+ remoteVersion = null
532
+ }
533
+ }
534
+ out.skippedLatest = remoteVersion !== null && compareVersions(remoteVersion, version) > 0
535
+
536
+ const common = { rsync, sshArgs, log }
537
+ if (dryRun) {
538
+ log('dry run — nothing is uploaded. Would send, in this order:')
539
+ if (remoteSums === null) {
540
+ for (const n of Object.keys(files)) log(` ${version}/${n}`)
541
+ log(` ${version}/SHA256SUMS`)
542
+ }
543
+ for (const n of rootFiles) log(` ${n} (when the site's copy differs)`)
544
+ log(out.skippedLatest ? ` (latest.json stays: the site names ${remoteVersion})` : ' latest.json (when the site\'s copy differs)')
545
+ return out
546
+ }
547
+
548
+ if (remoteSums === null) {
549
+ runRsync({ ...common, args: ['-rt', '--ignore-existing', '--exclude', 'SHA256SUMS', join(outDir, version), dest] })
550
+ // Check every file as a visitor would get it before the folder is declared complete.
551
+ for (const [name, want] of Object.entries(files)) {
552
+ const got = await hashUrl(fetchImpl, `${root}/${version}/${name}`)
553
+ if (got.sha256 !== want.sha256) {
554
+ throw new Error(
555
+ `${version}/${name} on the site is ${got.status === 200 ? 'a different file' : `answering ${got.status}`} than this build's — the folder was left without SHA256SUMS; a person removes that file on the server, then dispatch the same tag again`,
556
+ )
557
+ }
558
+ out.uploaded.push(`${version}/${name}`)
559
+ }
560
+ runRsync({ ...common, args: ['-t', join(outDir, version, 'SHA256SUMS'), `${dest}${slash}${version}/`] })
561
+ out.uploaded.push(`${version}/SHA256SUMS`)
562
+ } else {
563
+ for (const [name, want] of Object.entries(files)) {
564
+ const got = await hashUrl(fetchImpl, `${root}/${version}/${name}`)
565
+ if (got.sha256 !== want.sha256)
566
+ throw new Error(`${version}/${name} on the site does not match its SHA256SUMS (${got.status})`)
567
+ }
568
+ }
569
+
570
+ // The app-root files are replaced only when they differ, so a re-run sends nothing.
571
+ const mutable = out.skippedLatest ? rootFiles : [...rootFiles, 'latest.json']
572
+ for (const name of mutable) {
573
+ const local = readFileSync(join(outDir, name))
574
+ const remote = await readBytes(fetchImpl, `${root}/${name}`)
575
+ if (remote !== null && remote.equals(local)) {
576
+ out.unchanged.push(name)
577
+ continue
578
+ }
579
+ runRsync({ ...common, args: ['-t', join(outDir, name), dest] })
580
+ out.uploaded.push(name)
581
+ }
582
+ if (out.skippedLatest) log(`latest.json stays: the site already names ${remoteVersion}, newer than ${version}`)
583
+
584
+ // Read back what a visitor reads.
585
+ const sumsBack = await readBytes(fetchImpl, `${root}/${version}/SHA256SUMS`)
586
+ if (sumsBack === null || !sumsBack.equals(localSums))
587
+ throw new Error(`${root}/${version}/SHA256SUMS does not read back as this build's`)
588
+ for (const name of mutable) {
589
+ const back = await readBytes(fetchImpl, `${root}/${name}`)
590
+ if (back === null || !back.equals(readFileSync(join(outDir, name))))
591
+ throw new Error(`${root}/${name} does not read back as the file just sent`)
592
+ }
593
+ return out
594
+ }
595
+
596
+ function sshCommand(env) {
597
+ const need = (k) => {
598
+ if (!env[k]) throw new Error(`${k} is not set — the upload secrets are missing on this repo`)
599
+ return env[k]
600
+ }
601
+ const port = need('DOWNLOADS_SSH_PORT')
602
+ if (!/^\d+$/.test(port)) throw new Error('DOWNLOADS_SSH_PORT is not a port number')
603
+ const key = need('DOWNLOADS_KEY_FILE')
604
+ const known = need('DOWNLOADS_KNOWN_HOSTS_FILE')
605
+ for (const f of [key, known]) if (!existsSync(f)) throw new Error(`${f} does not exist`)
606
+ return {
607
+ dest: `${need('DOWNLOADS_SSH_USER')}@${need('DOWNLOADS_SSH_HOST')}:`,
608
+ sshArgs: `ssh -p ${port} -i ${key} -o UserKnownHostsFile=${known} -o StrictHostKeyChecking=yes -o IdentitiesOnly=yes -o BatchMode=yes`,
609
+ }
610
+ }
611
+
612
+ async function main(argv, env) {
613
+ const rootAt = argv.indexOf('--root')
614
+ const root = resolve(rootAt >= 0 ? argv[rootAt + 1] ?? '' : '.')
615
+ const args = argv.filter((a, i) => !(rootAt >= 0 && (i === rootAt || i === rootAt + 1)))
616
+ const [command, tag, ...rest] = args
617
+ const usage = 'usage: publish-downloads.mjs check | names <tag> | publish <tag> <assetsDir> [--dry-run] [--root <repo>]'
618
+ if (!['check', 'names', 'publish'].includes(command)) throw new Error(usage)
619
+ const { config, manifest } = loadRepo(root, env)
620
+ if (command === 'check') {
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}`)
623
+ return 0
624
+ }
625
+ if (command === 'names') {
626
+ const v = finalVersion(tag)
627
+ console.log([...namesFor(config.files, v), ...namesFor(config.optional, v)].join('\n'))
628
+ return 0
629
+ }
630
+ const dryRun = rest.includes('--dry-run')
631
+ const assetsDir = resolve(rest.filter((a) => !a.startsWith('--'))[0] ?? '')
632
+ const baseUrl = env.DOWNLOADS_URL
633
+ const outDir = mkdtempSync(join(tmpdir(), 'publish-downloads-'))
634
+ const staged = await stage({ tag, assetsDir, outDir, baseUrl, root, config, manifest })
635
+ console.log(`Staged ${config.app} ${staged.version}: ${Object.keys(staged.files).join(', ')}`)
636
+ await assertResolves(baseUrl)
637
+ const target = dryRun ? { dest: 'DRY-RUN:', sshArgs: undefined } : sshCommand(env)
638
+ const result = await publish({ outDir, app: config.app, ...target, baseUrl, dryRun })
639
+ if (dryRun) console.log(`Dry run of ${result.version} done — nothing was uploaded`)
640
+ else
641
+ console.log(
642
+ `Published ${config.app} ${result.version}: sent ${result.uploaded.length ? result.uploaded.join(', ') : 'nothing (a verified no-op)'}` +
643
+ `${result.unchanged.length ? `; unchanged ${result.unchanged.join(', ')}` : ''}${result.skippedLatest ? ' (latest.json names a newer version)' : ''}`,
644
+ )
645
+ return 0
646
+ }
647
+
648
+ // realpath: a script run through a symlinked path (macOS /var → /private/var) is still this script.
649
+ if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
650
+ main(process.argv.slice(2), process.env).then(
651
+ (code) => {
652
+ process.exitCode = code
653
+ },
654
+ (error) => {
655
+ console.error(error instanceof Error ? error.message : String(error))
656
+ process.exitCode = 1
657
+ },
658
+ )
659
+ }