@ham2k/extension-tools 0.4.0 → 0.6.0

package/h2kext-build.mjs

@@ -24,7 +24,7 @@ import { copyFile, mkdir, readFile } from "node:fs/promises"
 import { createRequire } from "node:module"
 import { dirname, join, resolve } from "node:path"
 
-import { H2KEXT_API_VERSION, MANIFEST_ENTRY, sharedModulesFor } from "./h2kext.mjs"
+import { H2KEXT_API_VERSION, MANIFEST_ENTRY, TIMERS_API_VERSION, 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.
@@ -202,14 +202,51 @@ function liquidBrowserBuild(fromDir) {
   }
 }
 
+/// Where the author's SDK keeps the file that stands in for the timer globals
+/// (sdk/src/timers.ts), or null if it has none. Resolved from the CALLER's
+/// directory for the same reason as [liquidBrowserBuild]: it must be the very
+/// SDK copy the extension imports, or the bundle carries a second one whose
+/// timers were never handed an identity.
+///
+/// Missing is not an error: a bundle that never schedules anything builds as
+/// it always did, and one that does fails where it calls `setTimeout`. But an
+/// SDK that is installed and simply too old gets a warning, since the manifest
+/// has just claimed an API it cannot fully build.
+function sdkTimersFile(fromDir) {
+  // Resolved under this process's conditions, while esbuild resolves the
+  // extension's own SDK import under its defaults. The two agree for an
+  // author's build, which passes no custom condition; this repo's own
+  // extensions pass [timers] explicitly rather than rely on it.
+  try {
+    return createRequire(resolve(fromDir, "noop.js")).resolve("@ham2k/extension-sdk/timers")
+  } catch (e) {
+    if (e.code === "ERR_PACKAGE_PATH_NOT_EXPORTED") {
+      console.warn(
+        "warning: extension API 3 wants an @ham2k/extension-sdk with timers — this one has none, so a bare setTimeout in the bundle is left undefined",
+      )
+      return null
+    }
+    if (e.code === "MODULE_NOT_FOUND") return null
+    throw e
+  }
+}
+
 /// The esbuild options a Ham2K extension bundle is built with.
 ///
 /// Everything here is a requirement of the runtime rather than a preference:
 /// one IIFE because the sandbox evaluates a script and has no module loader;
 /// `platform: 'neutral'` because there is no node and no DOM; es2020 because
 /// that is what QuickJS-NG speaks.
