@wirecat/cli-core 0.343.0 → 0.345.0

package/dist/cli/help/command-help.js

@@ -0,0 +1,218 @@
+import { metaOf } from "@wirecat/cli-base/commands";
+import { writes } from "@wirecat/cli-base/standards";
+import { commandPathOf, outputOf } from "../command-contract.js";
+import { commandAt } from "../steps.js";
+import { short } from "./commands-text.js";
+/** Argument names onto the kinds `domain/references.ts` names; a plural takes the same kind. */
+const ARGUMENT_KINDS = {
+    chat: "chat",
+    chats: "chat",
+    message: "message",
+    messages: "message",
+    post: "message",
+    person: "person",
+    people: "person",
+    task: "task",
+    meeting: "meeting",
+    folder: "folder",
+    folders: "folder",
+    topic: "topic",
+    note: "note",
+    document: "document",
+    model: "model",
+};
+/** What a command answers with, by its declared entity, onto the same kinds. */
+const ENTITY_KINDS = {
+    message: "message",
+    message_link: "message",
+    chat: "chat",
+    contact: "person",
+    member: "person",
+    person: "person",
+    task: "task",
+    meeting: "meeting",
+    meeting_details: "meeting",
+    meeting_hit: "meeting",
+    meeting_summary: "meeting",
+    folder: "folder",
+    topic: "topic",
+    note: "note",
+    document: "document",
+    model: "model",
+};
+/** The group a kind lives in, whose commands come first among the ones that take it. */
+const HOME = {
+    chat: "chats",
+    message: "messages",
+    person: "contacts",
+    task: "tasks",
+    meeting: "meetings",
+    folder: "folders",
+    topic: "topics",
+    note: "notes",
+    document: "documents",
+    model: "models",
+};
+const SAMPLES = {
+    chat: "Team",
+    message: "1234",
+    post: "1234",
+    person: "Anna",
+    people: "Anna",
+    task: "12",
+    meeting: "123",
+    folder: "Work",
+    topic: "General",
+    model: "default",
+    query: '"invoice"',
+    text: '"on my way"',
+    title: '"Weekly sync"',
+    name: "daily",
+    id: "1",
+    file: "./report.pdf",
+    link: "https://example.com/join/abc",
+    url: "https://example.com",
+    since: "1d",
+    duration: "1d",
+    limit: "20",
+};
+const MAX_NEXT = 3;
+const choices = new WeakMap();
+/** Overrides the "Next usually" a command's help derives from types. Kept off `annotate`, like its section. */
+export const nextUsually = (command, choice) => {
+    choices.set(command, choice);
+    return command;
+};
+const kindOfArgument = (argument) => ARGUMENT_KINDS[argument.name()];
+const leaves = (command) => command.commands
+    .filter((child) => !child._hidden)
+    .flatMap((child) => (child.commands.length === 0 ? [child] : leaves(child)));
+const rootOf = (command) => {
+    let at = command;
+    while (at.parent)
+        at = at.parent;
+    return at;
+};
+const call = (command) => [
+    rootOf(command).name(),
+    ...commandPathOf(command),
+    ...command.registeredArguments.map((one) => (one.required ? `<${one.name()}>` : `[${one.name()}]`)),
+].join(" ");
+const returnsOf = (command) => {
+    const output = metaOf(command).output;
+    const { item, coverage } = outputOf(command);
+    if (!output || coverage !== "declared-entity")
+        return short(command.summary() || command.description()) || "not declared";
+    const required = item.required ?? [];
+    const fields = [
+        ...required,
+        ...Object.keys(item.properties ?? {}).filter((name) => !required.includes(name)),
+    ];
+    const noun = (output.view ? `${output.entity} ${output.view}` : output.entity).replaceAll("_", " ");
+    const more = fields.length > 8 ? `, and ${fields.length - 8} more` : "";
+    const root = rootOf(command);
+    const schema = commandAt(root, "commands schema")
+        ? `; every field: ${root.name()} commands schema ${commandPathOf(command).join(" ")}`
+        : "";
+    return `${noun} — ${fields.slice(0, 8).join(", ")}${more}${schema}`;
+};
+const nextOf = (command) => {
+    const root = rootOf(command);
+    const choice = choices.get(command) ?? {};
+    const drop = new Set(choice.drop ?? []);
+    const pinned = (choice.pin ?? []).flatMap((path) => commandAt(root, path) ?? []);
+    const output = metaOf(command).output;
+    const kind = output ? ENTITY_KINDS[output.entity] : undefined;
+    const all = leaves(root);
+    const derived = kind
+        ? all
+            .filter((other) => other !== command && !pinned.includes(other))
+            .filter((other) => other.registeredArguments.some((argument) => kindOfArgument(argument) === kind))
+            .map((other, order) => ({ other, order }))
+            .sort((a, b) => {
+            const rank = (other) => [
+                Number(writes(metaOf(other).effects)),
+                Number(!other.registeredArguments.some((one) => one.required && kindOfArgument(one) === kind)),
+                Number(commandPathOf(other)[0] !== HOME[kind]),
+                Number(other.parent !== command.parent),
+            ];
+            const [left, right] = [rank(a.other), rank(b.other)];
+            return left.reduce((found, value, at) => found || value - (right[at] ?? 0), 0) || a.order - b.order;
+        })
+            .map(({ other }) => other)
+        : [];
+    return [...pinned, ...derived].filter((other) => !drop.has(commandPathOf(other).join(" "))).slice(0, MAX_NEXT);
+};
+const sample = (name) => SAMPLES[name] ?? `<${name}>`;
+const generatedExample = (command) => {
+    const { query } = metaOf(command);
+    const words = command.registeredArguments.flatMap((argument) => {
+        const name = argument.name();
+        // A list's `[query...]` is its field filters, not text; a search's is the text.
+        if (name === "query" && query)
+            return [];
+        if (!argument.required && SAMPLES[name] === undefined)
+            return [];
+        return [argument.argChoices?.[0] ?? sample(name)];
+    });
+    const options = command.options
+        .filter((option) => option.mandatory)
+        .flatMap((option) => {
+        const flag = option.long ?? option.short ?? option.flags;
+        const placeholder = /[<[]([^>\]]+)[>\]]/.exec(option.flags)?.[1];
+        if (!(option.required || option.optional))
+            return [flag];
+        return [flag, option.argChoices?.[0] ?? sample(placeholder ?? option.attributeName())];
+    });
+    // No profile word, as on the first screen and in written examples: the Usage line already shows `<profile>`.
+    return [rootOf(command).name(), ...commandPathOf(command), ...words, ...options].join(" ");
+};
+/** Returns, Next usually and Example for one command, from its definition alone. */
+export const commandHelp = (command) => {
+    const written = metaOf(command).examples ?? [];
+    return {
+        returns: returnsOf(command),
+        next: nextOf(command).map(call),
+        examples: written.length > 0 ? written : [generatedExample(command)],
+        origin: written.length > 0 ? "written" : "generated",
+    };
+};
+const LABEL = 15;
+/** The lines `--help` prints after a command's options. */
+export const commandHelpText = (command) => {
+    const { returns, next, examples } = commandHelp(command);
+    const rows = (label, values) => values.map((value, at) => `${(at === 0 ? label : "").padEnd(LABEL)}${value}`);
+    return ["", ...rows("Returns:", [returns]), ...rows("Next usually:", next), ...rows("Example:", examples), ""].join("\n");
+};
+/** The same, as Markdown lines for `docs/commands.md`: hand it to cli-base's `commandsPage` per command. */
+export const commandHelpMarkdown = (root, path) => {
+    const command = commandAt(root, path.join(" "));
+    if (!command || command.commands.length > 0)
+        return [];
+    const { returns, next, examples } = commandHelp(command);
+    const code = (values) => values.map((value) => `\`${value}\``).join(", ");
+    return [
+        `**Returns:** ${returns}`,
+        ...(next.length > 0 ? [`**Next usually:** ${code(next)}`] : []),
+        `**Example:** ${code(examples)}`,
+    ];
+};
+/** Puts Returns, Next usually and Example on every leaf command's `--help`, worked out when the help is shown. */
+export const installCommandHelp = (program) => {
+    for (const command of leaves(program))
+        command.addHelpText("after", () => commandHelpText(command));
+};
+/** Which leaf commands still show a generated example, so the important ones get a written one. Report only. */
+export const exampleReport = (program) => {
+    const written = [];
+    const generated = [];
+    for (const command of leaves(program))
+        (commandHelp(command).origin === "written" ? written : generated).push(commandPathOf(command).join(" "));
+    const total = written.length + generated.length;
+    const text = [
+        `${program.name()}: ${written.length} of ${total} commands have a written example; ${generated.length} show a generated one:`,
+        ...generated.map((path) => `  ${program.name()} ${path}`),
+        "",
+    ].join("\n");
+    return { written, generated, text };
+};

