@ham2k/extension-tools 0.15.0 → 1.12.1

package/README.md

@@ -6,6 +6,9 @@ Build and package extensions for the [Ham2K Logger](https://ham2k.com).
 npm install --save-dev @ham2k/extension-tools esbuild
 ```
 
+The minor version is the newest extension API the packer accepts — 1.12 packs
+bundles up to `"api": 12` — and matches `@ham2k/extension-sdk`'s.
+
 ## Starting one
 
 ```sh
@@ -57,6 +60,12 @@ size. Using one **without** declaring it fails the build rather than quietly
 shipping a private copy; pass `inline: ['liquidjs']` if that copy is what you
 want, which is how you use a version the host does not carry.
 
+It then activates the built bundle against a stand-in host, and fails the build
+if the bundle registers a settings panel that your manifest's `hooks` does not
+list: the app does not show an undeclared panel. If activation needs more than
+the stand-in provides, or waits on a timer or the host, the build succeeds and
+prints a warning that this check did not run.
+
 ## Packaging
 
 ```sh

package/h2kext-build.mjs

@@ -23,6 +23,7 @@ import { readFileSync } from "node:fs"
 import { copyFile, mkdir, readFile } 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"
 
@@ -345,6 +346,8 @@ export async function buildExtension(esbuild, { dir, entry = "src/index.ts", out
     }),
   )
 
+  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
@@ -353,3 +356,102 @@ export async function buildExtension(esbuild, { dir, entry = "src/index.ts", out
 
   return { outDir: out, manifest }
 }
+
+/// Fails the build when the bundle registers a `settingsPanel` hook its
+/// manifest's `hooks` does not list.
+///
+/// The app shows an installed extension's settings panel only when its
+/// manifest declares the hook (docs/extensions/settings.md), so the panel
+/// would build, pack, publish and install cleanly and then never appear —
+/// with nothing but a line in the app's console to say why.
+///
+/// Asked of the code rather than the source: the bundle is evaluated against
+/// a recording stand-in for the kernel and activated, so a panel registered
+/// from a loop or behind an await counts the same as a literal one. The
+/// libraries the host carries come from the author's own node_modules.
+///
+/// An extension whose activation needs more than the stand-in answers — or
+/// does not finish within [ACTIVATION_DEADLINE_MS] — is not failed for it,
+/// since that would be the check's shortcoming, not the author's, but it is
+/// told the check did not run.
+const ACTIVATION_DEADLINE_MS = 2000
+
+async function checkSettingsPanelDeclared({ bundle, manifest, dir }) {
+  const require = createRequire(resolve(dir, "noop.js"))
+  const sharedModules = new Proxy(
+    {},
+    {
+      get(_, pkg) {
+        if (typeof pkg !== "string") return undefined
+        try {
+          return require(pkg)
+        } catch {
+          // Left undefined, as on a host without it: a bundle that touches it
+          // while activating fails there, and the warning below says so.
+          return undefined
+        }
+      },
+    },
+  )
+  const hostCall = async (method) => (method === "getSettings" ? {} : method.startsWith("dbLookup") ? [] : null)
+  const definitions = []
+  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: {},
+    },
+  }
+  sandbox.globalThis = sandbox
+
+  const registered = new Set()
+  let deadline
+  try {
+    vm.runInContext(await readFile(bundle, "utf8"), vm.createContext(sandbox), { filename: bundle, timeout: ACTIVATION_DEADLINE_MS })
+    const activation = (async () => {
+      for (const definition of definitions) {
+        await definition.onActivation?.({
+          hostCall,
+          timers: { set: () => 0, clear: () => {} },
+          registerHook: (category) => registered.add(category),
+        })
+      }
+    })()
+    // The stand-in's timers never fire, so an activation that waits on one
+    // never settles — and a pending promise does not keep Node running, so
+    // the build would end right here, silently, without copying the manifest.
+    await Promise.race([
+      activation,
+      new Promise((_, reject) => {
+        deadline = setTimeout(
+          () => reject(new Error(`activation had not finished after ${ACTIVATION_DEADLINE_MS / 1000}s, waiting on a timer or the host`)),
+          ACTIVATION_DEADLINE_MS,
+        )
+      }),
+    ])
+  } catch (e) {
+    console.warn(`warning: could not activate the built bundle to check its "hooks" against what it registers, so that check did not run — ${e?.message ?? e}`)
+    return
+  } finally {
+    clearTimeout(deadline)
+  }
+
+  if (registered.has("settingsPanel") && !(manifest.hooks ?? []).includes("settingsPanel")) {
+    throw new BuildError(
+      `the extension registers a settings panel, but ${MANIFEST_ENTRY} does not list "settingsPanel" in "hooks" — ` +
+        `the app would never show the panel. Add it to "hooks", and say where it goes with "settings" ` +
+        `(docs/extensions/settings.md).`,
+    )
+  }
+}

package/h2kext-pack.mjs

@@ -10,7 +10,7 @@
 // The directory holds a built `index.js`, a `manifest.json`, and optionally an
 // `assets/` folder. Nothing here compiles anything — see h2kext.mjs.
 
-import { pack, PackError, H2KEXT_API_VERSION, RESERVED_PREFIX } from "./h2kext.mjs"
+import { pack, PackError, H2KEXT_API_VERSION, RESERVED_PREFIX, settingsReviewReasons } from "./h2kext.mjs"
 
 const args = process.argv.slice(2)
 
@@ -67,6 +67,11 @@ try {
   if (result.manifest.webSockets?.length) {
     console.log(`  may hold connections to: ${result.manifest.webSockets.join(", ")}`)
   }
+  // Not a refusal: placements beyond the usual are allowed, once an admin has
+  // looked. Said now so a publish that waits in the queue is no surprise.
+  for (const reason of settingsReviewReasons(result.manifest)) {
+    console.log(`  held for review on the catalog: ${reason}`)
+  }
 } catch (e) {
   if (e instanceof PackError) {
     console.error(`h2kext-pack: ${dir} is not ready to package:\n${e.message}`)

package/h2kext-publish.mjs

@@ -528,6 +528,15 @@ export async function main(
     const result = await publish({ bytes, manifest, channel, catalog, token }, { fetch })
     say(`published ${result.key} ${result.version} → ${result.channel} (${STATUS_WORDS[result.status] ?? result.status})`)
     if (result.url) say(result.url)
+    // The catalog names what about the settings placement an admin looks at
+    // (docs/extensions/settings.md), or which earlier version's identical
+    // placement one already approved.
+    const review = result.settingsReview
+    if (review?.acceptedIn) {
+      say(`settings placement as approved in ${review.acceptedIn}`)
+    } else {
+      for (const reason of review?.reasons ?? []) say(`settings placement for review: ${reason.message ?? reason.code}`)
+    }
 
     if (notes !== undefined) {
       try {

package/h2kext.mjs

@@ -26,6 +26,10 @@ import yazl from "yazl"
 /// was built against and the host refuses one it does not speak, so an old app
 /// meeting a newer bundle says so instead of failing at a call site.
 ///
+/// It is also the minor version of this package and of `@ham2k/extension-sdk`,
+/// whose `API_VERSION` repeats it: raising it is a minor release of both
+/// (sdk/src/apiVersion.test.ts holds the three together).
+///
 /// Raised when a bundle using something new could not work at all on an app
 /// without it — not for every addition. 2 adds `host.webSocket` and the
 /// manifest's `webSockets` grant; 3 adds timers and `onShow`/`onHide`; 4 lets
@@ -328,6 +332,63 @@ export function validateAdifFieldsScope(manifest) {
   ]
 }
 
+/// The settings sections a manifest's `settings.section` may name without
+/// review — keys of the app's own settings groups. `preferred` is where a
+/// panel usually belongs, by the extension's main purpose; `other` suits one
+/// that tunes something the app already has a section for. The app holds the
+/// same list (`extensionSettingsSections`, app/lib/services/extensions/
+/// settings_placement.dart) and the catalog its own copy; see
+/// docs/extensions/settings.md.
+export const SETTINGS_SECTIONS = {
+  preferred: ["activities", "hunting", "contests", "lookups", "spotting", "dashboard"],
+  other: ["logging", "radio", "map", "exports"],
+}
+
+const SETTINGS_KEYS = ["section", "sidebar", "common"]
+
+/// Everything wrong with the SHAPE of a manifest's `settings`, as a list —
+/// empty for a valid one and for an absent one. What it places is not
+/// checked here: a section outside [SETTINGS_SECTIONS], a sidebar entry or
+/// Common Preferences rows are allowed, and reviewed (see
+/// [settingsReviewReasons]).
+export function validateSettingsPlacement(settings) {
+  if (settings === undefined) return []
+  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+    return [`'settings' must be an object of ${SETTINGS_KEYS.join(" / ")}`]
+  }
+  const problems = []
+  for (const key of Object.keys(settings)) {
+    if (!SETTINGS_KEYS.includes(key)) problems.push(`'settings' has an unknown key '${key}' — only ${SETTINGS_KEYS.join(", ")} are read`)
+  }
+  if (settings.section !== undefined && (typeof settings.section !== "string" || !/^[a-z][a-z0-9-]*$/.test(settings.section))) {
+    problems.push(`'settings.section' must be a settings section's key, such as "${SETTINGS_SECTIONS.preferred[0]}"`)
+  }
+  for (const key of ["sidebar", "common"]) {
+    if (settings[key] !== undefined && typeof settings[key] !== "boolean") problems.push(`'settings.${key}' must be true or false`)
+  }
+  return problems
+}
+
+/// Why the catalog would hold this manifest's settings for an admin's review,
+/// as a list — empty when they go where any extension's may. The app shows
+/// a placement the manifest does not declare as if it were not asked for, so
+/// the manifest is the whole of what is reviewed.
+export function settingsReviewReasons(manifest) {
+  const settings = manifest?.settings
+  const hasPanel = Array.isArray(manifest?.hooks) && manifest.hooks.includes("settingsPanel")
+  const declared = typeof settings === "object" && settings !== null && !Array.isArray(settings) ? settings : {}
+  const reasons = []
+  const allowed = [...SETTINGS_SECTIONS.preferred, ...SETTINGS_SECTIONS.other]
+  if (typeof declared.section === "string") {
+    if (!allowed.includes(declared.section)) reasons.push(`'settings.section' is "${declared.section}", which is not one of ${allowed.join(", ")}`)
+  } else if (hasPanel) {
+    reasons.push(`'hooks' lists 'settingsPanel' but 'settings.section' names no section, so the panel would be a category of its own`)
+  }
+  if (declared.sidebar === true) reasons.push(`'settings.sidebar' asks for an entry in the Settings sidebar`)
+  if (declared.common === true) reasons.push(`'settings.common' asks to add fields to Common Preferences`)
+  return reasons
+}
+
 /// Everything wrong with a candidate bundle, as a list — an author fixing one
 /// problem per run is an author running this five times.
 export function validateManifest(manifest, { source = MANIFEST_ENTRY, forceName = false } = {}) {
@@ -435,6 +496,8 @@ export function validateManifest(manifest, { source = MANIFEST_ENTRY, forceName
 
   for (const problem of validateAdifFieldsScope(manifest)) say(problem)
 
+  for (const problem of validateSettingsPlacement(manifest.settings)) say(problem)
+
   return problems
 }
 

package/package.json

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