@skillcdn/console 0.4.1 → 0.4.2

package/src/cli/plugin-init.ts

@@ -0,0 +1,90 @@
+// `console-plugin init` (docs/specs/plugins.md, "Authoring"): writes a plugin from the template
+// the package ships, the words `__key__`, `__name__` and `__console__` in the template's files and
+// their names replaced. `examples/plugin-hello` in the console's repository is what it writes for
+// the key `hello`, and a test holds the two equal.
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+
+export interface InitOptions {
+  readonly key: string;
+  /** The plugin's name for people, in English. */
+  readonly name: string;
+  /** What the plugin's devDependency on `@skillcdn/console` says: `^<version>` of the command, unless said. */
+  readonly consoleDependency: string;
+}
+
+/** The words the template uses, and what each becomes. */
+export function substitutions(options: InitOptions): readonly [string, string][] {
+  return [
+    ["__key__", options.key],
+    ["__name__", options.name],
+    ["__console__", options.consoleDependency],
+  ];
+}
+
+export function substitute(text: string, options: InitOptions): string {
+  let result = text;
+  for (const [word, value] of substitutions(options)) {
+    result = result.replaceAll(word, value);
+  }
+  return result;
+}
+
+/** A name for people from a key: `leave-requests` is "Leave Requests". */
+export function nameFromKey(key: string): string {
+  return key
+    .split("-")
+    .filter((word) => word.length > 0)
+    .map((word) => `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`)
+    .join(" ");
+}
+
+async function* walk(dir: string): AsyncGenerator<string> {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(path);
+    } else if (entry.isFile()) {
+      yield path;
+    }
+  }
+}
+
+/** The files of the template, as paths relative to it with forward slashes. */
+export async function templateFiles(templateDir: string): Promise<string[]> {
+  const files: string[] = [];
+  for await (const path of walk(templateDir)) {
+    files.push(relative(templateDir, path).split(sep).join("/"));
+  }
+  return files.sort();
+}
+
+/**
+ * Writes the template into `targetDir`, which must not exist or be an empty directory, and
+ * answers the files written, relative to it.
+ */
+export async function writePluginFromTemplate(
+  templateDir: string,
+  targetDir: string,
+  options: InitOptions,
+): Promise<string[]> {
+  const found = await stat(targetDir).catch(() => null);
+  if (found !== null) {
+    if (!found.isDirectory()) {
+      throw new Error(`${targetDir} exists and is not a directory`);
+    }
+    if ((await readdir(targetDir)).length > 0) {
+      throw new Error(`${targetDir} is not empty`);
+    }
+  }
+  const written: string[] = [];
+  for (const file of await templateFiles(templateDir)) {
+    const target = substitute(file, options);
+    const text = await readFile(join(templateDir, file), "utf8");
+    const path = join(targetDir, ...target.split("/"));
+    await mkdir(join(path, ".."), { recursive: true });
+    await writeFile(path, substitute(text, options), "utf8");
+    written.push(target);
+  }
+  return written;
+}

package/src/cli/plugin-main.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import * as z from "zod/mini";
+import { loadServerModule } from "../plugin/load.js";
+import { runPluginCli } from "./plugin-cli.js";
+
+// The `console-plugin` command, the package's second bin: the only place it reads the process.
+// Everything it does is in plugin-cli.ts, which takes what it needs and is what the tests run.
+
+/** The package's own directory, two levels above dist/cli: where the template is. */
+const packageDir = fileURLToPath(new URL("../../", import.meta.url));
+const manifest = z
+  .object({ version: z.string() })
+  .safeParse(createRequire(import.meta.url)("../../package.json"));
+
+process.exitCode = await runPluginCli(process.argv.slice(2), {
+  stdout: (text) => {
+    process.stdout.write(text);
+  },
+  stderr: (text) => {
+    process.stderr.write(text);
+  },
+  cwd: process.cwd(),
+  templateDir: join(packageDir, "template", "plugin"),
+  version: manifest.success ? manifest.data.version : undefined,
+  loadServer: (file) => loadServerModule(file),
+});

