@ham2k/extension-tools 0.2.0 → 0.4.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

@@ -17,6 +17,12 @@ script, a tsconfig — into the working directory, and refuses rather than
 overwrite anything already there. An existing `package.json` is added to, never
 replaced.
 
+It also writes a `.prettierrc.json` and the `format` / `format:check` scripts,
+and what it scaffolds is already in that style — so `npm run format:check`
+passes on an untouched project, and the code an agent adds to it lands
+formatted the same way. Configure Prettier already, anywhere it looks, and
+yours is left in charge: no config is written, and the command says so.
+
 It takes the key rather than defaulting one: a placeholder like
 `n0call-my-extension` validates, so it would ship, which is the one outcome the
 naming convention exists to stop.
@@ -65,6 +71,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"
+```
 
-MPL-2.0
+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,11 +19,12 @@
 // The repo's own build uses it too, on the same terms, which is what keeps the
 // path a third party takes from being the untested one.
 
-import { copyFile, mkdir, readFile } from 'node:fs/promises'
-import { createRequire } from 'node:module'
-import { dirname, join, resolve } from 'node:path'
+import { readFileSync } from "node:fs"
+import { copyFile, mkdir, readFile } from "node:fs/promises"
+import { createRequire } from "node:module"
+import { dirname, join, resolve } from "node:path"
 
-import { H2KEXT_API_VERSION, MANIFEST_ENTRY, sharedModulesFor } from './h2kext.mjs'
+import { H2KEXT_API_VERSION, MANIFEST_ENTRY, sharedModulesFor } from "./h2kext.mjs"
 
 /// What an extension's own `build.mjs` says, for everything that has to write
 /// one: `h2kext-init`'s scaffold, and the samples the SDK ships.
@@ -33,12 +34,12 @@ import { H2KEXT_API_VERSION, MANIFEST_ENTRY, sharedModulesFor } from './h2kext.m
 /// copy is exercised by this repo's own build — the extensions here are built
 /// through `build-config.mjs`, which takes a different path into the same
 /// preset.
-export const EXAMPLE_BUILD_SCRIPT = `import { build } from 'esbuild'
-import { buildExtension } from '@ham2k/extension-tools'
+export const EXAMPLE_BUILD_SCRIPT = `import { build } from "esbuild"
+import { buildExtension } from "@ham2k/extension-tools"
 
 await buildExtension(build, { dir: import.meta.dirname })
 
-console.log('built build/index.js')
+console.log("built build/index.js")
 `
 
 export class BuildError extends Error {}
@@ -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)
@@ -67,8 +109,9 @@ export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_
   const notOffered = declared.filter((pkg) => !offered.includes(pkg))
   if (notOffered.length) {
     throw new BuildError(
-      `${MANIFEST_ENTRY} declares sharedDependencies the host does not carry (${notOffered.join(', ')}). ` +
-      'Bundle those into your build instead — only what the host offers can be shared.')
+      `${MANIFEST_ENTRY} declares sharedDependencies the host does not carry (${notOffered.join(", ")}). ` +
+        "Bundle those into your build instead — only what the host offers can be shared.",
+    )
   }
 
   // The two say opposite things about the same package, so neither can be
@@ -76,19 +119,19 @@ export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_
   const both = declared.filter((pkg) => inline.includes(pkg))
   if (both.length) {
     throw new BuildError(
-      `${both.join(', ')} appears in both sharedDependencies and inline. ` +
-      "Declare it to use the host's copy, or inline it to ship your own — not both.")
+      `${both.join(", ")} appears in both sharedDependencies and inline. ` + "Declare it to use the host's copy, or inline it to ship your own — not both.",
+    )
   }
 
   const undeclared = offered.filter((pkg) => !declared.includes(pkg) && !inline.includes(pkg))
 
   return {
-    name: 'ham2k-shared-modules',
+    name: "ham2k-shared-modules",
     setup(build) {
       if (declared.length) {
         build.onResolve({ filter: matcherFor(declared) }, (args) => ({
           path: args.path,
-          namespace: 'ham2k-shared-module',
+          namespace: "ham2k-shared-module",
         }))
       }
 
@@ -102,18 +145,22 @@ export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_
           // esbuild's pretty printer and nothing else, so a build script that
           // catches the error — or runs at logLevel 'silent' — shows the
           // author the complaint with the answer stripped off.
-          errors: [{
-            text: `'${args.path}' is carried by the Ham2K extension host, but this bundle does not declare it. ` +
-              `Add it to "sharedDependencies" in ${MANIFEST_ENTRY} with the version range you work with ` +
-              `(e.g. {${JSON.stringify(args.path)}: "^1.0.0"}), or pass inline: [${JSON.stringify(args.path)}] ` +
-              'to ship your own copy — which is how you use a version the host does not carry.',
-          }],
+          errors: [
+            {
+              text:
+                `'${args.path}' is carried by the Ham2K extension host, but this bundle does not declare it. ` +
+                `Add it to "sharedDependencies" in ${MANIFEST_ENTRY} with the version range you work with ` +
+                `(e.g. {${JSON.stringify(args.path)}: "^${installedVersionOf(args.path, args.resolveDir) ?? "1.0.0"}"}), ` +
+                `or pass inline: [${JSON.stringify(args.path)}] ` +
+                "to ship your own copy — which is how you use a version the host does not carry.",
+            },
+          ],
         }))
       }
 
