@ham2k/extension-tools 0.3.0 → 0.5.0

package/README.md

@@ -17,6 +17,12 @@ script, a tsconfig — into the working directory, and refuses rather than
 overwrite anything already there. An existing `package.json` is added to, never
 replaced.
 
+It also writes a `.prettierrc.json` and the `format` / `format:check` scripts,
+and what it scaffolds is already in that style — so `npm run format:check`
+passes on an untouched project, and the code an agent adds to it lands
+formatted the same way. Configure Prettier already, anywhere it looks, and
+yours is left in charge: no config is written, and the command says so.
+
 It takes the key rather than defaulting one: a placeholder like
 `n0call-my-extension` validates, so it would ship, which is the one outcome the
 naming convention exists to stop.

package/h2kext-build.mjs

@@ -19,12 +19,12 @@
 // The repo's own build uses it too, on the same terms, which is what keeps the
 // path a third party takes from being the untested one.
 
-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 { 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 { H2KEXT_API_VERSION, MANIFEST_ENTRY, sharedModulesFor } from './h2kext.mjs'
+import { H2KEXT_API_VERSION, MANIFEST_ENTRY, 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.
@@ -34,12 +34,12 @@ import { H2KEXT_API_VERSION, MANIFEST_ENTRY, sharedModulesFor } from './h2kext.m
 /// copy is exercised by this repo's own build — the extensions here are built
 /// through `build-config.mjs`, which takes a different path into the same
 /// preset.
-export const EXAMPLE_BUILD_SCRIPT = `import { build } from 'esbuild'
-import { buildExtension } from '@ham2k/extension-tools'
+export const EXAMPLE_BUILD_SCRIPT = `import { build } from "esbuild"
+import { buildExtension } from "@ham2k/extension-tools"
 
 await buildExtension(build, { dir: import.meta.dirname })
 
-console.log('built build/index.js')
+console.log("built build/index.js")
 `
 
 export class BuildError extends Error {}
@@ -75,7 +75,7 @@ export class BuildError extends Error {}
 /// failed build.
 function installedVersionOf(pkg, fromDir) {
   try {
-    const require = createRequire(resolve(fromDir, 'noop.js'))
+    const require = createRequire(resolve(fromDir, "noop.js"))
     // Walked up from the entry point rather than resolved directly: a package
     // with an `exports` map that does not list `./package.json` — which is
     // most of them, `@ham2k/lib-qson-cabrillo` included — refuses that path
@@ -84,7 +84,7 @@ function installedVersionOf(pkg, fromDir) {
     let dir = dirname(require.resolve(pkg))
     for (let up = 0; up < 6; up += 1) {
       try {
-        const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+        const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"))
         if (manifest.name === pkg) return manifest.version ?? null
       } catch {
         // Not this directory's package.json, or not readable — keep climbing.
@@ -109,8 +109,9 @@ export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_
   const notOffered = declared.filter((pkg) => !offered.includes(pkg))
   if (notOffered.length) {
     throw new BuildError(
-      `${MANIFEST_ENTRY} declares sharedDependencies the host does not carry (${notOffered.join(', ')}). ` +
-      'Bundle those into your build instead — only what the host offers can be shared.')
+      `${MANIFEST_ENTRY} declares sharedDependencies the host does not carry (${notOffered.join(", ")}). ` +
+        "Bundle those into your build instead — only what the host offers can be shared.",
+    )
   }
 
   // The two say opposite things about the same package, so neither can be
@@ -118,19 +119,19 @@ export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_
   const both = declared.filter((pkg) => inline.includes(pkg))
   if (both.length) {
     throw new BuildError(
-      `${both.join(', ')} appears in both sharedDependencies and inline. ` +
-      "Declare it to use the host's copy, or inline it to ship your own — not both.")
+      `${both.join(", ")} appears in both sharedDependencies and inline. ` + "Declare it to use the host's copy, or inline it to ship your own — not both.",
+    )
   }
 
   const undeclared = offered.filter((pkg) => !declared.includes(pkg) && !inline.includes(pkg))
 
   return {
-    name: 'ham2k-shared-modules',
+    name: "ham2k-shared-modules",
     setup(build) {
       if (declared.length) {
         build.onResolve({ filter: matcherFor(declared) }, (args) => ({
           path: args.path,
-          namespace: 'ham2k-shared-module',
+          namespace: "ham2k-shared-module",
         }))
       }
 
@@ -144,19 +145,22 @@ export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_
           // esbuild's pretty printer and nothing else, so a build script that
           // catches the error — or runs at logLevel 'silent' — shows the
           // author the complaint with the answer stripped off.
-          errors: [{
-            text: `'${args.path}' is carried by the Ham2K extension host, but this bundle does not declare it. ` +
-              `Add it to "sharedDependencies" in ${MANIFEST_ENTRY} with the version range you work with ` +
-              `(e.g. {${JSON.stringify(args.path)}: "^${installedVersionOf(args.path, args.resolveDir) ?? '1.0.0'}"}), ` +
-              `or pass inline: [${JSON.stringify(args.path)}] ` +
-              'to ship your own copy — which is how you use a version the host does not carry.',
-          }],
+          errors: [
+            {
+              text:
+                `'${args.path}' is carried by the Ham2K extension host, but this bundle does not declare it. ` +
+                `Add it to "sharedDependencies" in ${MANIFEST_ENTRY} with the version range you work with ` +
+                `(e.g. {${JSON.stringify(args.path)}: "^${installedVersionOf(args.path, args.resolveDir) ?? "1.0.0"}"}), ` +
+                `or pass inline: [${JSON.stringify(args.path)}] ` +
+                "to ship your own copy — which is how you use a version the host does not carry.",
+            },
+          ],
         }))
       }
 
-      build.onLoad({ filter: /.*/, namespace: 'ham2k-shared-module' }, (args) => ({
+      build.onLoad({ filter: /.*/, namespace: "ham2k-shared-module" }, (args) => ({
         contents: `module.exports = globalThis.__polo.sharedModules[${JSON.stringify(args.path)}];`,
-        loader: 'js',
+        loader: "js",
       }))
     },
   }
@@ -166,7 +170,7 @@ export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_
 /// names carry regex metacharacters (`@ham2k/lib-qson-adif` has a slash, and a
 /// dot would be a wildcard), so every one is escaped.
 function matcherFor(packages) {
-  const alternatives = packages.map((pkg) => pkg.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')).join('|')
+  const alternatives = packages.map((pkg) => pkg.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")).join("|")
   return new RegExp(`^(${alternatives})$`)
 }
 
@@ -186,14 +190,14 @@ function liquidBrowserBuild(fromDir) {
     // `dir` is the caller's to pass — a relative one lands in the catch below
     // and loses the alias, which is precisely the failure this function exists
     // to prevent, arriving with nothing to point at the cause.
-    const require = createRequire(resolve(fromDir, 'noop.js'))
-    return join(dirname(require.resolve('liquidjs/package.json')), 'dist/liquid.browser.mjs')
+    const require = createRequire(resolve(fromDir, "noop.js"))
+    return join(dirname(require.resolve("liquidjs/package.json")), "dist/liquid.browser.mjs")
   } catch (e) {
     // Not installed is the normal case for an extension that neither inlines
     // liquidjs nor uses it, and there is nothing to alias. Anything else is a
     // real fault, and swallowing it would hand the author five unresolvable
     // node built-ins instead.
-    if (e.code === 'MODULE_NOT_FOUND') return null
+    if (e.code === "MODULE_NOT_FOUND") return null
     throw e
   }
 }
@@ -210,20 +214,17 @@ export function buildOptionsFor({ entry, outfile, manifest = {}, dir = process.c
     entryPoints: [entry],
     ...(outfile ? { outfile } : { write: false }),
     bundle: true,
-    format: 'iife',
-    platform: 'neutral',
-    mainFields: ['module', 'main'],
-    target: 'es2020',
-    logLevel: 'warning',
+    format: "iife",
+    platform: "neutral",
+    mainFields: ["module", "main"],
+    target: "es2020",
+    logLevel: "warning",
     ...rest,
     alias: {
       ...(liquid ? { liquidjs: liquid } : {}),
       ...alias,
     },
-    plugins: [
-      sharedModulesPlugin({ sharedDependencies: manifest.sharedDependencies, api: manifest.api, inline }),
-      ...(rest.plugins ?? []),
-    ],
+    plugins: [sharedModulesPlugin({ sharedDependencies: manifest.sharedDependencies, api: manifest.api, inline }), ...(rest.plugins ?? [])],
   }
 }
 
@@ -236,12 +237,12 @@ export function buildOptionsFor({ entry, outfile, manifest = {}, dir = process.c
 ///
 /// [esbuild] is the caller's `build` function, passed in rather than imported
 /// so this module needs no copy of its own.
-export async function buildExtension(esbuild, { dir, entry = 'src/index.ts', outDir = 'build', ...rest } = {}) {
-  if (!dir) throw new BuildError('buildExtension needs `dir`: the extension directory holding manifest.json')
+export async function buildExtension(esbuild, { dir, entry = "src/index.ts", outDir = "build", ...rest } = {}) {
+  if (!dir) throw new BuildError("buildExtension needs `dir`: the extension directory holding manifest.json")
 
   let manifest
   try {
-    manifest = JSON.parse(await readFile(join(dir, MANIFEST_ENTRY), 'utf8'))
+    manifest = JSON.parse(await readFile(join(dir, MANIFEST_ENTRY), "utf8"))
   } catch (e) {
     throw new BuildError(`could not read ${join(dir, MANIFEST_ENTRY)}: ${e.message}`)
   }
@@ -249,13 +250,15 @@ export async function buildExtension(esbuild, { dir, entry = 'src/index.ts', out
   const out = join(dir, outDir)
   await mkdir(out, { recursive: true })
 
-  await esbuild(buildOptionsFor({
-    entry: join(dir, entry),
-    outfile: join(out, 'index.js'),
-    manifest,
-    dir,
-    ...rest,
-  }))
+  await esbuild(
+    buildOptionsFor({
+      entry: join(dir, entry),
+      outfile: join(out, "index.js"),
+      manifest,
+      dir,
+      ...rest,
+    }),
+  )
 
   // 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

package/h2kext-init.mjs

@@ -16,17 +16,17 @@
 // `n0call-my-extension` VALIDATES — N0CALL is a well-formed callsign — so it
 // would ship, which is the one outcome the naming convention exists to stop.
 
-import { readFileSync } from 'node:fs'
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises'
-import { dirname, join, relative, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { readFileSync } from "node:fs"
+import { access, mkdir, readFile, writeFile } from "node:fs/promises"
+import { dirname, join, relative, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
 
-import { EXAMPLE_BUILD_SCRIPT } from './h2kext-build.mjs'
-import { H2KEXT_API_VERSION, SCAFFOLD_SHARED_DEPENDENCIES, keyProblem } from './h2kext.mjs'
+import { EXAMPLE_BUILD_SCRIPT } from "./h2kext-build.mjs"
+import { H2KEXT_API_VERSION, SCAFFOLD_SHARED_DEPENDENCIES, keyProblem } from "./h2kext.mjs"
 
 const args = process.argv.slice(2)
 
-if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
   console.log(`Scaffold a Ham2K Logger extension.
 
   h2kext-init <key> [--dir <path>] [--name "<display name>"]
@@ -35,10 +35,11 @@ The key is '<yourcallsign>-<name>' — e.g. ki2d-my-clock. The callsign is a
 namespace you already have, globally unique, so two authors who never met
 cannot collide. It also namespaces your extension's storage.
 
-Writes manifest.json, src/index.ts, build.mjs, tsconfig.json, AGENTS.md and
-.gitignore into <path> (default: the working directory), refusing rather than
-overwrite anything already there. An existing package.json is added to — the
-scripts and dependencies this needs, nothing of yours replaced.`)
+Writes manifest.json, src/index.ts, build.mjs, tsconfig.json, AGENTS.md,
+.prettierrc.json and .gitignore into <path> (default: the working directory),
+refusing rather than overwrite anything already there. An existing
+package.json is added to — the scripts and dependencies this needs, nothing of
+yours replaced.`)
   process.exit(args.length === 0 ? 1 : 0)
 }
 
