@skillcdn/console 0.4.1 → 0.4.3

package/src/plugin.ts

@@ -0,0 +1,126 @@
+// The contract between a console and a plugin's server module (docs/specs/plugins.md): the
+// manifest's schema and words, `definePlugin` and its definers, the arguments, the types of `ctx`,
+// the capabilities and the bounds, and `z`, the schema library a plugin writes its records with.
+// A plugin bundles this into its server module; nothing of it is imported at runtime by the
+// console, which reads the description the module yields.
+
+export * as z from "zod";
+export {
+  ARG_TYPES,
+  type ArgDefinition,
+  type ArgDefinitions,
+  type ArgDescription,
+  type ArgsOf,
+  type ArgType,
+  type ArgValue,
+  arg,
+  argProblem,
+  argsProblem,
+  argUsage,
+  argValueFromWord,
+  type ParsedArgv,
+  type PluginFileHandle,
+  type PluginPersonRef,
+  type PluginProjectRef,
+  parseArgv,
+} from "./plugin/args.js";
+export {
+  CAPABILITY_WORDS,
+  type CapabilityWords,
+  capabilityWords,
+  isPluginCapability,
+  outboundAllows,
+  PLUGIN_CAPABILITIES,
+  PLUGIN_CAPABILITY_PREFIXES,
+  type PluginCapability,
+} from "./plugin/capabilities.js";
+export type * from "./plugin/context.js";
+export {
+  type ApiDefinition,
+  type CollectionDescription,
+  type CollectionInput,
+  type CommandDefinition,
+  type CommandInput,
+  type CommandResult,
+  defineCollection,
+  defineCommand,
+  defineEndpoint,
+  definePlugin,
+  defineQuery,
+  describePlugin,
+  descriptionProblems,
+  durationMs,
+  type EndpointAuth,
+  type EndpointDefinition,
+  type EndpointDescription,
+  type EndpointInput,
+  type HookHandler,
+  isPluginDefinition,
+  isQueryFile,
+  type JobDefinition,
+  type Lifecycle,
+  type OperationDescription,
+  type PluginDefinition,
+  type PluginDescription,
+  type PluginParts,
+  type QueryDefinition,
+  type QueryFile,
+  type QueryInput,
+  type UpgradeDefinition,
+} from "./plugin/define.js";
+export { PluginDefinitionError } from "./plugin/definition-error.js";
+export * from "./plugin/limits.js";
+export {
+  CURRENT_PLUGIN_API,
+  isPluginKey,
+  type Localized,
+  localizedText,
+  type ManifestParse,
+  PLUGIN_API_MAJORS,
+  PLUGIN_BOARD_NEEDS,
+  PLUGIN_KEY_PATTERN,
+  PLUGIN_MENU_GROUPS,
+  PLUGIN_PAGE_LEVELS,
+  PLUGIN_SETTING_TYPES,
+  PLUGIN_WIDGET_PLACES,
+  PLUGIN_WIDGET_SIZES,
+  type PluginBoard,
+  type PluginBoardNeeds,
+  type PluginManifest,
+  type PluginMenu,
+  type PluginMenuGroup,
+  type PluginPage,
+  type PluginPageLevel,
+  type PluginRole,
+  type PluginSetting,
+  type PluginSettingType,
+  type PluginWidget,
+  type PluginWidgetPlace,
+  type PluginWidgetSize,
+  parsePluginManifest,
+  pluginManifestSchema,
+  RESERVED_COMMAND_NAMES,
+  RESERVED_PAGE_KEYS,
+  RESERVED_PLUGIN_KEYS,
+  SETTING_KEY_PATTERN,
+} from "./plugin/manifest.js";
+export {
+  isPluginError,
+  isPluginRefusal,
+  ownRefusalCode,
+  PLUGIN_OWN_REFUSAL_STATUS,
+  PLUGIN_REFUSALS,
+  PluginError,
+  PluginRefusal,
+  type PluginRefusalCode,
+} from "./plugin/refusals.js";
+export {
+  FORBIDDEN_BUILTINS,
+  forbiddenImportsIn,
+  forbiddingResolve,
+  type HardenedThread,
+  hardenThread,
+  isForbiddenBuiltin,
+  REMOVED_GLOBALS,
+  removedGlobalsIn,
+} from "./plugin/sandbox.js";

