@ham2k/extension-tools 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sebastian Delmont <sd@ham2k.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,6 +6,27 @@ Build and package extensions for the [Ham2K Logger](https://ham2k.com).
 npm install --save-dev @ham2k/extension-tools esbuild
 ```
 
+## Starting one
+
+```sh
+npx h2kext-init w7abc-notes
+```
+
+Writes a whole small extension — manifest, a panel that says hello, the build
+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 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.
+
+The `AGENTS.md` it writes points at `@ham2k/extension-sdk`'s own — the hook
+reference, the sandbox's limits, and what to read for what. That matters most
+if something other than you is writing the code: an agent reads a project's
+`AGENTS.md` unprompted, and otherwise never learns the reference is sitting in
+`node_modules`.
+
 ## Building
 
 ```js
@@ -44,6 +65,39 @@ 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
+## Publishing to the catalog
+
+```sh
+export H2K_CATALOG_TOKEN=h2kc_…
+npx h2kext-publish build --notes "What changed"
+```
+
+Uploads a bundle to the [Ham2K extension catalog](https://catalog.ham2k.net),
+where the app finds it. Sign in there and make a token under
+[/publish](https://catalog.ham2k.net/publish); the command reads it from
+`H2K_CATALOG_TOKEN` and from nowhere else — there is no flag for it, because a
+flag lands in your shell history — and stores it nowhere. Publishing needs a
+grant for your callsign prefix, which the same page is where you ask for.
+
+A directory is packaged first, exactly as `h2kext-pack` would; a `.h2kext`
+you already made is sent as it is. A bundle must be 16 MiB or smaller: the
+app never downloads more than that, the catalog refuses more than that, and
+the command refuses it before sending a byte. A version's bytes are frozen
+the first time a reviewer approves them: from then on the same version with
+different bytes is refused, so a fix is a new version.
+
+Release notes go up in a second request, once the upload is accepted. If
+that request is refused, the version is still published — the command says
+so and exits 1, and you can write the notes on the site, where they can be
+edited at any time.
+
+The result line reads `published w7abc-notes 1.2.3 → prod (pending review)`.
+"Pending review" means a Ham2K reviewer has not looked yet — the version is
+stored, but nobody can install it until they approve it, and your dashboard on
+the site shows the outcome and any note. Every refusal prints the catalog's
+reason and exits 1; nothing is retried.
 
-MPL-2.0
+A channel says how finished a release is — `stable`, `unstable`, `bleeding` —
+not which app edition is asking. They cascade upward, so `stable` reaches
+everyone and `bleeding` reaches only somebody who asked for it. `--channel` is
+optional and defaults to `stable`.

package/h2kext-build.mjs

@@ -1,5 +1,5 @@
 // Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
-// SPDX-License-Identifier: MPL-2.0
+// SPDX-License-Identifier: MIT
 //
 // 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,
@@ -19,12 +19,29 @@
 // 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 { 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.
+///
+/// Here rather than in either of them because two copies of a file whose whole
+/// job is to be correct on someone else's machine would drift, and neither
+/// 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'
+
+await buildExtension(build, { dir: import.meta.dirname })
+
+console.log('built build/index.js')
+`
+
 export class BuildError extends Error {}
 
 /// Rewrites imports of the libraries the host carries into lookups on the
@@ -41,6 +58,47 @@ export class BuildError extends Error {}
 /// 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.
+/// The version of a shared package as installed beside the extension being
+/// built, for the range the "you must declare this" error suggests.
+///
+/// Suggesting a floor is not cosmetic. The host admits a bundle by comparing
+/// its declared range against the package version the host holds — it cannot
+/// see which SYMBOLS that version has. A package that grew an export (the
+/// Cabrillo writer arrived in `@ham2k/lib-qson-cabrillo` 1.2.0) therefore
+/// satisfies a `^1.0.0` declaration on a host too old to have the function,
+/// and the extension installs, loads, and throws the first time an operator
+/// asks for that feature. Suggesting the version the author is actually
+/// building against makes the honest declaration the easy one.
+///
+/// Null when the package is not resolvable from there, which leaves the
+/// caller its own fallback — a missing suggestion is worth far less than a
+/// failed build.
+function installedVersionOf(pkg, fromDir) {
+  try {
+    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
+    // outright, and asking for it is how this silently answers 1.0.0 for
+    // every package.
+    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'))
+        if (manifest.name === pkg) return manifest.version ?? null
+      } catch {
+        // Not this directory's package.json, or not readable — keep climbing.
+      }
+      const parent = dirname(dir)
+      if (parent === dir) break
+      dir = parent
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
 export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_VERSION, inline = [] } = {}) {
   const offered = sharedModulesFor(api)
   const declared = Object.keys(sharedDependencies)
@@ -89,7 +147,8 @@ export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_
           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)}] ` +
+              `(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.',
           }],
         }))

package/h2kext-init.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+//
+// Scaffolds an extension project (HALO-452, docs/extensions/distribution.md).
+//
+//   npx h2kext-init <yourcallsign>-<name>
+//
+// Writes the smallest whole extension — a panel that says hello — plus the
+// `AGENTS.md` that points whatever is writing the code at the reference inside
+// `@ham2k/extension-sdk`. That one line is the whole reason this command
+// exists: an agent reads a project's AGENTS.md unprompted, and otherwise never
+// learns the docs are sitting in node_modules and guesses the manifest instead.
+//
+// It takes the key rather than defaulting one. A placeholder like
+// `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 { 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')) {
+  console.log(`Scaffold a Ham2K Logger extension.
+
+  h2kext-init <key> [--dir <path>] [--name "<display name>"]
+
+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.`)
+  process.exit(args.length === 0 ? 1 : 0)
+}
+
+let key
+let dir = process.cwd()
+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]
+}
+
+const problem = keyProblem(key)
+if (problem) {
+  console.error(`h2kext-init: ${problem}`)
+  process.exit(1)
+}
+
+if (dir === undefined) {
+  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 here = dirname(fileURLToPath(import.meta.url))
+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
+/// tools-only patch would scaffold `^0.1.1` of an SDK that has no such
+/// release, and `npm install` — the very next line this command prints —
+/// fails with ETARGET. The other direction is worse, because it is quiet: an
+/// SDK a minor ahead, and the author installs the old one while reading the
+/// new one's docs.
+///
+/// Resolved from what is actually installed where the project is being made,
+/// which is right whenever the documented `npm i -D @ham2k/extension-tools`
+/// route pulled the SDK in too. With nothing installed there is nothing to
+/// read, and `latest` is the honest answer — the author's `npm install` then
+/// fetches whatever the current SDK is, which is what a new project wants.
+function sdkRange(projectDir) {
+  // READ the file; do not `require` it. A package's own package.json is not a
+  // subpath its `exports` map declares, and Node refuses an undeclared subpath
+  // — `createRequire(...)('@ham2k/extension-sdk/package.json')` throws
+  // ERR_PACKAGE_PATH_NOT_EXPORTED for a package sitting right there in
+  // node_modules, so every scaffold would silently fall through to `latest`.
+  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'))
+        if (version) return `^${version}`
+      } catch {
+        // Not here; walk up to the next node_modules.
+      }
+      if (dirname(dir) === dir) break
+    }
+  }
+  return 'latest'
+}
+
+/// 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',
+  private: true,
+  type: 'module',
+  scripts: {
+    build: 'node build.mjs',
+    pack: 'h2kext-pack build',
+    typecheck: 'tsc --noEmit',
+  },
+  dependencies: {
+    '@ham2k/extension-sdk': sdkRange(dir),
+  },
+  devDependencies: {
+    '@ham2k/extension-tools': `^${toolsVersion}`,
+    esbuild: '^0.25.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.
+//
+// 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 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' }]
+  },
+
+  /// What the pane shows. A panel returns CONTENT, never widgets — which is
+  /// what keeps extensions out of the app's UI toolkit.
+  ///
+  /// The method is \`render\`, not \`renderPanel\`: the host routes to the hook by
+  /// 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!' }
+  },
+}
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    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`,
+
+  // 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}
+
+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:
+
+@node_modules/@ham2k/extension-sdk/AGENTS.md
+`,
+
+  '.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(
+  (text) => {
+    try {
+      return JSON.parse(text)
+    } catch (e) {
+      // Read BEFORE anything is written: parsed after the write loop, this
+      // threw a raw SyntaxError over six files already on disk, and the retry
+      // then collided with them.
+      console.error(`h2kext-init: ${packagePath} is not readable JSON (${e.message}) — nothing written`)
+      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)) {
+  console.error(`h2kext-init: ${packagePath} is not a package description — nothing written`)
+  process.exit(1)
+}
+
+// `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 (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.')
+  process.exit(1)
+}
+
+for (const [path, content] of Object.entries(files)) {
+  await mkdir(dirname(join(dir, path)), { recursive: true })
+  await writeFile(join(dir, path), content)
+}
+
+// `package.json` is the one file that gets merged rather than refused, because
+// the obvious way to reach this command already made one:
+// `npm i -D @ham2k/extension-tools && npx h2kext-init …`. Refusing there would
+// turn the documented path into the broken one.
+//
+// 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
+  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  ')}
+
+Next:
+  npm install
+  npm run build && npm run pack`)

package/h2kext-pack.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
-// SPDX-License-Identifier: MPL-2.0
+// SPDX-License-Identifier: MIT
 //
 // Packages an extension into a `.h2kext` a user can install
 // (HALO-422, docs/extensions/distribution.md).

package/h2kext-publish.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+// Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
+// SPDX-License-Identifier: MIT
+//
+// Publishes a `.h2kext` to the extension catalog — catalog.ham2k.net, whose
+// SPEC.md lives in the ham2k/catalog.ham2k.net repo; the § references below
+// are to it (§5.1 is the publish request, §15 this command).
+//
+//   H2K_CATALOG_TOKEN=h2kc_… h2kext-publish <bundle.h2kext | build dir>
+//                  [--channel <stable|unstable|bleeding>] [--notes "…"] [--catalog <url>]
+//                  [--force-name]
+//
+// One POST of the raw bytes, then one PUT for the notes; no retries: a refusal
+// is the catalog's verdict on these bytes, and sending them again can only
+// repeat it. The token is read from the environment for those requests and
+// 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 { 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'
+/// 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']
+
+/// 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'
+
+/// The catalog refuses a larger upload before reading it (§5.1 step 2),
+/// because the app never downloads more than this (`kMaxDownloadBytes`).
+/// Checked here so the refusal costs nothing instead of a wasted upload.
+export const MAX_BUNDLE_BYTES = 16 * 1024 * 1024
+
+/// Exit codes. Usage problems — including a missing token — are 2 so a script
+/// can tell "you called this wrong" from "the catalog said no" (1).
+export const EXIT_REFUSED = 1
+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' }
+
+export class PublishError extends Error {
+  constructor(message, exitCode = EXIT_REFUSED) {
+    super(message)
+    this.exitCode = exitCode
+  }
+}
+
+const USAGE = `Publish an extension bundle to the Ham2K extension catalog.
+
+  ${TOKEN_ENV}=h2kc_… h2kext-publish <bundle.h2kext | build dir> [--channel <stable|unstable|bleeding>]
+                 [--notes "<release notes>"] [--catalog <url>] [--force-name]
+
+A directory is packaged first, exactly as h2kext-pack would. A bundle over
+16 MiB is refused here, as the catalog would refuse it.
+
+The token comes from the ${TOKEN_ENV} environment variable and only from
+there — a flag would land in shell history and \`ps\`. Get one at
+${DEFAULT_CATALOG}/publish. Nothing here stores it.
+
+  --channel      how finished this release is (default ${DEFAULT_CHANNEL});
+                 stable is visible to everyone, bleeding only to somebody
+                 who asked for it
+  --notes        release notes for this version, markdown; sent in a second
+                 request once the upload is accepted
+  --catalog      defaults to ${DEFAULT_CATALOG}
+  --force-name   waive the key naming convention when packaging a directory
+                 (Ham2K's own builds; the catalog checks it again regardless)
+
+Exits 0 once the catalog holds the submission and its notes, 1 when it refuses
+or cannot be reached, 2 for a usage problem.`
+
+/// The manifest inside a bundle's bytes.
+///
+/// A reader for one entry of a zip whose writer is ours — h2kext.mjs via yazl:
+/// stored or deflated, no zip64, no encryption — which is why this is forty
+/// lines and not a dependency. Sizes come from the central directory, never
+/// the local header: yazl streams, so the local header's sizes are zero and
+/// the truth sits in the data descriptor after the entry.
+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')
+  }
+  // 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.
+  let eocd = -1
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 0xffff); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) {
+      eocd = i
+      break
+    }
+  }
+  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')
+    }
+    const method = buf.readUInt16LE(offset + 10)
+    const compressedSize = buf.readUInt32LE(offset + 20)
+    const nameLength = buf.readUInt16LE(offset + 28)
+    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)
+    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,
+      // not as a RangeError out of Buffer.
+      const damaged = `not a .h2kext: ${MANIFEST_ENTRY} entry is truncated or damaged`
+      if (localOffset + 30 > buf.length || buf.readUInt32LE(localOffset) !== 0x04034b50) throw new PublishError(damaged)
+      const start = localOffset + 30 + buf.readUInt16LE(localOffset + 26) + buf.readUInt16LE(localOffset + 28)
+      if (start + compressedSize > buf.length) throw new PublishError(damaged)
+      const data = buf.subarray(start, start + compressedSize)
+      let raw
+      if (method === 0) raw = data
+      else if (method === 8) {
+        try {
+          raw = inflateRawSync(data)
+        } catch (e) {
+          throw new PublishError(`${damaged}: ${e.message}`)
+        }
+      } else throw new PublishError(`not a .h2kext: ${MANIFEST_ENTRY} uses zip compression method ${method}`)
+      try {
+        return JSON.parse(raw.toString('utf8'))
+      } catch (e) {
+        throw new PublishError(`${MANIFEST_ENTRY} inside the bundle is not valid JSON: ${e.message}`)
+      }
+    }
+    offset += 46 + nameLength + extraLength + commentLength
+  }
+  throw new PublishError(`not a .h2kext: no ${MANIFEST_ENTRY} inside`)
+}
+
+/// The bundle's bytes: the file as given, or a directory packaged the way
+/// h2kext-pack packages it, into a temporary file that is gone before this
+/// returns.
+async function loadBundle(source, { forceName }) {
+  let info
+  try {
+    info = await stat(source)
+  } catch (e) {
+    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-'))
+  try {
+    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}`)
+    throw e
+  } finally {
+    await rm(tmp, { recursive: true, force: true })
+  }
+}
+
+/// One request to the catalog, its answer parsed as JSON when it is JSON. A
+/// network failure is a [PublishError] naming the catalog, not a stack trace.
+async function call(fetch, catalog, path, init) {
+  let response
+  try {
+    response = await fetch(`${catalog}${path}`, init)
+  } catch (e) {
+    throw new PublishError(`could not reach ${catalog}: ${e.cause?.message ?? e.message}`)
+  }
+  const text = await response.text()
+  let body
+  try {
+    body = JSON.parse(text)
+  } catch {
+    body = undefined
+  }
+  return { response, text, body }
+}
+
+/// 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'
+}
+
+/// Uploads [bytes] as the raw request body (§5.1: no multipart) and
+/// returns the catalog's 201 body. Any other answer is a [PublishError].
+///
+/// `Content-Length` is not set here: fetch derives it from a Buffer body, and a
+/// header set by hand that disagreed with the body would be the request's
+/// 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' },
+    body: bytes,
+  })
+  if (answer.response.status === 201 && answer.body) return answer.body
+  throw new PublishError(`${catalog} refused ${manifest.key} ${manifest.version} with HTTP ${answer.response.status}: ${refusal(answer)}`)
+}
+
+/// Sets a submission's release notes (§5.1, the second call). Any answer
+/// 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' },
+    body: JSON.stringify({ releaseNotes: notes }),
+  })
+  if (answer.response.ok) return
+  throw new PublishError(`${catalog} refused the release notes for submission ${submissionId} with HTTP ${answer.response.status}: ${refusal(answer)}`)
+}
+
+/// 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')) {
+    stdout.write(`${USAGE}\n`)
+    return argv.length === 0 ? EXIT_USAGE : 0
+  }
+
+  const token = env[TOKEN_ENV]
+
+  // 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 say = (s) => stdout.write(`${redact(s)}\n`)
+  const complain = (s) => stderr.write(`h2kext-publish: ${redact(s)}\n`)
+
+  try {
+    // Walked by index, like h2kext-pack: `indexOf` finds the FIRST occurrence,
+    // and a value can repeat an option's name. Unlike h2kext-pack, an option
+    // this does not know is a refusal: `--token h2kc_…` from an older script
+    // would otherwise be ignored and the token sent nowhere, after sitting in
+    // the shell history — the reason the flag does not exist.
+    let source
+    let channel
+    let notes
+    let catalog = DEFAULT_CATALOG
+    let forceName = false
+    // An option at the end of the line has no value, and `--notes` with none
+    // would silently publish without notes — the one option whose absence
+    // looks like success.
+    const valueOf = (i) => {
+      if (i + 1 >= argv.length) throw new PublishError(`${argv[i]} needs a value`, EXIT_USAGE)
+      return argv[i + 1]
+    }
+    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)
+      else if (source === undefined) source = arg
+    }
+
+    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)
+    }
+    if (!token) {
+      throw new PublishError(`no token — set ${TOKEN_ENV} (get one at ${catalog}/publish)`, EXIT_USAGE)
+    }
+    try {
+      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`)
+    }
+    const manifest = readManifestFromBundle(bytes)
+    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}`)
+
+    const result = await publish({ bytes, manifest, channel, catalog, token }, { fetch })
+    say(`published ${result.key} ${result.version} → ${result.channel} (${STATUS_WORDS[result.status] ?? result.status})`)
+    if (result.url) say(result.url)
+
+    if (notes !== undefined) {
+      try {
+        if (result.submissionId === undefined || result.submissionId === null) {
+          throw new PublishError(`the catalog's answer named no submissionId to attach them to`)
+        }
+        await setReleaseNotes({ submissionId: result.submissionId, notes, catalog, token }, { fetch })
+      } catch (e) {
+        if (!(e instanceof PublishError)) throw e
+        // The version is published and stays published: the notes are the
+        // site's to edit at any time, so nothing is rolled back — but the
+        // exit code says the command did not do all it was asked.
+        complain(`warning: ${result.key} ${result.version} is published, but its release notes were not set — ${e.message}. Edit them on the site instead.`)
+        return EXIT_REFUSED
+      }
+    }
+    return 0
+  } catch (e) {
+    if (e instanceof PublishError) {
+      complain(e.message)
+      return e.exitCode
+    }
+    // Anything else is a bug here, not a refusal — but it still goes through
+    // the redactor rather than to an uncaught-exception stack trace.
+    complain(e.stack ?? e)
+    return EXIT_REFUSED
+  }
+}
+
+// Run only as the command. `realpathSync` because npm installs a bin as a
+// symlink while `import.meta.url` resolves to the real file — compared raw,
+// `npx h2kext-publish` would import this module and then do nothing.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  process.exit(await main(process.argv.slice(2)))
+}