@@ -48,9 +49,9 @@ let displayName
 for (let i = 0; i < args.length; i++) {
   // `resolve('')` is the working directory, so a bare `--dir` would scaffold
   // wherever the author happened to be standing.
-  if (args[i] === '--dir') dir = args[++i] ? resolve(args[i]) : undefined
-  else if (args[i] === '--name') displayName = args[++i]
-  else if (!args[i].startsWith('-') && key === undefined) key = args[i]
+  if (args[i] === "--dir") dir = args[++i] ? resolve(args[i]) : undefined
+  else if (args[i] === "--name") displayName = args[++i]
+  else if (!args[i].startsWith("-") && key === undefined) key = args[i]
 }
 
 const problem = keyProblem(key)
@@ -60,16 +61,21 @@ if (problem) {
 }
 
 if (dir === undefined) {
-  console.error('h2kext-init: --dir needs the directory to scaffold into')
+  console.error("h2kext-init: --dir needs the directory to scaffold into")
   process.exit(1)
 }
 
-const shortKey = key.slice(key.indexOf('-') + 1)
-const name = displayName ??
-  shortKey.split('-').filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ')
+const shortKey = key.slice(key.indexOf("-") + 1)
+const name =
+  displayName ??
+  shortKey
+    .split("-")
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join(" ")
 
 const here = dirname(fileURLToPath(import.meta.url))
-const { version: toolsVersion } = JSON.parse(await readFile(join(here, 'package.json'), 'utf8'))
+const { version: toolsVersion } = JSON.parse(await readFile(join(here, "package.json"), "utf8"))
 
 /// The SDK is a SEPARATE package on its own version line, so this cannot be
 /// answered with the version of the tools that happen to be running: a