-export function buildOptionsFor({ entry, outfile, manifest = {}, dir = process.cwd(), alias = {}, inline = [], ...rest } = {}) {
+///
+/// The sandbox has no timer globals of its own, so from extension API 3 the
+/// bundle's `setTimeout` and friends are INJECTED: every bare use, the npm
+/// dependencies' included, becomes the SDK's, which runs on the extension's
+/// own timers. [timers] names the file to inject when the SDK is not the
+/// package the caller's directory resolves, and `false` injects nothing — the
+/// kernel, which IS the implementation.
+export function buildOptionsFor({ entry, outfile, manifest = {}, dir = process.cwd(), alias = {}, inline = [], timers, ...rest } = {}) {
   const liquid = liquidBrowserBuild(dir)
+  const timersFile = timers !== false && (manifest.api ?? H2KEXT_API_VERSION) >= TIMERS_API_VERSION ? (timers ?? sdkTimersFile(dir)) : null
   return {
     entryPoints: [entry],
     ...(outfile ? { outfile } : { write: false }),
@@ -225,6 +262,7 @@ export function buildOptionsFor({ entry, outfile, manifest = {}, dir = process.c
       ...alias,
     },
     plugins: [sharedModulesPlugin({ sharedDependencies: manifest.sharedDependencies, api: manifest.api, inline }), ...(rest.plugins ?? [])],
+    inject: [...(timersFile ? [timersFile] : []), ...(rest.inject ?? [])],
   }
 }
 

package/h2kext-pack.mjs

@@ -64,6 +64,9 @@ try {
     // person installing it will be asked to approve.
     console.log(`  may reach: ${result.manifest.domains.join(", ")}`)
   }
+  if (result.manifest.webSockets?.length) {
+    console.log(`  may hold connections to: ${result.manifest.webSockets.join(", ")}`)
+  }
 } catch (e) {
   if (e instanceof PackError) {
     console.error(`h2kext-pack: ${dir} is not ready to package:\n${e.message}`)

package/h2kext.mjs

@@ -25,7 +25,21 @@ import yazl from "yazl"
 /// The extension API this format describes. A bundle declares the version it
 /// 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.
-export const H2KEXT_API_VERSION = 1
+///
+/// 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`.
+export const H2KEXT_API_VERSION = 3
+
+/// 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
+/// when it tried to connect.
+export const WEB_SOCKETS_API_VERSION = 2
+
+/// 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.
+export const TIMERS_API_VERSION = 3
 
 /// `<prefix>-<name>`, all lowercase. The shape is what the kernel's
 /// `bundleMayDefine` prefix rule can reason about; the PREFIX is what keeps two
@@ -117,6 +131,8 @@ export const SHARED_MODULES_BY_API = {
     "liquidjs",
   ],
 }
+SHARED_MODULES_BY_API[2] = SHARED_MODULES_BY_API[1]
+SHARED_MODULES_BY_API[3] = SHARED_MODULES_BY_API[2]
 
 /// 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
@@ -244,6 +260,31 @@ function calendarDateProblem(value) {
   return at.getUTCFullYear() === year && at.getUTCMonth() === month - 1 && at.getUTCDate() === day ? null : "is not a day that exists"
 }
 
+/// Everything wrong with how a manifest scopes its `adifFields` hook, as a
+/// list — empty for one with no such hook.
+///
+/// The full ADIF export asks an extension for fields only about a contact
+/// carrying a reference that extension answers for, unless the manifest says
+/// `adifFieldsScope: "always"`. A bundle that adds fields and declares neither
+/// a `ref:` type nor the opt-in writes nothing to that file, and nothing at
+/// export time says so. The opt-in is a manifest field rather than something
+/// on the hook so that this check can see it without running the bundle.
+///
+/// Shared with build-config.mjs's manifest checks, like [validateRelevance].
+export function validateAdifFieldsScope(manifest) {
+  const scope = manifest?.adifFieldsScope
+  if (scope !== undefined && scope !== "always") {
+    return [`'adifFieldsScope' must be "always", or left out to scope 'adifFields' to the references this extension handles`]
+  }
+  const hooks = Array.isArray(manifest?.hooks) ? manifest.hooks : []
+  if (!hooks.includes("adifFields") || scope === "always") return []
+  if (hooks.some((hook) => typeof hook === "string" && hook.startsWith("ref:"))) return []
+  return [
+    `'hooks' lists 'adifFields' but no 'ref:' type — the full ADIF export asks an extension only about contacts carrying a reference it handles, ` +
+      `so these fields would never be written; declare the 'ref:' types, or set "adifFieldsScope": "always" (docs/extensions/hooks.md)`,
+  ]
+}
+
 /// 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 } = {}) {
@@ -273,6 +314,14 @@ export function validateManifest(manifest, { source = MANIFEST_ENTRY, forceName
     say(`'api' is ${manifest.api}, but this packer only knows ${H2KEXT_API_VERSION}`)
   }
 
+  if (manifest.webSockets !== undefined) {
+    if (!Array.isArray(manifest.webSockets) || manifest.webSockets.some((host) => typeof host !== "string")) {
+      say("'webSockets' must be a list of hosts")
+    } else if (manifest.webSockets.length && Number.isInteger(manifest.api) && manifest.api < WEB_SOCKETS_API_VERSION) {
+      say(`'webSockets' needs 'api' ${WEB_SOCKETS_API_VERSION} or later — an app older than that would install this and fail only when it connects`)
+    }
+  }
+
   // An extension with no category is CORE to the host: always enabled, and
   // never listed in the Extensions panel. That is a status the app grants its
   // own extensions, not one a distributed bundle may claim for itself — a user
@@ -326,6 +375,8 @@ export function validateManifest(manifest, { source = MANIFEST_ENTRY, forceName
   // parse as "does not gate", so a malformed one would ship as worldwide.
   for (const problem of validateRelevance(manifest.relevance)) say(problem)
 
+  for (const problem of validateAdifFieldsScope(manifest)) say(problem)
+
   return problems
 }
 

package/package.json

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