@skillcdn/console 0.4.1 → 0.4.3

package/dist/cli/cli.js

@@ -4,13 +4,15 @@ 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 { capabilityWords } from "../plugin/capabilities.js";
+import { PLUGIN_LIST_LIMIT } from "../plugin/limits.js";
 import { fillRules, RULES_PATH, RULES_TITLE } from "../rules.js";
 import { hostOfLogin, } from "../schemas.js";
 import { COLOR_NAMES, GOAL_STATES, PEOPLE_VISIBILITIES, PERSON_ROLES, PROJECT_ROLES, PROJECT_VISIBILITIES, PROVIDER_KEYS, TASK_PRIORITIES, TASK_STATES, WEEK_STARTS, } from "../vocabulary.js";
 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, formatListingLine, formatMemberLine, formatMore, formatOptions, formatPersonLine, formatPersonWork, formatProject, formatProjectLine, formatRules, formatRun, formatRunLine, formatTask, formatTaskLine, formatVersion, formatVersionLine, formatWork, formatWorkspace, moment, setMomentZone, } from "./format.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 { 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";
@@ -772,18 +774,29 @@ const MAX_SKILL_PAGES = 64;
 /** How many results a search answers at most: what the deployment allows on one page. */
 const MAX_FIND_LIMIT = 25;
 /** The pack of the project as the console lists it, and what its reads are rendered at; none when the pack did not answer. */
