@skillcdn/console 0.4.1 → 0.4.3

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,
@@ -299,7 +325,8 @@ export interface ProjectClient {
    * while the decision waits, for as long as it allows, and answers the decision as it stands.
    */
   awaitDecision(id: string, waitSeconds: number, signal?: AbortSignal): Promise<RestDecision>;
-  raiseDecision(input: RestDecisionInput): Promise<RestDecision>;
+  /** Raises a decision; with `files`, the files put on it (ADR-0055) go in the one request. */
+  raiseDecision(input: RestDecisionInput, files?: readonly FileUpload[]): Promise<RestDecision>;
   answerDecision(id: string, input: RestAnswerInput): Promise<RestDecision>;
   /** Grows a decision's record: its context, or what followed. */
   updateDecision(id: string, patch: RestDecisionPatch): Promise<RestDecision>;
@@ -317,7 +344,7 @@ export interface ProjectClient {
   handIn(runId: string, input: RestArtifactInput): Promise<RestRun>;
   /** Hands in a file, on a run of the asker's: the console keeps the bytes. */
   handInFile(runId: string, input: FileUpload): Promise<RestRun>;
-  /** Where the bytes of a file of the project are read, by its id: handed in by a run, put in a comment, or attached to a page. */
+  /** Where the bytes of a file of the project are read, by its id: handed in by a run, put in a comment or on a decision, or attached to a page. */
   fileUrl(fileId: string): string;
   /** The bytes of a file of the project, by its id, with the name and the type the console says. */
   readFile(fileId: string, signal?: AbortSignal): Promise<FileRead>;
@@ -404,6 +431,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 +590,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. */
@@ -624,11 +775,9 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
     return form;
   };
 
-  /** A comment with files as the parts of a form: the part `body`, and a part `file` for each file. */
-  const commentFormOf = (input: CommentInput): FormData => {
-    const form = new FormData();
-    form.set("body", input.body);
-    for (const file of input.files ?? []) {
+  /** The files appended to a form, a part `file` each, with its name and its type. */
+  const appendFiles = (form: FormData, files: readonly FileUpload[]): void => {
+    for (const file of files) {
       const bytes =
         file.bytes instanceof Blob ? file.bytes : new Blob([Uint8Array.from(file.bytes)]);
       form.append(
@@ -637,6 +786,21 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
         file.name,
       );
     }
+  };
+
+  /** A comment with files as the parts of a form: the part `body`, and a part `file` for each file. */
+  const commentFormOf = (input: CommentInput): FormData => {
+    const form = new FormData();
+    form.set("body", input.body);
+    appendFiles(form, input.files ?? []);
+    return form;
+  };
+
+  /** A decision with files as the parts of a form (ADR-0055): the part `decision`, what the JSON would say, and a part `file` for each file. */
+  const decisionFormOf = (input: RestDecisionInput, files: readonly FileUpload[]): FormData => {
+    const form = new FormData();
+    form.set("decision", JSON.stringify(input));
+    appendFiles(form, files);
     return form;
   };
 
@@ -710,8 +874,13 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
           restDecisionSchema,
           signal,
         ),
-      raiseDecision: (input) =>
-        request("POST", `${base}${at("decisions")}`, input, restDecisionSchema),
+      raiseDecision: (input, files = []) =>
+        request(
+          "POST",
+          `${base}${at("decisions")}`,
+          files.length > 0 ? decisionFormOf(input, files) : input,
+          restDecisionSchema,
+        ),
       answerDecision: (id, input) =>
         request("POST", `${base}${at("decisions", id)}/answer`, input, restDecisionSchema),
       updateDecision: (id, patch) =>
@@ -915,6 +1084,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 +1282,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/comments.tsx

@@ -305,6 +305,7 @@ export function TaskThread(props: TaskThreadProps) {
         decision={item.decision}
         task={props.task}
         docHref={props.docHref}
+        fileHref={fileHref}
         onAnswer={props.onAnswer}
         onUpdate={props.onUpdateDecision}
         busy={props.busy}