@skillcdn/console 0.3.1 → 0.4.0

package/src/cli/cli.ts

@@ -7,8 +7,18 @@ 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 {
+  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 { fillRules, RULES_PATH, RULES_TITLE } from "../rules.js";
 import {
@@ -168,6 +178,10 @@ export interface CliIo {
   readonly install?: Install | undefined;
   /** What the command last said of the versions; left out, it says it every time. */
   readonly notices?: NoticeStore | undefined;
+  /** The oldest console this command works with (ADR-0038); left out, the package's own floor. */
+  readonly consoleAtLeast?: string | undefined;
+  /** The language and region of this machine (`ko-KR`), for what follows a language where the person chose none; left out, English. */
+  readonly locale?: string | 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. */
@@ -889,11 +903,15 @@ const whoami: Command = async (args, io) => {
     command === undefined || server === undefined
       ? undefined
       : judgeClient(command, server).verdict;
+  // The oldest console this command works with (ADR-0038), as it stands within the command's line.
+  const atLeast = io.consoleAtLeast ?? CONSOLE_AT_LEAST;
+  const floor =
+    command === undefined ? atLeast : versionText(consoleRange(command, atLeast).atLeast);
   // 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}`;
+      : `the console is ${me.console.version} and takes ${me.console.clientRange}; this command works with a console from ${floor} on`;
   answer(
     io,
     session,
@@ -975,6 +993,16 @@ const use: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/**
+ * The last day of this week (ADR-0039): the week begins as the workspace says, or, left to the
+ * language, as the person's language has it, else this machine's.
+ */
+async function endOfWeek(io: CliIo, session: Session, today: string): Promise<string> {
+  const me = await session.client.me();
+  const language = me.language ?? io.locale ?? "en";
+  return weekOf(today, firstDayOfWeek(language, me.workspace.weekStart ?? "auto")).at(-1) ?? today;
+}
+
 const tasks: Command = async (args, io) => {
   const { values } = parse(
     args,
@@ -986,6 +1014,7 @@ const tasks: Command = async (args, io) => {
       category: { type: "string" },
       goal: { type: "string" },
       due: { type: "string" },
+      search: { type: "string" },
       archived: { type: "boolean" },
       ...PAGE_OPTIONS,
     },
@@ -994,7 +1023,7 @@ const tasks: Command = async (args, io) => {
   const state = stateOf(text(values, "state"));
   if (on(values, "mine") && on(values, "unassigned")) {
     throw misuse(
-      "Say one: --mine for the tasks assigned to you, or --unassigned for those assigned to nobody",
+      "Say one: --mine for the tasks you work on, or --unassigned for those nobody works on",
     );
   }
   const page = pageOf(values);
@@ -1009,19 +1038,22 @@ const tasks: Command = async (args, io) => {
       : due === "overdue"
         ? addDays(today, -1)
         : due === "week"
-          ? addDays(today, 6)
+          ? await endOfWeek(io, session, today)
           : (dayOf(io, due) ?? undefined);
-  const assignee = on(values, "mine")
-    ? ((await personIdOf(session, "me")) ?? undefined)
-    : undefined;
+  const worker = on(values, "mine") ? ((await personIdOf(session, "me")) ?? undefined) : undefined;
+  const search = text(values, "search")?.trim();
+  if (search === "") {
+    throw misuse("Say what to search for: console tasks --search <words>");
+  }
   const found = await project.tasks({
     ...(state === undefined ? {} : { state }),
     ...(on(values, "open") || due === "overdue" ? { open: true } : {}),
-    ...(assignee === undefined ? {} : { assignee }),
+    ...(worker === undefined ? {} : { worker }),
     ...(on(values, "unassigned") ? { unassigned: true } : {}),
     ...(text(values, "category") === undefined ? {} : { category: text(values, "category") }),
     ...(text(values, "goal") === undefined ? {} : { goal: text(values, "goal") }),
     ...(dueBy === undefined ? {} : { dueBy }),
+    ...(search === undefined ? {} : { q: search }),
     ...(on(values, "archived") ? { archived: true } : {}),
     ...page,
   });
@@ -1140,8 +1172,37 @@ const skills: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/** 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;
+
+/** A count given as a flag, within its bounds, or nothing; anything else is not understood. */
+function countOf(
+  given: string | undefined,
+  name: string,
+  bounds: { readonly least: number; readonly most?: number },
+): number | undefined {
+  if (given === undefined) {
+    return undefined;
+  }
+  const count = Number(given);
+  if (
+    !Number.isInteger(count) ||
+    count < bounds.least ||
+    (bounds.most !== undefined && count > bounds.most)
+  ) {
+    const range =
+      bounds.most === undefined ? `${bounds.least} or more` : `${bounds.least} to ${bounds.most}`;
+    throw misuse(`Not a number for --${name}, ${range}: ${given}`);
+  }
+  return count;
+}
+
 const skill: Command = async (args, io) => {
-  const { values, positionals } = parse(args, { file: { type: "string" } });
+  const { values, positionals } = parse(args, {
+    file: { type: "string" },
+    offset: { type: "string" },
+    limit: { type: "string" },
+  });
   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.
@@ -1150,6 +1211,17 @@ const skill: Command = async (args, io) => {
       "Say one: console skill <path of its SKILL.md> for a skill, or console skill --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>]",
+    );
+  }
+  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);
@@ -1157,6 +1229,16 @@ const skill: Command = async (args, io) => {
     answer(io, session, listing, () => formatSkills(listing, io.skillsDir));
     return EXIT.ok;
   }
+  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 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;
+  }
   if (file !== undefined) {
     // The file whole, page after page, as the console reads it from the pack.
     const pages: RestSkillFile[] = [];
@@ -1335,10 +1417,42 @@ const TASK_FIELDS: OptionSpec = {
   goal: { type: "string" },
   starts: { type: "string" },
   due: { type: "string" },
-  assignee: { type: "string" },
+  worker: { type: "string", multiple: true },
   parent: { type: "string" },
 };
 
+/**
+ * The people `--worker` names, each a login or `me`, given again or with commas between for
+ * several, in place of those there were; `none` alone for nobody; nothing when the flag was
+ * not given.
+ */
+async function workerIdsOf(
+  session: Session,
+  given: readonly string[],
+): Promise<string[] | undefined> {
+  if (given.length === 0) {
+    return undefined;
+  }
+  const names = given
+    .flatMap((value) => value.split(","))
+    .map((name) => name.trim())
+    .filter((name) => name.length > 0);
+  if (names.includes("none")) {
+    if (names.length > 1) {
+      throw misuse("Say --worker none alone, for nobody; or the logins of the workers.");
+    }
+    return [];
+  }
+  const ids: string[] = [];
+  for (const name of names) {
+    const id = await personIdOf(session, name);
+    if (typeof id === "string" && !ids.includes(id)) {
+      ids.push(id);
+    }
+  }
+  return ids;
+}
+
 /** What the flags say of a task's fields, as the API takes them; `none` clears a field. */
 async function taskFieldsOf(
   io: CliIo,
@@ -1352,7 +1466,7 @@ async function taskFieldsOf(
   const goalId = orNone(text(values, "goal"));
   const startsOn = dayOf(io, text(values, "starts"), true);
   const dueOn = dayOf(io, text(values, "due"), true);
-  const assigneeId = await personIdOf(session, text(values, "assignee"));
+  const workerIds = await workerIdsOf(session, texts(values, "worker"));
   const parent = text(values, "parent");
   const parentId =
     parent === undefined ? undefined : parent === "none" ? null : (await project.task(parent)).id;
@@ -1363,7 +1477,7 @@ async function taskFieldsOf(
     ...(goalId === undefined ? {} : { goalId }),
     ...(startsOn === undefined ? {} : { startsOn }),
     ...(dueOn === undefined ? {} : { dueOn }),
-    ...(assigneeId === undefined ? {} : { assigneeId }),
+    ...(workerIds === undefined ? {} : { workerIds }),
     ...(parentId === undefined ? {} : { parentId }),
   };
 }
@@ -1415,7 +1529,7 @@ const editTask: Command = async (args, io) => {
   };
   if (Object.keys(patch).length === 0) {
     throw misuse(
-      "Say what to change: --title, --body, --state, --priority, --category, --goal, --starts, --due, --assignee or --parent; none clears a field.",
+      "Say what to change: --title, --body, --state, --priority, --category, --goal, --starts, --due, --worker or --parent; none clears a field.",
     );
   }
   const found = await project.task(ref);
@@ -1736,11 +1850,16 @@ const ask: Command = async (args, io) => {
     file: { type: "string" },
     run: { type: "string" },
     wait: { type: "string" },
+    to: { type: "string" },
   });
   const question = theOne(
     positionals,
     'Say the question: console ask "<question>" --option "<label>" --option "<label>"',
   );
+  const to = text(values, "to");
+  if (to === "none") {
+    throw misuse("Say whom the decision is for: --to <login|me>.");
+  }
   const options = texts(values, "option");
   if (options.length < MIN_OPTIONS || options.length > MAX_OPTIONS) {
     throw misuse(`Give ${MIN_OPTIONS} to ${MAX_OPTIONS} options, one --option each.`);
@@ -1750,21 +1869,58 @@ const ask: Command = async (args, io) => {
   const session = await open(io, values);
   const project = await session.project();
   const runId = await currentRun(project, values);
+  // Whom the decision is for (ADR-0042): the person the agent works for, unless --to names another.
+  const deciderId = await personIdOf(session, to);
   const raised = await project.raiseDecision({
     question,
     options: options.map((label) => ({ label })),
     runId,
     ...(body === undefined ? {} : { body }),
+    ...(typeof deciderId === "string" ? { deciderId } : {}),
   });
   // 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 a person.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`,
+      : `Decision ${raised.id} raised on run ${runId}; the run waits for ${raised.decider.login}.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`,
   );
   return settle(io, session, project, raised, seconds, true);
 };
 
+/**
+ * Writes a person's answer on a decision, in their name through the agent (ADR-0021): the
+ * option they chose, or their own words, and a note about it, so that a choice made in chat
+ * or in passing reaches the record the run waits on.
+ */
+const answering: Command = async (args, io) => {
+  const { values, positionals } = parse(args, {
+    option: { type: "string" },
+    own: { type: "string" },
+    note: { type: "string" },
+    file: { type: "string" },
+  });
+  const id = theOne(
+    positionals,
+    'Say which decision: console answer <id> --option <n>|--own "<answer>" [--note <markdown>|--file <path>]',
+  );
+  const option = text(values, "option");
+  const own = text(values, "own");
+  if ((option === undefined) === (own === undefined)) {
+    throw misuse(
+      'Say the option chosen, --option <n>, or the person\'s own answer, --own "<words>": one of the two.',
+    );
+  }
+  const note = await bodyOf(io, values, text(values, "note"));
+  const session = await open(io, values);
+  const project = await session.project();
+  const answered = await project.answerDecision(id, {
+    ...(own === undefined ? { option } : { own }),
+    ...(note === undefined ? {} : { note }),
+  });
+  answer(io, session, answered, () => formatDecision(answered));
+  return EXIT.ok;
+};
+
 const decision: Command = async (args, io) => {
   const { values, positionals } = parse(args, {
     wait: { type: "string" },
@@ -1956,23 +2112,36 @@ const restore: Command = async (args, io) => {
 const goals: Command = async (args, io) => {
   const { values } = parse(
     args,
-    { category: { type: "string" }, state: { type: "string" } },
+    {
+      category: { type: "string" },
+      state: { type: "string" },
+      search: { type: "string" },
+      ...PAGE_OPTIONS,
+    },
     false,
   );
   const state = goalStateOf(text(values, "state"));
   const category = text(values, "category");
+  const search = text(values, "search")?.trim();
+  if (search === "") {
+    throw misuse("Say what to search for: console goals --search <words>");
+  }
+  const page = pageOf(values);
   const session = await open(io, values);
   const project = await session.project();
   const found = await project.goals({
     ...(state === undefined ? {} : { state }),
     ...(category === undefined ? {} : { category }),
+    ...(search === undefined ? {} : { q: search }),
+    ...page,
   });
   answer(io, session, found, () =>
     found.items.length === 0
-      ? state === undefined && category === undefined
+      ? state === undefined && category === undefined && search === undefined
         ? "No goals. An owner sets one: console goal new <title> --due <day>"
         : "No goal matches."
-      : found.items.map(formatGoalLine).join("\n"),
+      : found.items.map(formatGoalLine).join("\n") +
+        formatMore(found.more, page.limit, page.offset),
   );
   return EXIT.ok;
 };
@@ -2062,14 +2231,37 @@ const goal: Command = async (args, io) => {
 };
 
 const decisions: Command = async (args, io) => {
-  const { values } = parse(args, { open: { type: "boolean" }, ...PAGE_OPTIONS }, false);
+  const { values } = parse(
+    args,
+    {
+      open: { type: "boolean" },
+      mine: { type: "boolean" },
+      raised: { type: "boolean" },
+      ...PAGE_OPTIONS,
+    },
+    false,
+  );
   const page = pageOf(values);
   const session = await open(io, values);
+  const open_ = on(values, "open") ? { open: true } : {};
+  if (on(values, "mine") || on(values, "raised")) {
+    // One's own across the projects (ADR-0042), addressed to the person or raised by them for
+    // someone else: the waiting first, each with its project's key.
+    const raised = on(values, "raised");
+    const found = await session.client.myDecisions({ ...open_, raised, ...page });
+    answer(io, session, found, () =>
+      found.items.length === 0
+        ? raised
+          ? "No decisions you asked of others."
+          : "No decisions of yours."
+        : found.items
+            .map(({ project, decision }) => `${project.key}  ${formatDecisionLine(decision)}`)
+            .join("\n") + formatMore(found.more, page.limit, page.offset),
+    );
+    return EXIT.ok;
+  }
   const project = await session.project();
-  const found = await project.decisions({
-    ...(on(values, "open") ? { open: true } : {}),
-    ...page,
-  });
+  const found = await project.decisions({ ...open_, ...page });
   answer(io, session, found, () =>
     found.items.length === 0
       ? "No decisions."
@@ -2792,6 +2984,7 @@ const COMMANDS: Readonly<Record<string, Command>> = {
   comment,
   file,
   ask,
+  answer: answering,
   decision,
   decisions,
   finish: ending("finished"),
@@ -2892,11 +3085,39 @@ async function noticeVersions(io: CliIo, seen: ConsoleSeen): Promise<void> {
   });
 }
 
+/**
+ * The refusal of a console older than this command works with (ADR-0038), in a console's own
+ * form: a `426` the command reads as it reads the console's, before it acts on anything the
+ * console answered.
+ */
+function consoleRefusal(io: CliIo, seen: ConsoleSeen): Response | undefined {
+  const command = parseVersion(io.version);
+  const server = parseVersion(seen.version);
+  if (command === undefined || server === undefined) {
+    return undefined;
+  }
+  const { verdict, range } = judgeConsole(server, command, io.consoleAtLeast ?? CONSOLE_AT_LEAST);
+  if (verdict !== "outdated") {
+    return undefined;
+  }
+  return Response.json(
+    {
+      error: {
+        code: "console.outdated",
+        message: `This console, ${seen.version}, is older than this command (${io.version}) works with (${formatRange(range)}).`,
+      },
+    },
+    { status: 426 },
+  );
+}
+
 /** What a refusal of the console is followed by, when there is something to do about it. */
 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 "console.outdated":
+      return `Install the console's version: ${updateWords(io, seen.version)}; or ask the console's operator to update the console.\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":
@@ -2972,7 +3193,13 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<number
       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;
+      // A console older than this command works with is refused here (ADR-0038); `serve`
+      // carries the pages' own requests, which are not the command's to judge.
+      // A refusal of the console's own is passed on as it is.
+      return (
+        (name === "serve" || response.status === 426 ? undefined : consoleRefusal(io, seen)) ??
+        response
+      );
     },
   };
   try {
@@ -3004,7 +3231,9 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<number
     }
     if (error instanceof ApiError) {
       io.stderr(`${error.code}: ${error.message}\n${hintFor(error, io, seen)}`);
-      return error.code === "client.outdated" || error.code === "client.too_new"
+      return error.code === "client.outdated" ||
+        error.code === "client.too_new" ||
+        error.code === "console.outdated"
         ? EXIT.incompatible
         : EXIT.failed;
     }

package/src/cli/format.ts

@@ -147,10 +147,14 @@ export function formatMore(more: boolean, limit: number, offset: number): string
   return more ? `\n... more: --offset ${offset + limit}` : "";
 }
 
+/** The logins of the people at work on a task, in the order they came to it. */
+const logins = (people: readonly RestPerson[]): string =>
+  people.map((person) => person.login).join(", ");
+
 export function formatTaskLine(task: RestTask): string {
   const notes = [`owner ${task.owner.login}`];
-  if (task.assignee !== null) {
-    notes.push(`assigned to ${task.assignee.login}`);
+  if (task.workers.length > 0) {
+    notes.push(`workers ${logins(task.workers)}`);
   }
   if (task.category !== null) {
     notes.push(task.category.key);
@@ -199,7 +203,7 @@ export function formatTask(
 ): string {
   const lines = [
     `#${task.number} ${task.title}`,
-    `state: ${task.state}  priority: ${task.priority}  owner: ${task.owner.login}  assignee: ${task.assignee?.login ?? "nobody"}`,
+    `state: ${task.state}  priority: ${task.priority}  owner: ${task.owner.login}  workers: ${task.workers.length === 0 ? "nobody" : logins(task.workers)}`,
     `id: ${task.id}${task.parentId === null ? "" : `  part of: ${task.parentId}`}`,
     ...scheduleLines(task),
   ];
@@ -375,14 +379,17 @@ export function formatCategoryLine(category: RestCategory): string {
 export function formatWork(work: RestWork): string {
   const lines: string[] = [];
   if (work.tasks.length === 0) {
-    lines.push("No open task is assigned to you.");
+    lines.push("No open task is on your plate.");
   } else {
-    lines.push("tasks assigned to you:");
+    lines.push("tasks you work on:");
     for (const { project, task } of work.tasks) {
       lines.push(`  ${project.key}  ${formatTaskLine(task)}`);
     }
   }
-  lines.push("", work.decisions.length === 0 ? "decisions waiting: none" : "decisions waiting:");
+  lines.push(
+    "",
+    work.decisions.length === 0 ? "decisions waiting for you: none" : "decisions waiting for you:",
+  );
   for (const { project, decision } of work.decisions) {
     lines.push(`  ${project.key}  ${formatDecisionLine(decision)}`);
   }
@@ -392,17 +399,21 @@ export function formatWork(work: RestWork): string {
 /** Another person's plate: their open tasks, each with its project; no decisions, which wait for anyone. */
 export function formatPersonWork(person: RestPerson, work: RestPersonWork): string {
   if (work.tasks.length === 0) {
-    return `No open task is assigned to ${person.login}.`;
+    return `No open task is on ${person.login}'s plate.`;
   }
   return [
-    `tasks assigned to ${person.login}:`,
+    `tasks ${person.login} works on:`,
     ...work.tasks.map(({ project, task }) => `  ${project.key}  ${formatTaskLine(task)}`),
   ].join("\n");
 }
 
+/** Whom a decision is for, where that is not the one who asked (ADR-0042). */
+const addressed = (decision: RestDecision): string =>
+  decision.decider.id === decision.raisedBy.id ? "" : `, for ${decision.decider.login}`;
+
 export function formatDecisionLine(decision: RestDecision): string {
   const state = decision.answer === null ? "waiting" : `answered ${decision.answer.option}`;
-  return `${decision.id}  ${state}  ${decision.question}  (asked by ${asker(decision)})`;
+  return `${decision.id}  ${state}  ${decision.question}  (asked by ${asker(decision)}${addressed(decision)})`;
 }
 
 /** The options, one a line; the person's own answer, when they wrote one, is the last and says so. */
@@ -419,7 +430,7 @@ export function formatOptions(decision: RestDecision): string {
 export function formatAnswer(decision: RestDecision): string {
   const { answer } = decision;
   if (answer === null) {
-    return "waits for a person.";
+    return `waits for ${decision.decider.login}.`;
   }
   const chosen = decision.options.find((option) => option.id === answer.option);
   const lines = [
@@ -434,7 +445,7 @@ export function formatAnswer(decision: RestDecision): string {
 export function formatDecision(decision: RestDecision): string {
   const lines = [
     `decision ${decision.id}: ${decision.question}`,
-    `asked by ${asker(decision)}${decision.taskNumber === null ? "" : `, about task #${decision.taskNumber}`}`,
+    `asked by ${asker(decision)}${addressed(decision)}${decision.taskNumber === null ? "" : `, about task #${decision.taskNumber}`}`,
   ];
   if (decision.body.trim().length > 0) {
     lines.push("", decision.body.trimEnd());