@skillcdn/console 0.1.16 → 0.1.18

package/src/cli/install.ts

@@ -0,0 +1,111 @@
+// Where the command runs from, so that the update it is told to make is the one that takes
+// effect: installed for the machine, in a project, run once from a cache, or a checkout of the
+// repository. Read from the package's own path and the working directory; nothing is asked of
+// the system, so that a notice about versions costs a command nothing.
+
+export type InstallKind = "global" | "project" | "temporary" | "checkout";
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+export interface Install {
+  readonly kind: InstallKind;
+  readonly manager: PackageManager;
+  /** The directory the package is installed in: a project's root, the machine's global one, a cache's; the checkout itself. */
+  readonly root: string;
+}
+
+export interface InstallClues {
+  /** The package's own directory, where its manifest is. */
+  readonly packageDir: string;
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly exists: (path: string) => boolean;
+}
+
+const PACKAGE = "@skillcdn/console";
+
+const slashes = (path: string): string => path.replaceAll("\\", "/").replace(/\/+$/, "");
+
+/** The package manager that ran this command, when one did: `pnpm exec`, `npx` and their kind say so. */
+function managerRunning(env: InstallClues["env"]): PackageManager | undefined {
+  const agent = env.npm_config_user_agent ?? "";
+  for (const manager of ["pnpm", "yarn", "bun", "npm"] as const) {
+    if (agent.startsWith(`${manager}/`)) {
+      return manager;
+    }
+  }
+  return undefined;
+}
+
+export function detectInstall(clues: InstallClues): Install {
+  const dir = slashes(clues.packageDir);
+  const cwd = slashes(clues.cwd);
+  const at = dir.indexOf("/node_modules/");
+  if (at < 0) {
+    return { kind: "checkout", manager: "pnpm", root: dir };
+  }
+  const root = dir.slice(0, at);
+  const lower = dir.toLowerCase();
+  const running = managerRunning(clues.env);
+  // What `npx`, `pnpm dlx`, `yarn dlx` and `bunx` fetch into a cache lives only for the run.
+  if (/\/(_npx|dlx|dlx-[^/]*)\//.test(lower) || lower.includes("/.bun/install/cache/")) {
+    const manager =
+      running ??
+      (lower.includes("/_npx/") ? "npm" : lower.includes("/.bun/install/cache/") ? "bun" : "pnpm");
+    return { kind: "temporary", manager, root };
+  }
+  if (cwd === root || cwd.startsWith(`${root}/`)) {
+    const manager: PackageManager = clues.exists(`${root}/pnpm-lock.yaml`)
+      ? "pnpm"
+      : clues.exists(`${root}/yarn.lock`)
+        ? "yarn"
+        : clues.exists(`${root}/bun.lock`) || clues.exists(`${root}/bun.lockb`)
+          ? "bun"
+          : (running ?? "npm");
+    return { kind: "project", manager, root };
+  }
+  const manager: PackageManager = /\/pnpm\/global\/|\/\.pnpm-global\//.test(lower)
+    ? "pnpm"
+    : lower.includes("/yarn/global/")
+      ? "yarn"
+      : lower.includes("/.bun/install/global/")
+        ? "bun"
+        : "npm";
+  return { kind: "global", manager, root };
+}
+
+/** The command that puts the version named where this command is installed. */
+export function updateCommandFor(install: Install, version: string): string {
+  const spec = `${PACKAGE}@${version}`;
+  switch (install.kind) {
+    case "global":
+      return install.manager === "npm"
+        ? `npm install -g ${spec}`
+        : install.manager === "yarn"
+          ? `yarn global add ${spec}`
+          : `${install.manager} add -g ${spec}`;
+    case "project":
+      return `${install.manager === "npm" ? "npm install" : `${install.manager} add`} ${spec}`;
+    case "temporary":
+      return install.manager === "npm"
+        ? `npx ${spec}`
+        : install.manager === "bun"
+          ? `bunx ${spec}`
+          : `${install.manager} dlx ${spec}`;
+    case "checkout":
+      return "git pull && pnpm install && pnpm build";
+  }
+}
+
+/** Where the command is installed, in words: what `whoami` and `--version` say. */
+export function describeInstall(install: Install): string {
+  switch (install.kind) {
+    case "global":
+      return `installed for the machine with ${install.manager} in ${install.root}`;
+    case "project":
+      return `installed in the project at ${install.root} with ${install.manager}`;
+    case "temporary":
+      return `fetched for this run by ${install.manager}`;
+    case "checkout":
+      return `built from the checkout at ${install.root}`;
+  }
+}

