@ham2k/extension-tools 0.14.0 → 0.14.1

package/README.md

@@ -107,3 +107,32 @@ A channel says how finished a release is — `stable`, `unstable`, `bleeding`
 not which app edition is asking. They cascade upward, so `stable` reaches
 everyone and `bleeding` reaches only somebody who asked for it. `--channel` is
 optional and defaults to `stable`.
+
+### Screenshots
+
+```
+screenshots/
+  1-logging.png
+  2-map.png
+  screenshots.json    optional — { "1-logging.png": "Logging a park" }
+```
+
+When your project has a `screenshots/` folder (or you name one with
+`--screenshots <dir>`), `h2kext-publish` makes the catalog's screenshots for
+your extension match it, after the bundle is accepted. The folder is the
+whole set: PNG, JPEG or WebP files, at most 8, shown in file-name order
+(`2-…` before `10-…`), captions from `screenshots.json`. Screenshots are never
+packed into the bundle, and they belong to the extension rather than to a
+version: every channel shows the same ones, and
+`h2kext-publish build --screenshots-only` updates them without publishing a
+version.
+
+Each screenshot is at most 2 MiB and 3840 pixels on its longest side. The
+command makes the thumbnail the app shows in search results itself, with
+[sharp](https://sharp.pixelplumbing.com) — an optional dependency, so if it
+could not install on your machine the command says so, and you can add your
+screenshots on the site's [/publish](https://catalog.ham2k.net/publish) page
+instead. An unchanged folder sends nothing. A new set waits for a reviewer,
+like a version, while the approved one keeps showing. An empty folder named
+with `--screenshots` takes every screenshot down at once; an empty
+`./screenshots` found on its own is left alone.

package/h2kext-publish.mjs

@@ -8,18 +8,19 @@
 //
 //   H2K_CATALOG_TOKEN=h2kc_… h2kext-publish <bundle.h2kext | build dir>
 //                  [--channel <stable|unstable|bleeding>] [--notes "…"] [--catalog <url>]
-//                  [--force-name]
+//                  [--force-name] [--screenshots <dir>] [--screenshots-only]
 //
-// One POST of the raw bytes, then one PUT for the notes; no retries: a refusal
-// is the catalog's verdict on these bytes, and sending them again can only
-// repeat it. The token is read from the environment for those requests and
+// One POST of the raw bytes, then one PUT for the notes, then the screenshot
+// sync (§4.8); no retries: a refusal is the catalog's verdict on these bytes,
+// and sending them again can only repeat it. The token is read from the environment for those requests and
 // never written anywhere — not to a config file, not to the terminal, not into
 // an error message.
 
+import { createHash } from "node:crypto"
 import { realpathSync } from "node:fs"
-import { mkdtemp, readFile, rm, stat } from "node:fs/promises"
+import { mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises"
 import { tmpdir } from "node:os"
-import { join } from "node:path"
+import { extname, join, resolve } from "node:path"
 import { pathToFileURL } from "node:url"
 import { inflateRawSync } from "node:zlib"
 
@@ -43,6 +44,16 @@ export const DEFAULT_CHANNEL = "stable"
 /// Checked here so the refusal costs nothing instead of a wasted upload.
 export const MAX_BUNDLE_BYTES = 16 * 1024 * 1024
 
+/// Screenshots (§4.8). The catalog checks every one of these again; checking
+/// here turns a refusal after a round trip into one before any upload.
+export const SCREENSHOTS_DIR = "screenshots"
+export const CAPTIONS_FILE = "screenshots.json"
+export const MAX_SCREENSHOTS = 8
+export const MAX_SCREENSHOT_BYTES = 2 * 1024 * 1024
+export const THUMB_SIDE = 480
+export const CAPTION_MAX = 200
+const SCREENSHOT_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp" }
+
 /// Exit codes. Usage problems — including a missing token — are 2 so a script
 /// can tell "you called this wrong" from "the catalog said no" (1).
 export const EXIT_REFUSED = 1
@@ -64,6 +75,7 @@ const USAGE = `Publish an extension bundle to the Ham2K extension catalog.
 
   ${TOKEN_ENV}=h2kc_… h2kext-publish <bundle.h2kext | build dir> [--channel <stable|unstable|bleeding>]
                  [--notes "<release notes>"] [--catalog <url>] [--force-name]
+                 [--screenshots <dir>] [--screenshots-only]
 
 A directory is packaged first, exactly as h2kext-pack would. A bundle over
 16 MiB is refused here, as the catalog would refuse it.
@@ -80,6 +92,14 @@ ${DEFAULT_CATALOG}/publish. Nothing here stores it.
   --catalog      defaults to ${DEFAULT_CATALOG}
   --force-name   waive the key naming convention when packaging a directory
                  (Ham2K's own builds; the catalog checks it again regardless)
+  --screenshots  the folder holding the extension's screenshots (default
+                 ./${SCREENSHOTS_DIR}, when it exists). The folder is the whole
+                 set: PNG, JPEG or WebP files in file-name order, at most
+                 ${MAX_SCREENSHOTS}, captions from an optional ${CAPTIONS_FILE}
+                 ({ "<file name>": "<caption>" }). Thumbnails are made with the
+                 optional \`sharp\` package. An unchanged folder sends nothing.
+  --screenshots-only
+                 sync the screenshots without publishing the bundle
 
 Exits 0 once the catalog holds the submission and its notes, 1 when it refuses
 or cannot be reached, 2 for a usage problem.`
@@ -226,9 +246,177 @@ export async function setReleaseNotes({ submissionId, notes, catalog, token }, {
   throw new PublishError(`${catalog} refused the release notes for submission ${submissionId} with HTTP ${answer.response.status}: ${refusal(answer)}`)
 }
 
+// ---------------------------------------------------------------------------
+// Screenshots (§4.8)
+// ---------------------------------------------------------------------------
+
+function sha256Of(bytes) {
+  return createHash("sha256").update(bytes).digest("hex")
+}
+
+/// The type the catalog will read from the bytes, by the same magic numbers,
+/// or null: a file named `.png` that is not one is refused here, by name.
+export function sniffImageType(bytes) {
+  const b = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)
+  if (b.length >= 8 && b.readUInt32BE(0) === 0x89504e47 && b.readUInt32BE(4) === 0x0d0a1a0a) return "image/png"
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return "image/jpeg"
+  if (b.length >= 12 && b.toString("latin1", 0, 4) === "RIFF" && b.toString("latin1", 8, 12) === "WEBP") return "image/webp"
+  return null
+}
+
+/// The folder as a set: every image file in file-name order — numeric-aware,
+/// so `2-…` comes before `10-…` — with its bytes, hash and caption. Anything
+/// else in the folder is ignored, so a README beside the pictures is fine.
+export async function readScreenshotFolder(dir) {
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch (e) {
+    throw new PublishError(`${dir}: ${e.code === "ENOENT" ? "no such directory" : e.message}`)
+  }
+  // Files only: a directory named `old.png` is not a screenshot.
+  const names = entries.filter((entry) => entry.isFile()).map((entry) => entry.name)
+  let captions = {}
+  if (names.includes(CAPTIONS_FILE)) {
+    try {
+      captions = JSON.parse(await readFile(join(dir, CAPTIONS_FILE), "utf8"))
+    } catch (e) {
+      throw new PublishError(`${join(dir, CAPTIONS_FILE)} is not valid JSON: ${e.message}`)
+    }
+    if (typeof captions !== "object" || captions === null || Array.isArray(captions)) {
+      throw new PublishError(`${join(dir, CAPTIONS_FILE)} must map file names to captions`)
+    }
+  }
+  const files = names
+    .filter((name) => SCREENSHOT_TYPES[extname(name).toLowerCase()] && !name.startsWith("."))
+    .sort((a, b) => a.localeCompare(b, "en", { numeric: true }))
+  if (files.length > MAX_SCREENSHOTS) {
+    throw new PublishError(`${dir} holds ${files.length} screenshots; the catalog takes at most ${MAX_SCREENSHOTS}`)
+  }
+  for (const name of Object.keys(captions)) {
+    // A caption for a file that is not there is almost always a renamed file.
+    if (!files.includes(name)) throw new PublishError(`${join(dir, CAPTIONS_FILE)} has a caption for '${name}', which is not a screenshot in ${dir}`)
+  }
+  const shots = []
+  for (const name of files) {
+    const bytes = await readFile(join(dir, name))
+    const type = sniffImageType(bytes)
+    if (!type) throw new PublishError(`${join(dir, name)} is not a PNG, JPEG or WebP image`)
+    if (bytes.length > MAX_SCREENSHOT_BYTES) {
+      throw new PublishError(`${join(dir, name)} is ${bytes.length} bytes; a screenshot is at most 2 MiB (${MAX_SCREENSHOT_BYTES} bytes)`)
+    }
+    const caption = captions[name]
+    if (caption !== undefined && caption !== null && typeof caption !== "string") {
+      throw new PublishError(`${join(dir, CAPTIONS_FILE)}: the caption for '${name}' must be a string`)
+    }
+    const trimmed = caption?.trim() || null
+    if (trimmed && [...trimmed].length > CAPTION_MAX) {
+      throw new PublishError(`${join(dir, CAPTIONS_FILE)}: the caption for '${name}' is longer than ${CAPTION_MAX} characters`)
+    }
+    shots.push({ name, bytes, type, sha256: sha256Of(bytes), caption: trimmed })
+  }
+  return shots
+}
+
+/// A thumbnail at most [THUMB_SIDE] pixels on its longest side, in the
+/// image's proportions, as WebP — a PNG screenshot's thumbnail kept as PNG is
+/// often past the catalog's 128 KiB, and every client decodes WebP. `sharp`
+/// is optional so packing and plain publishing never need a native module;
+/// it is loaded only when a new picture needs a thumbnail.
+export async function sharpThumbnail(bytes) {
+  let sharp
+  try {
+    sharp = (await import("sharp")).default
+  } catch {
+    throw new PublishError(
+      "making screenshot thumbnails needs the optional 'sharp' package — `npm install --save-dev sharp` in your project, or manage screenshots on the catalog site instead",
+    )
+  }
+  const data = await sharp(bytes).resize({ width: THUMB_SIDE, height: THUMB_SIDE, fit: "inside", withoutEnlargement: true }).webp({ quality: 80 }).toBuffer()
+  return { bytes: data, type: "image/webp" }
+}
+
+const sameItems = (set, shots) =>
+  set !== null &&
+  set !== undefined &&
+  set.items.length === shots.length &&
+  set.items.every((item, i) => item.image === shots[i].sha256 && (item.caption ?? null) === shots[i].caption)
+
+/// Makes the catalog's set for [key] the folder's [shots], sending only what
+/// it lacks: nothing at all when the waiting set — or the live one, with none
+/// waiting — already is the folder; otherwise a thumbnail made only for a
+/// picture no set of the key already has one for, the uploads the catalog
+/// does not hold, and the set. Answers what happened, for the result line.
+export async function syncScreenshots({ key, shots, catalog, token }, { fetch = globalThis.fetch, thumbnail = sharpThumbnail } = {}) {
+  const base = `/api/v1/extensions/${encodeURIComponent(key)}`
+  const auth = { authorization: `Bearer ${token}` }
+  const current = await call(fetch, catalog, `${base}/screenshots`, { headers: auth })
+  if (!current.response.ok) {
+    throw new PublishError(`${catalog} refused to show the screenshots of ${key} with HTTP ${current.response.status}: ${refusal(current)}`)
+  }
+  const { approved = null, pending = null } = current.body ?? {}
+  if (pending ? sameItems(pending, shots) : sameItems(approved, shots)) return { changed: false, set: pending ?? approved }
+
+  // A picture already in a set keeps that set's thumbnail: making it again
+  // with another sharp could give other bytes, and a new set to review.
+  const known = new Map()
+  for (const set of [approved, pending]) for (const item of set?.items ?? []) known.set(item.image, item.thumb)
+  const held = new Set([...known.keys(), ...known.values()])
+
+  const upload = async (bytes, type, what) => {
+    const sha256 = sha256Of(bytes)
+    if (held.has(sha256)) return sha256
+    const answer = await call(fetch, catalog, `${base}/media/${sha256}`, { method: "PUT", headers: { ...auth, "content-type": type }, body: bytes })
+    if (!answer.response.ok) throw new PublishError(`${catalog} refused ${what} with HTTP ${answer.response.status}: ${refusal(answer)}`)
+    held.add(sha256)
+    return sha256
+  }
+
+  const items = []
+  for (const shot of shots) {
+    const image = await upload(shot.bytes, shot.type, shot.name)
+    let thumb = known.get(shot.sha256)
+    if (!thumb) {
+      let made
+      try {
+        made = await thumbnail(shot.bytes)
+      } catch (e) {
+        // A file whose header looks right and whose body does not: said by
+        // name, as a refusal, not as a stack trace that hides whether the
+        // version went out.
+        if (e instanceof PublishError) throw e
+        throw new PublishError(`could not make a thumbnail of ${shot.name}: ${e.message}`)
+      }
+      thumb = await upload(made.bytes, made.type, `the thumbnail of ${shot.name}`)
+    }
+    items.push({ image, thumb, ...(shot.caption ? { caption: shot.caption } : {}) })
+  }
+
+  const answer = await call(fetch, catalog, `${base}/screenshots`, {
+    method: "PUT",
+    headers: { ...auth, "content-type": "application/json" },
+    body: JSON.stringify({ screenshots: items }),
+  })
+  if (!answer.response.ok || !answer.body?.set) {
+    throw new PublishError(`${catalog} refused the screenshots of ${key} with HTTP ${answer.response.status}: ${refusal(answer)}`)
+  }
+  return { changed: true, set: answer.body.set }
+}
+
+/// The result line's words for a set's state.
+function screenshotState({ changed, set }) {
+  const count = set?.items.length ?? 0
+  const what = count === 0 ? "no screenshots" : `${count} screenshot${count === 1 ? "" : "s"}`
+  if (!changed) return `screenshots unchanged (${what}${set?.status === "pending" ? ", pending review" : ""})`
+  return `screenshots → ${what} (${STATUS_WORDS[set.status] ?? (set.status === "approved" ? "live" : set.status)})`
+}
+
 /// The command. Returns the exit code rather than exiting, so the same code
 /// runs under a test with a fake `fetch` and captured output.
-export async function main(argv, { env = process.env, fetch = globalThis.fetch, stdout = process.stdout, stderr = process.stderr } = {}) {
+export async function main(
+  argv,
+  { env = process.env, fetch = globalThis.fetch, stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), thumbnail = sharpThumbnail } = {},
+) {
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
     stdout.write(`${USAGE}\n`)
     return argv.length === 0 ? EXIT_USAGE : 0
@@ -253,6 +441,8 @@ export async function main(argv, { env = process.env, fetch = globalThis.fetch,
     let notes
     let catalog = DEFAULT_CATALOG
     let forceName = false
+    let screenshotsDir
+    let screenshotsOnly = false
     // An option at the end of the line has no value, and `--notes` with none
     // would silently publish without notes — the one option whose absence
     // looks like success.
@@ -266,6 +456,8 @@ export async function main(argv, { env = process.env, fetch = globalThis.fetch,
       else if (arg === "--notes") notes = valueOf(i++)
       else if (arg === "--catalog") catalog = valueOf(i++)
       else if (arg === "--force-name") forceName = true
+      else if (arg === "--screenshots") screenshotsDir = valueOf(i++)
+      else if (arg === "--screenshots-only") screenshotsOnly = true
       else if (arg === "--token") throw new PublishError(`there is no --token option; set ${TOKEN_ENV} instead`, EXIT_USAGE)
       else if (arg.startsWith("-")) throw new PublishError(`unknown option '${arg}'`, EXIT_USAGE)
       else if (source === undefined) source = arg
@@ -285,6 +477,32 @@ export async function main(argv, { env = process.env, fetch = globalThis.fetch,
       throw new PublishError(`--catalog must be a URL, not '${catalog}'`, EXIT_USAGE)
     }
 
+    // The folder is read before anything is sent, so what can be checked
+    // without decoding — type, size, count, captions — stops the command
+    // before the version is published rather than after; the rest is the
+    // catalog's to refuse. Without `--screenshots`, only a folder that exists
+    // and holds pictures is a set: a project with none, or a stray empty
+    // `screenshots/` where the command happens to run, has not asked for its
+    // screenshots to be taken down. Naming the folder is how to ask.
+    let shots
+    const folder = resolve(cwd, screenshotsDir ?? SCREENSHOTS_DIR)
+    if (
+      screenshotsDir !== undefined ||
+      (await stat(folder).then(
+        (s) => s.isDirectory(),
+        () => false,
+      ))
+    ) {
+      shots = await readScreenshotFolder(folder)
+      if (screenshotsDir === undefined && shots.length === 0) {
+        say(`./${SCREENSHOTS_DIR} holds no screenshots; leaving the catalog's as they are (name it with --screenshots to remove them all)`)
+        shots = undefined
+        if (screenshotsOnly) return 0
+      }
+    } else if (screenshotsOnly) {
+      throw new PublishError(`--screenshots-only, but there is no ./${SCREENSHOTS_DIR} folder; name one with --screenshots`, EXIT_USAGE)
+    }
+
     const bytes = await loadBundle(source, { forceName })
     if (bytes.length > MAX_BUNDLE_BYTES) {
       throw new PublishError(
@@ -297,6 +515,14 @@ export async function main(argv, { env = process.env, fetch = globalThis.fetch,
         throw new PublishError(`${MANIFEST_ENTRY} inside the bundle has no '${field}'`)
       }
     }
+    const syncShots = async () => {
+      say(screenshotState(await syncScreenshots({ key: manifest.key, shots, catalog, token }, { fetch, thumbnail })))
+    }
+    if (screenshotsOnly) {
+      await syncShots()
+      return 0
+    }
+
     say(`publishing ${manifest.key} ${manifest.version}${manifest.name ? ` — ${manifest.name}` : ""} → ${channel} at ${catalog}`)
 
     const result = await publish({ bytes, manifest, channel, catalog, token }, { fetch })
@@ -318,6 +544,15 @@ export async function main(argv, { env = process.env, fetch = globalThis.fetch,
         return EXIT_REFUSED
       }
     }
+    if (shots !== undefined) {
+      try {
+        await syncShots()
+      } catch (e) {
+        if (!(e instanceof PublishError)) throw e
+        complain(`warning: ${result.key} ${result.version} is published, but its screenshots were not updated — ${e.message}`)
+        return EXIT_REFUSED
+      }
+    }
     return 0
   } catch (e) {
     if (e instanceof PublishError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-tools",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Build and package extensions for the Ham2K Logger",
   "keywords": [
     "ham2k",
@@ -43,6 +43,9 @@
     "@ham2k/lib-callsigns": "^1.0.2",
     "yazl": "^3.3.1"
   },
+  "optionalDependencies": {
+    "sharp": "^0.34.0"
+  },
   "peerDependencies": {
     "esbuild": ">=0.20"
   },