@skillcdn/console 0.1.12 → 0.1.13

package/docs/specs/rest.md

@@ -11,7 +11,7 @@ The API is the board as its members see it: the people, the projects, and in eac
 - Every answer is `cache-control: no-store`: it is one person's, or it changes.
 - A request that changes something (`POST`, `PATCH`, `DELETE`) on a session must carry the session cookie **and** come from the console's own pages: the browser's `origin` header must be `PUBLIC_URL`. The cookie is `SameSite=Lax`, so another site's request does not carry it in the first place; the origin is the second fence.
 - A token ([`POST /api/v1/tokens`](#get-apiv1tokens-and-post-apiv1tokens)) is presented as `Authorization: Bearer <secret>` on any route, by an agent, a script or a console of a person's own. It is then the credential: a cookie beside it is not looked at, and no origin is needed, since nothing attaches a token but whoever holds it. A token that is nothing is refused, whatever cookie travels with it. What a token does is attributed to its person, and the event names the agent: the token's name, or what the agent called itself on its run.
-- Configuring is a person's own doing, signed in on the console's own pages, never with a token: the tokens themselves, roles, projects and their members.
+- A token configures as its person does ([ADR-0021](../adr/0021-a-token-configures-as-its-person-does.md)): every request a session may make, a token may make, within the same roles, except the tokens themselves and the approval of a connection, which stay a person's own doing, signed in on the console's own pages.
 - An agent connects without anyone copying a token ([ADR-0011](../adr/0011-an-agent-connects-with-a-short-code-a-person-approves-and-the-token-is-never-shown.md)): [`POST /api/v1/connect`](#connecting-an-agent) is nobody's, the approval is a person's own doing on the console's own pages, and the claim is the command's, with the secret it was given.
 - Request bodies are JSON, at most 256 KiB, and parsed once with the package's input schema. Text is trimmed where it is a line, bounded everywhere (`MAX_TITLE_LENGTH` and the rest of `@skillcdn/console/api`), and refused when it carries control or invisible characters. Links are `https` URLs only.
 - Errors have `{ "error": { "code": "...", "message": "..." } }`. The code is stable; the message is for a person, in English.
@@ -37,7 +37,7 @@ The API is the board as its members see it: the people, the projects, and in eac
 | 401 | `auth.required` | Nobody is signed in, or the session has ended, or the token is nothing. The cookie is taken away when the operator no longer lists the login. |
 | 403 | `auth.forbidden_origin` | A request that changes something on a session did not come from the console's own pages. |
 | 403 | `auth.forbidden` | A member asked for what only an administrator, or only an owner of the project, may do. |
-| 403 | `auth.session_required` | A token asked for what only a person signed in may do: the tokens themselves, and configuring. |
+| 403 | `auth.session_required` | A token asked for what only a person signed in may do: the tokens themselves, and the approval of an agent's connection, which makes one. |
 | 403 | `run.not_yours` | The run is another person's. |
 | 404 | `project.not_found` | No project has that key, or it is not the asker's to see: the two are one answer. The key is checked before anything is asked. |
 | 404 | `task.not_found`, `decision.not_found`, `goal.not_found`, `token.not_found`, `person.not_found`, `run.not_found`, `run.task_not_found`, `member.not_found` | No such id in the project (or in the workspace, for a token, a person); for a token, none of the asker's. An id that is not a UUID is not found either, except a task's number. |
@@ -69,11 +69,11 @@ The API is the board as its members see it: the people, the projects, and in eac
 
 ### `GET /api/v1/people`
 
-`{ "items": [person, ...] }`: everyone who has signed in and is still listed, by login. What a picker of assignees and of members is made of. A person carries their `role` in the workspace: `admin`, who configures it, or `member`, who works in the projects they are in.
+`{ "items": [person, ...] }`: everyone who has signed in and is still listed, by login. What a picker of assignees and of members is made of. A person carries their `role` in the workspace: `admin`, who configures it, or `member`, who works in the projects they are in. A token reads it as its person does: what the command's `--assignee`, `member` and `person role` take a login from.
 
 ### `PATCH /api/v1/people/<id>`
 
-Takes `role` and answers the person. For an administrator signed in on the console's own pages, never with a token: an agent works as its person does, and configuring is a person's own doing. The board keeps at least one administrator (`person.last_admin`). A change writes a `person.role_changed` event with `login` and `role`; a change to what is already so writes nothing.
+Takes `role` and answers the person. For an administrator, signed in or through their agent's token ([ADR-0021](../adr/0021-a-token-configures-as-its-person-does.md)). The board keeps at least one administrator (`person.last_admin`). A change writes a `person.role_changed` event with `login` and `role`; a change to what is already so writes nothing.
 
 ### `GET /api/v1/projects`
 
@@ -81,7 +81,7 @@ Takes `role` and answers the person. For an administrator signed in on the conso
 
 ### `POST /api/v1/projects`
 
-Takes `key` and `name`, and optionally `description`, `visibility` (default `private`), `skillsAddress` (checked as the standard spells one, kept canonical; `project.invalid_address`), `color` and `symbol`. For whoever is signed in on the console's own pages, never with a token; they become the project's owner. Answers `201` with the project and writes a `project.created` event in it, with `key` and `name`. A key taken is `project.key_taken`.
+Takes `key` and `name`, and optionally `description`, `visibility` (default `private`), `skillsAddress` (checked as the standard spells one, kept canonical; `project.invalid_address`), `color` and `symbol`. For whoever is signed in, or their agent with their token; they become the project's owner. Answers `201` with the project and writes a `project.created` event in it, with `key` and `name`. A key taken is `project.key_taken`.
 
 ### `GET /api/v1/events?after=&limit=`
 
@@ -89,7 +89,7 @@ The workspace's own events, the ones about no project: who joined (`person.joine
 
 ### `PATCH /api/v1/me`
 
-Keeps the person's own choice of language for the pages ([ADR-0012](../adr/0012-the-pages-speak-the-persons-language-from-packs-that-ship-with-the-package.md)): `{ "language": "ko" }`, a language tag as a browser sends one, or `null` to choose none and let the browser's languages decide; answers what `GET` answers. A person's own doing, from the console's own pages: never with a token.
+Keeps the person's own choice of language for the pages ([ADR-0012](../adr/0012-the-pages-speak-the-persons-language-from-packs-that-ship-with-the-package.md)): `{ "language": "ko" }`, a language tag as a browser sends one, or `null` to choose none and let the browser's languages decide; answers what `GET` answers. From the console's own pages, or with a token: a console of a person's own keeps the choice on the person too.
 
 ### `GET /api/v1/categories`
 
@@ -97,7 +97,7 @@ Keeps the person's own choice of language for the pages ([ADR-0012](../adr/0012-
 
 ### `POST /api/v1/categories`, `PATCH /api/v1/categories/<key>` and `DELETE /api/v1/categories/<key>`
 
-Kept by an administrator signed in on the console's own pages, never with a token, as the rest of configuring is. `POST` takes `key`, `name` and optionally `color` (default `gray`), answers `201` with the category and writes a `category.created` event in the workspace's own feed with `key` and `name`; a key taken is `category.key_taken`, and the workspace holds at most `MAX_CATEGORIES` (`category.too_many`). `PATCH` takes any of `name` and `color`, answers the category and writes `category.updated` naming the `fields`; what is already so writes nothing; the key does not change. `DELETE` answers `204` and writes `category.removed`; a category tasks are sorted into is `category.in_use` until they are moved out of it.
+Kept by an administrator, signed in or through their agent's token. `POST` takes `key`, `name` and optionally `color` (default `gray`), answers `201` with the category and writes a `category.created` event in the workspace's own feed with `key` and `name`; a key taken is `category.key_taken`, and the workspace holds at most `MAX_CATEGORIES` (`category.too_many`). `PATCH` takes any of `name` and `color`, answers the category and writes `category.updated` naming the `fields`; what is already so writes nothing; the key does not change. `DELETE` answers `204` and writes `category.removed`; a category tasks are sorted into is `category.in_use` until they are moved out of it.
 
 ### `GET /api/v1/work`
 
@@ -119,7 +119,7 @@ An administrator's sight of everyone's agents ([ADR-0011](../adr/0011-an-agent-c
 
 `POST /api/v1/connect`, `GET /api/v1/connect/<code>`, `POST /api/v1/connect/<code>/approve`, `POST /api/v1/connect/<code>/deny` and `POST /api/v1/connect/claim`: how an agent gets its token without anyone copying one ([ADR-0011](../adr/0011-an-agent-connects-with-a-short-code-a-person-approves-and-the-token-is-never-shown.md)).
 
-`POST /api/v1/connect` is nobody's: the command sends `{ "agent" }` (what the agent calls itself and where it runs, a line up to `MAX_TOKEN_NAME_LENGTH`) and is answered `201` with `{ "code", "url", "secret", "expiresAt", "interval" }`: a code of eight characters in two groups (`ABCD-EFGH`, from an alphabet without look-alikes) for a person to approve, the console's own page for it, a secret (`cns_c_...`) the command claims with and shows nowhere, when the request expires (ten minutes after it began), and how many seconds the command waits between claims. A deployment holds a bounded number of requests at once (`connect.too_many`).
+`POST /api/v1/connect` is nobody's: the command sends `{ "agent" }` (what the agent calls itself and where it runs, a line up to `MAX_TOKEN_NAME_LENGTH`) and is answered `201` with `{ "code", "url", "secret", "expiresAt", "interval" }`: a code of eight characters in two groups (`ABCD-EFGH`, from an alphabet without look-alikes) for a person to approve, the console's own page for it, a secret (`cns_c_...`) the command claims with and shows nowhere, when the request expires (thirty minutes after it began), and how many seconds the command waits between claims. A deployment holds a bounded number of requests at once (`connect.too_many`).
 
 `GET /api/v1/connect/<code>`, for a person signed in, answers what asks: `{ "code", "agent", "createdAt", "expiresAt", "approved" }`. A code is read as a person types it: any case, with or without the hyphen. `POST .../approve`, from the console's own pages, takes what `POST /api/v1/tokens` takes (`name`, `expiresInDays`) and answers the request, approved; `POST .../deny` takes the request away and answers `204`.
 
@@ -131,19 +131,19 @@ Everything below is under `/api/v1/projects/<key>`, for whoever may see the proj
 
 ### `GET /api/v1/projects/<key>` and `PATCH /api/v1/projects/<key>`
 
-The project, as the asker sees it. A patch, for an owner signed in, takes any of `name`, `description`, `visibility`, `skillsAddress` (`null` for the organization's), `color` and `symbol` (`null` for none), and writes a `project.updated` event naming the `fields`; what is already so writes nothing. The key does not change.
+The project, as the asker sees it. A patch, for an owner, signed in or with a token, takes any of `name`, `description`, `visibility`, `skillsAddress` (`null` for the organization's), `color` and `symbol` (`null` for none), and writes a `project.updated` event naming the `fields`; what is already so writes nothing. The key does not change.
 
 ### `POST /api/v1/projects/<key>/icon`, `DELETE .../icon` and `GET .../icon`
 
-The project's own image for its mark, in place of the symbol on the colour. `POST`, for an owner signed in on the console's own pages, takes a form with a part called `file`: a PNG, a JPEG, a GIF or a WebP of at most `MAX_PROJECT_ICON_BYTES`, known by its first bytes and never by what the form says of it (`project.invalid_icon`; `request.too_large`). The bytes are kept by their hash, the project is answered with its `icon`, and the board hears `project.updated` with `fields: ["icon"]`; the same image again writes nothing. `DELETE` takes the image away and answers the project. `GET`, for whoever may see the project, answers the bytes with their type, the hash as `ETag` and `Cache-Control: private, max-age=86400`, or `304` to a matching `If-None-Match`; a project without an image is `project.no_icon`. The pages read it at `projectIconPath(key, icon)`, which carries the hash as a version.
+The project's own image for its mark, in place of the symbol on the colour. `POST`, for an owner, takes a form with a part called `file`: a PNG, a JPEG, a GIF or a WebP of at most `MAX_PROJECT_ICON_BYTES`, known by its first bytes and never by what the form says of it (`project.invalid_icon`; `request.too_large`). The bytes are kept by their hash, the project is answered with its `icon`, and the board hears `project.updated` with `fields: ["icon"]`; the same image again writes nothing. `DELETE` takes the image away and answers the project. `GET`, for whoever may see the project, answers the bytes with their type, the hash as `ETag` and `Cache-Control: private, max-age=86400`, or `304` to a matching `If-None-Match`; a project without an image is `project.no_icon`. The pages read it at `projectIconPath(key, icon)`, which carries the hash as a version.
 
 ### `GET /api/v1/projects/<key>/members` and `POST /api/v1/projects/<key>/members`
 
-`{ "items": [member, ...] }`: those listed in the project, by login, each a `person`, their `role` in it (`owner`, `member`) and `addedAt`. A project open to the workspace has everyone of it as a member besides; an administrator is an owner of every project, listed or not. `POST`, for an owner signed in, takes `personId` (a person of the workspace; `member.invalid_person`) and optionally `role` (default `member`), answers `201` with the member and writes `project.member_added` with `login` and `role`. A person listed already is `member.exists`.
+`{ "items": [member, ...] }`: those listed in the project, by login, each a `person`, their `role` in it (`owner`, `member`) and `addedAt`. A project open to the workspace has everyone of it as a member besides; an administrator is an owner of every project, listed or not. `POST`, for an owner, takes `personId` (a person of the workspace; `member.invalid_person`) and optionally `role` (default `member`), answers `201` with the member and writes `project.member_added` with `login` and `role`. A person listed already is `member.exists`.
 
 ### `PATCH /api/v1/projects/<key>/members/<person id>` and `DELETE .../members/<person id>`
 
-For an owner signed in. The patch takes `role` and writes `project.member_changed`; the removal answers `204` and writes `project.member_removed`. A person not listed is `member.not_found`. A project may be left without an owner listed; the administrators own it then.
+For an owner, signed in or with a token. The patch takes `role` and writes `project.member_changed`; the removal answers `204` and writes `project.member_removed`. A person not listed is `member.not_found`. A project may be left without an owner listed; the administrators own it then.
 
 ### `GET /api/v1/projects/<key>/tasks?state=&open=&category=&goal=&assignee=&dueBy=&limit=&offset=`
 
@@ -203,7 +203,7 @@ The bytes are read back at `/api/v1/projects/<key>/files/<artifact id>` by whoev
 
 ### `POST .../runs/<id>/end`
 
-Takes `status` (`finished`, `failed` or `abandoned`) and optionally a `summary` (Markdown, `MAX_SUMMARY_LENGTH`: what was done and what is left), ends the run (`run.ended`), and answers it. A finished run puts a task that was `in_progress` up for review (`in_review`); the rest leave the task as it is. The run's person ends it, as `finished` or `failed` from their agent; `abandoned` is a person giving up on a run that will not come back: their own, or anyone's as an owner of the project signed in on the console's own pages, never with a token (`run.not_yours`). A run that is over is `run.over`.
+Takes `status` (`finished`, `failed` or `abandoned`) and optionally a `summary` (Markdown, `MAX_SUMMARY_LENGTH`: what was done and what is left), ends the run (`run.ended`), and answers it. A finished run puts a task that was `in_progress` up for review (`in_review`); the rest leave the task as it is. The run's person ends it, as `finished` or `failed` from their agent; `abandoned` is a person giving up on a run that will not come back: their own, or anyone's as an owner of the project, signed in or through their agent (`run.not_yours` otherwise). A run that is over is `run.over`.
 
 ### `GET /api/v1/projects/<key>/skills`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillcdn/console",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "What a custom SkillCDN console is built from: the API client and schemas, the components, the composition of the default console, and the console command agents work the board with.",
   "license": "MIT",
   "homepage": "https://github.com/skillcdn/console#readme",

package/skills/building-a-console/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: A shell with Node.js 24 or newer and npm or pnpm, and an agent that reads and writes files. For looking at the pages against a board, the console command signed in by a person. A browser the agent can drive is optional. No key of the agent's own is needed, and it never sees a token.
 metadata:
   author: skillcdn
-  version: "1.2"
+  version: "1.3"
 skillcdn:
   translations:
     ko:
@@ -74,7 +74,7 @@ Produces the **pages**. For a page the default console lacks: `useConsoleData(cl
 
 ### Phase 4: Run it against the board
 
-Produces the **running console**. `console serve` serves the API at `http://127.0.0.1:11197/api/` while `npx vite` serves the pages, and `console serve dist` serves the build whole at `http://127.0.0.1:11197/`. The pages hold no token; the command carries it, on the loopback only. The pages know they hold a token (`GET /api/v1/me` answers `agent`) and offer nothing a token cannot do: the tokens themselves and configuring stay on the organization's console. The organization's console is looked at the same way, on the builder's token: it shows every page a token may see, and the pages a token may not (the agents, the settings) are the package's own and unchanged, so the look checkpoint covers everything the console changed. Where the organization's build then goes is the plan's answer: `console-ui/` of the deployment repository, whose workflow builds it into the image on every push, handed over to deploying-a-console, the skill beside this one at the same address (in the package under `node_modules/@skillcdn/console/skills/deploying-a-console/`), with the source and the repository, and with the package pinned at the version of the release the deployment pins as `CONSOLE_REF` (the tag `@skillcdn/console@<version>`), so that the pages and the server are one release and move together; the build beside the Dockerfile of [deploy/README.md](/deploy/README.md) "A custom console in the image", for an image the organization builds itself; or the mounted directory. A script: `createClient({ baseUrl, token })`, every answer parsed with the package's schemas.
+Produces the **running console**. `console serve` serves the API at `http://127.0.0.1:11197/api/` while `npx vite` serves the pages, and `console serve dist` serves the build whole at `http://127.0.0.1:11197/`. The pages hold no token; the command carries it, on the loopback only. The pages know they hold a token (`GET /api/v1/me` answers `agent`) and offer nothing a token cannot do: the tokens themselves stay on the organization's console, and everything else, configuring included, the pages do on the token as the person ([ADR-0021](/docs/adr/0021-a-token-configures-as-its-person-does.md)). The organization's console is looked at the same way, on the builder's token: it shows every page a token may see, and the pages a token may not (the agents) are the package's own and unchanged, so the look checkpoint covers everything the console changed. Where the organization's build then goes is the plan's answer: `console-ui/` of the deployment repository, whose workflow builds it into the image on every push, handed over to deploying-a-console, the skill beside this one at the same address (in the package under `node_modules/@skillcdn/console/skills/deploying-a-console/`), with the source and the repository, and with the package pinned at the version of the release the deployment pins as `CONSOLE_REF` (the tag `@skillcdn/console@<version>`), so that the pages and the server are one release and move together; the build beside the Dockerfile of [deploy/README.md](/deploy/README.md) "A custom console in the image", for an image the organization builds itself; or the mounted directory. A script: `createClient({ baseUrl, token })`, every answer parsed with the package's schemas; it configures as its person does too, with `createProject`, `updatePerson`, a project's `update`, `setIcon`, `addMember`, `updateMember` and `removeMember`, and `createCategory`, `updateCategory` and `removeCategory`, refused with `auth.forbidden` where the person may not, and never the tokens.
 
 ### Phase 5: Check and show
 

package/skills/working-the-board/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Needs a shell with the console command on the PATH (npm install -g @skillcdn/console, Node.js 24 or newer), signed in by a person. Nothing else; the command needs no key of its own and the agent never sees a token.
 metadata:
   author: skillcdn
-  version: "1.2"
+  version: "1.3"
 skillcdn:
   translations:
     ko:
@@ -73,6 +73,10 @@ What was learned and will be needed again (how a thing is set up, why a choice w
 
 After the last report, `console finish --summary "<what was done, and what is left>"`: the task goes up for review. `console fail --summary "<why, and what is left>"` when it could not be done. A run is never left open.
 
+## Setting up, when told to
+
+A task or a person may ask for the project itself rather than work in it: a project made or changed (`console project new <key> "<name>"`, `console project edit <key>`), its mark (`console project icon <key> <file>`), its members (`console member add <login>`, `console member role`, `console member remove`), the workspace's categories (`console category new <key> "<name>"`, `console category edit`, `console category remove`), what a person is (`console person role <login> <admin|member>`), and its goals (`console goal new`). The agent does these as its person may, an owner of the project or an administrator of the workspace ([ADR-0021](/docs/adr/0021-a-token-configures-as-its-person-does.md)); the feed names the agent beside the person on each. What the person may not, the console refuses (`auth.forbidden`): that step goes back to the person in the report, never worked around. `console people` and `console members` say who is who, by login.
+
 ## Hard rules
 
 - Never look for, read, print or send a token. The rules of the repository say the rest.

package/src/cli/cli.ts

@@ -9,10 +9,18 @@ import {
 } from "../client.js";
 import { addDays, dayOf as dayOfDate, isDay } from "../dates.js";
 import { DEFAULT_PAGE_LIMIT, LIST_LIMIT, MAX_OPTIONS, MIN_OPTIONS } from "../limits.js";
-import type { RestClaim, RestDecision, RestTaskPatch } from "../schemas.js";
+import type { RestClaim, RestDecision, RestPerson, RestTaskPatch } from "../schemas.js";
 import {
+  COLOR_NAMES,
+  type ColorName,
   GOAL_STATES,
   type GoalState,
+  PERSON_ROLES,
+  type PersonRole,
+  PROJECT_ROLES,
+  PROJECT_VISIBILITIES,
+  type ProjectRole,
+  type ProjectVisibility,
   TASK_PRIORITIES,
   TASK_STATES,
   type TaskPriority,
@@ -30,8 +38,11 @@ import {
   formatDocuments,
   formatGoal,
   formatGoalLine,
+  formatMemberLine,
   formatMore,
   formatOptions,
+  formatPersonLine,
+  formatProject,
   formatProjectLine,
   formatRun,
   formatRunLine,
@@ -331,16 +342,41 @@ async function personIdOf(
     }
     return me.person.id;
   }
+  return (await personOf(session, value)).id;
+}
+
+/** The person a login names, among the workspace's; the logins are as people sign in. */
+async function personOf(session: Session, login: string): Promise<RestPerson> {
   const { items } = await session.client.people();
-  const found = items.find((person) => person.login.toLowerCase() === value.toLowerCase());
+  const found = items.find((person) => person.login.toLowerCase() === login.toLowerCase());
   if (found === undefined) {
     throw misuse(
-      `Nobody of the workspace is called ${value}. console people is not a command; the logins are as people sign in.`,
+      `Nobody of the workspace is called ${login}. console people lists everyone, by login.`,
     );
   }
-  return found.id;
+  return found;
+}
+
+/** One word of a vocabulary, or the refusal to understand. */
+function wordOf<T extends string>(value: string, words: readonly T[], what: string): T {
+  const found = words.find((word) => word === value);
+  if (found === undefined) {
+    throw misuse(`Not ${what}: ${value}. One of ${words.join(", ")}`);
+  }
+  return found;
 }
 
+const personRoleOf = (value: string): PersonRole =>
+  wordOf(value, PERSON_ROLES, "a role in the workspace");
+const projectRoleOf = (value: string): ProjectRole =>
+  wordOf(value, PROJECT_ROLES, "a role in a project");
+const visibilityOf = (value: string): ProjectVisibility =>
+  wordOf(value, PROJECT_VISIBILITIES, "a visibility");
+const colorOf = (value: string): ColorName => wordOf(value, COLOR_NAMES, "a colour");
+/** A colour, or `none` for the one the pages choose, which is `null` on the wire. */
+const colorOrNoneOf = (value: string | undefined): ColorName | null | undefined =>
+  value === undefined ? undefined : value === "none" ? null : colorOf(value);
+
 function secondsOf(value: string | undefined, fallback: number): number {
   if (value === undefined) {
     return fallback;
@@ -381,6 +417,15 @@ function theOne(positionals: readonly string[], ask: string): string {
   return first;
 }
 
+/** Exactly two words, for a command on a thing and a value. */
+function theTwo(positionals: readonly string[], ask: string): readonly [string, string] {
+  const [first, second] = positionals;
+  if (first === undefined || second === undefined || positionals.length > 2) {
+    throw misuse(ask);
+  }
+  return [first, second];
+}
+
 /**
  * The decision once answered, or as it stands when the wait is over. Each request asks the
  * console to hold it for a while, so the answer arrives as soon as a person gives it.
@@ -535,7 +580,7 @@ const projects: Command = async (args, io) => {
   const found = await session.client.projects();
   answer(io, session, found, () =>
     found.items.length === 0
-      ? "No projects you may work in. A person makes one on the console's Projects page."
+      ? 'No projects you may work in. Make one: console project new <key> "<name>"'
       : found.items.map(formatProjectLine).join("\n"),
   );
   return EXIT.ok;
@@ -1349,6 +1394,263 @@ const serve: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+// Configuring, as the person (ADR-0021): what an administrator or an owner does on the pages,
+// their agent does here, attributed to them as the agent. The console decides on every request
+// with the same roles; what the person may not, the agent may not (auth.forbidden). The tokens
+// themselves have no command, by design.
+
+const people: Command = async (args, io) => {
+  const { values } = parse(args, {}, false);
+  const session = await open(io, values);
+  const found = await session.client.people();
+  answer(io, session, found, () => found.items.map(formatPersonLine).join("\n"));
+  return EXIT.ok;
+};
+
+const person: Command = async (args, io) => {
+  if (args[0] !== "role") {
+    throw misuse("Say what to do: console person role <login> <admin|member>");
+  }
+  const { values, positionals } = parse(args.slice(1), {});
+  const [login, role] = theTwo(
+    positionals,
+    "Say whom and what: console person role <login> <admin|member>",
+  );
+  const wanted = personRoleOf(role);
+  const session = await open(io, values);
+  const found = await personOf(session, login);
+  const changed = await session.client.updatePerson(found.id, { role: wanted });
+  answer(io, session, changed, () => formatPersonLine(changed));
+  return EXIT.ok;
+};
+
+/** The flags that set what a project is, shared by making one and changing one. */
+const PROJECT_FIELDS: OptionSpec = {
+  description: { type: "string" },
+  file: { type: "string" },
+  visibility: { type: "string" },
+  skills: { type: "string" },
+  color: { type: "string" },
+  symbol: { type: "string" },
+};
+
+/** What the flags say of a project; `none` clears what may be cleared. */
+async function projectFieldsOf(io: CliIo, values: Values) {
+  const description = await bodyOf(io, values, text(values, "description"));
+  const visibility = text(values, "visibility");
+  const skills = orNone(text(values, "skills"));
+  const color = colorOrNoneOf(text(values, "color"));
+  const symbol = orNone(text(values, "symbol"));
+  return {
+    ...(description === undefined
+      ? {}
+      : { description: description === "none" ? "" : description }),
+    ...(visibility === undefined ? {} : { visibility: visibilityOf(visibility) }),
+    ...(skills === undefined ? {} : { skillsAddress: skills }),
+    ...(color === undefined ? {} : { color }),
+    ...(symbol === undefined ? {} : { symbol }),
+  };
+}
+
+const newProject: Command = async (args, io) => {
+  const { values, positionals } = parse(args, PROJECT_FIELDS);
+  const [key, name] = theTwo(
+    positionals,
+    'Say the key and the name: console project new <key> "<name>" [--visibility workspace|private]',
+  );
+  const fields = await projectFieldsOf(io, values);
+  const session = await open(io, values);
+  const made = await session.client.createProject({ key, name, ...fields });
+  answer(
+    io,
+    session,
+    made,
+    () =>
+      `Project made: ${made.name} (${made.key}), with you as its owner.\nTo work in it from this directory: console use ${made.key}`,
+  );
+  return EXIT.ok;
+};
+
+const editProject: Command = async (args, io) => {
+  const { values, positionals } = parse(args, { ...PROJECT_FIELDS, name: { type: "string" } });
+  const key = theOne(
+    positionals,
+    "Say which project: console project edit <key> --name <name> ...",
+  );
+  const name = text(values, "name");
+  const patch = { ...(name === undefined ? {} : { name }), ...(await projectFieldsOf(io, values)) };
+  if (Object.keys(patch).length === 0) {
+    throw misuse(
+      "Say what to change: --name, --description, --visibility, --skills, --color or --symbol; none clears the description, the skills address, the colour or the symbol.",
+    );
+  }
+  const session = await open(io, values);
+  const changed = await session.client.project(key).update(patch);
+  answer(io, session, changed, () => formatProject(changed));
+  return EXIT.ok;
+};
+
+const projectIcon: Command = async (args, io) => {
+  const { values, positionals } = parse(args, { remove: { type: "boolean" } });
+  const [key, file] = positionals;
+  const removing = on(values, "remove");
+  if (key === undefined || positionals.length > 2 || (file === undefined) !== removing) {
+    throw misuse(
+      "Say which project and which image: console project icon <key> <file>, or console project icon <key> --remove",
+    );
+  }
+  const session = await open(io, values);
+  const project = session.client.project(key);
+  const changed =
+    file === undefined
+      ? await project.removeIcon()
+      : await project.setIcon({
+          name: basename(file),
+          bytes: await io.readBytes(file),
+          contentType: CONTENT_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream",
+        });
+  answer(io, session, changed, () => formatProject(changed));
+  return EXIT.ok;
+};
+
+const project: Command = async (args, io) => {
+  if (args[0] === "new") {
+    return newProject(args.slice(1), io);
+  }
+  if (args[0] === "edit") {
+    return editProject(args.slice(1), io);
+  }
+  if (args[0] === "icon") {
+    return projectIcon(args.slice(1), io);
+  }
+  const { values, positionals } = parse(args, {});
+  const key = theOne(
+    positionals,
+    "Say which project: console project <key>; or console project new, edit or icon",
+  );
+  const session = await open(io, values);
+  const found = await session.client.project(key).get();
+  answer(io, session, found, () => formatProject(found));
+  return EXIT.ok;
+};
+
+const members: Command = async (args, io) => {
+  const { values } = parse(args, {}, false);
+  const session = await open(io, values);
+  const project = await session.project();
+  const found = await project.members();
+  answer(io, session, found, () =>
+    found.items.length === 0
+      ? "Nobody is listed in the project."
+      : found.items.map(formatMemberLine).join("\n"),
+  );
+  return EXIT.ok;
+};
+
+const member: Command = async (args, io) => {
+  const [verb, ...rest] = args;
+  if (verb === "add") {
+    const { values, positionals } = parse(rest, { role: { type: "string" } });
+    const login = theOne(positionals, "Say whom: console member add <login> [--role owner|member]");
+    const role = text(values, "role");
+    const session = await open(io, values);
+    const project = await session.project();
+    const added = await project.addMember({
+      personId: (await personOf(session, login)).id,
+      ...(role === undefined ? {} : { role: projectRoleOf(role) }),
+    });
+    answer(io, session, added, () => formatMemberLine(added));
+    return EXIT.ok;
+  }
+  if (verb === "role") {
+    const { values, positionals } = parse(rest, {});
+    const [login, role] = theTwo(
+      positionals,
+      "Say whom and what: console member role <login> <owner|member>",
+    );
+    const wanted = projectRoleOf(role);
+    const session = await open(io, values);
+    const project = await session.project();
+    const changed = await project.updateMember((await personOf(session, login)).id, {
+      role: wanted,
+    });
+    answer(io, session, changed, () => formatMemberLine(changed));
+    return EXIT.ok;
+  }
+  if (verb === "remove") {
+    const { values, positionals } = parse(rest, {});
+    const login = theOne(positionals, "Say whom: console member remove <login>");
+    const session = await open(io, values);
+    const project = await session.project();
+    const found = await personOf(session, login);
+    await project.removeMember(found.id);
+    answer(
+      io,
+      session,
+      { removed: found.login },
+      () => `${found.login} is no longer listed in the project.`,
+    );
+    return EXIT.ok;
+  }
+  throw misuse(
+    "Say what to do: console member add <login> [--role owner|member], console member role <login> <owner|member>, or console member remove <login>",
+  );
+};
+
+const category: Command = async (args, io) => {
+  const [verb, ...rest] = args;
+  if (verb === "new") {
+    const { values, positionals } = parse(rest, { color: { type: "string" } });
+    const [key, name] = theTwo(
+      positionals,
+      'Say the key and the name: console category new <key> "<name>" [--color <name>]',
+    );
+    const color = text(values, "color");
+    const session = await open(io, values);
+    const made = await session.client.createCategory({
+      key,
+      name,
+      ...(color === undefined ? {} : { color: colorOf(color) }),
+    });
+    answer(io, session, made, () => formatCategoryLine(made));
+    return EXIT.ok;
+  }
+  if (verb === "edit") {
+    const { values, positionals } = parse(rest, {
+      name: { type: "string" },
+      color: { type: "string" },
+    });
+    const key = theOne(
+      positionals,
+      "Say which category: console category edit <key> [--name <name>] [--color <name>]",
+    );
+    const name = text(values, "name");
+    const color = text(values, "color");
+    const patch = {
+      ...(name === undefined ? {} : { name }),
+      ...(color === undefined ? {} : { color: colorOf(color) }),
+    };
+    if (Object.keys(patch).length === 0) {
+      throw misuse("Say what to change: --name or --color.");
+    }
+    const session = await open(io, values);
+    const changed = await session.client.updateCategory(key, patch);
+    answer(io, session, changed, () => formatCategoryLine(changed));
+    return EXIT.ok;
+  }
+  if (verb === "remove") {
+    const { values, positionals } = parse(rest, {});
+    const key = theOne(positionals, "Say which category: console category remove <key>");
+    const session = await open(io, values);
+    await session.client.removeCategory(key);
+    answer(io, session, { removed: key }, () => `Category ${key} removed.`);
+    return EXIT.ok;
+  }
+  throw misuse(
+    'Say what to do: console category new <key> "<name>" [--color <name>], console category edit <key> [--name <name>] [--color <name>], or console category remove <key>',
+  );
+};
+
 const COMMANDS: Readonly<Record<string, Command>> = {
   login,
   logout,
@@ -1363,6 +1665,12 @@ const COMMANDS: Readonly<Record<string, Command>> = {
   goal,
   categories,
   skills,
+  people,
+  person,
+  project,
+  members,
+  member,
+  category,
   take,
   report,
   "hand-in": handIn,
@@ -1416,6 +1724,26 @@ function hintFor(error: ApiError): string {
       return "The due day is before the start. Say a due day on or after it.\n";
     case "goal.not_found":
       return "No goal of this project has that id. console goals lists them.\n";
+    case "auth.forbidden":
+      return "What was asked is an administrator's, or an owner's of the project, and the person this token acts as is not one here. Hand the step to them.\n";
+    case "project.key_taken":
+      return "A project has that key already. console projects lists them.\n";
+    case "project.invalid_address":
+      return "The skills address is not one as SkillCDN spells it; none makes the organization's skills the project's.\n";
+    case "project.invalid_icon":
+      return "The image must be a PNG, a JPEG, a GIF or a WebP, known by its bytes.\n";
+    case "member.exists":
+      return "The person is listed already. console member role <login> <owner|member> changes what they are.\n";
+    case "member.not_found":
+      return "The person is not listed in the project. console members lists those who are.\n";
+    case "category.key_taken":
+      return "A category has that key already. console categories lists them.\n";
+    case "category.not_found":
+      return "No category has that key. console categories lists them.\n";
+    case "category.in_use":
+      return "Tasks are sorted into the category. Move them out first: console task edit <number> --category <other|none>\n";
+    case "person.last_admin":
+      return "The board keeps at least one administrator. Make another one first.\n";
     case "connect.too_many":
       return "The console holds as many connections as it may at once. Try again in a few minutes.\n";
     case "network":

package/src/cli/format.ts

@@ -6,6 +6,8 @@ import type {
   RestDocumentSummary,
   RestDocuments,
   RestGoal,
+  RestMember,
+  RestPerson,
   RestProject,
   RestRun,
   RestSkills,
@@ -42,6 +44,31 @@ export function formatProjectLine(project: RestProject): string {
   return `${project.key}  ${project.name}  (${notes.join("; ")})`;
 }
 
+/** One project in full: what it is, how it is marked, and what the person is in it. */
+export function formatProject(project: RestProject): string {
+  const lines = [
+    `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}`,
+  ];
+  if (project.description.trim().length > 0) {
+    lines.push("", project.description.trimEnd());
+  }
+  return lines.join("\n");
+}
+
+/** One person: their login, their name where the host gives one, and what they are in the workspace. */
+export function formatPersonLine(person: RestPerson): string {
+  return person.name === null
+    ? `${person.login}  (${person.role})`
+    : `${person.login}  ${person.name}  (${person.role})`;
+}
+
+/** One member of a project: their login, what they are in it, and since when. */
+export function formatMemberLine(member: RestMember): string {
+  return `${member.person.login}  ${member.role}  (since ${member.addedAt.slice(0, 10)})`;
+}
+
 /** The line under a page of a listing that has more after it: how to ask for the next page. */
 export function formatMore(more: boolean, limit: number, offset: number): string {
   return more ? `\n... more: --offset ${offset + limit}` : "";