@skillcdn/console 0.1.17 → 0.1.19

package/dist/cli/cli.js

@@ -1,14 +1,17 @@
 import { basename, extname } from "node:path";
 import { parseArgs } from "node:util";
 import { ApiError, createClient, } from "../client.js";
+import { CLIENT_RANGE_HEADER, judgeClient, parseVersion, VERSION_HEADER } from "../compat.js";
 import { addDays, dayOf as dayOfDate, isDay } from "../dates.js";
 import { DEFAULT_PAGE_LIMIT, LIST_LIMIT, MAX_OPTIONS, MIN_OPTIONS } from "../limits.js";
 import { fillRules, RULES_PATH, RULES_TITLE } from "../rules.js";
 import { hostOfLogin, } from "../schemas.js";
 import { COLOR_NAMES, GOAL_STATES, PERSON_ROLES, PROJECT_ROLES, PROJECT_VISIBILITIES, PROVIDER_KEYS, TASK_PRIORITIES, TASK_STATES, } from "../vocabulary.js";
 import { loadWebRoot, WebRootError } from "../web.js";
-import { formatAnswer, formatCategoryLine, formatComment, formatDecision, formatDecisionLine, formatDocument, formatDocuments, formatGoal, formatGoalLine, formatListingLine, formatMemberLine, formatMore, formatOptions, formatPersonLine, formatPersonWork, formatProject, formatProjectLine, formatRules, formatRun, formatRunLine, formatSkills, formatTask, formatTaskLine, formatVersion, formatVersionLine, formatWork, } from "./format.js";
+import { CredentialsError, EMPTY_CREDENTIALS, loginsAt, resolveLogin, withLogin, withoutLogin, } from "./credentials.js";
+import { formatAnswer, formatCategoryLine, formatComment, formatDecision, formatDecisionLine, formatDocument, formatDocuments, formatGoal, formatGoalLine, formatListingLine, formatMemberLine, formatMore, formatOptions, formatPersonLine, formatPersonWork, formatProject, formatProjectLine, formatRules, formatRun, formatRunLine, formatSkillFile, formatSkillLoad, formatSkills, formatTask, formatTaskLine, formatVersion, formatVersionLine, formatWork, } from "./format.js";
 import { COMMAND_HELP, helpFor, usage } from "./help.js";
+import { describeInstall, updateCommandFor } from "./install.js";
 import { createServeHandler, DEFAULT_SERVE_PORT } from "./serve.js";
 // The `console` command (docs/specs/cli.md): the agent's side of the console. A thin client of
 // the REST API with no logic of its own: every command is one or two requests and the words to
@@ -24,7 +27,11 @@ export const EXIT = {
     usage: 2,
     /** The decision still waits for a person. */
     waiting: 3,
+    /** The command and the console do not go together (ADR-0025): stderr says which to update, and how. */
+    incompatible: 4,
 };
+/** A day, for how often the command repeats what it noticed of the versions. */
+const DAY_MS = 86_400_000;
 /** How long one request for a decision's answer asks the console to hold it: what the server allows. */
 const WAIT_STEP_SECONDS = 50;
 /** A breath between two such requests, should the console answer at once. */
