@skillcdn/console 0.4.3 → 0.4.5

package/src/cli/cli.ts

@@ -21,12 +21,19 @@ 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";
 import {
   hostOfLogin,
+  type RestAnswerInput,
   type RestClaim,
   type RestDecision,
   type RestMember,
@@ -77,6 +84,7 @@ import {
 } from "./credentials.js";
 import { type DirectorySettings, type DirectoryStore, THE_SENTENCE } from "./directory.js";
 import {
+  deciderLogins,
   formatAnswer,
   formatCategoryLine,
   formatComment,
@@ -94,6 +102,7 @@ import {
   formatPersonLine,
   formatPersonWork,
   formatPlugin,
+  formatPluginAsks,
   formatPluginGrantLine,
   formatPluginHelp,
   formatPluginRecord,
@@ -108,6 +117,7 @@ import {
   formatRunLine,
   formatTask,
   formatTaskLine,
+  formatTeamLine,
   formatVersion,
   formatVersionLine,
   formatWork,
@@ -625,9 +635,14 @@ function theTwo(positionals: readonly string[], ask: string): readonly [string,
  * The decision once answered, or as it stands when the wait is over. Each request asks the
  * console to hold it for a while, so the answer arrives as soon as a person gives it.
  */
+/** Whatever waits for a decision's answer: the project's client, or the decision wherever it is (ADR-0068). */
+interface Waiter {
+  awaitDecision(id: string, waitSeconds: number): Promise<RestDecision>;
+}
+
 async function waitForAnswer(
   io: CliIo,
-  project: ProjectClient,
+  project: Waiter,
   decision: RestDecision,
   seconds: number,
 ): Promise<RestDecision> {
@@ -658,7 +673,7 @@ const stillWaiting = (id: string): string =>
 async function settle(
   io: CliIo,
   session: Session,
-  project: ProjectClient,
+  project: Waiter,
   decision: RestDecision,
   seconds: number,
   shown = false,
@@ -1526,6 +1541,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 +1804,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 +1877,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");
@@ -1854,12 +1927,18 @@ async function pluginEnable(
   answer(io, session, enabled, () =>
     [
       `Enabled ${enabled.key}${enabled.board === null ? "" : `, with the board project ${enabled.board.key}`}; on ${enabled.projects === "all" || enabled.projects === null ? "every project" : enabled.projects.join(", ") || "no project"}.`,
+      ...(enabled.needsTimeZone === true
+        ? [
+            "The workspace has no time zone: the plugin's times of day run on UTC until an administrator sets one, with console workspace edit --time-zone <zone>.",
+          ]
+        : []),
       ...(enabled.settings.length === 0
         ? []
         : [
             "Settings:",
             ...enabled.settings.map((setting) => formatPluginSettingLine(setting, me.language)),
           ]),
+      ...formatPluginAsks(enabled, me.language),
     ].join("\n"),
   );
   return EXIT.ok;
@@ -1934,7 +2013,10 @@ async function pluginSecret(
   return EXIT.ok;
 }
 
-/** Grants a role of the plugin to a person, to the members of a project, or to everyone; an administrator's. */
+/**
+ * Grants a role of the plugin to a person, to the members of a project, to another plugin, to the
+ * members of a team, or to everyone; an administrator's.
+ */
 async function pluginGrant(
   io: CliIo,
   session: Session,
@@ -1944,14 +2026,26 @@ async function pluginGrant(
 ): Promise<number> {
   const { values, positionals } = parse(rest, {
     person: { type: "string" },
+    plugin: { type: "string" },
+    team: { type: "string" },
     everyone: { type: "boolean" },
   });
-  const usage = `console plugin ${client.key} grant <role> --person <login> | --project <key> | --everyone`;
+  const usage = `console plugin ${client.key} grant <role> --person <login> | --project <key> | --plugin <key> | --team <key> | --everyone`;
   const role = theOne(positionals, `Say which role: ${usage}`);
   const login = text(values, "person");
+  const other = text(values, "plugin");
+  const teamKey = text(values, "team");
   const everyone = on(values, "everyone");
-  if ([login !== undefined, projectKey !== undefined, everyone].filter(Boolean).length !== 1) {
-    throw misuse(`Say whom, one of the three: ${usage}`);
+  if (
+    [
+      login !== undefined,
+      projectKey !== undefined,
+      other !== undefined,
+      teamKey !== undefined,
+      everyone,
+    ].filter(Boolean).length !== 1
+  ) {
+    throw misuse(`Say whom, one of the five: ${usage}`);
   }
   let input: RestPluginGrantInput;
   if (login !== undefined) {
@@ -1962,6 +2056,10 @@ async function pluginGrant(
     input = { role, person: person.id };
   } else if (projectKey !== undefined) {
     input = { role, project: projectKey };
+  } else if (other !== undefined) {
+    input = { role, plugin: other };
+  } else if (teamKey !== undefined) {
+    input = { role, team: teamKey };
   } else {
     input = { role, everyone: true };
   }
@@ -2070,7 +2168,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 +2628,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 +2653,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 +2682,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);
 };
@@ -2600,8 +2712,7 @@ const answering: Command = async (args, io) => {
   }
   const note = await bodyOf(io, values, text(values, "note"));
   const session = await open(io, values);
-  const project = await session.project();
-  const answered = await project.answerDecision(id, {
+  const answered = await answerReached(session, id, {
     ...(own === undefined ? { option } : { own }),
     ...(note === undefined ? {} : { note }),
   });
@@ -2609,6 +2720,75 @@ const answering: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/** Whether a refusal says the decision is not in the project the command works in, or the project is not the person's. */
+const notInProject = (error: unknown): boolean =>
+  error instanceof ApiError &&
+  (error.code === "decision.not_found" || error.code === "project.not_found");
+
+/**
+ * One decision as the command reaches it (ADR-0068): in the project the command works in, as
+ * before; else wherever it is, addressed to the person, raised by them, or a plugin's addressed
+ * to someone they manage, through the console's own route for one decision. A plugin's decision
+ * waits in the plugin's board project, which a checkout bound to another project does not name,
+ * and which the person may not be in at all. A console from before that route answers as before.
+ */
+async function reachDecision(
+  session: Session,
+  id: string,
+): Promise<{ readonly decision: RestDecision; readonly waiter: Waiter }> {
+  if ((await session.projectKey()) !== undefined) {
+    const project = await session.project();
+    try {
+      return { decision: await project.decision(id), waiter: project };
+    } catch (error) {
+      if (!notInProject(error)) {
+        throw error;
+      }
+    }
+  }
+  const anywhere = session.client;
+  try {
+    const reached = await anywhere.decision(id);
+    return {
+      decision: reached.decision,
+      waiter: {
+        awaitDecision: async (decisionId, seconds) =>
+          (await anywhere.awaitDecision(decisionId, seconds)).decision,
+      },
+    };
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 404) {
+      throw new ApiError(404, "decision.not_found", "The decision was not found.");
+    }
+    throw error;
+  }
+}
+
+/** Writes an answer on a decision as the command reaches it (ADR-0068): in the project, else wherever it is. */
+async function answerReached(
+  session: Session,
+  id: string,
+  input: RestAnswerInput,
+): Promise<RestDecision> {
+  if ((await session.projectKey()) !== undefined) {
+    try {
+      return await (await session.project()).answerDecision(id, input);
+    } catch (error) {
+      if (!notInProject(error)) {
+        throw error;
+      }
+    }
+  }
+  try {
+    return await session.client.answerDecision(id, input);
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 404) {
+      throw new ApiError(404, "decision.not_found", "The decision was not found.");
+    }
+    throw error;
+  }
+}
+
 const decision: Command = async (args, io) => {
   const { values, positionals } = parse(args, {
     wait: { type: "string" },
@@ -2622,19 +2802,19 @@ const decision: Command = async (args, io) => {
   const seconds = secondsOf(text(values, "wait"), 0);
   const outcome = await bodyOf(io, values, text(values, "outcome"));
   const session = await open(io, values);
-  const project = await session.project();
   if (outcome !== undefined) {
     // What followed the decision: the record grows, and is printed as it stands.
+    const project = await session.project();
     const grown = await project.updateDecision(id, { outcome });
     answer(io, session, grown, () => formatDecision(grown));
     return EXIT.ok;
   }
-  const found = await project.decision(id);
+  const { decision: found, waiter } = await reachDecision(session, id);
   if (seconds === 0) {
     answer(io, session, found, () => formatDecision(found));
     return EXIT.ok;
   }
-  return settle(io, session, project, found, seconds);
+  return settle(io, session, waiter, found, seconds);
 };
 
 const docs: Command = async (args, io) => {
@@ -3119,12 +3299,94 @@ 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((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;
+};
+
+/** The teams of the workspace (ADR-0073): each with who is in it, by login. */
+const teams: Command = async (args, io) => {
+  const { values } = parse(args, {}, false);
+  const session = await open(io, values);
+  const [found, everyone] = await Promise.all([session.client.teams(), session.client.people()]);
+  const loginOf = new Map(everyone.items.map((person) => [person.id, person.login]));
   answer(io, session, found, () =>
-    [...found.items.map(formatPersonLine), ...found.listed.map(formatListingLine)].join("\n"),
+    found.items.length === 0
+      ? "No teams yet. console team new <key> <name> makes one."
+      : found.items.map((team) => formatTeamLine(team, loginOf)).join("\n"),
   );
   return EXIT.ok;
 };
 
+const TEAM_USAGE =
+  'Say what to do: console team new <key> "<name>"  |  team rename <key> "<new name>"  |  team remove <key>  |  team add <key> <login>  |  team drop <key> <login>';
+
+// A team is called by its key (ADR-0074), which never changes; its name is what people read.
+const team: Command = async (args, io) => {
+  const what = args[0];
+  if (what === "new") {
+    const { values, positionals } = parse(args.slice(1), {});
+    const [key, name] = theTwo(
+      positionals,
+      'Say the key and the name: console team new <key> "<name>"',
+    );
+    const session = await open(io, values);
+    const made = await session.client.createTeam({ key, name });
+    answer(io, session, made, () => formatTeamLine(made, new Map()));
+    return EXIT.ok;
+  }
+  if (what === "rename") {
+    const { values, positionals } = parse(args.slice(1), {});
+    const [key, next] = theTwo(
+      positionals,
+      'Say which team and its new name: console team rename <key> "<new name>"',
+    );
+    const session = await open(io, values);
+    const changed = await session.client.renameTeam(key, { name: next });
+    answer(io, session, changed, () => formatTeamLine(changed, new Map()));
+    return EXIT.ok;
+  }
+  if (what === "remove") {
+    const { values, positionals } = parse(args.slice(1), {});
+    const key = theOne(positionals, "Say which team: console team remove <key>");
+    const session = await open(io, values);
+    await session.client.removeTeam(key);
+    answer(io, session, { removed: key }, () => `The team ${key} is no more.`);
+    return EXIT.ok;
+  }
+  if (what === "add" || what === "drop") {
+    const { values, positionals } = parse(args.slice(1), {});
+    const [key, login] = theTwo(
+      positionals,
+      `Say which team and whom: console team ${what} <key> <login>`,
+    );
+    const session = await open(io, values);
+    const person = await personOf(session, login);
+    const changed =
+      what === "add"
+        ? await session.client.addTeamMember(key, person.id)
+        : await session.client.removeTeamMember(key, person.id);
+    const everyone = await session.client.people();
+    answer(io, session, changed, () =>
+      formatTeamLine(changed, new Map(everyone.items.map((one) => [one.id, one.login]))),
+    );
+    return EXIT.ok;
+  }
+  throw misuse(TEAM_USAGE);
+};
+
 // The workspace's settings (ADR-0035): read by everyone, changed by an administrator, themselves
 // on the Settings page or through their agent here (ADR-0021).
 const WORKSPACE_FLAGS =
@@ -3201,7 +3463,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 email <login> <address|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 +3480,35 @@ const person: Command = async (args, io) => {
     answer(io, session, changed, () => formatPersonLine(changed));
     return EXIT.ok;
   }
+  if (what === "email") {
+    const { values, positionals } = parse(args.slice(1), {});
+    const [login, address] = theTwo(
+      positionals,
+      "Say whom and their address: console person email <login> <address|none>",
+    );
+    const session = await open(io, values);
+    const found = await personOf(session, login);
+    const changed = await session.client.updatePerson(found.id, {
+      email: address === "none" ? null : address,
+    });
+    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]");
@@ -3664,6 +3955,8 @@ const COMMANDS: Readonly<Record<string, Command>> = {
   plugin,
   people,
   person,
+  teams,
+  team,
   workspace,
   project,
   members,