@skillcdn/console 0.4.3 → 0.4.5

package/src/cli/format.ts

@@ -30,6 +30,7 @@ import type {
   RestRulesPlugin,
   RestRun,
   RestTask,
+  RestTeam,
   RestVersion,
   RestVersionSummary,
   RestWork,
@@ -119,12 +120,15 @@ 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}`;
+  // The work email where the console answers one: to an administrator, and for oneself.
+  const email = typeof person.email === "string" ? `  <${person.email}>` : "";
   return person.name === null
-    ? `${person.login}  (${standing})`
-    : `${person.login}  ${person.name}  (${standing})`;
+    ? `${person.login}${email}  (${standing}${line})`
+    : `${person.login}  ${person.name}${email}  (${standing}${line})`;
 }
 
 /** The provider a listing names, as people call it. */
@@ -219,6 +223,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 +384,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 +436,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 +477,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 +511,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 +620,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("  ")}`}`;
@@ -607,12 +640,22 @@ export function formatPlugins(plugins: RestPlugins, language: string | null | un
   ].join("\n");
 }
 
-/** How a command or a query of a plugin is given, as help prints it: the positionals, then the flags. */
-export function formatOperationUsage(key: string, operation: RestPluginOperation): string {
+/**
+ * How a command or a query of a plugin is given, as help prints it: the positionals, then the
+ * flags. In brief, for a listing that an agent reads whole at every first use, the positionals
+ * and the required flags alone, the rest as `[options]`, since `help <command>` has them all.
+ */
+export function formatOperationUsage(
+  key: string,
+  operation: RestPluginOperation,
+  { brief = false }: { readonly brief?: boolean } = {},
+): string {
   const entries = Object.entries(operation.args);
+  const shown = brief ? entries.filter(([, arg]) => arg.positional || !arg.optional) : entries;
   const usage = [
-    ...entries.filter(([, arg]) => arg.positional).map(([name, arg]) => argUsage(name, arg)),
-    ...entries.filter(([, arg]) => !arg.positional).map(([name, arg]) => argUsage(name, arg)),
+    ...shown.filter(([, arg]) => arg.positional).map(([name, arg]) => argUsage(name, arg)),
+    ...shown.filter(([, arg]) => !arg.positional).map(([name, arg]) => argUsage(name, arg)),
+    ...(brief && shown.length < entries.length ? ["[options]"] : []),
   ];
   return `console plugin ${key} ${operation.name}${usage.map((part) => ` ${part}`).join("")}`;
 }
@@ -673,11 +716,11 @@ export function formatPluginHelp(detail: RestPluginDetail, name: string | undefi
     }
     return [
       ...detail.operations.flatMap((operation) => [
-        formatOperationUsage(detail.key, operation),
+        formatOperationUsage(detail.key, operation, { brief: true }),
         `    ${operation.kind === "query" ? "[query] " : ""}${operation.about}`,
       ]),
       "",
-      `One in full: console plugin ${detail.key} help <command>.`,
+      `One in full, with every option: console plugin ${detail.key} help <command>.`,
     ].join("\n");
   }
   const operation = detail.operations.find((candidate) => candidate.name === name);
@@ -720,7 +763,13 @@ export function formatPluginSettingLine(
   const holds =
     setting.type === "secret"
       ? setting.set
-        ? `set${setting.setAt === null ? "" : ` ${moment(setting.setAt)}`}`
+        ? `set${setting.setAt === null ? "" : ` ${moment(setting.setAt)}`}${
+            setting.source === null ||
+            setting.source === undefined ||
+            setting.source === "administrator"
+              ? ""
+              : ` from ${setting.source}`
+          }${setting.expiresAt === null || setting.expiresAt === undefined ? "" : `, expires ${moment(setting.expiresAt)}`}`
         : "not set"
       : setting.set
         ? setting.value === null
@@ -735,14 +784,25 @@ export function formatPluginSettingLine(
 /** A grant in a line: its id, the role, whom it is to, since when. */
 export function formatPluginGrantLine(grant: RestPluginGrant): string {
   const whom =
-    grant.person !== null
-      ? `person ${grant.person.login}`
-      : grant.project !== null
-        ? `the members of ${grant.project.key}`
-        : "everyone";
+    grant.plugin !== null && grant.plugin !== undefined
+      ? `the plugin ${grant.plugin}`
+      : grant.team !== null && grant.team !== undefined
+        ? `the team ${grant.team.key}`
+        : grant.person !== null
+          ? `person ${grant.person.login}`
+          : grant.project !== null
+            ? `the members of ${grant.project.key}`
+            : "everyone";
   return `${grant.id}  ${grant.role} to ${whom}  since ${moment(grant.createdAt)}`;
 }
 
+/** A team in a line (ADR-0073): its key (ADR-0074), its name, how many are in it, and their logins. */
+export function formatTeamLine(team: RestTeam, loginOf: ReadonlyMap<string, string>): string {
+  const logins = team.memberIds.map((id) => loginOf.get(id) ?? id);
+  const count = team.memberIds.length === 1 ? "1 member" : `${team.memberIds.length} members`;
+  return `${team.key}  ${team.name}  ${count}${logins.length === 0 ? "" : `: ${logins.join(", ")}`}`;
+}
+
 /** One plugin in full: what it is, how it stands, what one may run, its skills and its settings. */
 export function formatPlugin(
   detail: RestPluginDetail,
@@ -761,6 +821,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."
@@ -778,11 +841,11 @@ export function formatPlugin(
     lines.push("Commands and queries:");
     for (const operation of detail.operations) {
       lines.push(
-        `  ${formatOperationUsage(detail.key, operation)}`,
+        `  ${formatOperationUsage(detail.key, operation, { brief: true })}`,
         `      ${operation.kind === "query" ? "[query] " : ""}${operation.about}`,
       );
     }
-    lines.push(`One in full: console plugin ${detail.key} help <command>.`);
+    lines.push(`One in full, with every option: console plugin ${detail.key} help <command>.`);
   }
   if (detail.skills !== null) {
     lines.push(
@@ -806,18 +869,51 @@ export function formatPlugin(
       ...detail.grants.map((grant) => `  ${formatPluginGrantLine(grant)}`),
     );
   }
+  lines.push(...formatPluginAsks(detail, language));
   return lines.join("\n");
 }
 
+/**
+ * The roles the plugin asks of other plugins (ADR-0072), each with how it stands and, where not
+ * granted, the command that grants it; nothing where it asks none.
+ */
+export function formatPluginAsks(
+  detail: RestPluginDetail,
+  language: string | null | undefined,
+): string[] {
+  const asks = detail.asks ?? [];
+  if (asks.length === 0) {
+    return [];
+  }
+  return [
+    "",
+    "Asks of other plugins:",
+    ...asks.map((ask) => {
+      const standing =
+        ask.state === "granted"
+          ? "granted"
+          : ask.state === "unavailable"
+            ? `${ask.plugin} is not enabled`
+            : `not granted; console plugin ${ask.plugin} grant ${ask.role} --plugin ${detail.key}`;
+      return `  ${ask.role} of ${ask.plugin}: ${standing}  ${localized(ask.why, language)}`;
+    }),
+  ];
+}
+
 /** What a command or a query answered, as the command prints it. */
 export function formatInvocation(result: RestPluginInvocation): string {
   if (result.kind === "query") {
     return result.data === undefined ? "null" : JSON.stringify(result.data, null, 2);
   }
   const text = result.text.length === 0 ? "Done." : result.text;
-  return result.waiting === null
-    ? text
-    : `${text}\ndecision id: ${result.waiting}\nThe decision waits for a person: console decision ${result.waiting} --wait 100`;
+  if (result.waiting === null) {
+    return text;
+  }
+  const where =
+    result.project === null || result.project === undefined
+      ? ""
+      : ` in the project ${result.project}`;
+  return `${text}\ndecision id: ${result.waiting}\nThe decision waits for a person${where}: console decision ${result.waiting} --wait 100`;
 }
 
 /** A record's data on one line, cut where it runs long. */

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,
@@ -228,6 +229,30 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     about:
       "The people of the workspace you see, by login, with their name where the host gives one and what they are in it: admin, who configures the workspace, or member, who works in the projects they are in; a person taken out is marked deactivated. Everyone, unless the workspace shows a member only the people they share a project with (console workspace says which; an administrator sees everyone). Then, where you see everyone, the logins an administrator let in that nobody has signed in with yet. The logins are what --worker, member and person take; a login is found exactly, so an owner lists someone the list does not show.",
   },
+  teams: {
+    usage: "teams",
+    synopsis: "The teams of the workspace, each with who is in it.",
+    about:
+      "The teams of the workspace (a name and its members: a unit to call people by, and to grant a plugin's role to, ADR-0073), by name, each with its key, what it is called by (ADR-0074), how many are in it and their logins. console team makes and keeps them, for an administrator.",
+  },
+  team: {
+    usage:
+      'team new <key> "<name>"  |  team rename <key> "<new name>"  |  team remove <key>  |  team add <key> <login>  |  team drop <key> <login>',
+    synopsis:
+      "Makes, renames or removes a team, or puts a person in one or takes them out; for an administrator.",
+    about:
+      "For an administrator: a team is a key, a name and its members, any number per person. The key is what a grant, a plugin and this command call the team by (ADR-0074): lowercase letters, digits and hyphens, one among the teams' and the projects' keys, and it never changes; the name, one per workspace, is what people read. new makes one; rename gives it another name, the key staying; remove takes it away, with its memberships and the plugin roles granted to it; add and drop put a person in and take them out, by login. The board records each as the workspace's own event, and a plugin with people:read:all hears of them.",
+    refusals: [
+      "auth.forbidden: only an administrator keeps the teams",
+      "request.invalid: the key is not lowercase letters, digits and hyphens, or the name is empty or too long",
+      "team.not_found: no team has that key",
+      "team.key_taken: a team or a project has that key already",
+      "team.name_taken: a team of that name is there already",
+      "team.too_many: the workspace holds as many teams as one may",
+      "team.invalid_member: the person is not an active person of the workspace",
+      "team.not_a_member: the person is not in the team",
+    ],
+  },
   workspace: {
     usage:
       "workspace  |  workspace edit [--people-visibility <everyone|shared-projects>] [--week-start <auto|monday|sunday>] [--time-zone <zone|none>]  |  workspace pack-token --connect  |  workspace pack-token --stdin  |  workspace pack-token --remove",
@@ -247,14 +272,16 @@ 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 email <login> <address|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, whom they report to and their work email, 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. email writes the person's work email, or none, by which a plugin allowed to read it matches them to an account elsewhere: a person who signs in at Google has their address from the sign-in, and an administrator writes everyone else's; it is read by an administrator, the person and such a plugin, and by nobody from the feed, which says only that it changed. 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.email_taken: the address is another person's in this workspace",
       "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,17 +405,18 @@ 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>|--plugin <key>|--team <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:
-      "One plugin of this console, by its key. Alone: what it is, the sentence for agents, its state, the roles you hold in it, its board project, then one line per command and query you may run, with its usage, where its skills are, and its settings. help [<command>]: one command or query in full, as console help prints one: its arguments, their types and bounds, and the refusals; every argument is given by its place when positional, else as --<name> <value> or --<name>=<value>; a boolean as --<name> alone; a list as the flag given again, or with commas between; a day as YYYY-MM-DD; a person by login, or me; a project by key; a file by --file <path>, or - for standard input, which the command uploads first, with the plugin's files capability. <command> [<args>]: runs the command or the query as the person whose token you hold; the console parses the words against the definition and refuses the first that does not fit; prints what the command says, or a query's answer as JSON, a file a query answers saved under its name; --json prints the whole answer. A command that raised a decision prints its id and exits with 3: console decision <id> --wait 100 waits for the answer. The event the command leaves names your open run in the plugin's board project, --run <id> saying which when several are open; an argument marked secret is hidden in it. records <collection>: the records you may read, one a line, newest first; --where <field>=<value>, given again for several, narrows by a field the collection indexes (id, owner and project always; a number, true, false and null are read as such); --search <words> by words; --project <key> to those linked to a project; --order <field>, with :desc for the newest first; a page of --limit with --after <cursor> as the last page printed; --archived the ones put away; <id> reads one record whole, --versions its versions. skills and skill: the plugin's own skills, a pack read from its package, exactly as console skills and console skill read a project's pack. enable, disable, settings, secret, grant and revoke are an administrator's. enable prints what each capability the plugin asks opens and what a malicious plugin would reach through it, and refuses unless --consent names every capability again; --board new makes the board project the manifest proposes, --board <key> chooses one, left out where the plugin needs none; --projects all, or the keys of the projects the plugin is on; --set a setting's value, which settings changes afterwards too, an empty value clearing one, a number or true and false read as such. secret <name> reads the value from standard input, seals it and shows it never; --remove takes it away. grant gives a role to a person by login, to the members of a project by key, or to everyone, and revoke takes a grant back by its id, which console plugin <key> lists to an administrator.",
+      "One plugin of this console, by its key. Alone: what it is, the sentence for agents, its state, the roles you hold in it, its board project, then one line per command and query you may run, with its usage, where its skills are, and its settings. help [<command>]: one command or query in full, as console help prints one: its arguments, their types and bounds, and the refusals; every argument is given by its place when positional, else as --<name> <value> or --<name>=<value>; a boolean as --<name> alone; a list as the flag given again, or with commas between; a day as YYYY-MM-DD; a person by login, or me; a project by key; a file by --file <path>, or - for standard input, which the command uploads first, with the plugin's files capability. <command> [<args>]: runs the command or the query as the person whose token you hold; the console parses the words against the definition and refuses the first that does not fit; prints what the command says, or a query's answer as JSON, a file a query answers saved under its name; --json prints the whole answer. A command that raised a decision prints its id and exits with 3: console decision <id> --wait 100 waits for the answer. The event the command leaves names your open run in the plugin's board project, --run <id> saying which when several are open; an argument marked secret is hidden in it. records <collection>: the records you may read, one a line, newest first; --where <field>=<value>, given again for several, narrows by a field the collection indexes (id, owner and project always; a number, true, false and null are read as such); --search <words> by words; --project <key> to those linked to a project; --order <field>, with :desc for the newest first; a page of --limit with --after <cursor> as the last page printed; --archived the ones put away; <id> reads one record whole, --versions its versions. skills and skill: the plugin's own skills, a pack read from its package, exactly as console skills and console skill read a project's pack. enable, disable, settings, secret, grant and revoke are an administrator's. enable prints what each capability the plugin asks opens and what a malicious plugin would reach through it, and refuses unless --consent names every capability again; --board new makes the board project the manifest proposes, --board <key> chooses one, left out where the plugin needs none; --projects all, or the keys of the projects the plugin is on; --set a setting's value, which settings changes afterwards too, an empty value clearing one, a number or true and false read as such. secret <name> reads the value from standard input, seals it and shows it never; --remove takes it away. grant gives a role to a person by login, to the members of a project by key, to another plugin by key, to the members of a team by key, or to everyone, and revoke takes a grant back by its id, which console plugin <key> lists to an administrator.",
     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 +479,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 +508,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 +524,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);
   }