@skillcdn/console 0.4.3 → 0.4.4

package/src/cli/cli.ts

@@ -21,7 +21,13 @@ import {
   formatVersion as versionText,
 } from "../compat.js";
 import { addDays, dayOf as dayOfDate, firstDayOfWeek, isDay, weekOf } from "../dates.js";
-import { DEFAULT_PAGE_LIMIT, LIST_LIMIT, MAX_OPTIONS, MIN_OPTIONS } from "../limits.js";
+import {
+  DEFAULT_PAGE_LIMIT,
+  LIST_LIMIT,
+  MAX_DECIDERS,
+  MAX_OPTIONS,
+  MIN_OPTIONS,
+} from "../limits.js";
 import { capabilityWords } from "../plugin/capabilities.js";
 import { PLUGIN_LIST_LIMIT } from "../plugin/limits.js";
 import { fillRules, RULES_PATH, RULES_TITLE } from "../rules.js";
@@ -77,6 +83,7 @@ import {
 } from "./credentials.js";
 import { type DirectorySettings, type DirectoryStore, THE_SENTENCE } from "./directory.js";
 import {
+  deciderLogins,
   formatAnswer,
   formatCategoryLine,
   formatComment,
@@ -1526,6 +1533,8 @@ const plugin: Command = async (args, io) => {
       );
       return EXIT.ok;
     }
+    case "capabilities":
+      return pluginCapabilities(io, session, client, rest);
     case "settings":
       return pluginSettings(io, session, client, rest);
     case "secret":
@@ -1787,7 +1796,60 @@ function capabilityLines(capabilities: readonly string[]): string[] {
   });
 }
 