-      build.onLoad({ filter: /.*/, namespace: 'ham2k-shared-module' }, (args) => ({
+      build.onLoad({ filter: /.*/, namespace: "ham2k-shared-module" }, (args) => ({
         contents: `module.exports = globalThis.__polo.sharedModules[${JSON.stringify(args.path)}];`,
-        loader: 'js',
+        loader: "js",
       }))
     },
   }
@@ -123,7 +170,7 @@ export function sharedModulesPlugin({ sharedDependencies = {}, api = H2KEXT_API_
 /// names carry regex metacharacters (`@ham2k/lib-qson-adif` has a slash, and a
 /// dot would be a wildcard), so every one is escaped.
 function matcherFor(packages) {
-  const alternatives = packages.map((pkg) => pkg.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')).join('|')
+  const alternatives = packages.map((pkg) => pkg.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")).join("|")
   return new RegExp(`^(${alternatives})$`)
 }
 
@@ -143,14 +190,14 @@ function liquidBrowserBuild(fromDir) {
     // `dir` is the caller's to pass — a relative one lands in the catch below
     // and loses the alias, which is precisely the failure this function exists
     // to prevent, arriving with nothing to point at the cause.
-    const require = createRequire(resolve(fromDir, 'noop.js'))
-    return join(dirname(require.resolve('liquidjs/package.json')), 'dist/liquid.browser.mjs')
+    const require = createRequire(resolve(fromDir, "noop.js"))
+    return join(dirname(require.resolve("liquidjs/package.json")), "dist/liquid.browser.mjs")
   } catch (e) {
     // Not installed is the normal case for an extension that neither inlines
     // liquidjs nor uses it, and there is nothing to alias. Anything else is a
     // real fault, and swallowing it would hand the author five unresolvable
     // node built-ins instead.
-    if (e.code === 'MODULE_NOT_FOUND') return null
+    if (e.code === "MODULE_NOT_FOUND") return null
     throw e
   }
 }
@@ -167,20 +214,17 @@ export function buildOptionsFor({ entry, outfile, manifest = {}, dir = process.c
     entryPoints: [entry],
     ...(outfile ? { outfile } : { write: false }),
     bundle: true,
-    format: 'iife',
-    platform: 'neutral',
-    mainFields: ['module', 'main'],
-    target: 'es2020',
-    logLevel: 'warning',
+    format: "iife",
+    platform: "neutral",
+    mainFields: ["module", "main"],
+    target: "es2020",
+    logLevel: "warning",
     ...rest,
     alias: {
       ...(liquid ? { liquidjs: liquid } : {}),
       ...alias,
     },
-    plugins: [
-      sharedModulesPlugin({ sharedDependencies: manifest.sharedDependencies, api: manifest.api, inline }),
-      ...(rest.plugins ?? []),
-    ],
+    plugins: [sharedModulesPlugin({ sharedDependencies: manifest.sharedDependencies, api: manifest.api, inline }), ...(rest.plugins ?? [])],
   }
 }
 
@@ -193,12 +237,12 @@ export function buildOptionsFor({ entry, outfile, manifest = {}, dir = process.c
 ///
 /// [esbuild] is the caller's `build` function, passed in rather than imported
 /// so this module needs no copy of its own.
-export async function buildExtension(esbuild, { dir, entry = 'src/index.ts', outDir = 'build', ...rest } = {}) {
-  if (!dir) throw new BuildError('buildExtension needs `dir`: the extension directory holding manifest.json')
+export async function buildExtension(esbuild, { dir, entry = "src/index.ts", outDir = "build", ...rest } = {}) {
+  if (!dir) throw new BuildError("buildExtension needs `dir`: the extension directory holding manifest.json")
 
   let manifest
   try {
-    manifest = JSON.parse(await readFile(join(dir, MANIFEST_ENTRY), 'utf8'))
+    manifest = JSON.parse(await readFile(join(dir, MANIFEST_ENTRY), "utf8"))
   } catch (e) {
     throw new BuildError(`could not read ${join(dir, MANIFEST_ENTRY)}: ${e.message}`)
   }
@@ -206,13 +250,15 @@ export async function buildExtension(esbuild, { dir, entry = 'src/index.ts', out
   const out = join(dir, outDir)
   await mkdir(out, { recursive: true })
 
-  await esbuild(buildOptionsFor({
-    entry: join(dir, entry),
-    outfile: join(out, 'index.js'),
-    manifest,
-    dir,
-    ...rest,
-  }))
+  await esbuild(
+    buildOptionsFor({
+      entry: join(dir, entry),
+      outfile: join(out, "index.js"),
+      manifest,
+      dir,
+      ...rest,
+    }),
+  )
 
   // The packer reads both from one directory, so the manifest the bundle was
   // built against is the manifest that ships with it. Copied rather than left