package/dist/cli/help/commands-text.d.ts

@@ -0,0 +1,9 @@
+import type { CommandInfo } from "@wirecat/cli-base/commands";
+import type { Command } from "commander";
+/** The first clause that fits: a line per command is the point, the whole text is in `--help`. */
+export declare const short: (text: string) => string;
+/**
+ * `<tool> commands` for a person or an agent reading text: every command that runs, one line each, under its
+ * section. `scope` is the group asked for (`commands messages`), whose commands are all listed.
+ */
+export declare const commandsText: (root: Command, commands: readonly CommandInfo[], scope?: readonly string[]) => string;

package/dist/cli/help/commands-text.js

@@ -0,0 +1,43 @@
+import { writes } from "@wirecat/cli-base/standards";
+import { findCommand } from "../command-contract.js";
+import { SECTIONS, sectionOf } from "./sections.js";
+const DESCRIPTION = 90;
+const COLUMN = 52;
+/** The first clause that fits: a line per command is the point, the whole text is in `--help`. */
+export const short = (text) => {
+    const line = text.replace(/\s+/g, " ").trim();
+    if (line.length <= DESCRIPTION)
+        return line;
+    const cut = line.slice(0, DESCRIPTION);
+    return `${cut.slice(0, Math.max(cut.lastIndexOf(" "), DESCRIPTION / 2))}…`;
+};
+/**
+ * `<tool> commands` for a person or an agent reading text: every command that runs, one line each, under its
+ * section. `scope` is the group asked for (`commands messages`), whose commands are all listed.
+ */
+export const commandsText = (root, commands, scope) => {
+    const cli = root.name();
+    const runs = (info) => [
+        ...(info.commands.length === 0 || info.runnable ? [info] : []),
+        ...info.commands.flatMap(runs),
+    ];
+    const bySection = new Map(Object.keys(SECTIONS).map((key) => [key, []]));
+    for (const info of commands.flatMap(runs))
+        bySection.get(sectionOf(findCommand(root, info.path)))?.push(info);
+    const where = scope ? `${cli} ${scope.join(" ")}` : cli;
+    const lines = [
+        `${where} commands, by section. One command's arguments and options: ${cli} <command> --help.`,
+        `As JSON: ${cli} commands${scope ? ` ${scope.join(" ")}` : ""} --json. (writes) marks a command that changes something.`,
+    ];
+    for (const [section, infos] of bySection) {
+        if (infos.length === 0)
+            continue;
+        lines.push("", SECTIONS[section]);
+        for (const { usage, summary, description, effects } of infos) {
+            const what = short(summary ?? description);
+            const mark = effects === undefined || writes(effects) ? " (writes)" : "";
+            lines.push(`  ${usage.padEnd(COLUMN)}  ${what}${mark}`.trimEnd());
+        }
+    }
+    return `${lines.join("\n")}\n`;
+};