package/src/cli/main.ts

@@ -5,21 +5,28 @@ import { hostname } from "node:os";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import * as z from "zod/mini";
+import { userAgentOf } from "../compat.js";
 import { runCli } from "./cli.js";
 import { createFileStore, defaultConfigDir } from "./credentials.js";
 import { createDirectoryStore } from "./directory.js";
+import { detectInstall } from "./install.js";
+import { createNoticeStore } from "./notices.js";
 import { listenOn } from "./serve.js";
-import { readBytesAt, readFileAt, readStdin } from "./terminal.js";
+import { readBytesAt, readFileAt, readStdin, writeBytesAt } from "./terminal.js";
 
 // The `console` command: the only place the command reads the process. Everything it does is in
 // cli.ts, which takes what it needs and is what the tests run.
 
-/** The version of the package this file runs from: its own manifest, two levels above dist/cli. */
+/** The package's own directory, two levels above dist/cli: where its manifest and its skills are. */
+const packageDir = fileURLToPath(new URL("../../", import.meta.url));
+/** The version of the package this file runs from: its own manifest. */
 const manifest = z
   .object({ version: z.string() })
   .safeParse(createRequire(import.meta.url)("../../package.json"));
+const version = manifest.success ? manifest.data.version : undefined;
 /** The console's own skills, shipped with the package beside dist/ (ADR-0015); not there in a checkout before packing. */
 const skillsDir = fileURLToPath(new URL("../../skills/", import.meta.url));
