@skillcdn/console 0.1.23 → 0.3.0

package/src/cli/cli.ts

@@ -20,7 +20,7 @@ import {
   type RestSkillBrowse,
   type RestSkillFile,
   type RestSkillLoad,
-  type RestSkillPage,
+  type RestSkills,
   type RestTaskPatch,
 } from "../schemas.js";
 import {
@@ -75,20 +75,31 @@ import {
   formatRules,
   formatRun,
   formatRunLine,
-  formatSkillBrowse,
-  formatSkillFile,
-  formatSkillFind,
-  formatSkillLoad,
-  formatSkills,
   formatTask,
   formatTaskLine,
   formatVersion,
   formatVersionLine,
   formatWork,
 } from "./format.js";
-import { COMMAND_HELP, helpFor, usage } from "./help.js";
+import { COMMAND_HELP, helpFor, ownSkillPath, usage } from "./help.js";
 import { describeInstall, type Install, updateCommandFor } from "./install.js";
 import type { NoticeStore } from "./notices.js";
+import {
+  bodyOfFile,
+  bodyOfFolder,
+  bodyOfSkill,
+  formatSkillBrowse,
+  formatSkillFile,
+  formatSkillFind,
+  formatSkillLoad,
+  formatSkills,
+  joinFile,
+  joinFolder,
+  joinSkill,
+  type PackSummary,
+  skillPathIn,
+  summaryOf,
+} from "./pack.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
@@ -339,11 +350,11 @@ async function currentRun(project: ProjectClient, values: Values): Promise<strin
   }
   if (items.length === 0) {
     throw failed(
-      "No run of yours is open in this project. Take a task first: console take <number>",
+      "run.none: no run of yours is open in this project. Take a task first: console take <number>; or name a run: --run <id>",
     );
   }
   throw failed(
-    `Several runs of yours are open; say which with --run <id>:\n${items.map((run) => `  ${formatRunLine(run)}`).join("\n")}`,
+    `run.ambiguous: several runs of yours are open in this project; say which with --run <id>:\n${items.map((run) => `  ${formatRunLine(run)}`).join("\n")}`,
   );
 }
 
@@ -851,14 +862,14 @@ const whoami: Command = async (args, io) => {
         ...(key === undefined
           ? []
           : [
-              "What this organization asks of agents: console rules. How the board is worked: the skill working-the-board, shipped with this command (console skills says where it is).",
+              `What this organization asks of agents: console rules. How the board is worked: the skill working-the-board, shipped with this command${io.skillsDir === undefined ? " (console skills says where it is)." : `: ${ownSkillPath(io.skillsDir)}`}`,
             ]),
         `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)}`,
+                `This command is newer than the console: it works, and what the console has not got yet is refused as not found; nothing to do until then. To match the console then: ${updateWords(io, me.console?.version)}`,
               ]
             : []),
       ].join("\n"),
@@ -1003,10 +1014,19 @@ const MAX_SKILL_PAGES = 64;
 /** How many results a search answers at most: what the deployment allows on one page. */
 const MAX_FIND_LIMIT = 25;
 