@@ -93,8 +99,8 @@ function sdkRange(projectDir) {
   for (const start of [projectDir, here]) {
     for (let dir = start; ; dir = dirname(dir)) {
       try {
-        const path = join(dir, 'node_modules/@ham2k/extension-sdk/package.json')
-        const { version } = JSON.parse(readFileSync(path, 'utf8'))
+        const path = join(dir, "node_modules/@ham2k/extension-sdk/package.json")
+        const { version } = JSON.parse(readFileSync(path, "utf8"))
         if (version) return `^${version}`
       } catch {
         // Not here; walk up to the next node_modules.
@@ -102,63 +108,91 @@ function sdkRange(projectDir) {
       if (dirname(dir) === dir) break
     }
   }
-  return 'latest'
+  return "latest"
+}
+
+/// One object of a JSON file, indented as Prettier indents it. Prettier keeps
+/// an object expanded when it was written expanded, so nesting one of these
+/// inside a template is stable at any width; an ARRAY it re-decides by width,
+/// which is why every array below is written inline by hand rather than
+/// stringified. Held by a test that formats everything the scaffold writes
+/// and compares it with what Prettier would have produced.
+function nestedJson(value, indent) {
+  return JSON.stringify(value, null, 2).replaceAll("\n", `\n${indent}`)
 }
 
 /// What the project's package.json has to say for the build, the packer and
 /// the typecheck to run.
 const projectPackage = {
   name: key,
-  version: '0.1.0',
+  version: "0.1.0",
   private: true,
-  type: 'module',
+  type: "module",
   scripts: {
-    build: 'node build.mjs',
-    pack: 'h2kext-pack build',
-    typecheck: 'tsc --noEmit',
+    build: "node build.mjs",
+    pack: "h2kext-pack build",
+    typecheck: "tsc --noEmit",
+    format: "prettier --write .",
+    "format:check": "prettier --check .",
   },
   dependencies: {
-    '@ham2k/extension-sdk': sdkRange(dir),
+    "@ham2k/extension-sdk": sdkRange(dir),
   },
   devDependencies: {
-    '@ham2k/extension-tools': `^${toolsVersion}`,
-    esbuild: '^0.25.0',
-    typescript: '^5.6.0',
+    "@ham2k/extension-tools": `^${toolsVersion}`,
+    esbuild: "^0.25.0",
+    // A patch range, not a caret: Prettier changes its output in a MINOR, and
+    // the templates below are checked against one version here. A caret would
+    // let an author install a 3.x that formats differently and fail the first
+    // `format:check` on files they never touched.
+    prettier: "~3.9.0",
+    typescript: "^5.6.0",
   },
 }
 
 const files = {
-  'manifest.json': `${JSON.stringify({
-    key,
-    name,
-    version: '0.1.0',
-    description: `${name}, an extension for the Ham2K Logger`,
-    category: 'dashboard',
-    api: H2KEXT_API_VERSION,
-    icon: 'hand-wave-outline',
-    // The Extensions list reads this without evaluating any bundle, and the
-    // Add-Panel route shows only what declares `panel`. Undeclared, a panel
-    // extension installs and then cannot be found or switched on.
-    hooks: ['panel'],
-    sharedDependencies: SCAFFOLD_SHARED_DEPENDENCIES,
-  }, null, 2)}\n`,
-
-  'build.mjs': EXAMPLE_BUILD_SCRIPT,
-
-  'src/index.ts': `// ${name} — a panel that says hello.
+  // `hooks` is what the Extensions list reads without evaluating any bundle,
+  // and the Add-Panel route shows only what declares `panel`. Undeclared, a
+  // panel extension installs and then cannot be found or switched on.
+  "manifest.json": `{
+  "key": ${JSON.stringify(key)},
+  "name": ${JSON.stringify(name)},
+  "version": "0.1.0",
+  "description": ${JSON.stringify(`${name}, an extension for the Ham2K Logger`)},
+  "category": "dashboard",
+  "api": ${JSON.stringify(H2KEXT_API_VERSION)},
+  "icon": "hand-wave-outline",
+  "hooks": ["panel"],
+  "sharedDependencies": ${nestedJson(SCAFFOLD_SHARED_DEPENDENCIES, "  ")}
+}
+`,
+
+  "build.mjs": EXAMPLE_BUILD_SCRIPT,
+
+  "src/index.ts": `// ${name} — a panel that says hello.
 //
 // Everything here is the minimum: one hook, one descriptor, one render. See
 // node_modules/@ham2k/extension-sdk/AGENTS.md for what to read next.
 
-import { defineExtension } from '@ham2k/extension-sdk'
-import type { HookContext, PanelContent, PanelDescriptor, PanelHook, PanelRenderArgs } from '@ham2k/extension-sdk'
+import { defineExtension } from "@ham2k/extension-sdk"
+import type { HookContext, PanelContent, PanelDescriptor, PanelHook, PanelRenderArgs } from "@ham2k/extension-sdk"
 
-import manifest from '../manifest.json'
+import manifest from "../manifest.json"
 
 const HelloPanel: PanelHook = {
   /// What the operator sees when choosing a panel to place.
   async getPanels(_args: Record<string, never>, _ctx: HookContext): Promise<PanelDescriptor[]> {
-    return [{ key: 'hello', title: ${JSON.stringify(name)}, description: 'A panel that says hello', icon: 'hand-wave-outline' }]
+    // Written a field per line, and left that way by the formatter: on one
+    // line a long enough --name would push it past the width and the
+    // scaffold's own \`format:check\` would fail on untouched code.
+    return [
+      {
+        key: "hello",
+        title: ${JSON.stringify(name)},
+        description: "A panel that says hello",
+        icon: "hand-wave-outline",
+      },
+    ]
   },
 
   /// What the pane shows. A panel returns CONTENT, never widgets — which is
@@ -168,37 +202,38 @@ const HelloPanel: PanelHook = {
   /// its registered key and then calls this by name, so a near-miss is a panel
   /// that installs, activates, and then renders nothing.
   async render(_args: PanelRenderArgs, _ctx: HookContext): Promise<PanelContent> {
-    return { kind: 'markdown', content: '# Hello, World!' }
+    return { kind: "markdown", content: "# Hello, World!" }
   },
 }
 
 defineExtension({
   ...manifest,
   onActivation({ registerHook }) {
-    registerHook('panel', { key: '${key}', hook: HelloPanel })
+    registerHook("panel", { key: "${key}", hook: HelloPanel })
   },
 })
 `,
 
-  'tsconfig.json': `${JSON.stringify({
-    compilerOptions: {
-      target: 'ES2020',
-      module: 'ESNext',
-      moduleResolution: 'bundler',
-      lib: ['ES2020'],
-      strict: true,
-      noEmit: true,
-      skipLibCheck: true,
-      resolveJsonModule: true,
-    },
-    include: ['src/**/*.ts'],
-  }, null, 2)}\n`,
+  "tsconfig.json": `{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts"]
+}
+`,
 
   // The whole point of the file. Claude Code and its siblings read a project's
   // AGENTS.md before they touch anything, so this is what carries the hook
   // reference, the sandbox's limits and the manifest's shape into the session
   // — none of which anyone would think to go looking for in node_modules.
-  'AGENTS.md': `# ${name}
+  "AGENTS.md": `# ${name}
 
 An extension for the Ham2K Logger. How to write one, what the hooks are, and
 what the sandbox will and will not let you do:
@@ -206,14 +241,24 @@ what the sandbox will and will not let you do:
 @node_modules/@ham2k/extension-sdk/AGENTS.md
 `,
 
-  '.gitignore': 'node_modules/\nbuild/\n*.h2kext\n',
+  // The style the scaffolded files are already in, so `npm run format:check`
+  // passes on an untouched project. Prettier reads the project's .gitignore
+  // from its working directory, so build/ and the packed .h2kext are already
+  // out of its way and no .prettierignore is needed.
+  ".prettierrc.json": `{
+  "printWidth": 160,
+  "semi": false
+}
+`,
+
+  ".gitignore": "node_modules/\nbuild/\n*.h2kext\n",
 }
 
 // Reported together rather than one per run: a scaffold that stops at the
 // first collision has already written half a project, and the second attempt
 // then collides with its own output.
-const packagePath = join(dir, 'package.json')
-const currentPackage = await readFile(packagePath, 'utf8').then(
+const packagePath = join(dir, "package.json")
+const currentPackage = await readFile(packagePath, "utf8").then(
   (text) => {
     try {
       return JSON.parse(text)
@@ -225,27 +270,71 @@ const currentPackage = await readFile(packagePath, 'utf8').then(
       process.exit(1)
     }
   },
-  () => ({}))
+  () => ({}),
+)
 
 // `null`, `[]` and `"text"` all parse, and none of them is something to merge
 // into — reached at the end, each is a raw TypeError over six written files.
-if (currentPackage === null || typeof currentPackage !== 'object' || Array.isArray(currentPackage)) {
+if (currentPackage === null || typeof currentPackage !== "object" || Array.isArray(currentPackage)) {
   console.error(`h2kext-init: ${packagePath} is not a package description — nothing written`)
   process.exit(1)
 }
 
+// Prettier reads the FIRST config it finds, and a `prettier` key in the
+// package.json already here outranks a `.prettierrc.json` sitting beside it —
+// so writing ours would leave a file that is never read, under templates
+// formatted to a style the author's own config contradicts. Their config
+// wins; this one is dropped, and said out loud, because the alternative is a
+// project whose first `npm run format` rewrites every scaffolded file.
+const PRETTIER_CONFIG_FILES = [
+  ".prettierrc",
+  ".prettierrc.json",
+  ".prettierrc.json5",
+  ".prettierrc.yaml",
+  ".prettierrc.yml",
+  ".prettierrc.js",
+  ".prettierrc.mjs",
+  ".prettierrc.cjs",
+  ".prettierrc.toml",
+  "prettier.config.js",
+  "prettier.config.mjs",
+  "prettier.config.cjs",
+]
+const foundAt = async (path) =>
+  await access(join(dir, path)).then(
+    () => true,
+    () => false,
+  )
+let foreignPrettierConfig
+if (currentPackage.prettier !== undefined) foreignPrettierConfig = "the `prettier` key in package.json"
+else
+  for (const path of PRETTIER_CONFIG_FILES) {
+    if (path !== ".prettierrc.json" && (await foundAt(path))) {
+      foreignPrettierConfig = path
+      break
+    }
+  }
+if (foreignPrettierConfig) delete files[".prettierrc.json"]
+
 // `access`, not a read: a directory where a file should go, or one this
 // process cannot read, is something in the way — treated as absent, it becomes
 // a write loop that fails half-way through.
 const existing = []
 for (const path of Object.keys(files)) {
-  if (await access(join(dir, path)).then(() => true, () => false)) existing.push(path)
+  if (
+    await access(join(dir, path)).then(
+      () => true,
+      () => false,
+    )
+  )
+    existing.push(path)
 }
 if (existing.length) {
   const where = relative(process.cwd(), dir)
   console.error(
-    `h2kext-init: ${where.startsWith('..') ? dir : where || '.'} already holds ${existing.join(', ')} — ` +
-    'nothing written. Scaffold into an empty directory with --dir.')
+    `h2kext-init: ${where.startsWith("..") ? dir : where || "."} already holds ${existing.join(", ")} — ` +
+      "nothing written. Scaffold into an empty directory with --dir.",
+  )
   process.exit(1)
 }
 
@@ -262,15 +351,24 @@ for (const [path, content] of Object.entries(files)) {
 // Filled in key by key, never overwritten: what the author already declared —
 // their own name for the project, a version of esbuild they chose — is theirs.
 for (const [field, value] of Object.entries(projectPackage)) {
-  if (typeof value !== 'object') currentPackage[field] ??= value
+  if (typeof value !== "object") currentPackage[field] ??= value
   else for (const [name, entry] of Object.entries(value)) (currentPackage[field] ??= {})[name] ??= entry
 }
 await writeFile(packagePath, `${JSON.stringify(currentPackage, null, 2)}\n`)
 
 console.log(`${key} — ${name}
 
-  ${[...Object.keys(files), 'package.json'].join('\n  ')}
-
+  ${[...Object.keys(files), "package.json"].join("\n  ")}
+${
+  foreignPrettierConfig
+    ? `
+No .prettierrc.json written — ${foreignPrettierConfig} already configures
+Prettier here, and it is the one Prettier reads. The scaffolded files are in
+the style this command's own config describes (print width 160, no
+semicolons); \`npm run format\` will restyle them to yours.
+`
+    : ""
+}
 Next:
   npm install
   npm run build && npm run pack`)

package/h2kext-pack.mjs

@@ -10,11 +10,11 @@
 // 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 } from "./h2kext.mjs"
 
 const args = process.argv.slice(2)
 
-if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
   console.log(`Package an extension directory into a .h2kext bundle.
 
   h2kext-pack <directory> [-o <out.h2kext>] [--force-name]
@@ -37,19 +37,19 @@ Defaults to <key>-<version>.h2kext in the working directory.`)
 
 // Walked by index rather than matched by value: `args.indexOf(a)` finds the
 // FIRST occurrence, so `-o foo foo` mistook the output path for the directory.
-const forceName = args.includes('--force-name')
+const forceName = args.includes("--force-name")
 let dir
 let outPath
 for (let i = 0; i < args.length; i++) {
-  if (args[i] === '-o') {
+  if (args[i] === "-o") {
     outPath = args[++i]
-  } else if (!args[i].startsWith('-') && dir === undefined) {
+  } else if (!args[i].startsWith("-") && dir === undefined) {
     dir = args[i]
   }
 }
 
 if (!dir) {
-  console.error('h2kext-pack: name the directory to package')
+  console.error("h2kext-pack: name the directory to package")
   process.exit(1)
 }
 
@@ -58,11 +58,14 @@ try {
   const assets = result.files.length - 2
   console.log(`${result.outPath}`)
   console.log(`  ${result.manifest.key} ${result.manifest.version} — ${result.manifest.name}`)
-  console.log(`  ${assets} asset${assets === 1 ? '' : 's'}`)
+  console.log(`  ${assets} asset${assets === 1 ? "" : "s"}`)
   if (result.manifest.domains?.length) {
     // Named on the way out, because this is the one part of the manifest the
     // person installing it will be asked to approve.
-    console.log(`  may reach: ${result.manifest.domains.join(', ')}`)
+    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) {

package/h2kext-publish.mjs

@@ -16,27 +16,27 @@
 // never written anywhere — not to a config file, not to the terminal, not into
 // an error message.
 
-import { realpathSync } from 'node:fs'
-import { mkdtemp, readFile, rm, stat } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { inflateRawSync } from 'node:zlib'
+import { realpathSync } from "node:fs"
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+import { inflateRawSync } from "node:zlib"
 
-import { MANIFEST_ENTRY, pack, PackError } from './h2kext.mjs'
+import { MANIFEST_ENTRY, pack, PackError } from "./h2kext.mjs"
 
-export const DEFAULT_CATALOG = 'https://catalog.ham2k.net'
-export const PUBLISH_PATH = '/api/v1/publish'
-export const SUBMISSIONS_PATH = '/api/v1/submissions'
-export const TOKEN_ENV = 'H2K_CATALOG_TOKEN'
+export const DEFAULT_CATALOG = "https://catalog.ham2k.net"
+export const PUBLISH_PATH = "/api/v1/publish"
+export const SUBMISSIONS_PATH = "/api/v1/submissions"
+export const TOKEN_ENV = "H2K_CATALOG_TOKEN"
 /// How finished a release is, steadiest first — NOT an app edition. The
 /// catalog cascades, so a release on `stable` is visible to everyone and one
 /// on `bleeding` only to somebody who asked for it.
-export const CHANNELS = ['stable', 'unstable', 'bleeding']
+export const CHANNELS = ["stable", "unstable", "bleeding"]
 
 /// What `--channel` means when it is not given. Publishing without saying is
 /// publishing something finished; anything rougher is a choice worth typing.
-export const DEFAULT_CHANNEL = 'stable'
+export const DEFAULT_CHANNEL = "stable"
 
 /// The catalog refuses a larger upload before reading it (§5.1 step 2),
 /// because the app never downloads more than this (`kMaxDownloadBytes`).
@@ -51,7 +51,7 @@ export const EXIT_USAGE = 2
 /// How a submission status reads on the result line. `pending` means a
 /// reviewer has not looked yet; saying "review" is what stops an author
 /// waiting for the extension to appear.
-const STATUS_WORDS = { pending: 'pending review' }
+const STATUS_WORDS = { pending: "pending review" }
 
 export class PublishError extends Error {
   constructor(message, exitCode = EXIT_REFUSED) {
@@ -94,7 +94,7 @@ or cannot be reached, 2 for a usage problem.`
 export function readManifestFromBundle(bytes) {
   const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)
   if (buf.length < 22 || buf.readUInt32LE(0) !== 0x04034b50) {
-    throw new PublishError('not a .h2kext: not a zip')
+    throw new PublishError("not a .h2kext: not a zip")
   }
   // The end-of-central-directory record is the last 22 bytes plus a comment of
   // up to 64 KiB, so the search walks backwards over that much and no more.
@@ -105,13 +105,13 @@ export function readManifestFromBundle(bytes) {
       break
     }
   }
-  if (eocd < 0) throw new PublishError('not a .h2kext: no zip central directory')
+  if (eocd < 0) throw new PublishError("not a .h2kext: no zip central directory")
 
   const count = buf.readUInt16LE(eocd + 10)
   let offset = buf.readUInt32LE(eocd + 16)
   for (let n = 0; n < count; n++) {
     if (offset + 46 > buf.length || buf.readUInt32LE(offset) !== 0x02014b50) {
-      throw new PublishError('not a .h2kext: damaged zip central directory')
+      throw new PublishError("not a .h2kext: damaged zip central directory")
     }
     const method = buf.readUInt16LE(offset + 10)
     const compressedSize = buf.readUInt32LE(offset + 20)
@@ -119,7 +119,7 @@ export function readManifestFromBundle(bytes) {
     const extraLength = buf.readUInt16LE(offset + 30)
     const commentLength = buf.readUInt16LE(offset + 32)
     const localOffset = buf.readUInt32LE(offset + 42)
-    const name = buf.toString('utf8', offset + 46, offset + 46 + nameLength)
+    const name = buf.toString("utf8", offset + 46, offset + 46 + nameLength)
     if (name === MANIFEST_ENTRY) {
       // Every offset here comes from the file itself, so a truncated or
       // doctored bundle can point past its own end: refused as a bundle,
@@ -139,7 +139,7 @@ export function readManifestFromBundle(bytes) {
         }
       } else throw new PublishError(`not a .h2kext: ${MANIFEST_ENTRY} uses zip compression method ${method}`)
       try {
-        return JSON.parse(raw.toString('utf8'))
+        return JSON.parse(raw.toString("utf8"))
       } catch (e) {
         throw new PublishError(`${MANIFEST_ENTRY} inside the bundle is not valid JSON: ${e.message}`)
       }
@@ -157,13 +157,13 @@ async function loadBundle(source, { forceName }) {
   try {
     info = await stat(source)
   } catch (e) {
-    throw new PublishError(`${source}: ${e.code === 'ENOENT' ? 'no such file or directory' : e.message}`)
+    throw new PublishError(`${source}: ${e.code === "ENOENT" ? "no such file or directory" : e.message}`)
   }
   if (!info.isDirectory()) return await readFile(source)
 
-  const tmp = await mkdtemp(join(tmpdir(), 'h2kext-publish-'))
+  const tmp = await mkdtemp(join(tmpdir(), "h2kext-publish-"))
   try {
-    const { outPath } = await pack(source, { outPath: join(tmp, 'bundle.h2kext'), forceName })
+    const { outPath } = await pack(source, { outPath: join(tmp, "bundle.h2kext"), forceName })
     return await readFile(outPath)
   } catch (e) {
     if (e instanceof PackError) throw new PublishError(`${source} is not ready to publish:\n${e.message}`)
@@ -195,9 +195,7 @@ async function call(fetch, catalog, path, init) {
 /// What a refusal says: the server's `error` and `code`, or its raw body when
 /// it sent no JSON — a proxy's HTML is still worth seeing.
 function refusal({ response, text, body }) {
-  return body?.error
-    ? `${body.error}${body.code ? ` (${body.code})` : ''}`
-    : text.trim() || response.statusText || 'no response body'
+  return body?.error ? `${body.error}${body.code ? ` (${body.code})` : ""}` : text.trim() || response.statusText || "no response body"
 }
 
 /// Uploads [bytes] as the raw request body (§5.1: no multipart) and
@@ -208,8 +206,8 @@ function refusal({ response, text, body }) {
 /// failure, not the catalog's.
 export async function publish({ bytes, manifest, channel, catalog, token }, { fetch = globalThis.fetch } = {}) {
   const answer = await call(fetch, catalog, `${PUBLISH_PATH}?channel=${channel}`, {
-    method: 'POST',
-    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/zip' },
+    method: "POST",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/zip" },
     body: bytes,
   })
   if (answer.response.status === 201 && answer.body) return answer.body
@@ -220,8 +218,8 @@ export async function publish({ bytes, manifest, channel, catalog, token }, { fe
 /// outside 2xx is a [PublishError]; the submission it was for stands.
 export async function setReleaseNotes({ submissionId, notes, catalog, token }, { fetch = globalThis.fetch } = {}) {
   const answer = await call(fetch, catalog, `${SUBMISSIONS_PATH}/${encodeURIComponent(submissionId)}/notes`, {
-    method: 'PUT',
-    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    method: "PUT",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
     body: JSON.stringify({ releaseNotes: notes }),
   })
   if (answer.response.ok) return
@@ -231,7 +229,7 @@ export async function setReleaseNotes({ submissionId, notes, catalog, token }, {
 /// The command. Returns the exit code rather than exiting, so the same code
 /// runs under a test with a fake `fetch` and captured output.
 export async function main(argv, { env = process.env, fetch = globalThis.fetch, stdout = process.stdout, stderr = process.stderr } = {}) {
-  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
     stdout.write(`${USAGE}\n`)
     return argv.length === 0 ? EXIT_USAGE : 0
   }
@@ -240,7 +238,7 @@ export async function main(argv, { env = process.env, fetch = globalThis.fetch,
 
   // Every line out goes through this, so the token cannot reach a terminal or
   // a CI log by way of an error that happened to quote a header or a URL.
-  const redact = (s) => (token ? String(s).split(token).join('<token>') : String(s))
+  const redact = (s) => (token ? String(s).split(token).join("<token>") : String(s))
   const say = (s) => stdout.write(`${redact(s)}\n`)
   const complain = (s) => stderr.write(`h2kext-publish: ${redact(s)}\n`)
 
@@ -264,40 +262,42 @@ export async function main(argv, { env = process.env, fetch = globalThis.fetch,
     }
     for (let i = 0; i < argv.length; i++) {
       const arg = argv[i]
-      if (arg === '--channel') channel = valueOf(i++)
-      else if (arg === '--notes') notes = valueOf(i++)
-      else if (arg === '--catalog') catalog = valueOf(i++)
-      else if (arg === '--force-name') forceName = true
-      else if (arg === '--token') throw new PublishError(`there is no --token option; set ${TOKEN_ENV} instead`, EXIT_USAGE)
-      else if (arg.startsWith('-')) throw new PublishError(`unknown option '${arg}'`, EXIT_USAGE)
+      if (arg === "--channel") channel = valueOf(i++)
+      else if (arg === "--notes") notes = valueOf(i++)
+      else if (arg === "--catalog") catalog = valueOf(i++)
+      else if (arg === "--force-name") forceName = true
+      else if (arg === "--token") throw new PublishError(`there is no --token option; set ${TOKEN_ENV} instead`, EXIT_USAGE)
+      else if (arg.startsWith("-")) throw new PublishError(`unknown option '${arg}'`, EXIT_USAGE)
       else if (source === undefined) source = arg
     }
 
-    if (!source) throw new PublishError('name the bundle or directory to publish', EXIT_USAGE)
+    if (!source) throw new PublishError("name the bundle or directory to publish", EXIT_USAGE)
     channel ??= DEFAULT_CHANNEL
     if (!CHANNELS.includes(channel)) {
-      throw new PublishError(`--channel must be one of ${CHANNELS.join(', ')}${channel ? `, not '${channel}'` : ''}`, EXIT_USAGE)
+      throw new PublishError(`--channel must be one of ${CHANNELS.join(", ")}${channel ? `, not '${channel}'` : ""}`, EXIT_USAGE)
     }
     if (!token) {
       throw new PublishError(`no token — set ${TOKEN_ENV} (get one at ${catalog}/publish)`, EXIT_USAGE)
     }
     try {
-      catalog = new URL(catalog).href.replace(/\/$/, '')
+      catalog = new URL(catalog).href.replace(/\/$/, "")
     } catch {
       throw new PublishError(`--catalog must be a URL, not '${catalog}'`, EXIT_USAGE)
     }
 
     const bytes = await loadBundle(source, { forceName })
     if (bytes.length > MAX_BUNDLE_BYTES) {
-      throw new PublishError(`${source} is ${bytes.length} bytes; the catalog takes at most 16 MiB (${MAX_BUNDLE_BYTES} bytes), because the app downloads no more than that`)
+      throw new PublishError(
+        `${source} is ${bytes.length} bytes; the catalog takes at most 16 MiB (${MAX_BUNDLE_BYTES} bytes), because the app downloads no more than that`,
+      )
     }
     const manifest = readManifestFromBundle(bytes)
-    for (const field of ['key', 'version']) {
-      if (typeof manifest[field] !== 'string' || manifest[field].trim() === '') {
+    for (const field of ["key", "version"]) {
+      if (typeof manifest[field] !== "string" || manifest[field].trim() === "") {
         throw new PublishError(`${MANIFEST_ENTRY} inside the bundle has no '${field}'`)
       }
     }
-    say(`publishing ${manifest.key} ${manifest.version}${manifest.name ? ` — ${manifest.name}` : ''} → ${channel} at ${catalog}`)
+    say(`publishing ${manifest.key} ${manifest.version}${manifest.name ? ` — ${manifest.name}` : ""} → ${channel} at ${catalog}`)
 
     const result = await publish({ bytes, manifest, channel, catalog, token }, { fetch })
     say(`published ${result.key} ${result.version} → ${result.channel} (${STATUS_WORDS[result.status] ?? result.status})`)

package/h2kext.mjs

@@ -16,16 +16,25 @@
 // one way it can be built WRONG is invisible until the extension is running
 // inside somebody's app.
 
-import { createWriteStream } from 'node:fs'
-import { readFile, readdir, stat } from 'node:fs/promises'
-import { join, posix, relative, sep } from 'node:path'
-import { parseCallsign } from '@ham2k/lib-callsigns'
-import yazl from 'yazl'
+import { createWriteStream } from "node:fs"
+import { readFile, readdir, stat } from "node:fs/promises"
+import { join, posix, relative, sep } from "node:path"
+import { parseCallsign } from "@ham2k/lib-callsigns"
+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.
+export const H2KEXT_API_VERSION = 2
+
+/// 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
 
 /// `<prefix>-<name>`, all lowercase. The shape is what the kernel's
 /// `bundleMayDefine` prefix rule can reason about; the PREFIX is what keeps two
@@ -36,7 +45,7 @@ export const KEY_PATTERN = /^[a-z0-9]+-[a-z0-9-]*[a-z0-9]$/
 /// bundle unless it is one of ours: there is no signing yet, so anyone could
 /// claim it, and a key is what the app shows when it says where a hook came
 /// from.
-export const RESERVED_PREFIX = 'ham2k'
+export const RESERVED_PREFIX = "ham2k"
 
 /// Whether [prefix] is a real amateur callsign — the namespace every author of
 /// this software already has, globally unique, and free.
@@ -66,14 +75,14 @@ export const SAFE_KEY_PATTERN = /^[a-z0-9][a-z0-9-]*$/
 /// app is where the rule bites, refusing a reserved or colliding key at
 /// install.
 export function keyProblem(key, { forceName = false } = {}) {
-  if (typeof key !== 'string' || !SAFE_KEY_PATTERN.test(key)) {
+  if (typeof key !== "string" || !SAFE_KEY_PATTERN.test(key)) {
     return `key '${key}' must be lowercase, and contain only letters, digits and hyphens`
   }
   if (forceName) return null
   if (!KEY_PATTERN.test(key)) {
     return `key '${key}' must be '<callsign>-<name>' (e.g. ki2d-my-clock)`
   }
-  const prefix = key.slice(0, key.indexOf('-'))
+  const prefix = key.slice(0, key.indexOf("-"))
   if (prefix === RESERVED_PREFIX) {
     return `key '${key}' uses the '${RESERVED_PREFIX}-' prefix, which is reserved for Ham2K's own extensions`
   }
@@ -84,9 +93,9 @@ export function keyProblem(key, { forceName = false } = {}) {
 }
 
 /// The only entries a bundle may contain, beyond `assets/`.
-export const MANIFEST_ENTRY = 'manifest.json'
-export const BUNDLE_ENTRY = 'index.js'
-export const ASSETS_PREFIX = 'assets/'
+export const MANIFEST_ENTRY = "manifest.json"
+export const BUNDLE_ENTRY = "index.js"
+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
@@ -103,20 +112,21 @@ export const ASSETS_PREFIX = 'assets/'
 /// live once this file is published on its own.
 export const SHARED_MODULES_BY_API = {
   1: [
-    '@ham2k/lib-callsigns',
-    '@ham2k/lib-country-files',
-    '@ham2k/lib-cqmag-data',
-    '@ham2k/lib-dxcc-data',
-    '@ham2k/lib-format-tools',
-    '@ham2k/lib-geo-tools',
-    '@ham2k/lib-operation-data',
-    '@ham2k/lib-qson-adif',
-    '@ham2k/lib-qson-cabrillo',
-    '@ham2k/lib-qson-tools',
-    'i18next',
-    'liquidjs',
+    "@ham2k/lib-callsigns",
+    "@ham2k/lib-country-files",
+    "@ham2k/lib-cqmag-data",
+    "@ham2k/lib-dxcc-data",
+    "@ham2k/lib-format-tools",
+    "@ham2k/lib-geo-tools",
+    "@ham2k/lib-operation-data",
+    "@ham2k/lib-qson-adif",
+    "@ham2k/lib-qson-cabrillo",
+    "@ham2k/lib-qson-tools",
+    "i18next",
+    "liquidjs",
   ],
 }
+SHARED_MODULES_BY_API[2] = SHARED_MODULES_BY_API[1]
 
 /// 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
@@ -136,14 +146,14 @@ export const SHARED_MODULES_BY_API = {
 /// actually holds, so a major bump there fails a build rather than shipping a
 /// scaffold that cannot install.
 export const SCAFFOLD_SHARED_DEPENDENCIES = {
-  '@ham2k/lib-callsigns': '^1.0.0',
-  '@ham2k/lib-country-files': '^1.0.0',
-  '@ham2k/lib-dxcc-data': '^1.0.0',
-  '@ham2k/lib-format-tools': '^1.0.0',
-  '@ham2k/lib-geo-tools': '^1.0.0',
-  '@ham2k/lib-operation-data': '^1.0.0',
-  'i18next': '^23.0.0',
-  'liquidjs': '^10.0.0',
+  "@ham2k/lib-callsigns": "^1.0.0",
+  "@ham2k/lib-country-files": "^1.0.0",
+  "@ham2k/lib-dxcc-data": "^1.0.0",
+  "@ham2k/lib-format-tools": "^1.0.0",
+  "@ham2k/lib-geo-tools": "^1.0.0",
+  "@ham2k/lib-operation-data": "^1.0.0",
+  i18next: "^23.0.0",
+  liquidjs: "^10.0.0",
 }
 
 /// What the host offers a bundle declaring [api].
@@ -157,7 +167,7 @@ export class PackError extends Error {}
 /// the operator's own values against, so a value outside it can never match
 /// anyone. Continents are cty.dat's column-4 codes; the regions are the three
 /// the ITU Radio Regulations define.
-export const GEO_CONTINENTS = ['AF', 'AS', 'EU', 'NA', 'OC', 'SA', 'AN']
+export const GEO_CONTINENTS = ["AF", "AS", "EU", "NA", "OC", "SA", "AN"]
 export const GEO_ITU_REGIONS = [1, 2, 3]
 
 /// What `relevance.interests` may name: a mode, a band group, or a style of
@@ -167,13 +177,9 @@ export const GEO_ITU_REGIONS = [1, 2, 3]
 /// asks for.
 ///
 /// Growing the list is how a new interest arrives. Guessing is not.
-export const RELEVANCE_INTERESTS = [
-  'cw', 'phone', 'digital',
-  'hf', 'vhf', 'uhf', 'microwave',
-  'satellite', 'portable', 'qrp',
-]
+export const RELEVANCE_INTERESTS = ["cw", "phone", "digital", "hf", "vhf", "uhf", "microwave", "satellite", "portable", "qrp"]
 
-const RELEVANCE_KEYS = ['entities', 'countries', 'continents', 'ituRegions', 'dates', 'interests']
+const RELEVANCE_KEYS = ["entities", "countries", "continents", "ituRegions", "dates", "interests"]
 
 /// Everything wrong with a manifest's `relevance`, as a list — empty for a
 /// valid one, and for an absent one, which means worldwide and undated.
@@ -188,13 +194,13 @@ const RELEVANCE_KEYS = ['entities', 'countries', 'continents', 'ituRegions', 'da
 /// rules are the format's, not the repo's, and this module is the format.
 export function validateRelevance(relevance) {
   if (relevance === undefined) return []
-  if (typeof relevance !== 'object' || relevance === null || Array.isArray(relevance)) {
-    return [`'relevance' must be an object of ${RELEVANCE_KEYS.join(' / ')}`]
+  if (typeof relevance !== "object" || relevance === null || Array.isArray(relevance)) {
+    return [`'relevance' must be an object of ${RELEVANCE_KEYS.join(" / ")}`]
   }
   const problems = []
   for (const key of Object.keys(relevance)) {
     if (!RELEVANCE_KEYS.includes(key)) {
-      problems.push(`'relevance' has an unknown key '${key}' — only ${RELEVANCE_KEYS.join(', ')} are read`)
+      problems.push(`'relevance' has an unknown key '${key}' — only ${RELEVANCE_KEYS.join(", ")} are read`)
     }
   }
   for (const key of RELEVANCE_KEYS) {
@@ -213,25 +219,21 @@ export function validateRelevance(relevance) {
 }
 
 function relevanceValueProblem(key, value) {
-  if (key === 'ituRegions') {
-    return GEO_ITU_REGIONS.includes(value) ? null : `is not an ITU region (${GEO_ITU_REGIONS.join(', ')})`
+  if (key === "ituRegions") {
+    return GEO_ITU_REGIONS.includes(value) ? null : `is not an ITU region (${GEO_ITU_REGIONS.join(", ")})`
   }
-  if (typeof value !== 'string' || value.trim() === '') return 'is not a non-empty string'
-  if (key === 'entities') {
-    return /^\*?[A-Z0-9/]+$/.test(value.toUpperCase())
-      ? null
-      : "is not a DXCC entity prefix (letters, digits and '/', with an optional leading '*')"
+  if (typeof value !== "string" || value.trim() === "") return "is not a non-empty string"
+  if (key === "entities") {
+    return /^\*?[A-Z0-9/]+$/.test(value.toUpperCase()) ? null : "is not a DXCC entity prefix (letters, digits and '/', with an optional leading '*')"
   }
-  if (key === 'countries') {
-    return /^[a-z]{2}$/.test(value.toLowerCase()) ? null : 'is not a two-letter ISO country code'
+  if (key === "countries") {
+    return /^[a-z]{2}$/.test(value.toLowerCase()) ? null : "is not a two-letter ISO country code"
   }
-  if (key === 'dates') return calendarDateProblem(value)
-  if (key === 'interests') {
-    return RELEVANCE_INTERESTS.includes(value)
-      ? null
-      : `is not an interest (${RELEVANCE_INTERESTS.join(' ')})`
+  if (key === "dates") return calendarDateProblem(value)
+  if (key === "interests") {
+    return RELEVANCE_INTERESTS.includes(value) ? null : `is not an interest (${RELEVANCE_INTERESTS.join(" ")})`
   }
-  return GEO_CONTINENTS.includes(value.toUpperCase()) ? null : `is not a continent (${GEO_CONTINENTS.join(' ')})`
+  return GEO_CONTINENTS.includes(value.toUpperCase()) ? null : `is not a continent (${GEO_CONTINENTS.join(" ")})`
 }
 
 /// Why [value] is not a UTC calendar day, or null.
@@ -245,13 +247,11 @@ function relevanceValueProblem(key, value) {
 /// would fail the round trip here and pass in Dart — a disagreement between
 /// the two on an input neither should be accepting anyway.
 function calendarDateProblem(value) {
-  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return 'is not a YYYY-MM-DD date'
-  const [year, month, day] = value.split('-').map(Number)
-  if (year < 1000) return 'is not a year an event could fall in'
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return "is not a YYYY-MM-DD date"
+  const [year, month, day] = value.split("-").map(Number)
+  if (year < 1000) return "is not a year an event could fall in"
   const at = new Date(Date.UTC(year, month - 1, day))
-  return at.getUTCFullYear() === year && at.getUTCMonth() === month - 1 && at.getUTCDate() === day
-    ? null
-    : 'is not a day that exists'
+  return at.getUTCFullYear() === year && at.getUTCMonth() === month - 1 && at.getUTCDate() === day ? null : "is not a day that exists"
 }
 
 /// Everything wrong with a candidate bundle, as a list — an author fixing one
@@ -260,12 +260,12 @@ export function validateManifest(manifest, { source = MANIFEST_ENTRY, forceName
   const problems = []
   const say = (m) => problems.push(`${source}: ${m}`)
 
-  if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest)) {
+  if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
     return [`${source}: must be a JSON object`]
   }
 
-  for (const field of ['key', 'name', 'version', 'description']) {
-    if (typeof manifest[field] !== 'string' || manifest[field].trim() === '') {
+  for (const field of ["key", "name", "version", "description"]) {
+    if (typeof manifest[field] !== "string" || manifest[field].trim() === "") {
       say(`missing required field '${field}'`)
     }
   }
@@ -283,24 +283,32 @@ 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
   // could neither see it nor turn it off.
-  if (typeof manifest.category !== 'string' || manifest.category.trim() === '') {
+  if (typeof manifest.category !== "string" || manifest.category.trim() === "") {
     say("missing 'category' — a bundle with none is treated as core: always on, and invisible in the Extensions panel")
   }
 
   if (manifest.sharedDependencies !== undefined) {
     const declared = manifest.sharedDependencies
-    if (typeof declared !== 'object' || declared === null || Array.isArray(declared)) {
+    if (typeof declared !== "object" || declared === null || Array.isArray(declared)) {
       say("'sharedDependencies' must be an object of package name to version range")
     } else {
       const offered = sharedModulesFor(manifest.api)
       for (const [pkg, range] of Object.entries(declared)) {
         if (!offered.includes(pkg)) {
           say(`'sharedDependencies' names '${pkg}', which the host does not carry — bundle it into your build instead`)
-        } else if (typeof range !== 'string' || range.trim() === '') {
+        } else if (typeof range !== "string" || range.trim() === "") {
           say(`'sharedDependencies' entry '${pkg}' needs a version range, e.g. "^1.0.0"`)
         }
       }
@@ -361,7 +369,7 @@ export function findSharedModuleReferences(source) {
 export async function readBundleDirectory(dir, { forceName = false } = {}) {
   let manifestRaw
   try {
-    manifestRaw = await readFile(join(dir, MANIFEST_ENTRY), 'utf8')
+    manifestRaw = await readFile(join(dir, MANIFEST_ENTRY), "utf8")
   } catch {
     throw new PackError(`no ${MANIFEST_ENTRY} in ${dir}`)
   }
@@ -377,11 +385,11 @@ export async function readBundleDirectory(dir, { forceName = false } = {}) {
 
   let bundleSource
   try {
-    bundleSource = await readFile(join(dir, BUNDLE_ENTRY), 'utf8')
+    bundleSource = await readFile(join(dir, BUNDLE_ENTRY), "utf8")
   } catch {
     throw new PackError(`no ${BUNDLE_ENTRY} in ${dir} — build your extension first; this packages, it does not compile`)
   }
-  if (bundleSource.trim() === '') problems.push(`${BUNDLE_ENTRY}: is empty`)
+  if (bundleSource.trim() === "") problems.push(`${BUNDLE_ENTRY}: is empty`)
 
   // Using the host's shared libraries is allowed, and is much the better
   // option — inlining them costs about ten times the bundle size. What is NOT
@@ -393,12 +401,15 @@ export async function readBundleDirectory(dir, { forceName = false } = {}) {
   const undeclared = findSharedModuleReferences(bundleSource).filter((pkg) => !(pkg in declaredShared))
   if (undeclared.length) {
     problems.push(
-      `${BUNDLE_ENTRY}: uses the host's shared modules without declaring them (${undeclared.join(', ')}). ` +
+      `${BUNDLE_ENTRY}: uses the host's shared modules without declaring them (${undeclared.join(", ")}). ` +
         `Add them to 'sharedDependencies' in ${MANIFEST_ENTRY} with the version range you work with, ` +
-        'e.g. {"' + undeclared[0] + '": "^1.0.0"}, so the host can refuse to load this against a version you never tested.')
+        'e.g. {"' +
+        undeclared[0] +
+        '": "^1.0.0"}, so the host can refuse to load this against a version you never tested.',
+    )
   }
 
-  if (problems.length) throw new PackError(problems.join('\n'))
+  if (problems.length) throw new PackError(problems.join("\n"))
 
   const files = [
     { entry: MANIFEST_ENTRY, path: join(dir, MANIFEST_ENTRY) },
@@ -419,7 +430,7 @@ async function collectAssets(dir) {
     // No assets/ is ordinary. Anything else — unreadable, an I/O error, a
     // broken symlink — is not, and swallowing it ships a bundle silently
     // missing files the author believes are in it.
-    if (e.code === 'ENOENT') return []
+    if (e.code === "ENOENT") return []
     throw new PackError(`could not read ${root}: ${e.message}`)
   }
 
@@ -446,9 +457,9 @@ export function writeBundle(files, outPath) {
     for (const file of files) zip.addFile(file.path, file.entry)
     const out = createWriteStream(outPath)
     zip.outputStream.pipe(out)
-    out.on('close', () => resolve(outPath))
-    out.on('error', reject)
-    zip.outputStream.on('error', reject)
+    out.on("close", () => resolve(outPath))
+    out.on("error", reject)
+    zip.outputStream.on("error", reject)
     zip.end()
   })
 }

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@ham2k/extension-tools",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Build and package extensions for the Ham2K Logger",
-  "keywords": ["ham2k", "ham radio", "amateur radio", "extension", "esbuild", "h2kext"],
+  "keywords": [
+    "ham2k",
+    "ham radio",
+    "amateur radio",
+    "extension",
+    "esbuild",
+    "h2kext"
+  ],
   "license": "MIT",
   "author": "Sebastian Delmont <sd@ham2k.com>",
   "homepage": "https://ham2k.com",