@wirecat/cli-core 0.343.0 → 0.345.0

package/CHANGELOG.md

@@ -7,6 +7,85 @@ shape of this file.
 
 ## Unreleased
 
+## 0.345.0 — 18.10.2026
+
+### Added
+
+- **`gatherProjectEvidence` collects cited evidence for one project** from explicitly selected stored messages,
+  mail and imported documents: the project name, aliases, keywords and people's names are alternative search
+  lanes, the window defaults to 60 days and is read in 90-day chunks, every invocation has its own read, byte,
+  time and item budgets, and an opaque reference-only checkpoint resumes the run with its window frozen. An
+  optional host fetch port runs first; a failed fetch or source is reported as coverage, never as absence. It
+  writes nothing. See `docs/dev/PROJECT-GATHERING.md`.
+- **`<tool> guide [name]`: scenarios, the commands for a common task in order** (`guideCommand(app, { directory,
+  worksWith?, profile? })` from `@wirecat/cli-core/cli`). The list names each scenario and, under "Works with",
+  the ones another tool holds (`memo guide person-brief`); one scenario prints its goal, each step as a command and
+  why, and what to look at; `--json` gives the same as data. The source is one Markdown file per scenario with
+  front matter (`title`, `goal`, `steps: [{ run, why }]`, `look`) in a directory the tool ships and names.
+  `guide` takes no profile and is not an MCP tool. `await checkGuide(() => program, { packageRoot })` is for the
+  tool's CI: each step's command path exists and its options and arguments parse, with no account and no network,
+  and the directory is in the package's `files`. The first screen's "Next" names `guide` once a tool mounts it. The
+  peer range takes cli-base 0.46 too (`>=0.45.0 <0.47.0`): `cli-dev lint` knows `guide` from 0.46.0 on.
+- **The run record of a one-shot command's passive listen counts what it received**: the `adapter.listen`
+  response carries `counts` by event (`message`, `edit`, …), as `messages.watch` does, so a run shows how many
+  messages a store-history messenger handed on and saved during the command.
+- **Every leaf command's `--help` ends with Returns, Next usually and Example**, worked out from its definition when
+  the help is shown. Returns names the declared output entity and its first fields, or repeats the description
+  when there is none. Next usually lists up to three commands whose arguments take what this one returns (a
+  message, a chat, a person, a task…), reads first; `nextUsually(command, { pin, drop })` overrides them. Example
+  is the definition's own `examples`, or one built from the usage, a sample value per argument (`Team`, `1234`,
+  `"invoice"`) and the mandatory options. Examples leave out the profile, as the first screen does; the Usage line
+  shows `<profile>`.
+  `commandHelpMarkdown(root, path)` gives the same three lines for `docs/commands.md`, and
+  `exampleReport(program)` lists the commands still on a generated example.
+- **`contacts alias set|rm`, `contacts notes list|show|add|edit|remove`, `conversations consents list|revoke` and
+  `bot sends list` have descriptions**, in `--help`, `commands` and the commands document.
+
+### Fixed
+
+- **`inbox` and `review` declare their output**: they named the view `message.summary`, so the entity looked
+  up was `message.message.summary`, which does not exist. `commands schema inbox` now gives the message summary's
+  fields instead of open items, and `--help` ends with "Returns: message summary — …". `--json=<fields>` is now
+  checked against those fields, so a name they do not have is refused with the list instead of giving empty items.
+  The JSON they print is unchanged.
+- **`--brief` and `--full` no longer mention mail in a messenger's help.** They said "found messages and mail"; tg,
+  max and wa have no mail. Consumers' help snapshots change on bump.
+
+## 0.344.0 — 18.10.2026
+
+### Changed — may break callers
+
+- **`<tool> --help` and a bare `<tool>` show a short first screen instead of commander's full help**: the tool's
+  pitch, the usage line, one sentence that account commands start with the profile, what the tool can do, the other
+  WireCat tools, and where to go next (`commands`, `help options`, `skill show`, and `setup` or `guide` when the tool
+  has them). It no longer lists every command or the options for every command, so a test that looks for a command
+  or a global option in the root `--help` must read `--help-all`, which prints the old help, or `help options`.
+  Exit codes are unchanged: `--help` exits 0, a bare run exits 2.
+- **`<tool> commands` without `--json` prints a text list, by section, even when piped.** It printed the whole JSON
+  document (hundreds of kilobytes) to any reader that was not a terminal, and a table in one. Now every command that
+  runs is one line — its usage and the first clause of its description, `(writes)` when it changes something —
+  under Read, Write, Organise, Automate, Set up or Other. `commands <path>` narrows it. `--json` and `--jsonl` print
+  the same document as before; only the `commands` command's own description changed. A script that parsed the
+  output of a bare `commands` must pass `--json`.
+
+### Added
+
+- **`registerCommands(server, prefix, commands)` and the `McpCommand` type** (`@wirecat/cli-core/mcp`): the three
+  tools `<prefix>_tools_search`, `<prefix>_read` and `<prefix>_write` that tg and max serve in place of one tool per
+  command. A CLI without the messenger `mcpCommand`, such as drive, can now serve its own commands the same way.
+- **`ProgramDefinition.firstScreen` and `installHelp(program, screen)`** (`@wirecat/cli-core/cli`): a tool
+  supplies its `pitch` and 6–8 `can` lines (`{ command, does }`, the command without the profile);
+  `installHelp` puts the same screen on a program the tool builds itself, with `profile: false` for a tool
+  whose commands take no leading profile and `start` for its first command. A tool that supplies nothing gets its
+  description and no "What you can do" block.
+- **`<tool> help options`** prints the options for every command; `help <command>` prints that command's help.
+  `help` and `--help-all` are hidden, so `commands --json` and the MCP tools are unchanged.
+- **`inSection(command, section)` and `SECTIONS`** (`@wirecat/cli-core/cli`): where `commands` lists a group and
+  everything under it — `read`, `write`, `organise`, `automate` or `setup`; a command without one, or under none,
+  is listed under Other. `createProgram` puts cli-core's own groups (`chats`, `messages`, `tags`, `schedule`,
+  `config`…) in theirs; a tool sets its own groups (`session`, `setup`). The section is kept off the commands
+  document.
+
 ## 0.343.0 — 18.10.2026
 
 ### Added
