@skillcdn/console 0.1.16 → 0.1.18

package/dist/cli/cli.js

@@ -1,14 +1,16 @@
 import { basename, extname } from "node:path";
 import { parseArgs } from "node:util";
 import { ApiError, createClient, } from "../client.js";
+import { CLIENT_RANGE_HEADER, judgeClient, parseVersion, VERSION_HEADER } from "../compat.js";
 import { addDays, dayOf as dayOfDate, isDay } from "../dates.js";
 import { DEFAULT_PAGE_LIMIT, LIST_LIMIT, MAX_OPTIONS, MIN_OPTIONS } from "../limits.js";
 import { fillRules, RULES_PATH, RULES_TITLE } from "../rules.js";
 import { hostOfLogin, } from "../schemas.js";
 import { COLOR_NAMES, GOAL_STATES, PERSON_ROLES, PROJECT_ROLES, PROJECT_VISIBILITIES, PROVIDER_KEYS, TASK_PRIORITIES, TASK_STATES, } from "../vocabulary.js";
 import { loadWebRoot, WebRootError } from "../web.js";
-import { formatAnswer, formatCategoryLine, formatDecision, formatDecisionLine, formatDocument, formatDocuments, formatGoal, formatGoalLine, formatListingLine, formatMemberLine, formatMore, formatOptions, formatPersonLine, formatPersonWork, formatProject, formatProjectLine, formatRules, formatRun, formatRunLine, formatSkills, formatTask, formatTaskLine, formatVersion, formatVersionLine, formatWork, } from "./format.js";
+import { formatAnswer, formatCategoryLine, formatComment, formatDecision, formatDecisionLine, formatDocument, formatDocuments, formatGoal, formatGoalLine, formatListingLine, formatMemberLine, formatMore, formatOptions, formatPersonLine, formatPersonWork, formatProject, formatProjectLine, formatRules, formatRun, formatRunLine, formatSkills, formatTask, formatTaskLine, formatVersion, formatVersionLine, formatWork, } from "./format.js";
 import { COMMAND_HELP, helpFor, usage } from "./help.js";
+import { describeInstall, updateCommandFor } from "./install.js";
 import { createServeHandler, DEFAULT_SERVE_PORT } from "./serve.js";
 // The `console` command (docs/specs/cli.md): the agent's side of the console. A thin client of
 // the REST API with no logic of its own: every command is one or two requests and the words to
@@ -24,7 +26,11 @@ export const EXIT = {
     usage: 2,
     /** The decision still waits for a person. */
     waiting: 3,
+    /** The command and the console do not go together (ADR-0025): stderr says which to update, and how. */
+    incompatible: 4,
 };
+/** A day, for how often the command repeats what it noticed of the versions. */
+const DAY_MS = 86_400_000;
 /** How long one request for a decision's answer asks the console to hold it: what the server allows. */
 const WAIT_STEP_SECONDS = 50;
 /** A breath between two such requests, should the console answer at once. */
