@ham2k/extension-tools 1.16.0 → 1.17.0

package/README.md

@@ -46,7 +46,9 @@ await buildExtension(build, { dir: import.meta.dirname })
 ```
 
 Reads your `manifest.json`, compiles `src/index.ts` into `build/index.js`, and
-copies the manifest alongside it. The esbuild settings it applies are
+copies the manifest alongside it — with the text of an `ABOUT.md` beside it as
+the manifest's `about`, and of each `ABOUT.<locale>.md` as that translation's
+(see the manifest docs). The esbuild settings it applies are
 requirements of the runtime rather than preferences: one IIFE because the
 sandbox evaluates a script and has no module loader, `neutral` because there is
 no Node and no DOM, and `es2020` because that is what its engine speaks.

package/h2kext-build.mjs

@@ -20,12 +20,12 @@
 // path a third party takes from being the untested one.
 
 import { readFileSync } from "node:fs"
-import { copyFile, mkdir, readFile } from "node:fs/promises"
+import { copyFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises"
 import { createRequire } from "node:module"
 import { dirname, join, resolve } from "node:path"
 import vm from "node:vm"
 
-import { H2KEXT_API_VERSION, HALO_GLOBAL_API_VERSION, MANIFEST_ENTRY, TIMERS_API_VERSION, sharedModulesFor } from "./h2kext.mjs"
+import { H2KEXT_API_VERSION, HALO_GLOBAL_API_VERSION, MANIFEST_ENTRY, TIMERS_API_VERSION, aboutProblem, sharedModulesFor } from "./h2kext.mjs"
 
 /// What an extension's own `build.mjs` says, for everything that has to write
 /// one: `h2kext-init`'s scaffold, and the samples the SDK ships.
@@ -353,10 +353,58 @@ export async function buildExtension(esbuild, { dir, entry = "src/index.ts", out
   // The packer reads both from one directory, so the manifest the bundle was
   // built against is the manifest that ships with it. Copied rather than left
   // for the author to remember: a stale manifest beside a fresh bundle is a
-  // declared dependency list that no longer describes the code.
-  await copyFile(join(dir, MANIFEST_ENTRY), join(out, MANIFEST_ENTRY))
+  // declared dependency list that no longer describes the code. With ABOUT
+  // files it is written instead, carrying their text.
+  const shipped = await withAboutFiles(manifest, dir)
+  if (shipped === manifest) await copyFile(join(dir, MANIFEST_ENTRY), join(out, MANIFEST_ENTRY))
+  else await writeFile(join(out, MANIFEST_ENTRY), `${JSON.stringify(shipped, null, 2)}\n`)
 
-  return { outDir: out, manifest }
+  return { outDir: out, manifest: shipped }
+}
+
+/// `ABOUT.md`, and `ABOUT.<locale>.md` for a translation (`ABOUT.es.md`,
+/// `ABOUT.pt-BR.md`), beside `manifest.json`.
+export const ABOUT_FILE = /^ABOUT(?:\.([A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*))?\.md$/
+
+/// [manifest] with the text of the ABOUT files in [dir] as its `about` and
+/// its translations' `about` — or [manifest] itself, the same object, when
+/// there are none. Markdown several paragraphs long is miserable to write as
+/// one JSON string, so an author can keep it in a file of its own; the
+/// bundle carries it in the manifest either way, where the app and the
+/// catalog read it.
+///
+/// A text given both ways is refused rather than one silently winning: the
+/// author would be editing a copy that never ships.
+export async function withAboutFiles(manifest, dir) {
+  const names = (await readdir(dir)).filter((name) => ABOUT_FILE.test(name)).sort()
+  if (!names.length) return manifest
+  const folded = { ...manifest }
+  for (const name of names) {
+    const text = (await readFile(join(dir, name), "utf8")).trim()
+    // Checked here, naming the file: the packer would say the same about
+    // `'about'` in a manifest.json the author never wrote it into.
+    const problem = aboutProblem(text)
+    if (problem) throw new BuildError(`${name} ${problem.replace("leave it out instead", "delete the file instead")}`)
+    const locale = name.match(ABOUT_FILE)[1]
+    if (!locale) {
+      if (manifest.about != null) throw new BuildError(`both ${MANIFEST_ENTRY} and ${name} give 'about' — keep one`)
+      folded.about = text
+      continue
+    }
+    const translations = folded.translations
+    if (translations !== undefined && (typeof translations !== "object" || translations === null || Array.isArray(translations))) {
+      throw new BuildError(`${name} is a translation, but ${MANIFEST_ENTRY}'s 'translations' is not an object of locales`)
+    }
+    const fields = translations?.[locale]
+    if (fields !== undefined && (typeof fields !== "object" || fields === null || Array.isArray(fields))) {
+      throw new BuildError(`${name} is the '${locale}' translation, but ${MANIFEST_ENTRY}'s 'translations.${locale}' is not an object`)
+    }
+    if (fields?.about != null) {
+      throw new BuildError(`both ${MANIFEST_ENTRY} 'translations.${locale}.about' and ${name} give it — keep one`)
+    }
+    folded.translations = { ...translations, [locale]: { ...translations?.[locale], about: text } }
+  }
+  return folded
 }
 
 /// Fails the build when the bundle registers a `settingsPanel` hook its

