@skillcdn/console 0.1.14 → 0.1.16

package/src/cli/help.ts

@@ -20,6 +20,7 @@ import {
   MAX_PROJECT_SYMBOL_LENGTH,
   MAX_QUESTION_LENGTH,
   MAX_REPORTS_PER_RUN,
+  MAX_RULES_LENGTH,
   MAX_SUMMARY_LENGTH,
   MAX_TITLE_LENGTH,
   MAX_VERSIONS_PER_DOCUMENT,
@@ -83,7 +84,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   login: {
     usage: "login --url <origin> [--agent <name>] [--token-stdin]",
     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. --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, 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.",
     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",
@@ -92,7 +93,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   logout: {
     usage: "logout",
     about:
-      "Forgets the address and the token kept here. The token itself is removed on the Agents page.",
+      "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.",
   },
   whoami: {
     usage: "whoami",
@@ -111,9 +112,9 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     refusals: ["project.not_found: no project has the key, or it is not yours to see"],
   },
   work: {
-    usage: "work",
+    usage: "work [--person <login>]",
     about:
-      "What is on your plate across the projects you may see: the open tasks assigned to you, the sooner due first, each with its project; and the decisions waiting for a person. Needs no project.",
+      "What is on your plate across the projects you may see: the open tasks assigned to you, the sooner due first, each with its project; and the decisions waiting for a person. Needs no project. --person <login> shows another person's plate, for an administrator or for an owner of a project they are in: their open tasks within the projects you may see, without the decisions, which wait for anyone.",
   },
   tasks: {
     usage:
@@ -125,7 +126,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     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 and the runs on it; 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).",
     limits: [
-      `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
+      `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,
     ],
@@ -159,15 +160,19 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   people: {
     usage: "people",
     about:
-      "Everyone of the workspace, by login, with their name where the host gives one and what they are in it: admin, who configures the workspace, or member, who works in the projects they are in. The logins are what --assignee, member and person role take.",
+      "Everyone of the workspace, by login, with their name where the host gives one and what they are in it: admin, who configures the workspace, or member, who works in the projects they are in; a person taken out is marked deactivated. Then the logins an administrator let in that nobody has signed in with yet. The logins are what --assignee, member and person take.",
   },
   person: {
-    usage: "person role <login> <admin|member>",
+    usage:
+      "person role <login> <admin|member>  |  person add <login> [--host gh|google]  |  person remove <login>  |  person deactivate <login>  |  person reactivate <login>",
     about:
-      "Says what a person is in the workspace, for an administrator: the person themselves on the People page, or their agent here, named on it. The board keeps at least one administrator.",
+      "For an administrator: the person themselves on the People page, or their agent here, named on it. role says what a person is in the workspace; the board keeps at least one administrator in. add lets a login in: whoever signs in with that account at that host is a person from then on; the host is read off the login (an address is Google's, anything else GitHub's) unless --host says. remove takes a login away that nobody has signed in with yet. deactivate takes a person out: refused on every request at once, their agents with them, kept with everything they did, and listed nowhere; reactivate takes them back in. A person the organization let in comes and goes with it, and is neither.",
     refusals: [
-      "auth.forbidden: only an administrator says what a person is",
-      "person.last_admin: the board keeps at least one administrator; make another one first",
+      "auth.forbidden: only an administrator says who is in and what they are",
+      "person.last_admin: the board keeps at least one administrator in; make another one first",
+      "person.of_organization: the organization says whether that person is in",
+      "listing.exists: the login is let in already, or is a person's who is in",
+      "listing.unknown_host: nobody signs in through that provider here",
     ],
   },
   project: {
@@ -228,7 +233,20 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   skills: {
     usage: "skills",
     about:
-      "The organization's skills, as SkillCDN serves them at the console's address: each with its description and the URI you load it by through your own SkillCDN connection. --json adds the page of each, for a person.",
+      "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.",
+  },
+  rules: {
+    usage:
+      "rules  |  rules write --body <markdown>|--file <path>|-|none [--workspace] [--base <version>]",
+    about:
+      "What this organization asks of agents (ADR-0023): the workspace's rules, the console's own until an administrator writes the organization's, and this project's own when it has them. Read them before taking a task; take prints them again. rules write writes this project's rules, for an owner, or with --workspace the workspace's, for an administrator; none puts the written rules away, so that the console's own hold again, or the project adds none. Without a project named, rules shows the workspace's alone.",
+    limits: [
+      `body: Markdown, up to ${MAX_RULES_LENGTH} characters; the console's own rules, written as they are, write nothing`,
+    ],
+    refusals: [
+      "auth.forbidden: an owner writes a project's rules, an administrator the workspace's",
+      "document.conflict: the rules have moved on since --base; read them again",
+    ],
   },
   take: {
     usage: "take <number|id> [--agent <name>]",
@@ -384,6 +402,7 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
 const preamble = (version: string | undefined): string =>
   `console${version === undefined ? "" : ` ${version}`}: the board of your organization's work with AI agents, from the command line.
 You act as the person whose token you hold; everything you send is shown to people as text.
+The rules of this organization come with the task: console take prints them; console rules reads them any time.
 
 Usage: console <command> [arguments] [--json] [--url <origin>] [--project <key>]
 `;
@@ -425,6 +444,7 @@ const SECTIONS: readonly { readonly title: string; readonly commands: readonly s
       "runs",
       "run",
       "skills",
+      "rules",
     ],
   },
   { title: "Working", commands: ["take", "report", "hand-in", "ask", "finish", "fail", "abandon"] },

package/src/cli/main.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
+import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { hostname } from "node:os";
 import process from "node:process";
+import { fileURLToPath } from "node:url";
 import * as z from "zod/mini";
 import { runCli } from "./cli.js";
 import { createFileStore, defaultConfigDir } from "./credentials.js";
@@ -16,6 +18,8 @@ import { readBytesAt, readFileAt, readStdin } from "./terminal.js";
 const manifest = z
   .object({ version: z.string() })
   .safeParse(createRequire(import.meta.url)("../../package.json"));
+/** The console's own skills, shipped with the package beside dist/ (ADR-0015); not there in a checkout before packing. */
+const skillsDir = fileURLToPath(new URL("../../skills/", import.meta.url));
 
 process.exitCode = await runCli(process.argv.slice(2), {
   env: process.env,
@@ -35,5 +39,6 @@ process.exitCode = await runCli(process.argv.slice(2), {
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
   now: () => Date.now(),
   version: manifest.success ? manifest.data.version : undefined,
+  skillsDir: existsSync(skillsDir) ? skillsDir : undefined,
   listen: listenOn,
 });

package/src/client.ts

@@ -4,9 +4,11 @@ import {
   categoryPath,
   connectPath,
   personTokensPath,
+  personWorkPath,
   projectPath,
   REST_ROUTES,
   restPath,
+  rulesPath,
 } from "./routes.js";
 import {
   type RestAnswerInput,
@@ -31,6 +33,8 @@ import {
   type RestGoalInput,
   type RestGoalPatch,
   type RestGoals,
+  type RestListing,
+  type RestListingInput,
   type RestMe,
   type RestMember,
   type RestMemberInput,
@@ -40,11 +44,15 @@ import {
   type RestPeople,
   type RestPerson,
   type RestPersonPatch,
+  type RestPersonWork,
   type RestProject,
   type RestProjectInput,
   type RestProjectPatch,
+  type RestProjectRules,
   type RestProjects,
   type RestReportInput,
+  type RestRules,
+  type RestRulesInput,
   type RestRun,
   type RestRunEndInput,
   type RestRunInput,
@@ -73,13 +81,17 @@ import {
   restEventsSchema,
   restGoalSchema,
   restGoalsSchema,
+  restListingSchema,
   restMemberSchema,
   restMembersSchema,
   restMeSchema,
   restPeopleSchema,
   restPersonSchema,
+  restPersonWorkSchema,
+  restProjectRulesSchema,
   restProjectSchema,
   restProjectsSchema,
+  restRulesSchema,
   restRunSchema,
   restRunsSchema,
   restSkillsSchema,
@@ -243,6 +255,8 @@ 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>;
+  /** 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. */
   documents(filter?: DocumentFilter, signal?: AbortSignal): Promise<RestDocuments>;
   /** One document, by its path: its latest version, its links both ways, its files. */
@@ -271,11 +285,17 @@ export interface ProjectClient {
 
 export interface ConsoleClient {
   me(signal?: AbortSignal): Promise<RestMe>;
+  /** Gives up the token this client acts with, so that it is good for nothing from now on: what `console logout` does. For a token; a session has none. */
+  giveUpToken(): Promise<void>;
   /** Keeps the person's choice of language, or none; for a person signed in. */
   updateMe(patch: RestMePatch): Promise<RestMe>;
   people(signal?: AbortSignal): Promise<RestPeople>;
-  /** Changes what a person is; for an administrator. */
+  /** Changes what a person is, or whether they are in; for an administrator. */
   updatePerson(id: string, patch: RestPersonPatch): Promise<RestPerson>;
+  /** Lets a login in (ADR-0022): whoever signs in with that account becomes a person; for an administrator. */
+  createListing(input: RestListingInput): Promise<RestListing>;
+  /** Takes a listing away before anyone signed in with it; for an administrator. */
+  removeListing(id: string): Promise<void>;
   /** The projects the asker may see, with what they are in each. */
   projects(signal?: AbortSignal): Promise<RestProjects>;
   /** Makes a project, whose owner the asker becomes. */
@@ -286,6 +306,14 @@ export interface ConsoleClient {
   events(after: number, signal?: AbortSignal): Promise<RestEvents>;
   /** The categories tasks are sorted into (ADR-0019), by name. */
   categories(signal?: AbortSignal): Promise<RestCategories>;
+  /** The workspace's rules (ADR-0023): the console's own until an administrator writes the organization's. */
+  rules(signal?: AbortSignal): Promise<RestRules>;
+  /** Writes the organization's rules; for an administrator. The console's own, sent as they are, write nothing. */
+  writeRules(input: RestRulesInput): Promise<RestRules>;
+  /** Puts the organization's rules away, so that the console's own hold again; for an administrator. */
+  archiveRules(): Promise<RestRules>;
+  /** The versions of the organization's rules, newest first; none while the console's own hold. */
+  rulesVersions(signal?: AbortSignal): Promise<RestVersions>;
   /** Makes a category; for an administrator signed in. */
   createCategory(input: RestCategoryInput): Promise<RestCategory>;
   updateCategory(key: string, patch: RestCategoryPatch): Promise<RestCategory>;
@@ -293,6 +321,8 @@ export interface ConsoleClient {
   removeCategory(key: string): Promise<void>;
   /** What is on the asker's plate across the projects they may see: their open tasks, and the decisions waiting. */
   work(signal?: AbortSignal): Promise<RestWork>;
+  /** Another person's plate, within what the asker may see: for an administrator, or an owner of a project they are in. */
+  personWork(personId: string, signal?: AbortSignal): Promise<RestPersonWork>;
   /** The tokens of whoever asks. */
   tokens(signal?: AbortSignal): Promise<RestTokens>;
   /** The tokens of another person: for an administrator. */
@@ -520,6 +550,8 @@ 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),
+      rules: (signal) =>
+        request("GET", `${base}${at("rules")}`, undefined, restProjectRulesSchema, signal),
       documents: (filter = {}, signal) =>
         request(
           "GET",
@@ -572,10 +604,15 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
 
   return {
     me: (signal) => request("GET", `${base}${REST_ROUTES.me}`, undefined, restMeSchema, signal),
+    giveUpToken: () => request("DELETE", `${base}${REST_ROUTES.meToken}`, undefined, undefined),
     people: (signal) =>
       request("GET", `${base}${REST_ROUTES.people}`, undefined, restPeopleSchema, signal),
     updatePerson: (id, patch) =>
       request("PATCH", `${base}${restPath("people", id)}`, patch, restPersonSchema),
+    createListing: (input) =>
+      request("POST", `${base}${REST_ROUTES.listings}`, input, restListingSchema),
+    removeListing: (id) =>
+      request("DELETE", `${base}${restPath("listings", id)}`, undefined, undefined),
     projects: (signal) =>
       request("GET", `${base}${REST_ROUTES.projects}`, undefined, restProjectsSchema, signal),
     createProject: (input) =>
@@ -591,6 +628,13 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
       ),
     categories: (signal) =>
       request("GET", `${base}${REST_ROUTES.categories}`, undefined, restCategoriesSchema, signal),
+    rules: (signal) =>
+      request("GET", `${base}${REST_ROUTES.rules}`, undefined, restRulesSchema, signal),
+    writeRules: (input) => request("PUT", `${base}${REST_ROUTES.rules}`, input, restRulesSchema),
+    archiveRules: () =>
+      request("POST", `${base}${rulesPath("archive")}`, undefined, restRulesSchema),
+    rulesVersions: (signal) =>
+      request("GET", `${base}${rulesPath("versions")}`, undefined, restVersionsSchema, signal),
     createCategory: (input) =>
       request("POST", `${base}${REST_ROUTES.categories}`, input, restCategorySchema),
     updateCategory: (key, patch) =>
@@ -598,6 +642,8 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
     removeCategory: (key) => request("DELETE", `${base}${categoryPath(key)}`, undefined, undefined),
     work: (signal) =>
       request("GET", `${base}${REST_ROUTES.work}`, undefined, restWorkSchema, signal),
+    personWork: (personId, signal) =>
+      request("GET", `${base}${personWorkPath(personId)}`, undefined, restPersonWorkSchema, signal),
     tokens: (signal) =>
       request("GET", `${base}${REST_ROUTES.tokens}`, undefined, restTokensSchema, signal),
     createToken: (input) =>