package/dist/cli/help/first-screen.d.ts

@@ -0,0 +1,37 @@
+import { Command } from "commander";
+export interface FirstScreenLine {
+    /** The command without the tool's name or the profile: `review --since 1d`. */
+    command: string;
+    does: string;
+}
+/** What a tool says on its first screen; the rest of the screen is the same for every WireCat tool. */
+export interface FirstScreen {
+    /** One sentence after `tg —`. Unset, the program's description. */
+    pitch?: string;
+    /** 6–8 lines, the ones a plain API client would not give. Unset, the block is left out. */
+    can?: readonly FirstScreenLine[];
+    /** `false` for a tool whose commands take no leading profile: no profile sentence, no `<profile>` in the usage. */
+    profile?: boolean;
+    /** The first command to run. Unset, `<tool> personal setup` when the tool has `setup`. */
+    start?: string;
+}
+interface Tool {
+    command: string;
+    shown?: string;
+    does: string;
+}
+/** Every WireCat tool, as "Works with" names it; a tool's own entry is left out of its screen. */
+export declare const WIRECAT_TOOLS: readonly Tool[];
+/**
+ * The screen `<tool> --help` and a bare `<tool>` show: what the tool is for, what it does that a client would not,
+ * the other tools, and where the full list, the scenarios and the options are. It never lists every command.
+ */
+export declare const firstScreen: (program: Command, screen?: FirstScreen) => string;
+/**
+ * Puts the first screen on `--help`, a bare run and `help`, and Returns, Next usually and Example on every leaf
+ * command's `--help`. `help options` prints the options for every command, `--help-all` the full commander help;
+ * both are hidden, so `commands --json` and MCP do not change. For a tool that builds its own program;
+ * `createProgram` calls it for tg, max and wa.
+ */
+export declare const installHelp: (program: Command, screen?: FirstScreen) => Command;
+export {};

