@ham2k/extension-tools 1.15.0 → 1.16.1

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, 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.
@@ -160,7 +160,8 @@ export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_
       }
 
       build.onLoad({ filter: /.*/, namespace: "ham2k-shared-module" }, (args) => ({
-        contents: `module.exports = globalThis.__polo.sharedModules[${JSON.stringify(args.path)}];`,
+        // `__polo` is the kernel's name on an app before extension API 16.
+        contents: `module.exports = (globalThis.__halo ?? globalThis.__polo).sharedModules[${JSON.stringify(args.path)}];`,
         loader: "js",
       }))
     },
@@ -346,15 +347,64 @@ export async function buildExtension(esbuild, { dir, entry = "src/index.ts", out
     }),
   )
 
+  await checkKernelName({ bundle: join(out, "index.js"), manifest })
   await checkSettingsPanelDeclared({ bundle: join(out, "index.js"), manifest, dir })
 
   // 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
@@ -376,6 +426,22 @@ export async function buildExtension(esbuild, { dir, entry = "src/index.ts", out
 /// told the check did not run.
 const ACTIVATION_DEADLINE_MS = 2000
 
+/// Refuses a bundle that declares extension API 16 or more but was built with
+/// an SDK that reaches the kernel only as \`__polo\`, which such an app answers
+/// for nothing that declares that level. The SDK and the tools are separate
+/// packages, so a project can update one and not the other.
+async function checkKernelName({ bundle, manifest }) {
+  const api = manifest.api ?? H2KEXT_API_VERSION
+  if (api < HALO_GLOBAL_API_VERSION) return
+  const source = await readFile(bundle, "utf8")
+  if (source.includes("__halo") || !source.includes("__polo")) return
+  throw new BuildError(
+    `${MANIFEST_ENTRY} declares extension API ${api}, where the app's kernel is \`__halo\`, but this bundle's ` +
+      `@ham2k/extension-sdk reaches it only as \`__polo\`, which the app keeps for bundles declaring a level below ` +
+      `${HALO_GLOBAL_API_VERSION}. Update @ham2k/extension-sdk to 1.${HALO_GLOBAL_API_VERSION} or later, or declare a lower "api".`,
+  )
+}
+
 async function checkSettingsPanelDeclared({ bundle, manifest, dir }) {
   const require = createRequire(resolve(dir, "noop.js"))
   const sharedModules = new Proxy(
@@ -395,23 +461,27 @@ async function checkSettingsPanelDeclared({ bundle, manifest, dir }) {
   )
   const hostCall = async (method) => (method === "getSettings" ? {} : method.startsWith("dbLookup") ? [] : null)
   const definitions = []
+  const kernel = {
+    defineExtension: (definition) => definitions.push(definition),
+    hostCall,
+    log: () => {},
+    invokeLocal: async () => [],
+    invokeLocalSequential: async () => [],
+    updateInterpretation: () => {},
+    getAccountKvKey: (extensionKey) => extensionKey,
+    registerDynamicForm: () => {},
+    unregisterDynamicForm: () => {},
+    host: { showForm: async () => null },
+    sharedModules,
+    sharedVersions: {},
+  }
+  // The names the app answers for the level the manifest declares: `__polo`
+  // only below HALO_GLOBAL_API_VERSION, whose SDKs may predate `__halo`.
   const sandbox = {
     console: { log() {}, info() {}, warn() {}, error() {}, debug() {} },
     sendMessage: () => {},
-    __polo: {
-      defineExtension: (definition) => definitions.push(definition),
-      hostCall,
-      log: () => {},
-      invokeLocal: async () => [],
-      invokeLocalSequential: async () => [],
-      updateInterpretation: () => {},
-      getAccountKvKey: (extensionKey) => extensionKey,
-      registerDynamicForm: () => {},
-      unregisterDynamicForm: () => {},
-      host: { showForm: async () => null },
-      sharedModules,
-      sharedVersions: {},
-    },
+    __halo: kernel,
+    ...((manifest.api ?? H2KEXT_API_VERSION) < HALO_GLOBAL_API_VERSION ? { __polo: kernel } : {}),
   }
   sandbox.globalThis = sandbox
 

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
@@ -193,7 +193,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 +223,14 @@ export async function createDevServer({
     } catch (e) {
       throw new Error(`${MANIFEST_ENTRY}: ${e.message}`)
     }
+    // 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)
     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 +333,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

@@ -56,8 +56,9 @@ import yazl from "yazl"
 /// `radio.status` — `when` on layers and controls, and the `radio` panel
 /// 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.
-export const H2KEXT_API_VERSION = 15
+/// 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
 
 /// 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
@@ -80,6 +81,12 @@ export const CLUSTER_API_VERSION = 10
 /// install it and refuse every raw command it sends.
 export const RADIO_RAW_API_VERSION = 11
 
+/// The first API whose app names the kernel `__halo`. Below it, the app also
+/// answers `__polo`; from it, nothing answers that name for the bundle. A
+/// bundle declaring this level or more whose SDK reaches only `__polo` is
+/// refused at build: it would fail to load on the app it declares.
+export const HALO_GLOBAL_API_VERSION = 16
+
 /// The first API with timers. The build points a bundle's bare `setTimeout`
 /// and friends at the SDK's only from here on: an older app's kernel hands an
 /// extension no timers, and a bundle declaring less says it runs there.
@@ -141,6 +148,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"
@@ -148,7 +188,7 @@ export const ASSETS_PREFIX = "assets/"
 
 /// The libraries the extension host carries, per API version, so a bundle does
 /// not have to ship its own copy of each. The kernel holds one instance and
-/// hands it to every extension through `__polo.sharedModules`.
+/// hands it to every extension through `__halo.sharedModules`.
 ///
 /// NAMES only. The VERSION a given app carries is that build's business, which
 /// is the whole reason a bundle declares a RANGE in `sharedDependencies` and
@@ -189,6 +229,7 @@ SHARED_MODULES_BY_API[12] = SHARED_MODULES_BY_API[11]
 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]
 
 /// 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
@@ -481,6 +522,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
@@ -511,7 +554,8 @@ export function validateManifest(manifest, { source = MANIFEST_ENTRY, forceName
 }
 
 /// Every library a bundle takes from the host rather than carrying its own
-/// copy — the `globalThis.__polo.sharedModules[...]` lookups its build emitted.
+/// copy — the `sharedModules[...]` lookups on the kernel its build emitted,
+/// under either of the kernel's names.
 ///
 /// Taking them is the supported path and worth roughly thirty times the bundle
 /// size. What the caller checks is that each one was DECLARED: the host carries
@@ -522,7 +566,7 @@ export function validateManifest(manifest, { source = MANIFEST_ENTRY, forceName
 /// else's app.
 export function findSharedModuleReferences(source) {
   const hits = []
-  const pattern = /__polo\s*\.\s*sharedModules\s*\[\s*["']([^"']+)["']\s*\]/g
+  const pattern = /__(?:halo|polo)\s*\)?\s*\.\s*sharedModules\s*\[\s*["']([^"']+)["']\s*\]/g
   for (const match of source.matchAll(pattern)) hits.push(match[1])
   return [...new Set(hits)]
 }
@@ -676,6 +720,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.15.0",
+  "version": "1.16.1",
   "description": "Build and package extensions for the Ham2K Logger",
   "keywords": [
     "ham2k",