+const configDir = defaultConfigDir(process.env);
 
 process.exitCode = await runCli(process.argv.slice(2), {
   env: process.env,
@@ -34,11 +41,25 @@ process.exitCode = await runCli(process.argv.slice(2), {
   hostname: hostname(),
   readFile: readFileAt,
   readBytes: readBytesAt,
-  store: createFileStore(defaultConfigDir(process.env)),
+  writeBytes: writeBytesAt,
+  store: createFileStore(configDir),
   directory: createDirectoryStore(process.cwd()),
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
   now: () => Date.now(),
-  version: manifest.success ? manifest.data.version : undefined,
+  version,
+  // The command names itself on every request, and where it runs, so that the console holds it
+  // to the versions it takes and the access log says which commands are about (ADR-0025).
+  userAgent:
+    version === undefined
+      ? undefined
+      : userAgentOf(version, `cli; node ${process.versions.node}; ${process.platform}`),
+  install: detectInstall({
+    packageDir,
+    cwd: process.cwd(),
+    env: process.env,
+    exists: existsSync,
+  }),
+  notices: createNoticeStore(configDir),
   skillsDir: existsSync(skillsDir) ? skillsDir : undefined,
   listen: listenOn,
 });

package/src/cli/notices.ts

@@ -0,0 +1,48 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import * as z from "zod/mini";
+
+// What the command last said about the versions, kept beside the credentials, so that it says
+// it once a day for one pair of versions and not on every command an agent runs. A notice is
+// not worth failing a command for: a file that cannot be read or written is as good as none.
+
+export interface VersionNotice {
+  /** The version of the command that noticed. */
+  readonly command: string;
+  /** The version of the console it noticed. */
+  readonly console: string;
+  readonly shownAt: string;
+}
+
+export interface NoticeStore {
+  load(): Promise<VersionNotice | undefined>;
+  save(notice: VersionNotice): Promise<void>;
+}
+
+const noticesSchema = z.object({
+  versions: z.optional(z.object({ command: z.string(), console: z.string(), shownAt: z.string() })),
+});
+
+const FILE_NAME = "notices.json";
+
+export function createNoticeStore(directory: string): NoticeStore {
+  const path = join(directory, FILE_NAME);
+  return {
+    async load() {
+      try {
+        const parsed = noticesSchema.safeParse(JSON.parse(await readFile(path, "utf8")));
+        return parsed.success ? parsed.data.versions : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    async save(notice) {
+      try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await writeFile(path, `${JSON.stringify({ versions: notice }, null, 2)}\n`);
+      } catch {
+        // Said this time; said again next time.
+      }
+    },
+  };
+}

package/src/cli/terminal.ts

@@ -1,4 +1,5 @@
-import { readFile } from "node:fs/promises";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import process from "node:process";
 
 // The terminal's side of the command: what is read from it. Nothing here is reached by tests,
@@ -26,3 +27,13 @@ export function readFileAt(path: string): Promise<string> {
 export function readBytesAt(path: string): Promise<Uint8Array> {
   return readFile(path);
 }
+
+/**
+ * A file read from the console, written at the path, or into it under the file's name when
+ * the path is a directory; says where it went, in full.
+ */
+export async function writeBytesAt(path: string, bytes: Uint8Array, name: string): Promise<string> {
+  const target = (await stat(path).catch(() => undefined))?.isDirectory() ? join(path, name) : path;
+  await writeFile(target, bytes);
+  return resolve(target);
+}

package/src/client.ts

@@ -18,6 +18,8 @@ import {
   type RestCategoryInput,
   type RestCategoryPatch,
   type RestClaim,
+  type RestComment,
+  type RestComments,
   type RestConnectInput,
   type RestConnection,
   type RestConnectRequest,
@@ -71,6 +73,8 @@ import {
   restCategoriesSchema,
   restCategorySchema,
   restClaimSchema,
+  restCommentSchema,
+  restCommentsSchema,
   restConnectionSchema,
   restConnectRequestSchema,
   restDecisionSchema,
@@ -103,7 +107,7 @@ import {
   restVersionsSchema,
   restWorkSchema,
 } from "./schemas.js";
-import type { TaskState } from "./vocabulary.js";
+import type { GoalState, TaskState } from "./vocabulary.js";
 
 // The client of the console's REST API: what the default console and a custom one talk to the
 // server with, and what the command line, a script or a console of a person's own talks to it
@@ -123,6 +127,22 @@ export interface FileUpload {
   readonly label?: string | undefined;
 }
 
+/** A comment to write on a task: the word, and the files put in it, which go in the one request. */
+export interface CommentInput {
+  /** Markdown; may be blank when a file comes with it. */
+  readonly body: string;
+  readonly files?: readonly FileUpload[] | undefined;
+}
+
+/** The bytes of a file of the project, as the console hands them back, with what it calls them. */
+export interface FileRead {
+  /** The file's name, as the console says it; the id when it says none. */
+  readonly name: string;
+  /** The media type the console answered with, without its parameters. */
+  readonly contentType: string;
+  readonly bytes: Uint8Array;
+}
+
 export interface ClientOptions {
   /** The origin of the console, without a path. Empty: the origin of the page. */
   readonly baseUrl?: string;
@@ -134,6 +154,12 @@ export interface ClientOptions {
    * the page's own origin is what the console answers to.
    */
   readonly token?: string;
+  /**
+   * What the client calls itself, sent as `user-agent` where the platform lets a client say
+   * (Node; a browser keeps its own): the command sends its product token, by which the console
+   * holds it to the versions it takes (ADR-0025).
+   */
+  readonly userAgent?: string;
 }
 
 export class ApiError extends Error {
@@ -169,6 +195,13 @@ export interface Page {
 }
 
 /** What the board is narrowed to: one state, the open ones, a category, a goal, an assignee, or what is due by a day. */
+/** What the roadmap is narrowed by: the goals in one state, or sorted into one category (ADR-0026). */
+export interface GoalFilter {
+  readonly state?: GoalState | undefined;
+  /** The key of a category of the workspace. */
+  readonly category?: string | undefined;
+}
+
 export interface TaskFilter extends Page {
   readonly state?: TaskState | undefined;
   /** True for the tasks not done or dropped; false for the rest. */
@@ -245,8 +278,14 @@ 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 handed in are read, by the artifact's id. */
-  fileUrl(artifactId: string): string;
+  /** 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. */
+  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>;
+  /** The discussion on a task: its comments, oldest first, whole. */
+  comments(taskId: string, signal?: AbortSignal): Promise<RestComments>;
+  /** Writes a comment on a task, with its files when given, in one request. */
+  comment(taskId: string, input: CommentInput): Promise<RestComment>;
   /** Ends a run: finished or failed by the agent; abandoned by the person it is for, or an administrator. */
   endRun(runId: string, input: RestRunEndInput): Promise<RestRun>;
   /** What happened in the project after event number `after`; `0` for the beginning. Narrowed by `filter`. */
@@ -276,7 +315,8 @@ export interface ProjectClient {
   /** Where the bytes of a file attached to a document are read, by the file's id. */
   documentFileUrl(path: string, fileId: string): string;
   /** The roadmap (ADR-0019): the goals, the active first, each with its tasks counted by state. */
-  goals(signal?: AbortSignal): Promise<RestGoals>;
+  /** The roadmap, or what the filter keeps of it: the active goals first. */
+  goals(filter?: GoalFilter, signal?: AbortSignal): Promise<RestGoals>;
   goal(id: string, signal?: AbortSignal): Promise<RestGoal>;
   /** Sets a goal; for an owner, with a session or a token. */
   createGoal(input: RestGoalInput): Promise<RestGoal>;
@@ -355,7 +395,8 @@ const INVALID = "The server answered unexpectedly.";
 export function createClient(options: ClientOptions = {}): ConsoleClient {
   const base = (options.baseUrl ?? "").replace(/\/+$/, "");
   const send = options.fetch ?? ((input, init) => fetch(input, init));
-  const { token } = options;
+  const { token, userAgent } = options;
+  const named: Record<string, string> = userAgent === undefined ? {} : { "user-agent": userAgent };
 
   const withQuery = (path: string, params: Record<string, string | undefined>): string => {
     const query = new URLSearchParams();
@@ -397,6 +438,7 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
           // A form names its own type, boundary included; everything else is JSON.
           ...(body === undefined || form ? {} : { "content-type": "application/json" }),
           ...(token === undefined ? {} : { authorization: `Bearer ${token}` }),
+          ...named,
         },
         ...(body === undefined ? {} : { body: form ? body : JSON.stringify(body) }),
       });
@@ -419,6 +461,40 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
     return parsed.data;
   };
 
+  /** The bytes at `url`, with the name and the type the console says, for a file of the project. */
+  const read = async (
+    url: string,
+    fallbackName: string,
+    signal?: AbortSignal,
+  ): Promise<FileRead> => {
+    let response: Response;
+    try {
+      response = await send(url, {
+        method: "GET",
+        ...(signal === undefined ? {} : { signal }),
+        credentials: token === undefined ? "same-origin" : "omit",
+        headers: {
+          ...(token === undefined ? {} : { authorization: `Bearer ${token}` }),
+          ...named,
+        },
+      });
+    } catch (error) {
+      if (signal?.aborted === true) {
+        throw error;
+      }
+      throw new ApiError(0, "network", "The server could not be reached.");
+    }
+    if (!response.ok) {
+      throw await failure(response);
+    }
+    const type = response.headers.get("content-type") ?? "application/octet-stream";
+    return {
+      name: fileNameOf(response.headers.get("content-disposition") ?? "") ?? fallbackName,
+      contentType: type.split(";")[0]?.trim() ?? "application/octet-stream",
+      bytes: new Uint8Array(await response.arrayBuffer()),
+    };
+  };
+
   const flag = (value: boolean | undefined): string | undefined =>
     value === undefined ? undefined : String(value);
   const number = (value: number | undefined): string | undefined =>
@@ -440,6 +516,22 @@ 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 ?? []) {
+      const bytes =
+        file.bytes instanceof Blob ? file.bytes : new Blob([Uint8Array.from(file.bytes)]);
+      form.append(
+        "file",
+        new File([bytes], file.name, { type: file.contentType ?? "application/octet-stream" }),
+        file.name,
+      );
+    }
+    return form;
+  };
+
   const projectClient = (key: string): ProjectClient => {
     const at = (collection?: Parameters<typeof projectPath>[1], id?: string) =>
       projectPath(key, collection, id);
@@ -530,7 +622,23 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
         request("POST", `${base}${at("runs", runId)}/artifacts`, input, restRunSchema),
       handInFile: (runId, input) =>
         request("POST", `${base}${at("runs", runId)}/files`, formOf(input), restRunSchema),
-      fileUrl: (artifactId) => `${base}${at("files", artifactId)}`,
+      fileUrl: (fileId) => `${base}${at("files", fileId)}`,
+      readFile: (fileId, signal) => read(`${base}${at("files", fileId)}`, fileId, signal),
+      comments: (taskId, signal) =>
+        request(
+          "GET",
+          `${base}${at("tasks", taskId)}/comments`,
+          undefined,
+          restCommentsSchema,
+          signal,
+        ),
+      comment: (taskId, input) =>
+        request(
+          "POST",
+          `${base}${at("tasks", taskId)}/comments`,
+          (input.files?.length ?? 0) > 0 ? commentFormOf(input) : { body: input.body },
+          restCommentSchema,
+        ),
       endRun: (runId, input) =>
         request("POST", `${base}${at("runs", runId)}/end`, input, restRunSchema),
       events: (after, filter = {}, signal) =>
@@ -592,8 +700,14 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
         request("POST", `${base}${at("docs", path)}/files`, formOf(input), restDocumentSchema),
       documentFileUrl: (path, fileId) =>
         `${base}${at("docs", path)}/files/${encodeURIComponent(fileId)}`,
-      goals: (signal) =>
-        request("GET", `${base}${at("goals")}`, undefined, restGoalsSchema, signal),
+      goals: (filter = {}, signal) =>
+        request(
+          "GET",
+          withQuery(at("goals"), { state: filter.state, category: filter.category }),
+          undefined,
+          restGoalsSchema,
+          signal,
+        ),
       goal: (id, signal) =>
         request("GET", `${base}${at("goals", id)}`, undefined, restGoalSchema, signal),
       createGoal: (input) => request("POST", `${base}${at("goals")}`, input, restGoalSchema),
@@ -668,3 +782,23 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
     signOut: () => request("POST", `${base}${AUTH_ROUTES.logout}`, undefined, undefined),
   };
 }
+
+/**
+ * The file's name as a `content-disposition` header says it: the exact one (`filename*`, UTF-8,
+ * percent-encoded) when it is readable, else the plain one in quotes; nothing when neither is.
+ */
+export function fileNameOf(disposition: string): string | undefined {
+  const exact = /filename\*=UTF-8''([^;]+)/i.exec(disposition);
+  if (exact?.[1] !== undefined) {
+    try {
+      const decoded = decodeURIComponent(exact[1].trim());
+      if (decoded.length > 0) {
+        return decoded;
+      }
+    } catch {
+      // Not percent-encoded as it should be: the plain name below is what there is.
+    }
+  }
+  const plain = /filename="([^"]*)"/i.exec(disposition);
+  return plain?.[1] === undefined || plain[1].length === 0 ? undefined : plain[1];
+}

package/src/compat.ts

@@ -0,0 +1,173 @@
+// Whether the command and the console go together (ADR-0025). The command names its version on
+// every request, in the product token of its user-agent; the console answers every request of
+// the API with its own version and the range of command versions it takes, and refuses a
+// command outside the range with `426` and the words to update. One rule for both sides, kept
+// here so that the command and the console read the same one, and narrowed by the console's
+// policy below only, never widened: what the rule promises stays predictable.
+
+/** The product token the command names itself with: `skillcdn-console/<version>`. */
+export const CLIENT_PRODUCT = "skillcdn-console";
+/** On every answer of the API: the console's version. */
+export const VERSION_HEADER = "console-version";
+/** On every answer of the API: the range of command versions the console takes, as npm spells one. */
+export const CLIENT_RANGE_HEADER = "console-client-range";
+
+export interface Version {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+}
+
+/** `x.y.z`, each a number of at most nine digits without a leading zero; no tag, no build. */
+const VERSION = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+const MAX_VERSION_LENGTH = 32;
+
+/** A version as the package spells one, or nothing for any other text. */
+export function parseVersion(text: string | null | undefined): Version | undefined {
+  if (typeof text !== "string" || text.length > MAX_VERSION_LENGTH) {
+    return undefined;
+  }
+  const match = VERSION.exec(text);
+  return match === null
+    ? undefined
+    : { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+export function formatVersion(version: Version): string {
+  return `${version.major}.${version.minor}.${version.patch}`;
+}
+
+/** Negative when `a` is the older, zero when they are the same, positive when `a` is the newer. */
+export function compareVersions(a: Version, b: Version): number {
+  return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+
+/** A half-open range of versions: from `atLeast` on, and before `below`. */
+export interface VersionRange {
+  readonly atLeast: Version;
+  readonly below: Version;
+}
+
+/** The range as npm spells one: `>=0.1.18 <0.2.0`. */
+export function formatRange(range: VersionRange): string {
+  return `>=${formatVersion(range.atLeast)} <${formatVersion(range.below)}`;
+}
+
+const RANGE = /^>=(\S+) <(\S+)$/;
+const MAX_RANGE_LENGTH = 2 * MAX_VERSION_LENGTH + 4;
+
+/** A range as `formatRange` spells one, or nothing for any other text. */
+export function parseRange(text: string | null | undefined): VersionRange | undefined {
+  if (typeof text !== "string" || text.length > MAX_RANGE_LENGTH) {
+    return undefined;
+  }
+  const match = RANGE.exec(text);
+  const atLeast = parseVersion(match?.[1]);
+  const below = parseVersion(match?.[2]);
+  return atLeast !== undefined && below !== undefined && compareVersions(atLeast, below) < 0
+    ? { atLeast, below }
+    : undefined;
+}
+
+export function inRange(version: Version, range: VersionRange): boolean {
+  return compareVersions(version, range.atLeast) >= 0 && compareVersions(version, range.below) < 0;
+}
+
+/**
+ * The common rule. Before 1.0, a command from the console's own version on and within the
+ * console's minor (`^0.1.18`): any release may change the contract until then (ADR-0007), so the
+ * console's own version is the floor, and the minor is the line. From 1.0, the console's major
+ * and a minor within one of the console's, either way, whatever the patch: a minor adds and a
+ * major breaks, as the version promises from then on.
+ */
+export function commonRange(server: Version): VersionRange {
+  if (server.major === 0) {
+    return { atLeast: server, below: { major: 0, minor: server.minor + 1, patch: 0 } };
+  }
+  return {
+    atLeast: { major: server.major, minor: Math.max(0, server.minor - 1), patch: 0 },
+    below: { major: server.major, minor: server.minor + 2, patch: 0 },
+  };
+}
+
+/**
+ * What the console narrows the common rule by, and nothing it widens it by: a floor above the
+ * rule's, for a contract that moved within what the rule still allows, and versions refused
+ * whatever the rule says, for a release whose command is wrong. Changed with a changeset that
+ * says why.
+ */
+export interface ClientPolicy {
+  /** The oldest command this console answers, when the common rule's floor is too low. */
+  readonly atLeast?: string | undefined;
+  /** Versions of the command refused outright. */
+  readonly refused?: readonly string[] | undefined;
+}
+
+/** The console's policy today: the common rule as it is. */
+export const CLIENT_POLICY: ClientPolicy = {};
+
+/** The range of command versions a console of `server` takes: the common rule, narrowed by the policy's floor where that floor is within it. */
+export function clientRange(server: Version, policy: ClientPolicy = CLIENT_POLICY): VersionRange {
+  const common = commonRange(server);
+  const floor = parseVersion(policy.atLeast);
+  return floor !== undefined &&
+    compareVersions(floor, common.atLeast) > 0 &&
+    compareVersions(floor, common.below) < 0
+    ? { atLeast: floor, below: common.below }
+    : common;
+}
+
+/**
+ * What a command of one version is to a console of another: within the range and the same
+ * (`current`), older (`behind`) or newer (`ahead`), which the console answers; or outside it,
+ * older (`outdated`) or newer (`too_new`), which the console refuses.
+ */
+export type ClientVerdict = "current" | "behind" | "ahead" | "outdated" | "too_new";
+
+export interface ClientJudgement {
+  readonly verdict: ClientVerdict;
+  readonly range: VersionRange;
+}
+
+export function judgeClient(
+  client: Version,
+  server: Version,
+  policy: ClientPolicy = CLIENT_POLICY,
+): ClientJudgement {
+  const range = clientRange(server, policy);
+  const order = compareVersions(client, server);
+  const refused = (policy.refused ?? []).some((text) => {
+    const version = parseVersion(text);
+    return version !== undefined && compareVersions(version, client) === 0;
+  });
+  if (refused) {
+    return { verdict: order > 0 ? "too_new" : "outdated", range };
+  }
+  if (compareVersions(client, range.atLeast) < 0) {
+    return { verdict: "outdated", range };
+  }
+  if (compareVersions(client, range.below) >= 0) {
+    return { verdict: "too_new", range };
+  }
+  return { verdict: order === 0 ? "current" : order < 0 ? "behind" : "ahead", range };
+}
+
+/** What the command sends as its user-agent: its product token, and, in a comment, where it runs. */
+export function userAgentOf(version: string, comment?: string): string {
+  // A comment holds printable ASCII without parentheses or backslashes; nothing else is said.
+  const safe = comment?.replaceAll(/[^\x20-\x27\x2a-\x5b\x5d-\x7e]/g, "").trim();
+  return `${CLIENT_PRODUCT}/${version}${safe === undefined || safe.length === 0 ? "" : ` (${safe})`}`;
+}
+
+const MAX_USER_AGENT_LENGTH = 512;
+const CLIENT_TOKEN = new RegExp(
+  `(?:^|\\s)${CLIENT_PRODUCT}/(\\d{1,9}\\.\\d{1,9}\\.\\d{1,9})(?![\\w.-])`,
+);
+
+/** The version of the command a request's user-agent names, or nothing for any other client. */
+export function clientVersionOf(userAgent: string | null | undefined): Version | undefined {
+  if (typeof userAgent !== "string") {
+    return undefined;
+  }
+  return parseVersion(CLIENT_TOKEN.exec(userAgent.slice(0, MAX_USER_AGENT_LENGTH))?.[1]);
+}