@ham2k/extension-tools 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @ham2k/extension-tools
+
+Build and package extensions for the [Ham2K Logger](https://ham2k.com).
+
+```sh
+npm install --save-dev @ham2k/extension-tools esbuild
+```
+
+## Building
+
+```js
+import { build } from 'esbuild'
+import { buildExtension } from '@ham2k/extension-tools'
+
+await buildExtension(build, { dir: import.meta.dirname })
+```
+
+Reads your `manifest.json`, compiles `src/index.ts` into `build/index.js`, and
+copies the manifest alongside it. The esbuild settings it applies are
+requirements of the runtime rather than preferences: one IIFE because the
+sandbox evaluates a script and has no module loader, `neutral` because there is
+no Node and no DOM, and `es2020` because that is what its engine speaks.
+
+esbuild is yours to bring — the preset takes your `build` function rather than
+importing its own, so there is only ever one copy of it.
+
+Everything your manifest's `sharedDependencies` names becomes a lookup on the
+library the host already holds, which is worth roughly thirty times the bundle
+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.
+
+## Packaging
+
+```sh
+npx h2kext-pack build -o my-extension.h2kext
+```
+
+Packages a directory holding a built `index.js`, a `manifest.json` and an
+optional `assets/`. It packages; it does not compile.
+
+It reports every problem at once, and refuses what would install cleanly and
+then misbehave where you cannot see it. Extension keys are `<callsign>-<name>`
+— the namespace every author of this software already holds, so two people who
+never met cannot ship the same key.
+
+## License
+
+MPL-2.0

package/h2kext-build.mjs

@@ -0,0 +1,208 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MPL-2.0
+//
+// Building an extension: the esbuild settings a Ham2K bundle needs, and the
+// plugin that takes the host up on the libraries it carries (HALO-442,
+// docs/extensions/development.md).
+//
+// Standalone in the same way h2kext.mjs is, and for the same reason — that
+// module is its only import, because its whole purpose is to work for someone
+// with none of this repo. esbuild it does NOT import: the caller passes their
+// own `build` in, so an author's toolchain and this preset cannot end up
+// running two copies of it.
+//
+// Ships beside the packer, in `@ham2k/extension-tools`, because both read the
+// FORMAT — the API version, the manifest's entry names, the list of libraries
+// the host carries. Neither depends on the SDK an extension imports, so the
+// runtime package stays free of any build-time surface.
+//
+// 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 { 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'
+
+export class BuildError extends Error {}
+
+/// Rewrites imports of the libraries the host carries into lookups on the
+/// kernel's single instance, so a bundle need not ship its own copy.
+///
+/// Only what the manifest DECLARES is rewritten. Declaring is what lets the
+/// host check, before it loads anything, that the version it holds is one the
+/// bundle can work with — an undeclared lookup is a bundle that loads happily
+/// and then dies at the first call into a library that turned out to be a
+/// different major, in someone else's app, far from the cause.
+///
+/// So using an offered library without declaring it FAILS the build rather
+/// than quietly inlining a private copy. Inlining is a legitimate choice — it
+/// is how you use a version the host does not carry — and [inline] is how to
+/// make it, but it is a choice worth stating, because the silent version costs
+/// roughly thirty times the bundle size and nothing anywhere says so.
+export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_VERSION, inline = [] } = {}) {
+  const offered = sharedModulesFor(api)
+  const declared = Object.keys(sharedDependencies)
+
+  // Refused rather than ignored. Externalizing a name the host has no instance
+  // of emits `sharedModules["lodash"]`, which is `undefined` at the first call
+  // — a build that succeeded and a bundle that cannot work.
+  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.')
+  }
+
+  // The two say opposite things about the same package, so neither can be
+  // honoured silently: whichever won, the other statement would be a lie.
+  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.")
+  }
+
+  const undeclared = offered.filter((pkg) => !declared.includes(pkg) && !inline.includes(pkg))
+
+  return {
+    name: 'ham2k-shared-modules',
+    setup(build) {
+      if (declared.length) {
+        build.onResolve({ filter: matcherFor(declared) }, (args) => ({
+          path: args.path,
+          namespace: 'ham2k-shared-module',
+        }))
+      }
+
+      // A separate resolver rather than one branch inside the first: esbuild
+      // consults filters in order, and a plugin that resolved a package only
+      // to return null would hand it back to the very resolution this exists
+      // to intercept.
+      if (undeclared.length) {
+        build.onResolve({ filter: matcherFor(undeclared) }, (args) => ({
+          // The fix goes in `text`, not in a `notes` entry: a note reaches
+          // 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)}: "^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) => ({
+        contents: `module.exports = globalThis.__polo.sharedModules[${JSON.stringify(args.path)}];`,
+        loader: 'js',
+      }))
+    },
+  }
+}
+
+/// An esbuild filter matching exactly [packages] and nothing else. Package
+/// 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('|')
+  return new RegExp(`^(${alternatives})$`)
+}
+
+/// Where liquidjs's BROWSER build lives, or null if liquidjs is not installed.
+///
+/// Every author who inlines liquidjs hits this: its `main`/`module` are the
+/// NODE builds, which import fs, path and stream, and `platform: 'neutral'`
+/// ignores the `browser` field that would have picked the right one. Without
+/// the alias the build fails on unresolvable node built-ins before tree-shaking
+/// gets a chance to drop the half that wanted them (HALO-443).
+///
+/// Resolved from the CALLER's directory, not this file's — the point is to find
+/// the author's copy.
+function liquidBrowserBuild(fromDir) {
+  try {
+    // `resolve` because createRequire rejects a relative path outright, and
+    // `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')
+  } 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
+    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 } = {}) {
+  const liquid = liquidBrowserBuild(dir)
+  return {
+    entryPoints: [entry],
+    ...(outfile ? { outfile } : { write: false }),
+    bundle: true,
+    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 ?? []),
+    ],
+  }
+}
+
+/// Builds one extension directory into something `h2kext-pack` can package:
+/// a `manifest.json` and an `index.js`, side by side.
+///
+///   import { build } from 'esbuild'
+///   import { buildExtension } from '@ham2k/extension-tools'
+///   await buildExtension(build, { dir: import.meta.dirname })
+///
+/// [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')
+
+  let manifest
+  try {
+    manifest = JSON.parse(await readFile(join(dir, MANIFEST_ENTRY), 'utf8'))
+  } catch (e) {
+    throw new BuildError(`could not read ${join(dir, MANIFEST_ENTRY)}: ${e.message}`)
+  }
+
+  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,
+  }))
+
+  // 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
+  // declared dependency list that no longer describes the code.
+  await copyFile(join(dir, MANIFEST_ENTRY), join(out, MANIFEST_ENTRY))
+
+  return { outDir: out, manifest }
+}