@@ -54,6 +133,20 @@ shape of this file.
   permission governs those commands. Commands that a profile's permissions govern still need one.
 - **`serve`'s relay socket fits on macOS with a deep `TMPDIR`.** When the temporary folder is too deep for a socket
   path too, the socket goes under `/tmp` (still in an owner-only folder). It made tg's macOS release check fail.
+- **Help and errors say what a person typed.** The usage line of every command that uses a profile now reads
+  `<tool> <profile> …` (`Usage: tg <profile> mcp`); `commands`, `complete`, `help`, `skill` and `upgrade` keep the bare
+  form. Consumers' help snapshots change with this version.
+- A command that takes a free query (`chats list`, `meetings list`, `meetings projects evidence`) refuses a word that
+  starts with `--` as an unknown option, with commander's suggestion (`unknown option '--limt' (Did you mean
+  --limit?)`), instead of reading it as query text; a negated term like `-kind:channel` is still query, and after `--`
+  every word is.
+- A commander error is one line: `unknown command 'chts' (Did you mean chats?) …`.
+- The profile may follow global options: `tg --json personal chats list` works.
+- `complete --help` prints the help and exits 0.
+- A bot with no token, given a chat by name, says to store a token (exit 4) instead of "no chat matches".
+- "nothing recorded for profile" says "run the command once without --offline" only when `--offline` was given, and
+  names the profile in `serve`/`watch`.
+- `mcp setup` says "1 tool that may write"; the search help calls memo "the separate memo CLI".
 
 ### Security
 

package/dist/cli/bot/command.js

@@ -159,7 +159,9 @@ const recipientsCommand = (bot) => {
 };
 const sendsCommand = (bot) => new Command("sends")
     .description("what this bot sent, edited and deleted from this machine — ids and outcomes, never text")
-    .addCommand(annotate(new Command("list"), { effects: LOCAL_READ }).action(async function () {
+    .addCommand(annotate(new Command("list"), { effects: LOCAL_READ })
+    .description("every send, edit and delete this bot made from this machine, with its outcome")
+    .action(async function () {
     const context = botContext(this, bot);
     await context.run(async () => renderAnswer(this, context, wholeList("bot sends list", context.journal().entries().map(snakeKeys))));
 }));

package/dist/cli/bot/context.js

@@ -29,6 +29,7 @@ export const botContext = (command, bot) => {
         base.track(adapter);
         return adapter;
     };
+    const noToken = () => new CliError("authentication_error", `no bot token for profile "${profile}" — run \`${words} auth set\``);
     return {
         ...base,
         profile,
@@ -64,7 +65,11 @@ export const botContext = (command, bot) => {
             const trimmed = typed.trim();
             if (/^-?\d+$/.test(trimmed) || /^user:\d+$/.test(trimmed))
                 return trimmed;
-            return pickChat(trimmed, registry.list()).id;
+            const known = registry.list();
+            // A bot that never had a token has seen no chat, and its missing token is what needs fixing.
+            if (known.length === 0 && !tokens.read())
+                throw noToken();
+            return pickChat(trimmed, known).id;
         },
         readSecret: (prompt) => {
             return bot.readSecret?.(command, prompt) ?? readSecret(prompt, secretInputOf(command));
@@ -74,9 +79,8 @@ export const botContext = (command, bot) => {
         /** A client for the stored token, or a refusal that says how to store one. */
         authenticated: (options = {}) => {
             const stored = tokens.read();
-            if (!stored) {
-                throw new CliError("authentication_error", `no bot token for profile "${profile}" — run \`${words} auth set\``);
-            }
+            if (!stored)
+                throw noToken();
             return connect(stored.token, options);
         },
     };

package/dist/cli/command-contract.d.ts

@@ -1,6 +1,19 @@
 import type { Command } from "commander";
 export type JsonSchema = Record<string, unknown>;
 export declare const SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+/**
+ * What `--json` prints, from the entity the command declares (`annotate(…, { output })`): a list or one thing of it.
+ * A command that declares none answers the same envelopes with items of any shape; `--jsonl` streams the items.
+ */
+export declare const outputOf: (command: Command) => {
+    schema: {
+        [x: string]: unknown;
+    };
+    item: {
+        [x: string]: unknown;
+    };
+    coverage: string;
+};
 export declare const commandPathOf: (command: Command) => string[];
 export declare const findCommand: (root: Command, path: readonly string[]) => Command;
 export declare const commandContract: (command: Command) => {

package/dist/cli/command-contract.js

@@ -9,7 +9,7 @@ export const SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
  * What `--json` prints, from the entity the command declares (`annotate(…, { output })`): a list or one thing of it.
  * A command that declares none answers the same envelopes with items of any shape; `--jsonl` streams the items.
  */
-const outputOf = (command) => {
+export const outputOf = (command) => {
     const output = metaOf(command).output;
     const entity = output
         ? ENTITIES[(output.view ? `${output.entity}.${output.view}` : output.entity)]

package/dist/cli/commands-command.js

@@ -1,11 +1,12 @@
 import { CliError, EXIT_CODES, GENERIC_FAILURE } from "@wirecat/cli-base";
-import { annotate, describeOptions, describeProgram, flatten } from "@wirecat/cli-base/commands";
-import { CRASH_CODE, writes } from "@wirecat/cli-base/standards";
+import { annotate, describeOptions, describeProgram } from "@wirecat/cli-base/commands";
+import { CRASH_CODE } from "@wirecat/cli-base/standards";
 import { Command } from "commander";
 import { commandContract, findCommand } from "./command-contract.js";
-import { outputFor } from "./context.js";
+import { environmentOf, outputFor } from "./context.js";
 import { NO_EFFECTS } from "./effects.js";
 import { renderDocument } from "./envelope.js";
+import { commandsText } from "./help/commands-text.js";
 import { rootOf } from "./profile.js";
 /**
  * The major version of the JSON every command prints. The output types live in this package, so the
@@ -18,22 +19,18 @@ export const CONTRACT = 3;
  */
 export const commandsCommand = (app) => {
     const command = annotate(new Command("commands"), { effects: NO_EFFECTS })
-        .description("commands, options and exit codes as JSON — inspect one command path per call")
+        .description("every command by section, one line each; --json: the contract, one path per call")
         .argument("[path...]", "one command path, for example: search messages; inspect other groups in separate calls")
         .action(function (path) {
         const root = rootOf(this);
         const output = outputFor(this);
-        const { renderer, format } = output;
         const all = describeProgram(root);
         const scoped = path.length > 0 ? scopeOf(root, all, path) : undefined;
         const commands = scoped ? [scoped.command] : all;
-        if (format === "pretty") {
-            renderer.result(flatten(commands).map(({ usage, summary, description, effects, state }) => ({
-                command: usage,
-                description: summary ?? description,
-                writes: effects !== undefined && writes(effects) ? "yes" : "",
-                ...(state ? { state } : {}),
-            })));
+        const { json, jsonl } = this.optsWithGlobals();
+        // Asked by format, not by terminal: piped, an agent got the whole JSON tree it never asked for.
+        if (json === undefined && !jsonl && !environmentOf(this).agent) {
+            output.streams.data(commandsText(root, commands, scoped?.command.path).replace(/\n$/, ""));
             return;
         }
         renderDocument(output, {

package/dist/cli/context.d.ts

@@ -33,6 +33,8 @@ export interface BaseEnvironment {
     platform?: NodeJS.Platform;
     /** The local speech recognizer in place of the downloaded model; tests hand one in. */
     recognizer?: OpenRecognizer;
+    /** How long `store restore` and `store reset` wait on another connection's write, 1 s unless a test hands one in. */
+    storeLockWaitMs?: number;
     /** Where raw bytes go when stdout is not this process's own — an MCP session relayed by serve. */
     stdout?: NodeJS.WritableStream;
     /** Where a prompt and what is typed at it go, in place of the process's stderr; tests hand one in. */

package/dist/cli/guide.d.ts

@@ -0,0 +1,52 @@
+import { Command } from "commander";
+import type { AppIdentity } from "../ports/app.js";
+export interface GuideStep {
+    /** The command as a person types it: the tool's name first, no profile — `tg review --since 1d`. */
+    run: string;
+    why: string;
+}
+export interface Scenario {
+    name: string;
+    title: string;
+    goal: string;
+    steps: GuideStep[];
+    look: string[];
+}
+/** A scenario another tool holds — memo's cross-tool ones — listed by reference under "Works with". */
+export interface GuideReference {
+    tool: string;
+    name: string;
+    title: string;
+}
+export interface GuideOptions {
+    /** Absolute path of the tool's scenario files: `fileURLToPath(new URL("../scenarios", import.meta.url))`. */
+    directory: string;
+    worksWith?: readonly GuideReference[];
+    /** `false` for a tool whose commands take no leading profile. */
+    profile?: boolean;
+}
+/** One scenario file, or what is wrong with it. The Markdown body is for the site's page; the CLI reads none of it. */
+export declare const parseScenario: (file: string, content: string) => Promise<{
+    scenario?: Scenario;
+    problems: string[];
+}>;
+export declare const loadScenarios: (directory: string) => Promise<{
+    scenarios: Scenario[];
+    problems: string[];
+}>;
+/**
+ * `<tool> guide` lists the tool's scenarios and the ones it works with; `<tool> guide <name>` prints one: the goal,
+ * each step as a command and why, and what to look at. The files are read when the command runs, never when the
+ * program is built. `checkGuide` validates them in the tool's CI.
+ */
+export declare const guideCommand: (app: Pick<AppIdentity, "command">, options: GuideOptions) => Command;
+/** What is wrong with one step on this program: the path, each option and its value, the arguments. Never runs it. */
+export declare const checkStep: (program: Command, run: string) => string[];
+/**
+ * For a tool's CI: every scenario file parses, and each step's command exists and its options and arguments parse
+ * on a program built fresh per step — no account, no network, no action runs. With `packageRoot`, the scenario
+ * directory must also be in the package's `files`, so it ships. Returns the problems; empty means sound.
+ */
+export declare const checkGuide: (build: () => Command, { packageRoot }?: {
+    packageRoot?: string;
+}) => Promise<string[]>;

package/dist/cli/guide.js

@@ -0,0 +1,307 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { basename, join, relative, resolve, sep } from "node:path";
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command } from "commander";
+import { environmentOf, outputFor } from "./context.js";
+import { NO_EFFECTS } from "./effects.js";
+import { itemOf, listOf, renderAnswer } from "./envelope.js";
+import { PROFILE_FREE } from "./profile.js";
+const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+const FIELDS = new Set(["title", "goal", "steps", "look"]);
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const text = (value) => typeof value === "string" && value.trim().length > 0;
+/** One scenario file, or what is wrong with it. The Markdown body is for the site's page; the CLI reads none of it. */
+export const parseScenario = async (file, content) => {
+    const name = basename(file, ".md");
+    const at = (problem) => `${basename(file)}: ${problem}`;
+    if (!NAME.test(name))
+        return { problems: [at("the file name is the scenario's name: lower case words and dashes")] };
+    const match = FRONT_MATTER.exec(content);
+    if (!match)
+        return { problems: [at("needs front matter between --- lines")] };
+    // Loaded here, not at the top: every tool start loads this module, and only `guide` reads YAML.
+    const { parseDocument } = await import("yaml");
+    const yaml = parseDocument(match[1] ?? "", { uniqueKeys: true });
+    if (yaml.errors.length > 0)
+        return { problems: [at("front matter is not valid YAML")] };
+    const data = yaml.toJS({ maxAliasCount: 0 });
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return { problems: [at("front matter is not a map")] };
+    const fields = data;
+    const problems = Object.keys(fields)
+        .filter((key) => !FIELDS.has(key))
+        .map((key) => at(`unknown field ${key}; the fields are ${[...FIELDS].join(", ")}`));
+    if (!text(fields.title))
+        problems.push(at("title is a line of text"));
+    if (!text(fields.goal))
+        problems.push(at("goal is a line of text"));
+    const steps = Array.isArray(fields.steps) ? fields.steps : [];
+    if (steps.length === 0)
+        problems.push(at("steps is a list of { run, why }"));
+    steps.forEach((step, index) => {
+        const one = (step ?? {});
+        if (!text(one.run) || !text(one.why))
+            problems.push(at(`step ${index + 1} needs run and why`));
+    });
+    const look = typeof fields.look === "string" ? [fields.look] : fields.look;
+    if (!Array.isArray(look) || look.length === 0 || !look.every(text))
+        problems.push(at("look is what to look at in the output: a line or a list of lines"));
+    if (problems.length > 0)
+        return { problems };
+    return {
+        scenario: {
+            name,
+            title: String(fields.title).trim(),
+            goal: String(fields.goal).trim(),
+            steps: steps.map(({ run, why }) => ({ run: run.trim(), why: why.trim() })),
+            look: look.map((line) => line.trim()),
+        },
+        problems: [],
+    };
+};
+export const loadScenarios = async (directory) => {
+    let files;
+    try {
+        files = readdirSync(directory).filter((file) => file.endsWith(".md") && file.toLowerCase() !== "readme.md");
+    }
+    catch {
+        return { scenarios: [], problems: [`${directory}: no such directory`] };
+    }
+    const parsed = await Promise.all(files.sort().map((file) => parseScenario(file, readFileSync(join(directory, file), "utf8"))));
+    return {
+        scenarios: parsed.flatMap(({ scenario }) => (scenario ? [scenario] : [])),
+        problems: parsed.flatMap(({ problems }) => problems),
+    };
+};
+const guides = new WeakMap();
+const rows = (pairs) => {
+    const width = pairs.reduce((most, [left]) => Math.max(most, left.length), 0) + 2;
+    return pairs.map(([left, right]) => `  ${left.padEnd(width)}${right}`);
+};
+const listText = (cli, scenarios, worksWith) => [
+    scenarios.length > 0 ? `Scenarios — ${cli} guide <name> for the steps:` : `${cli} has no scenarios yet.`,
+    ...rows(scenarios.map((one) => [one.name, one.title])),
+    ...(worksWith.length > 0
+        ? ["", "Works with:", ...rows(worksWith.map((one) => [`${one.tool} guide ${one.name}`, one.title]))]
+        : []),
+].join("\n");
+const needsProfile = (cli, run) => {
+    const [tool, first] = words(run);
+    return tool === cli && first !== undefined && !first.startsWith("-") && !PROFILE_FREE.has(first);
+};
+const scenarioText = (cli, scenario, profile) => [
+    scenario.title,
+    "",
+    `Goal: ${scenario.goal}`,
+    "",
+    profile && scenario.steps.some((step) => needsProfile(cli, step.run))
+        ? `Steps — account commands start with your profile: ${cli} <profile> …`
+        : "Steps:",
+    ...scenario.steps.flatMap((step, index) => [`  ${index + 1}. ${step.run}`, `     ${step.why}`]),
+    "",
+    "Look at:",
+    ...scenario.look.map((line) => `  - ${line}`),
+].join("\n");
+/**
+ * `<tool> guide` lists the tool's scenarios and the ones it works with; `<tool> guide <name>` prints one: the goal,
+ * each step as a command and why, and what to look at. The files are read when the command runs, never when the
+ * program is built. `checkGuide` validates them in the tool's CI.
+ */
+export const guideCommand = (app, options) => {
+    const command = annotate(new Command("guide"), {
+        effects: NO_EFFECTS,
+        mcp: false,
+        examples: [`${app.command} guide`, `${app.command} guide <name> --json`],
+    })
+        .description("scenarios: the commands for a common task, in order, and why each")
+        .argument("[name]", "one scenario; without it, the list")
+        .action(async function (name) {
+        const cli = app.command;
+        const { scenarios, problems } = await loadScenarios(options.directory);
+        if (problems.length > 0)
+            throw new CliError("configuration_error", `broken scenario files: ${problems.join("; ")}`);
+        const worksWith = options.worksWith ?? [];
+        const output = outputFor(this);
+        const { json, jsonl } = this.optsWithGlobals();
+        const asText = json === undefined && !jsonl && !environmentOf(this).agent;
+        if (name === undefined) {
+            const items = [
+                ...scenarios.map(({ name, title, goal }) => ({
+                    tool: cli,
+                    name,
+                    title,
+                    goal,
+                    command: `${cli} guide ${name}`,
+                })),
+                ...worksWith.map(({ tool, name, title }) => ({ tool, name, title, command: `${tool} guide ${name}` })),
+            ];
+            if (asText)
+                output.streams.data(listText(cli, scenarios, worksWith));
+            else
+                renderAnswer(this, output, listOf("guide", { items, limit: Math.max(1, items.length), has_more: false }));
+            return;
+        }
+        const scenario = scenarios.find((one) => one.name === name);
+        if (!scenario) {
+            const elsewhere = worksWith.find((one) => one.name === name);
+            throw new CliError("not_found", elsewhere
+                ? `"${name}" is ${elsewhere.tool}'s scenario: ${elsewhere.tool} guide ${name}`
+                : `no scenario "${name}"; ${cli} guide lists them`, { name, available: scenarios.map((one) => one.name) });
+        }
+        if (asText)
+            output.streams.data(scenarioText(cli, scenario, options.profile !== false));
+        else
+            renderAnswer(this, output, itemOf(scenario));
+    });
+    guides.set(command, options);
+    return command;
+};
+/** A step's words, split as a shell would on spaces, with "…" and '…' kept together. */
+const words = (line) => {
+    const found = [];
+    let word;
+    let quote;
+    for (const char of line) {
+        if (quote) {
+            if (char === quote)
+                quote = undefined;
+            else
+                word = (word ?? "") + char;
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+            word ??= "";
+        }
+        else if (/\s/.test(char)) {
+            if (word !== undefined)
+                found.push(word);
+            word = undefined;
+        }
+        else
+            word = (word ?? "") + char;
+    }
+    if (word !== undefined)
+        found.push(word);
+    return found;
+};
+const silent = (command) => command.exitOverride().configureOutput({ writeOut: () => { }, writeErr: () => { }, outputError: () => { } });
+const ownerOf = (chain, flag) => {
+    for (const owner of chain) {
+        const option = owner.options.find((one) => one.long === flag || one.short === flag);
+        if (option)
+            return { owner, option };
+    }
+    return undefined;
+};
+/** What is wrong with one step on this program: the path, each option and its value, the arguments. Never runs it. */
+export const checkStep = (program, run) => {
+    const [tool, ...rest] = words(run);
+    if (tool !== program.name())
+        return [`starts with "${tool ?? ""}", not ${program.name()}`];
+    const chain = [program];
+    let at = program;
+    let index = 0;
+    for (; index < rest.length; index++) {
+        const next = at.commands.find((one) => one.name() === rest[index] || one.aliases().includes(rest[index] ?? ""));
+        if (!next)
+            break;
+        chain.unshift(next);
+        at = next;
+    }
+    if (at === program)
+        return [`no command "${rest[0] ?? ""}" — steps leave out the profile`];
+    if (at.commands.length > 0)
+        return [`needs one of: ${at.commands.map((one) => one.name()).join(", ")}`];
+    for (const command of chain)
+        silent(command);
+    const problems = [];
+    const operands = [];
+    const left = rest.slice(index);
+    for (let word = 0; word < left.length; word++) {
+        const token = left[word];
+        if (token === "--") {
+            operands.push(...left.slice(word + 1));
+            break;
+        }
+        if (!token.startsWith("-") || token === "-" || /^-\d/.test(token)) {
+            operands.push(token);
+            continue;
+        }
+        const flag = token.split("=")[0];
+        const found = ownerOf(chain, flag);
+        if (!found) {
+            problems.push(`no option ${flag}`);
+            continue;
+        }
+        const tokens = [token];
+        const takes = found.option.required || found.option.optional;
+        if (takes && !token.includes("=")) {
+            while (left[word + 1] !== undefined && !left[word + 1].startsWith("-")) {
+                tokens.push(left[++word]);
+                if (!found.option.variadic)
+                    break;
+            }
+            if (found.option.required && tokens.length === 1) {
+                problems.push(`${flag} needs a value`);
+                continue;
+            }
+        }
+        try {
+            found.owner.parseOptions(tokens);
+        }
+        catch (error) {
+            problems.push(`${flag}: ${error instanceof Error ? error.message.replace(/^error: /, "") : String(error)}`);
+        }
+    }
+    for (const option of at.options)
+        if (option.mandatory && at.getOptionValue(option.attributeName()) === undefined)
+            problems.push(`${option.long ?? option.flags} is required`);
+    const declared = at.registeredArguments;
+    const required = declared.filter((one) => one.required).length;
+    const unbounded = declared.at(-1)?.variadic === true;
+    if (operands.length < required)
+        problems.push(`needs ${declared
+            .filter((one) => one.required)
+            .map((one) => `<${one.name()}>`)
+            .join(" ")}`);
+    if (!unbounded && operands.length > declared.length)
+        problems.push(`takes ${declared.length} argument(s), got ${operands.length}: ${operands.join(" ")}`);
+    declared.forEach((argument, position) => {
+        const value = operands[position];
+        if (value !== undefined && argument.argChoices && !argument.argChoices.includes(value))
+            problems.push(`<${argument.name()}> is one of ${argument.argChoices.join(", ")}, not ${value}`);
+    });
+    return problems;
+};
+const covered = (files, path) => files.some((entry) => {
+    const plain = entry.replace(/(\/\*\*?)?(\/\*)?\/?$/, "").replace(/^\.\//, "");
+    return path === plain || path.startsWith(`${plain}/`);
+});
+/**
+ * For a tool's CI: every scenario file parses, and each step's command exists and its options and arguments parse
+ * on a program built fresh per step — no account, no network, no action runs. With `packageRoot`, the scenario
+ * directory must also be in the package's `files`, so it ships. Returns the problems; empty means sound.
+ */
+export const checkGuide = async (build, { packageRoot } = {}) => {
+    const guide = build().commands.find((one) => one.name() === "guide");
+    const options = guide ? guides.get(guide) : undefined;
+    if (!options)
+        return ["the program has no guideCommand"];
+    const { scenarios, problems } = await loadScenarios(options.directory);
+    for (const scenario of scenarios)
+        scenario.steps.forEach((step, index) => {
+            for (const problem of checkStep(build(), step.run))
+                problems.push(`${scenario.name}.md step ${index + 1} (${step.run}): ${problem}`);
+        });
+    for (const reference of options.worksWith ?? [])
+        if (!NAME.test(reference.name) || !text(reference.tool) || !text(reference.title))
+            problems.push(`works with ${reference.tool} ${reference.name}: needs tool, a lower-case name and a title`);
+    if (packageRoot !== undefined) {
+        const path = relative(resolve(packageRoot), resolve(options.directory)).split(sep).join("/");
+        const files = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")).files;
+        if (files !== undefined && !covered(files, path))
+            problems.push(`package.json files leaves out ${path}`);
+    }
+    return problems;
+};

package/dist/cli/help/command-help.d.ts

@@ -0,0 +1,30 @@
+import type { Command } from "commander";
+export interface NextChoice {
+    /** Command paths shown first, in this order: `messages context`. */
+    pin?: readonly string[];
+    /** Command paths never shown, though their arguments take what this one returns. */
+    drop?: readonly string[];
+}
+/** Overrides the "Next usually" a command's help derives from types. Kept off `annotate`, like its section. */
+export declare const nextUsually: <T extends Command>(command: T, choice: NextChoice) => T;
+export interface CommandHelp {
+    returns: string;
+    next: readonly string[];
+    examples: readonly string[];
+    /** `generated` until the definition has an example of its own; the examples report lists those. */
+    origin: "written" | "generated";
+}
+/** Returns, Next usually and Example for one command, from its definition alone. */
+export declare const commandHelp: (command: Command) => CommandHelp;
+/** The lines `--help` prints after a command's options. */
+export declare const commandHelpText: (command: Command) => string;
+/** The same, as Markdown lines for `docs/commands.md`: hand it to cli-base's `commandsPage` per command. */
+export declare const commandHelpMarkdown: (root: Command, path: readonly string[]) => string[];
+/** Puts Returns, Next usually and Example on every leaf command's `--help`, worked out when the help is shown. */
+export declare const installCommandHelp: (program: Command) => void;
+/** Which leaf commands still show a generated example, so the important ones get a written one. Report only. */
+export declare const exampleReport: (program: Command) => {
+    written: string[];
+    generated: string[];
+    text: string;
+};