package/h2kext.mjs

@@ -1,5 +1,5 @@
 // Copyright ©️ 2026 Sebastian Delmont <sd@ham2k.com>
-// SPDX-License-Identifier: MPL-2.0
+// SPDX-License-Identifier: MIT
 //
 // The `.h2kext` bundle format: what one contains, what makes one valid, and how
 // to write it (HALO-422, docs/extensions/distribution.md).
@@ -118,6 +118,34 @@ export const SHARED_MODULES_BY_API = {
   ],
 }
 
+/// 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
+/// builds. Importing anything from `@ham2k/extension-sdk` pulls them in —
+/// `dxcc`, `i18n` and `templates` are on the barrel — which makes declaring
+/// them a starting condition rather than a choice the author makes later.
+///
+/// Ranges at the MAJOR, which is the grain the check is really about and the
+/// one the docs model. They are a starting point the author owns from the
+/// moment it is written: narrowing one to the version actually tested against
+/// is a normal thing to do before publishing.
+///
+/// Versions here and nowhere else in this file. `SHARED_MODULES_BY_API` is the
+/// host's OFFER, which must stay version-free; this is one author's opening
+/// DECLARATION, which the format requires to carry ranges. A test in the repo
+/// asserts every range here is satisfied by the versions this build's host
+/// 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',
+}
+
 /// 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]