package/h2kext-pack.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MPL-2.0
+//
+// Packages an extension into a `.h2kext` a user can install
+// (HALO-422, docs/extensions/distribution.md).
+//
+//   node tools/h2kext-pack.mjs <directory> [-o out.h2kext]
+//
+// 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'
+
+const args = process.argv.slice(2)
+
+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]
+
+The directory must contain:
+  manifest.json   key, name, version, description, category, api (${H2KEXT_API_VERSION})
+  index.js        your extension, built
+  assets/         optional
+
+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.
+
+  --force-name    waive the naming convention (Ham2K's own builds, which
+                  ship bare keys and the reserved '${RESERVED_PREFIX}-' prefix)
+
+Defaults to <key>-<version>.h2kext in the working directory.`)
+  process.exit(args.length === 0 ? 1 : 0)
+}
+
+// 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')
+let dir
+let outPath
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '-o') {
+    outPath = args[++i]
+  } else if (!args[i].startsWith('-') && dir === undefined) {
+    dir = args[i]
+  }
+}
+
+if (!dir) {
+  console.error('h2kext-pack: name the directory to package')
+  process.exit(1)
+}
+
+try {
+  const result = await pack(dir, { outPath, forceName })
+  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'}`)
+  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(', ')}`)
+  }
+} catch (e) {
+  if (e instanceof PackError) {
+    console.error(`h2kext-pack: ${dir} is not ready to package:\n${e.message}`)
+    process.exit(1)
+  }
+  throw e
+}

package/h2kext.mjs

@@ -0,0 +1,311 @@
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MPL-2.0
+//
+// The `.h2kext` bundle format: what one contains, what makes one valid, and how
+// to write it (HALO-422, docs/extensions/distribution.md).
+//
+// Deliberately standalone. It imports nothing from this repo — not the bundle
+// list, not the esbuild options, not the SDK — because its whole purpose is to
+// work for someone who has none of that. Its only dependency is a zip writer.
+// Lifting this file and its CLI into a published npm package should be a
+// packaging change, not a rewrite.
+//
+// It PACKAGES; it does not compile. The input is a directory that already
+// holds a built `index.js` and a `manifest.json`. How that JS got built is the
+// author's business — which is exactly why the checks below matter, since the
+// 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'
+
+/// 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
+
+/// `<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.
+export const KEY_PATTERN = /^[a-z0-9]+-[a-z0-9-]*[a-z0-9]$/
+
+/// The prefix reserved for Ham2K's own extensions. Refused to a distributed
+/// 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'
+
+/// Whether [prefix] is a real amateur callsign — the namespace every author of
+/// this software already has, globally unique, and free.
+export function isCallsignPrefix(prefix) {
+  const parsed = parseCallsign(prefix.toUpperCase())
+  return !!parsed.baseCall && parsed.baseCall === prefix.toUpperCase()
+}
+
+/// The shape a key must have whatever else is waived: lowercase, letters
+/// digits and hyphens. Not a naming convention — the key namespaces KV
+/// storage, scopes secrets, and identifies hooks, so anything outside this
+/// breaks the runtime rather than merely looking wrong.
+///
+/// A leading DIGIT is legitimate and must stay allowed: plenty of callsigns
+/// begin with one (2E0ABC, 9A1AA, 4X4XYZ), and the convention below builds a
+/// key out of exactly that.
+export const SAFE_KEY_PATTERN = /^[a-z0-9][a-z0-9-]*$/
+
+/// Why [key] is not a usable extension key, or null if it is.
+///
+/// [forceName] waives the naming CONVENTION — the callsign prefix and the
+/// reserved `ham2k-` — for Ham2K's own packaging, which builds the extensions
+/// that ship inside the app under bare keys (`pota`, `sota`) and the reserved
+/// prefix. It does not waive [SAFE_KEY_PATTERN], which is not a convention.
+///
+/// A guardrail, not a gate: a standalone tool cannot enforce who runs it. The
+/// 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)) {
+    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('-'))
+  if (prefix === RESERVED_PREFIX) {
+    return `key '${key}' uses the '${RESERVED_PREFIX}-' prefix, which is reserved for Ham2K's own extensions`
+  }
+  if (!isCallsignPrefix(prefix)) {
+    return `key '${key}' must start with your callsign — '${prefix}' is not one (e.g. ki2d-my-clock)`
+  }
+  return null
+}
+
+/// 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/'
+
+/// 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`.
+///
+/// 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
+/// the host checks it at load: a list of names is stable across releases,
+/// a list of versions would be a lie the moment either side shipped.
+///
+/// Deliberately duplicated from build-config.mjs's `sharedPackages` rather than
+/// imported — this module has to work with none of this repo present. A test
+/// in the repo asserts the two agree, which is the only place that check can
+/// 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',
+  ],
+}
+
+/// What the host offers a bundle declaring [api].
+export function sharedModulesFor(api) {
+  return SHARED_MODULES_BY_API[api] ?? SHARED_MODULES_BY_API[H2KEXT_API_VERSION]
+}
+
+export class PackError extends Error {}
+
+/// 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 } = {}) {
+  const problems = []
+  const say = (m) => problems.push(`${source}: ${m}`)
+
+  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() === '') {
+      say(`missing required field '${field}'`)
+    }
+  }
+
+  if (manifest.key !== undefined) {
+    const problem = keyProblem(manifest.key, { forceName })
+    if (problem) say(problem)
+  }
+
+  if (manifest.api === undefined) {
+    say(`missing 'api' — declare the extension API this was built against (currently ${H2KEXT_API_VERSION})`)
+  } else if (!Number.isInteger(manifest.api)) {
+    say(`'api' must be an integer, not ${JSON.stringify(manifest.api)}`)
+  } else if (manifest.api > H2KEXT_API_VERSION) {
+    say(`'api' is ${manifest.api}, but this packer only knows ${H2KEXT_API_VERSION}`)
+  }
+
+  // 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() === '') {
+    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)) {
+      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() === '') {
+          say(`'sharedDependencies' entry '${pkg}' needs a version range, e.g. "^1.0.0"`)
+        }
+      }
+    }
+  }
+
+  // `experiments` gates availability against the APP's experiment catalog. A
+  // key the host does not define hides the extension forever, with nothing in
+  // the UI to explain it, so a distributed bundle must not carry one.
+  if (manifest.experiments !== undefined) {
+    say("'experiments' gates on the app's own experiment catalog and would hide this extension permanently — remove it")
+  }
+
+  return problems
+}
+
+/// Every library a bundle takes from the host rather than carrying its own
+/// copy — the `globalThis.__polo.sharedModules[...]` lookups its build emitted.
+///
+/// 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
+/// whatever version its build shipped with and makes no promise, so an
+/// undeclared lookup is a bundle the app cannot version-check before loading.
+/// It loads happily and then dies at the first call into a library that turned
+/// out to be absent or a different major — far from the cause, and in someone
+/// else's app.
+export function findSharedModuleReferences(source) {
+  const hits = []
+  const pattern = /__polo\s*\.\s*sharedModules\s*\[\s*["']([^"']+)["']\s*\]/g
+  for (const match of source.matchAll(pattern)) hits.push(match[1])
+  return [...new Set(hits)]
+}
+
+/// Reads a bundle directory and returns `{manifest, files}` ready to write, or
+/// throws a [PackError] naming everything wrong with it.
+export async function readBundleDirectory(dir, { forceName = false } = {}) {
+  let manifestRaw
+  try {
+    manifestRaw = await readFile(join(dir, MANIFEST_ENTRY), 'utf8')
+  } catch {
+    throw new PackError(`no ${MANIFEST_ENTRY} in ${dir}`)
+  }
+
+  let manifest
+  try {
+    manifest = JSON.parse(manifestRaw)
+  } catch (e) {
+    throw new PackError(`${MANIFEST_ENTRY} is not valid JSON: ${e.message}`)
+  }
+
+  const problems = validateManifest(manifest, { forceName })
+
+  let bundleSource
+  try {
+    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`)
+
+  // 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
+  // allowed is using one silently: the host carries whatever version that
+  // build shipped with, so a bundle has to say what it can work with, and the
+  // host checks it before loading. Undeclared, it loads happily and then dies
+  // at the first call into a library that turned out to be a different major.
+  const declaredShared = manifest?.sharedDependencies ?? {}
+  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(', ')}). ` +
+        `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.')
+  }
+
+  if (problems.length) throw new PackError(problems.join('\n'))
+
+  const files = [
+    { entry: MANIFEST_ENTRY, path: join(dir, MANIFEST_ENTRY) },
+    { entry: BUNDLE_ENTRY, path: join(dir, BUNDLE_ENTRY) },
+    ...(await collectAssets(dir)),
+  ]
+  return { manifest, files }
+}
+
+/// Everything under `assets/`, as forward-slashed entry names. Zip entry names
+/// are `/`-separated by specification, so a Windows author must not produce a
+/// bundle whose paths only their own machine can read.
+async function collectAssets(dir) {
+  const root = join(dir, ASSETS_PREFIX.slice(0, -1))
+  try {
+    if (!(await stat(root)).isDirectory()) return []
+  } catch (e) {
+    // 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 []
+    throw new PackError(`could not read ${root}: ${e.message}`)
+  }
+
+  const found = []
+  const walk = async (current) => {
+    for (const item of await readdir(current, { withFileTypes: true })) {
+      const full = join(current, item.name)
+      if (item.isDirectory()) await walk(full)
+      else if (item.isFile()) {
+        found.push({ entry: ASSETS_PREFIX + relative(root, full).split(sep).join(posix.sep), path: full })
+      }
+    }
+  }
+  await walk(root)
+  return found.sort((a, b) => a.entry.localeCompare(b.entry))
+}
+
+/// Writes the `.h2kext` at [outPath]. Resolves once the file is closed —
+/// yazl's `end()` only starts the write, and a caller that reported success
+/// before then would be describing a file that is still being produced.
+export function writeBundle(files, outPath) {
+  return new Promise((resolve, reject) => {
+    const zip = new yazl.ZipFile()
+    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)
+    zip.end()
+  })
+}
+
+/// Validate a directory and write its `.h2kext`. Returns `{manifest, outPath}`.
+export async function pack(dir, { outPath, forceName = false } = {}) {
+  const { manifest, files } = await readBundleDirectory(dir, { forceName })
+  const target = outPath ?? join(process.cwd(), `${manifest.key}-${manifest.version}.h2kext`)
+  await writeBundle(files, target)
+  return { manifest, outPath: target, files }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ham2k/extension-tools",
+  "version": "0.1.0",
+  "description": "Build and package extensions for the Ham2K Logger",
+  "keywords": ["ham2k", "ham radio", "amateur radio", "extension", "esbuild", "h2kext"],
+  "license": "MPL-2.0",
+  "author": "Sebastian Delmont <sd@ham2k.com>",
+  "homepage": "https://ham2k.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ham2k/halo.git",
+    "directory": "extensions/tools"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./h2kext-build.mjs",
+    "./format": "./h2kext.mjs"
+  },
+  "bin": {
+    "h2kext-pack": "./h2kext-pack.mjs"
+  },
+  "files": [
+    "h2kext.mjs",
+    "h2kext-build.mjs",
+    "h2kext-pack.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@ham2k/lib-callsigns": "^1.0.2",
+    "yazl": "^3.3.1"
+  },
+  "peerDependencies": {
+    "esbuild": ">=0.20"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    }
+  }
+}