@skillcdn/console 0.4.2 → 0.4.4

package/src/plugin/bridge.ts

@@ -3,8 +3,18 @@
 // frame the console's origin alone. The shapes and their guards, with no DOM in them, so that the
 // page's side and the frame's side read the same words and the tests need no browser.
 
+import { WEEK_STARTS, type WeekStart } from "../vocabulary.js";
+
 export const PLUGIN_BRIDGE_VERSION = 1;
 
+/**
+ * The sizes a widget comes in (ADR-0061): columns and rows of the front page's grid of square
+ * cells, `small` 2×2, `medium` 4×2, `large` 4×4, `wide` 8×2, `full` 8×4. Here, so that a bundle
+ * learns them without the manifest's schema.
+ */
+export const PLUGIN_WIDGET_SIZE_NAMES = ["small", "medium", "large", "wide", "full"] as const;
+export type PluginWidgetSizeName = (typeof PLUGIN_WIDGET_SIZE_NAMES)[number];
+
 /** What the frame may ask the page to perform, each under `/api/v1/plugins/<key>/` and nothing else. */
 export const BRIDGE_METHODS = [
   "command",
@@ -14,6 +24,7 @@ export const BRIDGE_METHODS = [
   "records.versions",
   "files.get",
   "files.put",
+  "people.picture",
 ] as const;
 
 export type BridgeMethod = (typeof BRIDGE_METHODS)[number];
@@ -31,6 +42,17 @@ export interface BridgePerson {
   readonly admin: boolean;
 }
 
+/** The workspace as a page lays itself out for it: what it is called, the languages it writes in, its clock and the day its week begins on. */
+export interface BridgeWorkspace {
+  readonly name: string;
+  readonly languages: readonly string[];
+  readonly timeZone: string;
+  /** The workspace's setting (ADR-0035): `auto` leaves the week to the language of the pages. */
+  readonly weekStart: WeekStart;
+  /** The day a week begins on with the setting applied, for a calendar to start from: 1 for Monday, 7 for Sunday. */
+  readonly firstDay: number;
+}
+
 /** What the page tells the frame once it is ready: who looks, at what, in which words and colours. */
 export interface BridgeInit {
   readonly v: 1;
@@ -38,8 +60,12 @@ export interface BridgeInit {
   readonly plugin: { readonly key: string; readonly version: string };
   readonly page?: string;
   readonly widget?: string;
+  /** The size the widget's frame has (ADR-0059), one of the sizes the manifest declared for it; none for a page. */
+  readonly size?: PluginWidgetSizeName;
   readonly project: { readonly key: string; readonly name: string } | null;
   readonly person: BridgePerson;
+  /** The workspace; none from a console older than this. */
+  readonly workspace?: BridgeWorkspace;
   readonly roles: readonly string[];
   /** What follows the page's key in the address. */
   readonly path: string;
@@ -82,7 +108,20 @@ export interface BridgePath {
   readonly path: string;
 }
 
-export type BridgeToFrame = BridgeInit | BridgeResult | BridgeEvent | BridgeTheme | BridgePath;
+/** The person gave the widget another size (ADR-0059): the frame lays itself out for it. */
+export interface BridgeSize {
+  readonly v: 1;
+  readonly t: "size";
+  readonly size: PluginWidgetSizeName;
+}
+
+export type BridgeToFrame =
+  | BridgeInit
+  | BridgeResult
+  | BridgeEvent
+  | BridgeTheme
+  | BridgePath
+  | BridgeSize;
 
 export interface BridgeReady {
   readonly v: 1;
@@ -127,8 +166,18 @@ export interface BridgeSubscribe {
   readonly kinds: readonly BridgeEventKind[];
 }
 
+/**
+ * The frame has nothing to show: the plugin is off, or the page is not one of its own. The console
+ * serves such a frame a document with no words, and the console's page says so in its own.
+ */
+export interface BridgeUnavailable {
+  readonly v: 1;
+  readonly t: "unavailable";
+}
+
 export type BridgeToPage =
   | BridgeReady
+  | BridgeUnavailable
   | BridgeCall
   | BridgeNavigate
   | BridgeResize
@@ -177,6 +226,21 @@ function isTheme(value: unknown): value is Record<string, string> {
   );
 }
 
+function isWorkspace(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === "string" &&
+    Array.isArray(value.languages) &&
+    value.languages.every((language) => typeof language === "string") &&
+    isLine(value.timeZone, 100) &&
+    (WEEK_STARTS as readonly unknown[]).includes(value.weekStart) &&
+    typeof value.firstDay === "number" &&
+    Number.isInteger(value.firstDay) &&
+    value.firstDay >= 1 &&
+    value.firstDay <= 7
+  );
+}
+
 function isEnvelope(value: unknown): value is Record<string, unknown> & { t: string } {
   return isRecord(value) && value.v === PLUGIN_BRIDGE_VERSION && typeof value.t === "string";
 }
@@ -194,6 +258,8 @@ export function isBridgeToFrame(value: unknown): value is BridgeToFrame {
         isLine(value.plugin.version, 64) &&
         (value.page === undefined || isLine(value.page, 32)) &&
         (value.widget === undefined || isLine(value.widget, 32)) &&
+        (value.size === undefined ||
+          (PLUGIN_WIDGET_SIZE_NAMES as readonly unknown[]).includes(value.size)) &&
         (value.project === null ||
           (isRecord(value.project) &&
             isLine(value.project.key, 64) &&
@@ -204,6 +270,7 @@ export function isBridgeToFrame(value: unknown): value is BridgeToFrame {
         (value.person.name === null || typeof value.person.name === "string") &&
         typeof value.person.language === "string" &&
         typeof value.person.admin === "boolean" &&
+        (value.workspace === undefined || isWorkspace(value.workspace)) &&
         Array.isArray(value.roles) &&
         value.roles.every((role) => typeof role === "string") &&
         typeof value.path === "string" &&
@@ -229,6 +296,8 @@ export function isBridgeToFrame(value: unknown): value is BridgeToFrame {
       return isTheme(value.theme);
     case "path":
       return typeof value.path === "string" && value.path.length <= MAX_BRIDGE_PATH_LENGTH;
+    case "size":
+      return (PLUGIN_WIDGET_SIZE_NAMES as readonly unknown[]).includes(value.size);
     default:
       return false;
   }
@@ -241,6 +310,7 @@ export function isBridgeToPage(value: unknown): value is BridgeToPage {
   }
   switch (value.t) {
     case "ready":
+    case "unavailable":
       return true;
     case "call":
       return (
@@ -307,6 +377,12 @@ export interface BridgeFilesPutParams {
 }
 
 /** What `files.get` answers: the bytes, transferred, with the file's name and type. */
+/** A person's picture, as the page hands it to the frame (ADR-0063). */
+export interface BridgePicture {
+  readonly type: string;
+  readonly bytes: ArrayBuffer;
+}
+
 export interface BridgeFile {
   readonly name: string;
   readonly type: string;

package/src/plugin/capabilities.ts

@@ -19,10 +19,18 @@ export const PLUGIN_CAPABILITIES = [
   "jobs",
   "endpoints",
   "storage:sql",
+  "outbound:webrtc",
 ] as const;
 
 export type PluginCapability = (typeof PLUGIN_CAPABILITIES)[number];
 
+/**
+ * WebRTC on a plugin's pages (ADR-0066). It stands with `outbound:<host>` as a way to the internet,
+ * and it is no host: a connection goes from a person's browser to any address a page names, which
+ * no host could bound, so that consent to a host does not open it, and it opens no host.
+ */
+export const OUTBOUND_WEBRTC: PluginCapability = "outbound:webrtc";
+
 /** The capabilities that carry a parameter: a host to reach, a plugin to call. */
 export const PLUGIN_CAPABILITY_PREFIXES = ["outbound:", "plugins:"] as const;
 
@@ -97,6 +105,10 @@ export const CAPABILITY_WORDS: Readonly<Record<PluginCapability, CapabilityWords
     opens: "a schema and a login role of its own in the console's database",
     reach: "statements up to the timeout, within its schema",
   },
+  "outbound:webrtc": {
+    opens: "WebRTC on its pages: connections from each person's browser to any address",
+    reach: "what its pages are shown, sent anywhere from the person's browser; their address",
+  },
 };
 
 /** True for a capability the catalogue knows, parameter included. */
@@ -137,7 +149,11 @@ export function capabilityWords(capability: string): CapabilityWords | undefined
 
 /** True when the request's host is within what `outbound:<host>` names: the host itself, or a subdomain where the capability starts with `*.`. */
 export function outboundAllows(capability: string, host: string): boolean {
-  if (!capability.startsWith("outbound:") || !isPluginCapability(capability)) {
+  if (
+    !capability.startsWith("outbound:") ||
+    capability === OUTBOUND_WEBRTC ||
+    !isPluginCapability(capability)
+  ) {
     return false;
   }
   const named = capability.slice("outbound:".length);

package/src/plugin/context.ts

@@ -16,6 +16,7 @@ import type {
   RestTaskInput,
   RestTaskPatch,
 } from "../schemas.js";
+import type { WeekStart } from "../vocabulary.js";
 import type { PluginFileHandle } from "./args.js";
 
 /** A schema as the Standard Schema interface spells one: what every build of zod implements, so that a plugin's own copy validates its records. */
@@ -199,6 +200,11 @@ export interface PluginInfo {
   readonly dataVersion: number;
   /** The settings as the administrator set them, by key, without the secrets. */
   readonly settings: Readonly<Record<string, unknown>>;
+  /**
+   * The capabilities the plugin holds: those it requires, and the optional ones an administrator
+   * turned on (ADR-0060), so that it offers what it can do. One it does not hold is refused.
+   */
+  readonly capabilities: readonly string[];
   /** The board project, or none. */
   readonly board: { readonly id: string; readonly key: string } | null;
   /** The projects the plugin is on: all, or their keys. */
@@ -245,6 +251,8 @@ export interface PluginWorkspace {
   readonly name: string;
   readonly languages: readonly string[];
   readonly timeZone: string;
+  /** The day the week begins on (ADR-0035): `auto` leaves it to the language of whoever reads. */
+  readonly weekStart: WeekStart;
   readonly categories: readonly {
     readonly key: string;
     readonly name: string;
@@ -253,11 +261,19 @@ export interface PluginWorkspace {
 }
 
 export interface DecisionAsk {
+  /** In the language of whoever is to answer, as `people.get` says it (ADR-0065). */
   readonly question: string;
   readonly body?: string;
-  readonly options: readonly { readonly label: string }[];
-  /** Who is to answer: a person who may work in the project; the project's owners when left out. */
+  /**
+   * The options, each a label and optionally a key (spelled as a plugin's key is, each once),
+   * which the answered event carries back as `optionKey`, so that the plugin reads the answer
+   * without comparing labels.
+   */
+  readonly options: readonly { readonly label: string; readonly key?: string }[];
+  /** Who is to answer: a person who may work in the project; the administrator who enabled the plugin when left out. */
   readonly deciderId?: string;
+  /** Several to answer (ADR-0057), in place of `deciderId`: any of them may, and the first answer ends it; up to MAX_DECIDERS. */
+  readonly deciderIds?: readonly string[];
   readonly taskId?: string;
   /** The record the decision is for, by which the plugin maps the answer back. */
   readonly about: { readonly collection: string; readonly id: string };
@@ -269,6 +285,12 @@ export interface PluginConsole {
   people: {
     list(options?: { readonly q?: string }): Promise<readonly RestPerson[]>;
     get(id: string): Promise<RestPerson | null>;
+    /**
+     * The active people a role of the plugin was granted to, by name, through a project or with
+     * everyone, and everyone for `defaultRole` (ADR-0063). An administrator holds every role, and
+     * is listed only where they were granted it.
+     */
+    granted(role: string): Promise<readonly RestPerson[]>;
   };
   projects: {
     list(): Promise<readonly RestProject[]>;

package/src/plugin/define.ts

@@ -714,6 +714,7 @@ export function descriptionProblems(
   manifest: {
     readonly roles: Readonly<Record<string, unknown>>;
     readonly capabilities: readonly string[];
+    readonly optionalCapabilities?: readonly string[] | undefined;
     readonly settings: readonly { readonly key: string; readonly type: string }[];
     readonly dataVersion: number;
   },
@@ -729,7 +730,9 @@ export function descriptionProblems(
     }
   };
   const needs = (where: string, capability: string) => {
-    if (!manifest.capabilities.includes(capability)) {
+    if (
+      ![...manifest.capabilities, ...(manifest.optionalCapabilities ?? [])].includes(capability)
+    ) {
       problems.push(
         `${where} needs the capability ${capability}, which the manifest does not declare`,
       );

package/src/plugin/limits.ts

@@ -8,11 +8,14 @@ export const MAX_PLUGIN_DESCRIPTION_LENGTH = 200;
 export const MAX_PLUGIN_AGENT_NOTE_LENGTH = 200;
 /** A plugin's key, a role's, a page's, a widget's, a setting's, a collection's, a command's: `^[a-z][a-z0-9-]{1,31}$`. */
 export const MAX_PLUGIN_KEY_LENGTH = 32;
-/** How many roles, settings, pages and widgets one manifest declares. */
+/** How many roles, settings, groups of settings, pages and widgets one manifest declares. */
 export const MAX_PLUGIN_ROLES = 10;
 export const MAX_PLUGIN_SETTINGS = 50;
+export const MAX_PLUGIN_SETTING_GROUPS = 10;
 export const MAX_PLUGIN_PAGES = 12;
 export const MAX_PLUGIN_WIDGETS = 4;
+/** How many capabilities a plugin asks, the optional ones counted. */
+export const MAX_PLUGIN_CAPABILITIES = 50;
 /** How many collections, commands and queries together, endpoints, and indexes of one collection a server module defines. */
 export const MAX_PLUGIN_COLLECTIONS = 50;
 export const MAX_PLUGIN_OPERATIONS = 100;
@@ -64,7 +67,7 @@ export const MAX_PLUGIN_SQL_ROWS = 10_000;
 export const PLUGIN_SQL_CONNECTIONS = 4;
 /** The memory a plugin's thread may hold, in megabytes, where the deployment says nothing. */
 export const DEFAULT_PLUGIN_MEMORY_MB = 256;
-/** How tall a widget's frame may grow, in pixels. */
+/** How tall a widget's frame grew, in pixels, before a widget had sizes of a family (ADR-0059); kept for the readers of before, read by nothing. */
 export const MAX_PLUGIN_WIDGET_HEIGHT = 480;
 /** How many retries a hook gets before its event is skipped with a `plugin.failed` event. */
 export const PLUGIN_HOOK_RETRIES = 5;

package/src/plugin/manifest.ts

@@ -8,14 +8,17 @@ import {
   MAX_PROJECT_NAME_LENGTH,
 } from "../limits.js";
 import { hasForbiddenCodePoint } from "../text.js";
+import { PLUGIN_WIDGET_SIZE_NAMES, type PluginWidgetSizeName } from "./bridge.js";
 import { isPluginCapability } from "./capabilities.js";
 import {
   MAX_PLUGIN_AGENT_NOTE_LENGTH,
+  MAX_PLUGIN_CAPABILITIES,
   MAX_PLUGIN_DESCRIPTION_LENGTH,
   MAX_PLUGIN_NAME_LENGTH,
   MAX_PLUGIN_OPTIONS,
   MAX_PLUGIN_PAGES,
   MAX_PLUGIN_ROLES,
+  MAX_PLUGIN_SETTING_GROUPS,
   MAX_PLUGIN_SETTINGS,
   MAX_PLUGIN_WIDGETS,
 } from "./limits.js";
@@ -135,6 +138,7 @@ export const PLUGIN_SETTING_TYPES = [
   "boolean",
   "enum",
   "day",
+  "time",
   "person",
   "project",
   "secret",
@@ -149,14 +153,68 @@ export type PluginPageLevel = (typeof PLUGIN_PAGE_LEVELS)[number];
 export const PLUGIN_WIDGET_PLACES = ["home:top", "home:bottom"] as const;
 export type PluginWidgetPlace = (typeof PLUGIN_WIDGET_PLACES)[number];
 
+/** The sizes of before (ADR-0054), each read as one of the family (ADR-0059): a third as small, a half as medium, the width as wide. */
 export const PLUGIN_WIDGET_SIZES = ["third", "half", "full"] as const;
 export type PluginWidgetSize = (typeof PLUGIN_WIDGET_SIZES)[number];
 
+export { PLUGIN_WIDGET_SIZE_NAMES, type PluginWidgetSizeName };
+
+const LEGACY_WIDGET_SIZES: Readonly<Record<PluginWidgetSize, PluginWidgetSizeName>> = {
+  third: "small",
+  half: "medium",
+  full: "wide",
+};
+
+/** The columns and the rows of the front page's grid of square cells each size takes (ADR-0061). */
+export const PLUGIN_WIDGET_SIZE_CELLS: Readonly<
+  Record<PluginWidgetSizeName, { readonly columns: number; readonly rows: number }>
+> = {
+  small: { columns: 2, rows: 2 },
+  medium: { columns: 4, rows: 2 },
+  large: { columns: 4, rows: 4 },
+  wide: { columns: 8, rows: 2 },
+  full: { columns: 8, rows: 4 },
+};
+
+/** The most cells across a phone's grid has; a widget comes in a size that fits it (ADR-0062). */
+const PLUGIN_WIDGET_PHONE_COLUMNS = 4;
+
+/** Whether a size fits a phone's grid. */
+const fitsPhone = (size: PluginWidgetSizeName): boolean =>
+  PLUGIN_WIDGET_SIZE_CELLS[size].columns <= PLUGIN_WIDGET_PHONE_COLUMNS;
+
+/**
+ * The sizes a widget comes in and the one it starts at: `sizes` and `defaultSize` where the
+ * manifest declares them, else the one size of before read as one of the family, with a size a
+ * phone can hold beside it where that one is too wide.
+ */
+export function widgetSizesOf(widget: {
+  readonly size?: PluginWidgetSize | undefined;
+  readonly sizes?: readonly PluginWidgetSizeName[] | undefined;
+  readonly defaultSize?: PluginWidgetSizeName | undefined;
+}): {
+  readonly sizes: readonly PluginWidgetSizeName[];
+  readonly defaultSize: PluginWidgetSizeName;
+} {
+  if (widget.sizes !== undefined && widget.sizes.length > 0) {
+    return { sizes: widget.sizes, defaultSize: widget.defaultSize ?? widget.sizes[0] ?? "small" };
+  }
+  const one = LEGACY_WIDGET_SIZES[widget.size ?? "third"];
+  return { sizes: fitsPhone(one) ? [one] : ["medium", one], defaultSize: one };
+}
+
+/** The size of before nearest to one of the family, for a reader of before. */
+export function legacyWidgetSize(size: PluginWidgetSizeName): PluginWidgetSize {
+  return size === "small" ? "third" : size === "medium" || size === "large" ? "half" : "full";
+}
+
 export const PLUGIN_BOARD_NEEDS = ["required", "optional", "none"] as const;
 export type PluginBoardNeeds = (typeof PLUGIN_BOARD_NEEDS)[number];
 
 const LANGUAGE_TAG = /^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
 const DAY = /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$/;
+/** A time of day as `HH:MM`, read in the workspace's time zone. */
+export const TIME_OF_DAY = /^(?:[01]\d|2[0-3]):[0-5]\d$/;
 /** A path within the package: relative, forward slashes, never climbing out. */
 const PACKAGE_PATH = /^(?!\/)(?!\.\.(?:\/|$))(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
 /** A semver range as npm spells one, loosely: the console compares versions, the registry resolves. */
@@ -230,6 +288,8 @@ const pluginSettingSchema = z
       z.array(settingOption).check(z.minLength(1), z.maxLength(MAX_PLUGIN_OPTIONS)),
     ),
     of: z.optional(settingItemType),
+    /** The group of `settingGroups` the setting is shown under; left out, above every group. */
+    group: z.optional(key),
   })
   .check(
     z.superRefine((setting, ctx) => {
@@ -241,6 +301,15 @@ const pluginSettingSchema = z
 
 export type PluginSetting = z.infer<typeof pluginSettingSchema>;
 
+/** A group the settings form is divided into: a panel with a name and, where given, a word under it. */
+const pluginSettingGroupSchema = z.strictObject({
+  key,
+  name: localized(MAX_PLUGIN_NAME_LENGTH),
+  description: z.optional(localized(MAX_PLUGIN_DESCRIPTION_LENGTH)),
+});
+
+export type PluginSettingGroup = z.infer<typeof pluginSettingGroupSchema>;
+
 /** True when `value` is what a setting of `type` holds, `options` being the values of an `enum`. */
 function fitsSettingType(
   type: Exclude<PluginSettingType, "secret" | "list">,
@@ -259,6 +328,8 @@ function fitsSettingType(
       return typeof value === "string" && (options ?? []).includes(value);
     case "day":
       return typeof value === "string" && DAY.test(value);
+    case "time":
+      return typeof value === "string" && TIME_OF_DAY.test(value);
     case "person":
     case "project":
       return false;
@@ -334,16 +405,60 @@ const pluginPageSchema = z.strictObject({
 
 export type PluginPage = z.infer<typeof pluginPageSchema>;
 
-const pluginWidgetSchema = z.strictObject({
-  key,
-  name: localized(MAX_PLUGIN_NAME_LENGTH),
-  place: z.enum(PLUGIN_WIDGET_PLACES),
-  size: z.enum(PLUGIN_WIDGET_SIZES),
-  roles: z.optional(roleList),
-});
+const pluginWidgetSchema = z
+  .strictObject({
+    key,
+    name: localized(MAX_PLUGIN_NAME_LENGTH),
+    place: z.enum(PLUGIN_WIDGET_PLACES),
+    /** The one size of before; `sizes` says it better. */
+    size: z.optional(z.enum(PLUGIN_WIDGET_SIZES)),
+    /** The sizes the widget comes in (ADR-0059), each once; the person picks among them. */
+    sizes: z.optional(
+      z.array(z.enum(PLUGIN_WIDGET_SIZE_NAMES)).check(z.minLength(1), z.maxLength(5)),
+    ),
+    /** The size it starts at, one of `sizes`; the first of them when left out. */
+    defaultSize: z.optional(z.enum(PLUGIN_WIDGET_SIZE_NAMES)),
+    roles: z.optional(roleList),
+  })
+  .check(
+    z.superRefine((widget, ctx) => {
+      if (widget.size === undefined && widget.sizes === undefined) {
+        ctx.addIssue({
+          code: "custom",
+          message: "needs sizes, the sizes it comes in",
+          input: widget,
+        });
+      }
+      if (widget.sizes !== undefined && new Set(widget.sizes).size !== widget.sizes.length) {
+        ctx.addIssue({ code: "custom", message: "sizes names a size twice", input: widget });
+      }
+      if (widget.sizes !== undefined && !widget.sizes.some(fitsPhone)) {
+        ctx.addIssue({
+          code: "custom",
+          message: "sizes needs small, medium or large: a phone's grid is four cells across",
+          input: widget,
+        });
+      }
+      if (widget.defaultSize !== undefined && !(widget.sizes ?? []).includes(widget.defaultSize)) {
+        ctx.addIssue({
+          code: "custom",
+          message: "defaultSize is not one of sizes",
+          input: widget,
+        });
+      }
+    }),
+  );
 
 export type PluginWidget = z.infer<typeof pluginWidgetSchema>;
 
+/** Every capability a plugin asks: those it needs, then those it can go without (ADR-0060). */
+export function capabilitiesAsked(manifest: {
+  readonly capabilities: readonly string[];
+  readonly optionalCapabilities?: readonly string[] | undefined;
+}): string[] {
+  return [...manifest.capabilities, ...(manifest.optionalCapabilities ?? [])];
+}
+
 const pluginMenuSchema = z
   .strictObject({
     group: key,
@@ -409,12 +524,19 @@ export const pluginManifestSchema = z
     description: localized(MAX_PLUGIN_DESCRIPTION_LENGTH),
     agentNote: z.optional(localized(MAX_PLUGIN_AGENT_NOTE_LENGTH)),
     pluginApi: z.int().check(z.positive()),
+    /** The consoles the plugin runs on, as a semver range of the console's version; left out, any console that serves `pluginApi`. */
+    console: z.optional(z.string().check(z.regex(SEMVER_RANGE, "is a semver range"))),
     server: packagePath,
     web: z.optional(packagePath),
     skills: z.optional(packagePath),
     migrations: z.optional(packagePath),
     capabilities: z._default(
-      z.array(z.string().check(z.maxLength(300))).check(z.maxLength(50)),
+      z.array(z.string().check(z.maxLength(300))).check(z.maxLength(MAX_PLUGIN_CAPABILITIES)),
+      [],
+    ),
+    /** What the plugin can go without (ADR-0060): an administrator turns each on, or leaves it off. */
+    optionalCapabilities: z._default(
+      z.array(z.string().check(z.maxLength(300))).check(z.maxLength(MAX_PLUGIN_CAPABILITIES)),
       [],
     ),
     roles: z._default(z.record(key, pluginRoleSchema), {}),
@@ -425,6 +547,10 @@ export const pluginManifestSchema = z
     ),
     board: z._default(pluginBoardSchema, { needs: "none" }),
     settings: z._default(z.array(pluginSettingSchema).check(z.maxLength(MAX_PLUGIN_SETTINGS)), []),
+    settingGroups: z._default(
+      z.array(pluginSettingGroupSchema).check(z.maxLength(MAX_PLUGIN_SETTING_GROUPS)),
+      [],
+    ),
     menu: z.optional(pluginMenuSchema),
     pages: z._default(z.array(pluginPageSchema).check(z.maxLength(MAX_PLUGIN_PAGES)), []),
     widgets: z._default(z.array(pluginWidgetSchema).check(z.maxLength(MAX_PLUGIN_WIDGETS)), []),
@@ -465,12 +591,21 @@ function manifestProblems(
   if (manifest.defaultRole !== undefined && !roles.includes(manifest.defaultRole)) {
     problems.push(`defaultRole ${manifest.defaultRole} is not a declared role`);
   }
-  for (const capability of manifest.capabilities) {
+  const asked = capabilitiesAsked(manifest);
+  if (asked.length > MAX_PLUGIN_CAPABILITIES) {
+    problems.push(`capabilities: at most ${MAX_PLUGIN_CAPABILITIES}, the optional ones counted`);
+  }
+  if (manifest.optionalCapabilities.includes("storage:sql")) {
+    problems.push(
+      "optionalCapabilities: storage:sql cannot be optional: its schema is made when the plugin is enabled",
+    );
+  }
+  for (const capability of asked) {
     if (!isPluginCapability(capability)) {
       problems.push(`capabilities: ${capability} is not one the console knows`);
     }
   }
-  for (const capability of duplicates(manifest.capabilities)) {
+  for (const capability of duplicates(asked)) {
     problems.push(`capabilities: ${capability} is declared twice`);
   }
   const undeclared = (where: string, named: readonly string[] | undefined) => {
@@ -490,11 +625,20 @@ function manifestProblems(
     ["pages", manifest.pages.map((page) => page.key)],
     ["widgets", manifest.widgets.map((widget) => widget.key)],
     ["settings", manifest.settings.map((setting) => setting.key)],
+    ["settingGroups", manifest.settingGroups.map((group) => group.key)],
   ] as const) {
     for (const twice of duplicates(keys)) {
       problems.push(`${what}: ${twice} is declared twice`);
     }
   }
+  const groups = manifest.settingGroups.map((group) => group.key);
+  for (const setting of manifest.settings) {
+    if (setting.group !== undefined && !groups.includes(setting.group)) {
+      problems.push(
+        `settings.${setting.key} names the group ${setting.group}, which settingGroups does not declare`,
+      );
+    }
+  }
   if ((manifest.pages.length > 0 || manifest.widgets.length > 0) && manifest.web === undefined) {
     problems.push("pages and widgets need web, the directory of the bundle");
   }

package/src/plugin/rest-schemas.ts

@@ -21,6 +21,7 @@ import {
   PLUGIN_PAGE_LEVELS,
   PLUGIN_SETTING_TYPES,
   PLUGIN_WIDGET_PLACES,
+  PLUGIN_WIDGET_SIZE_NAMES,
   PLUGIN_WIDGET_SIZES,
   SETTING_KEY_PATTERN,
 } from "./manifest.js";
@@ -91,7 +92,11 @@ export const restPluginWidgetSchema = z.object({
   key: z.string(),
   name: localized,
   place: z.enum(PLUGIN_WIDGET_PLACES),
+  /** The size of before nearest to the one it starts at, for a reader of before. */
   size: z.enum(PLUGIN_WIDGET_SIZES),
+  /** The sizes the widget comes in (ADR-0059) and the one it starts at; answered from 0.4.4 and read as optional. */
+  sizes: z.optional(z.array(z.enum(PLUGIN_WIDGET_SIZE_NAMES))),
+  defaultSize: z.optional(z.enum(PLUGIN_WIDGET_SIZE_NAMES)),
 });
 export type RestPluginWidget = z.infer<typeof restPluginWidgetSchema>;
 
@@ -103,6 +108,13 @@ export const restPluginSchema = z.object({
   /** The sentence agents read with the rules, or `null` for the description. */
   agentNote: z.nullable(localized),
   version: z.string(),
+  /**
+   * The consoles the plugin declares it runs on, a semver range of the console's version, or
+   * `null` where the manifest names none; a console outside it fails the plugin with the reason
+   * in `problems`. Answered from 0.4.4 and read as optional, so that a console built on this
+   * package still reads an older console's answer.
+   */
+  console: z.optional(z.nullable(z.string())),
   state: z.enum(PLUGIN_STATES),
   /** Why the plugin failed, or waits for consent; empty otherwise. */
   problems: z.array(z.string()),
@@ -121,6 +133,8 @@ export const restPluginSchema = z.object({
   boardNeeds: z.enum(PLUGIN_BOARD_NEEDS),
   /** What the plugin asks, and what was consented to; `consent` is `null` to a member. */
   capabilities: z.array(z.string()),
+  /** What it can go without (ADR-0060), an administrator's to turn on; a console older than them names none. */
+  optionalCapabilities: z.optional(z.array(z.string())),
   consent: z.nullable(z.array(z.string())),
   /** The projects the plugin is on: all, their keys, or `null` to a member. */
   projects: z.nullable(z.union([z.literal("all"), z.array(z.string())])),
@@ -149,6 +163,8 @@ export const restPluginSettingSchema = z.object({
   max: z.nullable(z.number()),
   options: z.nullable(z.array(z.object({ value: z.string(), name: localized }))),
   of: z.nullable(z.string()),
+  /** The group the setting is shown under, or `null` for above every group; answered from 0.4.4 and read as optional. */
+  group: z.optional(z.nullable(z.string())),
   /** Whether a value is set; a secret's value is never here. */
   set: z.boolean(),
   value: z.nullable(z.unknown()),
@@ -179,6 +195,10 @@ export const restPluginDetailSchema = z.extend(restPluginSchema, {
   /** The board project the manifest proposes, for an administrator who makes it; `null` where it proposes none. */
   boardDefaults: z.nullable(z.object({ key: z.string(), name: localized, description: localized })),
   settings: z.array(restPluginSettingSchema),
+  /** The groups the settings form is divided into, in the manifest's order; answered from 0.4.4 and read as optional. */
+  settingGroups: z.optional(
+    z.array(z.object({ key: z.string(), name: localized, description: z.nullable(localized) })),
+  ),
   /** The grants, to an administrator; `null` to a member. */
   grants: z.nullable(z.array(restPluginGrantSchema)),
   /** The plugin's own events are at this path. */
@@ -188,7 +208,7 @@ export type RestPluginDetail = z.infer<typeof restPluginDetailSchema>;
 
 /** What `POST /api/v1/plugins/<key>/enable` is sent. */
 export const restPluginEnableInputSchema = z.object({
-  /** Every capability the manifest asks, named again: consent. */
+  /** Every capability the manifest requires, named again, and the optional ones to turn on: consent. */
   consent: z.array(z.string().check(z.maxLength(300))).check(z.maxLength(50)),
   /** The board project: one to make, one that exists, or none. */
   board: z.nullable(
@@ -216,6 +236,12 @@ export const restPluginSettingsPatchSchema = z.object({
 });
 export type RestPluginSettingsPatch = z.infer<typeof restPluginSettingsPatchSchema>;
 
+/** What `PATCH /api/v1/plugins/<key>/consent` is sent: what the plugin holds from now on, those it requires named again. */
+export const restPluginConsentPatchSchema = z.object({
+  consent: z.array(z.string().check(z.maxLength(300))).check(z.maxLength(50)),
+});
+export type RestPluginConsentPatch = z.infer<typeof restPluginConsentPatchSchema>;
+
 /** What `PUT /api/v1/plugins/<key>/secrets/<name>` is sent. */
 export const restPluginSecretInputSchema = z.object({
   value: z.string().check(z.minLength(1), z.maxLength(MAX_PLUGIN_SECRET_LENGTH)),