@skillcdn/console 0.1.17 → 0.1.18

package/src/cli/cli.ts

@@ -7,6 +7,7 @@ import {
   type FetchLike,
   type ProjectClient,
 } 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";
@@ -67,6 +68,8 @@ import {
   formatWork,
 } from "./format.js";
 import { COMMAND_HELP, helpFor, usage } from "./help.js";
+import { describeInstall, type Install, updateCommandFor } from "./install.js";
+import type { NoticeStore } from "./notices.js";
 import { createServeHandler, DEFAULT_SERVE_PORT, type Listen } from "./serve.js";
 
 // The `console` command (docs/specs/cli.md): the agent's side of the console. A thin client of
@@ -84,8 +87,13 @@ 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,
 } as const;
 
+/** 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. */
@@ -117,6 +125,12 @@ export interface CliIo {
   readonly now: () => number;
   /** The version of the package the command runs from, when the entry point knows it. */
   readonly version?: string | undefined;
+  /** What the command calls itself on every request (ADR-0025); nothing when it does not know its version. */
+  readonly userAgent?: string | undefined;
+  /** Where the command is installed, so that an update is told the way it takes effect; nothing when unknown. */
+  readonly install?: Install | undefined;
+  /** What the command last said of the versions; left out, it says it every time. */
+  readonly notices?: NoticeStore | undefined;
   /** Where the console's own skills are on this machine, shipped with the package; nothing when they are not there. */
   readonly skillsDir?: string | undefined;
   /** How `serve` listens on the loopback (ADR-0014); left out, the command cannot serve. */
@@ -200,7 +214,7 @@ async function open(io: CliIo, values: Values): Promise<Session> {
       "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 client = clientOf(io, url, token);
   const projectKey = async () =>
     text(values, "project") ?? io.env.CONSOLE_PROJECT ?? (await io.directory.load())?.project;
   return {
@@ -505,7 +519,7 @@ type Command = (args: readonly string[], io: CliIo) => Promise<number>;
 
 /** Checks a token against the console, keeps it with the address, and says who it is. */
 async function keep(io: CliIo, url: string, token: string, agent?: string): Promise<number> {
-  const me = await createClient({ baseUrl: url, token, fetch: io.fetch }).me();
+  const me = await clientOf(io, url, token).me();
   const person = me.person;
   if (person === null) {
     throw failed(
@@ -540,7 +554,7 @@ const login: Command = async (args, io) => {
   }
   // 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({
@@ -582,7 +596,7 @@ const logout: Command = async (args, io) => {
   // 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, token).giveUpToken();
   } catch (error) {
     if (!(error instanceof ApiError && error.code === "auth.required")) {
       gone = false;
@@ -620,12 +634,38 @@ const whoami: Command = async (args, io) => {
     throw failed("The console does not know this token. Sign in again: console login");
   }
   const key = await session.projectKey();
+  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, project: key ?? null },
+    {
+      ...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}`}`,
+      [
+        `${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;
 };
@@ -1417,13 +1457,24 @@ const restore: Command = async (args, io) => {
 };
 
 const goals: Command = 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;
@@ -1431,15 +1482,24 @@ const goals: Command = async (args, io) => {
 
 const GOAL_FIELDS: OptionSpec = {
   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: string | undefined, clearable = false): string | null | undefined {
+  return clearable && value === "none" ? null : value;
+}
+
 const newGoal: Command = 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);
@@ -1448,6 +1508,8 @@ const newGoal: Command = 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}`);
@@ -1459,17 +1521,21 @@ const editGoal: Command = 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.",
+      "Say what to change: --title, --body, --state, --category, --starts or --due; none clears a category or a day.",
     );
   }
   const session = await open(io, values);
@@ -2021,9 +2087,82 @@ function help(io: CliIo, name: string | undefined): number {
   return EXIT.ok;
 }
 
+/** A client of the console at `url`, naming the command on every request (ADR-0025). */
+function clientOf(io: CliIo, url: string, token?: string): ConsoleClient {
+  return createClient({
+    baseUrl: url,
+    fetch: io.fetch,
+    ...(token === undefined ? {} : { token }),
+    ...(io.userAgent === undefined ? {} : { userAgent: io.userAgent }),
+  });
+}
+
+/** What the console said of itself on its last answer (ADR-0025): its version, and the range of command versions it takes. */
+interface ConsoleSeen {
+  version?: string | undefined;
+  range?: string | undefined;
+}
+
+/** The command that puts the console's version where this command is installed. */
+function updateWords(io: CliIo, version: string | undefined): string {
+  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: CliIo, seen: ConsoleSeen): Promise<void> {
+  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: ApiError): string {
+function hintFor(error: ApiError, io: CliIo, seen: ConsoleSeen): string {
   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":
@@ -2042,6 +2181,10 @@ 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 "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":
@@ -2082,9 +2225,23 @@ function hintFor(error: ApiError): string {
 /** Runs the command and answers with its exit code. What it prints goes through `io`. */
 export async function runCli(argv: readonly string[], io: CliIo): Promise<number> {
   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: ConsoleSeen = {};
+  const watched: CliIo = {
+    ...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") {
@@ -2097,15 +2254,21 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<number
     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) {
       io.stderr(`${error.message}\n`);
       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;
   }

package/src/cli/format.ts

@@ -314,9 +314,14 @@ function progressOf(goal: RestGoal): string {
   return `${counts.done}/${total} done${working === 0 ? "" : `, ${working} in progress`}${counts.dropped === 0 ? "" : `, ${counts.dropped} dropped`}`;
 }
 
-/** One goal: its id, its state, its title, when it is due, and how far it is. */
+/** One goal: its id, its state, its title, its category, its days, and how far it is. */
 export function formatGoalLine(goal: RestGoal): string {
-  const notes = [goal.dueOn === null ? "no target day" : `due ${goal.dueOn}`, progressOf(goal)];
+  const notes = [
+    ...(goal.category === null ? [] : [goal.category.key]),
+    ...(goal.startsOn === null ? [] : [`starts ${goal.startsOn}`]),
+    goal.dueOn === null ? "no target day" : `due ${goal.dueOn}`,
+    progressOf(goal),
+  ];
   return `${goal.id}  ${goal.state}  ${goal.title}  (${notes.join("; ")})`;
 }
 
@@ -324,7 +329,7 @@ export function formatGoalLine(goal: RestGoal): string {
 export function formatGoal(goal: RestGoal, tasks?: readonly RestTask[]): string {
   const lines = [
     `goal ${goal.id}: ${goal.title}`,
-    `state: ${goal.state}  due: ${goal.dueOn ?? "none"}  set by: ${goal.createdBy.login}`,
+    `state: ${goal.state}  category: ${goal.category?.key ?? "none"}  starts: ${goal.startsOn ?? "none"}  due: ${goal.dueOn ?? "none"}  set by: ${goal.createdBy.login}`,
     `progress: ${progressOf(goal)}`,
   ];
   if (goal.body.trim().length > 0) {

package/src/cli/help.ts

@@ -135,22 +135,24 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     refusals: ["task.not_found: no task has that number or id", ...TASK_FIELD_REFUSALS],
   },
   goals: {
-    usage: "goals",
+    usage: "goals [--category <key>] [--state <state>]",
     about:
-      "The roadmap of the project: its goals, the active first, each with its id, its state (planned, active, done, dropped), its target day, and how far it is, counted from the tasks that work towards it.",
+      "The roadmap of the project: its goals, the active first, each with its id, its state (planned, active, done, dropped), its category, the days it starts and is meant to be reached by, and how far it is, counted from the tasks that work towards it. --category keeps those sorted into one, --state those in one state.",
   },
   goal: {
     usage:
-      'goal <id>  |  goal new "<title>" [--body <markdown>|--file <path>] [--state <state>] [--due <day>]  |  goal edit <id> [--title <title>] [--body <markdown>|--file <path>] [--state <state>] [--due <day|none>]',
+      'goal <id>  |  goal new "<title>" [--body <markdown>|--file <path>] [--state <state>] [--category <key>] [--starts <day>] [--due <day>]  |  goal edit <id> [--title <title>] [--body <markdown>|--file <path>] [--state <state>] [--category <key|none>] [--starts <day|none>] [--due <day|none>]',
     about:
-      "One goal in full, with the tasks that work towards it; or a goal set on the roadmap, for an owner of the project; or one changed, only in what the flags say. A task works towards a goal through its --goal.",
+      "One goal in full, with the tasks that work towards it; or a goal set on the roadmap, for an owner of the project; or one changed, only in what the flags say, where none clears a category or a day. A goal is planned in days as a task is, a start and a target, and sorted into a category of the workspace (console categories). A task works towards a goal through its --goal.",
     limits: [
       `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
       `body: ${MARKDOWN}`,
-      `due: ${DAY}`,
+      `starts, due: ${DAY}`,
     ],
     refusals: [
       "goal.not_found: no goal of this project has that id",
+      "goal.invalid_category: no category of the workspace has that key",
+      "goal.invalid_dates: the target day is before the start",
       "auth.forbidden: only an owner of the project sets its roadmap",
     ],
   },

package/src/cli/install.ts

@@ -0,0 +1,111 @@
+// Where the command runs from, so that the update it is told to make is the one that takes
+// effect: installed for the machine, in a project, run once from a cache, or a checkout of the
+// repository. Read from the package's own path and the working directory; nothing is asked of
+// the system, so that a notice about versions costs a command nothing.
+
+export type InstallKind = "global" | "project" | "temporary" | "checkout";
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+export interface Install {
+  readonly kind: InstallKind;
+  readonly manager: PackageManager;
+  /** The directory the package is installed in: a project's root, the machine's global one, a cache's; the checkout itself. */
+  readonly root: string;
+}
+
+export interface InstallClues {
+  /** The package's own directory, where its manifest is. */
+  readonly packageDir: string;
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly exists: (path: string) => boolean;
+}
+
+const PACKAGE = "@skillcdn/console";
+
+const slashes = (path: string): string => path.replaceAll("\\", "/").replace(/\/+$/, "");
+
+/** The package manager that ran this command, when one did: `pnpm exec`, `npx` and their kind say so. */
+function managerRunning(env: InstallClues["env"]): PackageManager | undefined {
+  const agent = env.npm_config_user_agent ?? "";
+  for (const manager of ["pnpm", "yarn", "bun", "npm"] as const) {
+    if (agent.startsWith(`${manager}/`)) {
+      return manager;
+    }
+  }
+  return undefined;
+}
+
+export function detectInstall(clues: InstallClues): Install {
+  const dir = slashes(clues.packageDir);
+  const cwd = slashes(clues.cwd);
+  const at = dir.indexOf("/node_modules/");
+  if (at < 0) {
+    return { kind: "checkout", manager: "pnpm", root: dir };
+  }
+  const root = dir.slice(0, at);
+  const lower = dir.toLowerCase();
+  const running = managerRunning(clues.env);
+  // What `npx`, `pnpm dlx`, `yarn dlx` and `bunx` fetch into a cache lives only for the run.
+  if (/\/(_npx|dlx|dlx-[^/]*)\//.test(lower) || lower.includes("/.bun/install/cache/")) {
+    const manager =
+      running ??
+      (lower.includes("/_npx/") ? "npm" : lower.includes("/.bun/install/cache/") ? "bun" : "pnpm");
+    return { kind: "temporary", manager, root };
+  }
+  if (cwd === root || cwd.startsWith(`${root}/`)) {
+    const manager: PackageManager = clues.exists(`${root}/pnpm-lock.yaml`)
+      ? "pnpm"
+      : clues.exists(`${root}/yarn.lock`)
+        ? "yarn"
+        : clues.exists(`${root}/bun.lock`) || clues.exists(`${root}/bun.lockb`)
+          ? "bun"
+          : (running ?? "npm");
+    return { kind: "project", manager, root };
+  }
+  const manager: PackageManager = /\/pnpm\/global\/|\/\.pnpm-global\//.test(lower)
+    ? "pnpm"
+    : lower.includes("/yarn/global/")
+      ? "yarn"
+      : lower.includes("/.bun/install/global/")
+        ? "bun"
+        : "npm";
+  return { kind: "global", manager, root };
+}
+
+/** The command that puts the version named where this command is installed. */
+export function updateCommandFor(install: Install, version: string): string {
+  const spec = `${PACKAGE}@${version}`;
+  switch (install.kind) {
+    case "global":
+      return install.manager === "npm"
+        ? `npm install -g ${spec}`
+        : install.manager === "yarn"
+          ? `yarn global add ${spec}`
+          : `${install.manager} add -g ${spec}`;
+    case "project":
+      return `${install.manager === "npm" ? "npm install" : `${install.manager} add`} ${spec}`;
+    case "temporary":
+      return install.manager === "npm"
+        ? `npx ${spec}`
+        : install.manager === "bun"
+          ? `bunx ${spec}`
+          : `${install.manager} dlx ${spec}`;
+    case "checkout":
+      return "git pull && pnpm install && pnpm build";
+  }
+}
+
+/** Where the command is installed, in words: what `whoami` and `--version` say. */
+export function describeInstall(install: Install): string {
+  switch (install.kind) {
+    case "global":
+      return `installed for the machine with ${install.manager} in ${install.root}`;
+    case "project":
+      return `installed in the project at ${install.root} with ${install.manager}`;
+    case "temporary":
+      return `fetched for this run by ${install.manager}`;
+    case "checkout":
+      return `built from the checkout at ${install.root}`;
+  }
+}

package/src/cli/main.ts

@@ -5,21 +5,28 @@ import { hostname } from "node:os";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import * as z from "zod/mini";
+import { userAgentOf } from "../compat.js";
 import { runCli } from "./cli.js";
 import { createFileStore, defaultConfigDir } from "./credentials.js";
 import { createDirectoryStore } from "./directory.js";
+import { detectInstall } from "./install.js";
+import { createNoticeStore } from "./notices.js";
 import { listenOn } from "./serve.js";
 import { readBytesAt, readFileAt, readStdin, writeBytesAt } from "./terminal.js";
 
 // The `console` command: the only place the command reads the process. Everything it does is in
 // cli.ts, which takes what it needs and is what the tests run.
 
-/** The version of the package this file runs from: its own manifest, two levels above dist/cli. */
+/** The package's own directory, two levels above dist/cli: where its manifest and its skills are. */
+const packageDir = fileURLToPath(new URL("../../", import.meta.url));
+/** The version of the package this file runs from: its own manifest. */
 const manifest = z
   .object({ version: z.string() })
   .safeParse(createRequire(import.meta.url)("../../package.json"));
+const version = manifest.success ? manifest.data.version : undefined;
 /** 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));
+const configDir = defaultConfigDir(process.env);
 
 process.exitCode = await runCli(process.argv.slice(2), {
   env: process.env,
@@ -35,11 +42,24 @@ process.exitCode = await runCli(process.argv.slice(2), {
   readFile: readFileAt,
   readBytes: readBytesAt,
   writeBytes: writeBytesAt,
-  store: createFileStore(defaultConfigDir(process.env)),
+  store: createFileStore(configDir),
   directory: createDirectoryStore(process.cwd()),
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
   now: () => Date.now(),
-  version: manifest.success ? manifest.data.version : undefined,
+  version,
+  // The command names itself on every request, and where it runs, so that the console holds it
+  // to the versions it takes and the access log says which commands are about (ADR-0025).
+  userAgent:
+    version === undefined
+      ? undefined
+      : userAgentOf(version, `cli; node ${process.versions.node}; ${process.platform}`),
+  install: detectInstall({
+    packageDir,
+    cwd: process.cwd(),
+    env: process.env,
+    exists: existsSync,
+  }),
+  notices: createNoticeStore(configDir),
   skillsDir: existsSync(skillsDir) ? skillsDir : undefined,
   listen: listenOn,
 });

package/src/cli/notices.ts

@@ -0,0 +1,48 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import * as z from "zod/mini";
+
+// What the command last said about the versions, kept beside the credentials, so that it says
+// it once a day for one pair of versions and not on every command an agent runs. A notice is
+// not worth failing a command for: a file that cannot be read or written is as good as none.
+
+export interface VersionNotice {
+  /** The version of the command that noticed. */
+  readonly command: string;
+  /** The version of the console it noticed. */
+  readonly console: string;
+  readonly shownAt: string;
+}
+
+export interface NoticeStore {
+  load(): Promise<VersionNotice | undefined>;
+  save(notice: VersionNotice): Promise<void>;
+}
+
+const noticesSchema = z.object({
+  versions: z.optional(z.object({ command: z.string(), console: z.string(), shownAt: z.string() })),
+});
+
+const FILE_NAME = "notices.json";
+
+export function createNoticeStore(directory: string): NoticeStore {
+  const path = join(directory, FILE_NAME);
+  return {
+    async load() {
+      try {
+        const parsed = noticesSchema.safeParse(JSON.parse(await readFile(path, "utf8")));
+        return parsed.success ? parsed.data.versions : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    async save(notice) {
+      try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await writeFile(path, `${JSON.stringify({ versions: notice }, null, 2)}\n`);
+      } catch {
+        // Said this time; said again next time.
+      }
+    },
+  };
+}