@wirecat/cli-core 0.344.0 → 0.345.0

package/CHANGELOG.md

@@ -7,6 +7,50 @@ 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

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/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/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;
+};