@@ -125,6 +153,107 @@ export function sharedModulesFor(api) {
 
 export class PackError extends Error {}
 
+/// The vocabulary of the manifest's `relevance` — what the matcher compares
+/// 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_ITU_REGIONS = [1, 2, 3]
+
+/// What `relevance.interests` may name: a mode, a band group, or a style of
+/// operating. Closed, and checked, because an interest nothing else spells
+/// the same way matches nobody while looking like it works — `CW`, `cw` and
+/// `morse` would be three interests, and only one of them the one the app
+/// 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',
+]
+
+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.
+///
+/// The shape rules are the ones that matter: the matcher reads a key it
+/// cannot parse as "does not gate", so a misspelt key or a string where a
+/// list should be would quietly make a Chilean extension relevant to the
+/// whole world. The vocabulary rules catch the opposite mistake — a value that
+/// can never match anyone, which is a bundle nobody is shown.
+///
+/// Shared with build-config.mjs's manifest checks, which import it: the
+/// 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(' / ')}`]
+  }
+  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`)
+    }
+  }
+  for (const key of RELEVANCE_KEYS) {
+    const values = relevance[key]
+    if (values === undefined) continue
+    if (!Array.isArray(values)) {
+      problems.push(`'relevance.${key}' must be a list`)
+      continue
+    }
+    for (const value of values) {
+      const problem = relevanceValueProblem(key, value)
+      if (problem) problems.push(`'relevance.${key}' has ${JSON.stringify(value)}, which ${problem}`)
+    }
+  }
+  return problems
+}
+
+function relevanceValueProblem(key, value) {
+  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 (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(' ')})`
+  }
+  return GEO_CONTINENTS.includes(value.toUpperCase()) ? null : `is not a continent (${GEO_CONTINENTS.join(' ')})`
+}
+
+/// Why [value] is not a UTC calendar day, or null.
+///
+/// The round trip is the whole check: `Date.UTC` rolls 31 February over into
+/// 3 March rather than refusing it, so a pattern match alone accepts a day
+/// that does not exist and then silently means a different one.
+///
+/// A year under 1000 is refused before that round trip, and the Dart twin
+/// refuses it too. `Date.UTC` reads a year under 100 as 19xx, so `0050-01-01`
+/// 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'
+  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'
+}
+
 /// 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 } = {}) {