package/dist/cli/help/first-screen.js

@@ -0,0 +1,109 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command, Help, Option } from "commander";
+import wrapAnsi from "wrap-ansi";
+import { NO_EFFECTS } from "../effects.js";
+import { commandAt } from "../steps.js";
+import { installCommandHelp } from "./command-help.js";
+/** Every WireCat tool, as "Works with" names it; a tool's own entry is left out of its screen. */
+export const WIRECAT_TOOLS = [
+    { command: "tg", does: "Telegram in the same local store: search, review and tasks offline" },
+    { command: "max", does: "MAX in the same local store: search, review and tasks offline" },
+    { command: "wa", does: "WhatsApp in the same local store: search, review and tasks offline" },
+    { command: "zm", does: "Zoom meetings: transcripts and summaries, searchable with your messages" },
+    { command: "drive", does: "Google Drive and Docs as local text, searchable with your messages" },
+    { command: "memo", shown: "memo context <person>", does: "one person across messengers, mail, notes and meetings" },
+];
+const WIDTH = 100;
+const widest = (texts) => texts.reduce((most, text) => Math.max(most, text.length), 0);
+const block = (title, rows, column) => rows.length === 0 ? [] : ["", `${title}:`, ...rows.map(([left, right]) => `  ${left.padEnd(column)}${right}`)];
+/** Only commands the tool has: `guide` and `setup` are not in every tool. */
+const pointers = (program, cli, start, profile) => {
+    const has = (path) => commandAt(program, path) !== undefined;
+    const next = [
+        has("commands") ? [`${cli} commands`, "every command, by section"] : undefined,
+        has("guide") ? [`${cli} guide`, "scenarios: command sequences for common tasks"] : undefined,
+        [`${cli} help options`, "output, offline, timeouts, dry run"],
+    ].filter((row) => row !== undefined);
+    const rows = [
+        ...(start ? [["Start here:", start, profile ? "(any profile name works)" : ""]] : []),
+        ...next.map(([command = "", does = ""], at) => [at === 0 ? "Next:" : "", command, does]),
+        ...(has("skill show") ? [["For agents:", `${cli} skill show`, "rules and the discovery loop"]] : []),
+    ];
+    const width = widest(rows.map(([, command]) => command)) + 2;
+    return ["", ...rows.map(([label, command, does]) => `${label.padEnd(14)}${command.padEnd(width)}${does}`.trimEnd())];
+};
+/**
+ * The screen `<tool> --help` and a bare `<tool>` show: what the tool is for, what it does that a client would not,
+ * the other tools, and where the full list, the scenarios and the options are. It never lists every command.
+ */
+export const firstScreen = (program, screen = {}) => {
+    const cli = program.name();
+    const profile = screen.profile !== false;
+    const pitch = screen.pitch ?? program.description().split("\n")[0] ?? "";
+    const can = (screen.can ?? []).map(({ command, does }) => [command, does]);
+    const works = WIRECAT_TOOLS.filter((tool) => tool.command !== cli).map(({ command, shown, does }) => [shown ?? command, does]);
+    const column = Math.max(22, widest([...can, ...works].map(([left]) => left))) + 2;
+    const start = screen.start ?? (commandAt(program, "setup") ? `${cli} personal setup` : undefined);
+    return [
+        wrapAnsi(`${cli} — ${pitch}`, WIDTH),
+        "",
+        `Usage: ${cli} ${profile ? "<profile> " : ""}<command> [options]`,
+        ...(profile ? ["Account commands start with your profile, a name you choose; none is ever assumed."] : []),
+        ...block("What you can do", can, column),
+        ...block("Works with", works, column),
+        ...pointers(program, cli, start, profile),
+        "",
+    ].join("\n");
+};
+const optionsScreen = (program) => {
+    const helper = program.createHelp();
+    const width = helper.longestOptionTermLength(program, helper);
+    return [
+        `Options for every ${program.name()} command:`,
+        ...helper
+            .visibleOptions(program)
+            .map((option) => helper.formatItem(helper.optionTerm(option), width, helper.optionDescription(option), helper)),
+        "",
+    ].join("\n");
+};
+/**
+ * Puts the first screen on `--help`, a bare run and `help`, and Returns, Next usually and Example on every leaf
+ * command's `--help`. `help options` prints the options for every command, `--help-all` the full commander help;
+ * both are hidden, so `commands --json` and MCP do not change. For a tool that builds its own program;
+ * `createProgram` calls it for tg, max and wa.
+ */
+export const installHelp = (program, screen = {}) => {
+    let full = false;
+    const own = program.configureHelp();
+    program.configureHelp({
+        ...own,
+        // Commander copies this configuration to children made with `.command()`, so only the root gets the screen.
+        formatHelp: (command, helper) => command === program && !full
+            ? firstScreen(program, screen)
+            : (own.formatHelp ?? Help.prototype.formatHelp).call(helper, command, helper),
+    });
+    installCommandHelp(program);
+    program.addOption(new Option("--help-all", "the full help: every command and option").hideHelp());
+    program.on("option:help-all", () => {
+        full = true;
+        program.help();
+    });
+    if (program.commands.some((command) => command.name() === "help"))
+        return program;
+    const help = annotate(new Command("help"), { effects: NO_EFFECTS, mcp: false })
+        .description("this screen; help options: the options for every command; help <command>: that command's help")
+        .argument("[topic...]", "options, or a command path")
+        .action((topic) => {
+        if (topic.length === 0)
+            return program.outputHelp();
+        if (topic.length === 1 && topic[0] === "options")
+            return program.configureOutput().writeOut?.(optionsScreen(program));
+        const command = commandAt(program, topic.join(" "));
+        if (!command)
+            throw new CliError("validation_error", `no command "${topic.join(" ")}" — run \`${program.name()} help\`, or \`${program.name()} help options\``, { available: program.commands.map((one) => one.name()).filter((name) => name !== "help") });
+        command.outputHelp();
+    });
+    program.addCommand(help, { hidden: true });
+    return program;
+};

