@ham2k/extension-tools 1.15.0 → 1.16.0

package/h2kext-build.mjs

@@ -25,7 +25,7 @@ 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, 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,6 +347,7 @@ 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
@@ -376,6 +378,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 +413,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.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.
@@ -148,7 +155,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 +196,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
@@ -511,7 +519,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 +531,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)]
 }

package/package.json

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