@@ -185,6 +314,28 @@ export function validateManifest(manifest, { source = MANIFEST_ENTRY, forceName
     say("'experiments' gates on the app's own experiment catalog and would hide this extension permanently — remove it")
   }
 
+  // The name `relevance` replaced. Nothing reads `geo`, and nothing here
+  // rejects unknown top-level keys, so a manifest still carrying it would
+  // pack, publish and install as WORLDWIDE — the author's audience silently
+  // discarded rather than refused. It is the one stale key certain to
+  // arrive, because it is what every older manifest says.
+  if (manifest.geo !== undefined) {
+    say("'geo' is now 'relevance' — rename it (docs/extensions/distribution.md)")
+  }
+
+  // `enabledByDefault` is the shipping app's answer for its OWN extensions,
+  // which arrive whether the operator wanted them or not. An installed
+  // bundle is one the operator went and got, so the answer is always yes and
+  // a manifest that says otherwise is describing a state it cannot reach.
+  if (manifest.enabledByDefault !== undefined) {
+    say("'enabledByDefault' applies to an app's built-in extensions — an installed one is on because the operator installed it")
+  }
+
+  // `relevance` ranks the bundle, in the catalog and the Extensions panel,
+  // for the operators it was written for. The matcher reads a key it cannot
+  // parse as "does not gate", so a malformed one would ship as worldwide.
+  for (const problem of validateRelevance(manifest.relevance)) say(problem)
+
   return problems
 }
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@ham2k/extension-tools",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Build and package extensions for the Ham2K Logger",
   "keywords": ["ham2k", "ham radio", "amateur radio", "extension", "esbuild", "h2kext"],
-  "license": "MPL-2.0",
+  "license": "MIT",
   "author": "Sebastian Delmont <sd@ham2k.com>",
   "homepage": "https://ham2k.com",
   "repository": {
@@ -17,12 +17,16 @@
     "./format": "./h2kext.mjs"
   },
   "bin": {
-    "h2kext-pack": "./h2kext-pack.mjs"
+    "h2kext-init": "./h2kext-init.mjs",
+    "h2kext-pack": "./h2kext-pack.mjs",
+    "h2kext-publish": "./h2kext-publish.mjs"
   },
   "files": [
     "h2kext.mjs",
     "h2kext-build.mjs",
+    "h2kext-init.mjs",
     "h2kext-pack.mjs",
+    "h2kext-publish.mjs",
     "README.md"
   ],
   "engines": {