package/src/router.ts

@@ -121,6 +121,24 @@ export type Route =
       readonly project: string;
       readonly page: string;
     }
+  /** A plugin's page (docs/specs/plugins.md, "Tabs, sub-tabs and addresses"): the first when the address names none; `rest` is what follows the page, handed to the frame. */
+  | {
+      readonly name: "plugin";
+      readonly level: "workspace";
+      readonly plugin: string;
+      readonly page: string | undefined;
+      readonly rest: string;
+    }
+  | {
+      readonly name: "plugin";
+      readonly level: "project";
+      readonly project: string;
+      readonly plugin: string;
+      readonly page: string | undefined;
+      readonly rest: string;
+    }
+  /** The plugins' settings, for an administrator: the list, or one plugin by its key. */
+  | { readonly name: "plugins-settings"; readonly plugin: string | undefined }
   | { readonly name: "not-found" };
 
 /** The pages of a project, after its key. */
@@ -158,12 +176,34 @@ export const PATHS = {
   settings: "/settings",
   /** Where the pages a console adds of its own are: `/pages/<key>`, and `/projects/<key>/pages/<page>` on a project. */
   pages: "/pages",
+  /** Where the plugins' pages are: `/plugins/<key>[/<page>[/<rest>]]`, and `/projects/<key>/plugins/<key>...` on a project (ADR-0054). */
+  plugins: "/plugins",
+  /** The plugins' settings, for an administrator: the list, and `/settings/plugins/<key>` for one. */
+  pluginSettings: "/settings/plugins",
   /** Where an agent's connection is approved (ADR-0011): `/connect/<code>`, or the code typed. */
   connect: "/connect",
 } as const;
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const PROJECT_KEY = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+/** A plugin's key, and a page's: as the manifest spells them. */
+const PLUGIN_KEY = /^[a-z][a-z0-9-]{1,31}$/;
+
+/** A plugin's address after its key: the page, if any, and what follows it for the frame. */
+function pluginRouteOf(
+  segments: readonly string[],
+):
+  | { readonly plugin: string; readonly page: string | undefined; readonly rest: string }
+  | undefined {
+  const [plugin, page, ...rest] = segments;
+  if (plugin === undefined || !PLUGIN_KEY.test(plugin)) {
+    return undefined;
+  }
+  if (page !== undefined && !PLUGIN_KEY.test(page)) {
+    return undefined;
+  }
+  return { plugin, page, rest: rest.length === 0 ? "" : `/${rest.join("/")}` };
+}
 const NUMBER = /^[1-9][0-9]{0,8}$/;
 /** A code as it may be typed into an address: checked for what it is by the page. */
 const CODE_TEXT = /^[A-Za-z0-9-]{1,16}$/;
