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

@@ -65,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
 
-MPL-2.0
+```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.
+
+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,6 +19,7 @@
 // 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'
@@ -57,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)
@@ -105,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

@@ -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
 //
 // Scaffolds an extension project (HALO-452, docs/extensions/distribution.md).
 //

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).
@@ -153,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 } = {}) {
@@ -213,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.2.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": {
@@ -18,13 +18,15 @@
   },
   "bin": {
     "h2kext-init": "./h2kext-init.mjs",
-    "h2kext-pack": "./h2kext-pack.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": {