@skillcdn/console 0.4.2 → 0.4.4

package/src/plugin/sandbox.ts

@@ -13,6 +13,15 @@ export const FORBIDDEN_BUILTINS: readonly string[] = [
   "dgram",
   "dns",
   "dns/promises",
+  // The same network, under the names Node keeps for compatibility.
+  "_http_agent",
+  "_http_client",
+  "_http_common",
+  "_http_incoming",
+  "_http_outgoing",
+  "_http_server",
+  "_tls_common",
+  "_tls_wrap",
   "child_process",
   "cluster",
   "worker_threads",
@@ -67,6 +76,15 @@ export interface HardenedThread {
   readonly removed: readonly string[];
 }
 
+/** What a plugin is told of a built-in it may not have, by whichever way it asked. */
+function refusedBuiltin(specifier: string): Error {
+  const error = new Error(
+    `the host refuses ${specifier}: a plugin reaches the console through ctx alone`,
+  );
+  (error as { code?: string }).code = "ERR_PLUGIN_FORBIDDEN_BUILTIN";
+  return error;
+}
+
 /** The module hook: refuses the forbidden built-ins and lets everything else resolve as it would. */
 export function forbiddingResolve<C, R>(
   specifier: string,
@@ -74,19 +92,16 @@ export function forbiddingResolve<C, R>(
   nextResolve: (specifier: string, context: C) => R,
 ): R {
   if (isForbiddenBuiltin(specifier)) {
-    const error = new Error(
-      `the host refuses ${specifier}: a plugin reaches the console through ctx alone`,
-    );
-    (error as { code?: string }).code = "ERR_PLUGIN_FORBIDDEN_BUILTIN";
-    throw error;
+    throw refusedBuiltin(specifier);
   }
   return nextResolve(specifier, context);
 }
 
 /**
- * Hardens the current thread: refuses the forbidden built-ins through the module hooks, removes
- * the globals, empties the environment, and blocks `process.binding`. Call it in a worker thread
- * before importing plugin code; it reaches nothing outside that thread.
+ * Hardens the current thread: refuses the forbidden built-ins through the module hooks and through
+ * `process.getBuiltinModule`, which goes round them, removes the globals, empties the environment,
+ * and blocks `process.binding`. Call it in a worker thread before importing plugin code; it reaches
+ * nothing outside that thread.
  */
 export function hardenThread(
   moduleApi: Pick<typeof import("node:module"), "registerHooks">,
@@ -112,6 +127,19 @@ export function hardenThread(
     for (const name of ["binding", "_linkedBinding", "dlopen"]) {
       Object.defineProperty(proc, name, { value: refuse, writable: false, configurable: false });
     }
+    const getBuiltinModule = proc.getBuiltinModule;
+    if (typeof getBuiltinModule === "function") {
+      Object.defineProperty(proc, "getBuiltinModule", {
+        value: (specifier: string): unknown => {
+          if (isForbiddenBuiltin(specifier)) {
+            throw refusedBuiltin(specifier);
+          }
+          return getBuiltinModule.call(proc, specifier);
+        },
+        writable: false,
+        configurable: false,
+      });
+    }
     const env = proc.env as Record<string, unknown> | undefined;
     if (env !== undefined) {
       for (const key of Object.keys(env)) {

package/src/plugin/semver.ts

@@ -0,0 +1,89 @@
+// Versions and ranges as a manifest spells them (docs/specs/plugins.md, "The manifest"): the
+// range of another plugin's version in `requires`, and the range of the console's version in
+// `console`. Read loosely, as npm spells the common ones, with no library: a plugin declares
+// `>=0.4.3 <0.6`, and the console, the authoring command and the tests compare the same way.
+
+export type Triple = readonly [number, number, number];
+
+/**
+ * A version read loosely: `0.4.3`, `v0.4.3`, `0.6` (as `0.6.0`), `1` (as `1.0.0`), a prerelease or
+ * a build after the numbers ignored; nothing for anything else.
+ */
+export function parseLooseVersion(text: string): Triple | undefined {
+  const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:[-+].*)?$/.exec(text.trim());
+  return match === null
+    ? undefined
+    : [Number(match[1]), Number(match[2] ?? "0"), Number(match[3] ?? "0")];
+}
+
+export function compareTriples(a: Triple, b: Triple): number {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+
+/**
+ * Whether a version is within a range as npm spells the common ones: `*`, exact, `^`, `~`, `>=`,
+ * `>`, `<=`, `<`, several with spaces between (all must hold) and alternatives with `||` between
+ * (one must hold). A partial version in the range is read as `.0` filled in: `<0.6` is `<0.6.0`.
+ */
+export function satisfiesRange(version: string, range: string): boolean {
+  const have = parseLooseVersion(version);
+  const trimmed = range.trim();
+  if (trimmed === "*" || trimmed === "" || trimmed === "x" || trimmed === "latest") {
+    return true;
+  }
+  if (have === undefined) {
+    return false;
+  }
+  return trimmed.split(/\s*\|\|\s*/).some((alternative) =>
+    alternative.split(/\s+/).every((part) => {
+      const operator = /^(\^|~|>=|<=|>|<|=)?(.*)$/.exec(part);
+      const wanted = parseLooseVersion(operator?.[2] ?? "");
+      if (wanted === undefined) {
+        return false;
+      }
+      switch (operator?.[1]) {
+        case "^":
+          return (
+            compareTriples(have, wanted) >= 0 &&
+            (wanted[0] === 0 ? have[0] === 0 && have[1] === wanted[1] : have[0] === wanted[0])
+          );
+        case "~":
+          return (
+            compareTriples(have, wanted) >= 0 && have[0] === wanted[0] && have[1] === wanted[1]
+          );
+        case ">=":
+          return compareTriples(have, wanted) >= 0;
+        case ">":
+          return compareTriples(have, wanted) > 0;
+        case "<=":
+          return compareTriples(have, wanted) <= 0;
+        case "<":
+          return compareTriples(have, wanted) < 0;
+        default:
+          return compareTriples(have, wanted) === 0;
+      }
+    }),
+  );
+}
+
+/**
+ * The version a dependency spells, read loosely: `^0.4.3`, `~0.4.3`, `>=0.4.3` and `0.4.3` are
+ * all `0.4.3`; `workspace:*`, `*`, `latest` and a tag name none.
+ */
+export function versionOfDependency(spec: string): Triple | undefined {
+  return parseLooseVersion(spec.trim().replace(/^(?:\^|~|>=|=)\s*/, ""));
+}
+
+export function formatTriple(version: Triple): string {
+  return `${version[0]}.${version[1]}.${version[2]}`;
+}
+
+/**
+ * The range of consoles a plugin written against `version` runs on, as `console-plugin init`
+ * writes it: from that version on, within its line, since the plugin API moves with the console's
+ * line before 1.0 (`>=0.4.3 <0.5.0`), and within its major from 1.0 (`>=1.2.0 <2.0.0`).
+ */
+export function lineRangeFrom(version: Triple): string {
+  const below: Triple = version[0] === 0 ? [0, version[1] + 1, 0] : [version[0] + 1, 0, 0];
+  return `>=${formatTriple(version)} <${formatTriple(below)}`;
+}

package/src/plugin/testing.ts

@@ -519,7 +519,7 @@ function refusingConsole(given: TestConsoleOptions | undefined): PluginConsole {
   return {
     workspace:
       given?.workspace ?? (async () => forbidden("console.workspace", "console.workspace")),
-    people: fill("people", ["list", "get"], given?.people),
+    people: fill("people", ["list", "get", "granted"], given?.people),
     projects: fill("projects", ["list", "get", "members"], given?.projects),
     tasks: fill("tasks", ["list", "get", "create", "update", "comment"], given?.tasks),
     decisions: fill("decisions", ["list", "get", "ask"], given?.decisions),
@@ -538,6 +538,7 @@ function build(store: Store, options: TestContextOptions, caller: PluginCaller):
     version: "0.0.0",
     dataVersion: 1,
     settings: {},
+    capabilities: [],
     board: null,
     projects: "all",
     ...options.plugin,

package/src/plugin/web.ts

@@ -11,11 +11,13 @@ import {
   type BridgeFile,
   type BridgeInit,
   type BridgeMethod,
+  type BridgePicture,
   type BridgeToPage,
   isBridgePath,
   isBridgeToFrame,
   MAX_BRIDGE_TITLE_LENGTH,
   PLUGIN_BRIDGE_VERSION,
+  type PluginWidgetSizeName,
 } from "./bridge.js";
 import type { PluginRecord, RecordPage, RecordVersion } from "./context.js";
 
@@ -111,6 +113,13 @@ export interface PluginFrame {
       type: string,
     ): Promise<{ readonly handle: string }>;
   };
+  readonly people: {
+    /**
+     * An address to put in an image, of the person of that id (ADR-0063), with `people:read`; or
+     * `null` for a person with no picture to show. Kept for the life of the frame.
+     */
+    picture(id: string): Promise<string | null>;
+  };
   /** The console's page follows a path of the console's in place; a URL is refused. */
   navigate(path: string): void;
   /** The console's page downloads a file of this plugin. */
@@ -125,12 +134,21 @@ export interface PluginFrame {
   onTheme(handler: (theme: Readonly<Record<string, string>>) => void): () => void;
   /** The console navigated within this page's address. */
   onPath(handler: (path: string) => void): () => void;
+  /** The person gave the widget another size (ADR-0059); `context.size` was the first. */
+  onSize(handler: (size: PluginWidgetSizeName) => void): () => void;
   /** Stops listening to the console's page. */
   close(): void;
 }
 
 const DEFAULT_CONNECT_MS = 10_000;
 
+/** What a page is told for a person with no picture to show, which is no failure of the page's. */
+const NO_PICTURE: ReadonlySet<string> = new Set([
+  "plugin.not_found",
+  "picture.refused",
+  "picture.unavailable",
+]);
+
 function globalWindow(): FrameWindow {
   const candidate = (globalThis as { window?: FrameWindow }).window;
   if (candidate === undefined) {
@@ -219,7 +237,9 @@ export function connect(options: ConnectOptions = {}): Promise<PluginFrame> {
   const eventHandlers = new Set<(kind: BridgeEventKind, data: unknown) => void>();
   const themeHandlers = new Set<(theme: Readonly<Record<string, string>>) => void>();
   const pathHandlers = new Set<(path: string) => void>();
+  const sizeHandlers = new Set<(size: PluginWidgetSizeName) => void>();
   const subscribed = new Set<BridgeEventKind>();
+  const pictures = new Map<string, Promise<string | null>>();
   let counter = 0;
   let stopHeight: (() => void) | undefined;
 
@@ -301,6 +321,26 @@ export function connect(options: ConnectOptions = {}): Promise<PluginFrame> {
                 }>;
               },
             },
+            people: {
+              picture: (id) => {
+                const kept = pictures.get(id);
+                if (kept !== undefined) {
+                  return kept;
+                }
+                const asked = (call("people.picture", { id }) as Promise<BridgePicture>).then(
+                  ({ type, bytes }) => URL.createObjectURL(new Blob([bytes], { type })),
+                  (error: unknown) => {
+                    if (error instanceof PluginBridgeError && NO_PICTURE.has(error.code)) {
+                      return null;
+                    }
+                    pictures.delete(id);
+                    throw error;
+                  },
+                );
+                pictures.set(id, asked);
+                return asked;
+              },
+            },
             navigate: (path) => {
               if (!isBridgePath(path)) {
                 throw new PluginBridgeError({
@@ -338,6 +378,10 @@ export function connect(options: ConnectOptions = {}): Promise<PluginFrame> {
               pathHandlers.add(handler);
               return () => pathHandlers.delete(handler);
             },
+            onSize: (handler) => {
+              sizeHandlers.add(handler);
+              return () => sizeHandlers.delete(handler);
+            },
             close: () => {
               win.removeEventListener("message", listener);
               stopHeight?.();
@@ -393,6 +437,11 @@ export function connect(options: ConnectOptions = {}): Promise<PluginFrame> {
             handler(message.path);
           }
           return;
+        case "size":
+          for (const handler of sizeHandlers) {
+            handler(message.size);
+          }
+          return;
         default:
           return;
       }

package/src/plugin.ts

@@ -29,6 +29,7 @@ export {
   type CapabilityWords,
   capabilityWords,
   isPluginCapability,
+  OUTBOUND_WEBRTC,
   outboundAllows,
   PLUGIN_CAPABILITIES,
   PLUGIN_CAPABILITY_PREFIXES,
@@ -72,8 +73,10 @@ export { PluginDefinitionError } from "./plugin/definition-error.js";
 export * from "./plugin/limits.js";
 export {
   CURRENT_PLUGIN_API,
+  capabilitiesAsked,
   isPluginKey,
   type Localized,
+  legacyWidgetSize,
   localizedText,
   type ManifestParse,
   PLUGIN_API_MAJORS,
@@ -83,6 +86,8 @@ export {
   PLUGIN_PAGE_LEVELS,
   PLUGIN_SETTING_TYPES,
   PLUGIN_WIDGET_PLACES,
+  PLUGIN_WIDGET_SIZE_CELLS,
+  PLUGIN_WIDGET_SIZE_NAMES,
   PLUGIN_WIDGET_SIZES,
   type PluginBoard,
   type PluginBoardNeeds,
@@ -93,16 +98,20 @@ export {
   type PluginPageLevel,
   type PluginRole,
   type PluginSetting,
+  type PluginSettingGroup,
   type PluginSettingType,
   type PluginWidget,
   type PluginWidgetPlace,
   type PluginWidgetSize,
+  type PluginWidgetSizeName,
   parsePluginManifest,
   pluginManifestSchema,
   RESERVED_COMMAND_NAMES,
   RESERVED_PAGE_KEYS,
   RESERVED_PLUGIN_KEYS,
   SETTING_KEY_PATTERN,
+  TIME_OF_DAY,
+  widgetSizesOf,
 } from "./plugin/manifest.js";
 export {
   isPluginError,
@@ -124,3 +133,12 @@ export {
   REMOVED_GLOBALS,
   removedGlobalsIn,
 } from "./plugin/sandbox.js";
+export {
+  compareTriples,
+  formatTriple,
+  lineRangeFrom,
+  parseLooseVersion,
+  satisfiesRange,
+  type Triple,
+  versionOfDependency,
+} from "./plugin/semver.js";

package/src/rules.ts

@@ -83,7 +83,7 @@ export function isReferenceRules(body: string): boolean {
 /** What stands in the rules for the language of the person the agent works for. */
 export const RULES_LANGUAGE_PLACEHOLDER = "{language}";
 
-/** What the rules say when the person chose no language: the task's, as the people of the board wrote it. */
+/** What the rules say for a person with no language yet: the task's, as the people of the board wrote it. */
 const TASKS_LANGUAGE = "the language the task is written in";
 
 /** The name of a language in English, from its tag (`ko` is Korean); the tag itself when it is not one. */
@@ -101,8 +101,8 @@ export function languageNameOf(tag: string): string {
 
 /**
  * The rules as they read for a person: `{language}` filled with the name of the language they
- * chose for the pages, or with the task's language when they chose none. The command fills
- * them for the person whose token it holds; the pages for whoever reads them.
+ * read in (ADR-0065), or with the task's language while they have none. The command fills them
+ * for the person whose token it holds; the pages for whoever reads them.
  */
 export function fillRules(body: string, language: string | null | undefined): string {
   const name = language == null ? TASKS_LANGUAGE : languageNameOf(language);