package/h2kext-dev.mjs

@@ -39,7 +39,7 @@ import { networkInterfaces } from "node:os"
 import { join, resolve } from "node:path"
 import { pathToFileURL } from "node:url"
 
-import { buildOptionsFor } from "./h2kext-build.mjs"
+import { ABOUT_FILE, buildOptionsFor, withAboutFiles } from "./h2kext-build.mjs"
 import { indexEntryFor, MANIFEST_ENTRY, validateManifest } from "./h2kext.mjs"
 
 /// The protocol the app's dev client speaks. Bumped when the shape below
@@ -104,6 +104,9 @@ export function parseArgs(argv) {
       case "--dir":
         options.dir = resolve(value())
         break
+      case "--force-name":
+        options.forceName = true
+        break
       case "--help":
       case "-h":
         options.help = true
@@ -115,7 +118,7 @@ export function parseArgs(argv) {
   return options
 }
 
-export const USAGE = `usage: h2kext-dev [--port <n>] [--host <address>] [--entry <file>] [--inline <pkg,…>] [--dir <path>]
+export const USAGE = `usage: h2kext-dev [--port <n>] [--host <address>] [--entry <file>] [--inline <pkg,…>] [--dir <path>] [--force-name]
 
 Serves the extension in the current directory to the app's Extension Dev
 Server (Settings → Developer), rebuilding it as you save and printing what it
@@ -125,7 +128,8 @@ logs. Point the app at one of the addresses it prints.
   --host    the address to bind (default 0.0.0.0, so a phone on the LAN can connect)
   --entry   the entry point (default src/index.ts); pass what build.mjs passes
   --inline  shared libraries to bundle rather than take from the app; pass what build.mjs passes
-  --dir     the extension directory (default the current directory)`
+  --dir     the extension directory (default the current directory)
+  --force-name  Ham2K's own extensions: waives the key convention, as h2kext-pack's does`
 
 /// The author's own esbuild, resolved from their project rather than from
 /// wherever this file is installed: the preset is written to use the caller's
@@ -164,6 +168,7 @@ export async function createDevServer({
   port = DEFAULT_PORT,
   entry = "src/index.ts",
   inline = [],
+  forceName = false,
   log = console.log,
   warn = console.error,
 }) {
@@ -193,7 +198,10 @@ export async function createDevServer({
   /// the extension from the manifest as it stands and the bundle route serves
   /// [EMPTY_BUNDLE], so the app connects and hears the error.
   let source = null
-  let servedManifest = startManifest
+  // Folded now as well, so an index served before the first good build lists
+  // the extension as it will ship; a problem with the files is the first
+  // build's to report.
+  let servedManifest = await withAboutFiles(startManifest, dir).catch(() => startManifest)
   let servedManifestText = null
   let buildError = null
   const clients = new Set()
@@ -220,10 +228,14 @@ export async function createDevServer({
     } catch (e) {
       throw new Error(`${MANIFEST_ENTRY}: ${e.message}`)
     }
-    const problems = validateManifest(parsed)
+    // As the build folds them in, so the dialog shows what will ship. The
+    // text compared for "unchanged" is the folded one: an edit to ABOUT.md
+    // alone is a reload too.
+    parsed = await withAboutFiles(parsed, dir)
+    const problems = validateManifest(parsed, { forceName })
     if (problems.length) throw new Error(problems.join("\n"))
     if (parsed.key !== key) throw new Error(`${MANIFEST_ENTRY}: 'key' changed from ${key} to ${parsed.key}; restart h2kext-dev to serve it`)
-    return { parsed, text }
+    return { parsed, text: JSON.stringify(parsed) }
   }
 
   /// The esbuild context, rebuilt from scratch when the manifest changes in
@@ -326,12 +338,13 @@ export async function createDevServer({
   // The manifest may change without changing any bundle input (an entry that
   // does not import it), and an editor that saves by writing a temporary file
   // and renaming it replaces the file's inode, which a watch on the file alone
-  // would lose. So the directory is watched, for that one name.
+  // would lose. So the directory is watched, for that one name — and for the
+  // ABOUT files, which reach the manifest the same way.
   const manifestWatch = new AbortController()
   ;(async () => {
     try {
       for await (const event of watch(dir, { signal: manifestWatch.signal })) {
-        if (event.filename !== MANIFEST_ENTRY) continue
+        if (event.filename !== MANIFEST_ENTRY && !ABOUT_FILE.test(event.filename ?? "")) continue
         await restarting
         await ctx?.rebuild().catch(() => {})
       }

package/h2kext.mjs

@@ -57,8 +57,10 @@ import yazl from "yazl"
 /// trigger; 14 adds `host.fyi`, messages on the FYI line under the call
 /// info; 15 adds `incomplete` on a live scoring verdict, the fields a
 /// contact still needs before Enter logs it; 16 names the kernel `__halo`,
-/// and keeps `__polo` only for a bundle that declares a lower level.
-export const H2KEXT_API_VERSION = 16
+/// and keeps `__polo` only for a bundle that declares a lower level; 17
+/// makes a spectrum's gestures the host's — tuning, zoom, pan and an axis —
+/// unless its scene's `gestures` and `scale` say otherwise.
+export const H2KEXT_API_VERSION = 17
 
 /// The first API with `host.webSocket`. A manifest declaring `webSockets`
 /// under an older one is refused: an older app would install it and fail only
@@ -148,6 +150,39 @@ export function keyProblem(key, { forceName = false } = {}) {
   return null
 }
 
+/// The longest `about` the packer, the app and the catalog accept, in each
+/// language: room for several paragraphs, not for a manual. It travels on
+/// every catalog listing entry, so its size is everyone's download.
+export const ABOUT_MAX_LENGTH = 10000
+
+/// What is wrong with [value] as an `about` text, or null. Markdown, at most
+/// [ABOUT_MAX_LENGTH] characters, and not blank: an empty one would draw an
+/// empty section where the app would otherwise draw none.
+export function aboutProblem(value) {
+  if (typeof value !== "string") return "must be a string of markdown"
+  if (value.trim() === "") return "is empty — leave it out instead"
+  if (value.length > ABOUT_MAX_LENGTH) return `is ${value.length} characters; at most ${ABOUT_MAX_LENGTH} are allowed`
+  return null
+}
+
+/// Every problem with [manifest]'s `about` and its translations' `about`, as
+/// "'<field>' <problem>" — one list the packer and the built-in build share.
+export function aboutProblems(manifest) {
+  const problems = []
+  if (manifest?.about !== undefined) {
+    const problem = aboutProblem(manifest.about)
+    if (problem) problems.push(`'about' ${problem}`)
+  }
+  if (typeof manifest?.translations === "object" && manifest.translations !== null) {
+    for (const [locale, fields] of Object.entries(manifest.translations)) {
+      if (fields?.about === undefined) continue
+      const problem = aboutProblem(fields.about)
+      if (problem) problems.push(`'translations.${locale}.about' ${problem}`)
+    }
+  }
+  return problems
+}
+
 /// The only entries a bundle may contain, beyond `assets/`.
 export const MANIFEST_ENTRY = "manifest.json"
 export const BUNDLE_ENTRY = "index.js"
@@ -197,6 +232,7 @@ SHARED_MODULES_BY_API[13] = SHARED_MODULES_BY_API[12]
 SHARED_MODULES_BY_API[14] = SHARED_MODULES_BY_API[13]
 SHARED_MODULES_BY_API[15] = SHARED_MODULES_BY_API[14]
 SHARED_MODULES_BY_API[16] = SHARED_MODULES_BY_API[15]
+SHARED_MODULES_BY_API[17] = SHARED_MODULES_BY_API[16]
 
 /// What a scaffolded extension declares on day one: the eight modules the SDK
 /// barrel itself reaches, so a project that has written no code yet still
@@ -489,6 +525,8 @@ export function validateManifest(manifest, { source = MANIFEST_ENTRY, forceName
     say("'experiments' refers to the app's own experiment catalog and would hide this extension permanently — remove it")
   }
 
+  for (const problem of aboutProblems(manifest)) say(problem)
+
   // The name `relevance` replaced. Nothing reads `geo`, and nothing here
   // rejects unknown top-level keys, so a manifest still carrying it would
   // pack, publish and install as WORLDWIDE — the author's audience silently
@@ -685,6 +723,7 @@ export function indexEntryFor(key, m) {
           enabledByDefault: m.enabledByDefault ?? true,
           ...(m.icon ? { icon: m.icon } : {}),
           ...(m.description ? { description: m.description } : {}),
+          ...(m.about ? { about: m.about } : {}),
           ...(m.accentColor ? { accentColor: m.accentColor } : {}),
           ...(m.keywords ? { keywords: m.keywords } : {}),
           ...(m.hooks ? { hooks: m.hooks } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-tools",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Build and package extensions for the Ham2K Logger",
   "keywords": [
     "ham2k",