@skillcdn/console 0.1.17 → 0.1.19

package/src/cli/cli.ts

@@ -7,6 +7,7 @@ import {
   type FetchLike,
   type ProjectClient,
 } from "../client.js";
+import { CLIENT_RANGE_HEADER, judgeClient, parseVersion, VERSION_HEADER } from "../compat.js";
 import { addDays, dayOf as dayOfDate, isDay } from "../dates.js";
 import { DEFAULT_PAGE_LIMIT, LIST_LIMIT, MAX_OPTIONS, MIN_OPTIONS } from "../limits.js";
 import { fillRules, RULES_PATH, RULES_TITLE } from "../rules.js";
@@ -14,7 +15,11 @@ import {
   hostOfLogin,
   type RestClaim,
   type RestDecision,
+  type RestMember,
   type RestPerson,
+  type RestSkillFile,
+  type RestSkillLoad,
+  type RestSkillPage,
   type RestTaskPatch,
 } from "../schemas.js";
 import {
@@ -36,8 +41,18 @@ import {
   type TaskState,
 } from "../vocabulary.js";
 import { loadWebRoot, type WebRoot, WebRootError } from "../web.js";
-import type { CredentialStore } from "./credentials.js";
-import type { DirectoryStore } from "./directory.js";
+import {
+  type CredentialStore,
+  type Credentials,
+  CredentialsError,
+  EMPTY_CREDENTIALS,
+  loginsAt,
+  type Resolution,
+  resolveLogin,
+  withLogin,
+  withoutLogin,
+} from "./credentials.js";
+import type { DirectorySettings, DirectoryStore } from "./directory.js";
 import {
   formatAnswer,
   formatCategoryLine,
@@ -59,6 +74,8 @@ import {
   formatRules,
   formatRun,
   formatRunLine,
+  formatSkillFile,
+  formatSkillLoad,
   formatSkills,
   formatTask,
   formatTaskLine,
@@ -67,6 +84,8 @@ import {
   formatWork,
 } from "./format.js";
 import { COMMAND_HELP, helpFor, usage } from "./help.js";
+import { describeInstall, type Install, updateCommandFor } from "./install.js";
+import type { NoticeStore } from "./notices.js";
 import { createServeHandler, DEFAULT_SERVE_PORT, type Listen } from "./serve.js";
 
 // The `console` command (docs/specs/cli.md): the agent's side of the console. A thin client of
@@ -84,8 +103,13 @@ export const EXIT = {
   usage: 2,
   /** The decision still waits for a person. */
   waiting: 3,
+  /** The command and the console do not go together (ADR-0025): stderr says which to update, and how. */
+  incompatible: 4,
 } as const;
 
+/** A day, for how often the command repeats what it noticed of the versions. */
+const DAY_MS = 86_400_000;
+
 /** How long one request for a decision's answer asks the console to hold it: what the server allows. */
 const WAIT_STEP_SECONDS = 50;
 /** A breath between two such requests, should the console answer at once. */
@@ -117,6 +141,12 @@ export interface CliIo {
   readonly now: () => number;
   /** The version of the package the command runs from, when the entry point knows it. */
   readonly version?: string | undefined;
+  /** What the command calls itself on every request (ADR-0025); nothing when it does not know its version. */
+  readonly userAgent?: string | undefined;
+  /** Where the command is installed, so that an update is told the way it takes effect; nothing when unknown. */
+  readonly install?: Install | undefined;
+  /** What the command last said of the versions; left out, it says it every time. */
+  readonly notices?: NoticeStore | undefined;
   /** Where the console's own skills are on this machine, shipped with the package; nothing when they are not there. */
   readonly skillsDir?: string | undefined;
   /** How `serve` listens on the loopback (ADR-0014); left out, the command cannot serve. */
@@ -144,6 +174,7 @@ type OptionSpec = Readonly<
 const GLOBAL_OPTIONS: OptionSpec = {
   json: { type: "boolean" },
   url: { type: "string" },
+  account: { type: "string" },
   project: { type: "string" },
 };
 
@@ -180,6 +211,12 @@ interface Session {
   readonly url: string;
   /** The token the client holds: what `serve` carries the page's requests with. */
   readonly token: string;
+  /** The person's login at the console, when the login kept knows it. */
+  readonly account: string | undefined;
+  /** Where the token came from: the environment's pair, or a login kept here. */
+  readonly via: "environment" | "login";
+  /** What the command keeps, as it was read for this command. */
+  readonly credentials: Credentials | undefined;
   readonly json: boolean;
   /** The project the command works in: named by `--project`, the environment, or the working directory. */
   project(): Promise<ProjectClient>;
@@ -190,23 +227,85 @@ interface Session {
 const NO_PROJECT =
   "Say which project: --project <key>, CONSOLE_PROJECT in the environment, or console use <key> once in this directory. console projects lists the projects you may work in.";
 
-/** The console and the token to talk to it with: the flags, the environment, then what login kept. */
+/** What the command keeps, or nothing; a file that cannot be read stops the command, and is never written over. */
+async function loadCredentials(io: CliIo): Promise<Credentials | undefined> {
+  try {
+    return await io.store.load();
+  } catch (error) {
+    if (error instanceof CredentialsError) {
+      throw failed(
+        `${error.message} Move it away, then sign in again: console login --url <the console's origin>`,
+      );
+    }
+    throw error;
+  }
+}
+
+/** The console a directory is bound to, as an origin, when it names one. */
+function directoryOrigin(settings: DirectorySettings | undefined): string | undefined {
+  if (settings?.url === undefined) {
+    return undefined;
+  }
+  try {
+    return originOf(settings.url);
+  } catch {
+    throw failed(`.skillcdn-console.json names a console that is not an origin: ${settings.url}`);
+  }
+}
+
+/** Why no console could be talked to, for the person who reads it. */
+function wordsOf(failure: Exclude<Resolution, { ok: true }>): string {
+  switch (failure.reason) {
+    case "nothing":
+      return "Not signed in. A person signs the command in: console login --url <the console's origin>";
+    case "environment_half":
+      return `Both CONSOLE_URL and CONSOLE_TOKEN are needed in the environment, and only ${failure.have} is set: set both, or neither.`;
+    case "no_login": {
+      const whom = failure.account === undefined ? "" : ` as ${failure.account}`;
+      const where =
+        failure.source === "directory"
+          ? `This directory works at ${failure.url}${whom}, where nobody is signed in here`
+          : `Nobody is signed in here at ${failure.url}${whom}`;
+      return `${where}: console login --url ${failure.url}. console logins lists the consoles signed in.`;
+    }
+    case "ambiguous":
+      return `Several accounts are signed in at ${failure.url} (${failure.accounts.join(", ")}): say which with --account <login>, or bind this directory to one with console use <key> --account <login>.`;
+  }
+}
+
+/**
+ * The console a command talks to, and with what (ADR-0027): the address from the flag, the
+ * environment, the directory or the default login, in that order, and then the token kept for
+ * that address and no other. A token never travels to a console it was not made at.
+ */
 async function open(io: CliIo, values: Values): Promise<Session> {
-  const stored = await io.store.load();
-  const url = text(values, "url") ?? io.env.CONSOLE_URL ?? stored?.url;
-  const token = io.env.CONSOLE_TOKEN ?? stored?.token;
-  if (url === undefined || token === undefined) {
-    throw failed(
-      "Not signed in. A person signs the command in: console login --url <the console's origin>",
-    );
+  const directory = await io.directory.load();
+  const flag = text(values, "url");
+  const envUrl = io.env.CONSOLE_URL;
+  const credentials = await loadCredentials(io);
+  const resolved = resolveLogin({
+    flagUrl: flag === undefined ? undefined : originOf(flag),
+    flagAccount: text(values, "account"),
+    envUrl: envUrl === undefined ? undefined : originOf(envUrl),
+    envToken: io.env.CONSOLE_TOKEN,
+    directoryUrl: directoryOrigin(directory),
+    directoryAccount: directory?.account,
+    credentials,
+  });
+  if (!resolved.ok) {
+    throw failed(wordsOf(resolved));
   }
-  const client = createClient({ baseUrl: url, token, fetch: io.fetch });
+  const { url, token } = resolved;
+  const client = clientOf(io, url, token);
   const projectKey = async () =>
-    text(values, "project") ?? io.env.CONSOLE_PROJECT ?? (await io.directory.load())?.project;
+    text(values, "project") ?? io.env.CONSOLE_PROJECT ?? directory?.project;
   return {
     client,
     url,
     token,
+    account: resolved.account,
+    via: resolved.via,
+    credentials,
     json: on(values, "json"),
     projectKey,
     async project() {
@@ -258,6 +357,9 @@ async function bodyOf(
   return given === "-" ? io.readStdin() : given;
 }
 
+/** The hosts a token may travel to in the clear: this machine, and no other. */
+const LOOPBACK_HOSTS: ReadonlySet<string> = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
 function originOf(value: string): string {
   const url = URL.canParse(value) ? new URL(value) : undefined;
   if (
@@ -271,6 +373,12 @@ function originOf(value: string): string {
       `Not an origin: ${value}. Say the console's address without a path, such as https://console.example.com`,
     );
   }
+  // A token travels over https; in the clear only to this machine, where a console is run for development.
+  if (url.protocol === "http:" && !LOOPBACK_HOSTS.has(url.hostname)) {
+    throw misuse(
+      `Not a safe origin: ${value}. A token travels over https only; http is for a console on this machine (localhost).`,
+    );
+  }
   return url.origin;
 }
 
@@ -503,18 +611,40 @@ async function settle(
 
 type Command = (args: readonly string[], io: CliIo) => Promise<number>;
 
-/** Checks a token against the console, keeps it with the address, and says who it is. */
-async function keep(io: CliIo, url: string, token: string, agent?: string): Promise<number> {
-  const me = await createClient({ baseUrl: url, token, fetch: io.fetch }).me();
+/**
+ * Checks a token against the console, keeps it as the login at that console for that account,
+ * and says who it is. A token the login replaces is given up at the console on the way.
+ */
+async function keep(
+  io: CliIo,
+  url: string,
+  token: string,
+  agent: string | undefined,
+  asDefault: boolean,
+): Promise<number> {
+  const me = await clientOf(io, url, token).me();
   const person = me.person;
   if (person === null) {
     throw failed(
       "The console does not know this token. Make one on your Agents page and try again.",
     );
   }
-  const kept = await io.store.save({ url, token });
+  const credentials = (await loadCredentials(io)) ?? EMPTY_CREDENTIALS;
+  const replaced = loginsAt(credentials, url).find((login) => login.account === person.login);
+  if (replaced !== undefined && replaced.token !== token) {
+    await clientOf(io, url, replaced.token)
+      .giveUpToken()
+      .catch(() => undefined);
+  }
+  const next = withLogin(
+    credentials,
+    { url, account: person.login, token, agent, since: new Date(io.now()).toISOString() },
+    { default: asDefault },
+  );
+  const kept = await io.store.save(next);
+  const standing = next.default === url ? ", the default console here" : "";
   io.stdout(
-    `${agent === undefined ? "Signed in" : `Connected as "${agent}"`} to ${me.workspace.name} at ${url} as ${person.login} (${person.role}). The token is kept in ${kept}.\nNext, say which project this directory works in: console use <key> (console projects lists them).\n`,
+    `${agent === undefined ? "Signed in" : `Connected as "${agent}"`} to ${me.workspace.name} at ${url} as ${person.login} (${person.role})${standing}. The token is kept in ${kept}.\nNext, say which project this directory works in: console use <key> (console projects lists them).\n`,
   );
   return EXIT.ok;
 }
@@ -522,25 +652,26 @@ async function keep(io: CliIo, url: string, token: string, agent?: string): Prom
 const login: Command = async (args, io) => {
   const { values } = parse(
     args,
-    { "token-stdin": { type: "boolean" }, agent: { type: "string" } },
+    { "token-stdin": { type: "boolean" }, agent: { type: "string" }, default: { type: "boolean" } },
     false,
   );
-  const stored = await io.store.load();
-  const wanted = text(values, "url") ?? io.env.CONSOLE_URL ?? stored?.url;
+  const credentials = await loadCredentials(io);
+  const wanted = text(values, "url") ?? io.env.CONSOLE_URL ?? credentials?.default;
   if (wanted === undefined) {
     throw misuse("Say where the console is: console login --url https://console.example.com");
   }
   const url = originOf(wanted);
+  const asDefault = on(values, "default");
   if (on(values, "token-stdin")) {
     const token = (await io.readStdin()).trim();
     if (token.length === 0) {
       throw failed("No token was given.");
     }
-    return keep(io, url, token);
+    return keep(io, url, token, undefined, asDefault);
   }
   // A connection (ADR-0011): a code a person approves on the console's own pages, and the token
   // handed over here once, never shown.
-  const client = createClient({ baseUrl: url, fetch: io.fetch });
+  const client = clientOf(io, url);
   // "<agent> on <machine>": the pages say the agent and keep the machine for a hover.
   const agent = text(values, "agent") ?? agentOf(io.env) ?? "An agent";
   const begun = await client.connect({
@@ -563,40 +694,110 @@ const login: Command = async (args, io) => {
       throw error;
     }
     if (claim.status === "connected") {
-      return keep(io, url, claim.secret, claim.token.name);
+      return keep(io, url, claim.secret, claim.token.name, asDefault);
     }
   }
 };
 
 const logout: Command = async (args, io) => {
-  parse(args, {}, false);
-  const stored = await io.store.load();
-  const url = io.env.CONSOLE_URL ?? stored?.url;
-  const token = io.env.CONSOLE_TOKEN ?? stored?.token;
-  if (url === undefined || token === undefined) {
+  const { values } = parse(args, {}, false);
+  const credentials = await loadCredentials(io);
+  const directory = await io.directory.load();
+  const envNote = () => {
+    if (io.env.CONSOLE_TOKEN !== undefined) {
+      io.stdout("CONSOLE_TOKEN in the environment still holds a token: unset it.\n");
+    }
+  };
+  if (credentials === undefined || credentials.logins.length === 0) {
     io.stdout("Not signed in here: nothing to forget.\n");
+    envNote();
     return EXIT.ok;
   }
+  // Which login: the console the flag names, else the directory's, else the default, else the
+  // one console signed in to; and the account the same way, where the console has several.
+  const consoles = [...new Set(credentials.logins.map((login) => login.url))];
+  const flag = text(values, "url");
+  const url =
+    flag === undefined
+      ? (directoryOrigin(directory) ??
+        credentials.default ??
+        (consoles.length === 1 ? consoles[0] : undefined))
+      : originOf(flag);
+  if (url === undefined) {
+    throw failed(
+      `Several consoles are signed in here; say which: console logout --url <origin>. console logins lists them.`,
+    );
+  }
+  const account = text(values, "account") ?? directory?.account;
+  const at = loginsAt(credentials, url);
+  const chosen = account === undefined ? at : at.filter((login) => login.account === account);
+  const [login] = chosen;
+  if (login === undefined) {
+    throw failed(
+      `Nobody is signed in here at ${url}${account === undefined ? "" : ` as ${account}`}: nothing to forget. console logins lists the consoles signed in.`,
+    );
+  }
+  if (chosen.length > 1) {
+    throw failed(
+      `Several accounts are signed in at ${url} (${chosen.map((kept) => kept.account ?? "?").join(", ")}); say which: console logout --url ${url} --account <login>`,
+    );
+  }
   // The token is given up at the console first, so that it is good for nothing from now on;
   // one the console no longer knows is gone already. A console out of reach leaves it to the
   // Agents page, and the person is told so.
   let gone = true;
   try {
-    await createClient({ baseUrl: url, token, fetch: io.fetch }).giveUpToken();
+    await clientOf(io, url, login.token).giveUpToken();
   } catch (error) {
     if (!(error instanceof ApiError && error.code === "auth.required")) {
       gone = false;
     }
   }
-  await io.store.clear();
+  const next = withoutLogin(credentials, url, login.account);
+  if (next.logins.length === 0) {
+    await io.store.clear();
+  } else {
+    await io.store.save(next);
+  }
+  const whom = login.account === undefined ? "" : ` as ${login.account}`;
   io.stdout(
     gone
-      ? "Signed out: the token is given up at the console and forgotten here.\n"
-      : `Signed out here, but the console at ${url} could not be reached to give the token up: a person removes it on the Agents page.\n`,
+      ? `Signed out of ${url}${whom}: the token is given up at the console and forgotten here.\n`
+      : `Signed out of ${url}${whom} here, but the console could not be reached to give the token up: a person removes it on the Agents page.\n`,
   );
-  if (io.env.CONSOLE_TOKEN !== undefined) {
-    io.stdout("CONSOLE_TOKEN in the environment still holds it: unset it.\n");
+  envNote();
+  return EXIT.ok;
+};
+
+/** The consoles this machine is signed in to, with the account at each; never a token. */
+const logins: Command = async (args, io) => {
+  const { values } = parse(args, {}, false);
+  const credentials = await loadCredentials(io);
+  const kept = (credentials?.logins ?? []).map((login) => ({
+    url: login.url,
+    account: login.account ?? null,
+    agent: login.agent ?? null,
+    since: login.since ?? null,
+    default: credentials?.default === login.url,
+  }));
+  if (on(values, "json")) {
+    io.stdout(
+      `${JSON.stringify({ default: credentials?.default ?? null, logins: kept }, null, 2)}\n`,
+    );
+    return EXIT.ok;
   }
+  if (kept.length === 0) {
+    io.stdout("Not signed in anywhere here: console login --url <the console's origin>\n");
+    return EXIT.ok;
+  }
+  io.stdout(
+    `${kept
+      .map(
+        (login) =>
+          `${login.url}  ${login.account ?? "(account unknown)"}${login.agent === null ? "" : `  ${login.agent}`}${login.since === null ? "" : `  since ${login.since.slice(0, 10)}`}${login.default ? "  (default)" : ""}`,
+      )
+      .join("\n")}\n`,
+  );
   return EXIT.ok;
 };
 
@@ -620,12 +821,38 @@ const whoami: Command = async (args, io) => {
     throw failed("The console does not know this token. Sign in again: console login");
   }
   const key = await session.projectKey();
+  const command = parseVersion(io.version);
+  const server = parseVersion(me.console?.version);
+  const verdict =
+    command === undefined || server === undefined
+      ? undefined
+      : judgeClient(command, server).verdict;
+  // A console from before the rule says nothing of itself; the command says so instead.
+  const consoleWords =
+    me.console === undefined
+      ? "the console does not say its version, so it is older than 0.1.18"
+      : `the console is ${me.console.version} and takes ${me.console.clientRange}`;
   answer(
     io,
     session,
-    { ...me, project: key ?? null },
+    {
+      ...me,
+      console: me.console ?? null,
+      project: key ?? null,
+      command: { version: io.version ?? null, install: io.install ?? null },
+    },
     () =>
-      `${person.login} (${person.role}) at ${me.workspace.name}, ${session.url}${key === undefined ? "; no project named here" : `; project ${key}`}`,
+      [
+        `${person.login} (${person.role}) at ${me.workspace.name}, ${session.url}${key === undefined ? "; no project named here" : `; project ${key}`}`,
+        `This command is ${io.version ?? "of a version it does not know"}${io.install === undefined ? "" : `, ${describeInstall(io.install)}`}; ${consoleWords}.`,
+        ...(verdict === "behind"
+          ? [`A newer command exists. Update it: ${updateWords(io, me.console?.version)}`]
+          : verdict === "ahead"
+            ? [
+                `This command is newer than the console: what the console has not got yet is refused as not found. To match the console: ${updateWords(io, me.console?.version)}`,
+              ]
+            : []),
+      ].join("\n"),
   );
   return EXIT.ok;
 };
@@ -644,16 +871,35 @@ const projects: Command = async (args, io) => {
 
 const use: Command = async (args, io) => {
   const { values, positionals } = parse(args, {});
-  const key = theOne(positionals, "Say which project: console use <key>");
+  const key = theOne(
+    positionals,
+    "Say which project: console use <key> [--url <origin>] [--account <login>]",
+  );
   const session = await open(io, values);
   const project = await session.client.project(key).get();
-  const kept = await io.directory.save({ project: project.key });
+  // The directory names the console where that is not the default login here, or when asked,
+  // and the account where the console has several, or when asked; never a token.
+  const credentials = session.credentials ?? EMPTY_CREDENTIALS;
+  const pinUrl =
+    text(values, "url") !== undefined ||
+    (session.via === "login" && credentials.default !== session.url);
+  const pinAccount =
+    text(values, "account") !== undefined ||
+    (session.via === "login" && loginsAt(credentials, session.url).length > 1);
+  const kept = await io.directory.save({
+    project: project.key,
+    ...(pinUrl ? { url: session.url } : {}),
+    ...(pinAccount && session.account !== undefined ? { account: session.account } : {}),
+  });
+  const bound = pinUrl
+    ? ` at ${session.url}${pinAccount && session.account !== undefined ? ` as ${session.account}` : ""}`
+    : "";
   answer(
     io,
     session,
     project,
     () =>
-      `Working in ${project.name} (${project.key}) from this directory on: kept in ${kept}, which is meant to be committed. What its people ask of agents: console rules.`,
+      `Working in ${project.name} (${project.key})${bound} from this directory on: kept in ${kept}, which is meant to be committed in a private repository and left out of a public one. What its people ask of agents: console rules.`,
   );
   return EXIT.ok;
 };
@@ -665,14 +911,21 @@ const tasks: Command = async (args, io) => {
       state: { type: "string" },
       open: { type: "boolean" },
       mine: { type: "boolean" },
+      unassigned: { type: "boolean" },
       category: { type: "string" },
       goal: { type: "string" },
       due: { type: "string" },
+      archived: { type: "boolean" },
       ...PAGE_OPTIONS,
     },
     false,
   );
   const state = stateOf(text(values, "state"));
+  if (on(values, "mine") && on(values, "unassigned")) {
+    throw misuse(
+      "Say one: --mine for the tasks assigned to you, or --unassigned for those assigned to nobody",
+    );
+  }
   const page = pageOf(values);
   const session = await open(io, values);
   const project = await session.project();
@@ -694,9 +947,11 @@ const tasks: Command = async (args, io) => {
     ...(state === undefined ? {} : { state }),
     ...(on(values, "open") || due === "overdue" ? { open: true } : {}),
     ...(assignee === undefined ? {} : { assignee }),
+    ...(on(values, "unassigned") ? { unassigned: true } : {}),
     ...(text(values, "category") === undefined ? {} : { category: text(values, "category") }),
     ...(text(values, "goal") === undefined ? {} : { goal: text(values, "goal") }),
     ...(dueBy === undefined ? {} : { dueBy }),
+    ...(on(values, "archived") ? { archived: true } : {}),
     ...page,
   });
   answer(io, session, found, () =>
@@ -743,6 +998,65 @@ const skills: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/** How many pages of a skill, or of a file, the command follows before it stops: far above what one holds. */
+const MAX_SKILL_PAGES = 64;
+
+const skill: Command = async (args, io) => {
+  const { values, positionals } = parse(args, { file: { type: "string" } });
+  const path = theOne(
+    positionals,
+    "Say which skill: console skill <path of its SKILL.md> [--file <path>]",
+  );
+  const session = await open(io, values);
+  const project = await session.project();
+  const file = text(values, "file");
+  if (file !== undefined) {
+    // The file whole, page after page, as the console reads it from the deployment.
+    const parts: string[] = [];
+    let offset: number | undefined;
+    let last: RestSkillFile | undefined;
+    for (let pages = 0; pages < MAX_SKILL_PAGES; pages += 1) {
+      last = await project.skillFile(file, offset === undefined ? {} : { offset });
+      if (last.status !== "ready" || last.file === null) {
+        break;
+      }
+      parts.push(last.file.content);
+      if (last.file.nextOffset === null) {
+        break;
+      }
+      offset = last.file.nextOffset;
+    }
+    if (last === undefined) {
+      throw failed("The file could not be read.");
+    }
+    const read = last;
+    const content = parts.join("");
+    answer(io, session, { ...read, content }, () => formatSkillFile(read, content));
+    return EXIT.ok;
+  }
+  // The skill whole: its pages until complete, the rules first, as load_skill lays them out.
+  const pages: RestSkillPage[] = [];
+  let cursor: string | undefined;
+  let last: RestSkillLoad | undefined;
+  for (let n = 0; n < MAX_SKILL_PAGES; n += 1) {
+    last = await project.skill(path, cursor);
+    if (last.status !== "ready" || last.skill === null) {
+      break;
+    }
+    pages.push(last.skill);
+    if (last.skill.complete || last.skill.nextCursor === null) {
+      break;
+    }
+    cursor = last.skill.nextCursor;
+  }
+  if (last === undefined) {
+    throw failed("The skill could not be read.");
+  }
+  const loaded = last;
+  answer(io, session, { ...loaded, pages }, () => formatSkillLoad(loaded, pages));
+  return EXIT.ok;
+};
+
 /** A version number given as a flag, or nothing; anything else is not understood. */
 function versionOf(given: string | undefined): number | undefined {
   if (given === undefined) {
@@ -943,6 +1257,45 @@ const editTask: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/** Puts a task away, or every done or dropped task of a goal (ADR-0029); the task by its number or its id. */
+const taskArchive: Command = async (args, io) => {
+  const { values, positionals } = parse(args, { goal: { type: "string" } });
+  const goal = text(values, "goal");
+  if (positionals.length > 1 || (positionals.length === 0) === (goal === undefined)) {
+    throw misuse(
+      "Say which: console task archive <number|id>, or console task archive --goal <id> for every done or dropped task of a goal",
+    );
+  }
+  const session = await open(io, values);
+  const project = await session.project();
+  if (goal !== undefined) {
+    const { archived } = await project.archiveTasksOfGoal(goal);
+    answer(
+      io,
+      session,
+      { archived },
+      () => `${archived} ${archived === 1 ? "task" : "tasks"} of the goal put away.`,
+    );
+    return EXIT.ok;
+  }
+  const found = await project.task(positionals[0] ?? "");
+  const archived = await project.archiveTask(found.id);
+  answer(io, session, archived, () => formatTaskLine(archived));
+  return EXIT.ok;
+};
+
+/** Brings a task back from the archive. */
+const taskRestore: Command = async (args, io) => {
+  const { values, positionals } = parse(args, {});
+  const ref = theOne(positionals, "Say which task: console task restore <number|id>");
+  const session = await open(io, values);
+  const project = await session.project();
+  const found = await project.task(ref);
+  const restored = await project.restoreTask(found.id);
+  answer(io, session, restored, () => formatTaskLine(restored));
+  return EXIT.ok;
+};
+
 const task: Command = async (args, io) => {
   if (args[0] === "new") {
     return newTask(args.slice(1), io);
@@ -950,6 +1303,12 @@ const task: Command = async (args, io) => {
   if (args[0] === "edit") {
     return editTask(args.slice(1), io);
   }
+  if (args[0] === "archive") {
+    return taskArchive(args.slice(1), io);
+  }
+  if (args[0] === "restore") {
+    return taskRestore(args.slice(1), io);
+  }
   const { values, positionals } = parse(args, {});
   const ref = theOne(positionals, "Say which task: console task <number|id>");
   const session = await open(io, values);
@@ -1417,13 +1776,24 @@ const restore: Command = async (args, io) => {
 };
 
 const goals: Command = async (args, io) => {
-  const { values } = parse(args, {}, false);
+  const { values } = parse(
+    args,
+    { category: { type: "string" }, state: { type: "string" } },
+    false,
+  );
+  const state = goalStateOf(text(values, "state"));
+  const category = text(values, "category");
   const session = await open(io, values);
   const project = await session.project();
-  const found = await project.goals();
+  const found = await project.goals({
+    ...(state === undefined ? {} : { state }),
+    ...(category === undefined ? {} : { category }),
+  });
   answer(io, session, found, () =>
     found.items.length === 0
-      ? "No goals. An owner sets one: console goal new <title> --due <day>"
+      ? state === undefined && category === undefined
+        ? "No goals. An owner sets one: console goal new <title> --due <day>"
+        : "No goal matches."
       : found.items.map(formatGoalLine).join("\n"),
   );
   return EXIT.ok;
@@ -1431,15 +1801,24 @@ const goals: Command = async (args, io) => {
 
 const GOAL_FIELDS: OptionSpec = {
   state: { type: "string" },
+  category: { type: "string" },
+  starts: { type: "string" },
   due: { type: "string" },
   body: { type: "string" },
   file: { type: "string" },
 };
 
+/** A category's key as a flag names one, or `null` for `none` where the field may be cleared. */
+function categoryOf(value: string | undefined, clearable = false): string | null | undefined {
+  return clearable && value === "none" ? null : value;
+}
+
 const newGoal: Command = async (args, io) => {
   const { values, positionals } = parse(args, GOAL_FIELDS);
   const title = theOne(positionals, 'Say the title: console goal new "<title>" [--due <day>]');
   const state = goalStateOf(text(values, "state"));
+  const category = categoryOf(text(values, "category"));
+  const startsOn = dayOf(io, text(values, "starts"));
   const dueOn = dayOf(io, text(values, "due"));
   const body = await bodyOf(io, values, text(values, "body"));
   const session = await open(io, values);
@@ -1448,6 +1827,8 @@ const newGoal: Command = async (args, io) => {
     title,
     ...(body === undefined ? {} : { body }),
     ...(state === undefined ? {} : { state }),
+    ...(category === undefined ? {} : { category }),
+    ...(startsOn === undefined ? {} : { startsOn }),
     ...(dueOn === undefined ? {} : { dueOn }),
   });
   answer(io, session, made, () => `Goal set: ${made.title}\nid: ${made.id}`);
@@ -1459,17 +1840,21 @@ const editGoal: Command = async (args, io) => {
   const id = theOne(positionals, "Say which goal: console goal edit <id> --state <state> ...");
   const title = text(values, "title");
   const state = goalStateOf(text(values, "state"));
+  const category = categoryOf(text(values, "category"), true);
+  const startsOn = dayOf(io, text(values, "starts"), true);
   const dueOn = dayOf(io, text(values, "due"), true);
   const body = await bodyOf(io, values, text(values, "body"));
   const patch = {
     ...(title === undefined ? {} : { title }),
     ...(body === undefined ? {} : { body }),
     ...(state === undefined ? {} : { state }),
+    ...(category === undefined ? {} : { category }),
+    ...(startsOn === undefined ? {} : { startsOn }),
     ...(dueOn === undefined ? {} : { dueOn }),
   };
   if (Object.keys(patch).length === 0) {
     throw misuse(
-      "Say what to change: --title, --body, --state or --due; --due none clears the day.",
+      "Say what to change: --title, --body, --state, --category, --starts or --due; none clears a category or a day.",
     );
   }
   const session = await open(io, values);
@@ -1805,6 +2190,37 @@ const editProject: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/** The pack token (ADR-0028): read from standard input and never from an argument, so that no shell keeps it. */
+const projectPackToken: Command = async (args, io) => {
+  const { values, positionals } = parse(args, {
+    stdin: { type: "boolean" },
+    remove: { type: "boolean" },
+  });
+  const key = theOne(
+    positionals,
+    "Say which project: console project pack-token <key> --stdin, or console project pack-token <key> --remove",
+  );
+  if (on(values, "stdin") === on(values, "remove")) {
+    throw misuse(
+      "Say one of --stdin, which reads the token from standard input, and --remove, which takes it away.",
+    );
+  }
+  const session = await open(io, values);
+  const project = session.client.project(key);
+  if (on(values, "remove")) {
+    const changed = await project.removePackToken();
+    answer(io, session, changed, () => formatProject(changed));
+    return EXIT.ok;
+  }
+  const token = (await io.readStdin()).trim();
+  if (token.length === 0) {
+    throw failed("No token was given on standard input.");
+  }
+  const changed = await project.setPackToken({ token });
+  answer(io, session, changed, () => formatProject(changed));
+  return EXIT.ok;
+};
+
 const projectIcon: Command = async (args, io) => {
   const { values, positionals } = parse(args, { remove: { type: "boolean" } });
   const [key, file] = positionals;
@@ -1838,10 +2254,13 @@ const project: Command = async (args, io) => {
   if (args[0] === "icon") {
     return projectIcon(args.slice(1), io);
   }
+  if (args[0] === "pack-token") {
+    return projectPackToken(args.slice(1), io);
+  }
   const { values, positionals } = parse(args, {});
   const key = theOne(
     positionals,
-    "Say which project: console project <key>; or console project new, edit or icon",
+    "Say which project: console project <key>; or console project new, edit, icon or pack-token",
   );
   const session = await open(io, values);
   const found = await session.client.project(key).get();
@@ -1862,18 +2281,59 @@ const members: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/** The keys --project names with commas, each once, or nothing when it names one project or none. */
+function projectKeysOf(value: string | undefined): readonly string[] | undefined {
+  if (value === undefined || !value.includes(",")) {
+    return undefined;
+  }
+  const keys = [...new Set(value.split(",").map((key) => key.trim()))].filter((key) => key !== "");
+  if (keys.length === 0) {
+    throw misuse("Say which projects: --project <key>[,<key>...]");
+  }
+  return keys;
+}
+
 const member: Command = async (args, io) => {
   const [verb, ...rest] = args;
   if (verb === "add") {
     const { values, positionals } = parse(rest, { role: { type: "string" } });
-    const login = theOne(positionals, "Say whom: console member add <login> [--role owner|member]");
+    const login = theOne(
+      positionals,
+      "Say whom: console member add <login> [--role owner|member] [--project <key>[,<key>...]]",
+    );
     const role = text(values, "role");
     const session = await open(io, values);
-    const project = await session.project();
-    const added = await project.addMember({
+    const input = {
       personId: (await personOf(session, login)).id,
       ...(role === undefined ? {} : { role: projectRoleOf(role) }),
-    });
+    };
+    // Several projects at once, where --project names them with commas: the person is listed
+    // in each in turn, one listed already is said so, and the rest go on.
+    const keys = projectKeysOf(text(values, "project"));
+    if (keys !== undefined) {
+      const added: { readonly project: string; readonly member: RestMember | null }[] = [];
+      for (const key of keys) {
+        try {
+          added.push({ project: key, member: await session.client.project(key).addMember(input) });
+        } catch (error) {
+          if (!(error instanceof ApiError && error.code === "member.exists")) {
+            throw error;
+          }
+          added.push({ project: key, member: null });
+        }
+      }
+      answer(io, session, added, () =>
+        added
+          .map(
+            ({ project, member }) =>
+              `${project}  ${member === null ? `${login} is listed already` : formatMemberLine(member)}`,
+          )
+          .join("\n"),
+      );
+      return EXIT.ok;
+    }
+    const project = await session.project();
+    const added = await project.addMember(input);
     answer(io, session, added, () => formatMemberLine(added));
     return EXIT.ok;
   }
@@ -1908,7 +2368,7 @@ const member: Command = async (args, io) => {
     return EXIT.ok;
   }
   throw misuse(
-    "Say what to do: console member add <login> [--role owner|member], console member role <login> <owner|member>, or console member remove <login>",
+    "Say what to do: console member add <login> [--role owner|member] [--project <key>[,<key>...]], console member role <login> <owner|member>, or console member remove <login>",
   );
 };
 
@@ -1968,6 +2428,7 @@ const category: Command = async (args, io) => {
 
 const COMMANDS: Readonly<Record<string, Command>> = {
   login,
+  logins,
   logout,
   whoami,
   serve,
@@ -1980,6 +2441,7 @@ const COMMANDS: Readonly<Record<string, Command>> = {
   goal,
   categories,
   skills,
+  skill,
   rules,
   people,
   person,
@@ -2021,9 +2483,85 @@ function help(io: CliIo, name: string | undefined): number {
   return EXIT.ok;
 }
 
+/**
+ * A client of the console at `url`, naming the command on every request (ADR-0025). A redirect
+ * is not followed: the token goes to the address the command resolved, and nowhere it is sent on to.
+ */
+function clientOf(io: CliIo, url: string, token?: string): ConsoleClient {
+  return createClient({
+    baseUrl: url,
+    fetch: (input, init) => io.fetch(input, { ...init, redirect: "manual" }),
+    ...(token === undefined ? {} : { token }),
+    ...(io.userAgent === undefined ? {} : { userAgent: io.userAgent }),
+  });
+}
+
+/** What the console said of itself on its last answer (ADR-0025): its version, and the range of command versions it takes. */
+interface ConsoleSeen {
+  version?: string | undefined;
+  range?: string | undefined;
+}
+
+/** The command that puts the console's version where this command is installed. */
+function updateWords(io: CliIo, version: string | undefined): string {
+  const wanted = version ?? "latest";
+  if (io.install === undefined) {
+    return `npm install -g @skillcdn/console@${wanted}`;
+  }
+  const command = updateCommandFor(io.install, wanted);
+  return io.install.kind === "project" ? `${command} (in ${io.install.root})` : command;
+}
+
+/**
+ * What the command says of the versions once the console answered: that a newer command exists,
+ * or that this one is newer than the console; once a day for one pair of versions, on stderr,
+ * so that the console's JSON stays what it is. What is out of the range never gets here: the
+ * console refused it, and the refusal says what to do.
+ */
+async function noticeVersions(io: CliIo, seen: ConsoleSeen): Promise<void> {
+  const command = parseVersion(io.version);
+  const server = parseVersion(seen.version);
+  if (
+    io.version === undefined ||
+    seen.version === undefined ||
+    command === undefined ||
+    server === undefined
+  ) {
+    return;
+  }
+  const { verdict } = judgeClient(command, server);
+  if (verdict !== "behind" && verdict !== "ahead") {
+    return;
+  }
+  const previous = await io.notices?.load();
+  const now = io.now();
+  if (
+    previous !== undefined &&
+    previous.command === io.version &&
+    previous.console === seen.version &&
+    now - Date.parse(previous.shownAt) < DAY_MS
+  ) {
+    return;
+  }
+  io.stderr(
+    verdict === "behind"
+      ? `A newer command exists: the console runs ${seen.version}, this command is ${io.version}. Update it: ${updateWords(io, seen.version)}\n`
+      : `This command (${io.version}) is newer than the console (${seen.version}, which takes ${seen.range ?? "an older line"}): what the console has not got yet is refused as not found. The console's operator updates it; to match the console meanwhile: ${updateWords(io, seen.version)}\n`,
+  );
+  await io.notices?.save({
+    command: io.version,
+    console: seen.version,
+    shownAt: new Date(now).toISOString(),
+  });
+}
+
 /** What a refusal of the console is followed by, when there is something to do about it. */
-function hintFor(error: ApiError): string {
+function hintFor(error: ApiError, io: CliIo, seen: ConsoleSeen): string {
   switch (error.code) {
+    case "client.outdated":
+      return `Update the command: ${updateWords(io, seen.version)}\n`;
+    case "client.too_new":
+      return `Install the console's version: ${updateWords(io, seen.version)}; or ask the console's operator to update the console.\n`;
     case "auth.required":
       return "The token is not one the console knows, any more or at all. A person signs the command in again: console login\n";
     case "project.not_found":
@@ -2042,6 +2580,10 @@ function hintFor(error: ApiError): string {
       return "The due day is before the start. Say a due day on or after it.\n";
     case "goal.not_found":
       return "No goal of this project has that id. console goals lists them.\n";
+    case "goal.invalid_category":
+      return "No category has that key. console categories lists them.\n";
+    case "goal.invalid_dates":
+      return "The target day is before the start. Say a target day on or after it.\n";
     case "auth.forbidden":
       return "What was asked is an administrator's, or an owner's of the project, and the person this token acts as is not one here. Hand the step to them.\n";
     case "project.key_taken":
@@ -2082,9 +2624,23 @@ function hintFor(error: ApiError): string {
 /** Runs the command and answers with its exit code. What it prints goes through `io`. */
 export async function runCli(argv: readonly string[], io: CliIo): Promise<number> {
   const [name, ...rest] = argv;
+  // Every answer of the console says its version and the range it takes; the command reads
+  // them off the answers it gets anyway, and asks nothing more (ADR-0025).
+  const seen: ConsoleSeen = {};
+  const watched: CliIo = {
+    ...io,
+    fetch: async (input, init) => {
+      const response = await io.fetch(input, init);
+      seen.version = response.headers.get(VERSION_HEADER) ?? seen.version;
+      seen.range = response.headers.get(CLIENT_RANGE_HEADER) ?? seen.range;
+      return response;
+    },
+  };
   try {
     if (name === "--version" || name === "-v" || name === "version") {
-      io.stdout(`console ${io.version ?? "(version unknown)"} (@skillcdn/console)\n`);
+      io.stdout(
+        `console ${io.version ?? "(version unknown)"} (@skillcdn/console)${io.install === undefined ? "" : `, ${describeInstall(io.install)}`}\n`,
+      );
       return EXIT.ok;
     }
     if (name === undefined || name === "help" || name === "--help" || name === "-h") {
@@ -2097,15 +2653,21 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<number
     if (command === undefined) {
       throw misuse(`Not a command: ${name}. Run: console help`);
     }
-    return await command(rest, io);
+    const exit = await command(rest, watched);
+    if (name !== "whoami") {
+      await noticeVersions(io, seen);
+    }
+    return exit;
   } catch (error) {
     if (error instanceof CliExit) {
       io.stderr(`${error.message}\n`);
       return error.exit;
     }
     if (error instanceof ApiError) {
-      io.stderr(`${error.code}: ${error.message}\n${hintFor(error)}`);
-      return EXIT.failed;
+      io.stderr(`${error.code}: ${error.message}\n${hintFor(error, io, seen)}`);
+      return error.code === "client.outdated" || error.code === "client.too_new"
+        ? EXIT.incompatible
+        : EXIT.failed;
     }
     throw error;
   }