@skillcdn/console 0.4.2 → 0.4.4

package/src/cli/plugin-check.ts

@@ -8,11 +8,14 @@ import { descriptionProblems, type PluginDescription } from "../plugin/define.js
 import type { ServerLoad } from "../plugin/load.js";
 import {
   CURRENT_PLUGIN_API,
+  capabilitiesAsked,
   PLUGIN_API_MAJORS,
   type PluginManifest,
   parsePluginManifest,
 } from "../plugin/manifest.js";
 import { forbiddenImportsIn, removedGlobalsIn } from "../plugin/sandbox.js";
+import { formatTriple, satisfiesRange, versionOfDependency } from "../plugin/semver.js";
+import { isLanguageMap } from "./plugin-init.js";
 
 export interface CheckReport {
   readonly ok: boolean;
@@ -308,10 +311,37 @@ function describeCounts(manifest: PluginManifest, description: PluginDescription
   return counts.join(", ");
 }
 
+/**
+ * The words of the manifest, as JSON, whose translation repeats the English words (`name.ko`,
+ * for one): what `init --languages` copies for the author to translate, and what was left.
+ */
+export function sameAsEnglish(value: unknown, at = ""): string[] {
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => sameAsEnglish(item, `${at}[${index}]`));
+  }
+  if (typeof value !== "object" || value === null) {
+    return [];
+  }
+  if (isLanguageMap(value)) {
+    return Object.entries(value)
+      .filter(([language, words]) => language !== "en" && words === value.en)
+      .map(([language]) => `${at}.${language}`.replace(/^\./, ""));
+  }
+  return Object.entries(value).flatMap(([key, inner]) =>
+    sameAsEnglish(inner, at.length === 0 ? key : `${at}.${key}`),
+  );
+}
+
+export interface CheckOptions {
+  /** The version of the console this command belongs to, held against the manifest's `console`; left out, not compared. */
+  readonly consoleVersion?: string | undefined;
+}
+
 /** Reads the plugin at `root` as a console would, and says what it would refuse. */
 export async function checkPlugin(
   root: string,
   loadServer: (file: string) => Promise<ServerLoad>,
+  options: CheckOptions = {},
 ): Promise<CheckReport> {
   const errors: string[] = [];
   const warnings: string[] = [];
@@ -338,6 +368,20 @@ export async function checkPlugin(
       `console-plugin.json: pluginApi ${manifest.pluginApi} is not one this command knows (${PLUGIN_API_MAJORS.join(", ")}); write against ${CURRENT_PLUGIN_API}`,
     );
   }
+  for (const path of sameAsEnglish(manifestRead.value)) {
+    warnings.push(
+      `console-plugin.json: ${path} is the same as en: translate it, or leave the language out`,
+    );
+  }
+  if (
+    manifest.console !== undefined &&
+    options.consoleVersion !== undefined &&
+    !satisfiesRange(options.consoleVersion, manifest.console)
+  ) {
+    warnings.push(
+      `console-plugin.json: console ${manifest.console} leaves out ${options.consoleVersion}, the console this command belongs to`,
+    );
+  }
 
   const packageRead = await readJson(join(root, "package.json"));
   let version = "0.0.0";