+/** The pack of the project as the console lists it, and what its reads are rendered at; none when the pack did not answer. */
+async function packOf(
+  project: ProjectClient,
+): Promise<{ readonly listing: RestSkills; readonly summary: PackSummary | undefined }> {
+  const listing = await project.skills();
+  return { listing, summary: summaryOf(listing) };
+}
+
 const skills: Command = async (args, io) => {
   const { values, positionals } = parse(args, {
     search: { type: "string" },
     limit: { type: "string" },
+    cursor: { type: "string" },
   });
   if (positionals.length > 1) {
     throw misuse("Say one folder: console skills [<folder>] [--search <words>]");
@@ -1016,8 +1036,11 @@ const skills: Command = async (args, io) => {
   const folder = given === undefined || given === "/" || given === "." ? undefined : given;
   const words = text(values, "search");
   const limit = text(values, "limit");
-  if (words === undefined && limit !== undefined) {
-    throw misuse("--limit goes with --search: console skills --search <words> [--limit <n>]");
+  const cursor = text(values, "cursor");
+  if (words === undefined && (limit !== undefined || cursor !== undefined)) {
+    throw misuse(
+      "--limit and --cursor go with --search: console skills --search <words> [--limit <n>] [--cursor <cursor>]",
+    );
   }
   const atMost = limit === undefined ? undefined : Number(limit);
   if (
@@ -1028,37 +1051,41 @@ const skills: Command = async (args, io) => {
   }
   const session = await open(io, values);
   const project = await session.project();
+  const { listing, summary } = await packOf(project);
+  // The pack as it stands; or why it does not answer, which a folder or a search would meet too.
+  if (summary === undefined || (words === undefined && given === undefined)) {
+    answer(io, session, listing, () => formatSkills(listing, io.skillsDir));
+    return EXIT.ok;
+  }
   if (words !== undefined) {
-    // One page of what the words find; more is said, and narrowed by the agent, not fetched.
-    const found = await project.skillFind(words, { path: folder, limit: atMost });
-    answer(io, session, found, () => formatSkillFind(found));
+    // One page of what the words find; more is said, and asked for with --cursor.
+    const found = await project.skillFind(words, { path: folder, limit: atMost, cursor });
+    answer(io, session, found, () => formatSkillFind(found, summary));
     return EXIT.ok;
   }
-  if (given !== undefined) {
-    // The folder whole: its pages until the end, as the deployment lists them.
-    const folders: NonNullable<RestSkillBrowse["folder"]>[] = [];
-    let cursor: string | undefined;
-    let last: RestSkillBrowse | undefined;
-    for (let n = 0; n < MAX_SKILL_PAGES; n += 1) {
-      last = await project.skillBrowse({ path: folder, cursor });
-      if (last.status !== "ready" || last.folder === null) {
-        break;
-      }
-      folders.push(last.folder);
-      if (last.folder.nextCursor === null) {
-        break;
-      }
-      cursor = last.folder.nextCursor;
+  // The folder whole: its pages until the end, as the pack lists them.
+  const pages: RestSkillBrowse[] = [];
+  let next: string | undefined;
+  let last: RestSkillBrowse | undefined;
+  for (let n = 0; n < MAX_SKILL_PAGES; n += 1) {
+    last = await project.skillBrowse({ path: folder, cursor: next });
+    if (last.read?.status !== "ready") {
+      break;
     }
-    if (last === undefined) {
-      throw failed("The folder could not be read.");
+    pages.push(last);
+    next = last.read.nextCursor ?? undefined;
+    if (next === undefined) {
+      break;
     }
-    const browsed = last;
-    answer(io, session, { ...browsed, folders }, () => formatSkillBrowse(browsed, folders));
-    return EXIT.ok;
   }
-  const found = await project.skills();
-  answer(io, session, found, () => formatSkills(found, io.skillsDir));
+  if (last === undefined) {
+    throw failed("The folder could not be read.");
+  }
+  const browsed = last;
+  const whole = joinFolder(pages, summary);
+  answer(io, session, { ...browsed, read: whole === undefined ? null : bodyOfFolder(whole) }, () =>
+    formatSkillBrowse(browsed, whole),
+  );
   return EXIT.ok;
 };
 
@@ -1074,54 +1101,70 @@ const skill: Command = async (args, io) => {
   }
   const session = await open(io, values);
   const project = await session.project();
+  const { listing, summary } = await packOf(project);
+  if (summary === undefined) {
+    answer(io, session, listing, () => formatSkills(listing, io.skillsDir));
+    return EXIT.ok;
+  }
   if (file !== undefined) {
-    // The file whole, page after page, as the console reads it from the deployment.
-    const parts: string[] = [];
+    // The file whole, page after page, as the console reads it from the pack.
+    const pages: RestSkillFile[] = [];
     let offset: number | undefined;
     let last: RestSkillFile | undefined;
-    for (let pages = 0; pages < MAX_SKILL_PAGES; pages += 1) {
+    for (let n = 0; n < MAX_SKILL_PAGES; n += 1) {
       last = await project.skillFile(file, offset === undefined ? {} : { offset });
-      if (last.status !== "ready" || last.file === null) {
+      if (last.read === null) {
         break;
       }
-      parts.push(last.file.content);
-      if (last.file.nextOffset === null) {
+      pages.push(last);
+      if (last.read.kind !== "file" || last.read.nextOffset === null) {
         break;
       }
-      offset = last.file.nextOffset;
+      offset = last.read.nextOffset;
     }
     if (last === undefined) {
       throw failed("The file could not be read.");
     }
-    const read = last;
-    const content = parts.join("");
-    answer(io, session, { ...read, content }, () => formatSkillFile(read, content));
+    const fileRead = last;
+    const whole = joinFile(pages, summary);
+    answer(io, session, { ...fileRead, read: whole === undefined ? null : bodyOfFile(whole) }, () =>
+      formatSkillFile(fileRead, whole),
+    );
     return EXIT.ok;
   }
-  const path = theOne(
-    positionals,
-    "Say which skill: console skill <path of its SKILL.md>, or console skill --file <path> for a file of the pack",
+  const wanted = skillPathIn(
+    theOne(
+      positionals,
+      "Say which skill: console skill <path of its SKILL.md>, or console skill --file <path> for a file of the pack",
+    ),
+    listing.address,
   );
+  if ("error" in wanted) {
+    throw misuse(wanted.error);
+  }
   // The skill whole: its pages until complete, the rules first, as load_skill lays them out.
-  const pages: RestSkillPage[] = [];
+  const pages: RestSkillLoad[] = [];
   let cursor: string | undefined;
   let last: RestSkillLoad | undefined;
   for (let n = 0; n < MAX_SKILL_PAGES; n += 1) {
-    last = await project.skill(path, cursor);
-    if (last.status !== "ready" || last.skill === null) {
+    last = await project.skill(wanted.path, cursor);
+    if (last.read?.status !== "ready") {
       break;
     }
-    pages.push(last.skill);
-    if (last.skill.complete || last.skill.nextCursor === null) {
+    pages.push(last);
+    cursor = last.read.skill.nextCursor ?? undefined;
+    if (last.read.skill.complete === true || cursor === undefined) {
       break;
     }
-    cursor = last.skill.nextCursor;
   }
   if (last === undefined) {
     throw failed("The skill could not be read.");
   }
   const loaded = last;
-  answer(io, session, { ...loaded, pages }, () => formatSkillLoad(loaded, pages));
+  const whole = joinSkill(pages, summary);
+  answer(io, session, { ...loaded, read: whole === undefined ? null : bodyOfSkill(whole) }, () =>
+    formatSkillLoad(loaded, whole),
+  );
   return EXIT.ok;
 };
 
@@ -1487,24 +1530,32 @@ 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, comments] = await Promise.all([
+  const [ruling, me, taken, comments, openRuns] = await Promise.all([
     project.rules(),
     session.client.me(),
     project.task(ref),
     project.comments(found.id),
+    project.runs({ open: true, mine: true }),
   ]);
   // 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."
       : "";
+  // Another run of this token open in the project makes every command on a run ask which
+  // (currentRun): said here, with the id to say, before the first report runs into it.
+  const others = openRuns.items.filter((item) => item.id !== run.id);
+  const elsewhere =
+    others.length === 0
+      ? ""
+      : `\nOther runs of yours are open in this project (${others.map((item) => `#${item.taskNumber}`).join(", ")}): say which run on report, hand-in, ask, finish and fail, --run ${run.id} for this one.`;
   const rules = {
     workspace: forPerson(ruling.workspace, me.language),
     project: forPerson(ruling.project, me.language),
   };
   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}`,
+      `Run ${run.id} began on #${found.number} ${found.title}, as "${run.agent}" for ${run.person.login}. The task is in progress and theirs.${tookOver}${elsewhere}`,
       "",
       formatTask(taken, undefined, undefined, comments.items),
       "",
@@ -2540,7 +2591,7 @@ const COMMANDS: Readonly<Record<string, Command>> = {
 
 function help(io: CliIo, name: string | undefined): number {
   if (name === undefined) {
-    io.stdout(usage(io.version));
+    io.stdout(usage(io.version, io.skillsDir));
     return EXIT.ok;
   }
   const found = helpFor(name);
@@ -2614,7 +2665,7 @@ async function noticeVersions(io: CliIo, seen: ConsoleSeen): Promise<void> {
   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`,
+      : `This command (${io.version}) is newer than the console (${seen.version}, which takes ${seen.range ?? "an older line"}): it works, and what the console has not got yet is refused as not found; nothing to do until then. The console's operator updates it; to match the console meanwhile: ${updateWords(io, seen.version)}\n`,
   );
   await io.notices?.save({
     command: io.version,