@drift-beacon/plugin 0.1.0 → 0.2.0

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;
+}

package/dist/internal/semver.js

@@ -0,0 +1,47 @@
+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)));
+const parts = (version) => {
+    const [major = 0, minor = 0, patch = 0] = (version.split("+")[0] ?? "").split(".").map(Number);
+    return [major, minor, patch];
+};
+export function compareVersions(left, right) {
+    if (!isStableVersion(left) || !isStableVersion(right))
+        throw new Error("Expected a stable semantic version");
+    const a = parts(left);
+    const b = parts(right);
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return (a[i] ?? 0) > (b[i] ?? 0) ? 1 : -1;
+    return 0;
+}
+const RANGE = /^(\^|~|>=)?(.+)$/;
+export function validateRange(range) {
+    if (range === "*")
+        return;
+    const match = typeof range === "string" ? RANGE.exec(range) : null;
+    if (!match?.[2] || !isStableVersion(match[2]) || match[2].includes("+"))
+        throw new Error(`Unsupported version range "${String(range)}": use 1.2.3, ^1.2.3, ~1.2.3, >=1.2.3 or *`);
+}
+export function satisfiesRange(version, range) {
+    validateRange(range);
+    if (range === "*")
+        return true;
+    const [, operator = "", base = ""] = RANGE.exec(range) ?? [];
+    if (compareVersions(version, base) < 0)
+        return false;
+    if (operator === "")
+        return compareVersions(version, base) === 0;
+    if (operator === ">=")
+        return true;
+    const [major, minor, patch] = parts(base);
+    const [vMajor, vMinor, vPatch] = parts(version);
+    if (operator === "~")
+        return vMajor === major && vMinor === minor;
+    if (major > 0)
+        return vMajor === major;
+    if (minor > 0)
+        return vMajor === 0 && vMinor === minor;
+    return vMajor === 0 && vMinor === 0 && vPatch === patch;
+}

package/dist/main.d.ts

