@skillcdn/console 0.1.18 → 0.1.20

package/src/cli/help.ts

@@ -84,23 +84,28 @@ const TASK_FIELD_REFUSALS = [
 
 export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   login: {
-    usage: "login --url <origin> [--agent <name>] [--token-stdin]",
+    usage: "login --url <origin> [--agent <name>] [--token-stdin] [--default]",
     about:
-      "Connects this agent to the console: shows an address and a code, which a person opens signed in, names the agent and approves; the command then receives a token of its own and keeps it, with the console's address, in your home directory, never showing it. An agent running the command relays the address and the code to its person and waits. --agent says what the agent calls itself; left out, the command names the agent it runs under where its environment says so (Claude Code, Codex), else An agent; the machine's name follows, and the pages show the name before 'on' with the whole on hover. --token-stdin reads a token made by hand from standard input instead, for a script or a job.",
+      "Connects this agent to the console: shows an address and a code, which a person opens signed in, names the agent and approves; the command then receives a token of its own and keeps it, with the console's address and the account, in your home directory, never showing it. One login per console and account: a second console adds a login beside the first, the first is the default console a directory that names none works at, and --default makes this one that. A login repeated for the same console and account replaces its token, which is given up at the console. An agent running the command relays the address and the code to its person and waits. --agent says what the agent calls itself; left out, the command names the agent it runs under where its environment says so (Claude Code, Codex), else An agent; the machine's name follows, and the pages show the name before 'on' with the whole on hover. --token-stdin reads a token made by hand from standard input instead, for a script or a job.",
     refusals: [
       "connect.not_found: the code was not approved in time, or the person said it was not theirs; run login again",
       "the console does not know the token given: make one on the Agents page and try again",
     ],
   },
+  logins: {
+    usage: "logins",
+    about:
+      "The consoles this machine is signed in to, each with the account, what the token is called there, since when, and which is the default; never a token.",
+  },
   logout: {
-    usage: "logout",
+    usage: "logout [--url <origin>] [--account <login>]",
     about:
-      "Signs this agent out: gives the token up at the console, so that it is good for nothing from now on, and forgets it with the address kept here. A console out of reach leaves the token to the Agents page.",
+      "Signs this agent out of one console: gives the token up there, so that it is good for nothing from now on, and forgets it here. Which console: --url, else the one this directory is bound to, else the default, else the one console signed in to; --account says which account where the console has several. A console out of reach leaves the token to the Agents page.",
   },
   whoami: {
     usage: "whoami",
     about:
-      "Who the token acts as, which console it is for, and which project this directory works in.",
+      "Who the token acts as, which console the command talks to from here and as which account, and which project this directory works in.",
   },
   projects: {
     usage: "projects",
@@ -108,9 +113,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       "The projects you may work in: each with its key, its name, what you are in it, and what waits in it. Every command on the board works in one project.",
   },
   use: {
-    usage: "use <key>",
+    usage: "use <key> [--url <origin>] [--account <login>]",
     about:
-      "Says which project this directory works in: writes .skillcdn-console.json here, which the commands read from this directory or one above it, and which is meant to be committed. --project <key> on any command, or CONSOLE_PROJECT in the environment, wins over it.",
+      "Says which project this directory works in: writes .skillcdn-console.json here, which the commands read from this directory or one above it, and which is meant to be committed in a private repository and left out of a public one. The file names the project; and the console, where that is not the default login here or --url says so; and the account, where the console has several logins or --account says so. Never a token. --project <key> on any command, or CONSOLE_PROJECT in the environment, wins over the project it names.",
     refusals: ["project.not_found: no project has the key, or it is not yours to see"],
   },
   work: {
@@ -120,19 +125,23 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   tasks: {
     usage:
-      "tasks [--state <state>] [--open] [--mine] [--category <key>] [--goal <id>] [--due <day|today|week|overdue>] [--limit <n>] [--offset <n>]",
-    about: `The tasks on the board, newest first: number, state, priority, title, who owns and works on each, its category and its due day, and what waits on it. --open keeps the ones not done or dropped, --mine those assigned to you, --category and --goal those sorted into one, --due those due by a day: today, within the week, or overdue (the open ones past their day). A page at a time: ${DEFAULT_PAGE_LIMIT} unless --limit says otherwise, from --offset on; a last line says when there is more. States: idea, ready, in_progress, in_review, done, dropped.`,
+      "tasks [--state <state>] [--open] [--mine] [--category <key>] [--goal <id>] [--due <day|today|week|overdue>] [--unassigned] [--archived] [--limit <n>] [--offset <n>]",
+    about: `The tasks on the board, newest first: number, state, priority, title, who owns and works on each, its category and its due day, and what waits on it. --open keeps the ones not done or dropped, --mine those assigned to you, --unassigned those assigned to nobody (not with --mine), --category and --goal those sorted into one, --due those due by a day: today, within the week, or overdue (the open ones past their day). The tasks put away (ADR-0029) are left out unless --archived asks for them alone. A page at a time: ${DEFAULT_PAGE_LIMIT} unless --limit says otherwise, from --offset on; a last line says when there is more. States: idea, ready, in_progress, in_review, done, dropped.`,
   },
   task: {
-    usage: `task <number|id>  |  task new <title> [--body <markdown>|--file <path>] ${TASK_FIELD_FLAGS}  |  task edit <number|id> [--title <title>] [--body <markdown>|--file <path>] ${TASK_FIELD_FLAGS}`,
+    usage: `task <number|id>  |  task new <title> [--body <markdown>|--file <path>] ${TASK_FIELD_FLAGS}  |  task edit <number|id> [--title <title>] [--body <markdown>|--file <path>] ${TASK_FIELD_FLAGS}  |  task archive <number|id>  |  task archive --goal <id>  |  task restore <number|id>`,
     about:
-      "One task in full, with its plan (category, goal, start and due days), what happened to it (when it was started and done, which the board keeps itself), the decisions about it, the runs on it and the discussion on it, each comment whole with its files; or a new task written down; or a task changed, only in what the flags say, where none clears a field (priorities: low, normal, high, urgent).",
+      "One task in full, with its plan (category, goal, start and due days), what happened to it (when it was started and done, which the board keeps itself, and when it was put away), the decisions about it, the runs on it and the discussion on it, each comment whole with its files; or a new task written down; or a task changed, only in what the flags say, where none clears a field (priorities: low, normal, high, urgent). archive puts a done or dropped task away (ADR-0029): out of the listings, the board and the calendar, open by its number still; with --goal, every done or dropped task of the goal at once, for an owner. restore brings one back.",
     limits: [
       `title: one line, up to ${MAX_TITLE_LENGTH} characters, saying what is to be done on its own; what it refers to goes in the body`,
       `body: ${MARKDOWN}`,
       ...TASK_FIELD_LIMITS,
     ],
-    refusals: ["task.not_found: no task has that number or id", ...TASK_FIELD_REFUSALS],
+    refusals: [
+      "task.not_found: no task has that number or id",
+      "task.open: an open task is not put away; one done or dropped is",
+      ...TASK_FIELD_REFUSALS,
+    ],
   },
   goals: {
     usage: "goals [--category <key>] [--state <state>]",
@@ -181,9 +190,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   project: {
     usage:
-      'project <key>  |  project new <key> "<name>" [--description <markdown>|--file <path>] [--visibility workspace|private] [--skills <address>|none] [--color <name>] [--symbol <text>]  |  project edit <key> [--name "<name>"] [the same flags; none clears]  |  project icon <key> <file>  |  project icon <key> --remove',
+      'project <key>  |  project new <key> "<name>" [--description <markdown>|--file <path>] [--visibility workspace|private] [--skills <address>|none] [--color <name>] [--symbol <text>]  |  project edit <key> [--name "<name>"] [the same flags; none clears]  |  project icon <key> <file>  |  project icon <key> --remove  |  project pack-token <key> --stdin  |  project pack-token <key> --remove',
     about:
-      "One project in full; or a project made, with you as its owner, private unless --visibility workspace says everyone of the workspace works in it; or one changed, only in what the flags say, for an owner; or its image for its mark, set from a file of this machine or taken away. The organization's skills are the project's unless --skills names an address of its own.",
+      "One project in full; or a project made, with you as its owner, private unless --visibility workspace says everyone of the workspace works in it; or one changed, only in what the flags say, for an owner; or its image for its mark, set from a file of this machine or taken away; or its pack token (ADR-0028), the token a person made at SkillCDN for a private pack, read from standard input and never an argument, which the console keeps sealed to read the pack with, or taken away. The organization's skills are the project's unless --skills names an address of its own.",
     limits: [
       `key: ${KEY}, up to ${MAX_PROJECT_KEY_LENGTH} characters; it does not change once made`,
       `name: one line, up to ${MAX_PROJECT_NAME_LENGTH} characters; description: up to ${MAX_PROJECT_DESCRIPTION_LENGTH}`,
@@ -206,9 +215,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   },
   member: {
     usage:
-      "member add <login> [--role owner|member]  |  member role <login> <owner|member>  |  member remove <login>",
+      "member add <login> [--role owner|member] [--project <key>[,<key>...]]  |  member role <login> <owner|member>  |  member remove <login>",
     about:
-      "Lists a person of the workspace in the project, as a member unless --role says owner; changes what they are in it; or takes them off the list. For an owner of the project.",
+      "Lists a person of the workspace in the project, as a member unless --role says owner; changes what they are in it; or takes them off the list. For an owner of the project. With --project naming several keys with commas, member add lists the person in each of them in turn, one line per project; one listed already is said so, and the rest go on.",
     refusals: [
       "auth.forbidden: only an owner of the project lists its members",
       "member.invalid_person: the person is not of the workspace",
@@ -237,7 +246,17 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   skills: {
     usage: "skills",
     about:
-      "The organization's skills, as SkillCDN serves them at the project's address: each with its description and the URI you load it by through your own SkillCDN connection, which a person makes at the address's page when you have none; and where the console's own skills are on this machine. --json adds the page of each, for a person.",
+      "The skills of the project's pack, as SkillCDN serves them at the project's address: 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. A private pack is read with the pack token the project holds (ADR-0028). --json adds the page of each, for a person.",
+  },
+  skill: {
+    usage: "skill <path> [--file <path>]",
+    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. --file <path> reads a file of the pack instead, whole, or what a folder holds. What you read is the pack's, under its license: what a private pack says stays in your work and is not copied into reports or pages beyond what the work needs.",
+    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",
+    ],
   },
   rules: {
     usage:
@@ -275,7 +294,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   "hand-in": {
     usage: "hand-in <https url | file path> [--label <words>]",
     about:
-      "Hands in what was made: a link (a branch, a pull request, a document, a page), or a file from this machine, which the console keeps and shows on the task.",
+      "Hands in what was made: a link (a branch, a pull request, a document, a page), or a file from this machine, which the console keeps and shows on the task; a picture is shown there small and large, and a report that names it as ![words](its name) shows it where the words are.",
     limits: [
       "a link: https only",
       `a file: up to ${MAX_FILE_BYTES} bytes, not empty; it is called by its name, without the path`,
@@ -395,7 +414,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   attach: {
     usage: "attach <path> <file> [--label <words>]",
     about:
-      "Attaches a file from this machine to a page: the console keeps it, and the page shows it.",
+      "Attaches a file from this machine to a page: the console keeps it, and the page lists it; a picture is shown where the body names it as ![words](its name).",
     limits: [
       `a file: up to ${MAX_FILE_BYTES} bytes, not empty; it is called by its name, without the path`,
       `at most ${MAX_FILES_PER_DOCUMENT} files on one page`,
@@ -449,14 +468,18 @@ Exit codes: 0 done; 1 the console refused, or could not be reached (the reason i
 What the console refuses is printed as its code and its words. Everywhere:
 ${COMMON_REFUSALS.map((refusal) => `  ${refusal}`).join("\n")}
 
-Credentials: CONSOLE_URL and CONSOLE_TOKEN in the environment, else what login kept in
-$XDG_CONFIG_HOME/skillcdn-console/credentials.json (~/.config when XDG_CONFIG_HOME is unset).
+Which console a command talks to: --url, else CONSOLE_URL in the environment, else the console
+.skillcdn-console.json binds this directory to, else the default login. The token is then the one
+kept for that console alone (CONSOLE_TOKEN only together with CONSOLE_URL, for a hook or a job), in
+$XDG_CONFIG_HOME/skillcdn-console/credentials.json (~/.config when XDG_CONFIG_HOME is unset);
+a console nobody is signed in to here gets no request. --account <login> says which account where
+a console has several. console logins lists them.
 `;
 
 const SECTIONS: readonly { readonly title: string; readonly commands: readonly string[] }[] = [
   {
     title: "Signing in, once, as a person, and the project to work in",
-    commands: ["login", "logout", "whoami", "projects", "use"],
+    commands: ["login", "logins", "logout", "whoami", "projects", "use"],
   },
   {
     title: "The board",
@@ -472,6 +495,7 @@ const SECTIONS: readonly { readonly title: string; readonly commands: readonly s
       "runs",
       "run",
       "skills",
+      "skill",
       "rules",
     ],
   },

package/src/client.ts

@@ -12,6 +12,7 @@ import {
 } from "./routes.js";
 import {
   type RestAnswerInput,
+  type RestArchivedTasks,
   type RestArtifactInput,
   type RestCategories,
   type RestCategory,
@@ -43,6 +44,7 @@ import {
   type RestMemberPatch,
   type RestMembers,
   type RestMePatch,
+  type RestPackTokenInput,
   type RestPeople,
   type RestPerson,
   type RestPersonPatch,
@@ -59,6 +61,8 @@ import {
   type RestRunEndInput,
   type RestRunInput,
   type RestRuns,
+  type RestSkillFile,
+  type RestSkillLoad,
   type RestSkills,
   type RestTask,
   type RestTaskInput,
@@ -70,6 +74,7 @@ import {
   type RestVersion,
   type RestVersions,
   type RestWork,
+  restArchivedTasksSchema,
   restCategoriesSchema,
   restCategorySchema,
   restClaimSchema,
@@ -98,6 +103,8 @@ import {
   restRulesSchema,
   restRunSchema,
   restRunsSchema,
+  restSkillFileSchema,
+  restSkillLoadSchema,
   restSkillsSchema,
   restTaskSchema,
   restTasksSchema,
@@ -212,8 +219,12 @@ export interface TaskFilter extends Page {
   readonly goal?: string | undefined;
   /** The id of the person the tasks are assigned to. */
   readonly assignee?: string | undefined;
+  /** True for the tasks assigned to nobody. */
+  readonly unassigned?: boolean | undefined;
   /** A day (`2026-10-20`): the tasks due on it or before it. */
   readonly dueBy?: string | undefined;
+  /** True for the tasks put away alone (ADR-0029); false, or left out, for the current ones. */
+  readonly archived?: boolean | undefined;
 }
 
 /** What a folder's listing, or a search, of the documents is narrowed to. */
@@ -249,6 +260,11 @@ export interface ProjectClient {
   task(ref: string, signal?: AbortSignal): Promise<RestTask>;
   createTask(input: RestTaskInput): Promise<RestTask>;
   updateTask(id: string, patch: RestTaskPatch): Promise<RestTask>;
+  /** Puts a done or dropped task away (ADR-0029), or brings one back. */
+  archiveTask(id: string): Promise<RestTask>;
+  restoreTask(id: string): Promise<RestTask>;
+  /** Puts every done or dropped task of a goal away at once; for an owner. Answers how many. */
+  archiveTasksOfGoal(goalId: string): Promise<RestArchivedTasks>;
   /** The decisions, or only those that wait, or only those about one task; a page of them. */
   decisions(
     filter?: { readonly open?: boolean; readonly task?: string } & Page,
@@ -294,6 +310,18 @@ export interface ProjectClient {
   eventStreamUrl(after: number): string;
   /** The project's skills, as SkillCDN serves them at its address, or the organization's. */
   skills(signal?: AbortSignal): Promise<RestSkills>;
+  /** One skill of the pack, a page of it (`load_skill`), read by the console with the pack token the project holds (ADR-0028). */
+  skill(path: string, cursor?: string, signal?: AbortSignal): Promise<RestSkillLoad>;
+  /** A file of the pack, a page of it, or what a folder holds (`read_repo_file`). */
+  skillFile(
+    path: string,
+    page?: { readonly offset?: number | undefined; readonly limit?: number | undefined },
+    signal?: AbortSignal,
+  ): Promise<RestSkillFile>;
+  /** Sets the pack token the project reads a private pack with; for an owner. The token travels once and is answered never. */
+  setPackToken(input: RestPackTokenInput): Promise<RestProject>;
+  /** Takes the pack token away; for an owner. */
+  removePackToken(): Promise<RestProject>;
   /** The rules that hold in the project (ADR-0023): the workspace's, and what the project adds. */
   rules(signal?: AbortSignal): Promise<RestProjectRules>;
   /** A folder's pages and folders, or the pages a search finds. */
@@ -553,10 +581,12 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
           "GET",
           withQuery(at("tasks"), {
             state: filter.state,
+            archived: flag(filter.archived),
             open: flag(filter.open),
             category: filter.category,
             goal: filter.goal,
             assignee: filter.assignee,
+            unassigned: flag(filter.unassigned),
             dueBy: filter.dueBy,
             limit: number(filter.limit),
             offset: number(filter.offset),
@@ -570,6 +600,12 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
       createTask: (input) => request("POST", `${base}${at("tasks")}`, input, restTaskSchema),
       updateTask: (id, patch) =>
         request("PATCH", `${base}${at("tasks", id)}`, patch, restTaskSchema),
+      archiveTask: (id) =>
+        request("POST", `${base}${at("tasks", id)}/archive`, undefined, restTaskSchema),
+      restoreTask: (id) =>
+        request("POST", `${base}${at("tasks", id)}/restore`, undefined, restTaskSchema),
+      archiveTasksOfGoal: (goalId) =>
+        request("POST", `${base}${at("tasks")}/archive`, { goalId }, restArchivedTasksSchema),
       decisions: (filter = {}, signal) =>
         request(
           "GET",
@@ -658,6 +694,30 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
       eventStreamUrl: (after) => withQuery(`${at("events")}/stream`, { after: String(after) }),
       skills: (signal) =>
         request("GET", `${base}${at("skills")}`, undefined, restSkillsSchema, signal),
+      skill: (path, cursor, signal) =>
+        request(
+          "GET",
+          withQuery(`${at("skills")}/one`, { path, cursor }),
+          undefined,
+          restSkillLoadSchema,
+          signal,
+        ),
+      skillFile: (path, page = {}, signal) =>
+        request(
+          "GET",
+          withQuery(`${at("skills")}/file`, {
+            path,
+            offset: page.offset === undefined ? undefined : String(page.offset),
+            limit: page.limit === undefined ? undefined : String(page.limit),
+          }),
+          undefined,
+          restSkillFileSchema,
+          signal,
+        ),
+      setPackToken: (input) =>
+        request("PUT", `${base}${at()}/pack-token`, input, restProjectSchema),
+      removePackToken: () =>
+        request("DELETE", `${base}${at()}/pack-token`, undefined, restProjectSchema),
       rules: (signal) =>
         request("GET", `${base}${at("rules")}`, undefined, restProjectRulesSchema, signal),
       documents: (filter = {}, signal) =>