@skillcdn/console 0.4.0 → 0.4.2

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

@@ -9,6 +9,8 @@ export const REST_ROUTES = {
   me: "/api/v1/me",
   /** The token a request is made with, for it to give itself up. */
   meToken: "/api/v1/me/token",
+  /** A picture from elsewhere, fetched by the console for a page (ADR-0048); `?src=` names it. */
+  pictures: "/api/v1/pictures",
   /** The workspace's settings (ADR-0035), changed by an administrator; read through `me`. */
   workspace: "/api/v1/workspace",
   /** The SkillCDN token the organization's pack is read with (ADR-0036), an administrator's; `/connect` under it connects one with a code. */
@@ -33,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,
@@ -167,6 +168,18 @@ export const restProviderSchema = z.object({
   key: z.enum(PROVIDER_KEYS),
   /** What people read on the button. */
   label: z.string(),
+  /**
+   * Who this way in lets in, for the line under the button: the organization at the git host
+   * whose members are in, the Workspace domains whose accounts are, or neither, where only the
+   * logins an administrator listed get in. Answered from 0.4.1; read as optional, so that a
+   * console built on this package reads an older console's answer.
+   */
+  admits: z.optional(
+    z.object({
+      organization: z.nullable(z.string()),
+      domains: z.array(z.string()),
+    }),
+  ),
 });
 export type RestProvider = z.infer<typeof restProviderSchema>;
 
@@ -483,6 +496,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`. */
@@ -656,6 +671,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({
@@ -803,6 +820,18 @@ export const restEventDataSchema = z.object({
   excerpt: z.optional(z.string()),
   /** For `task.commented`: 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>;
 
@@ -823,6 +852,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,
 });
@@ -1095,9 +1126,10 @@ export const restPackConnectStartedSchema = z.object({
 export type RestPackConnectStarted = z.infer<typeof restPackConnectStartedSchema>;
 
 /**
- * `GET .../pack-token/connect`: how the connection stands. Nothing asked; waiting for the
- * person, with what they were shown; connected, the token kept and the project as it stands; or
- * ended short of a token, and why.
+ * `GET .../pack-token/connect` and `POST .../pack-token/connect/claim`: how the connection
+ * stands. Nothing asked; waiting for the person, with what they were shown; connected, which
+ * only the claim answers (ADR-0046), the token kept and the project as it stands; or ended
+ * short of a token, and why.
  */
 const packConnectNone = z.object({ status: z.literal("none") });
 const packConnectPending = z.object({
@@ -1119,7 +1151,7 @@ export const restPackConnectSchema = z.union([
 ]);
 export type RestPackConnect = z.infer<typeof restPackConnectSchema>;
 
-/** `GET /api/v1/workspace/pack-token/connect`: the same, for the workspace's token, with the workspace as it stands once connected. */
+/** `GET /api/v1/workspace/pack-token/connect` and `POST .../connect/claim`: the same, for the workspace's token, with the workspace as it stands once connected. */
 export const restWorkspacePackConnectSchema = z.union([
   packConnectNone,
   packConnectPending,
@@ -1180,6 +1212,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,
@@ -1252,6 +1286,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;
@@ -1263,6 +1312,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>;
 
@@ -1270,6 +1321,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>;
 
@@ -1377,3 +1430,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";