@skillcdn/console 0.1.24 → 0.3.0

package/src/cli/format.ts

@@ -15,13 +15,6 @@ import type {
   RestProjectRules,
   RestRules,
   RestRun,
-  RestSkillBrowse,
-  RestSkillBrowseEntry,
-  RestSkillFile,
-  RestSkillFind,
-  RestSkillLoad,
-  RestSkillPage,
-  RestSkills,
   RestTask,
   RestVersion,
   RestVersionSummary,
@@ -247,70 +240,6 @@ export function formatArtifact(
   return artifact.label === null ? what : `${artifact.label}: ${what}`;
 }
 
-const SKILLS_WORDS: Readonly<Record<Exclude<RestSkills["status"], "none" | "ready">, string>> = {
-  indexing: "SkillCDN is still indexing the repository; ask again in a moment.",
-  failed: "SkillCDN could not index the repository.",
-  not_found:
-    "SkillCDN does not serve this address to the console: nothing is there, or the pack is private and the project holds no pack token for it (console project pack-token <key> --stdin, for an owner).",
-  token_invalid:
-    "The pack token the project holds no longer works at SkillCDN: an owner sets a new one (console project pack-token <key> --stdin).",
-  unavailable: "SkillCDN could not be reached; ask again later.",
-};
-
-/** A count with its noun: `1 skill`, `2 skills`. */
-const counted = (n: number, noun: string): string => `${n} ${noun}${n === 1 ? "" : "s"}`;
-
-/**
- * The organization's skills: where they are, the pack by name and by count, each skill with
- * what an agent loads it by, where a person connects an agent that has no connection to the
- * address, and where the console's own skills are on this machine, when the command knows.
- */
-export function formatSkills(skills: RestSkills, ownSkills?: string): string {
-  const own =
-    ownSkills === undefined
-      ? []
-      : ["", `The console's own skills, for working the board: ${ownSkills}`];
-  if (skills.status === "none" || skills.address === null || skills.page === null) {
-    return ["No skills address: neither this project nor the console names one.", ...own].join(
-      "\n",
-    );
-  }
-  const head = `skills at ${skills.address}, served by ${skills.source}: ${skills.status}`;
-  if (skills.status !== "ready") {
-    return [head, SKILLS_WORDS[skills.status], ...own].join("\n");
-  }
-  const lines = [head];
-  if (skills.pack !== undefined) {
-    const named = [skills.pack.name, skills.pack.description]
-      .filter((text): text is string => text !== null)
-      .join("  ");
-    if (named !== "") {
-      lines.push(named);
-    }
-  }
-  if (skills.counts !== undefined) {
-    lines.push(
-      `${counted(skills.counts.skills, "skill")}, ${counted(skills.counts.documents, "document")}: console skills <folder> shows what a folder holds (. for the root), console skills --search <words> finds skills and documents by words.`,
-    );
-  }
-  if (skills.items.length === 0) {
-    lines.push("No skills at this address.");
-  }
-  // The path, which console skill takes, and the URI beside it, which a host's own connection takes.
-  for (const skill of skills.items) {
-    lines.push(
-      `${skill.name}  ${skill.description}`,
-      `    ${skill.path}${skill.uri === null ? "" : `  ${skill.uri}`}`,
-    );
-  }
-  lines.push(
-    "",
-    `Read a skill whole with console skill <path>, its rules first, and a file of the pack with console skill --file <path>; or load it by its URI through your own SkillCDN connection to this address, which a person makes at ${skills.page}. --json adds the page of each, for a person.`,
-    ...own,
-  );
-  return lines.join("\n");
-}
-
 /** One half of the rules: where it comes from, and the text as it stands. */
 function formatRulesHalf(where: "the workspace" | "this project", rules: RestRules): string {
   const page = rules.page;
@@ -417,19 +346,25 @@ export function formatDecisionLine(decision: RestDecision): string {
   return `${decision.id}  ${state}  ${decision.question}  (asked by ${asker(decision)})`;
 }
 
+/** The options, one a line; the person's own answer, when they wrote one, is the last and says so. */
 export function formatOptions(decision: RestDecision): string {
-  return decision.options.map((option) => `  ${option.id}) ${option.label}`).join("\n");
+  return decision.options
+    .map(
+      (option) =>
+        `  ${option.id}) ${option.label}${option.own === true ? "  (the person's own answer, not one given)" : ""}`,
+    )
+    .join("\n");
 }
 
-/** The answer, with who gave it; or that there is none yet. */
+/** The answer, with who gave it, and that it is in their own words when it is; or that there is none yet. */
 export function formatAnswer(decision: RestDecision): string {
   const { answer } = decision;
   if (answer === null) {
     return "waits for a person.";
   }
-  const label = decision.options.find((option) => option.id === answer.option)?.label;
+  const chosen = decision.options.find((option) => option.id === answer.option);
   const lines = [
-    `Answered: ${answer.option}) ${label ?? answer.option}, by ${answer.by.login} at ${answer.at}`,
+    `Answered: ${answer.option}) ${chosen?.label ?? answer.option}${chosen?.own === true ? ", in their own words" : ""}, by ${answer.by.login} at ${answer.at}`,
   ];
   if (answer.note !== null && answer.note.length > 0) {
     lines.push(`Note: ${answer.note}`);
@@ -531,256 +466,3 @@ export function formatVersion(path: string, version: RestVersion): string {
 }
 
 /** The text of one path across the pages a skill came in: the fragments joined in order. */
-function joinTexts(
-  pages: readonly RestSkillPage[],
-  pick: (page: RestSkillPage) => readonly { readonly path: string; readonly body: string }[],
-): { readonly path: string; readonly body: string }[] {
-  const joined = new Map<string, string>();
-  for (const page of pages) {
-    for (const text of pick(page)) {
-      joined.set(text.path, (joined.get(text.path) ?? "") + text.body);
-    }
-  }
-  return [...joined.entries()].map(([path, body]) => ({ path, body }));
-}
-
-const NO_ADDRESS = "No skills address: neither this project nor the console names one.";
-
-/**
- * One skill, as load_skill lays it out for a model (ADR-0028): the rules from the repository's
- * root to the nearest manifest, the body, the included files, each under a line that names its
- * path; then the files the skill has and what it refers to. A skill described only is named and
- * pointed at, and nothing of its body is shown.
- */
-export function formatSkillLoad(loaded: RestSkillLoad, pages: readonly RestSkillPage[]): string {
-  if (loaded.status === "none" || loaded.address === null) {
-    return NO_ADDRESS;
-  }
-  const head = `skill at ${loaded.address}, served by ${loaded.source}: ${loaded.status}`;
-  if (loaded.status !== "ready") {
-    return [head, SKILLS_WORDS[loaded.status]].join("\n");
-  }
-  const [first] = pages;
-  if (first === undefined) {
-    return [head, "Nothing was read."].join("\n");
-  }
-  const last = pages[pages.length - 1] ?? first;
-  const lines = [
-    `${first.name}  ${first.description}`,
-    `skill ${first.path} at ${loaded.address}, served by ${loaded.source}`,
-  ];
-  if (first.serving.license !== null) {
-    lines.push(`license: ${first.serving.license}`);
-  }
-  if (!first.serving.full) {
-    lines.push(
-      "",
-      `Described only: the license keeps the skill at its source. Read it there: ${first.serving.sourceUrl ?? loaded.page ?? loaded.source}`,
-    );
-    return lines.join("\n");
-  }
-  for (const rule of joinTexts(pages, (page) => page.rules)) {
-    lines.push("", `--- applicable rules: ${rule.path} ---`, rule.body.trimEnd());
-  }
-  lines.push(
-    "",
-    `--- skill: ${first.path} ---`,
-    pages
-      .map((page) => page.body)
-      .join("")
-      .trimEnd(),
-  );
-  for (const file of joinTexts(pages, (page) => page.included)) {
-    lines.push("", `--- included file: ${file.path} ---`, file.body.trimEnd());
-  }
-  if (!last.complete) {
-    lines.push("", "The skill did not come whole: the deployment stopped before the end.");
-  }
-  if (last.files.length > 0) {
-    lines.push(
-      "",
-      `Files of the skill, read with console skill --file <path>: ${last.files.join(", ")}`,
-    );
-  }
-  if (last.references.length > 0) {
-    lines.push(
-      `References: ${last.references
-        .map((reference) =>
-          reference.status === "available"
-            ? reference.path
-            : `${reference.path} (${reference.status})`,
-        )
-        .join(", ")}`,
-    );
-  }
-  if (last.warnings.length > 0) {
-    lines.push(`Warnings: ${last.warnings.join("; ")}`);
-  }
-  lines.push(
-    "",
-    "Paths from the repository's root are the only identifiers. The content is the pack's, under its license; what a private pack says stays in your work.",
-  );
-  return lines.join("\n");
-}
-
-/** A file of the pack as read: its text whole, or what the folder holds. */
-export function formatSkillFile(read: RestSkillFile, content: string): string {
-  if (read.status === "none" || read.address === null) {
-    return NO_ADDRESS;
-  }
-  const head = `file at ${read.address}, served by ${read.source}: ${read.status}`;
-  if (read.status !== "ready") {
-    return [
-      head,
-      read.status === "failed"
-        ? "SkillCDN will not carry this file: it is too large, or not text. Read it at the repository."
-        : SKILLS_WORDS[read.status],
-    ].join("\n");
-  }
-  if (read.folder !== null) {
-    return [
-      `folder ${read.folder.path} at ${read.address}${read.folder.truncated ? " (cut)" : ""}`,
-      ...read.folder.entries.map(
-        (entry) =>
-          `${entry.kind === "directory" ? "d" : "f"}  ${entry.path}${entry.size === null ? "" : `  ${entry.size}`}`,
-      ),
-      "",
-      "console skills <folder> shows a folder with its skills marked, what each folder holds and the README that introduces it.",
-    ].join("\n");
-  }
-  if (read.file === null) {
-    return `${head}: nothing was read.`;
-  }
-  return [
-    `--- file: ${read.file.path} (${read.file.totalLength} characters) ---`,
-    content.trimEnd(),
-  ].join("\n");
-}
-
-/** One entry of a browsed folder: what it is, its path, its words, and the facts of its kind. */
-function formatBrowseEntry(entry: RestSkillBrowseEntry): string {
-  const facts: string[] = [];
-  if (entry.kind === "directory") {
-    if (entry.skillCount > 0) {
-      facts.push(counted(entry.skillCount, "skill"));
-    }
-    if (entry.documentCount > 0) {
-      facts.push(counted(entry.documentCount, "document"));
-    }
-    if (entry.overviewPath !== null) {
-      facts.push(`README ${entry.overviewPath}`);
-    }
-  }
-  if (entry.kind === "skill") {
-    if (entry.license !== null) {
-      facts.push(entry.license);
-    }
-    if (entry.describedOnly) {
-      facts.push("described only");
-    }
-  }
-  if (entry.kind === "file" && entry.size !== null) {
-    facts.push(`${entry.size} bytes`);
-  }
-  const words = [entry.name, entry.description]
-    .filter((text): text is string => text !== null && text !== "")
-    .join("  ");
-  const mark = entry.kind === "skill" ? "skill" : entry.kind === "directory" ? "d" : "f";
-  return `${mark}  ${entry.path}${words === "" ? "" : `  ${words}`}${facts.length === 0 ? "" : `  (${facts.join("; ")})`}`;
-}
-
-/**
- * What a folder of the pack holds, as browse_repo lays it out: the README that introduces the
- * folder, then its skills, its folders with what each holds, and its files, across the pages the
- * listing came in.
- */
-export function formatSkillBrowse(
-  browsed: RestSkillBrowse,
-  folders: readonly NonNullable<RestSkillBrowse["folder"]>[],
-): string {
-  if (browsed.status === "none" || browsed.address === null) {
-    return NO_ADDRESS;
-  }
-  const head = `folder at ${browsed.address}, served by ${browsed.source}: ${browsed.status}`;
-  if (browsed.status !== "ready") {
-    return [head, SKILLS_WORDS[browsed.status]].join("\n");
-  }
-  const [first] = folders;
-  if (first === undefined) {
-    return [head, "Nothing was read."].join("\n");
-  }
-  const last = folders[folders.length - 1] ?? first;
-  const lines = [`folder ${first.path === "" ? "/" : first.path} at ${browsed.address}`];
-  if (first.overview !== null) {
-    const words = [first.overview.title, first.overview.description]
-      .filter((text): text is string => text !== null && text !== "")
-      .join("  ");
-    lines.push(`    ${words === "" ? "" : `${words}  `}(README: ${first.overview.path})`);
-  }
-  const entries = folders.flatMap((folder) => folder.entries);
-  if (entries.length === 0) {
-    lines.push("Nothing in this folder.");
-  }
-  for (const entry of entries) {
-    lines.push(formatBrowseEntry(entry));
-  }
-  if (last.nextCursor !== null) {
-    lines.push("More entries: the listing stopped before the end of the folder.");
-  }
-  lines.push(
-    "",
-    "Read a skill with console skill <path>; a file, or a README named above, with console skill --file <path>; a folder with console skills <folder>.",
-  );
-  return lines.join("\n");
-}
-
-/**
- * What words found in the pack, as search_repo lays it out: skills with the files of theirs that
- * matched, documents on their own, in relevance order; words, not meaning.
- */
-export function formatSkillFind(found: RestSkillFind): string {
-  if (found.status === "none" || found.address === null) {
-    return NO_ADDRESS;
-  }
-  const head = `search at ${found.address}, served by ${found.source}: ${found.status}`;
-  if (found.status !== "ready") {
-    return [head, SKILLS_WORDS[found.status]].join("\n");
-  }
-  if (found.found === null) {
-    return [head, "Nothing was read."].join("\n");
-  }
-  const { query, path, items, nextCursor } = found.found;
-  const where = path === null || path === "" ? "" : ` within ${path}`;
-  const lines = [
-    `found for "${query}"${where} at ${found.address}: ${counted(items.length, "result")}`,
-  ];
-  for (const item of items) {
-    if (item.kind === "skill") {
-      lines.push(
-        `skill  ${item.path}  ${item.name}  ${item.description}${item.describedOnly ? "  (described only)" : ""}`,
-      );
-      for (const file of item.files) {
-        lines.push(`    file  ${file.path}${file.title === null ? "" : `  ${file.title}`}`);
-      }
-      if (item.moreFiles > 0) {
-        lines.push(`    and ${counted(item.moreFiles, "more file")}`);
-      }
-    } else {
-      lines.push(
-        `document  ${item.path}${item.title === null ? "" : `  ${item.title}`}${item.summary === null ? "" : `  ${item.summary}`}`,
-      );
-    }
-  }
-  if (nextCursor !== null) {
-    lines.push(
-      "More matched: narrow the words, or search within a folder (console skills <folder> --search <words>).",
-    );
-  }
-  if (items.length > 0) {
-    lines.push(
-      "",
-      "Read a skill with console skill <path>, a file or a document with console skill --file <path>.",
-    );
-  }
-  return lines.join("\n");
-}

package/src/cli/help.ts

@@ -285,11 +285,12 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     ],
   },
   skills: {
-    usage: "skills  |  skills <folder>  |  skills --search <words> [<folder>] [--limit <n>]",
+    usage:
+      "skills  |  skills <folder>  |  skills --search <words> [<folder>] [--limit <n>] [--cursor <cursor>]",
     synopsis:
       "The project's pack: its skills; what a folder of it holds; or what words find in it.",
     about:
-      "The project's pack, as SkillCDN serves it at the project's address, read by the console with the pack token the project holds where the pack is private (ADR-0028). Alone: the pack by name with how many skills and documents it has, and its skills, each with its description, the path of its SKILL.md, which console skill reads it by, and the URI you load it by through your own SkillCDN connection where your host has one; and where the console's own skills are on this machine. With a folder (. for the root): what it holds, as browse_repo lays it out: its skills, its folders with how many skills and documents each holds and the README that introduces it, its files; whole, page after page. With --search: the skills and the documents the words find, in relevance order, a skill with the files of it that matched; words, not meaning, in the language the pack is written in; within the folder when one is named; 10 unless --limit says otherwise, up to 25, and a last line says when more matched. --json answers with the console's own JSON, the page of each skill included.",
+      "The project's pack, read by the console at the project's address, or the organization's: at a SkillCDN deployment, with the pack token the project holds where the pack is private (ADR-0028), or from a directory on the console's machine for a local address (ADR-0031). Alone: where the pack is and what a client is told of it on connect, then every skill with the path of its SKILL.md and every document, as a connection of your own would list them, and where the console's own skills are on this machine. With a folder (. for the root): what it holds, whole, as browse_repo lays it out for a model: its skills, its folders with what each holds and the README that introduces it, its files. With --search: what the words find, as search_repo does: skills first, with the files of theirs that matched, then documents, in relevance order; words, not meaning, in the language the pack is written in; within the folder when one is named; 10 unless --limit says otherwise, up to 25, and a nextCursor line says when more matched, which --cursor continues. The text is the one an MCP client's model is given, with the reads named as these commands. --json answers with the console's own JSON: what the pack answered, in the shapes of the main repository's REST API, the pages of a folder joined.",
     limits: ["search: 1 to 500 characters; limit: 1 to 25"],
     refusals: [
       "status not_found: the pack is not served to the console; private, with no pack token on the project",
@@ -301,11 +302,11 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     synopsis:
       "One skill of the pack whole, its rules first; or with --file a file of the pack, or what a folder holds.",
     about:
-      "One skill of the project's pack, whole, as load_skill lays it out for you: the rules of the repository from its root to the nearest manifest, the skill's body, the files it includes, each under a line that names its path; then the files it has and what it refers to. Read by the console from the SkillCDN deployment, with the pack token the project holds where the pack is private, so you need no connection of your own. <path> is the path of the SKILL.md from the repository's root, as console skills lists it, or the URI it lists beside the path (skill://gh/<owner>/<repo>/<path>). --file <path> reads a file of the pack instead, whole, or what a folder holds, and takes no skill's path beside it; console skills <folder> shows a folder with more.",
+      "One skill of the project's pack, whole, as load_skill lays it out for a model: the rules of the repository from its root to the nearest manifest, the skill's instructions, the files it includes, then its supporting files and what it refers to; the pages it came in are joined. Read by the console from the pack, with the pack token the project holds where the pack is private, so you need no connection of your own. <path> is the path of the SKILL.md from the repository's root, as console skills lists it, or the URI the pack names it by (skill://<host>/<owner>/<name>/<path>). --file <path> reads a file of the pack instead, whole, as read_repo_file does, or what a folder holds, and takes no skill's path beside it; console skills <folder> shows a folder with more. --json answers with what the pack answered, in the shapes of the main repository's REST API, the pages joined.",
     refusals: [
       "status not_found: the pack is not served to the console; private, with no pack token on the project",
       "status token_invalid: the pack token the project holds no longer works; an owner sets a new one",
-      "status failed, for a file: SkillCDN will not carry it, too large or not text",
+      "status failed, for a file: the pack will not carry it, too large or not text",
     ],
   },
   rules: {
@@ -370,7 +371,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       'ask "<question>" --option "<label>" --option "<label>" [...] [--body <markdown>|--file <path>] [--wait <seconds>]',
     synopsis:
       "Raises a decision a person must make, with options, and waits a while for the answer.",
-    about: `Raises a decision a person must make: the question, the options to choose from, and what they need to know. The run waits for the answer. The command waits 60 seconds for it unless --wait says otherwise, and exits with 3 if it is still to come: keep waiting with \`console decision <id> --wait 100\`, within what your shell gives one command. The decision's id is printed as soon as it is raised. ${ON_THE_RUN}`,
+    about: `Raises a decision a person must make: the question, the options to choose from, and what they need to know. The run waits for the answer. The command waits 60 seconds for it unless --wait says otherwise, and exits with 3 if it is still to come: keep waiting with \`console decision <id> --wait 100\`, within what your shell gives one command. The decision's id is printed as soon as it is raised. The person chooses one of the options, or answers in their own words: the answer then names one more option, their words, marked own; act on it as given. ${ON_THE_RUN}`,
     limits: [
       `question: one line, up to ${MAX_QUESTION_LENGTH} characters`,
       `options: ${MIN_OPTIONS} to ${MAX_OPTIONS}, each one line up to ${MAX_OPTION_LABEL_LENGTH} characters`,
@@ -383,7 +384,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     synopsis:
       "One decision in full; waits for its answer with --wait; writes what followed with --outcome.",
     about:
-      "One decision, with its context, its options, its answer and what followed. With --wait, holds on for the answer that long, and exits with 3 if it is still to come. With --outcome, writes down what followed the decision, so that it reads as a record.",
+      "One decision, with its context, its options, its answer (one of the options, or the person's own words as one more, marked own) and what followed. With --wait, holds on for the answer that long, and exits with 3 if it is still to come. With --outcome, writes down what followed the decision, so that it reads as a record.",
     limits: [`outcome: ${MARKDOWN}`],
     refusals: ["decision.not_found: no decision has that id"],
   },