@ham2k/extension-tools 0.5.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.mjs

@@ -28,14 +28,19 @@ import yazl from "yazl"
 ///
 /// 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.
-export const H2KEXT_API_VERSION = 2
+/// 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
 /// authors who never met from choosing the same key.
@@ -127,6 +132,7 @@ export const SHARED_MODULES_BY_API = {
   ],
 }
 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
@@ -254,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 } = {}) {
@@ -344,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.5.0",
+  "version": "0.6.0",
   "description": "Build and package extensions for the Ham2K Logger",
   "keywords": [
     "ham2k",