@skillcdn/console 0.1.18 → 0.1.19

package/src/cli/credentials.ts

@@ -1,31 +1,270 @@
-import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import process from "node:process";
 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.
+// Where the command keeps what `login` was given (ADR-0027): for every console a person signed
+// it in to, the console's address, the account there and the token, in the person's own
+// configuration directory, readable by them alone where the system can say so. A token is a
+// secret the person made; this file is the one place it rests, and a token goes only to the
+// console that issued it: the command resolves which console a command talks to first, and then
+// looks for a login there, never the other way round.
 
-export interface Credentials {
+/** One sign-in: a console, an account there, and the token the console handed over. */
+export interface Login {
   /** The origin of the console, without a path. */
   readonly url: string;
-  /** A token made on the console's Agents page. */
+  /** The person's login at the console, as the console named them; unknown for a login kept before accounts were. */
+  readonly account: string | undefined;
   readonly token: string;
+  /** What the token is called at the console, when known. */
+  readonly agent: string | undefined;
+  /** When the command was signed in, when known. */
+  readonly since: string | undefined;
 }
 
+/** Everything the command keeps: the logins, and the console a directory that names none works at. */
+export interface Credentials {
+  readonly default: string | undefined;
+  readonly logins: readonly Login[];
+}
+
+export const EMPTY_CREDENTIALS: Credentials = { default: undefined, logins: [] };
+
+/** How many consoles one machine may be signed in to: far more than anyone has. */
+export const MAX_LOGINS = 100;
+/** How large the file may be before it is not read: far above a hundred logins. */
+const MAX_FILE_BYTES = 64 * 1024;
+
 export interface CredentialStore {
+  /**
+   * What is kept, or nothing. A file that is there and cannot be read is a `CredentialsError`,
+   * so that the command stops and never writes over what it did not understand.
+   */
   load(): Promise<Credentials | undefined>;
-  /** Keeps the credentials and answers where. */
+  /** Keeps the credentials, whole, and answers where. */
   save(credentials: Credentials): Promise<string>;
+  /** Forgets everything kept. */
   clear(): Promise<void>;
 }
 
-const credentialsSchema = z.object({
+export class CredentialsError extends Error {
+  readonly code: "credentials.malformed" | "credentials.too_large";
+  readonly path: string;
+
+  constructor(code: CredentialsError["code"], path: string) {
+    super(
+      code === "credentials.too_large"
+        ? `The credentials file ${path} is larger than the command reads.`
+        : `The credentials file ${path} could not be read as one.`,
+    );
+    this.name = "CredentialsError";
+    this.code = code;
+    this.path = path;
+  }
+}
+
+const loginSchema = z.object({
+  url: z.string().check(z.minLength(1), z.maxLength(2048)),
+  account: z.optional(z.string().check(z.minLength(1), z.maxLength(254))),
+  token: z.string().check(z.minLength(1), z.maxLength(1024)),
+  agent: z.optional(z.string().check(z.maxLength(200))),
+  since: z.optional(z.string().check(z.maxLength(40))),
+});
+const fileSchema = z.object({
+  version: z.literal(2),
+  default: z.optional(z.string().check(z.minLength(1), z.maxLength(2048))),
+  logins: z.array(loginSchema).check(z.maxLength(MAX_LOGINS)),
+});
+/** The file as the command kept it before 2026-10: one console, one token. */
+const firstFileSchema = z.object({
   url: z.string().check(z.minLength(1)),
   token: z.string().check(z.minLength(1)),
 });
 
+/** What a file says, in the current shape; one in the first shape reads as one login, the default. Nothing for anything else. */
+export function parseCredentials(json: unknown): Credentials | undefined {
+  const current = fileSchema.safeParse(json);
+  if (current.success) {
+    return {
+      default: current.data.default,
+      logins: current.data.logins.map((login) => ({
+        url: login.url,
+        account: login.account,
+        token: login.token,
+        agent: login.agent,
+        since: login.since,
+      })),
+    };
+  }
+  const first = firstFileSchema.safeParse(json);
+  if (first.success) {
+    return {
+      default: first.data.url,
+      logins: [
+        {
+          url: first.data.url,
+          account: undefined,
+          token: first.data.token,
+          agent: undefined,
+          since: undefined,
+        },
+      ],
+    };
+  }
+  return undefined;
+}
+
+/** The logins at one console. */
+export function loginsAt(credentials: Credentials, url: string): readonly Login[] {
+  return credentials.logins.filter((login) => login.url === url);
+}
+
+/** The consoles signed in to, each once, in the order they were signed in to. */
+export function consolesOf(credentials: Credentials): readonly string[] {
+  return [...new Set(credentials.logins.map((login) => login.url))];
+}
+
+/**
+ * With a login kept: in place of the one at the same console for the same account, else added.
+ * The first login kept is the default console, and one kept as the default is.
+ */
+export function withLogin(
+  credentials: Credentials,
+  login: Login,
+  options: { readonly default?: boolean | undefined } = {},
+): Credentials {
+  const rest = credentials.logins.filter(
+    (kept) => !(kept.url === login.url && kept.account === login.account),
+  );
+  const first = credentials.logins.length === 0 ? login.url : undefined;
+  return {
+    default: options.default === true ? login.url : (credentials.default ?? first),
+    logins: [...rest, login],
+  };
+}
+
+/**
+ * Without the login at a console, for one account or for every account there. The default
+ * stays while a login at it remains; else it moves to the one console left, or to none.
+ */
+export function withoutLogin(credentials: Credentials, url: string, account?: string): Credentials {
+  const logins = credentials.logins.filter(
+    (kept) => !(kept.url === url && (account === undefined || kept.account === account)),
+  );
+  const consoles = [...new Set(logins.map((kept) => kept.url))];
+  const [only] = consoles;
+  const fallback = consoles.length === 1 ? only : undefined;
+  return {
+    default:
+      credentials.default !== undefined && consoles.includes(credentials.default)
+        ? credentials.default
+        : fallback,
+    logins,
+  };
+}
+
+/** Where a command is told which console to talk to, in the order the first one found wins. */
+export type AddressSource = "flag" | "environment" | "directory" | "default";
+
+export interface Lookup {
+  /** `--url`, as an origin. */
+  readonly flagUrl?: string | undefined;
+  /** `--account`. */
+  readonly flagAccount?: string | undefined;
+  /** `CONSOLE_URL`, as an origin, and `CONSOLE_TOKEN`: a pair, for a hook or a job. */
+  readonly envUrl?: string | undefined;
+  readonly envToken?: string | undefined;
+  /** What `.skillcdn-console.json` says of the console and the account, when it does. */
+  readonly directoryUrl?: string | undefined;
+  readonly directoryAccount?: string | undefined;
+  readonly credentials: Credentials | undefined;
+}
+
+export type Resolution =
+  | {
+      readonly ok: true;
+      readonly url: string;
+      readonly token: string;
+      readonly account: string | undefined;
+      readonly source: AddressSource;
+      /** Where the token came from: the environment's pair, or a login kept here. */
+      readonly via: "environment" | "login";
+    }
+  /** Nothing names a console and nothing is kept. */
+  | { readonly ok: false; readonly reason: "nothing" }
+  /** One half of the environment's pair is set. */
+  | {
+      readonly ok: false;
+      readonly reason: "environment_half";
+      readonly have: "CONSOLE_URL" | "CONSOLE_TOKEN";
+    }
+  /** A console is named, and nothing here is signed in to it, as that account where one is named. */
+  | {
+      readonly ok: false;
+      readonly reason: "no_login";
+      readonly url: string;
+      readonly account: string | undefined;
+      readonly source: AddressSource;
+    }
+  /** Several accounts are signed in at the console, and nothing says which. */
+  | {
+      readonly ok: false;
+      readonly reason: "ambiguous";
+      readonly url: string;
+      readonly accounts: readonly string[];
+    };
+
+/**
+ * Which console a command talks to, and with what (ADR-0027). The address comes first: the
+ * flag, else the environment, else the directory, else the default login. The token is then
+ * the one for that address and no other: the environment's token where its address is that
+ * one, else the login kept for it, for the account named or the one account there.
+ */
+export function resolveLogin(lookup: Lookup): Resolution {
+  const { envUrl, envToken } = lookup;
+  if ((envUrl === undefined) !== (envToken === undefined)) {
+    return {
+      ok: false,
+      reason: "environment_half",
+      have: envUrl === undefined ? "CONSOLE_TOKEN" : "CONSOLE_URL",
+    };
+  }
+  const credentials = lookup.credentials ?? EMPTY_CREDENTIALS;
+  const consoles = consolesOf(credentials);
+  const [source, url]: [AddressSource, string | undefined] =
+    lookup.flagUrl !== undefined
+      ? ["flag", lookup.flagUrl]
+      : envUrl !== undefined
+        ? ["environment", envUrl]
+        : lookup.directoryUrl !== undefined
+          ? ["directory", lookup.directoryUrl]
+          : ["default", credentials.default ?? (consoles.length === 1 ? consoles[0] : undefined)];
+  if (url === undefined) {
+    return { ok: false, reason: "nothing" };
+  }
+  const account = lookup.flagAccount ?? lookup.directoryAccount;
+  if (envUrl !== undefined && envToken !== undefined && envUrl === url) {
+    return { ok: true, url, token: envToken, account, source, via: "environment" };
+  }
+  const at = loginsAt(credentials, url);
+  const chosen = account === undefined ? at : at.filter((login) => login.account === account);
+  const [login] = chosen;
+  if (login === undefined) {
+    return { ok: false, reason: "no_login", url, account, source };
+  }
+  if (chosen.length > 1) {
+    return {
+      ok: false,
+      reason: "ambiguous",
+      url,
+      accounts: chosen.map((kept) => kept.account ?? "?"),
+    };
+  }
+  return { ok: true, url, token: login.token, account: login.account, source, via: "login" };
+}
+
 const FILE_NAME = "credentials.json";
 
 /** The directory the file lives in: under `XDG_CONFIG_HOME`, or `~/.config`. */
@@ -41,22 +280,45 @@ export function createFileStore(directory: string): CredentialStore {
   const path = join(directory, FILE_NAME);
   return {
     async load() {
-      let content: string;
+      let size: number;
       try {
-        content = await readFile(path, "utf8");
+        size = (await stat(path)).size;
       } catch {
         return undefined;
       }
+      if (size > MAX_FILE_BYTES) {
+        throw new CredentialsError("credentials.too_large", path);
+      }
+      let json: unknown;
       try {
-        const parsed = credentialsSchema.safeParse(JSON.parse(content));
-        return parsed.success ? parsed.data : undefined;
+        json = JSON.parse(await readFile(path, "utf8"));
       } catch {
-        return undefined;
+        throw new CredentialsError("credentials.malformed", path);
+      }
+      const parsed = parseCredentials(json);
+      if (parsed === undefined) {
+        throw new CredentialsError("credentials.malformed", path);
       }
+      return parsed;
     },
     async save(credentials) {
       await mkdir(directory, { recursive: true, mode: 0o700 });
-      await writeFile(path, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+      const file = {
+        version: 2,
+        default: credentials.default,
+        logins: credentials.logins.map((login) => ({
+          url: login.url,
+          account: login.account,
+          token: login.token,
+          agent: login.agent,
+          since: login.since,
+        })),
+      };
+      // Written beside the file and moved over it in one step, so that a command that stops
+      // half-way leaves the file as it was, whole.
+      const draft = `${path}.${process.pid}.tmp`;
+      await writeFile(draft, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+      await rename(draft, path);
       // 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;

package/src/cli/directory.ts

@@ -4,15 +4,27 @@ 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.
+// and meant to be committed in a private repository, so that everyone who works in the
+// checkout, and every agent they run in it, is in the same project without saying so; left out
+// of a public one, since it may name the organization's console. It names the project, and
+// where the checkout is bound to a console other than the default login, that console and the
+// account there (ADR-0027). Never a token, a code or anything secret: the token for the console
+// it names is looked up in the credentials the command keeps, and a key this file does not
+// know is dropped on reading.
 
 /** The file's name, in the working directory or one above it. */
 export const DIRECTORY_FILE = ".skillcdn-console.json";
 
+/** How large the file may be before it is not read: a few names, never more. */
+const MAX_FILE_CHARS = 16 * 1024;
+
 export interface DirectorySettings {
   /** The key of the project the directory's work belongs to. */
   readonly project: string;
+  /** The origin of the console the directory is bound to; the default login when left out. */
+  readonly url?: string | undefined;
+  /** The account at that console, where several are signed in to it. */
+  readonly account?: string | undefined;
 }
 
 export interface DirectoryStore {
@@ -22,7 +34,24 @@ export interface DirectoryStore {
   save(settings: DirectorySettings): Promise<string>;
 }
 
-const settingsSchema = z.object({ project: z.string().check(z.minLength(1)) });
+const settingsSchema = z.object({
+  project: z.string().check(z.minLength(1), z.maxLength(100)),
+  url: z.optional(z.string().check(z.minLength(1), z.maxLength(2048))),
+  account: z.optional(z.string().check(z.minLength(1), z.maxLength(254))),
+});
+
+/** What a file says, with nothing but the three settings kept; nothing for anything else. */
+export function parseDirectorySettings(json: unknown): DirectorySettings | undefined {
+  const parsed = settingsSchema.safeParse(json);
+  if (!parsed.success) {
+    return undefined;
+  }
+  return {
+    project: parsed.data.project,
+    ...(parsed.data.url === undefined ? {} : { url: parsed.data.url }),
+    ...(parsed.data.account === undefined ? {} : { account: parsed.data.account }),
+  };
+}
 
 export function createDirectoryStore(cwd: string): DirectoryStore {
   return {
@@ -36,9 +65,11 @@ export function createDirectoryStore(cwd: string): DirectoryStore {
           content = undefined;
         }
         if (content !== undefined) {
+          if (content.length > MAX_FILE_CHARS) {
+            return undefined;
+          }
           try {
-            const parsed = settingsSchema.safeParse(JSON.parse(content));
-            return parsed.success ? parsed.data : undefined;
+            return parseDirectorySettings(JSON.parse(content));
           } catch {
             return undefined;
           }
@@ -52,7 +83,13 @@ export function createDirectoryStore(cwd: string): DirectoryStore {
     },
     async save(settings) {
       const path = join(cwd, DIRECTORY_FILE);
-      await writeFile(path, `${JSON.stringify(settings, null, 2)}\n`);
+      // The three settings, named one by one: nothing else ever reaches this file.
+      const written = {
+        project: settings.project,
+        ...(settings.url === undefined ? {} : { url: settings.url }),
+        ...(settings.account === undefined ? {} : { account: settings.account }),
+      };
+      await writeFile(path, `${JSON.stringify(written, null, 2)}\n`);
       return path;
     },
   };

package/src/cli/format.ts

@@ -15,6 +15,9 @@ import type {
   RestProjectRules,
   RestRules,
   RestRun,
+  RestSkillFile,
+  RestSkillLoad,
+  RestSkillPage,
   RestSkills,
   RestTask,
   RestVersion,
@@ -55,6 +58,7 @@ export function formatProject(project: RestProject): string {
     `project ${project.key}: ${project.name}`,
     `visibility: ${project.visibility}  role: ${project.role}  skills: ${project.skillsAddress ?? "the organization's"}`,
     `color: ${project.color ?? "none"}  symbol: ${project.symbol ?? "none"}  image: ${project.icon === null ? "none" : project.icon.contentType}`,
+    `pack token: ${project.packToken === null ? "none" : `set ${project.packToken.setAt}`}`,
   ];
   if (project.description.trim().length > 0) {
     lines.push("", project.description.trimEnd());
@@ -102,6 +106,9 @@ export function formatTaskLine(task: RestTask): string {
   if (task.openDecisions > 0) {
     notes.push(`${plural(task.openDecisions, "decision")} waiting`);
   }
+  if (task.archivedAt !== null) {
+    notes.push("archived");
+  }
   return `#${task.number}  ${task.state}  ${task.priority}  ${task.title}  (${notes.join("; ")})`;
 }
 
@@ -120,6 +127,7 @@ function scheduleLines(task: RestTask): string[] {
   const happened = [
     task.startedAt === null ? undefined : `started: ${task.startedAt}`,
     task.doneAt === null ? undefined : `done: ${task.doneAt}`,
+    task.archivedAt === null ? undefined : `archived: ${task.archivedAt}`,
   ].filter((part) => part !== undefined);
   if (happened.length > 0) {
     lines.push(happened.join("  "));
@@ -239,7 +247,10 @@ export function formatArtifact(
 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.",
+  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.",
 };
 
@@ -271,7 +282,7 @@ export function formatSkills(skills: RestSkills, ownSkills?: string): string {
   }
   lines.push(
     "",
-    `Load a skill by its URI through your SkillCDN connection to this address; an agent without one is connected by a person at ${skills.page}. --json adds the page of each, for a person.`,
+    `Read a skill whole with console skill <path>, its rules first, and a file of the pack with console skill <path> --file <file>; 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");
@@ -495,3 +506,128 @@ export function formatVersion(path: string, version: RestVersion): string {
   }
   return lines.join("\n");
 }
+
+/** 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 ${first.path} --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}`}`,
+      ),
+    ].join("\n");
+  }
+  if (read.file === null) {
+    return `${head}: nothing was read.`;
+  }
+  return [
+    `--- file: ${read.file.path} (${read.file.totalLength} characters) ---`,
+    content.trimEnd(),
+  ].join("\n");
+}