package/src/client.ts

@@ -5,6 +5,7 @@ import {
   connectPath,
   personTokensPath,
   personWorkPath,
+  pluginPath,
   projectPath,
   REST_ROUTES,
   restPath,
@@ -52,6 +53,21 @@ import {
   type RestPerson,
   type RestPersonPatch,
   type RestPersonWork,
+  type RestPluginCommandInput,
+  type RestPluginDetail,
+  type RestPluginEnableInput,
+  type RestPluginEvents,
+  type RestPluginFileHandle,
+  type RestPluginGrant,
+  type RestPluginGrantInput,
+  type RestPluginGrants,
+  type RestPluginInvocation,
+  type RestPluginInvokeInput,
+  type RestPluginRecordPage,
+  type RestPluginRecordRead,
+  type RestPluginRecordVersions,
+  type RestPluginSettingsPatch,
+  type RestPlugins,
   type RestProject,
   type RestProjectInput,
   type RestProjectPatch,
@@ -108,6 +124,16 @@ import {
   restPeopleSchema,
   restPersonSchema,
   restPersonWorkSchema,
+  restPluginDetailSchema,
+  restPluginEventsSchema,
+  restPluginFileHandleSchema,
+  restPluginGrantSchema,
+  restPluginGrantsSchema,
+  restPluginInvocationSchema,
+  restPluginRecordPageSchema,
+  restPluginRecordReadSchema,
+  restPluginRecordVersionsSchema,
+  restPluginsSchema,
   restProjectRulesSchema,
   restProjectSchema,
   restProjectsSchema,
@@ -404,6 +430,126 @@ export interface ProjectClient {
   updateGoal(id: string, patch: RestGoalPatch): Promise<RestGoal>;
 }
 
+/** What a read of a plugin's collection is narrowed by (docs/specs/plugins.md, "Records"). */
+export interface RecordFilter {
+  /** Conditions on indexed fields, as `ctx.records().list` takes them. */
+  readonly where?: Readonly<Record<string, unknown>> | undefined;
+  /** A field, with `-` before it for descending. */
+  readonly order?: string | undefined;
+  readonly limit?: number | undefined;
+  /** The cursor the last page answered with. */
+  readonly after?: string | undefined;
+  /** Words to search the collection's search fields for. */
+  readonly q?: string | undefined;
+  /** The key of a project, for the records linked to it. */
+  readonly project?: string | undefined;
+  readonly archived?: boolean | undefined;
+}
+
+/**
+ * The client of one plugin (docs/specs/plugins.md, "REST"): its commands and queries run as the
+ * person the client acts as, its records read within their roles, its skills, its events; and,
+ * for an administrator, enabling, configuring and granting. Every answer is in the console's
+ * generic shapes; what a command or a query itself answers is the plugin's own.
+ */
+export interface PluginClient {
+  readonly key: string;
+  /** The plugin whole: its commands and queries with their arguments, its skills, its settings. */
+  get(signal?: AbortSignal): Promise<RestPluginDetail>;
+  /** Runs a command or a query by the words as typed, which the console parses against the definition. */
+  invoke(input: RestPluginInvokeInput): Promise<RestPluginInvocation>;
+  /** Runs a command with its arguments as JSON, by name, for a page. */
+  command(name: string, input: RestPluginCommandInput): Promise<RestPluginInvocation>;
+  /** Runs a query with its arguments as JSON; the answer is the query's own JSON. */
+  query(
+    name: string,
+    args: Readonly<Record<string, unknown>>,
+    options?: { readonly project?: string | undefined },
+    signal?: AbortSignal,
+  ): Promise<unknown>;
+  /** Where a query's answer is read as bytes, for one that answers a file. */
+  queryUrl(
+    name: string,
+    args: Readonly<Record<string, unknown>>,
+    options?: { readonly project?: string | undefined },
+  ): string;
+  /** Uploads a file for a command, with the `files` capability: the handle a `file` argument takes, good for an hour. */
+  upload(input: FileUpload): Promise<RestPluginFileHandle>;
+  /** A page of a collection's records, as the person may read them. */
+  records(
+    collection: string,
+    filter?: RecordFilter,
+    signal?: AbortSignal,
+  ): Promise<RestPluginRecordPage>;
+  /** One record, or one version of it. */
+  record(
+    collection: string,
+    id: string,
+    version?: number,
+    signal?: AbortSignal,
+  ): Promise<RestPluginRecordRead>;
+  recordVersions(
+    collection: string,
+    id: string,
+    signal?: AbortSignal,
+  ): Promise<RestPluginRecordVersions>;
+  /** Where a record's file is read, by its id. */
+  fileUrl(fileId: string): string;
+  /** The bytes of a record's file, with the name and the type the console says. */
+  readFile(fileId: string, signal?: AbortSignal): Promise<FileRead>;
+  /** Where the frame of a page or a widget is (ADR-0054), on a project when its key is given. */
+  frameUrl(options: {
+    readonly page?: string | undefined;
+    readonly widget?: string | undefined;
+    readonly project?: string | undefined;
+  }): string;
+  /** The events the plugin emitted after number `after`, oldest first: what a frame hears. */
+  pluginEvents(
+    page: { readonly after: number; readonly limit: number },
+    signal?: AbortSignal,
+  ): Promise<RestPluginEvents>;
+  /** Removes everything the console keeps of a disabled plugin, the key named again; for an administrator. */
+  purge(confirm: string): Promise<void>;
+  /** The plugin's skills, a pack of its own read from its package, as a project's five reads. */
+  skills(signal?: AbortSignal): Promise<RestSkills>;
+  skill(path: string, cursor?: string, signal?: AbortSignal): Promise<RestSkillLoad>;
+  skillFile(
+    path: string,
+    page?: { readonly offset?: number | undefined; readonly limit?: number | undefined },
+    signal?: AbortSignal,
+  ): Promise<RestSkillFile>;
+  skillBrowse(
+    page?: {
+      readonly path?: string | undefined;
+      readonly cursor?: string | undefined;
+      readonly limit?: number | undefined;
+    },
+    signal?: AbortSignal,
+  ): Promise<RestSkillBrowse>;
+  skillFind(
+    query: string,
+    options?: {
+      readonly path?: string | undefined;
+      readonly cursor?: string | undefined;
+      readonly limit?: number | undefined;
+    },
+    signal?: AbortSignal,
+  ): Promise<RestSkillFind>;
+  /** The plugin's events, newest first, a page at a time. */
+  events(page?: Page, signal?: AbortSignal): Promise<RestEvents>;
+  /** Enables the plugin, with consent to every capability it asks; for an administrator. */
+  enable(input: RestPluginEnableInput): Promise<RestPluginDetail>;
+  disable(): Promise<RestPluginDetail>;
+  /** Changes the settings' values, without secrets; `null` clears one. */
+  updateSettings(patch: RestPluginSettingsPatch): Promise<RestPluginDetail>;
+  /** Seals a secret for the plugin; it is answered by nothing from then on. */
+  setSecret(name: string, value: string): Promise<void>;
+  removeSecret(name: string): Promise<void>;
+  grants(signal?: AbortSignal): Promise<RestPluginGrants>;
+  grant(input: RestPluginGrantInput): Promise<RestPluginGrant>;
+  revoke(grantId: string): Promise<RestPluginGrant>;
+}
+
 export interface ConsoleClient {
   me(signal?: AbortSignal): Promise<RestMe>;
   /** Gives up the token this client acts with, so that it is good for nothing from now on: what `console logout` does. For a token; a session has none. */
@@ -443,6 +589,10 @@ export interface ConsoleClient {
   createProject(input: RestProjectInput): Promise<RestProject>;
   /** The board of one project. */
   project(key: string): ProjectClient;
+  /** The plugins the asker may know of: the enabled ones, every one for an administrator. */
+  plugins(signal?: AbortSignal): Promise<RestPlugins>;
+  /** One plugin, by its key. */
+  plugin(key: string): PluginClient;
   /** The workspace's own events, the ones about no project, after event number `after`. */
   events(after: number, signal?: AbortSignal): Promise<RestEvents>;
   /** Where a picture from elsewhere is read through the console (ADR-0048), given the https URL that names it. */
@@ -915,6 +1065,147 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
     };
   };
 
+  /** A schema that takes whatever JSON came: a query's own answer. */
+  const anything: Schema<unknown> = { safeParse: (data) => ({ success: true, data }) };
+
+  const pluginClient = (key: string): PluginClient => {
+    const at = (...parts: readonly string[]) => pluginPath(key, ...parts);
+    const skillsQuery = (part: string, params: Record<string, string | undefined>): string =>
+      withQuery(at("skills", part), params);
+    const queryUrl = (
+      name: string,
+      args: Readonly<Record<string, unknown>>,
+      options: { readonly project?: string | undefined } = {},
+    ): string =>
+      withQuery(at("queries", name), { args: JSON.stringify(args), project: options.project });
+    return {
+      key,
+      get: (signal) => request("GET", `${base}${at()}`, undefined, restPluginDetailSchema, signal),
+      invoke: (input) =>
+        request("POST", `${base}${at("invoke")}`, input, restPluginInvocationSchema),
+      command: (name, input) =>
+        request("POST", `${base}${at("commands", name)}`, input, restPluginInvocationSchema),
+      query: (name, args, options = {}, signal) =>
+        request("GET", queryUrl(name, args, options), undefined, anything, signal),
+      queryUrl,
+      upload: (input) =>
+        request("POST", `${base}${at("files")}`, formOf(input), restPluginFileHandleSchema),
+      records: (collection, filter = {}, signal) =>
+        request(
+          "GET",
+          withQuery(at("records", collection), {
+            where: filter.where === undefined ? undefined : JSON.stringify(filter.where),
+            order: filter.order,
+            limit: number(filter.limit),
+            after: filter.after,
+            q: filter.q,
+            project: filter.project,
+            archived: flag(filter.archived),
+          }),
+          undefined,
+          restPluginRecordPageSchema,
+          signal,
+        ),
+      record: (collection, id, version, signal) =>
+        request(
+          "GET",
+          withQuery(at("records", collection, id), { version: number(version) }),
+          undefined,
+          restPluginRecordReadSchema,
+          signal,
+        ),
+      recordVersions: (collection, id, signal) =>
+        request(
+          "GET",
+          `${base}${at("records", collection, id, "versions")}`,
+          undefined,
+          restPluginRecordVersionsSchema,
+          signal,
+        ),
+      fileUrl: (fileId) => `${base}${at("files", fileId)}`,
+      readFile: (fileId, signal) => read(`${base}${at("files", fileId)}`, fileId, signal),
+      frameUrl: (options) =>
+        withQuery(at("frame"), {
+          page: options.page,
+          widget: options.widget,
+          project: options.project,
+        }),
+      pluginEvents: (page, signal) =>
+        request(
+          "GET",
+          withQuery(at("plugin-events"), { after: String(page.after), limit: String(page.limit) }),
+          undefined,
+          restPluginEventsSchema,
+          signal,
+        ),
+      purge: (confirm) => request("POST", `${base}${at("purge")}`, { confirm }, undefined),
+      skills: (signal) =>
+        request("GET", `${base}${at("skills")}`, undefined, restSkillsSchema, signal),
+      skill: (path, cursor, signal) =>
+        request(
+          "GET",
+          skillsQuery("one", { path, cursor }),
+          undefined,
+          restSkillLoadSchema,
+          signal,
+        ),
+      skillFile: (path, page = {}, signal) =>
+        request(
+          "GET",
+          skillsQuery("file", { path, offset: number(page.offset), limit: number(page.limit) }),
+          undefined,
+          restSkillFileSchema,
+          signal,
+        ),
+      skillBrowse: (page = {}, signal) =>
+        request(
+          "GET",
+          skillsQuery("browse", {
+            path: page.path,
+            cursor: page.cursor,
+            limit: number(page.limit),
+          }),
+          undefined,
+          restSkillBrowseSchema,
+          signal,
+        ),
+      skillFind: (query, options = {}, signal) =>
+        request(
+          "GET",
+          skillsQuery("find", {
+            query,
+            path: options.path,
+            cursor: options.cursor,
+            limit: number(options.limit),
+          }),
+          undefined,
+          restSkillFindSchema,
+          signal,
+        ),
+      events: (page = {}, signal) =>
+        request(
+          "GET",
+          withQuery(at("events"), { limit: number(page.limit), offset: number(page.offset) }),
+          undefined,
+          restEventsSchema,
+          signal,
+        ),
+      enable: (input) => request("POST", `${base}${at("enable")}`, input, restPluginDetailSchema),
+      disable: () => request("POST", `${base}${at("disable")}`, undefined, restPluginDetailSchema),
+      updateSettings: (patch) =>
+        request("PATCH", `${base}${at("settings")}`, patch, restPluginDetailSchema),
+      setSecret: (name, value) =>
+        request("PUT", `${base}${at("secrets", name)}`, { value }, undefined),
+      removeSecret: (name) =>
+        request("DELETE", `${base}${at("secrets", name)}`, undefined, undefined),
+      grants: (signal) =>
+        request("GET", `${base}${at("grants")}`, undefined, restPluginGrantsSchema, signal),
+      grant: (input) => request("POST", `${base}${at("grants")}`, input, restPluginGrantSchema),
+      revoke: (grantId) =>
+        request("DELETE", `${base}${at("grants", grantId)}`, undefined, restPluginGrantSchema),
+    };
+  };
+
   return {
     me: (signal) => request("GET", `${base}${REST_ROUTES.me}`, undefined, restMeSchema, signal),
     giveUpToken: () => request("DELETE", `${base}${REST_ROUTES.meToken}`, undefined, undefined),
@@ -972,6 +1263,9 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
     createProject: (input) =>
       request("POST", `${base}${REST_ROUTES.projects}`, input, restProjectSchema),
     project: projectClient,
+    plugins: (signal) =>
+      request("GET", `${base}${REST_ROUTES.plugins}`, undefined, restPluginsSchema, signal),
+    plugin: pluginClient,
     events: (after, signal) =>
       request(
         "GET",

package/src/compat.ts

@@ -113,7 +113,7 @@ export interface ClientPolicy {
  * last changed what the command reads or sends (ADR-0038), whose changelog entry begins with
  * `Breaking:`; `pnpm check` holds it to a version the package has, or is about to have.
  */
-export const CLIENT_POLICY: ClientPolicy = { atLeast: "0.4.1" };
+export const CLIENT_POLICY: ClientPolicy = { atLeast: "0.4.2" };
 
 /**
  * The oldest console this command works with (ADR-0038): raised by the release that last
@@ -122,7 +122,7 @@ export const CLIENT_POLICY: ClientPolicy = { atLeast: "0.4.1" };
  * itself, naming the command to install instead; `pnpm check` holds it as it holds the
  * console's floor.
  */
-export const CONSOLE_AT_LEAST = "0.4.1";
+export const CONSOLE_AT_LEAST = "0.4.2";
 
 /** `common` from `atLeast` on, where that floor is within it; `common` as it is otherwise. */
 function narrowed(common: VersionRange, atLeast: string | undefined): VersionRange {

package/src/components/board.tsx

@@ -80,7 +80,28 @@ const HOLD_MS = 300;
 const HOLD_SLACK = 8;
 /** How near the pointer comes to the board's edge before the board scrolls to show more columns. */
 const EDGE = 48;
-const EDGE_STEP = 12;
+/** How fast the board scrolls, in pixels a second, with the pointer at the edge itself; slower further in. */
+const EDGE_SPEED = 720;
+/** The most a frame counts for, so that a tab that was away does not leap when it is back. */
+const FRAME_AT_MOST_MS = 64;
+
+/**
+ * How far the board scrolls in one frame for a pointer at `x`, the board spanning `left` to
+ * `right` on the screen: nothing away from the edges; towards the edge the pointer is near, the
+ * nearer the faster, and no faster beyond it. Asked every frame while a card is held, not only
+ * when the pointer moves, so that a card held still at the edge carries the board on, as an icon
+ * held at the edge of a phone's screen turns the page. Negative is leftwards.
+ */
+export function edgeScrollOf(x: number, left: number, right: number, elapsedMs: number): number {
+  const ms = Math.min(Math.max(elapsedMs, 0), FRAME_AT_MOST_MS);
+  const depth = (distance: number) => Math.min(1, Math.max(0, (EDGE - distance) / EDGE));
+  const leftward = depth(x - left);
+  const rightward = depth(right - x);
+  if (leftward === 0 && rightward === 0) {
+    return 0;
+  }
+  return ((leftward > rightward ? -leftward : rightward) * EDGE_SPEED * ms) / 1000;
+}
 
 /** The state a column stands for, read off its `data-column`; nothing for a value that is not one. */
 export function columnStateOf(value: string | null | undefined): TaskState | undefined {
@@ -422,10 +443,10 @@ export function Board(props: BoardProps) {
   }, []);
 
   // While a card is held, the pointer is followed over the whole document: the column under it
-  // is marked, the board scrolls when the pointer nears its edge, and the release moves the task.
-  // A finger's hold is timed here, and once the card has come loose the page no longer scrolls
-  // under the finger, nor asks for the menu a long press would otherwise bring up; the click that
-  // follows a drag opens nothing.
+  // is marked, the board scrolls while the pointer is near its edge, moving or still, and the
+  // release moves the task. A finger's hold is timed here, and once the card has come loose the
+  // page no longer scrolls under the finger, nor asks for the menu a long press would otherwise
+  // bring up; the click that follows a drag opens nothing.
   const held = drag !== null;
   useEffect(() => {
     if (!held) {
@@ -435,8 +456,42 @@ export function Board(props: BoardProps) {
       columnStateOf(
         document.elementFromPoint(x, y)?.closest<HTMLElement>("[data-column]")?.dataset.column,
       );
+    // Where the pointer last was, for the frames between its moves.
+    const pointer = { x: current.current?.x ?? 0, y: current.current?.y ?? 0 };
+    // The board is carried on every frame the loose card is near its edge; what a frame's share
+    // comes to short of a whole pixel is kept for the next, since a scroll position holds whole
+    // ones, and the column under the pointer is marked again where the board moved under it.
+    let frame = 0;
+    let at: number | undefined;
+    let rest = 0;
+    const carry = (now: number) => {
+      frame = window.requestAnimationFrame(carry);
+      const elapsed = at === undefined ? 0 : now - at;
+      at = now;
+      const element = board.current;
+      if (element === null || !loose.current) {
+        return;
+      }
+      const rect = element.getBoundingClientRect();
+      const share = edgeScrollOf(pointer.x, rect.left, rect.right, elapsed) + rest;
+      const whole = Math.trunc(share);
+      rest = share - whole;
+      if (whole === 0) {
+        return;
+      }
+      const was = element.scrollLeft;
+      element.scrollLeft = was + whole;
+      if (element.scrollLeft !== was) {
+        const over = columnUnder(pointer.x, pointer.y);
+        setDrag((before) =>
+          before === null || before.over === over ? before : { ...before, over },
+        );
+      }
+    };
     const follow = (event: PointerEvent) => {
       const { clientX: x, clientY: y } = event;
+      pointer.x = x;
+      pointer.y = y;
       setDrag((before) => {
         if (before === null) {
           return before;
@@ -455,15 +510,6 @@ export function Board(props: BoardProps) {
         }
         return { ...before, x, y, moving: true, over: columnUnder(x, y) };
       });
-      const element = board.current;
-      if (element !== null && loose.current) {
-        const rect = element.getBoundingClientRect();
-        if (x < rect.left + EDGE) {
-          element.scrollLeft -= EDGE_STEP;
-        } else if (x > rect.right - EDGE) {
-          element.scrollLeft += EDGE_STEP;
-        }
-      }
     };
     const loosen = () => {
       setDrag((before) => {
@@ -502,6 +548,7 @@ export function Board(props: BoardProps) {
     };
     const quiet = (event: Event) => event.preventDefault();
     const timer = current.current?.hold === true ? window.setTimeout(loosen, HOLD_MS) : undefined;
+    frame = window.requestAnimationFrame(carry);
     window.addEventListener("pointermove", follow);
     window.addEventListener("pointerup", release);
     window.addEventListener("pointercancel", release);
@@ -511,6 +558,7 @@ export function Board(props: BoardProps) {
       if (timer !== undefined) {
         window.clearTimeout(timer);
       }
+      window.cancelAnimationFrame(frame);
       window.removeEventListener("pointermove", follow);
       window.removeEventListener("pointerup", release);
       window.removeEventListener("pointercancel", release);

package/src/components/event-feed.tsx

@@ -10,8 +10,15 @@ import { formatInstant, PersonChip } from "./ui.js";
 // as which agent when through one, and what. It takes its data as props and nothing from the
 // network; the sentence is the language's (ADR-0012).
 
-/** What an event says, without its actor: the words after the name, in the words given. */
+/** What an event says, without its actor: the words after the name, in the words given; a board's event a plugin caused says so (ADR-0052). */
 export function describeEvent(event: RestEvent, words: Messages = en): string {
+  const sentence = sentenceOf(event, words);
+  return event.plugin !== null && !event.kind.startsWith("plugin.")
+    ? `${sentence} ${words.feed.throughPlugin(event.plugin)}`
+    : sentence;
+}
+
+function sentenceOf(event: RestEvent, words: Messages): string {
   const { data } = event;
   const { feed, vocabulary } = words;
   const task =
@@ -34,6 +41,15 @@ export function describeEvent(event: RestEvent, words: Messages = en): string {
   const question = data.question ?? feed.aQuestion;
   const goal = data.title ?? feed.aGoal;
   const category = data.name ?? data.key ?? feed.aCategory;
+  const plugin = event.plugin ?? feed.aPlugin;
+  const grantee =
+    data.everyone === true
+      ? feed.everyone
+      : data.login !== undefined
+        ? data.login
+        : data.key !== undefined
+          ? feed.membersOf(data.name ?? data.key)
+          : feed.someone;
   switch (event.kind) {
     case "person.joined":
       return feed.event.personJoined();
@@ -115,6 +131,31 @@ export function describeEvent(event: RestEvent, words: Messages = en): string {
       return feed.event.documentRestored(page);
     case "document.file_attached":
       return feed.event.fileAttached(data.label ?? feed.aFile, page);
+    case "plugin.enabled":
+      return feed.event.pluginEnabled(plugin);
+    case "plugin.disabled":
+      return feed.event.pluginDisabled(plugin);
+    case "plugin.configured":
+      return feed.event.pluginConfigured(fields, plugin);
+    case "plugin.granted":
+      return feed.event.pluginGranted(data.role ?? feed.role.other, grantee, plugin);
+    case "plugin.revoked":
+      return feed.event.pluginRevoked(data.role ?? feed.role.other, grantee, plugin);
+    case "plugin.upgraded":
+      return feed.event.pluginUpgraded(
+        plugin,
+        data.version === undefined ? feed.something : String(data.version),
+      );
+    case "plugin.command":
+      return feed.event.pluginCommand(
+        data.command ?? feed.something,
+        plugin,
+        feed.outcome[data.outcome ?? ""] ?? data.outcome ?? feed.something,
+      );
+    case "plugin.purged":
+      return feed.event.pluginPurged(plugin);
+    case "plugin.failed":
+      return feed.event.pluginFailed(plugin, data.problem ?? feed.something);
   }
 }