@@ -1,4 +1,4 @@
-import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, Session, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
+import type { ActivitiesApi, CategoriesApi, PeerStateApi, PluginConfig, PluginInfo, PluginPeer, PluginsApi, Session, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
 export type SessionEndReason = "completed" | "discarded";
 export interface MainSessionsApi extends SessionsApi {
     /**
@@ -51,6 +51,94 @@ export interface LogApi {
     warn(...args: unknown[]): void;
     error(...args: unknown[]): void;
 }
+/** Who ran a command: another plugin's main code (by manifest id), a plugin UI, or an integration such as Home Assistant. */
+export type CommandCaller = {
+    readonly kind: "plugin";
+    readonly plugin: string;
+} | {
+    readonly kind: "ui";
+    readonly plugin: string;
+} | {
+    readonly kind: "integration";
+};
+/** The commands this plugin provides. `dbplugin prepare` fills this in from manifest.json `provides` (.drift-beacon/config.d.ts). */
+export interface PluginCommands {
+}
+/** The events this plugin emits. `dbplugin prepare` fills this in from manifest.json `provides`. */
+export interface PluginEvents {
+}
+/** The state this plugin publishes. `dbplugin prepare` fills this in from manifest.json `provides`. */
+export interface PluginState {
+}
+/** A declared map, or any name when nothing is declared (a plugin without generated types). */
+type Declared<T, Fallback> = keyof T extends never ? {
+    readonly [name: string]: Fallback;
+} : T;
+type Commands = Declared<PluginCommands, {
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly output: unknown;
+}>;
+type Events = Declared<PluginEvents, unknown>;
+type States = Declared<PluginState, unknown>;
+type CommandName = keyof Commands & string;
+type EventName = keyof Events & string;
+type StateKey = keyof States & string;
+/** The chain a call belongs to: commands, events and state changes a handler or listener causes continue it. */
+export interface ChainInfo {
+    readonly chainId: string;
+    /**
+     * 1 for anything started outside a handler or listener; one more per step. Past 8, commands fail (`loop`),
+     * events are dropped and state changes run no callbacks. 0 for changes Drift Beacon makes itself (a plugin
+     * stopping or being replaced).
+     */
+    readonly depth: number;
+}
+export interface CommandMeta extends ChainInfo {
+    readonly caller: CommandCaller;
+    /** When the caller stops waiting (epoch milliseconds). */
+    readonly deadline: number;
+    /** Aborts at the deadline: pass it to `fetch` and the like. */
+    readonly signal: AbortSignal;
+}
+/** Handles a command: `input` has the declared fields (`{}` when it declares none); the result is the command's output. */
+export type CommandHandler<K extends CommandName = CommandName> = (input: Commands[K]["input"], meta: CommandMeta) => undefined extends Commands[K]["output"] ? unknown : Commands[K]["output"] | Promise<Commands[K]["output"]>;
+export interface CommandsApi {
+    /** Handle a command declared in manifest.json `provides.commands`. One handler per command; throws `invalid` otherwise. */
+    handle<K extends CommandName>(name: K, handler: CommandHandler<K>): Unsubscribe;
+}
+export interface EventsApi {
+    /**
+     * Send a declared event (manifest.json `provides.events`) to the plugins that use this one, and to this plugin
+     * itself. Throws `invalid` for an undeclared event or a payload that doesn't match its schema (or is over 64 KiB).
+     */
+    emit<K extends EventName>(name: K, ...payload: undefined extends Events[K] ? [payload?: Events[K]] : [payload: Events[K]]): void;
+}
+/** The state this plugin publishes to the plugins that use it (manifest.json `provides.state`). Kept in memory while it runs. */
+export interface StateApi {
+    get<K extends StateKey>(key: K): States[K] | undefined;
+    keys(): readonly StateKey[];
+    /**
+     * Publish a value (`undefined` removes it). Throws `invalid` for an undeclared key, a value that doesn't match
+     * its schema, over 64 KiB, or over 256 KiB of state in all.
+     */
+    set<K extends StateKey>(key: K, value: States[K] | undefined): void;
+}
+/** Another plugin's state, with the chain of the change that caused each callback. */
+export interface MainPeerStateApi extends PeerStateApi {
+    onChange(callback: (key: string, value: unknown, meta: ChainInfo) => void | Promise<void>): Unsubscribe;
+}
+export interface MainPluginPeer extends PluginPeer {
+    readonly state: MainPeerStateApi;
+    /**
+     * Called for each of its events with this name. Commands, events and state changes the callback causes continue
+     * its chain. A throw, or a rejection of the promise it returns, stops the instance.
+     */
+    onEvent(name: string, callback: (payload: unknown, meta: ChainInfo) => void | Promise<void>): Unsubscribe;
+}
+export interface MainPluginsApi extends PluginsApi {
+    get(id: string): MainPluginPeer;
+    readonly self: MainPluginPeer;
+}
 /** Everything a plugin's main code can use. One `ctx` per instance: a plugin for one user in one workspace. */
 export interface MainContext {
     readonly plugin: PluginInfo;
@@ -66,6 +154,14 @@ export interface MainContext {
     readonly storage: StorageApi;
     readonly mqtt: MqttApi;
     readonly routes: RoutesApi;
+    /** The commands this plugin provides to other plugins, its UI and integrations. */
+    readonly commands: CommandsApi;
+    /** The events this plugin emits to the plugins that use it. */
+    readonly events: EventsApi;
+    /** The state this plugin publishes to the plugins that use it. */
+    readonly state: StateApi;
+    /** The plugins this one uses, and itself. */
+    readonly plugins: MainPluginsApi;
     readonly log: LogApi;
     /**
      * Run when the instance stops: disabled, reconfigured, updated or shut down. `ctx` still works
@@ -89,4 +185,5 @@ export interface PluginDefinition {
  * ```
  */
 export declare function definePlugin(definition: PluginDefinition): PluginDefinition;
+export {};
 //# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -1,14 +1,3 @@
-/**
- * Define a plugin's main code. Export the result as the module's default export:
- *
- * ```ts
- * export default definePlugin({
- *   onStart(ctx) {
- *     ctx.mqtt.subscribe(ctx.config.mqttTopic, (message) => ctx.log.info(message.payload));
- *   },
- * });
- * ```
- */
 export function definePlugin(definition) {
     return definition;
 }

package/dist/pack.js

@@ -6,10 +6,6 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-/**
- * Release packaging. `packDirectory` zips a finished package folder (`dbplugin pack` and the server's
- * `plugin:install`); `pack` typechecks a plugin package, builds it fresh into a temp folder and packs that.
- */
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { lstat, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
@@ -20,10 +16,6 @@ import { pathToFileURL } from "node:url";
 import { strToU8, zipSync } from "fflate";
 import { PACKAGE_JSON, PACKAGE_LIMITS, REQUIRED_FILES } from "./internal/package-layout.js";
 import { loadManifest, prepare } from "./prepare.js";
-/**
- * Zip the package in `dir` into `<outDir>/<id>.zip`: its manifest, a generated `package.json`, and `main/**`
- * and `ui/**`. Anything else in `dir` (the dev marker, its `package.json`) is left out. Never runs plugin code.
- */
 export async function packDirectory(dir, outDir) {
     const source = path.resolve(dir);
     const { manifest, bytes: manifestBytes } = loadManifest(source);
@@ -87,12 +79,6 @@ export async function packDirectory(dir, outDir) {
     await writeFile(archivePath, archive);
     return { id: manifest.id, version: manifest.version, tag: `${manifest.id}-${manifest.version}`, asset, archivePath };
 }
-/**
- * Build a release of the plugin package at `root`: prepare, typecheck main and UI with the package's own
- * TypeScript, `vite build` into a fresh temp folder with the package's own Vite, then `packDirectory`. The
- * package's `dist/` is never read or written. Everything printed meanwhile goes to stderr, so a caller's
- * stdout carries only the result.
- */
 export async function pack(root, options = {}) {
     const pkg = path.resolve(root);
     const write = process.stdout.write;
@@ -101,19 +87,17 @@ export async function pack(root, options = {}) {
     try {
         prepare(pkg, { strict: true });
         const require = createRequire(path.join(pkg, "package.json"));
-        // Found through its package.json `bin`: TypeScript 7 doesn't export `typescript/bin/tsc`.
         const typescript = require.resolve("typescript/package.json");
         const { bin } = JSON.parse(await readFile(typescript, "utf8"));
         const tsc = path.join(path.dirname(typescript), bin.tsc);
-        for (const project of ["tsconfig.main.json", "tsconfig.ui.json"]) {
-            const result = spawnSync(process.execPath, [tsc, "-p", path.join(".drift-beacon", project)], {
-                cwd: pkg,
-                stdio: ["ignore", 2, 2],
-            });
+        for (const part of ["main", "ui"]) {
+            const authored = `${part}/tsconfig.json`;
+            const project = existsSync(path.join(pkg, authored)) ? authored : `.drift-beacon/tsconfig.${part}.json`;
+            const result = spawnSync(process.execPath, [tsc, "-p", project], { cwd: pkg, stdio: ["ignore", 2, 2] });
             if (result.error)
                 throw result.error;
             if (result.status !== 0)
-                throw new Error(`Type errors (.drift-beacon/${project}); nothing was packed`);
+                throw new Error(`Type errors (${project}); nothing was packed`);
         }
         temp = await mkdtemp(path.join(tmpdir(), "dbplugin-pack-"));
         const vite = await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("vite")).href));

package/dist/prepare.js

@@ -1,8 +1,3 @@
-/**
- * Writes a plugin package's generated `.drift-beacon/` folder: `config.d.ts` (the `ctx.config` types from
- * manifest.json), the main and UI tsconfigs, and a `.gitignore` that ignores the folder itself. Also reads
- * and checks manifests for `driftBeacon()` and `dbplugin pack` (`loadManifest`).
- */
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { checkApiCompatibility } from "./internal/compatibility.js";
@@ -22,7 +17,6 @@ const COMPILER_OPTIONS = {
     noFallthroughCasesInSwitch: true,
     noUncheckedSideEffectImports: true,
 };
-// Explicit `types` keep UI typings (React, three.js) out of main; `vite/client` allows CSS and asset imports in the UI.
 const TSCONFIG_MAIN = {
     compilerOptions: { ...COMPILER_OPTIONS, lib: ["ES2023"], types: ["node"] },
     include: ["../main/src", "../vite.config.ts", "./config.d.ts"],
@@ -52,16 +46,11 @@ export function prepare(root, { strict }) {
     const out = path.join(root, ".drift-beacon");
     mkdirSync(out, { recursive: true });
     writeIfChanged(path.join(out, ".gitignore"), "*\n");
-    writeIfChanged(path.join(out, "config.d.ts"), configTypes(manifest.configuration));
+    writeIfChanged(path.join(out, "config.d.ts"), configTypes(manifest));
     writeIfChanged(path.join(out, "tsconfig.main.json"), `${JSON.stringify(TSCONFIG_MAIN, null, 2)}\n`);
     writeIfChanged(path.join(out, "tsconfig.ui.json"), `${JSON.stringify(TSCONFIG_UI, null, 2)}\n`);
     return loaded;
 }
-/**
- * `<root>/manifest.json`, the one read of a manifest in the SDK (dev, build, prepare and pack): a regular
- * file within the package limit, valid, and for an `apiVersion` this SDK runs (the server's check). The
- * error names the file.
- */
 export function loadManifest(root) {
     const file = path.join(root, "manifest.json");
     let manifest;
@@ -85,35 +74,73 @@ export function loadManifest(root) {
         throw new Error(`${file}: ${compatibility.message}`);
     return { manifest, bytes };
 }
-/**
- * Augments the SDK's `PluginConfig`. Mirrors the server's config validation: a setting can be missing
- * unless it is required or has a default. The type-only import makes this a module, so `declare module`
- * augments instead of declaring an ambient module, and it loads the SDK entry into every program: the UI
- * imports only `@drift-beacon/plugin/ui`, and an augmentation of a module the program never loads has no effect.
- */
-function configTypes(configuration) {
+function configTypes(manifest) {
     const lines = [
         "// Generated by dbplugin prepare from manifest.json. Do not edit.",
         'import type {} from "@drift-beacon/plugin";',
         'declare module "@drift-beacon/plugin" {',
         "  interface PluginConfig {",
     ];
-    for (const item of configuration) {
-        const doc = [item.title, item.description].filter(Boolean).join(": ").replaceAll("*/", "*\\/");
+    const member = (title, description, name, type) => {
+        const doc = docComment(title, description);
         if (doc)
-            lines.push(`    /** ${doc} */`);
+            lines.push(`    ${doc}`);
+        lines.push(`    ${name}: ${type};`);
+    };
+    for (const item of manifest.configuration) {
         const optional = item.required === true || item.default !== undefined ? "" : "?";
-        lines.push(`    ${JSON.stringify(item.name)}${optional}: ${valueType(item)};`);
+        member(item.title, item.description, `${JSON.stringify(item.name)}${optional}`, valueType(item));
     }
-    lines.push("  }", "}", "");
+    lines.push("  }");
+    const { commands = {}, events = {}, state = {} } = manifest.provides ?? {};
+    const block = (name, declarations, type) => {
+        if (!manifest.provides)
+            return;
+        lines.push(`  interface ${name} {`);
+        if (Object.keys(declarations).length === 0)
+            lines.push("    readonly [name: string]: never;");
+        for (const [key, declaration] of Object.entries(declarations))
+            member(declaration.title, declaration.description, JSON.stringify(key), type(declaration));
+        lines.push("  }");
+    };
+    block("PluginCommands", commands, ({ input, output }) => {
+        const inputType = input ? tsType(input) : NO_PROPERTIES;
+        return `{ readonly input: ${inputType}; readonly output: ${output ? tsType(output) : "undefined"} }`;
+    });
+    block("PluginEvents", events, ({ payload }) => (payload ? tsType(payload) : "undefined"));
+    block("PluginState", state, ({ schema }) => tsType(schema));
+    lines.push("}", "");
     return lines.join("\n");
 }
+const docComment = (title, description) => {
+    const doc = [title, description].filter(Boolean).join(": ").replaceAll("*/", "*\\/");
+    return doc ? `/** ${doc} */` : "";
+};
+const NO_PROPERTIES = "{ readonly [key: string]: never }";
+const SCALAR_TYPES = { string: "string", number: "number", integer: "number", boolean: "boolean", null: "null" };
+function tsType(schema) {
+    if (schema.enum)
+        return unique(schema.enum.map((value) => JSON.stringify(value)));
+    const types = typeof schema.type === "string" ? [schema.type] : schema.type;
+    return unique(types.map((type) => type === "array"
+        ? `readonly (${schema.items ? tsType(schema.items) : "unknown"})[]`
+        : type === "object"
+            ? objectType(schema)
+            : SCALAR_TYPES[type]));
+}
+function objectType(schema) {
+    const required = new Set(schema.required ?? []);
+    const members = Object.entries(schema.properties ?? {}).map(([name, property]) => `readonly ${JSON.stringify(name)}${required.has(name) ? "" : "?"}: ${tsType(property)}`);
+    if (schema.additionalProperties === true)
+        members.push("readonly [key: string]: unknown");
+    return members.length === 0 ? NO_PROPERTIES : `{ ${members.join("; ")} }`;
+}
+const unique = (types) => [...new Set(types)].join(" | ");
 const valueType = (item) => item.type !== "dropdown"
     ? item.type
     : item.data.length === 0
         ? "string"
         : [...new Set(item.data.map((option) => JSON.stringify(option.value)))].join(" | ");
-/** Leaves the file (and its mtime) alone when it already has `content`, so editors and watchers stay quiet. */
 function writeIfChanged(file, content) {
     if (existsSync(file) && readFileSync(file, "utf8") === content)
         return;

package/dist/types.d.ts

@@ -182,12 +182,67 @@ export interface SessionsApi {
 export interface StorageApi {
     get<T = unknown>(key: string): T | undefined;
     keys(): readonly string[];
-    /** Applies locally at once and resolves when the server has stored it. */
+    /**
+     * Applies locally at once and resolves when Drift Beacon has accepted the write. `undefined` removes the key;
+     * a value that isn't JSON-compatible rejects with `invalid`.
+     */
     set(key: string, value: unknown): Promise<void>;
+    /** Applies locally at once and resolves when Drift Beacon has accepted the removal. */
     remove(key: string): Promise<void>;
     /** Called for changes made anywhere else: main code, a UI or another device. */
     onChange(callback: (key: string, value: unknown) => void): Unsubscribe;
 }
-/** Error codes on rejected operations (`error.code`). */
-export type PluginErrorCode = "unsupported" | "invalid" | "not-found" | "unavailable" | "stopped" | "failed";
+/**
+ * Error codes on rejected operations (`error.code`). For a command to another plugin: `unavailable`
+ * means it didn't run (the plugin isn't running here); `timeout` and `stopped` mean it may have run.
+ */
+export type PluginErrorCode = "unsupported" | "invalid" | "not-found" | "unavailable" | "stopped" | "failed" | "not-installed" | "disabled" | "incompatible" | "loop" | "timeout";
+export interface CommandOptions {
+    /** How long to wait, in milliseconds (default 10 s, at most 30 s). Inside a command, at most what its caller has left. */
+    readonly timeoutMs?: number;
+}
+export type PluginStatusState = "running" | "starting" | "unavailable" | "disabled" | "incompatible" | "not-installed";
+/** Whether another plugin can run for this user in this workspace now. */
+export interface PluginStatus {
+    readonly state: PluginStatusState;
+    /** The version it resolved to, when one did. */
+    readonly version?: string;
+    /** Why it isn't running, when known. */
+    readonly reason?: string;
+}
+/** Another plugin's published state (or this plugin's own, as others see it: after a round trip). Values are read-only. */
+export interface PeerStateApi {
+    get<T = unknown>(key: string): T | undefined;
+    keys(): readonly string[];
+    /** A key changed, or was removed (`undefined`). */
+    onChange(callback: (key: string, value: unknown) => void): Unsubscribe;
+}
+/** Another plugin this one uses (listed in manifest.json `uses`), or this plugin itself. */
+export interface PluginPeer {
+    /** Its manifest id. */
+    readonly id: string;
+    /**
+     * The same object until it changes. In main code, updated at once when the plugin starts, finishes starting or
+     * stops, and otherwise within 250 ms; in a UI, within about 250 ms.
+     */
+    readonly status: PluginStatus;
+    /** Called when its `state`, `version` or `reason` changes. */
+    onStatusChange(callback: (status: PluginStatus) => void): Unsubscribe;
+    /**
+     * Run one of its commands (manifest.json `provides.commands`) as this user in this workspace and wait for
+     * the result. Fails fast with `not-installed`, `disabled`, `incompatible` or `unavailable` when it can't run;
+     * `timeout` means it may have run. In main code, the state it published reaches this plugin before this resolves;
+     * in a UI, it (like storage and workspace data the command changed) can arrive just after.
+     */
+    command<T = unknown>(name: string, input?: Readonly<Record<string, unknown>>, options?: CommandOptions): Promise<T>;
+    /** The state it publishes (manifest.json `provides.state`). */
+    readonly state: PeerStateApi;
+}
+/** The plugins this one uses. */
+export interface PluginsApi {
+    /** A plugin listed in manifest.json `uses`, or this plugin's own manifest id. Anything else throws `invalid`. */
+    get(id: string): PluginPeer;
+    /** This plugin itself, as other plugins see it. */
+    readonly self: PluginPeer;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -1,10 +1 @@
-/**
- * Data and APIs shared by plugin main code (server) and UIs (iframe).
- *
- * Workspace data comes as models: an `Activity`, `Category` or `Session` with its fields, links,
- * derived values and actions. Models read the latest snapshot the app sent, synchronously; there is
- * one model per row for the life of a `ctx`, and `model.data` is its plain, frozen row. Later API
- * versions may add fields and new values to string unions such as `trackingType`, so plugins must
- * ignore what they don't recognise.
- */
 export {};

package/dist/ui.d.ts

@@ -1,9 +1,10 @@
-import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
+import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, PluginsApi, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
 export { PluginError } from "./errors.ts";
 export type * from "./types.ts";
 export { API_VERSION } from "./version.ts";
 /** Everything a plugin UI can use. */
 export interface UiContext {
+    /** The installed plugin; it can change while the UI is open, for example to a new version. */
     readonly plugin: PluginInfo;
     readonly user: UserInfo;
     readonly workspace: WorkspaceInfo;
@@ -12,9 +13,17 @@ export interface UiContext {
     readonly activities: ActivitiesApi;
     readonly categories: CategoriesApi;
     readonly sessions: SessionsApi;
-    /** Called after each update from the app (workspace data, config or storage) and after local storage writes. */
+    /**
+     * Called after each update from the app (workspace data, config, storage, or other plugins' status and state) and
+     * after local storage writes.
+     */
     onDataChange(callback: () => void): Unsubscribe;
     readonly storage: StorageApi;
+    /**
+     * Its own plugin and the plugins it uses: their status and published state (within about 250 ms of a change), and
+     * their commands. A command's effects on their state, storage or data can arrive just after it resolves.
+     */
+    readonly plugins: PluginsApi;
 }
 export interface ConnectOptions {
     /** How long to wait for the app to answer. Default 10 seconds. */