@@ -366,6 +410,25 @@ export async function checkPlugin(
     if (pkg.type !== "module") {
       errors.push('package.json: type is not "module"; the server module is ESM');
     }
+    // The console the plugin is built against is the one its types come from: a devDependency
+    // outside the consoles it declares is a plugin built for a console it says it does not run on.
+    const devDependencies = (
+      typeof pkg.devDependencies === "object" && pkg.devDependencies !== null
+        ? pkg.devDependencies
+        : {}
+    ) as Record<string, unknown>;
+    const dependency = devDependencies["@skillcdn/console"];
+    const builtAgainst =
+      typeof dependency === "string" ? versionOfDependency(dependency) : undefined;
+    if (
+      manifest.console !== undefined &&
+      builtAgainst !== undefined &&
+      !satisfiesRange(formatTriple(builtAgainst), manifest.console)
+    ) {
+      errors.push(
+        `package.json: devDependencies names @skillcdn/console ${String(dependency)}, outside the consoles the manifest declares (console ${manifest.console})`,
+      );
+    }
     const scripts = (
       typeof pkg.scripts === "object" && pkg.scripts !== null ? pkg.scripts : {}
     ) as Record<string, unknown>;
@@ -429,14 +492,17 @@ export async function checkPlugin(
         errors.push(`${manifest.server}: ${problem}`);
       }
       if (
-        manifest.capabilities.includes("endpoints") &&
+        capabilitiesAsked(manifest).includes("endpoints") &&
         Object.keys(description.endpoints).length === 0
       ) {
         warnings.push(
           "console-plugin.json: asks the capability endpoints and the server module defines no endpoint",
         );
       }
-      if (manifest.capabilities.includes("jobs") && Object.keys(description.jobs).length === 0) {
+      if (
+        capabilitiesAsked(manifest).includes("jobs") &&
+        Object.keys(description.jobs).length === 0
+      ) {
         warnings.push(
           "console-plugin.json: asks the capability jobs and the server module defines no job",
         );

package/src/cli/plugin-cli.ts

@@ -5,8 +5,9 @@ import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import type { ServerLoad } from "../plugin/load.js";
 import { isPluginKey, RESERVED_PLUGIN_KEYS } from "../plugin/manifest.js";
+import { lineRangeFrom, versionOfDependency } from "../plugin/semver.js";
 import { checkPlugin } from "./plugin-check.js";
-import { nameFromKey, writePluginFromTemplate } from "./plugin-init.js";
+import { LANGUAGE_TAG, nameFromKey, PACKAGE_NAME, writePluginFromTemplate } from "./plugin-init.js";
 
 export interface PluginCliIo {
   stdout(text: string): void;
@@ -25,12 +26,20 @@ export const PLUGIN_EXIT = { ok: 0, failed: 1, usage: 2 } as const;
 export const PLUGIN_USAGE = `console-plugin: writes and checks a plugin of the SkillCDN Console.
 
   console-plugin init <dir> --key <key> [--name <name>] [--console <dependency>]
+      [--package <name>] [--repository <url> [--directory <path>]] [--languages <tags>]
       Writes a plugin into <dir>, which must not exist or be empty, from the template this
       package ships: the manifest, a server module with one collection, one command and one
       query, the source of a web bundle with one page and one widget, one skill with its
       manifest, tests, and the build. <key> is the plugin's key, lowercase letters, digits and
       hyphens; --name its name for people, from the key unless said; --console what the
-      plugin's devDependency on @skillcdn/console says, ^<this version> unless said.
+      plugin's devDependency on @skillcdn/console says, ^<this version> unless said;
+      --package the package's name, console-plugin-<key> unless said, a scoped one
+      (@scope/console-plugin-<key>) published as public; --repository the https address of
+      the repository it lives in, with --directory its path there in a repository of several,
+      which fill repository, homepage and bugs and the manifest's store; --languages the
+      languages of its words with commas between, en first (en,ko), each language map and
+      both manifests' translations given the others as English words to translate, of which
+      check warns while they stay English.
 
   console-plugin check [<dir>]
       Reads the plugin in <dir>, the working directory unless said, as a console would, built:
@@ -68,13 +77,32 @@ export async function runPluginCli(argv: readonly string[], io: PluginCliIo): Pr
   return PLUGIN_EXIT.usage;
 }
 
+const INIT_USAGE =
+  "usage: console-plugin init <dir> --key <key> [--name <name>] [--console <dependency>] [--package <name>] [--repository <url> [--directory <path>]] [--languages <tags>]\n";
+
 async function init(args: readonly string[], io: PluginCliIo): Promise<number> {
-  let values: { key?: string; name?: string; console?: string };
+  let values: {
+    key?: string;
+    name?: string;
+    console?: string;
+    package?: string;
+    repository?: string;
+    directory?: string;
+    languages?: string;
+  };
   let positionals: string[];
   try {
     ({ values, positionals } = parseArgs({
       args: [...args],
-      options: { key: { type: "string" }, name: { type: "string" }, console: { type: "string" } },
+      options: {
+        key: { type: "string" },
+        name: { type: "string" },
+        console: { type: "string" },
+        package: { type: "string" },
+        repository: { type: "string" },
+        directory: { type: "string" },
+        languages: { type: "string" },
+      },
       allowPositionals: true,
       strict: true,
     }));
@@ -85,8 +113,51 @@ async function init(args: readonly string[], io: PluginCliIo): Promise<number> {
   const [dir, ...extra] = positionals;
   const key = values.key;
   if (dir === undefined || extra.length > 0 || key === undefined) {
+    io.stderr(INIT_USAGE);
+    return PLUGIN_EXIT.usage;
+  }
+  const packageName = values.package;
+  if (packageName !== undefined && (packageName.length > 214 || !PACKAGE_NAME.test(packageName))) {
+    io.stderr(
+      `console-plugin init: ${packageName} is not a package name: lowercase letters, digits, hyphens, dots and underscores, with a scope as @scope/name\n`,
+    );
+    return PLUGIN_EXIT.usage;
+  }
+  if (values.directory !== undefined && values.repository === undefined) {
+    io.stderr("console-plugin init: --directory goes with --repository\n");
+    return PLUGIN_EXIT.usage;
+  }
+  if (values.repository !== undefined && !isRepositoryAddress(values.repository)) {
+    io.stderr(
+      `console-plugin init: ${values.repository} is not the https address of a repository\n`,
+    );
+    return PLUGIN_EXIT.usage;
+  }
+  if (
+    values.directory !== undefined &&
+    !/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/.test(values.directory)
+  ) {
     io.stderr(
-      "usage: console-plugin init <dir> --key <key> [--name <name>] [--console <dependency>]\n",
+      "console-plugin init: --directory is a path within the repository, with forward slashes\n",
+    );
+    return PLUGIN_EXIT.usage;
+  }
+  const languages = values.languages
+    ?.split(",")
+    .map((language) => language.trim())
+    .filter((language) => language.length > 0);
+  if (
+    languages !== undefined &&
+    (languages.length === 0 || languages.some((language) => !LANGUAGE_TAG.test(language)))
+  ) {
+    io.stderr(
+      "console-plugin init: --languages is a list of language tags with commas between, en first: en,ko\n",
+    );
+    return PLUGIN_EXIT.usage;
+  }
+  if (languages !== undefined && languages[0] !== "en") {
+    io.stderr(
+      "console-plugin init: --languages begins with en, the language the template is written in\n",
     );
     return PLUGIN_EXIT.usage;
   }
@@ -106,12 +177,24 @@ async function init(args: readonly string[], io: PluginCliIo): Promise<number> {
     return PLUGIN_EXIT.usage;
   }
   const consoleDependency = values.console ?? (io.version === undefined ? "*" : `^${io.version}`);
+  // The consoles the plugin runs on: the line of the version it is written against, read from
+  // the dependency where it names one (`^0.4.3`, `0.4.3`); a dependency that names none
+  // (`workspace:*`) leaves the manifest naming no console.
+  const writtenAgainst = versionOfDependency(consoleDependency);
+  const consoleRange = writtenAgainst === undefined ? undefined : lineRangeFrom(writtenAgainst);
   const target = resolve(io.cwd, dir);
   try {
     const written = await writePluginFromTemplate(io.templateDir, target, {
       key,
       name,
       consoleDependency,
+      consoleRange,
+      packageName,
+      repository:
+        values.repository === undefined
+          ? undefined
+          : { url: values.repository, directory: values.directory },
+      languages,
     });
     io.stdout(`Wrote the plugin ${key} into ${target}: ${written.length} files.\n`);
     io.stdout(
@@ -124,6 +207,19 @@ async function init(args: readonly string[], io: PluginCliIo): Promise<number> {
   }
 }
 
+/** An https address of a repository, as git names it or as a browser opens it. */
+function isRepositoryAddress(value: string): boolean {
+  const address = value.replace(/^git\+/, "");
+  if (!/^https:\/\/\S+$/.test(address)) {
+    return false;
+  }
+  try {
+    return new URL(address).hostname.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 async function check(args: readonly string[], io: PluginCliIo): Promise<number> {
   const [dir, ...extra] = args;
   if (extra.length > 0 || dir?.startsWith("-")) {
@@ -131,7 +227,9 @@ async function check(args: readonly string[], io: PluginCliIo): Promise<number>
     return PLUGIN_EXIT.usage;
   }
   const root = resolve(io.cwd, dir ?? ".");
-  const report = await checkPlugin(root, (file) => io.loadServer(file));
+  const report = await checkPlugin(root, (file) => io.loadServer(file), {
+    consoleVersion: io.version,
+  });
   io.stdout(`console-plugin check ${root}\n`);
   io.stdout(wordsOf(report.errors, "error"));
   io.stdout(wordsOf(report.warnings, "warning"));

package/src/cli/plugin-init.ts

@@ -1,7 +1,9 @@
 // `console-plugin init` (docs/specs/plugins.md, "Authoring"): writes a plugin from the template
-// the package ships, the words `__key__`, `__name__` and `__console__` in the template's files and
-// their names replaced. `examples/plugin-hello` in the console's repository is what it writes for
-// the key `hello`, and a test holds the two equal.
+// the package ships, the words `__package__`, `__key__`, `__name__` and `__console__` in the
+// template's files and their names replaced; then what the template cannot say in a word, where
+// it was asked for: the fields a published or a repository-bound package carries, and the
+// languages beyond English. `examples/plugin-hello` in the console's repository is what it writes
+// for the key `hello` with nothing else said, and a test holds the two equal.
 import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
 
@@ -11,19 +13,47 @@ export interface InitOptions {
   readonly name: string;
   /** What the plugin's devDependency on `@skillcdn/console` says: `^<version>` of the command, unless said. */
   readonly consoleDependency: string;
+  /** The consoles the plugin runs on, the manifest's `console`: the line of the version it is written against; left out, the manifest names none. */
+  readonly consoleRange?: string | undefined;
+  /** The package's name: `console-plugin-<key>` unless said. A scoped name is published with `publishConfig.access` `public`. */
+  readonly packageName?: string | undefined;
+  /** The repository the plugin lives in and, in a repository of several, its directory: `repository`, `homepage`, `bugs` and the manifest's `store`. */
+  readonly repository?:
+    | { readonly url: string; readonly directory?: string | undefined }
+    | undefined;
+  /** The languages the plugin's words are in, `en` first; `en` alone unless said. Every language map and both manifests' translations get the others, copied from English for the author to translate. */
+  readonly languages?: readonly string[] | undefined;
+}
+
+/** A language tag as the manifest's language maps are keyed: `en`, `ko`, `pt-BR`. */
+export const LANGUAGE_TAG = /^[a-z]{2,3}(?:-[A-Za-z0-9]+)*$/;
+
+/** A package's name as the registry takes one: lowercase, with a scope as `@scope/name`. */
+export const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+/** The package's name from the options: what was said, else `console-plugin-<key>`. */
+export function packageNameOf(options: InitOptions): string {
+  return options.packageName ?? `console-plugin-${options.key}`;
 }
 
 /** The words the template uses, and what each becomes. */
 export function substitutions(options: InitOptions): readonly [string, string][] {
   return [
+    ["__package__", packageNameOf(options)],
     ["__key__", options.key],
     ["__name__", options.name],
+    ["__consoleRange__", options.consoleRange ?? "*"],
     ["__console__", options.consoleDependency],
   ];
 }
 
 export function substitute(text: string, options: InitOptions): string {
   let result = text;
+  if (options.consoleRange === undefined) {
+    // No console to name: the manifest's line goes, and any console that serves the plugin API
+    // runs the plugin, as before the field. Taken out as text, so that the file keeps its shape.
+    result = result.replace(/^[ \t]*"console": "__consoleRange__",\r?\n/m, "");
+  }
   for (const [word, value] of substitutions(options)) {
     result = result.replaceAll(word, value);
   }
@@ -86,5 +116,150 @@ export async function writePluginFromTemplate(
     await writeFile(path, substitute(text, options), "utf8");
     written.push(target);
   }
+  await adaptPlugin(targetDir, options);
   return written;
 }
+
+/** Whether a value of the manifest is a language map: words per language, `en` among them. */
+export function isLanguageMap(value: unknown): value is Record<string, string> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    "en" in value &&
+    Object.entries(value).every(
+      ([language, words]) => LANGUAGE_TAG.test(language) && typeof words === "string",
+    )
+  );
+}
+
+/** Every language map of the manifest, wherever it is, gets `languages`, each copied from English where it is missing. */
+function addLanguages(value: unknown, languages: readonly string[]): void {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      addLanguages(item, languages);
+    }
+    return;
+  }
+  if (typeof value !== "object" || value === null) {
+    return;
+  }
+  if (isLanguageMap(value)) {
+    const english = value.en ?? "";
+    for (const language of languages) {
+      if (!(language in value)) {
+        value[language] = english;
+      }
+    }
+    return;
+  }
+  for (const inner of Object.values(value)) {
+    addLanguages(inner, languages);
+  }
+}
+
+/** The page of a repository at its host, from the address git names it by. */
+function pageOf(url: string): string {
+  return url
+    .replace(/^git\+/, "")
+    .replace(/\.git$/, "")
+    .replace(/\/$/, "");
+}
+
+/**
+ * The manifest's front-matter with `translations` for `languages`, each the English words
+ * again, inserted before the front-matter's end; under `parent` where the format nests them
+ * (`skillcdn.translations` in a skill). The description is the one the front-matter has, as
+ * written; the title is the plugin's name.
+ */
+function withTranslations(
+  text: string,
+  languages: readonly string[],
+  titleKey: "name" | "title",
+  title: string,
+  parent?: "skillcdn",
+): string {
+  const newline = text.includes("\r\n") ? "\r\n" : "\n";
+  const lines = text.split(/\r?\n/);
+  const end = lines.indexOf("---", 1);
+  if (lines[0] !== "---" || end === -1) {
+    return text;
+  }
+  const described = lines
+    .slice(1, end)
+    .find((line) => line.startsWith("description:"))
+    ?.slice("description:".length)
+    .trim();
+  const indent = parent === undefined ? "" : "  ";
+  const block = [
+    ...(parent === undefined ? [] : [`${parent}:`]),
+    `${indent}translations:`,
+    ...languages.flatMap((language) => [
+      `${indent}  ${language}:`,
+      `${indent}    ${titleKey}: ${JSON.stringify(title)}`,
+      ...(described === undefined ? [] : [`${indent}    description: ${described}`]),
+    ]),
+  ];
+  return [...lines.slice(0, end), ...block, ...lines.slice(end)].join(newline);
+}
+
+/**
+ * What the template cannot say in a word, where it was asked for: `publishConfig` for a scoped
+ * name, `repository`, `homepage` and `bugs` with the manifest's `store` for a repository, and
+ * the languages beyond English in every language map and both manifests' translations, each
+ * copied from the English words for the author to translate (`console-plugin check` warns of
+ * one left as it was). Nothing is rewritten when nothing was asked, so that the example stays
+ * what the template says.
+ */
+async function adaptPlugin(targetDir: string, options: InitOptions): Promise<void> {
+  const name = packageNameOf(options);
+  const repository = options.repository;
+  const languages = (options.languages ?? []).filter((language) => language !== "en");
+  if (!name.startsWith("@") && repository === undefined && languages.length === 0) {
+    return;
+  }
+  const packagePath = join(targetDir, "package.json");
+  const pkg = JSON.parse(await readFile(packagePath, "utf8")) as Record<string, unknown>;
+  const manifestPath = join(targetDir, "console-plugin.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as Record<string, unknown>;
+  if (name.startsWith("@")) {
+    pkg.publishConfig = { access: "public" };
+  }
+  if (repository !== undefined) {
+    const page = pageOf(repository.url);
+    // The paths a git host has for a directory and for issues are the host's; only the one
+    // whose paths are known gets them.
+    const atGitHub = new URL(page).hostname === "github.com";
+    const homepage =
+      repository.directory !== undefined && atGitHub
+        ? `${page}/tree/HEAD/${repository.directory}`
+        : page;
+    pkg.repository = {
+      type: "git",
+      url: repository.url,
+      ...(repository.directory === undefined ? {} : { directory: repository.directory }),
+    };
+    pkg.homepage = homepage;
+    if (atGitHub) {
+      pkg.bugs = { url: `${page}/issues` };
+    }
+    manifest.store = { homepage, repository: page };
+  }
+  if (languages.length > 0) {
+    addLanguages(manifest, languages);
+    const skillcdn = join(targetDir, "SKILLCDN.md");
+    await writeFile(
+      skillcdn,
+      withTranslations(await readFile(skillcdn, "utf8"), languages, "name", options.name),
+      "utf8",
+    );
+    const skill = join(targetDir, "skills", options.key, "SKILL.md");
+    await writeFile(
+      skill,
+      withTranslations(await readFile(skill, "utf8"), languages, "title", options.name, "skillcdn"),
+      "utf8",
+    );
+  }
+  await writeFile(packagePath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}

package/src/client.ts

@@ -325,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>;
@@ -343,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>;
@@ -497,6 +498,8 @@ export interface PluginClient {
   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>;
+  /** A person's picture, for a frame, which names the person and never an address (ADR-0063). */
+  personPicture(personId: 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;
@@ -542,6 +545,8 @@ export interface PluginClient {
   disable(): Promise<RestPluginDetail>;
   /** Changes the settings' values, without secrets; `null` clears one. */
   updateSettings(patch: RestPluginSettingsPatch): Promise<RestPluginDetail>;
+  /** Says what an enabled plugin holds: those it requires, named again, and the optional ones to turn on. */
+  updateConsent(consent: readonly string[]): 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>;
@@ -774,11 +779,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(
@@ -787,6 +790,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;
   };
 
@@ -860,8 +878,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) =>
@@ -1124,6 +1147,8 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
         ),
       fileUrl: (fileId) => `${base}${at("files", fileId)}`,
       readFile: (fileId, signal) => read(`${base}${at("files", fileId)}`, fileId, signal),
+      personPicture: (personId, signal) =>
+        read(`${base}${at("people", personId, "picture")}`, personId, signal),
       frameUrl: (options) =>
         withQuery(at("frame"), {
           page: options.page,
@@ -1194,6 +1219,8 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
       disable: () => request("POST", `${base}${at("disable")}`, undefined, restPluginDetailSchema),
       updateSettings: (patch) =>
         request("PATCH", `${base}${at("settings")}`, patch, restPluginDetailSchema),
+      updateConsent: (consent) =>
+        request("PATCH", `${base}${at("consent")}`, { consent }, restPluginDetailSchema),
       setSecret: (name, value) =>
         request("PUT", `${base}${at("secrets", name)}`, { value }, undefined),
       removeSecret: (name) =>

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.2" };
+export const CLIENT_POLICY: ClientPolicy = { atLeast: "0.4.4" };
 
 /**
  * The oldest console this command works with (ADR-0038): raised by the release that last

package/src/components/board.tsx

@@ -71,13 +71,13 @@ export interface BoardProps {
 export const FOLDED_STATES: readonly TaskState[] = ["done", "dropped"];
 
 /** How far a mouse travels on a card before the press is a drag and not a click. */
-const DRAG_SLACK = 4;
+export const DRAG_SLACK = 4;
 /**
  * How long a finger rests on a card before the card comes loose, and how far it may wander
  * meanwhile; a finger that moves sooner is scrolling the page, not moving the card.
  */
-const HOLD_MS = 300;
-const HOLD_SLACK = 8;
+export const HOLD_MS = 300;
+export 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;
 /** How fast the board scrolls, in pixels a second, with the pointer at the edge itself; slower further in. */

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}