package/dist/cli/help/sections.d.ts

@@ -0,0 +1,19 @@
+import type { Command } from "commander";
+export declare const SECTIONS: {
+    readonly read: "Read";
+    readonly write: "Write";
+    readonly organise: "Organise";
+    readonly automate: "Automate";
+    readonly setup: "Set up";
+    readonly other: "Other";
+};
+export type HelpSection = Exclude<keyof typeof SECTIONS, "other">;
+/**
+ * Where `<tool> commands` lists the command and everything under it. Kept off `annotate`, whose metadata becomes
+ * fields of `commands --json`, which must not change.
+ */
+export declare const inSection: <T extends Command>(command: T, section: HelpSection) => T;
+/** The nearest section on the command or above it; `other` when none is set. */
+export declare const sectionOf: (command: Command) => keyof typeof SECTIONS;
+/** Puts each of cli-core's groups mounted on `program` in its section, unless the tool already chose one. */
+export declare const sectionCoreGroups: (program: Command) => void;

package/dist/cli/help/sections.js

@@ -0,0 +1,77 @@
+export const SECTIONS = {
+    read: "Read",
+    write: "Write",
+    organise: "Organise",
+    automate: "Automate",
+    setup: "Set up",
+    other: "Other",
+};
+const sections = new WeakMap();
+/**
+ * Where `<tool> commands` lists the command and everything under it. Kept off `annotate`, whose metadata becomes
+ * fields of `commands --json`, which must not change.
+ */
+export const inSection = (command, section) => {
+    sections.set(command, section);
+    return command;
+};
+/** The nearest section on the command or above it; `other` when none is set. */
+export const sectionOf = (command) => {
+    for (let at = command; at; at = at.parent) {
+        const section = sections.get(at);
+        if (section)
+            return section;
+    }
+    return "other";
+};
+/** The groups cli-core builds, by name; a tool sets its own with `inSection`. */
+const CORE_SECTIONS = {
+    attachments: "read",
+    chats: "read",
+    contacts: "read",
+    conversations: "read",
+    images: "read",
+    inbox: "read",
+    meetings: "read",
+    mentions: "read",
+    messages: "read",
+    review: "read",
+    search: "read",
+    stats: "read",
+    topics: "read",
+    watch: "read",
+    flood: "write",
+    polls: "write",
+    reactions: "write",
+    recipients: "write",
+    sends: "write",
+    metadata: "organise",
+    searches: "organise",
+    tags: "organise",
+    tasks: "organise",
+    bot: "automate",
+    mcp: "automate",
+    replies: "automate",
+    runs: "automate",
+    schedule: "automate",
+    serve: "automate",
+    server: "automate",
+    account: "setup",
+    commands: "setup",
+    complete: "setup",
+    config: "setup",
+    doctor: "setup",
+    guide: "setup",
+    models: "setup",
+    skill: "setup",
+    store: "setup",
+    upgrade: "setup",
+};
+/** Puts each of cli-core's groups mounted on `program` in its section, unless the tool already chose one. */
+export const sectionCoreGroups = (program) => {
+    for (const command of program.commands) {
+        const section = CORE_SECTIONS[command.name()];
+        if (section && !sections.has(command))
+            inSection(command, section);
+    }
+};