-/** Enables a plugin, with consent to every capability it asks, named again; an administrator's. */
+/** The capabilities `--consent` names, given again or with commas between. */
+function capabilitiesNamed(values: Values): string[] {
+  return texts(values, "consent")
+    .flatMap((value) => value.split(","))
+    .map((capability) => capability.trim())
+    .filter((capability) => capability.length > 0);
+}
+
+/** What a plugin requires, and which of what it can go without it holds, as `capabilities` prints it. */
+function capabilitiesHeld(detail: RestPluginDetail): string {
+  const held = detail.consent ?? [];
+  const optional = detail.optionalCapabilities ?? [];
+  const named = (capabilities: readonly string[]) =>
+    capabilities.length === 0 ? "none" : capabilities.join(", ");
+  return [
+    `Capabilities of ${detail.key}:`,
+    `  required: ${named(detail.capabilities)}`,
+    `  optional, on: ${named(optional.filter((capability) => held.includes(capability)))}`,
+    `  optional, off: ${named(optional.filter((capability) => !held.includes(capability)))}`,
+  ].join("\n");
+}
+
+/**
+ * What a plugin holds; with `--consent`, which of the optional capabilities it holds from now on,
+ * `none` for none of them. An administrator's.
+ */
+async function pluginCapabilities(
+  io: CliIo,
+  session: Session,
+  client: PluginClient,
+  rest: readonly string[],
+): Promise<number> {
+  const { values, positionals } = parse(rest, { consent: { type: "string", multiple: true } });
+  if (positionals.length > 0) {
+    throw misuse(
+      `Nothing follows capabilities but --consent: console plugin ${client.key} capabilities [--consent <capability>,...|none]`,
+    );
+  }
+  const detail = await client.get();
+  const named = capabilitiesNamed(values);
+  if (named.length === 0) {
+    answer(io, session, detail, () => capabilitiesHeld(detail));
+    return EXIT.ok;
+  }
+  const chosen = named.filter((capability) => capability !== "none");
+  const changed = await client.updateConsent([
+    ...detail.capabilities,
+    ...chosen.filter((capability) => !detail.capabilities.includes(capability)),
+  ]);
+  answer(io, session, changed, () => capabilitiesHeld(changed));
+  return EXIT.ok;
+}
+
+/** Enables a plugin, with consent to every capability it requires, named again; an administrator's. */
 async function pluginEnable(
   io: CliIo,
   session: Session,
@@ -1807,19 +1869,22 @@ async function pluginEnable(
   }
   const [detail, me] = await Promise.all([client.get(), session.client.me()]);
   const asked = detail.capabilities;
-  const consent = texts(values, "consent")
-    .flatMap((value) => value.split(","))
-    .map((capability) => capability.trim())
-    .filter((capability) => capability.length > 0);
+  const optional = detail.optionalCapabilities ?? [];
+  const consent = capabilitiesNamed(values);
   if (asked.length > 0 && !session.json) {
     io.stdout(
-      `${detail.key} asks ${asked.length === 1 ? "one capability" : `${asked.length} capabilities`}:\n${capabilityLines(asked).join("\n")}\n`,
+      `${detail.key} requires ${asked.length === 1 ? "one capability" : `${asked.length} capabilities`}:\n${capabilityLines(asked).join("\n")}\n`,
+    );
+  }
+  if (optional.length > 0 && !session.json) {
+    io.stdout(
+      `It can go without these, which it holds if --consent names them too:\n${capabilityLines(optional).join("\n")}\n`,
     );
   }
   const missing = asked.filter((capability) => !consent.includes(capability));
   if (missing.length > 0) {
     throw misuse(
-      `Enabling ${detail.key} needs consent to every capability it asks, named again: --consent ${asked.join(",")}. Not named: ${missing.join(", ")}.`,
+      `Enabling ${detail.key} needs consent to every capability it requires, named again: --consent ${asked.join(",")}. Not named: ${missing.join(", ")}.`,
     );
   }
   const boardFlag = text(values, "board");
@@ -2070,7 +2135,7 @@ const rules: Command = async (args, io) => {
 
 /**
  * The rules as they read for the person whose token the command holds: `{language}` filled
- * with the language they chose for the pages, or with the task's when they chose none.
+ * with the language they read in, or with the task's while they have none.
  */
 function forPerson<T extends { readonly body: string | null }>(
   half: T,
@@ -2530,16 +2595,19 @@ const ask: Command = async (args, io) => {
     file: { type: "string" },
     run: { type: "string" },
     wait: { type: "string" },
-    to: { type: "string" },
+    to: { type: "string", multiple: true },
     attach: { type: "string", multiple: true },
   });
   const question = theOne(
     positionals,
     'Say the question: console ask "<question>" --option "<label>" --option "<label>"',
   );
-  const to = text(values, "to");
-  if (to === "none") {
-    throw misuse("Say whom the decision is for: --to <login|me>.");
+  const tos = texts(values, "to");
+  if (tos.includes("none")) {
+    throw misuse("Say whom the decision is for: --to <login|me>, given again for several.");
+  }
+  if (tos.length > MAX_DECIDERS) {
+    throw misuse(`Name up to ${MAX_DECIDERS} people with --to.`);
   }
   const options = texts(values, "option");
   if (options.length < MIN_OPTIONS || options.length > MAX_OPTIONS) {
@@ -2552,15 +2620,26 @@ const ask: Command = async (args, io) => {
   const session = await open(io, values);
   const project = await session.project();
   const runId = await currentRun(project, values);
-  // Whom the decision is for (ADR-0042): the person the agent works for, unless --to names another.
-  const deciderId = await personIdOf(session, to);
+  // Whom the decision is for (ADR-0042, ADR-0057): the person the agent works for, unless --to
+  // names others of the project, each once; several, and any of them may answer.
+  const deciderIds: string[] = [];
+  for (const to of tos) {
+    const id = await personIdOf(session, to);
+    if (typeof id === "string" && !deciderIds.includes(id)) {
+      deciderIds.push(id);
+    }
+  }
   const raised = await project.raiseDecision(
     {
       question,
       options: options.map((label) => ({ label })),
       runId,
       ...(body === undefined ? {} : { body }),
-      ...(typeof deciderId === "string" ? { deciderId } : {}),
+      ...(deciderIds.length === 0
+        ? {}
+        : deciderIds.length === 1
+          ? { deciderId: deciderIds[0] }
+          : { deciderId: deciderIds[0], deciderIds }),
     },
     files,
   );
@@ -2570,7 +2649,7 @@ const ask: Command = async (args, io) => {
   io.stdout(
     session.json
       ? `${JSON.stringify(raised, null, 2)}\n`
-      : `Decision ${raised.id} raised on run ${runId}${withFiles}; the run waits for ${raised.decider.login}.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`,
+      : `Decision ${raised.id} raised on run ${runId}${withFiles}; the run waits for ${deciderLogins(raised)}.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`,
   );
   return settle(io, session, project, raised, seconds, true);
 };
@@ -3119,8 +3198,19 @@ const people: Command = async (args, io) => {
   const { values } = parse(args, {}, false);
   const session = await open(io, values);
   const found = await session.client.people();
+  const loginOf = new Map(found.items.map((person) => [person.id, person.login]));
   answer(io, session, found, () =>
-    [...found.items.map(formatPersonLine), ...found.listed.map(formatListingLine)].join("\n"),
+    [
+      ...found.items.map((person) =>
+        formatPersonLine(
+          person,
+          person.managerId === null || person.managerId === undefined
+            ? undefined
+            : (loginOf.get(person.managerId) ?? person.managerId),
+        ),
+      ),
+      ...found.listed.map(formatListingLine),
+    ].join("\n"),
   );
   return EXIT.ok;
 };
@@ -3201,7 +3291,7 @@ const workspace: Command = async (args, io) => {
 };
 
 const PERSON_USAGE =
-  "Say what to do: console person role <login> <admin|member>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>";
+  "Say what to do: console person role <login> <admin|member>  |  person manager <login> <manager login|none>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>";
 
 const person: Command = async (args, io) => {
   const what = args[0];
@@ -3218,6 +3308,21 @@ const person: Command = async (args, io) => {
     answer(io, session, changed, () => formatPersonLine(changed));
     return EXIT.ok;
   }
+  if (what === "manager") {
+    const { values, positionals } = parse(args.slice(1), {});
+    const [login, manager] = theTwo(
+      positionals,
+      "Say whom and whom they report to: console person manager <login> <manager login|none>",
+    );
+    const session = await open(io, values);
+    const found = await personOf(session, login);
+    const managerId = manager === "none" ? null : (await personOf(session, manager)).id;
+    const changed = await session.client.updatePerson(found.id, { managerId });
+    answer(io, session, changed, () =>
+      formatPersonLine(changed, managerId === null ? undefined : manager),
+    );
+    return EXIT.ok;
+  }
   if (what === "add") {
     const { values, positionals } = parse(args.slice(1), { host: { type: "string" } });
     const login = theOne(positionals, "Say whom: console person add <login> [--host gh|google]");

package/src/cli/format.ts

@@ -119,12 +119,13 @@ export function formatProject(project: RestProject): string {
   return lines.join("\n");
 }
 
-/** One person: their login, their name where the host gives one, what they are in the workspace, and that they are out when they are. */
-export function formatPersonLine(person: RestPerson): string {
+/** One person: their login, their name where the host gives one, what they are in the workspace, that they are out when they are, and whom they report to where known. */
+export function formatPersonLine(person: RestPerson, reportsTo?: string | undefined): string {
   const standing = person.status === "active" ? person.role : `${person.role}, deactivated`;
+  const line = reportsTo === undefined ? "" : `, reports to ${reportsTo}`;
   return person.name === null
-    ? `${person.login}  (${standing})`
-    : `${person.login}  ${person.name}  (${standing})`;
+    ? `${person.login}  (${standing}${line})`
+    : `${person.login}  ${person.name}  (${standing}${line})`;
 }
 
 /** The provider a listing names, as people call it. */
@@ -219,6 +220,7 @@ export function formatTask(
     `#${task.number} ${task.title}`,
     `state: ${task.state}  priority: ${task.priority}  owner: ${task.owner.login}  workers: ${task.workers.length === 0 ? "nobody" : logins(task.workers)}`,
     `id: ${task.id}${task.parentId === null ? "" : `  part of: ${task.parentId}`}`,
+    ...(task.agent == null ? [] : [`written through: ${task.agent}`]),
     ...scheduleLines(task),
   ];
   if (task.links.length > 0) {
@@ -379,7 +381,7 @@ export function formatGoalLine(goal: RestGoal): string {
 export function formatGoal(goal: RestGoal, tasks?: readonly RestTask[]): string {
   const lines = [
     `goal ${goal.id}: ${goal.title}`,
-    `state: ${goal.state}  category: ${goal.category?.key ?? "none"}  starts: ${goal.startsOn ?? "none"}  due: ${goal.dueOn ?? "none"}  set by: ${goal.createdBy.login}`,
+    `state: ${goal.state}  category: ${goal.category?.key ?? "none"}  starts: ${goal.startsOn ?? "none"}  due: ${goal.dueOn ?? "none"}  set by: ${goal.createdBy.login}${through(goal.agent)}`,
     `progress: ${progressOf(goal)}`,
   ];
   if (goal.body.trim().length > 0) {
@@ -431,9 +433,27 @@ export function formatPersonWork(person: RestPerson, work: RestPersonWork): stri
   ].join("\n");
 }
 
-/** Whom a decision is for, where that is not the one who asked (ADR-0042). */
+/** The agent a thing came through, beside the person (ADR-0056); nothing when they did it themselves. */
+const through = (agent: string | null | undefined): string =>
+  agent === null || agent === undefined ? "" : ` through ${agent}`;
+
+/** Everyone a decision is addressed to (ADR-0057): `deciders` where the console answers it, else the one decider. */
+const decidersOf = (decision: RestDecision): readonly RestPerson[] =>
+  decision.deciders !== undefined && decision.deciders.length > 0
+    ? decision.deciders
+    : [decision.decider];
+
+/** The logins of everyone a decision is addressed to, with commas between. */
+export const deciderLogins = (decision: RestDecision): string =>
+  decidersOf(decision)
+    .map((person) => person.login)
+    .join(", ");
+
+/** Whom a decision is for, where that is not the one who asked alone (ADR-0042, ADR-0057). */
 const addressed = (decision: RestDecision): string =>
-  decision.decider.id === decision.raisedBy.id ? "" : `, for ${decision.decider.login}`;
+  decidersOf(decision).every((person) => person.id === decision.raisedBy.id)
+    ? ""
+    : `, for ${deciderLogins(decision)}`;
 
 export function formatDecisionLine(decision: RestDecision): string {
   const state = decision.answer === null ? "waiting" : `answered ${decision.answer.option}`;
@@ -454,11 +474,11 @@ export function formatOptions(decision: RestDecision): string {
 export function formatAnswer(decision: RestDecision): string {
   const { answer } = decision;
   if (answer === null) {
-    return `waits for ${decision.decider.login}.`;
+    return `waits for ${deciderLogins(decision)}.`;
   }
   const chosen = decision.options.find((option) => option.id === answer.option);
   const lines = [
-    `Answered: ${answer.option}) ${chosen?.label ?? answer.option}${chosen?.own === true ? ", in their own words" : ""}, by ${answer.by.login} at ${answer.at}`,
+    `Answered: ${answer.option}) ${chosen?.label ?? answer.option}${chosen?.own === true ? ", in their own words" : ""}, by ${answer.by.login}${through(answer.agent)} at ${answer.at}`,
   ];
   if (answer.note !== null && answer.note.length > 0) {
     lines.push(`Note: ${answer.note}`);
@@ -488,6 +508,13 @@ export function formatDecision(decision: RestDecision): string {
   lines.push("", "options:", formatOptions(decision), "", formatAnswer(decision));
   if (decision.outcome !== null && decision.outcome.trim().length > 0) {
     lines.push("", "what followed:", indent(decision.outcome));
+    if (decision.outcomeBy != null && decision.outcomeAt != null) {
+      lines.push(
+        indent(
+          `written by ${decision.outcomeBy.login}${through(decision.outcomeAgent)} at ${decision.outcomeAt}`,
+        ),
+      );
+    }
   }
   return lines.join("\n");
 }
@@ -590,6 +617,9 @@ export function localized(
 export function formatPluginLine(plugin: RestPlugin, language: string | null | undefined): string {
   const notes = [
     plugin.roles.length === 0 ? undefined : `roles: ${plugin.roles.join(", ")}`,
+    plugin.console === null || plugin.console === undefined
+      ? undefined
+      : `console: ${plugin.console}`,
     plugin.problems.length === 0 ? undefined : `problems: ${plugin.problems.join("; ")}`,
   ].filter((note): note is string => note !== undefined);
   return `${plugin.key}  ${localized(plugin.name, language)} ${plugin.version}  ${plugin.state}${notes.length === 0 ? "" : `  ${notes.join("  ")}`}`;
@@ -761,6 +791,9 @@ export function formatPlugin(
   if (detail.problems.length > 0) {
     lines.push(`problems: ${detail.problems.join("; ")}`);
   }
+  if (detail.console !== null && detail.console !== undefined) {
+    lines.push(`Runs on consoles ${detail.console}.`);
+  }
   lines.push(
     detail.roles.length === 0
       ? "You hold no role in it."

package/src/cli/help.ts

@@ -7,6 +7,7 @@ import {
   MAX_CATEGORY_KEY_LENGTH,
   MAX_CATEGORY_NAME_LENGTH,
   MAX_COMMENTS_PER_TASK,
+  MAX_DECIDERS,
   MAX_DECISIONS_PER_PROJECT,
   MAX_DOCUMENT_LENGTH,
   MAX_DOCUMENT_PATH_LENGTH,
@@ -247,14 +248,15 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   person: {
     usage:
-      "person role <login> <admin|member>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>",
+      "person role <login> <admin|member>  |  person manager <login> <manager login|none>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>",
     synopsis:
-      "Says what a person is in the workspace, lets a login in or takes one out; for an administrator.",
+      "Says what a person is in the workspace and whom they report to, lets a login in or takes one out; for an administrator.",
     about:
-      "For an administrator: the person themselves on the People page, or their agent here, named on it. role says what a person is in the workspace; the board keeps at least one administrator in. add lets a login in: whoever signs in with that account at that host is a person from then on; the host is read off the login (an address is Google's, anything else GitHub's) unless --host says. remove takes a login away that nobody has signed in with yet. deactivate takes a person out: refused on every request at once, their agents with them, kept with everything they did, and listed nowhere; reactivate takes them back in. A person the organization let in comes and goes with it, and is neither.",
+      "For an administrator: the person themselves on the People page, or their agent here, named on it. role says what a person is in the workspace; the board keeps at least one administrator in. manager says whom a person reports to, the reporting line of the directory, which the plugins read as a default (the approver of their leave, say) in place of a line of their own: another active person of the workspace who does not report to them, directly or through others, or none; console people shows it. add lets a login in: whoever signs in with that account at that host is a person from then on; the host is read off the login (an address is Google's, anything else GitHub's) unless --host says. remove takes a login away that nobody has signed in with yet. deactivate takes a person out: refused on every request at once, their agents with them, kept with everything they did, and listed nowhere; reactivate takes them back in. A person the organization let in comes and goes with it, and is neither.",
     refusals: [
       "auth.forbidden: only an administrator says who is in and what they are",
       "person.last_admin: the board keeps at least one administrator in; make another one first",
+      "person.invalid_manager: the manager is not another active person of the workspace, or reports to this person already",
       "person.of_organization: the organization says whether that person is in",
       "listing.exists: the login is let in already, or is a person's who is in",
       "listing.unknown_host: nobody signs in through that provider here",
@@ -378,9 +380,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   plugin: {
     usage:
-      "plugin <key>  |  plugin <key> help [<command>]  |  plugin <key> <command> [<args>] [--<name> <value>]... [--file <path> | -] [--run <id>]  |  plugin <key> records <collection> [<id>] [--where <field>=<value>]... [--search <words>] [--project <key>] [--order <field>[:desc]] [--limit <n>] [--after <cursor>] [--archived] [--versions]  |  plugin <key> skills [<folder>|<file>] [--search <words> [--limit <n>] [--cursor <cursor>]]  |  plugin <key> skill <path>  |  plugin <key> skill --file <path> [--offset <n>] [--limit <n>]  |  plugin <key> enable --consent <capability>,... [--board new|<key>] [--projects all|<key>,...] [--set <key>=<value>]...  |  plugin <key> disable  |  plugin <key> settings [--set <key>=<value>]...  |  plugin <key> secret <name> [--remove]  |  plugin <key> grant <role> --person <login>|--project <key>|--everyone  |  plugin <key> revoke <grant id>",
+      "plugin <key>  |  plugin <key> help [<command>]  |  plugin <key> <command> [<args>] [--<name> <value>]... [--file <path> | -] [--run <id>]  |  plugin <key> records <collection> [<id>] [--where <field>=<value>]... [--search <words>] [--project <key>] [--order <field>[:desc]] [--limit <n>] [--after <cursor>] [--archived] [--versions]  |  plugin <key> skills [<folder>|<file>] [--search <words> [--limit <n>] [--cursor <cursor>]]  |  plugin <key> skill <path>  |  plugin <key> skill --file <path> [--offset <n>] [--limit <n>]  |  plugin <key> enable --consent <capability>,... [--board new|<key>] [--projects all|<key>,...] [--set <key>=<value>]...  |  plugin <key> disable  |  plugin <key> capabilities [--consent <capability>,...|none]  |  plugin <key> settings [--set <key>=<value>]...  |  plugin <key> secret <name> [--remove]  |  plugin <key> grant <role> --person <login>|--project <key>|--everyone  |  plugin <key> revoke <grant id>",
     overview:
-      "plugin <key> [help [<command>] | <command> [<args>] | records <collection> | skills | skill <path> | enable | disable | settings | secret | grant | revoke]",
+      "plugin <key> [help [<command>] | <command> [<args>] | records <collection> | skills | skill <path> | enable | disable | capabilities | settings | secret | grant | revoke]",
     synopsis:
       "One plugin: what it is for and its commands; a command run as you; its records, its skills; its settings, for an administrator.",
     about:
@@ -388,7 +390,8 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     limits: [
       "a command line: up to 200 words of up to 50,000 characters each; one file, up to the file bound (console help hand-in), with the plugin's files capability",
       "records: a page of up to 200; where: a field the collection indexes",
-      "enable: consent names every capability the manifest asks; settings and secrets as the manifest bounds them",
+      "enable: consent names every capability the manifest requires, and the optional ones to turn on; settings and secrets as the manifest bounds them",
+      "capabilities: --consent names the optional capabilities the plugin holds from now on, none for none of them; those it requires stay",
     ],
     refusals: [
       "plugin.not_found: no plugin has that key, or you may not know of it; or the plugin has no such command or query",
@@ -451,25 +454,26 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   ask: {
     usage:
-      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--attach <path>]... [--to <login|me>] [--wait <seconds>] [--run <id>]',
+      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--attach <path>]... [--to <login|me>]... [--wait <seconds>] [--run <id>]',
     overview:
-      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--attach <path>]... [--to <login|me>] [--wait <seconds>]',
+      'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--attach <path>]... [--to <login|me>]... [--wait <seconds>]',
     synopsis:
       "Raises a decision a person must make, with options, and waits a while for the answer.",
-    about: `Raises a decision a person must make: the question, the options to choose from, and what they need to know. --attach puts a file on the decision, in the one request: a picture of what is to be chosen between, a screenshot of what was made; a picture the body names as ![words](its name) is shown there, the rest after the body, and the person reads each back with \`console file <id>\` (ADR-0055). It is for the person you work for unless --to names another of the project, who then finds it among their decisions (ADR-0042); anyone of the project may still answer. The run waits for the answer. The command waits 60 seconds for it unless --wait says otherwise, and exits with 3 if it is still to come: keep waiting with \`console decision <id> --wait 100\`, within what your shell gives one command. The decision's id is printed as soon as it is raised. The person chooses one of the options, or answers in their own words: the answer then names one more option, their words, marked own; act on it as given. ${ON_THE_RUN}`,
+    about: `Raises a decision a person must make: the question, the options to choose from, and what they need to know. --attach puts a file on the decision, in the one request: a picture of what is to be chosen between, a screenshot of what was made; a picture the body names as ![words](its name) is shown there, the rest after the body, and the person reads each back with \`console file <id>\` (ADR-0055). It is for the person you work for unless --to names another of the project, who then finds it among their decisions (ADR-0042); --to given again names several, each of whom finds it among theirs, and the first answer ends it (ADR-0057); anyone of the project may still answer. The run waits for the answer. The command waits 60 seconds for it unless --wait says otherwise, and exits with 3 if it is still to come: keep waiting with \`console decision <id> --wait 100\`, within what your shell gives one command. The decision's id is printed as soon as it is raised. The person chooses one of the options, or answers in their own words: the answer then names one more option, their words, marked own; act on it as given. ${ON_THE_RUN}`,
     limits: [
       `question: one line, up to ${MAX_QUESTION_LENGTH} characters`,
       `options: ${MIN_OPTIONS} to ${MAX_OPTIONS}, each one line up to ${MAX_OPTION_LABEL_LENGTH} characters`,
       `body: ${MARKDOWN}`,
       `attach: a file: up to ${MAX_FILE_BYTES} bytes, not empty; called by its name, without the path; a picture is placed in the body as ![words](its name)`,
       `at most ${MAX_FILES_PER_DECISION} files on one decision, together up to ${MAX_FILE_BYTES} bytes`,
-      "to: a login of the project, or me",
+      `to: a login of the project, or me; up to ${MAX_DECIDERS} of them`,
       `at most ${MAX_DECISIONS_PER_PROJECT} decisions in one project`,
     ],
     refusals: [
       ...RUN_CHOICE,
       "decision.invalid_run: the run is not yours, or is over",
-      "decision.invalid_decider: the person named may not work in the project",
+      "decision.invalid_decider: a person named may not work in the project",
+      "decision.too_many_deciders: more people named than one decision takes",
       "decision.too_many: the project holds as many decisions as one may",
       "decision.too_many_files: more files than one decision carries",
       "request.too_large: a file, or the files together, over the bound",
@@ -479,7 +483,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     usage: 'answer <id> --option <n>|--own "<answer>" [--note <markdown>|--file <path>]',
     synopsis: "Writes a person's answer on a decision: the option they chose, or their own words.",
     about:
-      "Writes on the board the answer a person gave: one of the decision's options by its number, or their own words, which become one more option of the decision marked as theirs; and a note about it. The answer is the person's, written in their name through you (ADR-0021): a choice they made in chat, in a meeting or by changing the task is written here, with where and when they made it in the note, so that the record is whole and a run that waited goes on. A decision is answered once; what followed is written with console decision <id> --outcome.",
+      "Writes on the board the answer a person gave: one of the decision's options by its number, or their own words, which become one more option of the decision marked as theirs; and a note about it. The answer is the person's, written in their name through you (ADR-0021), and the record says so: the decision names you beside them as the agent the answer came through, where an answer given on the pages names the person alone (ADR-0056). A choice they made in chat, in a meeting or by changing the task is written here, with where and when they made it in the note, so that the record is whole and a run that waited goes on. A decision is answered once; what followed is written with console decision <id> --outcome.",
     limits: [
       `own: one line, up to ${MAX_OPTION_LABEL_LENGTH} characters`,
       `note: Markdown, up to ${MAX_NOTE_LENGTH} characters`,
@@ -495,7 +499,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     synopsis:
       "One decision in full; waits for its answer with --wait; writes what followed with --outcome.",
     about:
-      "One decision, with its context, its options, its answer (one of the options, or the person's own words as one more, marked own) and what followed. With --wait, holds on for the answer that long, and exits with 3 if it is still to come. With --outcome, writes down what followed the decision, so that it reads as a record.",
+      "One decision, with its context, its options, its answer (one of the options, or the person's own words as one more, marked own) and what followed. With --wait, holds on for the answer that long, and exits with 3 if it is still to come. With --outcome, writes down what followed the decision, so that it reads as a record; the record names who wrote it, you beside them, and when (ADR-0056).",
     limits: [`outcome: ${MARKDOWN}`],
     refusals: ["decision.not_found: no decision has that id"],
   },

package/src/cli/plugin-check.ts

@@ -8,11 +8,13 @@ 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 {
@@ -330,10 +332,16 @@ export function sameAsEnglish(value: unknown, at = ""): string[] {
   );
 }
 
+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[] = [];
@@ -365,6 +373,15 @@ export async function checkPlugin(
       `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";
@@ -393,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>;
@@ -456,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,6 +5,7 @@ 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 { LANGUAGE_TAG, nameFromKey, PACKAGE_NAME, writePluginFromTemplate } from "./plugin-init.js";
 
@@ -176,12 +177,18 @@ 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
@@ -220,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

@@ -13,6 +13,8 @@ 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`. */
@@ -40,12 +42,18 @@ export function substitutions(options: InitOptions): readonly [string, string][]
     ["__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);
   }