@skillcdn/console 0.1.16 → 0.1.18

package/src/cli/cli.ts

@@ -7,6 +7,7 @@ import {
   type FetchLike,
   type ProjectClient,
 } 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";
@@ -41,6 +42,7 @@ import type { DirectoryStore } from "./directory.js";
 import {
   formatAnswer,
   formatCategoryLine,
+  formatComment,
   formatDecision,
   formatDecisionLine,
   formatDocument,
@@ -66,6 +68,8 @@ import {
   formatWork,
 } from "./format.js";
 import { COMMAND_HELP, helpFor, usage } from "./help.js";
+import { describeInstall, type Install, updateCommandFor } from "./install.js";
+import type { NoticeStore } from "./notices.js";
 import { createServeHandler, DEFAULT_SERVE_PORT, type Listen } from "./serve.js";
 
 // The `console` command (docs/specs/cli.md): the agent's side of the console. A thin client of
@@ -83,8 +87,13 @@ 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,
 } as const;
 
+/** 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. */
@@ -107,6 +116,8 @@ export interface CliIo {
   readonly readFile: (path: string) => Promise<string>;
   /** A file handed in, as bytes. */
   readonly readBytes: (path: string) => Promise<Uint8Array>;
+  /** A file read from the console, written at a path, or into a directory under its name; says where. */
+  readonly writeBytes: (path: string, bytes: Uint8Array, name: string) => Promise<string>;
   readonly store: CredentialStore;
   /** What the working directory says of the project, and the way to write it. */
   readonly directory: DirectoryStore;
@@ -114,6 +125,12 @@ export interface CliIo {
   readonly now: () => number;
   /** The version of the package the command runs from, when the entry point knows it. */
   readonly version?: string | undefined;
+  /** What the command calls itself on every request (ADR-0025); nothing when it does not know its version. */
+  readonly userAgent?: string | undefined;
+  /** Where the command is installed, so that an update is told the way it takes effect; nothing when unknown. */
+  readonly install?: Install | undefined;
+  /** What the command last said of the versions; left out, it says it every time. */
+  readonly notices?: NoticeStore | undefined;
   /** Where the console's own skills are on this machine, shipped with the package; nothing when they are not there. */
   readonly skillsDir?: string | undefined;
   /** How `serve` listens on the loopback (ADR-0014); left out, the command cannot serve. */
@@ -197,7 +214,7 @@ async function open(io: CliIo, values: Values): Promise<Session> {
       "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 {
@@ -502,7 +519,7 @@ type Command = (args: readonly string[], io: CliIo) => Promise<number>;
 
 /** Checks a token against the console, keeps it with the address, and says who it is. */
 async function keep(io: CliIo, url: string, token: string, agent?: string): Promise<number> {
-  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(
@@ -537,7 +554,7 @@ const login: Command = 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({
@@ -579,7 +596,7 @@ const logout: Command = 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")) {
       gone = false;
@@ -617,12 +634,38 @@ const whoami: Command = async (args, io) => {
     throw failed("The console does not know this token. Sign in again: console login");
   }
   const key = await session.projectKey();
+  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, project: key ?? null },
+    {
+      ...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}`}`,
+      [
+        `${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;
 };
@@ -952,12 +995,94 @@ const task: Command = 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: Command = 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: Uint8Array;
+    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: Command = 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: string;
+  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;
 };
@@ -975,10 +1100,11 @@ const take: Command = 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 =
@@ -989,16 +1115,16 @@ const take: Command = 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;
@@ -1331,13 +1457,24 @@ const restore: Command = async (args, io) => {
 };
 
 const goals: Command = 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;
@@ -1345,15 +1482,24 @@ const goals: Command = async (args, io) => {
 
 const GOAL_FIELDS: OptionSpec = {
   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: string | undefined, clearable = false): string | null | undefined {
+  return clearable && value === "none" ? null : value;
+}
+
 const newGoal: Command = 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);
@@ -1362,6 +1508,8 @@ const newGoal: Command = 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}`);
@@ -1373,17 +1521,21 @@ const editGoal: Command = 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.",
+      "Say what to change: --title, --body, --state, --category, --starts or --due; none clears a category or a day.",
     );
   }
   const session = await open(io, values);
@@ -1904,6 +2056,8 @@ const COMMANDS: Readonly<Record<string, Command>> = {
   take,
   report,
   "hand-in": handIn,
+  comment,
+  file,
   ask,
   decision,
   decisions,
@@ -1933,9 +2087,82 @@ function help(io: CliIo, name: string | undefined): number {
   return EXIT.ok;
 }
 
+/** A client of the console at `url`, naming the command on every request (ADR-0025). */
+function clientOf(io: CliIo, url: string, token?: string): ConsoleClient {
+  return createClient({
+    baseUrl: url,
+    fetch: io.fetch,
+    ...(token === undefined ? {} : { token }),
+    ...(io.userAgent === undefined ? {} : { userAgent: io.userAgent }),
+  });
+}
+
+/** What the console said of itself on its last answer (ADR-0025): its version, and the range of command versions it takes. */
+interface ConsoleSeen {
+  version?: string | undefined;
+  range?: string | undefined;
+}
+
+/** The command that puts the console's version where this command is installed. */
+function updateWords(io: CliIo, version: string | undefined): string {
+  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: CliIo, seen: ConsoleSeen): Promise<void> {
+  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: ApiError): string {
+function hintFor(error: ApiError, io: CliIo, seen: ConsoleSeen): string {
   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":
@@ -1954,6 +2181,10 @@ function hintFor(error: ApiError): string {
       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":
@@ -1994,9 +2225,23 @@ function hintFor(error: ApiError): string {
 /** Runs the command and answers with its exit code. What it prints goes through `io`. */
 export async function runCli(argv: readonly string[], io: CliIo): Promise<number> {
   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: ConsoleSeen = {};
+  const watched: CliIo = {
+    ...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") {
@@ -2009,15 +2254,21 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<number
     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) {
       io.stderr(`${error.message}\n`);
       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;
   }

package/src/cli/format.ts

@@ -1,6 +1,7 @@
 import type {
   RestArtifact,
   RestCategory,
+  RestComment,
   RestDecision,
   RestDocument,
   RestDocumentSummary,
@@ -131,6 +132,7 @@ export function formatTask(
   task: RestTask,
   decisions?: readonly RestDecision[],
   runs?: readonly RestRun[],
+  comments?: readonly RestComment[],
 ): string {
   const lines = [
     `#${task.number} ${task.title}`,
@@ -159,6 +161,31 @@ export function formatTask(
       lines.push(`  ${formatRunLine(run)}`);
     }
   }
+  if (comments !== undefined) {
+    lines.push("", comments.length === 0 ? "comments: none" : "comments:");
+    for (const comment of comments) {
+      lines.push(formatComment(comment));
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * One comment of the discussion, indented under the list: who said it, through which agent,
+ * when, the whole word, and each file put in it with the command that reads it.
+ */
+export function formatComment(comment: RestComment): string {
+  const who =
+    comment.agent === null ? comment.author.login : `${comment.author.login} as ${comment.agent}`;
+  const lines = [`  ${who}, ${comment.createdAt}, comment ${comment.id}:`];
+  if (comment.body.trim().length > 0) {
+    lines.push(indent(comment.body));
+  }
+  for (const attached of comment.files) {
+    lines.push(
+      `    file: ${attached.file.name} (${attached.file.size} bytes, ${attached.file.contentType}): console file ${attached.id}`,
+    );
+  }
   return lines.join("\n");
 }
 
@@ -205,7 +232,7 @@ export function formatArtifact(
   const what =
     artifact.file === null
       ? (artifact.url ?? "")
-      : `${artifact.file.name} (${artifact.file.size} bytes, ${artifact.file.contentType}${fileUrl === undefined ? "" : `; read at ${fileUrl(artifact.id)}`})`;
+      : `${artifact.file.name} (${artifact.file.size} bytes, ${artifact.file.contentType}${fileUrl === undefined ? "" : `; read at ${fileUrl(artifact.id)}`}; console file ${artifact.id})`;
   return artifact.label === null ? what : `${artifact.label}: ${what}`;
 }
 
@@ -287,9 +314,14 @@ function progressOf(goal: RestGoal): string {
   return `${counts.done}/${total} done${working === 0 ? "" : `, ${working} in progress`}${counts.dropped === 0 ? "" : `, ${counts.dropped} dropped`}`;
 }
 
-/** One goal: its id, its state, its title, when it is due, and how far it is. */
+/** One goal: its id, its state, its title, its category, its days, and how far it is. */
 export function formatGoalLine(goal: RestGoal): string {
-  const notes = [goal.dueOn === null ? "no target day" : `due ${goal.dueOn}`, progressOf(goal)];
+  const notes = [
+    ...(goal.category === null ? [] : [goal.category.key]),
+    ...(goal.startsOn === null ? [] : [`starts ${goal.startsOn}`]),
+    goal.dueOn === null ? "no target day" : `due ${goal.dueOn}`,
+    progressOf(goal),
+  ];
   return `${goal.id}  ${goal.state}  ${goal.title}  (${notes.join("; ")})`;
 }
 
@@ -297,7 +329,7 @@ export function formatGoalLine(goal: RestGoal): string {
 export function formatGoal(goal: RestGoal, tasks?: readonly RestTask[]): string {
   const lines = [
     `goal ${goal.id}: ${goal.title}`,
-    `state: ${goal.state}  due: ${goal.dueOn ?? "none"}  set by: ${goal.createdBy.login}`,
+    `state: ${goal.state}  category: ${goal.category?.key ?? "none"}  starts: ${goal.startsOn ?? "none"}  due: ${goal.dueOn ?? "none"}  set by: ${goal.createdBy.login}`,
     `progress: ${progressOf(goal)}`,
   ];
   if (goal.body.trim().length > 0) {

package/src/cli/help.ts

@@ -6,9 +6,11 @@ import {
   MAX_CATEGORIES,
   MAX_CATEGORY_KEY_LENGTH,
   MAX_CATEGORY_NAME_LENGTH,
+  MAX_COMMENTS_PER_TASK,
   MAX_DOCUMENT_LENGTH,
   MAX_DOCUMENT_PATH_LENGTH,
   MAX_FILE_BYTES,
+  MAX_FILES_PER_COMMENT,
   MAX_FILES_PER_DOCUMENT,
   MAX_LINK_LABEL_LENGTH,
   MAX_OPTION_LABEL_LENGTH,
@@ -124,7 +126,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   task: {
     usage: `task <number|id>  |  task new <title> [--body <markdown>|--file <path>] ${TASK_FIELD_FLAGS}  |  task edit <number|id> [--title <title>] [--body <markdown>|--file <path>] ${TASK_FIELD_FLAGS}`,
     about:
-      "One task in full, with its plan (category, goal, start and due days), what happened to it (when it was started and done, which the board keeps itself), the decisions about it and the runs on it; or a new task written down; or a task changed, only in what the flags say, where none clears a field (priorities: low, normal, high, urgent).",
+      "One task in full, with its plan (category, goal, start and due days), what happened to it (when it was started and done, which the board keeps itself), the decisions about it, the runs on it and the discussion on it, each comment whole with its files; or a new task written down; or a task changed, only in what the flags say, where none clears a field (priorities: low, normal, high, urgent).",
     limits: [
       `title: one line, up to ${MAX_TITLE_LENGTH} characters, saying what is to be done on its own; what it refers to goes in the body`,
       `body: ${MARKDOWN}`,
@@ -133,22 +135,24 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     refusals: ["task.not_found: no task has that number or id", ...TASK_FIELD_REFUSALS],
   },
   goals: {
-    usage: "goals",
+    usage: "goals [--category <key>] [--state <state>]",
     about:
-      "The roadmap of the project: its goals, the active first, each with its id, its state (planned, active, done, dropped), its target day, and how far it is, counted from the tasks that work towards it.",
+      "The roadmap of the project: its goals, the active first, each with its id, its state (planned, active, done, dropped), its category, the days it starts and is meant to be reached by, and how far it is, counted from the tasks that work towards it. --category keeps those sorted into one, --state those in one state.",
   },
   goal: {
     usage:
-      'goal <id>  |  goal new "<title>" [--body <markdown>|--file <path>] [--state <state>] [--due <day>]  |  goal edit <id> [--title <title>] [--body <markdown>|--file <path>] [--state <state>] [--due <day|none>]',
+      'goal <id>  |  goal new "<title>" [--body <markdown>|--file <path>] [--state <state>] [--category <key>] [--starts <day>] [--due <day>]  |  goal edit <id> [--title <title>] [--body <markdown>|--file <path>] [--state <state>] [--category <key|none>] [--starts <day|none>] [--due <day|none>]',
     about:
-      "One goal in full, with the tasks that work towards it; or a goal set on the roadmap, for an owner of the project; or one changed, only in what the flags say. A task works towards a goal through its --goal.",
+      "One goal in full, with the tasks that work towards it; or a goal set on the roadmap, for an owner of the project; or one changed, only in what the flags say, where none clears a category or a day. A goal is planned in days as a task is, a start and a target, and sorted into a category of the workspace (console categories). A task works towards a goal through its --goal.",
     limits: [
       `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
       `body: ${MARKDOWN}`,
-      `due: ${DAY}`,
+      `starts, due: ${DAY}`,
     ],
     refusals: [
       "goal.not_found: no goal of this project has that id",
+      "goal.invalid_category: no category of the workspace has that key",
+      "goal.invalid_dates: the target day is before the start",
       "auth.forbidden: only an owner of the project sets its roadmap",
     ],
   },
@@ -336,6 +340,30 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     about: "One run in full: its reports, what it handed in, what it waits for, how it ended.",
     refusals: ["run.not_found: no run has that id"],
   },
+  comment: {
+    usage:
+      'comment <number|id> "<markdown>" [--attach <path>]...  |  comment <number|id> --file <path>  |  comment <number|id> -',
+    about:
+      "Says something in the discussion on a task, for its people: an answer to what they asked there, a question that is not a decision, a remark; with files from this machine put in it, which the console keeps and shows on the task, pictures in place. Needs no run. A report is the run's record; a comment is a word to people. Never rewritten: a mistake is corrected in the next one.",
+    limits: [
+      `the comment: ${MARKDOWN}; blank only when a file comes with it`,
+      `a file: up to ${MAX_FILE_BYTES} bytes, not empty; called by its name, without the path; a picture is placed in the text as ![words](its name)`,
+      `at most ${MAX_FILES_PER_COMMENT} files on one comment, together up to ${MAX_FILE_BYTES} bytes`,
+      `at most ${MAX_COMMENTS_PER_TASK} comments on one task`,
+    ],
+    refusals: [
+      "task.not_found: no task has that number or id",
+      "comment.too_many: the task carries as many comments as one may",
+      "comment.too_many_files: more files than one comment may carry",
+      "request.too_large: the files are over the limit together",
+    ],
+  },
+  file: {
+    usage: "file <id> [--out <path>]",
+    about:
+      "Reads a file of the project from the console and writes it on this machine: one a run handed in, one put in a comment, or one attached to a page, by the id the task, the run or the page shows. Written under its own name in the working directory, at --out <path>, or into --out <directory>. Then look at it with your own tools.",
+    refusals: ["file.not_found: no file of this project has that id"],
+  },
   docs: {
     usage: "docs [<folder>] [--search <words>] [--archived]",
     about:
@@ -447,7 +475,10 @@ const SECTIONS: readonly { readonly title: string; readonly commands: readonly s
       "rules",
     ],
   },
-  { title: "Working", commands: ["take", "report", "hand-in", "ask", "finish", "fail", "abandon"] },
+  {
+    title: "Working",
+    commands: ["take", "report", "hand-in", "comment", "file", "ask", "finish", "fail", "abandon"],
+  },
   {
     title: "The documents: the project's pages of Markdown, in folders, by path",
     commands: ["docs", "doc", "write", "attach", "archive", "restore"],