@skillcdn/console 0.1.5 → 0.1.7

package/src/cli/credentials.ts

@@ -0,0 +1,68 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import * as z from "zod/mini";
+
+// Where the command keeps what `login` was given: the console's address and the token, in the
+// person's own configuration directory, readable by them alone where the system can say so.
+// The token is a secret the person made; the file is the one place it rests.
+
+export interface Credentials {
+  /** The origin of the console, without a path. */
+  readonly url: string;
+  /** A token made on the console's Agents page. */
+  readonly token: string;
+}
+
+export interface CredentialStore {
+  load(): Promise<Credentials | undefined>;
+  /** Keeps the credentials and answers where. */
+  save(credentials: Credentials): Promise<string>;
+  clear(): Promise<void>;
+}
+
+const credentialsSchema = z.object({
+  url: z.string().check(z.minLength(1)),
+  token: z.string().check(z.minLength(1)),
+});
+
+const FILE_NAME = "credentials.json";
+
+/** The directory the file lives in: under `XDG_CONFIG_HOME`, or `~/.config`. */
+export function defaultConfigDir(env: Readonly<Record<string, string | undefined>>): string {
+  const base = env.XDG_CONFIG_HOME;
+  return join(
+    base === undefined || base.length === 0 ? join(homedir(), ".config") : base,
+    "skillcdn-console",
+  );
+}
+
+export function createFileStore(directory: string): CredentialStore {
+  const path = join(directory, FILE_NAME);
+  return {
+    async load() {
+      let content: string;
+      try {
+        content = await readFile(path, "utf8");
+      } catch {
+        return undefined;
+      }
+      try {
+        const parsed = credentialsSchema.safeParse(JSON.parse(content));
+        return parsed.success ? parsed.data : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    async save(credentials) {
+      await mkdir(directory, { recursive: true, mode: 0o700 });
+      await writeFile(path, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+      // The mode above applies to a file made now; one that was there keeps its own, so it is set again.
+      await chmod(path, 0o600).catch(() => undefined);
+      return path;
+    },
+    async clear() {
+      await rm(path, { force: true });
+    },
+  };
+}

package/src/cli/directory.ts

@@ -0,0 +1,59 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import * as z from "zod/mini";
+
+// What a working directory says about the project it belongs to: `.skillcdn-console.json` in
+// it or in a directory above it, as `.nvmrc` and its kind are found. Written by `console use`,
+// and meant to be committed, so that everyone who works in the checkout, and every agent they
+// run in it, is in the same project without saying so.
+
+/** The file's name, in the working directory or one above it. */
+export const DIRECTORY_FILE = ".skillcdn-console.json";
+
+export interface DirectorySettings {
+  /** The key of the project the directory's work belongs to. */
+  readonly project: string;
+}
+
+export interface DirectoryStore {
+  /** The settings of the working directory, or of the nearest directory above it that has them. */
+  load(): Promise<DirectorySettings | undefined>;
+  /** Writes the settings into the working directory and answers where. */
+  save(settings: DirectorySettings): Promise<string>;
+}
+
+const settingsSchema = z.object({ project: z.string().check(z.minLength(1)) });
+
+export function createDirectoryStore(cwd: string): DirectoryStore {
+  return {
+    async load() {
+      let directory = cwd;
+      for (;;) {
+        let content: string | undefined;
+        try {
+          content = await readFile(join(directory, DIRECTORY_FILE), "utf8");
+        } catch {
+          content = undefined;
+        }
+        if (content !== undefined) {
+          try {
+            const parsed = settingsSchema.safeParse(JSON.parse(content));
+            return parsed.success ? parsed.data : undefined;
+          } catch {
+            return undefined;
+          }
+        }
+        const above = dirname(directory);
+        if (above === directory) {
+          return undefined;
+        }
+        directory = above;
+      }
+    },
+    async save(settings) {
+      const path = join(cwd, DIRECTORY_FILE);
+      await writeFile(path, `${JSON.stringify(settings, null, 2)}\n`);
+      return path;
+    },
+  };
+}

package/src/cli/format.ts

@@ -0,0 +1,284 @@
+import type {
+  RestArtifact,
+  RestDecision,
+  RestDocument,
+  RestDocumentSummary,
+  RestDocuments,
+  RestProject,
+  RestRun,
+  RestSkills,
+  RestTask,
+  RestVersion,
+  RestVersionSummary,
+} from "../schemas.js";
+
+// What the command prints: one line per thing in a list, a few lines for one thing in full.
+// Plain text, for an agent to read and a person to skim; ids are given, since the commands take
+// them, and the words are the vocabulary's own, since the options take those.
+
+const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? "" : "s"}`;
+
+const indent = (text: string): string =>
+  text
+    .trimEnd()
+    .split("\n")
+    .map((line) => `    ${line}`)
+    .join("\n");
+
+const asker = (decision: RestDecision): string =>
+  decision.run === null
+    ? decision.raisedBy.login
+    : `${decision.run.agent} for ${decision.raisedBy.login}`;
+
+/** One project: its key, its name, what the person is in it, and what waits in it. */
+export function formatProjectLine(project: RestProject): string {
+  const notes: string[] = [project.role];
+  if (project.openDecisions > 0) {
+    notes.push(`${plural(project.openDecisions, "decision")} waiting`);
+  }
+  if (project.openRuns > 0) {
+    notes.push(`${plural(project.openRuns, "agent")} at work`);
+  }
+  return `${project.key}  ${project.name}  (${notes.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.openDecisions > 0) {
+    notes.push(`${plural(task.openDecisions, "decision")} waiting`);
+  }
+  if (task.openRuns > 0) {
+    notes.push("an agent at work");
+  }
+  return `#${task.number}  ${task.state}  ${task.priority}  ${task.title}  (${notes.join("; ")})`;
+}
+
+/** One task in full; with the decisions about it and the runs on it, when given. */
+export function formatTask(
+  task: RestTask,
+  decisions?: readonly RestDecision[],
+  runs?: readonly RestRun[],
+): string {
+  const lines = [
+    `#${task.number} ${task.title}`,
+    `state: ${task.state}  priority: ${task.priority}  owner: ${task.owner.login}  assignee: ${task.assignee?.login ?? "nobody"}`,
+    `id: ${task.id}${task.parentId === null ? "" : `  part of: ${task.parentId}`}`,
+  ];
+  if (task.links.length > 0) {
+    lines.push("links:");
+    for (const link of task.links) {
+      lines.push(`  ${link.label === null ? link.url : `${link.label}: ${link.url}`}`);
+    }
+  }
+  if (task.body.trim().length > 0) {
+    lines.push("", task.body.trimEnd());
+  }
+  if (decisions !== undefined) {
+    lines.push("", decisions.length === 0 ? "decisions: none" : "decisions:");
+    for (const decision of decisions) {
+      lines.push(`  ${formatDecisionLine(decision)}`);
+    }
+  }
+  if (runs !== undefined) {
+    lines.push("", runs.length === 0 ? "runs: none" : "runs:");
+    for (const run of runs) {
+      lines.push(`  ${formatRunLine(run)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export function formatRunLine(run: RestRun): string {
+  const notes = [plural(run.reports.length, "report"), plural(run.artifacts.length, "artifact")];
+  if (run.waitingFor !== null) {
+    notes.push(`waiting for decision ${run.waitingFor}`);
+  }
+  return `${run.id}  ${run.status}  ${run.agent} for ${run.person.login}  task #${run.taskNumber}  (${notes.join(", ")})`;
+}
+
+/** One run in full; with where each file handed in is read, when the caller knows. */
+export function formatRun(run: RestRun, fileUrl?: (artifactId: string) => string): string {
+  const lines = [
+    formatRunLine(run),
+    `started: ${run.startedAt}${run.endedAt === null ? "" : `  ended: ${run.endedAt}`}`,
+  ];
+  if (run.summary !== null) {
+    lines.push("", "summary:", indent(run.summary));
+  }
+  if (run.reports.length > 0) {
+    lines.push("", "reports:");
+    for (const report of run.reports) {
+      lines.push(`  [${report.createdAt}]`, indent(report.body));
+    }
+  }
+  if (run.artifacts.length > 0) {
+    lines.push("", "artifacts:");
+    for (const artifact of run.artifacts) {
+      lines.push(`  ${formatArtifact(artifact, fileUrl)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/** What was handed in: the link, or the file with its size and where its bytes are read. */
+export function formatArtifact(
+  artifact: RestArtifact,
+  fileUrl?: (artifactId: string) => string,
+): string {
+  const what =
+    artifact.file === null
+      ? (artifact.url ?? "")
+      : `${artifact.file.name} (${artifact.file.size} bytes, ${artifact.file.contentType}${fileUrl === undefined ? "" : `; read at ${fileUrl(artifact.id)}`})`;
+  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.",
+  unavailable: "SkillCDN could not be reached; ask again later.",
+};
+
+/** The organization's skills: where they are, and each with what an agent loads it by. */
+export function formatSkills(skills: RestSkills): string {
+  if (skills.status === "none" || skills.address === null) {
+    return "No skills address: neither this project nor the console names one.";
+  }
+  const head = `skills at ${skills.address}, served by ${skills.source}: ${skills.status}`;
+  if (skills.status !== "ready") {
+    return `${head}\n${SKILLS_WORDS[skills.status]}`;
+  }
+  if (skills.items.length === 0) {
+    return `${head}\nNo skills at this address.`;
+  }
+  const lines = [head];
+  for (const skill of skills.items) {
+    lines.push(`${skill.name}  ${skill.description}`, `    ${skill.uri ?? skill.path}`);
+  }
+  lines.push(
+    "",
+    "Load a skill by its URI through your SkillCDN connection. --json adds the page of each, for a person.",
+  );
+  return lines.join("\n");
+}
+
+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)})`;
+}
+
+export function formatOptions(decision: RestDecision): string {
+  return decision.options.map((option) => `  ${option.id}) ${option.label}`).join("\n");
+}
+
+/** The answer, with who gave it; 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 lines = [
+    `Answered: ${answer.option}) ${label ?? answer.option}, by ${answer.by.login} at ${answer.at}`,
+  ];
+  if (answer.note !== null && answer.note.length > 0) {
+    lines.push(`Note: ${answer.note}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatDecision(decision: RestDecision): string {
+  const lines = [
+    `decision ${decision.id}: ${decision.question}`,
+    `asked by ${asker(decision)}${decision.taskNumber === null ? "" : `, about task #${decision.taskNumber}`}`,
+  ];
+  if (decision.body.trim().length > 0) {
+    lines.push("", decision.body.trimEnd());
+  }
+  lines.push("", "options:", formatOptions(decision), "", formatAnswer(decision));
+  if (decision.outcome !== null && decision.outcome.trim().length > 0) {
+    lines.push("", "what followed:", indent(decision.outcome));
+  }
+  return lines.join("\n");
+}
+
+/** Who wrote a version, and through which agent. */
+const writer = (by: { readonly login: string }, agent: string | null): string =>
+  agent === null ? by.login : `${agent} for ${by.login}`;
+
+/** One document in a list: its path, its title, its version, who wrote it last and when. */
+export function formatDocumentLine(document: RestDocumentSummary): string {
+  const notes = [`v${document.version}`, `by ${writer(document.updatedBy, document.agent)}`];
+  if (document.archivedAt !== null) {
+    notes.push("archived");
+  }
+  return `${document.path}  ${document.title}  (${notes.join(", ")}; ${document.updatedAt})`;
+}
+
+/** A folder's folders and pages, or the pages a search found. */
+export function formatDocuments(listing: RestDocuments): string {
+  if (listing.folders.length === 0 && listing.items.length === 0) {
+    return "No pages here.";
+  }
+  const lines = listing.folders.map((folder) => `${folder}/`);
+  for (const document of listing.items) {
+    lines.push(formatDocumentLine(document));
+  }
+  return lines.join("\n");
+}
+
+/** One document in full: its latest version, what it links to, what refers to it, and its files. */
+export function formatDocument(
+  document: RestDocument,
+  fileUrl?: (fileId: string) => string,
+): string {
+  const lines = [
+    `${document.path}: ${document.title}`,
+    `version ${document.version}, by ${writer(document.updatedBy, document.agent)} at ${document.updatedAt}${document.archivedAt === null ? "" : `; archived ${document.archivedAt}`}`,
+    `id: ${document.id}`,
+  ];
+  if (document.body.trim().length > 0) {
+    lines.push("", document.body.trimEnd());
+  }
+  if (document.links.length > 0) {
+    lines.push("", "refers to:");
+    for (const link of document.links) {
+      lines.push(
+        `  ${link.path}${link.title === null ? "  (no page there yet)" : `  ${link.title}`}`,
+      );
+    }
+  }
+  if (document.backlinks.length > 0) {
+    lines.push("", "referred to by:");
+    for (const backlink of document.backlinks) {
+      lines.push(
+        `  ${backlink.kind} ${backlink.kind === "task" ? `#${backlink.number ?? "?"}` : (backlink.path ?? backlink.id)}  ${backlink.title}`,
+      );
+    }
+  }
+  if (document.files.length > 0) {
+    lines.push("", "files:");
+    for (const attached of document.files) {
+      const where = fileUrl === undefined ? "" : `; read at ${fileUrl(attached.id)}`;
+      const what = `${attached.file.name} (${attached.file.size} bytes, ${attached.file.contentType}${where})`;
+      lines.push(`  ${attached.label === null ? what : `${attached.label}: ${what}`}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export function formatVersionLine(version: RestVersionSummary): string {
+  return `v${version.number}  ${version.title}  (by ${writer(version.author, version.agent)}; ${version.createdAt})`;
+}
+
+/** One version of a document, with its body as it was. */
+export function formatVersion(path: string, version: RestVersion): string {
+  const lines = [`${path}: ${version.title}`, formatVersionLine(version)];
+  if (version.body.trim().length > 0) {
+    lines.push("", version.body.trimEnd());
+  }
+  return lines.join("\n");
+}