@@ -83,7 +89,7 @@ async function open(io, values) {
     if (url === undefined || token === undefined) {
         throw failed("Not signed in. A person signs the command in: console login --url <the console's origin>");
     }
-    const client = createClient({ baseUrl: url, token, fetch: io.fetch });
+    const client = clientOf(io, url, token);
     const projectKey = async () => text(values, "project") ?? io.env.CONSOLE_PROJECT ?? (await io.directory.load())?.project;
     return {
         client,
@@ -323,7 +329,7 @@ async function settle(io, session, project, decision, seconds, shown = false) {
 }
 /** Checks a token against the console, keeps it with the address, and says who it is. */
 async function keep(io, url, token, agent) {
-    const me = await createClient({ baseUrl: url, token, fetch: io.fetch }).me();
+    const me = await clientOf(io, url, token).me();
     const person = me.person;
     if (person === null) {
         throw failed("The console does not know this token. Make one on your Agents page and try again.");
@@ -349,7 +355,7 @@ const login = async (args, io) => {
     }
     // A connection (ADR-0011): a code a person approves on the console's own pages, and the token
     // handed over here once, never shown.
-    const client = createClient({ baseUrl: url, fetch: io.fetch });
+    const client = clientOf(io, url);
     // "<agent> on <machine>": the pages say the agent and keep the machine for a hover.
     const agent = text(values, "agent") ?? agentOf(io.env) ?? "An agent";
     const begun = await client.connect({
@@ -387,7 +393,7 @@ const logout = async (args, io) => {
     // Agents page, and the person is told so.
     let gone = true;
     try {
-        await createClient({ baseUrl: url, token, fetch: io.fetch }).giveUpToken();
+        await clientOf(io, url, token).giveUpToken();
     }
     catch (error) {
         if (!(error instanceof ApiError && error.code === "auth.required")) {
@@ -422,7 +428,31 @@ const whoami = async (args, io) => {
         throw failed("The console does not know this token. Sign in again: console login");
     }
     const key = await session.projectKey();
-    answer(io, session, { ...me, project: key ?? null }, () => `${person.login} (${person.role}) at ${me.workspace.name}, ${session.url}${key === undefined ? "; no project named here" : `; project ${key}`}`);
+    const command = parseVersion(io.version);
+    const server = parseVersion(me.console?.version);
+    const verdict = command === undefined || server === undefined
+        ? undefined
+        : judgeClient(command, server).verdict;
+    // A console from before the rule says nothing of itself; the command says so instead.
+    const consoleWords = me.console === undefined
+        ? "the console does not say its version, so it is older than 0.1.18"
+        : `the console is ${me.console.version} and takes ${me.console.clientRange}`;
+    answer(io, session, {
+        ...me,
+        console: me.console ?? null,
+        project: key ?? null,
+        command: { version: io.version ?? null, install: io.install ?? null },
+    }, () => [
+        `${person.login} (${person.role}) at ${me.workspace.name}, ${session.url}${key === undefined ? "; no project named here" : `; project ${key}`}`,
+        `This command is ${io.version ?? "of a version it does not know"}${io.install === undefined ? "" : `, ${describeInstall(io.install)}`}; ${consoleWords}.`,
+        ...(verdict === "behind"
+            ? [`A newer command exists. Update it: ${updateWords(io, me.console?.version)}`]
+            : verdict === "ahead"
+                ? [
+                    `This command is newer than the console: what the console has not got yet is refused as not found. To match the console: ${updateWords(io, me.console?.version)}`,
+                ]
+                : []),
+    ].join("\n"));
     return EXIT.ok;
 };
 const projects = async (args, io) => {
@@ -697,11 +727,82 @@ const task = async (args, io) => {
     const session = await open(io, values);
     const project = await session.project();
     const found = await project.task(ref);
-    const [decisions, runs] = await Promise.all([
+    const [decisions, runs, comments] = await Promise.all([
         project.decisions({ task: found.id }),
         project.runs({ task: found.id }),
+        project.comments(found.id),
     ]);
-    answer(io, session, { task: found, decisions: decisions.items, runs: runs.items }, () => formatTask(found, decisions.items, runs.items));
+    answer(io, session, { task: found, decisions: decisions.items, runs: runs.items, comments: comments.items }, () => formatTask(found, decisions.items, runs.items, comments.items));
+    return EXIT.ok;
+};
+/**
+ * A word in the discussion on a task (ADR-0024): what is said, as given, from a file or from
+ * standard input, with the files named by --attach put in it; one request, one comment.
+ */
+const comment = async (args, io) => {
+    const { values, positionals } = parse(args, {
+        file: { type: "string" },
+        attach: { type: "string", multiple: true },
+    });
+    const ask = 'Say which task, and what: console comment <number|id> "<markdown>" [--file <path> | -] [--attach <path>]...';
+    if (positionals.length === 0 || positionals.length > 2) {
+        throw misuse(ask);
+    }
+    const ref = positionals[0] ?? "";
+    const body = (await bodyOf(io, values, positionals[1])) ?? "";
+    const paths = texts(values, "attach");
+    if (body.trim().length === 0 && paths.length === 0) {
+        throw misuse(`Say something, or attach a file. ${ask}`);
+    }
+    const files = [];
+    for (const path of paths) {
+        let bytes;
+        try {
+            bytes = await io.readBytes(path);
+        }
+        catch {
+            throw failed(`No file could be read at ${path}. Name the path of a file to attach.`);
+        }
+        const name = basename(path);
+        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;
+};
+/**
+ * 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.
+ */
+const file = async (args, io) => {
+    const { values, positionals } = parse(args, { out: { type: "string" } });
+    const id = theOne(positionals, "Say which file: console file <id> [--out <path>]");
+    const session = await open(io, values);
+    const project = await session.project();
+    const read = await project.readFile(id);
+    const target = text(values, "out") ?? read.name;
+    let saved;
+    try {
+        saved = await io.writeBytes(target, read.bytes, read.name);
+    }
+    catch {
+        throw failed(`The file could not be written at ${target}. Name a path with --out <path>.`);
+    }
+    answer(io, session, {
+        id,
+        name: read.name,
+        contentType: read.contentType,
+        size: read.bytes.byteLength,
+        path: saved,
+    }, () => `Saved ${read.name} (${read.bytes.byteLength} bytes, ${read.contentType}) at ${saved}`);
     return EXIT.ok;
 };
 const take = async (args, io) => {
@@ -717,10 +818,11 @@ const take = async (args, io) => {
     });
     // The rules come with the run, as they read for the person: everything from here acts
     // within them (ADR-0023); the task is read again, as it stands now that it is taken.
-    const [ruling, me, taken] = await Promise.all([
+    const [ruling, me, taken, comments] = await Promise.all([
         project.rules(),
         session.client.me(),
         project.task(ref),
+        project.comments(found.id),
     ]);
     // Taking a task with a run open on it ends that run (ADR-0020): said when it happened.
     const tookOver = found.openRuns > 0
@@ -730,15 +832,15 @@ const take = async (args, io) => {
         workspace: forPerson(ruling.workspace, me.language),
         project: forPerson(ruling.project, me.language),
     };
-    answer(io, session, { run, task: taken, rules }, () => [
+    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}`,
         "",
-        formatTask(taken),
+        formatTask(taken, undefined, undefined, comments.items),
         "",
         formatRules(rules),
         "",
         '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 "...". End with: console finish --summary "<what was done, what is left>".',
+        '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>".',
     ].join("\n"));
     return EXIT.ok;
 };
@@ -1005,25 +1107,40 @@ const restore = async (args, io) => {
     return EXIT.ok;
 };
 const goals = async (args, io) => {
-    const { values } = parse(args, {}, false);
+    const { values } = parse(args, { category: { type: "string" }, state: { type: "string" } }, false);
+    const state = goalStateOf(text(values, "state"));
+    const category = text(values, "category");
     const session = await open(io, values);
     const project = await session.project();
-    const found = await project.goals();
+    const found = await project.goals({
+        ...(state === undefined ? {} : { state }),
+        ...(category === undefined ? {} : { category }),
+    });
     answer(io, session, found, () => found.items.length === 0
-        ? "No goals. An owner sets one: console goal new <title> --due <day>"
+        ? state === undefined && category === undefined
+            ? "No goals. An owner sets one: console goal new <title> --due <day>"
+            : "No goal matches."
         : found.items.map(formatGoalLine).join("\n"));
     return EXIT.ok;
 };
 const GOAL_FIELDS = {
     state: { type: "string" },
+    category: { type: "string" },
+    starts: { type: "string" },
     due: { type: "string" },
     body: { type: "string" },
     file: { type: "string" },
 };
+/** A category's key as a flag names one, or `null` for `none` where the field may be cleared. */
+function categoryOf(value, clearable = false) {
+    return clearable && value === "none" ? null : value;
+}
 const newGoal = async (args, io) => {
     const { values, positionals } = parse(args, GOAL_FIELDS);
     const title = theOne(positionals, 'Say the title: console goal new "<title>" [--due <day>]');
     const state = goalStateOf(text(values, "state"));
+    const category = categoryOf(text(values, "category"));
+    const startsOn = dayOf(io, text(values, "starts"));
     const dueOn = dayOf(io, text(values, "due"));
     const body = await bodyOf(io, values, text(values, "body"));
     const session = await open(io, values);
@@ -1032,6 +1149,8 @@ const newGoal = async (args, io) => {
         title,
         ...(body === undefined ? {} : { body }),
         ...(state === undefined ? {} : { state }),
+        ...(category === undefined ? {} : { category }),
+        ...(startsOn === undefined ? {} : { startsOn }),
         ...(dueOn === undefined ? {} : { dueOn }),
     });
     answer(io, session, made, () => `Goal set: ${made.title}\nid: ${made.id}`);
@@ -1042,16 +1161,20 @@ const editGoal = async (args, io) => {
     const id = theOne(positionals, "Say which goal: console goal edit <id> --state <state> ...");
     const title = text(values, "title");
     const state = goalStateOf(text(values, "state"));
+    const category = categoryOf(text(values, "category"), true);
+    const startsOn = dayOf(io, text(values, "starts"), true);
     const dueOn = dayOf(io, text(values, "due"), true);
     const body = await bodyOf(io, values, text(values, "body"));
     const patch = {
         ...(title === undefined ? {} : { title }),
         ...(body === undefined ? {} : { body }),
         ...(state === undefined ? {} : { state }),
+        ...(category === undefined ? {} : { category }),
+        ...(startsOn === undefined ? {} : { startsOn }),
         ...(dueOn === undefined ? {} : { dueOn }),
     };
     if (Object.keys(patch).length === 0) {
-        throw misuse("Say what to change: --title, --body, --state or --due; --due none clears the day.");
+        throw misuse("Say what to change: --title, --body, --state, --category, --starts or --due; none clears a category or a day.");
     }
     const session = await open(io, values);
     const project = await session.project();
@@ -1476,6 +1599,8 @@ const COMMANDS = {
     take,
     report,
     "hand-in": handIn,
+    comment,
+    file,
     ask,
     decision,
     decisions,
@@ -1503,9 +1628,67 @@ function help(io, name) {
     io.stdout(found);
     return EXIT.ok;
 }
+/** A client of the console at `url`, naming the command on every request (ADR-0025). */
+function clientOf(io, url, token) {
+    return createClient({
+        baseUrl: url,
+        fetch: io.fetch,
+        ...(token === undefined ? {} : { token }),
+        ...(io.userAgent === undefined ? {} : { userAgent: io.userAgent }),
+    });
+}
+/** The command that puts the console's version where this command is installed. */
+function updateWords(io, version) {
+    const wanted = version ?? "latest";
+    if (io.install === undefined) {
+        return `npm install -g @skillcdn/console@${wanted}`;
+    }
+    const command = updateCommandFor(io.install, wanted);
+    return io.install.kind === "project" ? `${command} (in ${io.install.root})` : command;
+}
+/**
+ * What the command says of the versions once the console answered: that a newer command exists,
+ * or that this one is newer than the console; once a day for one pair of versions, on stderr,
+ * so that the console's JSON stays what it is. What is out of the range never gets here: the
+ * console refused it, and the refusal says what to do.
+ */
+async function noticeVersions(io, seen) {
+    const command = parseVersion(io.version);
+    const server = parseVersion(seen.version);
+    if (io.version === undefined ||
+        seen.version === undefined ||
+        command === undefined ||
+        server === undefined) {
+        return;
+    }
+    const { verdict } = judgeClient(command, server);
+    if (verdict !== "behind" && verdict !== "ahead") {
+        return;
+    }
+    const previous = await io.notices?.load();
+    const now = io.now();
+    if (previous !== undefined &&
+        previous.command === io.version &&
+        previous.console === seen.version &&
+        now - Date.parse(previous.shownAt) < DAY_MS) {
+        return;
+    }
+    io.stderr(verdict === "behind"
+        ? `A newer command exists: the console runs ${seen.version}, this command is ${io.version}. Update it: ${updateWords(io, seen.version)}\n`
+        : `This command (${io.version}) is newer than the console (${seen.version}, which takes ${seen.range ?? "an older line"}): what the console has not got yet is refused as not found. The console's operator updates it; to match the console meanwhile: ${updateWords(io, seen.version)}\n`);
+    await io.notices?.save({
+        command: io.version,
+        console: seen.version,
+        shownAt: new Date(now).toISOString(),
+    });
+}
 /** What a refusal of the console is followed by, when there is something to do about it. */
-function hintFor(error) {
+function hintFor(error, io, seen) {
     switch (error.code) {
+        case "client.outdated":
+            return `Update the command: ${updateWords(io, seen.version)}\n`;
+        case "client.too_new":
+            return `Install the console's version: ${updateWords(io, seen.version)}; or ask the console's operator to update the console.\n`;
         case "auth.required":
             return "The token is not one the console knows, any more or at all. A person signs the command in again: console login\n";
         case "project.not_found":
@@ -1524,6 +1707,10 @@ function hintFor(error) {
             return "The due day is before the start. Say a due day on or after it.\n";
         case "goal.not_found":
             return "No goal of this project has that id. console goals lists them.\n";
+        case "goal.invalid_category":
+            return "No category has that key. console categories lists them.\n";
+        case "goal.invalid_dates":
+            return "The target day is before the start. Say a target day on or after it.\n";
         case "auth.forbidden":
             return "What was asked is an administrator's, or an owner's of the project, and the person this token acts as is not one here. Hand the step to them.\n";
         case "project.key_taken":
@@ -1563,9 +1750,21 @@ function hintFor(error) {
 /** Runs the command and answers with its exit code. What it prints goes through `io`. */
 export async function runCli(argv, io) {
     const [name, ...rest] = argv;
+    // Every answer of the console says its version and the range it takes; the command reads
+    // them off the answers it gets anyway, and asks nothing more (ADR-0025).
+    const seen = {};
+    const watched = {
+        ...io,
+        fetch: async (input, init) => {
+            const response = await io.fetch(input, init);
+            seen.version = response.headers.get(VERSION_HEADER) ?? seen.version;
+            seen.range = response.headers.get(CLIENT_RANGE_HEADER) ?? seen.range;
+            return response;
+        },
+    };
     try {
         if (name === "--version" || name === "-v" || name === "version") {
-            io.stdout(`console ${io.version ?? "(version unknown)"} (@skillcdn/console)\n`);
+            io.stdout(`console ${io.version ?? "(version unknown)"} (@skillcdn/console)${io.install === undefined ? "" : `, ${describeInstall(io.install)}`}\n`);
             return EXIT.ok;
         }
         if (name === undefined || name === "help" || name === "--help" || name === "-h") {
@@ -1578,7 +1777,11 @@ export async function runCli(argv, io) {
         if (command === undefined) {
             throw misuse(`Not a command: ${name}. Run: console help`);
         }
-        return await command(rest, io);
+        const exit = await command(rest, watched);
+        if (name !== "whoami") {
+            await noticeVersions(io, seen);
+        }
+        return exit;
     }
     catch (error) {
         if (error instanceof CliExit) {
@@ -1586,8 +1789,10 @@ export async function runCli(argv, io) {
             return error.exit;
         }
         if (error instanceof ApiError) {
-            io.stderr(`${error.code}: ${error.message}\n${hintFor(error)}`);
-            return EXIT.failed;
+            io.stderr(`${error.code}: ${error.message}\n${hintFor(error, io, seen)}`);
+            return error.code === "client.outdated" || error.code === "client.too_new"
+                ? EXIT.incompatible
+                : EXIT.failed;
         }
         throw error;
     }