@drift-beacon/plugin 0.1.1 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 The plugin SDK for [Drift Beacon](https://driftbeacon.app). A plugin has **main code**, which runs on your Drift Beacon server, and a **UI**, which opens in the web app. This package gives you their APIs, a Vite plugin that builds both, and the `dbplugin` command that packages a release.
 
-Plugin API version: **0.1**. SDK `0.1.x` builds plugins for Drift Beacon servers that run API 0.1.
+Plugin API version: **0.2**. SDK `0.2.x` builds plugins for Drift Beacon servers that run API 0.2.
 
 ## Contents
 
@@ -16,6 +16,8 @@ Plugin API version: **0.1**. SDK `0.1.x` builds plugins for Drift Beacon servers
 - [Storage](#storage)
 - [Configuration](#configuration)
 - [MQTT and HTTP routes](#mqtt-and-http-routes)
+- [Commands between plugins](#commands-between-plugins)
+- [Events, state and status between plugins](#events-state-and-status-between-plugins)
 - [Errors and limits](#errors-and-limits)
 - [Developing against your server](#developing-against-your-server)
 - [Releasing a plugin](#releasing-a-plugin)
@@ -27,7 +29,7 @@ Plugin API version: **0.1**. SDK `0.1.x` builds plugins for Drift Beacon servers
 mkdir my-plugin && cd my-plugin
 npm init -y
 npm pkg set type=module
-npm install --save-dev @drift-beacon/plugin@0.1 vite typescript @types/node
+npm install --save-dev @drift-beacon/plugin@0.2 vite typescript @types/node
 ```
 
 `package.json` scripts:
@@ -65,7 +67,7 @@ export default defineConfig({ plugins: [driftBeacon()] }); // with React: [react
   "id": "hello",
   "name": "Hello",
   "version": "1.0.0",
-  "apiVersion": "0.1",
+  "apiVersion": "0.2",
   "description": "Says hello when a session starts",
   "author": { "name": "You" },
   "category": "plugin",
@@ -127,7 +129,7 @@ Then `npm run build` writes `dist/`, and `npm run release` writes `releases/hell
 my-plugin/
 ├── package.json        # "type": "module"
 ├── vite.config.ts      # plugins: [driftBeacon()]
-├── tsconfig.json       # references .drift-beacon/tsconfig.{main,ui}.json
+├── tsconfig.json       # references the main and UI tsconfigs
 ├── manifest.json       # identity, API version, icon, settings
 ├── main/src/index.ts   # main code: runs on the server
 ├── ui/                 # the UI: an ordinary Vite app, shown in an iframe in the web app
@@ -142,14 +144,28 @@ my-plugin/
 |---|---|
 | `vite` (`npm run dev`) | Serves the UI with hot reload and rebuilds main on every save. A Drift Beacon server in development mode applies each build and prints the plugin's status and logs in the same terminal. |
 | `vite build` | Production build into `dist/`: `manifest.json`, `package.json`, `main/index.js` and `ui/`. |
-| `dbplugin pack` | Typechecks main and the UI, builds fresh into a temporary folder and writes `releases/<id>.zip`. Prints `{ id, version, tag, asset, archivePath }` as JSON on stdout. `dist/` is untouched. `--out <dir>` picks another folder. |
+| `dbplugin pack` | Typechecks main and the UI (see [Compiler options](#compiler-options)), builds fresh into a temporary folder and writes `releases/<id>.zip`. Prints `{ id, version, tag, asset, archivePath }` as JSON on stdout. `dist/` is untouched. `--out <dir>` picks another folder. |
 | `dbplugin prepare` | Writes `.drift-beacon/`: typed settings and the two tsconfigs. Runs on install and on every build. |
 
 Run `dbplugin` through your package scripts or `npx dbplugin …` inside the plugin folder: it's the copy from your installed SDK.
 
 - **Main** is bundled into one ESM file with every dependency except `@drift-beacon/plugin`, which the server supplies at run time. Native modules aren't supported.
 - **The UI** bundles its own dependencies, including `@drift-beacon/plugin/ui`. Use any framework and library versions you like.
-- `driftBeacon()` owns Vite's `root` (`ui/`), `base` and `build.outDir`: don't set them. It works with Vite 7 and 8.
+- `driftBeacon()` owns Vite's `root` (`ui/`), `base` and `build.outDir`: don't set them. It works with Vite 7 and 8. Under Vitest it only adds the build, so your tests can share `vite.config.ts` while `npm run dev` runs.
+
+### Compiler options
+
+`dbplugin prepare` generates `.drift-beacon/tsconfig.main.json` and `.drift-beacon/tsconfig.ui.json` (React JSX in the UI). To change a compiler option, add `main/tsconfig.json` or `ui/tsconfig.json` that extends the generated file, and reference it from `tsconfig.json` instead. `dbplugin pack` typechecks it in place of the generated one. For a Preact UI:
+
+```json
+{ "extends": "../.drift-beacon/tsconfig.ui.json", "compilerOptions": { "jsxImportSource": "preact" } }
+```
+
+```json
+{ "files": [], "references": [{ "path": "./.drift-beacon/tsconfig.main.json" }, { "path": "./ui/tsconfig.json" }] }
+```
+
+Keep `extends`: the generated file brings the settings types, the SDK's module resolution and the source folders.
 
 | Import | Used by | Contents |
 |---|---|---|
@@ -163,12 +179,14 @@ Run `dbplugin` through your package scripts or `npx dbplugin …` inside the plu
 |---|---|
 | `id` | Lowercase letters, digits and hyphens, starting with a letter or digit, at most 64 characters |
 | `version` | Semantic version (`1.2.3`); build metadata is allowed, prereleases are not |
-| `apiVersion` | `major.minor` of the SDK you build with (`"0.1"`) |
+| `apiVersion` | `major.minor` of the SDK you build with (`"0.2"`) |
 | `name`, `description` | Required text |
 | `author` | `{ name, email? }` |
 | `category` | `plugin`, `utility` or `ui` |
 | `icon` | A file name in `ui/public/`, or `""` |
 | `configuration` | Settings (see [Configuration](#configuration)) |
+| `provides` | Optional: commands, events and state other plugins can use (see [Commands between plugins](#commands-between-plugins) and [Events, state and status](#events-state-and-status-between-plugins)) |
+| `uses` | Optional: the plugins this one uses, by manifest id, with a version range (`{ "magic-cube": "^1.1.0" }`) |
 
 Settings items have `name` (unique), `title`, `type` and optional `description` and `required`:
 
@@ -183,9 +201,9 @@ Settings items have `name` (unique), `title`, `type` and optional `description`
 
 `main/src/index.ts` default-exports `definePlugin({ onStart(ctx) { … } })`. The server runs one **instance** for each user and workspace that enabled the plugin; each gets its own `ctx`.
 
-- **Start.** `onStart(ctx)` may be async and must finish within 15 seconds. If it throws, the instance doesn't start.
+- **Start.** `onStart(ctx)` may be async and must finish within 15 seconds. Callbacks and routes work as soon as they are registered. If it throws, the instance doesn't start.
 - **Register through `ctx`.** Callbacks, routes and MQTT subscriptions made through `ctx` are released when the instance stops. Keep per-instance state inside `onStart`, never at module scope: the module is shared by every instance.
-- **Stop.** `ctx.onStop(fn)` callbacks run newest first, 5 seconds in total. Afterwards every `ctx` call throws `PluginError` with code `stopped`.
+- **Stop.** `ctx.onStop(fn)` callbacks run newest first, 5 seconds in total, whatever stops the instance (a fault or server shutdown too, even when something else stops it meanwhile). Afterwards every `ctx` call throws `PluginError` with code `stopped`. A server that is killed rather than shut down cuts them short.
 - **Faults.** An uncaught error or unhandled rejection stops only that instance, which is retried after 5, 30 and 120 seconds.
 
 | `ctx` member | Main | UI | |
@@ -196,11 +214,13 @@ Settings items have `name` (unique), `title`, `type` and optional `description`
 | `onDataChange` | ✓ | ✓ | The data changed |
 | `sessions.onStarted`, `onEnded`, `onMarked` | ✓ | | Live session events |
 | `storage` | ✓ | ✓ | Key-value storage |
+| `plugins` | ✓ | ✓ | The plugins it uses and itself: status, state, events and commands |
+| `commands`, `events`, `state` | ✓ | | What it provides to other plugins |
 | `mqtt`, `routes`, `log`, `onStop` | ✓ | | Main code only |
 
 ## UI
 
-`connect()` performs a handshake with the web app and resolves to the UI `ctx`. It rejects with `unsupported` when the app doesn't run this UI's API version, and with `unavailable` outside Drift Beacon or after 10 seconds without an answer. `ctx.onDataChange` fires after every update (data, settings or storage).
+`connect()` performs a handshake with the web app and resolves to the UI `ctx`. It rejects with `unsupported` when the app doesn't run this UI's API version, and with `unavailable` outside Drift Beacon or after 10 seconds without an answer. `ctx.onDataChange` fires after every update (data, settings, storage, or other plugins' status and state; not their events).
 
 With React, re-render on every update:
 
@@ -281,7 +301,7 @@ await ctx.sessions.end(sessionId);      // or session.end(), activity.end()
 await ctx.sessions.discard(sessionId);  // or session.discard()
 ```
 
-Actions run as the current user and resolve once `ctx` shows their result. Starting a session ends the user's other live session, as in the app.
+Actions run as the current user and resolve once `ctx` shows their result. Starting a session ends the user's other live session, as in the app. An id that isn't a non-empty string rejects with `invalid`.
 
 | | Live session events | Data change events |
 |---|---|---|
@@ -294,7 +314,7 @@ Never trigger actions from data changes. Live events fire for everyone's session
 
 ## Storage
 
-Per plugin, user and workspace, shared by main code and the UI. Values must be JSON.
+Per plugin, user and workspace, shared by main code and the UI. Keys are non-empty strings and values must be JSON: anything else rejects with `invalid`, and setting `undefined` removes the key. `set` and `remove` apply at once and resolve when Drift Beacon has accepted the write.
 
 ```ts
 const faces = ctx.storage.get<Record<string, string>>("faces") ?? {};
@@ -307,6 +327,8 @@ ctx.storage.onChange((key, value) => { /* changed by main code, a UI or another
 
 `ctx.config` holds the settings from the manifest's `configuration`. `dbplugin prepare` turns them into types (`.drift-beacon/config.d.ts`), so `ctx.config.mqttTopic` is typed in main code and the UI. A setting is optional unless it is `required` or has a `default`. An instance only runs with valid settings; changing them restarts it.
 
+The app blocks opening a UI when required settings are missing or blank. This presence check does not validate every setting: if saved values fail schema validation, the UI receives defaults under the saved values while main does not run. Check values before relying on them.
+
 ## MQTT and HTTP routes
 
 Main code only.
@@ -319,8 +341,83 @@ ctx.routes.post("webhook", async ({ body }) => ({ status: 202, body: { ok: true
 ctx.routes.get("status", () => ({ body: { live: ctx.sessions.live({ mine: true }).length } }));
 ```
 
-- MQTT uses the workspace's broker; `publish` rejects with `unavailable` without one.
-- Routes are served at `<server>/api/plugins/<plugin id>/api/<name>` (`ctx.plugin.apiPath` is the path up to `/api`). Callers send `Authorization: Bearer <workspace API key>`, which picks the user and workspace. Handlers return `{ status?, body? }`; `body` is sent as JSON.
+- MQTT uses the workspace's broker; `publish` rejects with `unavailable` without one or while it isn't connected, and with `invalid` for an empty topic or a payload that isn't a string (nothing is sent).
+- Routes are served at `<server>/api/plugins/<plugin id>/api/<name>` (`ctx.plugin.apiPath` is the path up to `/api`). Callers send `Authorization: Bearer <workspace API key>`, which picks the user and workspace. Handlers return `{ status?, body? }`; `body` is sent as JSON. While `onStart` runs, a route not registered yet answers 503 (retry after 5 s).
+
+## Commands between plugins
+
+Main code provides commands; main code, UIs and Home Assistant run them. A plugin declares the commands it provides in `manifest.json` and handles them; another plugin lists it in `uses` and runs them, as the same user in the same workspace.
+
+```jsonc
+// magic-cube/manifest.json
+"provides": { "commands": { "selectPreset": {
+  "title": "Select preset",
+  "input": { "type": "object", "properties": { "preset": { "type": ["string", "null"] } }, "required": ["preset"] },
+  "output": { "type": "object", "properties": { "activePresetId": { "type": ["string", "null"] } } }
+} } }
+// cartridge-reader/manifest.json
+"uses": { "magic-cube": "^1.1.0" }
+```
+
+```ts
+// magic-cube
+ctx.commands.handle("selectPreset", async ({ preset }, meta) => ({ activePresetId: await select(preset) }));
+// cartridge-reader
+const result = await ctx.plugins.get("magic-cube").command("selectPreset", { preset: "Focus" });
+```
+
+- Names are camelCase. Schemas are a subset of JSON Schema: `type` (a name or a list such as `["string", "null"]`), `enum`, `properties`, `required`, `additionalProperties` (objects are closed by default), `items`, `minimum`, `maximum`, `title`, `description`, `default`. Other keywords are rejected.
+- The input is checked before the command runs (`invalid`), the output after (`failed`). Throw a `PluginError` to answer with its code.
+- It fails fast: `not-installed`, `disabled`, `incompatible` (outside your range) or `unavailable` (not running; it didn't run). `timeout` and `stopped` mean it may have run.
+- `timeoutMs` defaults to 10 s (at most 30 s). A command run inside another continues its chain and shares what's left of its time; the ninth step of a chain is refused with `loop`.
+- From a UI: `ctx.plugins.get(id).command(…)` as in main code. The UI waits the command's time plus 2 s, then rejects `timeout`.
+- In Home Assistant, each command is an action, `drift_beacon.<manifest id>_<command in snake_case>` (`drift_beacon.magic_cube_select_preset`), on a workspace's device: its fields are your input's properties; if you declare `output`, a call on one workspace can ask for the response `{ output }`. It runs as that workspace's user with `meta.caller` `{ kind: "integration" }` and 10 s, and needs no `uses`. Renaming a command or input field breaks automations as it breaks other plugins.
+- `dbplugin prepare` types what you provide (`.drift-beacon/config.d.ts`): `ctx.commands.handle`, `ctx.events.emit` and `ctx.state` take only declared names, with their declared types (none for a kind you declare nothing of).
+- Plugins you use aren't typed for you: keep a copy of the types you need, written from their manifest. `command<T>()` and `state.get<T>()` take the type, and an event's payload is `unknown` until you narrow it. Update the copy along with your `uses` range.
+
+```ts
+// cartridge-reader: what it uses from magic-cube ^1.1.0, kept by hand
+interface SelectPresetOutput {
+  activePresetId: string | null;
+}
+
+const cube = ctx.plugins.get("magic-cube");
+const { activePresetId } = await cube.command<SelectPresetOutput>("selectPreset", { preset: "Focus" });
+const preset = cube.state.get<string | null>("activePreset");
+cube.onEvent("faceChanged", (face) => showFace(face as number));
+```
+
+## Events, state and status between plugins
+
+Main code emits and publishes; main code and UIs receive them. A plugin emits the events and publishes the state it declares in `provides`; the plugins that use it (and the plugin itself, through `ctx.plugins.self`) receive them, and see its status.
+
+```jsonc
+// magic-cube/manifest.json
+"provides": {
+  "events": { "faceChanged": { "title": "Face changed", "payload": { "type": "integer", "minimum": 1, "maximum": 6 } } },
+  "state": { "activePreset": { "title": "Active preset", "schema": { "type": ["string", "null"] } } }
+}
+```
+
+```ts
+// magic-cube
+ctx.events.emit("faceChanged", 3);
+ctx.state.set("activePreset", "focus"); // undefined removes it
+// cartridge-reader
+const cube = ctx.plugins.get("magic-cube");
+cube.onEvent("faceChanged", (face, meta) => ctx.log.info(`Face ${face}, step ${meta.depth}`));
+cube.state.get("activePreset"); // read it in onStart, then follow cube.state.onChange
+cube.onStatusChange(({ state, reason }) => ctx.log.info(state, reason ?? ""));
+```
+
+- `emit` and `set` throw `invalid` for an undeclared name, a value that doesn't match its schema, or over 64 KiB (256 KiB of state in all). Received values are frozen.
+- Events reach listeners registered by then (from `onStart` on; in a UI, right after `connect()`); earlier ones are missed. State is kept in memory while the provider runs, cleared when it stops, never persisted.
+- A plugin can emit 50 events a second on average, in bursts up to 100; Drift Beacon drops the rest, with a warning in your console at most every 10 s (each after the first says how many it dropped). For a value that changes faster, publish the latest as state (not limited) or send fewer, bigger events.
+- In main code, a command handler's events and state changes arrive before its caller's `await` resumes.
+- Listeners continue the chain of what caused them; past 8 steps, events are dropped (with a warning) and state changes call no callbacks.
+- `status.state` is `running`, `starting`, `unavailable`, `disabled`, `incompatible` or `not-installed`, with the resolved `version` and a `reason`.
+- In a UI, status and state arrive within about 250 ms (and `ctx.onDataChange` fires), as the latest at each update (changes close together arrive as one), so a command's effects can show just after it resolves: render from `onChange`, or use its output.
+- In a UI (from 0.2.1), events come with those updates, each after the state its plugin set before it. None are replayed (reconnects, reloads, more than about 100 between two updates), every open copy of the UI gets each one, and a command a UI listener runs starts a new chain: render in UI listeners, and react with commands in main code. On an older Drift Beacon they never arrive.
 
 ## Errors and limits
 
@@ -329,11 +426,13 @@ Operations reject with `PluginError`. Check `error.code`, not `instanceof`:
 | Code | Meaning |
 |---|---|
 | `unsupported` | The app doesn't support this API version or request |
-| `invalid` | Bad arguments (tracking a point with `start()`, a value that isn't JSON, …) |
+| `invalid` | Bad arguments (an empty id or storage key, an MQTT payload that isn't a string, tracking a point with `start()`, a value that isn't JSON, an undeclared event, …) |
 | `not-found` | The activity or session doesn't exist, or the model was removed |
 | `unavailable` | Something needed isn't there: no MQTT broker, no answer from the app |
 | `stopped` | The instance has stopped |
 | `failed` | Anything else, such as tracking an archived activity |
+| `not-installed`, `disabled`, `incompatible` | The plugin you ran a command on isn't installed, is disabled here, or is outside your `uses` range |
+| `loop`, `timeout` | A chain of commands went deeper than 8 steps; a command didn't answer in time (it may have run) |
 
 | | Limit |
 |---|---|
@@ -341,11 +440,12 @@ Operations reject with `PluginError`. Check `error.code`, not `instanceof`:
 | Blocking the event loop | The server restarts the plugin host after 10 s |
 | Actions | 10 s, then `unavailable` |
 | Route handlers | 30 s, then 504 |
+| Commands to other plugins | 10 s by default (at most 30 s), then `timeout`; 8 steps deep; 64 KiB in and out |
 | Release package | 32 MiB zipped, 128 MiB unpacked, 2,000 files |
 
 ## Developing against your server
 
-On a Drift Beacon server you run yourself, set `DEV_PLUGINS_PATH` to the folder that contains your plugin folders and start the server in development mode. It lists each plugin under **Plugins → Development**. Enable it in a workspace, then run `npm run dev` in the plugin folder: every save rebuilds main, the server restarts the plugin, and its status, logs and errors (with stack traces pointing at your source) print in your terminal. The UI updates in place.
+On a Drift Beacon server you run yourself, set `DEV_PLUGINS_PATH` to the folder that contains your plugin folders and start the server in development mode. It lists each plugin under **Plugins → Repositories → Local development**. Enable it in a workspace, then run `npm run dev` in the plugin folder: every save rebuilds main, the server restarts the plugin, and its status, logs and errors (with stack traces pointing at your source) print in your terminal. The UI updates in place.
 
 ## Releasing a plugin
 
@@ -355,13 +455,13 @@ Plugins are published on GitHub. In a public repository, each immediate child fo
 2. Run `npm run release` (or `npx dbplugin pack`), which writes `releases/<id>.zip`.
 3. Create a GitHub release tagged `<id>-<version>` (for example `hello-1.0.0`) and attach `<id>.zip`.
 
-Users add the repository URL in **Plugins → Store** and install from there. Don't commit `dist/` or `releases/`.
+Users add the repository URL in **Plugins → Repositories** and install from there. Don't commit `dist/` or `releases/`.
 
 ## Versions
 
 - `apiVersion` in the manifest must match the SDK: `dbplugin`, `vite build` and the server all check it.
-- Before 1.0, each minor version (`0.1`, `0.2`) may change the API, and a server runs only its exact version. Install the SDK with `@0.1` to stay on it.
-- Minor releases may add fields and new string values (such as a new `trackingType`): ignore what you don't recognise.
+- Before 1.0, each minor version (`0.1`, `0.2`) may change the API, and a server runs only its exact version. Install the SDK with `@0.2` to stay on it.
+- Patch releases (`0.2.x`) fix bugs and may add to API 0.2. An addition that needs the app, such as UI events in 0.2.1, does nothing on an older Drift Beacon. Ignore fields and string values you don't recognise (such as a new `trackingType`).
 
 ## License
 

package/dist/internal/actions.js

@@ -1 +1,23 @@
-export {};
+const nonEmpty = (value, what) => typeof value === "string" && value !== "" ? null : `${what} must be a non-empty string`;
+const ARGUMENTS = {
+    startSession: (action) => nonEmpty(action.activityId, "Activity id"),
+    markPoint: (action) => nonEmpty(action.activityId, "Activity id"),
+    endSession: (action) => nonEmpty(action.sessionId, "Session id"),
+    discardSession: (action) => nonEmpty(action.sessionId, "Session id"),
+    storageSet: (action) => nonEmpty(action.key, "Storage key"),
+    storageRemove: (action) => nonEmpty(action.key, "Storage key"),
+    mqttSubscribe: (action) => nonEmpty(action.topic, "MQTT topic"),
+    mqttUnsubscribe: (action) => nonEmpty(action.topic, "MQTT topic"),
+    mqttPublish: (action) => nonEmpty(action.topic, "MQTT topic") ??
+        (typeof action.payload === "string" ? null : "MQTT payload must be a string"),
+};
+export function checkedAction(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const action = value;
+    const name = action.name;
+    if (typeof name !== "string" || !Object.hasOwn(ARGUMENTS, name))
+        return null;
+    const problem = ARGUMENTS[name](action);
+    return problem === null ? { ok: true, action: action } : { ok: false, problem };
+}

package/dist/internal/collection.js

@@ -1,12 +1,5 @@
+import { deepFreeze } from "./freeze.js";
 import { jsonEqual } from "./json-equal.js";
-function deepFreeze(value) {
-    if (value && typeof value === "object" && !Object.isFrozen(value)) {
-        for (const child of Object.values(value))
-            deepFreeze(child);
-        Object.freeze(value);
-    }
-    return value;
-}
 export class Collection {
     rows = new Map();
     cachedList = null;

package/dist/internal/freeze.js

@@ -0,0 +1,8 @@
+export function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/internal/manifest.js

@@ -1,8 +1,9 @@
 import { parseApiVersion } from "./compatibility.js";
-const STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
-export const isStableVersion = (value) => typeof value === "string" &&
-    STABLE_VERSION.test(value) &&
-    (value.split("+")[0] ?? "").split(".").every((part) => Number.isSafeInteger(Number(part)));
+import { PEER_LIMITS, PEER_NAME } from "./peers.js";
+import { validateSchema } from "./schema.js";
+import { isStableVersion, validateRange } from "./semver.js";
+const PLUGIN_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const isManifestId = (id) => PLUGIN_ID.test(id);
 export function validateManifest(manifest) {
     if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
         throw new Error("Invalid plugin manifest");
@@ -12,8 +13,8 @@ export function validateManifest(manifest) {
         if (typeof text !== "string" || !text.trim())
             throw new Error(`Plugin manifest missing required field: ${field}`);
     }
-    const { id, version, apiVersion, author, category, icon, configuration } = value;
-    if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(id)) {
+    const { id, version, apiVersion, author, category, icon, configuration, provides, uses } = value;
+    if (!PLUGIN_ID.test(id)) {
         throw new Error("Plugin id must contain only lowercase letters, numbers and hyphens (maximum 64 characters)");
     }
     if (!isStableVersion(version)) {
@@ -34,6 +35,79 @@ export function validateManifest(manifest) {
     const names = new Set();
     for (const item of configuration)
         validateConfigurationItem(item, names);
+    if (provides !== undefined)
+        validateProvides(provides);
+    if (uses !== undefined)
+        validateUses(uses, id);
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const DECLARATION_FIELDS = {
+    commands: ["title", "description", "input", "output"],
+    events: ["title", "description", "payload"],
+    state: ["title", "description", "schema"],
+};
+function validateProvides(provides) {
+    if (!isRecord(provides))
+        throw new Error("provides: must be an object");
+    for (const [kind, declarations] of Object.entries(provides)) {
+        if (!Object.hasOwn(DECLARATION_FIELDS, kind))
+            throw new Error(`provides: "${kind}" is not supported`);
+        const fields = DECLARATION_FIELDS[kind];
+        const at = `provides.${kind}`;
+        if (!isRecord(declarations))
+            throw new Error(`${at}: must be an object`);
+        const entries = Object.entries(declarations);
+        if (entries.length > PEER_LIMITS.declarations)
+            throw new Error(`${at}: at most ${PEER_LIMITS.declarations}`);
+        for (const [name, declaration] of entries) {
+            if (!PEER_NAME.test(name))
+                throw new Error(`${at}: "${name}" must be camelCase (letters and digits, up to 48)`);
+            const path = `${at}.${name}`;
+            if (!isRecord(declaration))
+                throw new Error(`${path}: must be an object`);
+            for (const field of Object.keys(declaration))
+                if (!fields.includes(field))
+                    throw new Error(`${path}: "${field}" is not supported`);
+            if (typeof declaration.title !== "string" || !declaration.title.trim())
+                throw new Error(`${path}: title is required`);
+            if (declaration.description !== undefined && typeof declaration.description !== "string")
+                throw new Error(`${path}: description must be text`);
+            if (kind === "commands") {
+                if (declaration.input !== undefined) {
+                    validateSchema(declaration.input, `${path}.input`);
+                    if (declaration.input.type !== "object")
+                        throw new Error(`${path}.input: must be an object schema (named fields)`);
+                }
+                if (declaration.output !== undefined)
+                    validateSchema(declaration.output, `${path}.output`);
+            }
+            else if (kind === "events") {
+                if (declaration.payload !== undefined)
+                    validateSchema(declaration.payload, `${path}.payload`);
+            }
+            else
+                validateSchema(declaration.schema, `${path}.schema`);
+        }
+    }
+}
+function validateUses(uses, id) {
+    if (!isRecord(uses))
+        throw new Error("uses: must be an object of plugin ids and version ranges");
+    const entries = Object.entries(uses);
+    if (entries.length > PEER_LIMITS.uses)
+        throw new Error(`uses: at most ${PEER_LIMITS.uses} plugins`);
+    for (const [plugin, range] of entries) {
+        if (!PLUGIN_ID.test(plugin))
+            throw new Error(`uses: "${plugin}" is not a plugin id`);
+        if (plugin === id)
+            throw new Error("uses: a plugin can always reach itself; don't list it");
+        try {
+            validateRange(range);
+        }
+        catch (error) {
+            throw new Error(`uses.${plugin}: ${error.message}`);
+        }
+    }
 }
 function validateConfigurationItem(value, names) {
     const item = value;

package/dist/internal/peers.js

@@ -0,0 +1,60 @@
+import { schemaError } from "./schema.js";
+export const PEER_NAME = /^[a-z][A-Za-z0-9]{0,47}$/;
+export const PEER_LIMITS = {
+    declarations: 64,
+    uses: 32,
+    valueBytes: 64 * 1024,
+    stateBytes: 256 * 1024,
+    depth: 8,
+    eventsPerSecond: 50,
+    eventBurst: 100,
+};
+export const COMMAND_TIMEOUT = { defaultMs: 10_000, maxMs: 30_000, minimumMs: 100 };
+export const commandBudgetMs = (timeoutMs) => Math.min(timeoutMs ?? COMMAND_TIMEOUT.defaultMs, COMMAND_TIMEOUT.maxMs);
+export const eventNameProblem = (name) => typeof name === "string" && PEER_NAME.test(name)
+    ? null
+    : `Event names are camelCase letters and digits (got "${String(name)}")`;
+export function commandArgumentsProblem(command, input, options) {
+    if (typeof command !== "string" || !command)
+        return "Command name must be a non-empty string";
+    if (input !== undefined && (typeof input !== "object" || input === null || Array.isArray(input)))
+        return "Command input must be an object of named fields";
+    const timeoutMs = options?.timeoutMs;
+    if (timeoutMs !== undefined && (typeof timeoutMs !== "number" || !(timeoutMs > 0)))
+        return "timeoutMs must be a positive number of milliseconds";
+    return null;
+}
+export const PLUGIN_ERROR_CODES = [
+    "unsupported",
+    "invalid",
+    "not-found",
+    "unavailable",
+    "stopped",
+    "failed",
+    "not-installed",
+    "disabled",
+    "incompatible",
+    "loop",
+    "timeout",
+];
+export function checkedValue(schema, value, path) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch {
+        return { ok: false, problem: `${path} isn't JSON` };
+    }
+    if (json === undefined) {
+        const problem = schema ? schemaError(schema, undefined, path) : null;
+        return problem ? { ok: false, problem } : { ok: true, value: undefined, size: 0 };
+    }
+    if (!schema)
+        return { ok: false, problem: `${path}: none is declared` };
+    if (json.length > PEER_LIMITS.valueBytes)
+        return { ok: false, problem: `${path} is over ${PEER_LIMITS.valueBytes / 1024} KiB` };
+    const plain = JSON.parse(json);
+    const problem = schemaError(schema, plain, path);
+    return problem ? { ok: false, problem } : { ok: true, value: plain, size: json.length };
+}
+export const samePluginStatus = (a, b) => a.state === b.state && a.version === b.version && a.reason === b.reason;

package/dist/internal/schema.js

@@ -0,0 +1,156 @@
+export const SCHEMA_LIMITS = { depth: 6, nodes: 256 };
+const TYPES = ["string", "number", "integer", "boolean", "null", "object", "array"];
+const KEYWORDS = new Set([
+    "type",
+    "enum",
+    "properties",
+    "required",
+    "additionalProperties",
+    "items",
+    "minimum",
+    "maximum",
+    "title",
+    "description",
+    "default",
+]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const typesOf = (schema) => typeof schema.type === "string" ? [schema.type] : schema.type;
+export function validateSchema(schema, path) {
+    let nodes = 0;
+    const visit = (node, at, depth) => {
+        if (depth > SCHEMA_LIMITS.depth)
+            throw new Error(`${path}: nested more than ${SCHEMA_LIMITS.depth} levels`);
+        if (++nodes > SCHEMA_LIMITS.nodes)
+            throw new Error(`${path}: more than ${SCHEMA_LIMITS.nodes} schemas`);
+        if (!isRecord(node))
+            throw new Error(`${at}: type must be one of ${TYPES.join(", ")}`);
+        for (const key of Object.keys(node))
+            if (!KEYWORDS.has(key))
+                throw new Error(`${at}: "${key}" is not supported`);
+        const types = typeof node.type === "string" ? [node.type] : node.type;
+        if (!Array.isArray(types) ||
+            types.length === 0 ||
+            types.some((type) => !TYPES.includes(type)) ||
+            new Set(types).size !== types.length)
+            throw new Error(`${at}: type must be one of ${TYPES.join(", ")}, or a list of them`);
+        const schema = node;
+        const has = (type) => types.includes(type);
+        if (schema.title !== undefined && typeof schema.title !== "string")
+            throw new Error(`${at}: title must be text`);
+        if (schema.description !== undefined && typeof schema.description !== "string")
+            throw new Error(`${at}: description must be text`);
+        if (schema.minimum !== undefined || schema.maximum !== undefined) {
+            if (!has("number") && !has("integer"))
+                throw new Error(`${at}: minimum and maximum need type number or integer`);
+            for (const bound of [schema.minimum, schema.maximum])
+                if (bound !== undefined && (typeof bound !== "number" || !Number.isFinite(bound)))
+                    throw new Error(`${at}: minimum and maximum must be numbers`);
+            if (schema.minimum !== undefined && schema.maximum !== undefined && schema.minimum > schema.maximum)
+                throw new Error(`${at}: minimum exceeds maximum`);
+        }
+        if (schema.properties !== undefined || schema.required !== undefined || schema.additionalProperties !== undefined) {
+            if (!has("object"))
+                throw new Error(`${at}: properties need type object`);
+        }
+        if (has("object")) {
+            if (schema.properties !== undefined && !isRecord(schema.properties))
+                throw new Error(`${at}: properties must be an object`);
+            if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean")
+                throw new Error(`${at}: additionalProperties must be true or false`);
+            for (const [name, property] of Object.entries(schema.properties ?? {}))
+                visit(property, `${at}.properties.${name}`, depth + 1);
+            if (schema.required !== undefined) {
+                if (!Array.isArray(schema.required))
+                    throw new Error(`${at}: required must be a list of property names`);
+                for (const name of schema.required)
+                    if (typeof name !== "string" || !Object.hasOwn(schema.properties ?? {}, name))
+                        throw new Error(`${at}: required "${String(name)}" is not in properties`);
+            }
+        }
+        if (schema.items !== undefined && !has("array"))
+            throw new Error(`${at}: items need type array`);
+        if (has("array")) {
+            if (schema.items === undefined)
+                throw new Error(`${at}: an array needs items`);
+            visit(schema.items, `${at}.items`, depth + 1);
+        }
+        if (schema.enum !== undefined) {
+            if (!Array.isArray(schema.enum) || schema.enum.length === 0)
+                throw new Error(`${at}: enum must be a list of values`);
+            for (const [index, value] of schema.enum.entries()) {
+                const scalar = value === null || ["string", "number", "boolean"].includes(typeof value);
+                if (!scalar || valueError({ ...schema, enum: undefined }, value, `${at}.enum[${index}]`))
+                    throw new Error(`${at}.enum[${index}]: must be a ${types.join(" or ")} value`);
+            }
+        }
+        if (schema.default !== undefined) {
+            const error = valueError(schema, schema.default, `${at}.default`);
+            if (error)
+                throw new Error(error);
+        }
+    };
+    visit(schema, path, 1);
+}
+export function schemaError(schema, value, path) {
+    return valueError(schema, value, path);
+}
+function valueError(schema, value, path) {
+    const types = typesOf(schema);
+    const matches = (type) => {
+        switch (type) {
+            case "null":
+                return value === null;
+            case "boolean":
+                return typeof value === "boolean";
+            case "string":
+                return typeof value === "string";
+            case "number":
+                return typeof value === "number" && Number.isFinite(value);
+            case "integer":
+                return typeof value === "number" && Number.isInteger(value);
+            case "array":
+                return Array.isArray(value);
+            case "object":
+                return isRecord(value) && Object.getPrototypeOf(value) === Object.prototype;
+        }
+    };
+    const type = types.find(matches);
+    if (!type)
+        return `${path}: expected ${types.join(" or ")}`;
+    if (schema.enum && !schema.enum.includes(value))
+        return `${path}: must be one of ${schema.enum.map((option) => JSON.stringify(option)).join(", ")}`;
+    if (typeof value === "number") {
+        if (schema.minimum !== undefined && value < schema.minimum)
+            return `${path}: below the minimum ${schema.minimum}`;
+        if (schema.maximum !== undefined && value > schema.maximum)
+            return `${path}: above the maximum ${schema.maximum}`;
+    }
+    if (type === "array" && schema.items) {
+        for (const [index, item] of value.entries()) {
+            const error = valueError(schema.items, item, `${path}[${index}]`);
+            if (error)
+                return error;
+        }
+    }
+    if (type === "object") {
+        const object = value;
+        const properties = schema.properties ?? {};
+        for (const name of schema.required ?? [])
+            if (object[name] === undefined)
+                return `${path}: missing "${name}"`;
+        for (const [name, property] of Object.entries(object)) {
+            if (property === undefined)
+                continue;
+            const declared = properties[name];
+            if (!declared) {
+                if (schema.additionalProperties)
+                    continue;
+                return `${path}: unexpected "${name}"`;
+            }
+            const error = valueError(declared, property, `${path}.${name}`);
+            if (error)
+                return error;
+        }
+    }
+    return null;
+}