@@ -47,6 +54,7 @@ const misuse = (message) => new CliExit(EXIT.usage, message);
 const GLOBAL_OPTIONS = {
     json: { type: "boolean" },
     url: { type: "string" },
+    account: { type: "string" },
     project: { type: "string" },
 };
 function parse(args, options, allowPositionals = true) {
@@ -75,20 +83,80 @@ const texts = (values, name) => {
     return typeof value === "string" ? [value] : [];
 };
 const NO_PROJECT = "Say which project: --project <key>, CONSOLE_PROJECT in the environment, or console use <key> once in this directory. console projects lists the projects you may work in.";
-/** The console and the token to talk to it with: the flags, the environment, then what login kept. */
+/** What the command keeps, or nothing; a file that cannot be read stops the command, and is never written over. */
+async function loadCredentials(io) {
+    try {
+        return await io.store.load();
+    }
+    catch (error) {
+        if (error instanceof CredentialsError) {
+            throw failed(`${error.message} Move it away, then sign in again: console login --url <the console's origin>`);
+        }
+        throw error;
+    }
+}
+/** The console a directory is bound to, as an origin, when it names one. */
+function directoryOrigin(settings) {
+    if (settings?.url === undefined) {
+        return undefined;
+    }
+    try {
+        return originOf(settings.url);
+    }
+    catch {
+        throw failed(`.skillcdn-console.json names a console that is not an origin: ${settings.url}`);
+    }
+}
+/** Why no console could be talked to, for the person who reads it. */
+function wordsOf(failure) {
+    switch (failure.reason) {
+        case "nothing":
+            return "Not signed in. A person signs the command in: console login --url <the console's origin>";
+        case "environment_half":
+            return `Both CONSOLE_URL and CONSOLE_TOKEN are needed in the environment, and only ${failure.have} is set: set both, or neither.`;
+        case "no_login": {
+            const whom = failure.account === undefined ? "" : ` as ${failure.account}`;
+            const where = failure.source === "directory"
+                ? `This directory works at ${failure.url}${whom}, where nobody is signed in here`
+                : `Nobody is signed in here at ${failure.url}${whom}`;
+            return `${where}: console login --url ${failure.url}. console logins lists the consoles signed in.`;
+        }
+        case "ambiguous":
+            return `Several accounts are signed in at ${failure.url} (${failure.accounts.join(", ")}): say which with --account <login>, or bind this directory to one with console use <key> --account <login>.`;
+    }
+}
+/**
+ * The console a command talks to, and with what (ADR-0027): the address from the flag, the
+ * environment, the directory or the default login, in that order, and then the token kept for
+ * that address and no other. A token never travels to a console it was not made at.
+ */
 async function open(io, values) {
-    const stored = await io.store.load();
-    const url = text(values, "url") ?? io.env.CONSOLE_URL ?? stored?.url;
-    const token = io.env.CONSOLE_TOKEN ?? stored?.token;
-    if (url === undefined || token === undefined) {
-        throw failed("Not signed in. A person signs the command in: console login --url <the console's origin>");
-    }
-    const client = createClient({ baseUrl: url, token, fetch: io.fetch });
-    const projectKey = async () => text(values, "project") ?? io.env.CONSOLE_PROJECT ?? (await io.directory.load())?.project;
+    const directory = await io.directory.load();
+    const flag = text(values, "url");
+    const envUrl = io.env.CONSOLE_URL;
+    const credentials = await loadCredentials(io);
+    const resolved = resolveLogin({
+        flagUrl: flag === undefined ? undefined : originOf(flag),
+        flagAccount: text(values, "account"),
+        envUrl: envUrl === undefined ? undefined : originOf(envUrl),
+        envToken: io.env.CONSOLE_TOKEN,
+        directoryUrl: directoryOrigin(directory),
+        directoryAccount: directory?.account,
+        credentials,
+    });
+    if (!resolved.ok) {
+        throw failed(wordsOf(resolved));
+    }
+    const { url, token } = resolved;
+    const client = clientOf(io, url, token);
+    const projectKey = async () => text(values, "project") ?? io.env.CONSOLE_PROJECT ?? directory?.project;
     return {
         client,
         url,
         token,
+        account: resolved.account,
+        via: resolved.via,
+        credentials,
         json: on(values, "json"),
         projectKey,
         async project() {
@@ -128,6 +196,8 @@ async function bodyOf(io, values, given) {
     }
     return given === "-" ? io.readStdin() : given;
 }
+/** The hosts a token may travel to in the clear: this machine, and no other. */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 function originOf(value) {
     const url = URL.canParse(value) ? new URL(value) : undefined;
     if (url === undefined ||
@@ -137,6 +207,10 @@ function originOf(value) {
         url.hash !== "") {
         throw misuse(`Not an origin: ${value}. Say the console's address without a path, such as https://console.example.com`);
     }
+    // A token travels over https; in the clear only to this machine, where a console is run for development.
+    if (url.protocol === "http:" && !LOOPBACK_HOSTS.has(url.hostname)) {
+        throw misuse(`Not a safe origin: ${value}. A token travels over https only; http is for a console on this machine (localhost).`);
+    }
     return url.origin;
 }
 function stateOf(value) {
@@ -321,35 +395,48 @@ async function settle(io, session, project, decision, seconds, shown = false) {
     }
     return outcome.answer === null ? EXIT.waiting : EXIT.ok;
 }
-/** Checks a token against the console, keeps it with the address, and says who it is. */
-async function keep(io, url, token, agent) {
-    const me = await createClient({ baseUrl: url, token, fetch: io.fetch }).me();
+/**
+ * Checks a token against the console, keeps it as the login at that console for that account,
+ * and says who it is. A token the login replaces is given up at the console on the way.
+ */
+async function keep(io, url, token, agent, asDefault) {
+    const me = await clientOf(io, url, token).me();
     const person = me.person;
     if (person === null) {
         throw failed("The console does not know this token. Make one on your Agents page and try again.");
     }
-    const kept = await io.store.save({ url, token });
-    io.stdout(`${agent === undefined ? "Signed in" : `Connected as "${agent}"`} to ${me.workspace.name} at ${url} as ${person.login} (${person.role}). The token is kept in ${kept}.\nNext, say which project this directory works in: console use <key> (console projects lists them).\n`);
+    const credentials = (await loadCredentials(io)) ?? EMPTY_CREDENTIALS;
+    const replaced = loginsAt(credentials, url).find((login) => login.account === person.login);
+    if (replaced !== undefined && replaced.token !== token) {
+        await clientOf(io, url, replaced.token)
+            .giveUpToken()
+            .catch(() => undefined);
+    }
+    const next = withLogin(credentials, { url, account: person.login, token, agent, since: new Date(io.now()).toISOString() }, { default: asDefault });
+    const kept = await io.store.save(next);
+    const standing = next.default === url ? ", the default console here" : "";
+    io.stdout(`${agent === undefined ? "Signed in" : `Connected as "${agent}"`} to ${me.workspace.name} at ${url} as ${person.login} (${person.role})${standing}. The token is kept in ${kept}.\nNext, say which project this directory works in: console use <key> (console projects lists them).\n`);
     return EXIT.ok;
 }
 const login = async (args, io) => {
-    const { values } = parse(args, { "token-stdin": { type: "boolean" }, agent: { type: "string" } }, false);
-    const stored = await io.store.load();
-    const wanted = text(values, "url") ?? io.env.CONSOLE_URL ?? stored?.url;
+    const { values } = parse(args, { "token-stdin": { type: "boolean" }, agent: { type: "string" }, default: { type: "boolean" } }, false);
+    const credentials = await loadCredentials(io);
+    const wanted = text(values, "url") ?? io.env.CONSOLE_URL ?? credentials?.default;
     if (wanted === undefined) {
         throw misuse("Say where the console is: console login --url https://console.example.com");
     }
     const url = originOf(wanted);
+    const asDefault = on(values, "default");
     if (on(values, "token-stdin")) {
         const token = (await io.readStdin()).trim();
         if (token.length === 0) {
             throw failed("No token was given.");
         }
-        return keep(io, url, token);
+        return keep(io, url, token, undefined, asDefault);
     }
     // A connection (ADR-0011): a code a person approves on the console's own pages, and the token
     // handed over here once, never shown.
-    const client = createClient({ baseUrl: url, fetch: io.fetch });
+    const client = clientOf(io, url);
     // "<agent> on <machine>": the pages say the agent and keep the machine for a hover.
     const agent = text(values, "agent") ?? agentOf(io.env) ?? "An agent";
     const begun = await client.connect({
@@ -369,38 +456,94 @@ const login = async (args, io) => {
             throw error;
         }
         if (claim.status === "connected") {
-            return keep(io, url, claim.secret, claim.token.name);
+            return keep(io, url, claim.secret, claim.token.name, asDefault);
         }
     }
 };
 const logout = async (args, io) => {
-    parse(args, {}, false);
-    const stored = await io.store.load();
-    const url = io.env.CONSOLE_URL ?? stored?.url;
-    const token = io.env.CONSOLE_TOKEN ?? stored?.token;
-    if (url === undefined || token === undefined) {
+    const { values } = parse(args, {}, false);
+    const credentials = await loadCredentials(io);
+    const directory = await io.directory.load();
+    const envNote = () => {
+        if (io.env.CONSOLE_TOKEN !== undefined) {
+            io.stdout("CONSOLE_TOKEN in the environment still holds a token: unset it.\n");
+        }
+    };
+    if (credentials === undefined || credentials.logins.length === 0) {
         io.stdout("Not signed in here: nothing to forget.\n");
+        envNote();
         return EXIT.ok;
     }
+    // Which login: the console the flag names, else the directory's, else the default, else the
+    // one console signed in to; and the account the same way, where the console has several.
+    const consoles = [...new Set(credentials.logins.map((login) => login.url))];
+    const flag = text(values, "url");
+    const url = flag === undefined
+        ? (directoryOrigin(directory) ??
+            credentials.default ??
+            (consoles.length === 1 ? consoles[0] : undefined))
+        : originOf(flag);
+    if (url === undefined) {
+        throw failed(`Several consoles are signed in here; say which: console logout --url <origin>. console logins lists them.`);
+    }
+    const account = text(values, "account") ?? directory?.account;
+    const at = loginsAt(credentials, url);
+    const chosen = account === undefined ? at : at.filter((login) => login.account === account);
+    const [login] = chosen;
+    if (login === undefined) {
+        throw failed(`Nobody is signed in here at ${url}${account === undefined ? "" : ` as ${account}`}: nothing to forget. console logins lists the consoles signed in.`);
+    }
+    if (chosen.length > 1) {
+        throw failed(`Several accounts are signed in at ${url} (${chosen.map((kept) => kept.account ?? "?").join(", ")}); say which: console logout --url ${url} --account <login>`);
+    }
     // The token is given up at the console first, so that it is good for nothing from now on;
     // one the console no longer knows is gone already. A console out of reach leaves it to the
     // Agents page, and the person is told so.
     let gone = true;
     try {
-        await createClient({ baseUrl: url, token, fetch: io.fetch }).giveUpToken();
+        await clientOf(io, url, login.token).giveUpToken();
     }
     catch (error) {
         if (!(error instanceof ApiError && error.code === "auth.required")) {
             gone = false;
         }
     }
-    await io.store.clear();
+    const next = withoutLogin(credentials, url, login.account);
+    if (next.logins.length === 0) {
+        await io.store.clear();
+    }
+    else {
+        await io.store.save(next);
+    }
+    const whom = login.account === undefined ? "" : ` as ${login.account}`;
     io.stdout(gone
-        ? "Signed out: the token is given up at the console and forgotten here.\n"
-        : `Signed out here, but the console at ${url} could not be reached to give the token up: a person removes it on the Agents page.\n`);
-    if (io.env.CONSOLE_TOKEN !== undefined) {
-        io.stdout("CONSOLE_TOKEN in the environment still holds it: unset it.\n");
+        ? `Signed out of ${url}${whom}: the token is given up at the console and forgotten here.\n`
+        : `Signed out of ${url}${whom} here, but the console could not be reached to give the token up: a person removes it on the Agents page.\n`);
+    envNote();
+    return EXIT.ok;
+};
+/** The consoles this machine is signed in to, with the account at each; never a token. */
+const logins = async (args, io) => {
+    const { values } = parse(args, {}, false);
+    const credentials = await loadCredentials(io);
+    const kept = (credentials?.logins ?? []).map((login) => ({
+        url: login.url,
+        account: login.account ?? null,
+        agent: login.agent ?? null,
+        since: login.since ?? null,
+        default: credentials?.default === login.url,
+    }));
+    if (on(values, "json")) {
+        io.stdout(`${JSON.stringify({ default: credentials?.default ?? null, logins: kept }, null, 2)}\n`);
+        return EXIT.ok;
     }
+    if (kept.length === 0) {
+        io.stdout("Not signed in anywhere here: console login --url <the console's origin>\n");
+        return EXIT.ok;
+    }
+    io.stdout(`${kept
+        .map((login) => `${login.url}  ${login.account ?? "(account unknown)"}${login.agent === null ? "" : `  ${login.agent}`}${login.since === null ? "" : `  since ${login.since.slice(0, 10)}`}${login.default ? "  (default)" : ""}`)
+        .join("\n")}\n`);
     return EXIT.ok;
 };
 /** The agent the command runs under, where its environment says so: what a connection is named by default. */
@@ -422,7 +565,31 @@ const whoami = async (args, io) => {
         throw failed("The console does not know this token. Sign in again: console login");
     }
     const key = await session.projectKey();
-    answer(io, session, { ...me, project: key ?? null }, () => `${person.login} (${person.role}) at ${me.workspace.name}, ${session.url}${key === undefined ? "; no project named here" : `; project ${key}`}`);
+    const command = parseVersion(io.version);
+    const server = parseVersion(me.console?.version);
+    const verdict = command === undefined || server === undefined
+        ? undefined
+        : judgeClient(command, server).verdict;
+    // A console from before the rule says nothing of itself; the command says so instead.
+    const consoleWords = me.console === undefined
+        ? "the console does not say its version, so it is older than 0.1.18"
+        : `the console is ${me.console.version} and takes ${me.console.clientRange}`;
+    answer(io, session, {
+        ...me,
+        console: me.console ?? null,
+        project: key ?? null,
+        command: { version: io.version ?? null, install: io.install ?? null },
+    }, () => [
+        `${person.login} (${person.role}) at ${me.workspace.name}, ${session.url}${key === undefined ? "; no project named here" : `; project ${key}`}`,
+        `This command is ${io.version ?? "of a version it does not know"}${io.install === undefined ? "" : `, ${describeInstall(io.install)}`}; ${consoleWords}.`,
+        ...(verdict === "behind"
+            ? [`A newer command exists. Update it: ${updateWords(io, me.console?.version)}`]
+            : verdict === "ahead"
+                ? [
+                    `This command is newer than the console: what the console has not got yet is refused as not found. To match the console: ${updateWords(io, me.console?.version)}`,
+                ]
+                : []),
+    ].join("\n"));
     return EXIT.ok;
 };
 const projects = async (args, io) => {
@@ -436,11 +603,25 @@ const projects = async (args, io) => {
 };
 const use = async (args, io) => {
     const { values, positionals } = parse(args, {});
-    const key = theOne(positionals, "Say which project: console use <key>");
+    const key = theOne(positionals, "Say which project: console use <key> [--url <origin>] [--account <login>]");
     const session = await open(io, values);
     const project = await session.client.project(key).get();
-    const kept = await io.directory.save({ project: project.key });
-    answer(io, session, project, () => `Working in ${project.name} (${project.key}) from this directory on: kept in ${kept}, which is meant to be committed. What its people ask of agents: console rules.`);
+    // The directory names the console where that is not the default login here, or when asked,
+    // and the account where the console has several, or when asked; never a token.
+    const credentials = session.credentials ?? EMPTY_CREDENTIALS;
+    const pinUrl = text(values, "url") !== undefined ||
+        (session.via === "login" && credentials.default !== session.url);
+    const pinAccount = text(values, "account") !== undefined ||
+        (session.via === "login" && loginsAt(credentials, session.url).length > 1);
+    const kept = await io.directory.save({
+        project: project.key,
+        ...(pinUrl ? { url: session.url } : {}),
+        ...(pinAccount && session.account !== undefined ? { account: session.account } : {}),
+    });
+    const bound = pinUrl
+        ? ` at ${session.url}${pinAccount && session.account !== undefined ? ` as ${session.account}` : ""}`
+        : "";
+    answer(io, session, project, () => `Working in ${project.name} (${project.key})${bound} from this directory on: kept in ${kept}, which is meant to be committed in a private repository and left out of a public one. What its people ask of agents: console rules.`);
     return EXIT.ok;
 };
 const tasks = async (args, io) => {
@@ -448,12 +629,17 @@ const tasks = async (args, io) => {
         state: { type: "string" },
         open: { type: "boolean" },
         mine: { type: "boolean" },
+        unassigned: { type: "boolean" },
         category: { type: "string" },
         goal: { type: "string" },
         due: { type: "string" },
+        archived: { type: "boolean" },
         ...PAGE_OPTIONS,
     }, false);
     const state = stateOf(text(values, "state"));
+    if (on(values, "mine") && on(values, "unassigned")) {
+        throw misuse("Say one: --mine for the tasks assigned to you, or --unassigned for those assigned to nobody");
+    }
     const page = pageOf(values);
     const session = await open(io, values);
     const project = await session.project();
@@ -474,9 +660,11 @@ const tasks = async (args, io) => {
         ...(state === undefined ? {} : { state }),
         ...(on(values, "open") || due === "overdue" ? { open: true } : {}),
         ...(assignee === undefined ? {} : { assignee }),
+        ...(on(values, "unassigned") ? { unassigned: true } : {}),
         ...(text(values, "category") === undefined ? {} : { category: text(values, "category") }),
         ...(text(values, "goal") === undefined ? {} : { goal: text(values, "goal") }),
         ...(dueBy === undefined ? {} : { dueBy }),
+        ...(on(values, "archived") ? { archived: true } : {}),
         ...page,
     });
     answer(io, session, found, () => found.items.length === 0
@@ -515,6 +703,60 @@ const skills = async (args, io) => {
     answer(io, session, found, () => formatSkills(found, io.skillsDir));
     return EXIT.ok;
 };
+/** How many pages of a skill, or of a file, the command follows before it stops: far above what one holds. */
+const MAX_SKILL_PAGES = 64;
+const skill = async (args, io) => {
+    const { values, positionals } = parse(args, { file: { type: "string" } });
+    const path = theOne(positionals, "Say which skill: console skill <path of its SKILL.md> [--file <path>]");
+    const session = await open(io, values);
+    const project = await session.project();
+    const file = text(values, "file");
+    if (file !== undefined) {
+        // The file whole, page after page, as the console reads it from the deployment.
+        const parts = [];
+        let offset;
+        let last;
+        for (let pages = 0; pages < MAX_SKILL_PAGES; pages += 1) {
+            last = await project.skillFile(file, offset === undefined ? {} : { offset });
+            if (last.status !== "ready" || last.file === null) {
+                break;
+            }
+            parts.push(last.file.content);
+            if (last.file.nextOffset === null) {
+                break;
+            }
+            offset = last.file.nextOffset;
+        }
+        if (last === undefined) {
+            throw failed("The file could not be read.");
+        }
+        const read = last;
+        const content = parts.join("");
+        answer(io, session, { ...read, content }, () => formatSkillFile(read, content));
+        return EXIT.ok;
+    }
+    // The skill whole: its pages until complete, the rules first, as load_skill lays them out.
+    const pages = [];
+    let cursor;
+    let last;
+    for (let n = 0; n < MAX_SKILL_PAGES; n += 1) {
+        last = await project.skill(path, cursor);
+        if (last.status !== "ready" || last.skill === null) {
+            break;
+        }
+        pages.push(last.skill);
+        if (last.skill.complete || last.skill.nextCursor === null) {
+            break;
+        }
+        cursor = last.skill.nextCursor;
+    }
+    if (last === undefined) {
+        throw failed("The skill could not be read.");
+    }
+    const loaded = last;
+    answer(io, session, { ...loaded, pages }, () => formatSkillLoad(loaded, pages));
+    return EXIT.ok;
+};
 /** A version number given as a flag, or nothing; anything else is not understood. */
 function versionOf(given) {
     if (given === undefined) {
@@ -685,6 +927,36 @@ const editTask = async (args, io) => {
     answer(io, session, changed, () => formatTask(changed));
     return EXIT.ok;
 };
+/** Puts a task away, or every done or dropped task of a goal (ADR-0029); the task by its number or its id. */
+const taskArchive = async (args, io) => {
+    const { values, positionals } = parse(args, { goal: { type: "string" } });
+    const goal = text(values, "goal");
+    if (positionals.length > 1 || (positionals.length === 0) === (goal === undefined)) {
+        throw misuse("Say which: console task archive <number|id>, or console task archive --goal <id> for every done or dropped task of a goal");
+    }
+    const session = await open(io, values);
+    const project = await session.project();
+    if (goal !== undefined) {
+        const { archived } = await project.archiveTasksOfGoal(goal);
+        answer(io, session, { archived }, () => `${archived} ${archived === 1 ? "task" : "tasks"} of the goal put away.`);
+        return EXIT.ok;
+    }
+    const found = await project.task(positionals[0] ?? "");
+    const archived = await project.archiveTask(found.id);
+    answer(io, session, archived, () => formatTaskLine(archived));
+    return EXIT.ok;
+};
+/** Brings a task back from the archive. */
+const taskRestore = async (args, io) => {
+    const { values, positionals } = parse(args, {});
+    const ref = theOne(positionals, "Say which task: console task restore <number|id>");
+    const session = await open(io, values);
+    const project = await session.project();
+    const found = await project.task(ref);
+    const restored = await project.restoreTask(found.id);
+    answer(io, session, restored, () => formatTaskLine(restored));
+    return EXIT.ok;
+};
 const task = async (args, io) => {
     if (args[0] === "new") {
         return newTask(args.slice(1), io);
@@ -692,6 +964,12 @@ const task = async (args, io) => {
     if (args[0] === "edit") {
         return editTask(args.slice(1), io);
     }
+    if (args[0] === "archive") {
+        return taskArchive(args.slice(1), io);
+    }
+    if (args[0] === "restore") {
+        return taskRestore(args.slice(1), io);
+    }
     const { values, positionals } = parse(args, {});
     const ref = theOne(positionals, "Say which task: console task <number|id>");
     const session = await open(io, values);
@@ -1077,25 +1355,40 @@ const restore = async (args, io) => {
     return EXIT.ok;
 };
 const goals = async (args, io) => {
-    const { values } = parse(args, {}, false);
+    const { values } = parse(args, { category: { type: "string" }, state: { type: "string" } }, false);
+    const state = goalStateOf(text(values, "state"));
+    const category = text(values, "category");
     const session = await open(io, values);
     const project = await session.project();
-    const found = await project.goals();
+    const found = await project.goals({
+        ...(state === undefined ? {} : { state }),
+        ...(category === undefined ? {} : { category }),
+    });
     answer(io, session, found, () => found.items.length === 0
-        ? "No goals. An owner sets one: console goal new <title> --due <day>"
+        ? state === undefined && category === undefined
+            ? "No goals. An owner sets one: console goal new <title> --due <day>"
+            : "No goal matches."
         : found.items.map(formatGoalLine).join("\n"));
     return EXIT.ok;
 };
 const GOAL_FIELDS = {
     state: { type: "string" },
+    category: { type: "string" },
+    starts: { type: "string" },
     due: { type: "string" },
     body: { type: "string" },
     file: { type: "string" },
 };
+/** A category's key as a flag names one, or `null` for `none` where the field may be cleared. */
+function categoryOf(value, clearable = false) {
+    return clearable && value === "none" ? null : value;
+}
 const newGoal = async (args, io) => {
     const { values, positionals } = parse(args, GOAL_FIELDS);
     const title = theOne(positionals, 'Say the title: console goal new "<title>" [--due <day>]');
     const state = goalStateOf(text(values, "state"));
+    const category = categoryOf(text(values, "category"));
+    const startsOn = dayOf(io, text(values, "starts"));
     const dueOn = dayOf(io, text(values, "due"));
     const body = await bodyOf(io, values, text(values, "body"));
     const session = await open(io, values);
@@ -1104,6 +1397,8 @@ const newGoal = async (args, io) => {
         title,
         ...(body === undefined ? {} : { body }),
         ...(state === undefined ? {} : { state }),
+        ...(category === undefined ? {} : { category }),
+        ...(startsOn === undefined ? {} : { startsOn }),
         ...(dueOn === undefined ? {} : { dueOn }),
     });
     answer(io, session, made, () => `Goal set: ${made.title}\nid: ${made.id}`);
@@ -1114,16 +1409,20 @@ const editGoal = async (args, io) => {
     const id = theOne(positionals, "Say which goal: console goal edit <id> --state <state> ...");
     const title = text(values, "title");
     const state = goalStateOf(text(values, "state"));
+    const category = categoryOf(text(values, "category"), true);
+    const startsOn = dayOf(io, text(values, "starts"), true);
     const dueOn = dayOf(io, text(values, "due"), true);
     const body = await bodyOf(io, values, text(values, "body"));
     const patch = {
         ...(title === undefined ? {} : { title }),
         ...(body === undefined ? {} : { body }),
         ...(state === undefined ? {} : { state }),
+        ...(category === undefined ? {} : { category }),
+        ...(startsOn === undefined ? {} : { startsOn }),
         ...(dueOn === undefined ? {} : { dueOn }),
     };
     if (Object.keys(patch).length === 0) {
-        throw misuse("Say what to change: --title, --body, --state or --due; --due none clears the day.");
+        throw misuse("Say what to change: --title, --body, --state, --category, --starts or --due; none clears a category or a day.");
     }
     const session = await open(io, values);
     const project = await session.project();
@@ -1394,6 +1693,31 @@ const editProject = async (args, io) => {
     answer(io, session, changed, () => formatProject(changed));
     return EXIT.ok;
 };
+/** The pack token (ADR-0028): read from standard input and never from an argument, so that no shell keeps it. */
+const projectPackToken = async (args, io) => {
+    const { values, positionals } = parse(args, {
+        stdin: { type: "boolean" },
+        remove: { type: "boolean" },
+    });
+    const key = theOne(positionals, "Say which project: console project pack-token <key> --stdin, or console project pack-token <key> --remove");
+    if (on(values, "stdin") === on(values, "remove")) {
+        throw misuse("Say one of --stdin, which reads the token from standard input, and --remove, which takes it away.");
+    }
+    const session = await open(io, values);
+    const project = session.client.project(key);
+    if (on(values, "remove")) {
+        const changed = await project.removePackToken();
+        answer(io, session, changed, () => formatProject(changed));
+        return EXIT.ok;
+    }
+    const token = (await io.readStdin()).trim();
+    if (token.length === 0) {
+        throw failed("No token was given on standard input.");
+    }
+    const changed = await project.setPackToken({ token });
+    answer(io, session, changed, () => formatProject(changed));
+    return EXIT.ok;
+};
 const projectIcon = async (args, io) => {
     const { values, positionals } = parse(args, { remove: { type: "boolean" } });
     const [key, file] = positionals;
@@ -1423,8 +1747,11 @@ const project = async (args, io) => {
     if (args[0] === "icon") {
         return projectIcon(args.slice(1), io);
     }
+    if (args[0] === "pack-token") {
+        return projectPackToken(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 key = theOne(positionals, "Say which project: console project <key>; or console project new, edit, icon or pack-token");
     const session = await open(io, values);
     const found = await session.client.project(key).get();
     answer(io, session, found, () => formatProject(found));
@@ -1440,18 +1767,51 @@ const members = async (args, io) => {
         : found.items.map(formatMemberLine).join("\n"));
     return EXIT.ok;
 };
+/** The keys --project names with commas, each once, or nothing when it names one project or none. */
+function projectKeysOf(value) {
+    if (value === undefined || !value.includes(",")) {
+        return undefined;
+    }
+    const keys = [...new Set(value.split(",").map((key) => key.trim()))].filter((key) => key !== "");
+    if (keys.length === 0) {
+        throw misuse("Say which projects: --project <key>[,<key>...]");
+    }
+    return keys;
+}
 const member = 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 login = theOne(positionals, "Say whom: console member add <login> [--role owner|member] [--project <key>[,<key>...]]");
         const role = text(values, "role");
         const session = await open(io, values);
-        const project = await session.project();
-        const added = await project.addMember({
+        const input = {
             personId: (await personOf(session, login)).id,
             ...(role === undefined ? {} : { role: projectRoleOf(role) }),
-        });
+        };
+        // Several projects at once, where --project names them with commas: the person is listed
+        // in each in turn, one listed already is said so, and the rest go on.
+        const keys = projectKeysOf(text(values, "project"));
+        if (keys !== undefined) {
+            const added = [];
+            for (const key of keys) {
+                try {
+                    added.push({ project: key, member: await session.client.project(key).addMember(input) });
+                }
+                catch (error) {
+                    if (!(error instanceof ApiError && error.code === "member.exists")) {
+                        throw error;
+                    }
+                    added.push({ project: key, member: null });
+                }
+            }
+            answer(io, session, added, () => added
+                .map(({ project, member }) => `${project}  ${member === null ? `${login} is listed already` : formatMemberLine(member)}`)
+                .join("\n"));
+            return EXIT.ok;
+        }
+        const project = await session.project();
+        const added = await project.addMember(input);
         answer(io, session, added, () => formatMemberLine(added));
         return EXIT.ok;
     }
@@ -1477,7 +1837,7 @@ const member = async (args, io) => {
         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>");
+    throw misuse("Say what to do: console member add <login> [--role owner|member] [--project <key>[,<key>...]], console member role <login> <owner|member>, or console member remove <login>");
 };
 const category = async (args, io) => {
     const [verb, ...rest] = args;
@@ -1526,6 +1886,7 @@ const category = async (args, io) => {
 };
 const COMMANDS = {
     login,
+    logins,
     logout,
     whoami,
     serve,
@@ -1538,6 +1899,7 @@ const COMMANDS = {
     goal,
     categories,
     skills,
+    skill,
     rules,
     people,
     person,
@@ -1577,9 +1939,70 @@ function help(io, name) {
     io.stdout(found);
     return EXIT.ok;
 }
+/**
+ * A client of the console at `url`, naming the command on every request (ADR-0025). A redirect
+ * is not followed: the token goes to the address the command resolved, and nowhere it is sent on to.
+ */
+function clientOf(io, url, token) {
+    return createClient({
+        baseUrl: url,
+        fetch: (input, init) => io.fetch(input, { ...init, redirect: "manual" }),
+        ...(token === undefined ? {} : { token }),
+        ...(io.userAgent === undefined ? {} : { userAgent: io.userAgent }),
+    });
+}
+/** The command that puts the console's version where this command is installed. */
+function updateWords(io, version) {
+    const wanted = version ?? "latest";
+    if (io.install === undefined) {
+        return `npm install -g @skillcdn/console@${wanted}`;
+    }
+    const command = updateCommandFor(io.install, wanted);
+    return io.install.kind === "project" ? `${command} (in ${io.install.root})` : command;
+}
+/**
+ * What the command says of the versions once the console answered: that a newer command exists,
+ * or that this one is newer than the console; once a day for one pair of versions, on stderr,
+ * so that the console's JSON stays what it is. What is out of the range never gets here: the
+ * console refused it, and the refusal says what to do.
+ */
+async function noticeVersions(io, seen) {
+    const command = parseVersion(io.version);
+    const server = parseVersion(seen.version);
+    if (io.version === undefined ||
+        seen.version === undefined ||
+        command === undefined ||
+        server === undefined) {
+        return;
+    }
+    const { verdict } = judgeClient(command, server);
+    if (verdict !== "behind" && verdict !== "ahead") {
+        return;
+    }
+    const previous = await io.notices?.load();
+    const now = io.now();
+    if (previous !== undefined &&
+        previous.command === io.version &&
+        previous.console === seen.version &&
+        now - Date.parse(previous.shownAt) < DAY_MS) {
+        return;
+    }
+    io.stderr(verdict === "behind"
+        ? `A newer command exists: the console runs ${seen.version}, this command is ${io.version}. Update it: ${updateWords(io, seen.version)}\n`
+        : `This command (${io.version}) is newer than the console (${seen.version}, which takes ${seen.range ?? "an older line"}): what the console has not got yet is refused as not found. The console's operator updates it; to match the console meanwhile: ${updateWords(io, seen.version)}\n`);
+    await io.notices?.save({
+        command: io.version,
+        console: seen.version,
+        shownAt: new Date(now).toISOString(),
+    });
+}
 /** What a refusal of the console is followed by, when there is something to do about it. */
-function hintFor(error) {
+function hintFor(error, io, seen) {
     switch (error.code) {
+        case "client.outdated":
+            return `Update the command: ${updateWords(io, seen.version)}\n`;
+        case "client.too_new":
+            return `Install the console's version: ${updateWords(io, seen.version)}; or ask the console's operator to update the console.\n`;
         case "auth.required":
             return "The token is not one the console knows, any more or at all. A person signs the command in again: console login\n";
         case "project.not_found":
@@ -1598,6 +2021,10 @@ function hintFor(error) {
             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 "goal.invalid_category":
+            return "No category has that key. console categories lists them.\n";
+        case "goal.invalid_dates":
+            return "The target day is before the start. Say a target day on or after it.\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":
@@ -1637,9 +2064,21 @@ function hintFor(error) {
 /** Runs the command and answers with its exit code. What it prints goes through `io`. */
 export async function runCli(argv, io) {
     const [name, ...rest] = argv;
+    // Every answer of the console says its version and the range it takes; the command reads
+    // them off the answers it gets anyway, and asks nothing more (ADR-0025).
+    const seen = {};
+    const watched = {
+        ...io,
+        fetch: async (input, init) => {
+            const response = await io.fetch(input, init);
+            seen.version = response.headers.get(VERSION_HEADER) ?? seen.version;
+            seen.range = response.headers.get(CLIENT_RANGE_HEADER) ?? seen.range;
+            return response;
+        },
+    };
     try {
         if (name === "--version" || name === "-v" || name === "version") {
-            io.stdout(`console ${io.version ?? "(version unknown)"} (@skillcdn/console)\n`);
+            io.stdout(`console ${io.version ?? "(version unknown)"} (@skillcdn/console)${io.install === undefined ? "" : `, ${describeInstall(io.install)}`}\n`);
             return EXIT.ok;
         }
         if (name === undefined || name === "help" || name === "--help" || name === "-h") {
@@ -1652,7 +2091,11 @@ export async function runCli(argv, io) {
         if (command === undefined) {
             throw misuse(`Not a command: ${name}. Run: console help`);
         }
-        return await command(rest, io);
+        const exit = await command(rest, watched);
+        if (name !== "whoami") {
+            await noticeVersions(io, seen);
+        }
+        return exit;
     }
     catch (error) {
         if (error instanceof CliExit) {
@@ -1660,8 +2103,10 @@ export async function runCli(argv, io) {
             return error.exit;
         }
         if (error instanceof ApiError) {
-            io.stderr(`${error.code}: ${error.message}\n${hintFor(error)}`);
-            return EXIT.failed;
+            io.stderr(`${error.code}: ${error.message}\n${hintFor(error, io, seen)}`);
+            return error.code === "client.outdated" || error.code === "client.too_new"
+                ? EXIT.incompatible
+                : EXIT.failed;
         }
         throw error;
     }