@skillcdn/console 0.1.15 → 0.1.17

package/src/cli/cli.ts

@@ -41,6 +41,7 @@ import type { DirectoryStore } from "./directory.js";
 import {
   formatAnswer,
   formatCategoryLine,
+  formatComment,
   formatDecision,
   formatDecisionLine,
   formatDocument,
@@ -107,6 +108,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;
@@ -952,12 +955,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;
 };
@@ -974,22 +1059,32 @@ const take: Command = async (args, io) => {
     ...(agent === undefined ? {} : { agent }),
   });
   // The rules come with the run, as they read for the person: everything from here acts
-  // within them (ADR-0023).
-  const [ruling, me] = await Promise.all([project.rules(), session.client.me()]);
+  // within them (ADR-0023); the task is read again, as it stands now that it is taken.
+  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
+      ? " A run that was open on it is over now: the board cannot know whether its agent still ran, so taking it was deciding."
+      : "";
   const rules = {
     workspace: forPerson(ruling.workspace, me.language),
     project: forPerson(ruling.project, me.language),
   };
-  answer(io, session, { run, task: found, 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. A run that was open on it is over now: the board cannot know whether its agent still ran, so taking it was deciding.`,
+      `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(found),
+      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;
@@ -1895,6 +1990,8 @@ const COMMANDS: Readonly<Record<string, Command>> = {
   take,
   report,
   "hand-in": handIn,
+  comment,
+  file,
   ask,
   decision,
   decisions,

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}`;
 }
 

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,9 +126,9 @@ 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`,
+      `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}`,
       ...TASK_FIELD_LIMITS,
     ],
@@ -336,6 +338,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 +473,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"],

package/src/cli/main.ts

@@ -9,7 +9,7 @@ import { runCli } from "./cli.js";
 import { createFileStore, defaultConfigDir } from "./credentials.js";
 import { createDirectoryStore } from "./directory.js";
 import { listenOn } from "./serve.js";
-import { readBytesAt, readFileAt, readStdin } from "./terminal.js";
+import { readBytesAt, readFileAt, readStdin, writeBytesAt } from "./terminal.js";
 
 // The `console` command: the only place the command reads the process. Everything it does is in
 // cli.ts, which takes what it needs and is what the tests run.
@@ -34,6 +34,7 @@ process.exitCode = await runCli(process.argv.slice(2), {
   hostname: hostname(),
   readFile: readFileAt,
   readBytes: readBytesAt,
+  writeBytes: writeBytesAt,
   store: createFileStore(defaultConfigDir(process.env)),
   directory: createDirectoryStore(process.cwd()),
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),

package/src/cli/terminal.ts

@@ -1,4 +1,5 @@
-import { readFile } from "node:fs/promises";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import process from "node:process";
 
 // The terminal's side of the command: what is read from it. Nothing here is reached by tests,
@@ -26,3 +27,13 @@ export function readFileAt(path: string): Promise<string> {
 export function readBytesAt(path: string): Promise<Uint8Array> {
   return readFile(path);
 }
+
+/**
+ * A file read from the console, written at the path, or into it under the file's name when
+ * the path is a directory; says where it went, in full.
+ */
+export async function writeBytesAt(path: string, bytes: Uint8Array, name: string): Promise<string> {
+  const target = (await stat(path).catch(() => undefined))?.isDirectory() ? join(path, name) : path;
+  await writeFile(target, bytes);
+  return resolve(target);
+}

package/src/client.ts

@@ -18,6 +18,8 @@ import {
   type RestCategoryInput,
   type RestCategoryPatch,
   type RestClaim,
+  type RestComment,
+  type RestComments,
   type RestConnectInput,
   type RestConnection,
   type RestConnectRequest,
@@ -71,6 +73,8 @@ import {
   restCategoriesSchema,
   restCategorySchema,
   restClaimSchema,
+  restCommentSchema,
+  restCommentsSchema,
   restConnectionSchema,
   restConnectRequestSchema,
   restDecisionSchema,
@@ -123,6 +127,22 @@ export interface FileUpload {
   readonly label?: string | undefined;
 }
 
+/** A comment to write on a task: the word, and the files put in it, which go in the one request. */
+export interface CommentInput {
+  /** Markdown; may be blank when a file comes with it. */
+  readonly body: string;
+  readonly files?: readonly FileUpload[] | undefined;
+}
+
+/** The bytes of a file of the project, as the console hands them back, with what it calls them. */
+export interface FileRead {
+  /** The file's name, as the console says it; the id when it says none. */
+  readonly name: string;
+  /** The media type the console answered with, without its parameters. */
+  readonly contentType: string;
+  readonly bytes: Uint8Array;
+}
+
 export interface ClientOptions {
   /** The origin of the console, without a path. Empty: the origin of the page. */
   readonly baseUrl?: string;
@@ -245,8 +265,14 @@ export interface ProjectClient {
   handIn(runId: string, input: RestArtifactInput): Promise<RestRun>;
   /** Hands in a file, on a run of the asker's: the console keeps the bytes. */
   handInFile(runId: string, input: FileUpload): Promise<RestRun>;
-  /** Where the bytes of a file handed in are read, by the artifact's id. */
-  fileUrl(artifactId: string): string;
+  /** Where the bytes of a file of the project are read, by its id: handed in by a run, put in a comment, or attached to a page. */
+  fileUrl(fileId: string): string;
+  /** The bytes of a file of the project, by its id, with the name and the type the console says. */
+  readFile(fileId: string, signal?: AbortSignal): Promise<FileRead>;
+  /** The discussion on a task: its comments, oldest first, whole. */
+  comments(taskId: string, signal?: AbortSignal): Promise<RestComments>;
+  /** Writes a comment on a task, with its files when given, in one request. */
+  comment(taskId: string, input: CommentInput): Promise<RestComment>;
   /** Ends a run: finished or failed by the agent; abandoned by the person it is for, or an administrator. */
   endRun(runId: string, input: RestRunEndInput): Promise<RestRun>;
   /** What happened in the project after event number `after`; `0` for the beginning. Narrowed by `filter`. */
@@ -419,6 +445,37 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
     return parsed.data;
   };
 
+  /** The bytes at `url`, with the name and the type the console says, for a file of the project. */
+  const read = async (
+    url: string,
+    fallbackName: string,
+    signal?: AbortSignal,
+  ): Promise<FileRead> => {
+    let response: Response;
+    try {
+      response = await send(url, {
+        method: "GET",
+        ...(signal === undefined ? {} : { signal }),
+        credentials: token === undefined ? "same-origin" : "omit",
+        headers: token === undefined ? {} : { authorization: `Bearer ${token}` },
+      });
+    } catch (error) {
+      if (signal?.aborted === true) {
+        throw error;
+      }
+      throw new ApiError(0, "network", "The server could not be reached.");
+    }
+    if (!response.ok) {
+      throw await failure(response);
+    }
+    const type = response.headers.get("content-type") ?? "application/octet-stream";
+    return {
+      name: fileNameOf(response.headers.get("content-disposition") ?? "") ?? fallbackName,
+      contentType: type.split(";")[0]?.trim() ?? "application/octet-stream",
+      bytes: new Uint8Array(await response.arrayBuffer()),
+    };
+  };
+
   const flag = (value: boolean | undefined): string | undefined =>
     value === undefined ? undefined : String(value);
   const number = (value: number | undefined): string | undefined =>
@@ -440,6 +497,22 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
     return form;
   };
 
+  /** A comment with files as the parts of a form: the part `body`, and a part `file` for each file. */
+  const commentFormOf = (input: CommentInput): FormData => {
+    const form = new FormData();
+    form.set("body", input.body);
+    for (const file of input.files ?? []) {
+      const bytes =
+        file.bytes instanceof Blob ? file.bytes : new Blob([Uint8Array.from(file.bytes)]);
+      form.append(
+        "file",
+        new File([bytes], file.name, { type: file.contentType ?? "application/octet-stream" }),
+        file.name,
+      );
+    }
+    return form;
+  };
+
   const projectClient = (key: string): ProjectClient => {
     const at = (collection?: Parameters<typeof projectPath>[1], id?: string) =>
       projectPath(key, collection, id);
@@ -530,7 +603,23 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
         request("POST", `${base}${at("runs", runId)}/artifacts`, input, restRunSchema),
       handInFile: (runId, input) =>
         request("POST", `${base}${at("runs", runId)}/files`, formOf(input), restRunSchema),
-      fileUrl: (artifactId) => `${base}${at("files", artifactId)}`,
+      fileUrl: (fileId) => `${base}${at("files", fileId)}`,
+      readFile: (fileId, signal) => read(`${base}${at("files", fileId)}`, fileId, signal),
+      comments: (taskId, signal) =>
+        request(
+          "GET",
+          `${base}${at("tasks", taskId)}/comments`,
+          undefined,
+          restCommentsSchema,
+          signal,
+        ),
+      comment: (taskId, input) =>
+        request(
+          "POST",
+          `${base}${at("tasks", taskId)}/comments`,
+          (input.files?.length ?? 0) > 0 ? commentFormOf(input) : { body: input.body },
+          restCommentSchema,
+        ),
       endRun: (runId, input) =>
         request("POST", `${base}${at("runs", runId)}/end`, input, restRunSchema),
       events: (after, filter = {}, signal) =>
@@ -668,3 +757,23 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
     signOut: () => request("POST", `${base}${AUTH_ROUTES.logout}`, undefined, undefined),
   };
 }
+
+/**
+ * The file's name as a `content-disposition` header says it: the exact one (`filename*`, UTF-8,
+ * percent-encoded) when it is readable, else the plain one in quotes; nothing when neither is.
+ */
+export function fileNameOf(disposition: string): string | undefined {
+  const exact = /filename\*=UTF-8''([^;]+)/i.exec(disposition);
+  if (exact?.[1] !== undefined) {
+    try {
+      const decoded = decodeURIComponent(exact[1].trim());
+      if (decoded.length > 0) {
+        return decoded;
+      }
+    } catch {
+      // Not percent-encoded as it should be: the plain name below is what there is.
+    }
+  }
+  const plain = /filename="([^"]*)"/i.exec(disposition);
+  return plain?.[1] === undefined || plain[1].length === 0 ? undefined : plain[1];
+}