package/dist/cli/index.d.ts

@@ -56,6 +56,10 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
+export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, guideCommand, loadScenarios, type Scenario, } from "./guide.js";
+export { type CommandHelp, commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, type NextChoice, nextUsually, } from "./help/command-help.js";
+export { type FirstScreen, type FirstScreenLine, firstScreen, installHelp, WIRECAT_TOOLS, } from "./help/first-screen.js";
+export { type HelpSection, inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, type InputPolicy, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, type EntityFields, entityFields, type JsonFieldsResolver, type JsonRequest, liftJson, } from "./json-fields.js";
 export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTerms, pagedList, pageOf, type QueryWords, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";

package/dist/cli/index.js

@@ -51,6 +51,10 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { answerSchema, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
+export { checkGuide, checkStep, guideCommand, loadScenarios, } from "./guide.js";
+export { commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, nextUsually, } from "./help/command-help.js";
+export { firstScreen, installHelp, WIRECAT_TOOLS, } from "./help/first-screen.js";
+export { inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, entityFields, liftJson, } from "./json-fields.js";
 export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTerms, pagedList, pageOf, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";

package/dist/cli/list-query.js

@@ -1,6 +1,7 @@
 import { annotate } from "@wirecat/cli-base/commands";
 import { dateRange, defineQuery, fieldsHelp, fieldsNamed, OPERATORS_BY_TYPE, parseLucene, QUERY_LIMITS, queryError, queryFieldsOf, validateQuery, } from "@wirecat/cli-base/query";
 import * as v from "valibot";
+import { queryWordsAfterOptions } from "../meetings/cli/index.js";
 import { listOf } from "./envelope.js";
 export const LIST_QUERY_GUIDE = "https://github.com/WireCatLabs/cli-core/blob/main/docs/search/query-language.md";
 /**
@@ -11,10 +12,7 @@ export const withQuery = (command, registry) => {
     const query = defineQuery(registry);
     annotate(command, { query, output: { entity: registry.entity } });
     const shown = askable(query);
-    // `-kind:channel` is a negated term, not an option; a mistyped option still fails, as a query word.
-    command
-        .allowUnknownOption()
-        .argument("[query...]", shown.length > 0
+    queryWordsAfterOptions(command).argument("[query...]", shown.length > 0
         ? "field:value terms that narrow the list — the fields are below"
         : "field:value terms; this list filters by none yet");
     if (shown.length > 0)

package/dist/cli/messenger/complete-command.js

@@ -32,6 +32,8 @@ export const completeCommand = (messenger, config, options = {}) => annotate(new
     // Commander drops the `--` from the operands, so only the raw words tell a request from a shell name.
     const raw = root.rawArgs;
     if (!raw.includes("--")) {
+        if (words.includes("--help") || words.includes("-h"))
+            this.help();
         const [shell] = words;
         if (!shell || !SHELLS.includes(shell)) {
             throw new CliError("validation_error", `name a shell: ${app.command} complete ${SHELLS.join(" | ")}`);

package/dist/cli/messenger/context.js

@@ -230,16 +230,17 @@ export const connectedFor = async (command, messenger, base, options) => {
         ...connected(connection, messenger, base, options.events, store, options.listen ? { listen: true } : {}),
     };
 };
-const unrecorded = (command, messenger, profile) => {
-    const tool = messenger.app.command;
-    const setup = rootOf(command).commands.some((one) => one.name() === "setup")
-        ? `\`${tool} ${asFirstWord(profile)}setup\``
-        : undefined;
-    return new CliError("not_found", messenger.history === "store"
-        ? `nothing recorded for profile "${profile}" yet — ${setup ? `link it with ${setup}, then ` : ""}run ` +
-            `\`${tool} serve\` or \`${tool} watch\` once to fill the local store`
-        : `nothing recorded for profile "${profile}" yet — ${setup ? `log in with ${setup}, or ` : ""}run the ` +
-            "command once without --offline");
+const unrecorded = (command, messenger, profile, offline) => {
+    const words = `${messenger.app.command} ${asFirstWord(profile)}`;
+    const setup = rootOf(command).commands.some((one) => one.name() === "setup") ? `\`${words}setup\`` : undefined;
+    if (messenger.history === "store")
+        return new CliError("not_found", `nothing recorded for profile "${profile}" yet — ${setup ? `link it with ${setup}, then ` : ""}run ` +
+            `\`${words}serve\` or \`${words}watch\` once to fill the local store`);
+    const ways = [
+        ...(setup ? [`log in with ${setup}`] : []),
+        ...(offline ? ["run the command once without --offline"] : []),
+    ];
+    return new CliError("not_found", `nothing recorded for profile "${profile}" yet — ${ways.length > 0 ? ways.join(", or ") : "log in to it first"}`);
 };
 /** NEED-506 A: without it, an agent cannot tell a quiet chat from a store nothing keeps up to date. */
 const warnUnserved = async (messenger, profile, { env, renderer }, store) => {
@@ -300,7 +301,7 @@ export const messengerContext = (command, messenger, resolving = {}) => {
     const accountFor = () => {
         const account = messenger.accountOf?.(command) ?? recalledAccount(app, provider, profile, base.env);
         if (!account)
-            throw unrecorded(command, messenger, profile);
+            throw unrecorded(command, messenger, profile, base.settings.offline);
         return account;
     };
     const guard = messenger.guard?.(command, base.settings, warn) ??

package/dist/cli/messenger/conversations-command.js

@@ -335,7 +335,9 @@ export const conversationsCommand = (messenger) => {
     const consents = conversations
         .command("consents")
         .description("remembered analysis permissions for this account's chats and provider endpoints");
-    annotate(consents.command("list"), { effects: LOCAL_READ }).action(async function () {
+    annotate(consents.command("list"), { effects: LOCAL_READ })
+        .description("which chats and provider endpoints you allowed to analyse, and when")
+        .action(async function () {
         const context = messengerContext(this, messenger);
         const items = await context.withStore((store, account) => analysisConsents(store, account).list());
         renderAnswer(this, context, listOf("conversations consents list", {
@@ -345,6 +347,7 @@ export const conversationsCommand = (messenger) => {
         }));
     });
     annotate(consents.command("revoke"), { effects: LOCAL_WRITE })
+        .description("forget analysis permissions so the next analysis asks again")
         .option("--chat <chat>", "revoke only this chat's consents; defaults to every chat")
         .option("--provider <identity>", "exact provider identity from consents list; defaults to every provider")
         .action(async function () {

package/dist/cli/messenger/inbox.js

@@ -30,7 +30,7 @@ export const PARTIAL_NOTE = "the messenger did not list every chat, and did not
  */
 export const inboxCommand = (messenger) => annotate(new Command("inbox"), {
     effects: REMOTE_READ,
-    output: { entity: "message", view: "message.summary" },
+    output: { entity: "message", view: "summary" },
     query: INBOX_QUERY,
 })
     .description("other people's unread messages in every chat; --new for what arrived since the last check")

package/dist/cli/messenger/mcp-command.js

@@ -113,7 +113,7 @@ export const mcpCommand = (messenger) => {
             const server = entry;
             const { potentialWrites } = await probeStdio(server);
             if (potentialWrites.length > 0 && this.opts().allowWrites !== true)
-                throw new Error(`this profile offers ${potentialWrites.length} tools that may write; review its permissions, then pass --allow-writes to install it`);
+                throw new Error(`this profile offers ${potentialWrites.length} ${potentialWrites.length === 1 ? "tool" : "tools"} that may write; review its permissions, then pass --allow-writes to install it`);
             renderAnswer(this, context, itemOf({ ...installStdioEntry(client, name, server), potential_writes: potentialWrites.length }));
         }
         catch (error) {