@@ -268,6 +308,15 @@ export function matchRoute(pathname: string, search = ""): Route {
   if (path === PATHS.categories) {
     return { name: "categories" };
   }
+  if (path === PATHS.pluginSettings) {
+    return { name: "plugins-settings", plugin: undefined };
+  }
+  if (path.startsWith(`${PATHS.pluginSettings}/`)) {
+    const [plugin, ...more] = path.slice(PATHS.pluginSettings.length + 1).split("/");
+    return plugin !== undefined && PLUGIN_KEY.test(plugin) && more.length === 0
+      ? { name: "plugins-settings", plugin }
+      : NOT_FOUND;
+  }
   if (path === PATHS.settings) {
     return {
       name: "workspace-settings",
@@ -307,6 +356,10 @@ export function matchRoute(pathname: string, search = ""): Route {
       ? { name: "custom", level: "workspace", page }
       : NOT_FOUND;
   }
+  if (path.startsWith(`${PATHS.plugins}/`)) {
+    const found = pluginRouteOf(path.slice(PATHS.plugins.length + 1).split("/"));
+    return found === undefined ? NOT_FOUND : { name: "plugin", level: "workspace", ...found };
+  }
   if (!path.startsWith(`${PATHS.project}/`)) {
     return NOT_FOUND;
   }
@@ -331,6 +384,12 @@ export function matchRoute(pathname: string, search = ""): Route {
       ? { name: "custom", level: "project", project, page: third }
       : NOT_FOUND;
   }
+  if (page === "plugins") {
+    const found = pluginRouteOf([third, ...rest].filter((segment) => segment !== undefined));
+    return found === undefined
+      ? NOT_FOUND
+      : { name: "plugin", level: "project", project, ...found };
+  }
   if (rest.length > 0) {
     return NOT_FOUND;
   }
@@ -526,6 +585,20 @@ export function customPageHref(page: string, project?: string): string {
   return project === undefined ? `${PATHS.pages}/${page}` : `${projectHref(project)}/pages/${page}`;
 }
 
+/** Where a plugin's page is (ADR-0054): its first page, or the one named, with what follows it; on a project when its key is given. */
+export function pluginHref(plugin: string, page?: string, project?: string, rest = ""): string {
+  const base =
+    project === undefined
+      ? `${PATHS.plugins}/${plugin}`
+      : `${projectHref(project)}/plugins/${plugin}`;
+  return page === undefined ? base : `${base}/${page}${rest}`;
+}
+
+/** Where the plugins' settings are, or one plugin's. */
+export function pluginSettingsHref(plugin?: string): string {
+  return plugin === undefined ? PATHS.pluginSettings : `${PATHS.pluginSettings}/${plugin}`;
+}
+
 /** Where a goal is set: the form. */
 /** Where a project's roadmap is, from a month on, or from this one when none is named. */
 export function roadmapHref(key: string, from?: string): string {

package/src/routes.ts

@@ -35,8 +35,15 @@ export const REST_ROUTES = {
   decisions: "/api/v1/decisions",
   /** The rules of the board (ADR-0023): the console's own until an administrator writes the organization's. */
   rules: "/api/v1/rules",
+  /** The plugins (ADR-0049): the ones a member may know of, and under each key the plugin's own routes. */
+  plugins: "/api/v1/plugins",
 } as const;
 
+/** The REST path of one plugin, by its key, and of what is under it. */
+export function pluginPath(key: string, ...parts: readonly string[]): string {
+  return [REST_ROUTES.plugins, encodeURIComponent(key), ...parts.map(encodeURIComponent)].join("/");
+}
+
 /** The REST path of the workspace's rules put away, or of their versions. */
 export function rulesPath(part?: "archive" | "versions"): string {
   return part === undefined ? REST_ROUTES.rules : `${REST_ROUTES.rules}/${part}`;

package/src/schemas.ts

@@ -55,6 +55,7 @@ import {
   PEOPLE_VISIBILITIES,
   PERSON_ROLES,
   PERSON_STATUSES,
+  PLUGIN_COMMAND_OUTCOMES,
   PROJECT_ICON_TYPES,
   PROJECT_ROLES,
   PROJECT_VISIBILITIES,
@@ -283,6 +284,13 @@ export const restMeSchema = z.object({
    * built on this package still reads an older console's answer, and says it is older.
    */
   console: z.optional(z.object({ version: z.string(), clientRange: z.string() })),
+  /**
+   * How many decisions wait for the person's answer across the projects they may see
+   * (ADR-0042), for the pages to say beside My decisions; `null` for nobody. Answered from
+   * 0.4.3 and read as optional, so that a console built on this package still reads an older
+   * console's answer.
+   */
+  decisions: z.optional(z.nullable(z.object({ waiting: count }))),
 });
 export type RestMe = z.infer<typeof restMeSchema>;
 
@@ -495,6 +503,8 @@ export const restTaskSchema = z.object({
   priority: z.enum(TASK_PRIORITIES),
   /** Whose task it is: one person, whoever wrote it. */
   owner: restPersonSchema,
+  /** The plugin that made it, by key (ADR-0052), or `null`; left out by a console older than the plugins. */
+  plugin: z.optional(z.nullable(z.string())),
   /** The people at work on it (ADR-0037), in the order they came to it; `[]` while nobody is. */
   workers: z.array(restPersonSchema),
   /** The task this one is part of, or `null`. */
@@ -640,10 +650,50 @@ export const restGoalPatchSchema = z.object({
 });
 export type RestGoalPatch = z.infer<typeof restGoalPatchSchema>;
 
+/** A file a run handed in, as the console keeps it; its bytes are at `projectPath(key, "files", <artifact id>)`. */
+export const restFileSchema = z.object({
+  /** What the agent called it: one line, without a path. */
+  name: z.string(),
+  /** In bytes. */
+  size: count,
+  /** The media type the agent said, or `application/octet-stream`. */
+  contentType: z.string(),
+  /** The SHA-256 of the bytes, in hex: what the console keeps them under. */
+  sha256: z.string(),
+});
+export type RestFile = z.infer<typeof restFileSchema>;
+
+/** A file put on a decision when it was raised (ADR-0055), kept as a run's file is; its bytes are at `projectPath(key, "files", <id>)`. */
+export const restDecisionFileSchema = z.object({
+  id: uuid,
+  file: restFileSchema,
+});
+export type RestDecisionFile = z.infer<typeof restDecisionFileSchema>;
+
+/**
+ * The key a raiser may give an option, for a program to read the answer by instead of
+ * comparing labels: spelled as a plugin's key is.
+ */
+export const OPTION_KEY_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;
+const optionKey = z
+  .string()
+  .check(
+    z.regex(
+      OPTION_KEY_PATTERN,
+      "must be a key: a lowercase letter, then lowercase letters, digits and hyphens, 2 to 32 long",
+    ),
+  );
+
 export const restDecisionOptionSchema = z.object({
   /** What an answer names: stable once given. */
   id: z.string(),
   label: z.string(),
+  /**
+   * The key the raiser gave the option, for a program to read the answer by (`optionKey` on the
+   * `decision.answered` event) without comparing labels; none on an option given without one,
+   * and none on the person's own answer.
+   */
+  key: z.optional(z.string()),
   /**
    * On the one option a person's own answer became, when they answered in their own words
    * instead of choosing (`POST .../answer` with `own`): added then, after the options given,
@@ -668,6 +718,8 @@ export const restDecisionSchema = z.object({
   decider: restPersonSchema,
   /** The run that raised it, as the agent asked, or `null` when a person did. */
   run: z.nullable(z.object({ id: uuid, agent: z.string() })),
+  /** The plugin that raised it, by key (ADR-0052), or `null`; left out by a console older than the plugins. */
+  plugin: z.optional(z.nullable(z.string())),
   /** The answer, with who gave it and when; `null` while the decision waits. */
   answer: z.nullable(
     z.object({
@@ -681,6 +733,13 @@ export const restDecisionSchema = z.object({
   ),
   /** What followed the decision, in Markdown, written afterwards; `null` until someone does. */
   outcome: z.nullable(z.string()),
+  /**
+   * The files put on it when it was raised (ADR-0055), in the order they came; a picture among
+   * them is shown where the context names it as `![words](its name)`, else after it. Answered
+   * from 0.4.3 and read as optional, so that a console built on this package still reads an
+   * older console's decisions.
+   */
+  files: z.optional(z.array(restDecisionFileSchema)),
   createdAt: instant,
   updatedAt: instant,
 });
@@ -737,13 +796,25 @@ export const restPersonWorkSchema = z.object({
 });
 export type RestPersonWork = z.infer<typeof restPersonWorkSchema>;
 
-/** What `POST /api/v1/projects/<key>/decisions` is sent: the question, its context, and the options. */
+/**
+ * What `POST /api/v1/projects/<key>/decisions` is sent: the question, its context, and the
+ * options. As JSON; or, with files put on the decision (ADR-0055), as the part `decision` of a
+ * form, with a part `file` for each file.
+ */
 export const restDecisionInputSchema = z.object({
   question: line(MAX_QUESTION_LENGTH),
   body: z.optional(body),
+  /** Each a label, and optionally a key a program reads the answer by, each key once. */
   options: z
-    .array(z.object({ label: line(MAX_OPTION_LABEL_LENGTH) }))
-    .check(z.minLength(MIN_OPTIONS), z.maxLength(MAX_OPTIONS)),
+    .array(z.object({ label: line(MAX_OPTION_LABEL_LENGTH), key: z.optional(optionKey) }))
+    .check(
+      z.minLength(MIN_OPTIONS),
+      z.maxLength(MAX_OPTIONS),
+      z.refine((options) => {
+        const keys = options.flatMap((option) => (option.key === undefined ? [] : [option.key]));
+        return new Set(keys).size === keys.length;
+      }, "each key once"),
+    ),
   taskId: z.optional(z.nullable(uuid)),
   /** The run that asks, when an agent does: the decision is about its task, and it waits for the answer. */
   runId: z.optional(z.nullable(uuid)),
@@ -796,8 +867,9 @@ export const restEventDataSchema = z.object({
   from: z.optional(z.enum(TASK_STATES)),
   to: z.optional(z.enum(TASK_STATES)),
   question: z.optional(z.string()),
-  /** For `decision.answered`: the label of the chosen option. */
+  /** For `decision.answered`: the label of the chosen option, and its key where the raiser gave one. */
   option: z.optional(z.string()),
+  optionKey: z.optional(z.string()),
   /** For `person.role_changed` and the events about a project's members: whose role, and what it became. */
   login: z.optional(z.string()),
   role: z.optional(z.string()),
@@ -813,8 +885,20 @@ export const restEventDataSchema = z.object({
   label: z.optional(z.string()),
   /** For `run.reported` and `task.commented`: the first words of what was written. */
   excerpt: z.optional(z.string()),
-  /** For `task.commented`: how many files came with it. */
+  /** For `task.commented`, and for `decision.raised` when any came: how many files came with it. */
   files: z.optional(z.int()),
+  /** For `plugin.command`: the command, how it ended, the refusal's code where it was refused, how long it ran, and the arguments, a secret one as `[hidden]`. */
+  command: z.optional(z.string()),
+  outcome: z.optional(z.enum(PLUGIN_COMMAND_OUTCOMES)),
+  code: z.optional(z.string()),
+  durationMs: z.optional(z.int()),
+  args: z.optional(z.record(z.string(), z.unknown())),
+  /** For `plugin.enabled` and `plugin.configured`: the capabilities consented to. */
+  capabilities: z.optional(z.array(z.string())),
+  /** For `plugin.granted` and `plugin.revoked`: whether the role went to everyone. */
+  everyone: z.optional(z.boolean()),
+  /** For `plugin.failed`: what went wrong, in words for a person. */
+  problem: z.optional(z.string()),
 });
 export type RestEventData = z.infer<typeof restEventDataSchema>;
 
@@ -835,6 +919,8 @@ export const restEventSchema = z.object({
   documentId: z.nullable(uuid),
   /** The goal it is about, or `null`. */
   goalId: z.nullable(uuid),
+  /** The plugin that caused it, by key, or `null` (ADR-0052). */
+  plugin: z.nullable(z.string()),
   data: restEventDataSchema,
   createdAt: instant,
 });
@@ -848,19 +934,6 @@ export const restReportSchema = z.object({
 });
 export type RestReport = z.infer<typeof restReportSchema>;
 
-/** A file a run handed in, as the console keeps it; its bytes are at `projectPath(key, "files", <artifact id>)`. */
-export const restFileSchema = z.object({
-  /** What the agent called it: one line, without a path. */
-  name: z.string(),
-  /** In bytes. */
-  size: count,
-  /** The media type the agent said, or `application/octet-stream`. */
-  contentType: z.string(),
-  /** The SHA-256 of the bytes, in hex: what the console keeps them under. */
-  sha256: z.string(),
-});
-export type RestFile = z.infer<typeof restFileSchema>;
-
 /** What a run handed in: a link to a branch, a pull request, a page; or a file the console keeps. */
 export const restArtifactSchema = z.object({
   id: uuid,
@@ -1193,6 +1266,8 @@ export const restDocumentSummarySchema = z.object({
   /** Who wrote the latest version, and the agent they wrote it through, or `null`. */
   updatedBy: restPersonSchema,
   agent: z.nullable(z.string()),
+  /** The plugin that wrote it, by key (ADR-0052), or `null`; left out by a console older than the plugins. */
+  plugin: z.optional(z.nullable(z.string())),
   /** When the document was archived, or `null` while it is current. */
   archivedAt: z.nullable(instant),
   createdAt: instant,
@@ -1265,6 +1340,21 @@ export const restDocumentInputSchema = z.object({
 });
 export type RestDocumentInput = z.infer<typeof restDocumentInputSchema>;
 
+/**
+ * A plugin named after the rules (docs/specs/plugins.md, "The command"): one the asker may use,
+ * bound to the project where the rules are a project's; what agents are told of it, in the
+ * manifest's languages, and the asker's roles in it.
+ */
+export const restRulesPluginSchema = z.object({
+  key: z.string(),
+  name: z.record(z.string(), z.string()),
+  /** The sentence agents read, by language; `null` for the description. */
+  agentNote: z.nullable(z.record(z.string(), z.string())),
+  description: z.record(z.string(), z.string()),
+  roles: z.array(z.string()),
+});
+export type RestRulesPlugin = z.infer<typeof restRulesPluginSchema>;
+
 /**
  * `GET /api/v1/rules`, and each half of a project's (ADR-0023): the rules that hold, and where
  * they come from. `reference`: the console's own, since the organization wrote none;
@@ -1276,6 +1366,8 @@ export const restRulesSchema = z.object({
   body: z.nullable(z.string()),
   /** The page they are written on, or `null` for the console's own and for none. */
   page: z.nullable(restDocumentSummarySchema),
+  /** At the workspace: every plugin the asker may use, by key; left out in the halves of a project's answer. */
+  plugins: z.optional(z.array(restRulesPluginSchema)),
 });
 export type RestRules = z.infer<typeof restRulesSchema>;
 
@@ -1283,6 +1375,8 @@ export type RestRules = z.infer<typeof restRulesSchema>;
 export const restProjectRulesSchema = z.object({
   workspace: restRulesSchema,
   project: restRulesSchema,
+  /** The plugins bound to the project, as its board project or on it, that the asker holds a role in. */
+  plugins: z.optional(z.array(restRulesPluginSchema)),
 });
 export type RestProjectRules = z.infer<typeof restProjectRulesSchema>;
 
@@ -1390,3 +1484,6 @@ export const restRunEndInputSchema = z.object({
   summary: z.optional(summary),
 });
 export type RestRunEndInput = z.infer<typeof restRunEndInputSchema>;
+
+// The plugins' routes (docs/specs/plugins.md, "REST"), beside the board's.
+export * from "./plugin/rest-schemas.js";