@skillcdn/console 0.4.3 → 0.4.5

package/dist/cli/cli.js

@@ -3,7 +3,7 @@ import { parseArgs } from "node:util";
 import { ApiError, createClient, } from "../client.js";
 import { CLIENT_RANGE_HEADER, CONSOLE_AT_LEAST, consoleRange, formatRange, judgeClient, judgeConsole, parseVersion, VERSION_HEADER, 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";
@@ -12,7 +12,7 @@ import { COLOR_NAMES, GOAL_STATES, PEOPLE_VISIBILITIES, PERSON_ROLES, PROJECT_RO
 import { loadWebRoot, WebRootError } from "../web.js";
 import { CredentialsError, EMPTY_CREDENTIALS, loginsAt, resolveLogin, withLogin, withoutLogin, } from "./credentials.js";
 import { THE_SENTENCE } from "./directory.js";
-import { formatAnswer, formatCategoryLine, formatComment, formatDecision, formatDecisionLine, formatDocument, formatDocuments, formatGoal, formatGoalLine, formatInvocation, formatListingLine, formatMemberLine, formatMore, formatOptions, formatPersonLine, formatPersonWork, formatPlugin, formatPluginGrantLine, formatPluginHelp, formatPluginRecord, formatPluginRecords, formatPluginRecordVersions, formatPluginSettingLine, formatPlugins, formatProject, formatProjectLine, formatRules, formatRun, formatRunLine, formatTask, formatTaskLine, formatVersion, formatVersionLine, formatWork, formatWorkspace, localized, moment, setMomentZone, } from "./format.js";
+import { deciderLogins, formatAnswer, formatCategoryLine, formatComment, formatDecision, formatDecisionLine, formatDocument, formatDocuments, formatGoal, formatGoalLine, formatInvocation, formatListingLine, formatMemberLine, formatMore, formatOptions, formatPersonLine, formatPersonWork, formatPlugin, formatPluginAsks, formatPluginGrantLine, formatPluginHelp, formatPluginRecord, formatPluginRecords, formatPluginRecordVersions, formatPluginSettingLine, formatPlugins, formatProject, formatProjectLine, formatRules, formatRun, formatRunLine, formatTask, formatTaskLine, formatTeamLine, formatVersion, formatVersionLine, formatWork, formatWorkspace, localized, moment, setMomentZone, } from "./format.js";
 import { COMMAND_HELP, helpFor, ownSkillPath, usage } from "./help.js";
 import { describeInstall, updateCommandFor } from "./install.js";
 import { bodyOfFile, bodyOfFolder, bodyOfSkill, formatSkillBrowse, formatSkillFile, formatSkillFind, formatSkillLoad, formatSkills, joinFile, joinFolder, joinSkill, skillPathIn, summaryOf, } from "./pack.js";
@@ -373,10 +373,6 @@ function theTwo(positionals, ask) {
     }
     return [first, second];
 }
-/**
- * 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.
- */
 async function waitForAnswer(io, project, decision, seconds) {
     const deadline = io.now() + seconds * 1000;
     let current = decision;
@@ -1077,6 +1073,8 @@ const plugin = async (args, io) => {
             answer(io, session, detail, () => `Disabled ${detail.key}: its commands are refused until it is enabled again; what the console kept of it stays.`);
             return EXIT.ok;
         }
+        case "capabilities":
+            return pluginCapabilities(io, session, client, rest);
         case "settings":
             return pluginSettings(io, session, client, rest);
         case "secret":
@@ -1307,7 +1305,49 @@ function capabilityLines(capabilities) {
             : `  ${capability}: opens ${words.opens}; a malicious plugin reaches ${words.reach}`;
     });
 }
-/** 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) {
+    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) {
+    const held = detail.consent ?? [];
+    const optional = detail.optionalCapabilities ?? [];
+    const named = (capabilities) => 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, session, client, rest) {
+    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, session, client, rest) {
     const { values, positionals } = parse(rest, {
         consent: { type: "string", multiple: true },
@@ -1320,16 +1360,17 @@ async function pluginEnable(io, session, client, rest) {
     }
     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`);
+        io.stdout(`${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(", ")}.`);
+        throw misuse(`Enabling ${detail.key} needs consent to every capability it requires, named again: --consent ${asked.join(",")}. Not named: ${missing.join(", ")}.`);
     }
     const boardFlag = text(values, "board");
     let board = null;
@@ -1361,12 +1402,18 @@ async function pluginEnable(io, session, client, rest) {
     });
     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;
 }
@@ -1411,18 +1458,31 @@ async function pluginSecret(io, session, client, rest) {
     answer(io, session, { name, set: true }, () => `Set the secret ${name} of ${client.key}: sealed, and shown by nothing from now on.`);
     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, session, client, rest, projectKey) {
     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;
     if (login !== undefined) {
@@ -1435,6 +1495,12 @@ async function pluginGrant(io, session, client, rest, projectKey) {
     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 };
     }
@@ -1531,7 +1597,7 @@ const rules = 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(half, language) {
     return half.body === null ? half : { ...half, body: fillRules(half.body, language) };
@@ -1909,13 +1975,16 @@ const ask = 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) {
@@ -1928,20 +1997,31 @@ const ask = 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 = [];
+    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);
     const withFiles = files.length === 0 ? "" : `, with ${files.length} file${files.length === 1 ? "" : "s"}`;
     // The id is printed before any waiting, so that a wait cut short loses nothing.
     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);
 };
 /**
@@ -1964,14 +2044,74 @@ const answering = 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 }),
     });
     answer(io, session, answered, () => formatDecision(answered));
     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) => 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, id) {
+    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, id, input) {
+    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 = async (args, io) => {
     const { values, positionals } = parse(args, {
         wait: { type: "string" },
@@ -1982,19 +2122,19 @@ const decision = 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 = async (args, io) => {
     const { values, positionals } = parse(args, {
@@ -2396,9 +2536,68 @@ const people = async (args, io) => {
     const { values } = parse(args, {}, false);
     const session = await open(io, values);
     const found = await session.client.people();
-    answer(io, session, found, () => [...found.items.map(formatPersonLine), ...found.listed.map(formatListingLine)].join("\n"));
+    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 = 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.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 = 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 = "--people-visibility <everyone|shared-projects>, --week-start <auto|monday|sunday>, --time-zone <zone|none>";
@@ -2459,7 +2658,7 @@ const workspace = async (args, io) => {
     }
     throw misuse(WORKSPACE_USAGE);
 };
-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>";
+const PERSON_USAGE = "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 = async (args, io) => {
     const what = args[0];
     if (what === "role") {
@@ -2472,6 +2671,27 @@ const person = 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]");
@@ -2817,6 +3037,8 @@ const COMMANDS = {
     plugin,
     people,
     person,
+    teams,
+    team,
     workspace,
     project,
     members,