-async function packOf(project) {
-    const listing = await project.skills();
+async function packOf(reader) {
+    const listing = await reader.skills();
     return { listing, summary: summaryOf(listing) };
 }
-const skills = async (args, io) => {
-    const { values, positionals } = parse(args, {
-        search: { type: "string" },
-        limit: { type: "string" },
-        cursor: { type: "string" },
-    });
+const SKILLS_OPTIONS = {
+    search: { type: "string" },
+    limit: { type: "string" },
+    cursor: { type: "string" },
+};
+const SKILL_OPTIONS = {
+    file: { type: "string" },
+    offset: { type: "string" },
+    limit: { type: "string" },
+};
+/** The line `console skills` ends with: where the plugins' own skills are. */
+const PLUGIN_SKILLS_LINE = "The plugins of this console have skills of their own: console plugins lists the plugins, console plugin <key> skills the skills of one.";
+/**
+ * The pack as the words say: whole, a folder of it, a file's outline, or what words find; for
+ * the project's pack as `console skills`, and for a plugin's as `console plugin <key> skills`.
+ */
+async function readSkills(io, session, reader, values, positionals, extras) {
     if (positionals.length > 1) {
-        throw misuse("Say one folder: console skills [<folder>] [--search <words>]");
+        throw misuse(`Say one folder: ${extras.command} [<folder>] [--search <words>]`);
     }
     // The root of the pack is the mounted folder, which the deployment reads as no path at all.
     const given = positionals[0];
@@ -792,24 +805,24 @@ const skills = async (args, io) => {
     const limit = text(values, "limit");
     const cursor = text(values, "cursor");
     if (words === undefined && (limit !== undefined || cursor !== undefined)) {
-        throw misuse("--limit and --cursor go with --search: console skills --search <words> [--limit <n>] [--cursor <cursor>]");
+        throw misuse(`--limit and --cursor go with --search: ${extras.command} --search <words> [--limit <n>] [--cursor <cursor>]`);
     }
     const atMost = limit === undefined ? undefined : Number(limit);
     if (atMost !== undefined &&
         (!Number.isInteger(atMost) || atMost < 1 || atMost > MAX_FIND_LIMIT)) {
         throw misuse(`Not a number of results, 1 to ${MAX_FIND_LIMIT}: ${limit}`);
     }
-    const session = await open(io, values);
-    const project = await session.project();
-    const { listing, summary } = await packOf(project);
+    const { listing, summary } = await packOf(reader);
     // The pack as it stands; or why it does not answer, which a folder or a search would meet too.
     if (summary === undefined || (words === undefined && given === undefined)) {
-        answer(io, session, listing, () => formatSkills(listing, io.skillsDir));
+        answer(io, session, listing, () => [formatSkills(listing, extras.own), extras.afterwards]
+            .filter((part) => part !== undefined)
+            .join("\n"));
         return EXIT.ok;
     }
     if (words !== undefined) {
         // One page of what the words find; more is said, and asked for with --cursor.
-        const found = await project.skillFind(words, { path: folder, limit: atMost, cursor });
+        const found = await reader.skillFind(words, { path: folder, limit: atMost, cursor });
         answer(io, session, found, () => formatSkillFind(found, summary));
         return EXIT.ok;
     }
@@ -818,7 +831,7 @@ const skills = async (args, io) => {
     let next;
     let last;
     for (let n = 0; n < MAX_SKILL_PAGES; n += 1) {
-        last = await project.skillBrowse({ path: folder, cursor: next });
+        last = await reader.skillBrowse({ path: folder, cursor: next });
         if (last.read?.status !== "ready") {
             break;
         }
@@ -835,6 +848,16 @@ const skills = async (args, io) => {
     const whole = joinFolder(pages, summary);
     answer(io, session, { ...browsed, read: whole === undefined ? null : bodyOfFolder(whole) }, () => formatSkillBrowse(browsed, whole));
     return EXIT.ok;
+}
+const skills = async (args, io) => {
+    const { values, positionals } = parse(args, SKILLS_OPTIONS);
+    const session = await open(io, values);
+    const project = await session.project();
+    return readSkills(io, session, project, values, positionals, {
+        command: "console skills",
+        own: io.skillsDir,
+        afterwards: PLUGIN_SKILLS_LINE,
+    });
 };
 /** The most characters one read of a file asks for: what the console's API allows on one page. */
 const MAX_FILE_LIMIT = 100_000;
@@ -852,28 +875,25 @@ function countOf(given, name, bounds) {
     }
     return count;
 }
-const skill = async (args, io) => {
-    const { values, positionals } = parse(args, {
-        file: { type: "string" },
-        offset: { type: "string" },
-        limit: { type: "string" },
-    });
+/**
+ * One skill of the pack whole, a file of it, or one page of a file; for the project's pack as
+ * `console skill`, and for a plugin's as `console plugin <key> skill`.
+ */
+async function readSkill(io, session, reader, values, positionals, command) {
     const file = text(values, "file");
     // A file is read by its own path from the repository's root; a skill's path beside it would be
     // ignored, which reads as if it mattered, so the two together are not understood.
     if (file !== undefined && positionals.length > 0) {
-        throw misuse("Say one: console skill <path of its SKILL.md> for a skill, or console skill --file <path> for a file of the pack.");
+        throw misuse(`Say one: ${command} <path of its SKILL.md> for a skill, or ${command} --file <path> for a file of the pack.`);
     }
     // A section is a page of a file read as asked (SkillCDN 0.4): the flags mean nothing without one.
     if (file === undefined &&
         (text(values, "offset") !== undefined || text(values, "limit") !== undefined)) {
-        throw misuse("--offset and --limit go with --file: console skill --file <path> [--offset <n>] [--limit <n>]");
+        throw misuse(`--offset and --limit go with --file: ${command} --file <path> [--offset <n>] [--limit <n>]`);
     }
     const offset = countOf(text(values, "offset"), "offset", { least: 0 });
     const limit = countOf(text(values, "limit"), "limit", { least: 1, most: MAX_FILE_LIMIT });
-    const session = await open(io, values);
-    const project = await session.project();
-    const { listing, summary } = await packOf(project);
+    const { listing, summary } = await packOf(reader);
     if (summary === undefined) {
         answer(io, session, listing, () => formatSkills(listing, io.skillsDir));
         return EXIT.ok;
@@ -881,7 +901,7 @@ const skill = async (args, io) => {
     if (file !== undefined && (offset !== undefined || limit !== undefined)) {
         // One page as asked, the section a search or an outline named; the result says where the
         // file continues, and asks for nothing.
-        const page = await project.skillFile(file, { offset, limit });
+        const page = await reader.skillFile(file, { offset, limit });
         const section = page.read === null ? undefined : joinFile([page], summary, limit);
         answer(io, session, { ...page, read: section === undefined ? null : bodyOfFile(section) }, () => formatSkillFile(page, section));
         return EXIT.ok;
@@ -892,7 +912,7 @@ const skill = async (args, io) => {
         let offset;
         let last;
         for (let n = 0; n < MAX_SKILL_PAGES; n += 1) {
-            last = await project.skillFile(file, offset === undefined ? {} : { offset });
+            last = await reader.skillFile(file, offset === undefined ? {} : { offset });
             if (last.read === null) {
                 break;
             }
@@ -910,7 +930,7 @@ const skill = async (args, io) => {
         answer(io, session, { ...fileRead, read: whole === undefined ? null : bodyOfFile(whole) }, () => formatSkillFile(fileRead, whole));
         return EXIT.ok;
     }
-    const wanted = skillPathIn(theOne(positionals, "Say which skill: console skill <path of its SKILL.md>, or console skill --file <path> for a file of the pack"), listing.address);
+    const wanted = skillPathIn(theOne(positionals, `Say which skill: ${command} <path of its SKILL.md>, or ${command} --file <path> for a file of the pack`), listing.address);
     if ("error" in wanted) {
         throw misuse(wanted.error);
     }
@@ -919,7 +939,7 @@ const skill = async (args, io) => {
     let cursor;
     let last;
     for (let n = 0; n < MAX_SKILL_PAGES; n += 1) {
-        last = await project.skill(wanted.path, cursor);
+        last = await reader.skill(wanted.path, cursor);
         if (last.read?.status !== "ready") {
             break;
         }
@@ -936,7 +956,492 @@ const skill = async (args, io) => {
     const whole = joinSkill(pages, summary);
     answer(io, session, { ...loaded, read: whole === undefined ? null : bodyOfSkill(whole) }, () => formatSkillLoad(loaded, whole));
     return EXIT.ok;
+}
+const skill = async (args, io) => {
+    const { values, positionals } = parse(args, SKILL_OPTIONS);
+    const session = await open(io, values);
+    const project = await session.project();
+    return readSkill(io, session, project, values, positionals, "console skill");
+};
+// ---- The plugins (docs/specs/plugins.md, "The command") ----
+// `console plugins` and `console plugin <key> ...` are the two entries: the command sends the
+// words as typed and renders the console's generic shapes, and knows nothing of any plugin.
+const plugins = async (args, io) => {
+    const { values } = parse(args, {}, false);
+    const session = await open(io, values);
+    const [listed, me] = await Promise.all([session.client.plugins(), session.client.me()]);
+    answer(io, session, listed, () => formatPlugins(listed, me.language));
+    return EXIT.ok;
+};
+/** The flags of the command's own on `console plugin ...`, wherever they stand among the words. */
+const PLUGIN_GLOBAL_FLAGS = {
+    json: "boolean",
+    url: "string",
+    account: "string",
+    project: "string",
+};
+/** The flags of the command's own on a plugin's command: the file it uploads first, the run it is for. */
+const PLUGIN_COMMAND_FLAGS = {
+    file: "string",
+    run: "string",
+};
+/**
+ * The words with the flags named in `own` taken out, wherever they stand: the rest is the
+ * plugin's, and goes to the console as typed. `--` ends the flags, and stays among the words.
+ */
+function splitWords(args, own) {
+    const values = {};
+    const words = [];
+    let ended = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const word = args[index] ?? "";
+        if (ended || !word.startsWith("--") || word.length === 2) {
+            ended = ended || word === "--";
+            words.push(word);
+            continue;
+        }
+        const equals = word.indexOf("=");
+        const name = equals < 0 ? word.slice(2) : word.slice(2, equals);
+        const type = Object.hasOwn(own, name) ? own[name] : undefined;
+        if (type === undefined) {
+            words.push(word);
+            continue;
+        }
+        if (type === "boolean") {
+            if (equals >= 0) {
+                throw misuse(`--${name} takes no value`);
+            }
+            values[name] = true;
+            continue;
+        }
+        if (equals >= 0) {
+            values[name] = word.slice(equals + 1);
+            continue;
+        }
+        const next = args[index + 1];
+        if (next === undefined) {
+            throw misuse(`--${name} needs a value`);
+        }
+        values[name] = next;
+        index += 1;
+    }
+    return { values, words };
+}
+const PLUGIN_USAGE = "console plugin <key> [help [<command>] | <command> [args] | records <collection> | skills | skill <path> | enable | disable | settings | secret <name> | grant <role> | revoke <id>]. console plugins lists the plugins.";
+const plugin = async (args, io) => {
+    const { values, words } = splitWords(args, PLUGIN_GLOBAL_FLAGS);
+    const [key, verb, ...rest] = words;
+    if (key === undefined || key.startsWith("-")) {
+        throw misuse(`Say which plugin: ${PLUGIN_USAGE}`);
+    }
+    const session = await open(io, values);
+    const client = session.client.plugin(key);
+    switch (verb) {
+        case undefined: {
+            const [detail, me] = await Promise.all([client.get(), session.client.me()]);
+            answer(io, session, detail, () => formatPlugin(detail, me.language));
+            return EXIT.ok;
+        }
+        case "help": {
+            if (rest.length > 1) {
+                throw misuse(`Say one command: console plugin ${key} help [<command>]`);
+            }
+            const name = rest[0];
+            const detail = await client.get();
+            const operation = name === undefined
+                ? undefined
+                : detail.operations.find((candidate) => candidate.name === name);
+            if (name !== undefined && operation === undefined) {
+                throw misuse(`Not a command or a query of ${key} you may run: ${name}. console plugin ${key} lists them.`);
+            }
+            answer(io, session, operation ?? detail.operations, () => formatPluginHelp(detail, name));
+            return EXIT.ok;
+        }
+        case "records":
+            return pluginRecords(io, session, client, rest, text(values, "project"));
+        case "skills": {
+            const parsed = parse(rest, SKILLS_OPTIONS);
+            return readSkills(io, session, client, parsed.values, parsed.positionals, {
+                command: `console plugin ${key} skills`,
+            });
+        }
+        case "skill": {
+            const parsed = parse(rest, SKILL_OPTIONS);
+            return readSkill(io, session, client, parsed.values, parsed.positionals, `console plugin ${key} skill`);
+        }
+        case "enable":
+            return pluginEnable(io, session, client, rest);
+        case "disable": {
+            parse(rest, {}, false);
+            const detail = await client.disable();
+            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 "settings":
+            return pluginSettings(io, session, client, rest);
+        case "secret":
+            return pluginSecret(io, session, client, rest);
+        case "grant":
+            return pluginGrant(io, session, client, rest, text(values, "project"));
+        case "revoke": {
+            const { positionals } = parse(rest, {});
+            const id = theOne(positionals, `Say which grant: console plugin ${key} revoke <grant id>`);
+            const revoked = await client.revoke(id);
+            answer(io, session, revoked, () => `Revoked: ${formatPluginGrantLine(revoked)}`);
+            return EXIT.ok;
+        }
+        default:
+            return pluginInvoke(io, session, client, verb, rest);
+    }
 };
+/** A query's answer that is a file, as the console carries one: its name, its type, its bytes as base64. */
+function queryFileOf(result) {
+    if (result.kind !== "query" || typeof result.data !== "object" || result.data === null) {
+        return undefined;
+    }
+    const file = result.data.file;
+    if (typeof file !== "object" ||
+        file === null ||
+        typeof file.name !== "string" ||
+        typeof file.type !== "string" ||
+        typeof file.base64 !== "string") {
+        return undefined;
+    }
+    const named = file;
+    return {
+        name: basename(named.name) || "answer",
+        type: named.type,
+        bytes: Uint8Array.from(Buffer.from(named.base64, "base64")),
+    };
+}
+/**
+ * A command or a query of the plugin, by the words as typed: a file named with --file, or read
+ * from standard input for -, is uploaded first and goes as a handle; the console parses the rest.
+ */
+async function pluginInvoke(io, session, client, name, rest) {
+    const { values, words } = splitWords(rest, PLUGIN_COMMAND_FLAGS);
+    const stdin = words.includes("-");
+    const filePath = text(values, "file");
+    if (filePath !== undefined && stdin) {
+        throw misuse("Say one file: --file <path>, or - for standard input.");
+    }
+    const files = [];
+    if (filePath !== undefined) {
+        let bytes;
+        try {
+            bytes = await io.readBytes(filePath);
+        }
+        catch {
+            throw misuse(`The file could not be read: ${filePath}`);
+        }
+        const fileName = basename(filePath);
+        const uploaded = await client.upload({
+            name: fileName,
+            bytes,
+            contentType: CONTENT_TYPES[extname(fileName).toLowerCase()] ?? "application/octet-stream",
+        });
+        files.push(uploaded.handle);
+    }
+    else if (stdin) {
+        const uploaded = await client.upload({
+            name: "stdin.txt",
+            bytes: new TextEncoder().encode(await io.readStdin()),
+            contentType: "text/plain",
+        });
+        files.push(uploaded.handle);
+    }
+    const project = await session.projectKey();
+    const run = text(values, "run");
+    const result = await client.invoke({
+        argv: [name, ...words.filter((word) => word !== "-")],
+        ...(files.length === 0 ? {} : { files }),
+        ...(project === undefined ? {} : { project }),
+        ...(run === undefined ? {} : { run }),
+    });
+    // A query that answers a file: saved under its name in the working directory, as console file saves one.
+    const file = queryFileOf(result);
+    let saved;
+    if (file !== undefined && !session.json) {
+        try {
+            saved = await io.writeBytes(file.name, file.bytes, file.name);
+        }
+        catch {
+            throw failed(`The file could not be written at ${file.name}.`);
+        }
+    }
+    answer(io, session, result, () => file !== undefined && saved !== undefined
+        ? `Saved ${file.name} (${file.bytes.byteLength} bytes, ${file.type}) at ${saved}`
+        : formatInvocation(result));
+    return result.waiting === null ? EXIT.ok : EXIT.waiting;
+}
+/** A condition's value as typed: a number, true, false and null read as such; JSON where it begins as JSON; text otherwise. */
+function whereValueOf(word) {
+    if (word === "true") {
+        return true;
+    }
+    if (word === "false") {
+        return false;
+    }
+    if (word === "null") {
+        return null;
+    }
+    if (/^-?\d+(?:\.\d+)?$/.test(word)) {
+        return Number(word);
+    }
+    if (word.startsWith("{") || word.startsWith("[")) {
+        try {
+            return JSON.parse(word);
+        }
+        catch {
+            return word;
+        }
+    }
+    return word;
+}
+/** The records of a collection one may read, a page of them; or one record, or its versions. */
+async function pluginRecords(io, session, client, rest, project) {
+    const { values, positionals } = parse(rest, {
+        where: { type: "string", multiple: true },
+        search: { type: "string" },
+        order: { type: "string" },
+        limit: { type: "string" },
+        after: { type: "string" },
+        archived: { type: "boolean" },
+        versions: { type: "boolean" },
+    });
+    const [collection, id, ...more] = positionals;
+    if (collection === undefined || more.length > 0) {
+        throw misuse(`Say which collection: console plugin ${client.key} records <collection> [<id>] [--where <field>=<value>]... [--search <words>] [--order <field>[:desc]] [--limit <n>] [--after <cursor>] [--archived] [--versions]`);
+    }
+    if (id !== undefined) {
+        if (on(values, "versions")) {
+            const versions = await client.recordVersions(collection, id);
+            answer(io, session, versions, () => formatPluginRecordVersions(versions));
+            return EXIT.ok;
+        }
+        const record = await client.record(collection, id);
+        answer(io, session, record, () => formatPluginRecord(record));
+        return EXIT.ok;
+    }
+    if (on(values, "versions")) {
+        throw misuse("--versions goes with a record's id: console plugin <key> records <collection> <id> --versions");
+    }
+    const where = {};
+    for (const pair of texts(values, "where")) {
+        const equals = pair.indexOf("=");
+        if (equals <= 0) {
+            throw misuse(`Not a condition, as <field>=<value>: ${pair}`);
+        }
+        where[pair.slice(0, equals)] = whereValueOf(pair.slice(equals + 1));
+    }
+    const order = text(values, "order");
+    const page = await client.records(collection, {
+        ...(Object.keys(where).length === 0 ? {} : { where }),
+        q: text(values, "search"),
+        order: order === undefined ? undefined : order.endsWith(":desc") ? `-${order.slice(0, -5)}` : order,
+        limit: countOf(text(values, "limit"), "limit", { least: 1, most: PLUGIN_LIST_LIMIT }),
+        after: text(values, "after"),
+        project,
+        archived: on(values, "archived") ? true : undefined,
+    });
+    answer(io, session, page, () => formatPluginRecords(page));
+    return EXIT.ok;
+}
+/** The values `--set <key>=<value>` give, each read as its setting's type; an empty value clears one. */
+function settingValuesOf(pairs, detail) {
+    const values = {};
+    const read = (type, word, key) => {
+        switch (type) {
+            case "number": {
+                const value = Number(word);
+                if (!Number.isFinite(value) || word.trim().length === 0) {
+                    throw misuse(`Not a number for the setting ${key}: ${word}`);
+                }
+                return value;
+            }
+            case "boolean":
+                if (word !== "true" && word !== "false") {
+                    throw misuse(`The setting ${key} is true or false: ${word}`);
+                }
+                return word === "true";
+            default:
+                return word;
+        }
+    };
+    for (const pair of pairs) {
+        const equals = pair.indexOf("=");
+        if (equals <= 0) {
+            throw misuse(`Not a setting, as <key>=<value>: ${pair}`);
+        }
+        const key = pair.slice(0, equals);
+        const word = pair.slice(equals + 1);
+        const setting = detail.settings.find((candidate) => candidate.key === key);
+        if (setting === undefined) {
+            throw misuse(`Not a setting of ${detail.key}: ${key}. Its settings: ${detail.settings.map((candidate) => candidate.key).join(", ") || "none"}`);
+        }
+        if (setting.type === "secret") {
+            throw misuse(`${key} is a secret: console plugin ${detail.key} secret ${key} reads it from standard input.`);
+        }
+        if (word.length === 0) {
+            values[key] = null;
+        }
+        else if (setting.type === "list") {
+            values[key] = word
+                .split(",")
+                .map((item) => item.trim())
+                .filter((item) => item.length > 0)
+                .map((item) => read(setting.of ?? "text", item, key));
+        }
+        else {
+            values[key] = read(setting.type, word, key);
+        }
+    }
+    return values;
+}
+/** The capabilities a plugin asks, each with what it opens and what it risks, for the administrator to read before consenting. */
+function capabilityLines(capabilities) {
+    return capabilities.map((capability) => {
+        const words = capabilityWords(capability);
+        return words === undefined
+            ? `  ${capability}: a capability this command does not know`
+            : `  ${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. */
+async function pluginEnable(io, session, client, rest) {
+    const { values, positionals } = parse(rest, {
+        consent: { type: "string", multiple: true },
+        board: { type: "string" },
+        projects: { type: "string", multiple: true },
+        set: { type: "string", multiple: true },
+    });
+    if (positionals.length > 0) {
+        throw misuse(`Nothing follows enable but its flags: console plugin ${client.key} enable [--consent <capability>,...] [--board new|<key>] [--projects all|<key>,...] [--set <key>=<value>]...`);
+    }
+    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);
+    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`);
+    }
+    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(", ")}.`);
+    }
+    const boardFlag = text(values, "board");
+    let board = null;
+    if (boardFlag === "new") {
+        if (detail.boardDefaults === null) {
+            throw misuse(`${detail.key} names no defaults for a board project: choose one with --board <key>.`);
+        }
+        board = {
+            create: {
+                key: detail.boardDefaults.key,
+                name: localized(detail.boardDefaults.name, me.language),
+                description: localized(detail.boardDefaults.description, me.language),
+            },
+        };
+    }
+    else if (boardFlag !== undefined) {
+        board = { project: boardFlag };
+    }
+    const named = texts(values, "projects")
+        .flatMap((value) => value.split(","))
+        .map((key) => key.trim())
+        .filter((key) => key.length > 0);
+    const settings = settingValuesOf(texts(values, "set"), detail);
+    const enabled = await client.enable({
+        consent,
+        board,
+        projects: named.length === 0 || named.includes("all") ? "all" : named,
+        ...(Object.keys(settings).length === 0 ? {} : { settings }),
+    });
+    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.settings.length === 0
+            ? []
+            : [
+                "Settings:",
+                ...enabled.settings.map((setting) => formatPluginSettingLine(setting, me.language)),
+            ]),
+    ].join("\n"));
+    return EXIT.ok;
+}
+/** The settings as they stand, or changed as `--set` says; an administrator's. */
+async function pluginSettings(io, session, client, rest) {
+    const { values, positionals } = parse(rest, { set: { type: "string", multiple: true } });
+    if (positionals.length > 0) {
+        throw misuse(`Nothing follows settings but --set: console plugin ${client.key} settings [--set <key>=<value>]...`);
+    }
+    const [detail, me] = await Promise.all([client.get(), session.client.me()]);
+    const sets = texts(values, "set");
+    if (sets.length === 0) {
+        answer(io, session, detail.settings, () => detail.settings.length === 0
+            ? `${detail.key} has no settings.`
+            : [
+                `Settings of ${detail.key}:`,
+                ...detail.settings.map((setting) => formatPluginSettingLine(setting, me.language)),
+            ].join("\n"));
+        return EXIT.ok;
+    }
+    const changed = await client.updateSettings({ values: settingValuesOf(sets, detail) });
+    answer(io, session, changed.settings, () => [
+        `Changed the settings of ${changed.key}:`,
+        ...changed.settings.map((setting) => formatPluginSettingLine(setting, me.language)),
+    ].join("\n"));
+    return EXIT.ok;
+}
+/** Seals a secret of the plugin, read from standard input and shown never; or takes it away. */
+async function pluginSecret(io, session, client, rest) {
+    const { values, positionals } = parse(rest, { remove: { type: "boolean" } });
+    const name = theOne(positionals, `Say which secret: console plugin ${client.key} secret <name> [--remove]; the value is read from standard input.`);
+    if (on(values, "remove")) {
+        await client.removeSecret(name);
+        answer(io, session, { name, set: false }, () => `Removed the secret ${name} of ${client.key}.`);
+        return EXIT.ok;
+    }
+    const value = (await io.readStdin()).replace(/\r?\n$/, "");
+    if (value.length === 0) {
+        throw misuse(`Pipe the value in: console plugin ${client.key} secret ${name} < file. It is sealed by the console and shown never.`);
+    }
+    await client.setSecret(name, value);
+    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. */
+async function pluginGrant(io, session, client, rest, projectKey) {
+    const { values, positionals } = parse(rest, {
+        person: { type: "string" },
+        everyone: { type: "boolean" },
+    });
+    const usage = `console plugin ${client.key} grant <role> --person <login> | --project <key> | --everyone`;
+    const role = theOne(positionals, `Say which role: ${usage}`);
+    const login = text(values, "person");
+    const everyone = on(values, "everyone");
+    if ([login !== undefined, projectKey !== undefined, everyone].filter(Boolean).length !== 1) {
+        throw misuse(`Say whom, one of the three: ${usage}`);
+    }
+    let input;
+    if (login !== undefined) {
+        const person = await session.client.findPerson(login);
+        if (person === undefined) {
+            throw failed(`No person has the login ${login} among those you may see.`);
+        }
+        input = { role, person: person.id };
+    }
+    else if (projectKey !== undefined) {
+        input = { role, project: projectKey };
+    }
+    else {
+        input = { role, everyone: true };
+    }
+    const granted = await client.grant(input);
+    answer(io, session, granted, () => `Granted: ${formatPluginGrantLine(granted)}`);
+    return EXIT.ok;
+}
 /** A version number given as a flag, or nothing; anything else is not understood. */
 function versionOf(given) {
     if (given === undefined) {
@@ -1018,9 +1523,10 @@ const rules = async (args, io) => {
         ? {
             workspace: forPerson(found.workspace, me.language),
             project: forPerson(found.project, me.language),
+            ...(found.plugins === undefined ? {} : { plugins: found.plugins }),
         }
         : forPerson(found, me.language);
-    answer(io, session, read, () => formatRules(read));
+    answer(io, session, read, () => formatRules(read, me.language));
     return EXIT.ok;
 };
 /**
@@ -1210,6 +1716,22 @@ const comment = async (args, io) => {
     if (body.trim().length === 0 && paths.length === 0) {
         throw misuse(`Say something, or attach a file. ${ask}`);
     }
+    const files = await attachmentsOf(io, paths);
+    const session = await open(io, values);
+    const project = await session.project();
+    const task = await project.task(ref);
+    const written = await project.comment(task.id, { body, files });
+    answer(io, session, written, () => [
+        `Commented on #${task.number} ${task.title}${written.files.length === 0 ? "" : `, with ${written.files.length} file${written.files.length === 1 ? "" : "s"}`}.`,
+        formatComment(written),
+    ].join("\n"));
+    return EXIT.ok;
+};
+/**
+ * The files named by --attach, read from this machine: each called by its name, without the
+ * path, and typed by its extension where the extension says.
+ */
+async function attachmentsOf(io, paths) {
     const files = [];
     for (const path of paths) {
         let bytes;
@@ -1223,20 +1745,12 @@ const comment = async (args, io) => {
         const contentType = CONTENT_TYPES[extname(name).toLowerCase()];
         files.push({ name, bytes, ...(contentType === undefined ? {} : { contentType }) });
     }
-    const session = await open(io, values);
-    const project = await session.project();
-    const task = await project.task(ref);
-    const written = await project.comment(task.id, { body, files });
-    answer(io, session, written, () => [
-        `Commented on #${task.number} ${task.title}${written.files.length === 0 ? "" : `, with ${written.files.length} file${written.files.length === 1 ? "" : "s"}`}.`,
-        formatComment(written),
-    ].join("\n"));
-    return EXIT.ok;
-};
+    return files;
+}
 /**
  * A file of the project, read from the console and written on this machine: one a run handed
- * in, one put in a comment, or one attached to a page, by its id, so that an agent can look at
- * a picture a person put on the board.
+ * in, one put in a comment or on a decision, or one attached to a page, by its id, so that an
+ * agent can look at a picture a person put on the board.
  */
 const file = async (args, io) => {
     const { values, positionals } = parse(args, { out: { type: "string" } });
@@ -1294,6 +1808,7 @@ const take = async (args, io) => {
     const rules = {
         workspace: forPerson(ruling.workspace, me.language),
         project: forPerson(ruling.project, me.language),
+        ...(ruling.plugins === undefined ? {} : { plugins: ruling.plugins }),
     };
     answer(io, session, { run, task: taken, comments: comments.items, rules }, () => [
         `Run ${run.id} began on #${found.number} ${found.title}, as "${run.agent}" for ${run.person.login}. The task is in progress and theirs.${tookOver}${elsewhere}`,
@@ -1303,7 +1818,7 @@ const take = async (args, io) => {
         "",
         formatTask(taken, undefined, undefined, comments.items),
         "",
-        formatRules(rules),
+        formatRules(rules, me.language),
         "",
         'Say how it goes: console report "<what you found or did>". Hand in what you make: console hand-in <https url | file path>.',
         'Ask when a person must decide: console ask "<question>" --option "..." --option "...". A word for the task\'s people that is not a report: console comment <number> "<markdown>". End with: console finish --summary "<what was done, what is left>".',
@@ -1395,6 +1910,7 @@ const ask = async (args, io) => {
         run: { type: "string" },
         wait: { type: "string" },
         to: { type: "string" },
+        attach: { type: "string", multiple: true },
     });
     const question = theOne(positionals, 'Say the question: console ask "<question>" --option "<label>" --option "<label>"');
     const to = text(values, "to");
@@ -1407,6 +1923,8 @@ const ask = async (args, io) => {
     }
     const seconds = secondsOf(text(values, "wait"), DEFAULT_ASK_WAIT_SECONDS);
     const body = await bodyOf(io, values, text(values, "body"));
+    // The files put on the decision (ADR-0055): a picture of what is to be chosen between, for one.
+    const files = await attachmentsOf(io, texts(values, "attach"));
     const session = await open(io, values);
     const project = await session.project();
     const runId = await currentRun(project, values);
@@ -1418,11 +1936,12 @@ const ask = async (args, io) => {
         runId,
         ...(body === undefined ? {} : { body }),
         ...(typeof deciderId === "string" ? { deciderId } : {}),
-    });
+    }, 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}; 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 ${raised.decider.login}.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`);
     return settle(io, session, project, raised, seconds, true);
 };
 /**
@@ -2294,6 +2813,8 @@ const COMMANDS = {
     skills,
     skill,
     rules,
+    plugins,
+    plugin,
     people,
     person,
     workspace,