@ham2k/extension-sdk 0.1.0 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,139 @@
+# Writing a Ham2K Logger extension
+
+*This file describes the published `@ham2k/extension-sdk` package, as installed
+in an extension project's `node_modules`. Working inside the Ham2K Logger
+repository itself is a different setup — see `docs/extensions/README.md` there.*
+
+You are building an extension for the Ham2K Logger — a TypeScript module the
+app loads into a sandbox and calls through **hooks**. Extensions are where the
+app's domain knowledge lives: award programs, contests, callsign lookups, spot
+sources, exporters, panels.
+
+Everything you need is in this package. `samples/` holds one worked extension
+per shape — start there, with the one whose shape matches what you are
+building. `docs/` is the reference, pinned to the version of the SDK installed
+here; `dist/index.d.ts` is the typed surface, and is the final word wherever
+prose and types disagree.
+
+Paths like `app/lib/config/secret_policy.dart` or `app/experiments.yaml`,
+mentioned in those docs, are files in the Ham2K Logger's own repository
+(<https://github.com/ham2k/halo>). They are not part of your project and you
+cannot read them here.
+
+## The shape of a project
+
+```
+manifest.json      your extension's public identity — read without running code
+src/index.ts       imports the manifest, calls defineExtension
+build.mjs          runs @ham2k/extension-tools' build preset
+build/             generated: index.js + manifest.json
+```
+
+`npx -p @ham2k/extension-tools h2kext-init <yourcallsign>-<name>` writes all of it.
+
+## The smallest whole extension
+
+```ts
+import { defineExtension } from '@ham2k/extension-sdk'
+import type { PanelHook } from '@ham2k/extension-sdk'
+
+import manifest from '../manifest.json'
+
+const HelloPanel: PanelHook = {
+  async getPanels() {
+    return [{ key: 'hello', title: 'Hello World', icon: 'hand-wave-outline' }]
+  },
+  async render() {
+    return { kind: 'markdown', content: '# Hello, World!' }
+  },
+}
+
+defineExtension({
+  ...manifest,
+  onActivation({ registerHook }) {
+    registerHook('panel', { key: manifest.key, hook: HelloPanel })
+  },
+})
+```
+
+`manifest.json` needs at least `key`, `name`, `version`, `description`,
+`category`, `api`, and the `sharedDependencies` below. The manifest is spread
+into `defineExtension` rather than retyped: two sources for the same identity
+drift, and the packer reads the file.
+
+## Building and shipping
+
+```sh
+node build.mjs                              # → build/index.js
+npx -p @ham2k/extension-tools h2kext-pack build -o my-extension.h2kext
+```
+
+The packer is also the checker. It reports every problem at once and refuses
+anything that would install cleanly and then misbehave where you cannot watch
+it, so a clean pack is the strongest evidence available outside the app itself.
+Run it whenever you have changed the manifest or the hooks you register.
+
+`tsc --noEmit` is the other half: the hook interfaces are typed, and a hook that
+typechecks is registered under a category the host knows, with the methods it
+will actually call.
+
+## Where to read next
+
+| Doing this | Read |
+| --- | --- |
+| Anything, before the reference — a whole worked extension of that shape | `samples/`: `k2hrc-hamqth` (lookup + credentials), `k2hrc-llota` (award program), `k2hrc-cqww` (contest + scoring), `k2hrc-radio` (HTML panel) |
+| Any hook at all — what the category is, what it's handed, what it must return | `docs/hooks.md`, the section named for the category |
+| A pane in a view: `getPanels`, `render`, panel content kinds | `docs/hooks.md` §`panel` |
+| Callsign lookups, spot sources, exporters, reference types (POTA-style) | `docs/hooks.md` §`lookup`, §`spots`, §`export`, §`ref:<type>` |
+| Contest or award scoring, and the UI an activity contributes | `docs/hooks.md` §`scoring`, §`activity` |
+| A settings screen for your extension | `docs/settings.md` |
+| Any form, dialog or field the user fills in | `docs/forms.md` |
+| Panel text, export filenames, ADIF fields — anything with `{{ }}` in it | `docs/templates.md` |
+| Packaging, the `.h2kext` format, keys, using the host's libraries | `docs/distribution.md` |
+
+`docs/hooks.md` is long. Read the section for the category you are registering,
+not the file.
+
+## What the sandbox is
+
+No Node, no DOM, no `fetch`, no `window`, no filesystem. One ES2020 engine
+evaluating one script. Reach the outside world through `host`:
+
+```ts
+import { host } from '@ham2k/extension-sdk'
+
+await host.fetch(url)          // https only, and only domains your manifest lists
+await host.kvGet('key')        // storage, namespaced to your extension
+await host.kvSet('key', value)
+await host.showForm(form)      // ask the user something
+await host.showMessage({ … })  // tell them something
+host.log('…')                  // the app's console
+```
+
+`dist/index.d.ts` has the rest, with the types.
+
+## Traps worth knowing before you write anything
+
+- **A panel returns content, not widgets.** `{ kind: 'markdown', content }` and
+  its siblings. There is no way to reach the app's UI toolkit, by design.
+- **`host.fetch` only reaches domains your manifest's `domains` lists**, over
+  https. An undeclared host is refused at the call, not at build.
+- **Using a shared library without declaring it fails the build.** The app
+  carries `@ham2k/lib-*`, `i18next` and `liquidjs`; naming one in
+  `sharedDependencies` rewrites your imports into lookups on the app's single
+  copy, which is worth roughly thirty times the bundle size. Don't install them.
+  `inline: ['liquidjs']` in your build ships your own copy, for when you need a
+  version the app does not carry. A scaffolded manifest already declares the
+  eight this SDK's own modules reach — importing anything from it pulls them
+  in — so deleting one from the manifest breaks a build that was working.
+- **Your key is `<callsign>-<name>`**, lowercase. It namespaces your storage and
+  is what the app shows when it says where something came from. `ham2k-` is
+  reserved.
+- **`host.secret()` returns null** for anything not built into the app. Degrade;
+  don't throw. A hook that throws takes its whole feature down.
+- **Hook method names are routed by string.** The host finds your hook by its
+  registered key and then calls the method by name, so `renderPanel` where
+  `render` was meant is an extension that installs, activates, and does nothing.
+  This is what typing your hook as `PanelHook` (or its siblings) catches.
+- **Every hook is async and crosses a bridge.** Some context reads carry a whole
+  log — fine when exporting, not on a per-keystroke path.

package/README.md

@@ -26,7 +26,7 @@ const HelloPanel: PanelHook = {
 defineExtension({
   ...manifest,
   onActivation({ registerHook }) {
-    registerHook('panel', { key: 'ki2d-hello-world', hook: HelloPanel })
+    registerHook('panel', { key: manifest.key, hook: HelloPanel })
   },
 })
 ```
@@ -34,9 +34,24 @@ defineExtension({
 A panel returns *content*, not widgets — which is what keeps extensions out of
 the app's UI toolkit.
 
-`@ham2k/extension-tools` builds and packages it into a `.h2kext` the app can
-install. See [the extension docs](https://github.com/ham2k/halo/tree/main/docs/extensions)
-for hooks, forms, templates and distribution.
+`npx -p @ham2k/extension-tools h2kext-init <yourcallsign>-<name>` writes
+all of that and the build script; the same package packages the result into a
+`.h2kext` the app can install.
+
+## The reference is in this package
+
+`samples/` holds one worked extension per shape — a callsign lookup with the
+credentials it needs, an award program, a contest and its scorer, an HTML
+panel. Each builds and packs; each says in its header what it leaves out.
+
+`AGENTS.md` beside this file is the map — the manifest, the sandbox's limits,
+and which of `docs/` answers what. `docs/` holds the references themselves:
+every hook category, forms, settings panels, templates, and the bundle format.
+
+They travel in the package rather than being linked to, so they are readable
+offline and describe the version installed here rather than whatever the
+repository says today. If an agent is writing your extension, point it at
+`node_modules/@ham2k/extension-sdk/AGENTS.md` — `h2kext-init` does that for you.
 
 ## About the peer dependencies
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.1.0
+// @ham2k/extension-sdk 0.2.0
 export type CallInfo = {
 	call: string;
 	baseCall?: string;

package/docs/distribution.md

@@ -0,0 +1,279 @@
+# Distributing an extension — the `.h2kext` bundle
+
+An extension can be handed to someone as a single file they install into the
+app: no registry, no app-store release. This describes the format and the tool
+that writes one.
+
+Writing the extension in the first place is the dev loop's job —
+[development.md](https://github.com/ham2k/halo/blob/main/docs/extensions/development.md).
+
+## The format
+
+A `.h2kext` is a **zip**:
+
+```
+manifest.json     required — identity and capabilities
+index.js          required — your extension, built
+assets/           optional — icons, data, licence text
+```
+
+Zip rather than tar.gz for one reason above the others: the host must read
+`manifest.json` **without** running any JS and often without unpacking the
+rest — to list an installed-but-disabled extension, and to show someone what a
+file is asking for *before* they agree to install it. A zip's central
+directory makes that a seek; a tar.gz is a solid stream that must be
+decompressed from the beginning every time. Signed-archive precedent (`.vsix`,
+`.xpi`, `.crx`, `.jar`, `.epub` are all zip) and being openable by
+double-click on macOS and Windows settle the rest.
+
+### manifest.json
+
+The same manifest a built-in extension carries, plus `api`:
+
+```json
+{
+  "key": "w7abc-notes",
+  "name": "W7ABC Notes",
+  "version": "1.2.3",
+  "description": "Notes about the stations I work",
+  "category": "dashboard",
+  "api": 1,
+  "domains": ["notes.example.org"],
+  "icon": "note-text"
+}
+```
+
+`api` is the extension API the bundle was built against. The host refuses one
+it does not speak, so an older app meeting a newer bundle says so instead of
+failing somewhere deep in a hook.
+
+Two fields are **refused** in a distributed bundle, and it is worth
+understanding why:
+
+- **No `category`** makes an extension *core* to the host: always enabled, and
+  never listed in the Extensions panel. That is a status the app grants its own
+  extensions. A distributed bundle claiming it would be one the user could
+  neither see nor turn off.
+- **`experiments`** gates availability against the *app's* experiment catalog.
+  A key the host doesn't define hides the extension permanently, with nothing
+  in the UI to explain it.
+
+## Using the host's libraries
+
+The host carries a set of libraries and hands every extension the same
+instances, so a bundle does not have to ship its own copies:
+
+```
+@ham2k/lib-callsigns      @ham2k/lib-qson-adif
+@ham2k/lib-country-files  @ham2k/lib-qson-cabrillo
+@ham2k/lib-cqmag-data     @ham2k/lib-qson-tools
+@ham2k/lib-dxcc-data      i18next
+@ham2k/lib-format-tools   liquidjs
+@ham2k/lib-geo-tools
+@ham2k/lib-operation-data
+```
+
+It matters more than it sounds. The same extension, built both ways:
+
+| | bundle | packaged |
+|---|---|---|
+| dependencies inlined | 1430 KB | 218 KB |
+| using the host's | 22 KB | **7 KB** |
+
+**Declare what you need.** The host carries whatever version *that build*
+shipped with, and you have no say in which app your bundle lands in. So the
+manifest states the ranges you work with:
+
+```json
+"sharedDependencies": {
+  "@ham2k/lib-callsigns": "^1.0.0",
+  "liquidjs": "^10.0.0"
+}
+```
+
+The host checks those before loading, and refuses a bundle it cannot satisfy —
+which is a message naming the library and both versions, instead of a call
+failing somewhere deep in a hook against a major you never tested.
+
+The packer refuses a bundle that reaches for a shared module **without**
+declaring it, and one that declares a package the host doesn't carry. Anything
+outside that list you bundle yourself, as normal.
+
+Which versions a particular build carries are in its
+`assets/extensions/index.json`, under `sharedModules`.
+
+Emitting the lookups is the build preset's job — see **Building** below.
+
+## Building
+
+```sh
+npm install @ham2k/extension-sdk
+npm install --save-dev @ham2k/extension-tools esbuild
+```
+
+`npx -p @ham2k/extension-tools h2kext-init <yourcallsign>-<name>` writes a working one of everything
+below — manifest, source, build script — so the rest of this section is what to
+change rather than what to type.
+
+```js
+import { build } from 'esbuild'
+import { buildExtension } from '@ham2k/extension-tools'
+
+await buildExtension(build, { dir: import.meta.dirname })
+```
+
+That reads `manifest.json`, compiles `src/index.ts` into `build/index.js`, and
+copies the manifest alongside it, ready for the packer. The esbuild settings it
+applies are requirements of the runtime rather than preferences: one IIFE
+because the sandbox evaluates a script and has no module loader, `neutral`
+because there is no Node and no DOM, and `es2020` because that is what
+QuickJS-NG speaks.
+
+esbuild is yours to bring — the preset takes your `build` function rather than
+importing its own, so there is only ever one copy of it.
+
+Everything `sharedDependencies` names becomes a lookup on the host's instance.
+Anything else you use is bundled, as normal.
+
+**Using one of the host's libraries without declaring it fails the build**,
+naming the library and the two ways out. That is deliberate: the alternative is
+a bundle that silently carries its own copy — thirty times the size, with its
+own module state — and nothing anywhere that says so. If the second copy is
+what you want, which is how you use a version the host does not carry, say so:
+
+```js
+await buildExtension(build, { dir: import.meta.dirname, inline: ['liquidjs'] })
+```
+
+`extensions/samples/hello-world` is the shortest complete example. Declaring
+what it uses rather than carrying it took the packaged bundle from 185 KB to
+**4 KB**.
+
+The preset also settles a trap every author would otherwise hit: the SDK
+reaches `liquidjs`, whose `main`/`module` are its **Node** builds, and
+`platform: 'neutral'` ignores the `browser` field that would pick the right
+one, so a hand-written esbuild config fails on unresolvable Node built-ins
+before it compiles anything — even for an extension that never renders a
+template.
+
+## Packaging
+
+```sh
+node extensions/tools/h2kext-pack.mjs <directory> [-o out.h2kext]
+```
+
+The directory holds your built `index.js`, your `manifest.json`, and optionally
+`assets/`. The packer **packages; it does not compile** — building is yours,
+which is what lets this work outside this repo.
+
+It reports every problem at once rather than one per run:
+
+```
+h2kext-pack: ./build is not ready to package:
+manifest.json: missing required field 'name'
+manifest.json: key 'my-clock' must start with your callsign — 'my' is not one (e.g. ki2d-my-clock)
+manifest.json: missing 'api' — declare the extension API this was built against (currently 1)
+```
+
+`--force-name` waives the naming convention below. It exists for Ham2K's own
+packaging, which builds the extensions that ship inside the app under bare keys
+and the reserved prefix; it does not waive what the runtime needs of a key.
+
+`extensions/tools/h2kext.mjs` holds the format and its rules, and
+`h2kext-build.mjs` the build preset. Both are free of any dependency on the
+rest of this repo, and ship together as **`@ham2k/extension-tools`** — the
+toolchain half, separate from the **`@ham2k/extension-sdk`** an extension
+imports and bundles.
+
+Two things about the SDK package are load-bearing rather than incidental, and
+`extensions/sdk/build.mjs` asserts both:
+
+- It ships as **one file per module**, not one bundle. Rolled into a single
+  file, your bundler can no longer tell which parts your extension reaches, and
+  Hello World comes out five times larger carrying an ADIF importer it cannot
+  call.
+- Its JavaScript keeps the shared libraries as **bare specifiers**. The build
+  preset can only rewrite an import it can see; resolved inside the SDK, they
+  would be gone before it ran, and every extension would carry private copies
+  again.
+
+`kernel.ts` lives in the SDK's source directory and is never published. It is
+the host — it defines the runtime and holds the one instance of every shared
+library that extensions look up. This repo's own
+build uses the same plugin, which is what keeps the path you take from being
+the untested one.
+
+## Keys
+
+An extension key is **`<yourcallsign>-<name>`**:
+
+```
+ki2d-my-clock        w7abc-notes        2e0abc-contest-helper
+```
+
+Lowercase, letters digits and hyphens. The callsign is a namespace every author
+of this software already holds — globally unique, free, and already meaningful
+to everyone here — so two people who never met cannot ship the same key. The
+packer refuses anything else.
+
+`ham2k-` is reserved for Ham2K's own extensions, and refused to everyone else.
+There is no signing yet, so anyone could claim it, and the key is what the app
+shows when it says where a hook came from.
+
+The extensions built into the app use bare keys (`pota`, `sota`, …). Those are
+reserved too: hook identity has to stay unambiguous, and build-secret
+visibility is by key prefix, so an installed extension calling itself `sota`
+would be asking to read `SOTA_*`. The app refuses any collision at install —
+the packer cannot, because a standalone tool has no way to know what the app it
+will be installed into contains.
+
+## What an installed extension does not get
+
+**Build secrets.** `host.secret()` returns null for an installed extension
+whatever key it claims, exactly as it does for a dev-served one: visibility
+follows where the code came from, not what it calls itself. A feature that
+needs one degrades the same way it does in a build without that value
+configured.
+
+The sandbox is otherwise the same one the built-in extensions run in — no
+filesystem, no network beyond the `domains` the manifest declares and the user
+approved, no timers.
+
+## Installing one
+
+**Settings → Extensions → Install from file…**, pick the `.h2kext`, and agree
+to what it asks for. The runtime restarts with it loaded, and the extension
+appears in its own category alongside the app's own, marked *Installed* and
+with a way to remove it again.
+
+What the operator is shown before anything is written is the whole point of
+the format being a zip: the file is opened and read, and only then unpacked.
+
+Installing a bundle whose key is already installed **updates it in place**.
+What it stored survives — an update is not a reinstall, and re-entering
+credentials every time is how people learn not to update.
+
+**Every install asks, including an update that wants nothing new.** Comparing
+capabilities and staying quiet when they had not grown would let a version
+through on the strength of its key alone, and nothing about the *code* behind
+that key is compared — a bundle can change completely and still ask for the
+same things. That may be worth revisiting once a bundle can be shown to come
+from whoever it claims; it is not worth it while a key is all there is.
+
+Removing an extension removes what it stored with it.
+
+## What is checked at install
+
+Beyond what the packer already refused:
+
+- the key is not one the app ships, and does not begin `ham2k-`;
+- the `api` version is one this build speaks;
+- every `sharedDependencies` range is satisfied by what this build carries;
+- entry names are sanitised on extract, so `../` in one writes nothing.
+
+Each has its own message. A bundle that cannot be installed says why.
+
+## Native only, for now
+
+Installed bundles are files on disk. On web the app runs from its own assets
+and, for authors, the dev server — [development.md](https://github.com/ham2k/halo/blob/main/docs/extensions/development.md).