@wirecat/cli-core 0.421.0 → 0.422.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ shape of this file.
 
 ## Unreleased
 
+## 0.422.0 — 25.10.2026
+
+### Added
+
+- **`AppIdentity.messenger`: set it to `false` in a CLI that is not a messenger** (a notes, files or calendar CLI from cli-template). The shared program, `commands`, `config` and MCP text then stop speaking of chats and messages: the profile example in the program description names the CLI's own first command, `commands info`'s example is `<cmd> commands info commands`, `--brief` and `--full` describe "found items", `--trace` and `--record` say "never content", and `config show` and the `config set`/`unset` list leave out `sender_colors`. Unset means a messenger: tg, max and wa print exactly what they did. A CLI that sets it refreshes its contract snapshots once.
+- **The MCP `_tools_search`, `_read` and `_write` tools speak neutrally when the catalogue has no `messages` commands**: task words "list", "show", "change a setting", one of the CLI's own reading commands as the example, and "creates, edits, deletes" for writes. No setting is needed; a messenger's catalogue is unchanged.
+
+### Changed — may break callers
+
+- **The languages search stems are one table, `LANGUAGES`, and each entry now names its Hunspell dictionary** (`dictionary: "dictionary-ru"`). `LANGUAGES` from `/cli` keeps its other fields. `LATIN_STEMMERS` is now `english, spanish, none`, in the order the error for an unknown stemmer already printed, so the `allowed` list of a `stemmer.invalid` error comes in that order too. A caller that compared that list in order sorts it first.
+
 ## 0.421.0 — 25.10.2026
 
 ### Changed — may break callers

package/dist/cli/commands-command.js

@@ -59,7 +59,7 @@ export const commandsCommand = (app) => {
     });
     command.addCommand(annotate(new Command("info"), {
         effects: NO_EFFECTS,
-        examples: [`${app.command} commands info messages list`],
+        examples: [`${app.command} commands info ${app.messenger === false ? "commands" : "messages list"}`],
     })
         .description(DISCOVERY_DESCRIPTIONS.info)
         .argument("[path...]", "one command path; without one, export schemas, error reasons and explicit overrides")

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

@@ -2,10 +2,6 @@ import { Command } from "commander";
 import { type AppIdentity } from "../ports/app.js";
 import { type PermissionKeyOf } from "./permission-keys.js";
 import { type Configuration } from "./settings.js";
-/**
- * The settings in force and where each came from, and changing them. Printed whole: no field the
- * configuration accepts can hold a secret — the schema has nowhere to put one.
- */
 export declare const configCommand: (app: AppIdentity, config: Configuration, { permissionKey }?: {
     permissionKey?: PermissionKeyOf;
 }) => Command;

package/dist/cli/config-command.js

@@ -15,6 +15,8 @@ import { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } fro
  * The settings in force and where each came from, and changing them. Printed whole: no field the
  * configuration accepts can hold a secret — the schema has nowhere to put one.
  */
+/** `sender_colors` colours who wrote a message; a CLI without messages has nothing to colour. */
+const shownSettings = (app, config) => app.messenger === false ? config.allSettings.filter((setting) => setting !== "sender_colors") : config.allSettings;
 export const configCommand = (app, config, { permissionKey } = {}) => {
     const command = new Command("config").description("the settings in force, and where each one came from");
     annotate(command.command("show"), { effects: LOCAL_READ, examples: [`${app.command} personal config show`] })
@@ -32,7 +34,7 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
             config_file: settings.configPath,
             config_found: settings.configFound,
             paths_overridden: overridden,
-            settings: [...config.allSettings, "command_timeout_ms"]
+            settings: [...shownSettings(app, config), "command_timeout_ms"]
                 .filter((setting) => bot || setting !== "read_other_bots")
                 .map((setting) => sourced(settings, setting, config.schema)),
             store_settings: await storeSettings(env),
@@ -49,7 +51,7 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
         }))
             .argument("<setting>", 
         // default_profile is only removed now: `config unset` still takes it, `config set` refuses it.
-        `one of: ${[...config.allSettings.filter((one) => action === "unset" || one !== "default_profile"), ...STORE_SETTINGS, "account_groups.<name>"].join(", ")}`)
+        `one of: ${[...shownSettings(app, config).filter((one) => action === "unset" || one !== "default_profile"), ...STORE_SETTINGS, "account_groups.<name>"].join(", ")}`)
             .option("--defaults", "change what every profile gets, rather than this profile")
             .option("--personal", "only for personal accounts — the personal section of the file")
             .option("--bot", "only for bots — the bot section of the file");

package/dist/cli/first-run.d.ts

@@ -1,22 +1,6 @@
 import { type Installer } from "@wirecat/cli-base/update";
 import { type Question } from "./setup-answers.js";
 /** The languages cli-core stems and has a dictionary for; each is one stemmer of its alphabet. */
-export declare const LANGUAGES: readonly [{
-    readonly name: "russian";
-    readonly code: "ru";
-    readonly label: "Russian";
-    readonly script: "cyrillic";
-}, {
-    readonly name: "english";
-    readonly code: "en";
-    readonly label: "English";
-    readonly script: "latin";
-}, {
-    readonly name: "spanish";
-    readonly code: "es";
-    readonly label: "Spanish";
-    readonly script: "latin";
-}];
 export interface FirstRunIo {
     ask: (prompt: string) => Promise<string>;
     say: (text: string) => void;

package/dist/cli/first-run.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { accessSync, constants, realpathSync } from "node:fs";
 import { delimiter, join } from "node:path";
 import { installerOf, updateCommand } from "@wirecat/cli-base/update";
+import { LANGUAGES } from "../search/languages.js";
 import { DEFAULT_STEMMERS } from "../search/stem.js";
 import { openCache } from "../store/open.js";
 import { storePath } from "../store/path.js";
@@ -11,12 +12,6 @@ import { readSecret } from "../terminal/prompt.js";
 import { WIRECAT_TOOLS } from "./help/first-screen.js";
 import { buildStems } from "./messenger/store-maintenance-command.js";
 import { QUESTIONS, readSetupAnswers, unanswered, writeSetupAnswers, } from "./setup-answers.js";
-/** The languages cli-core stems and has a dictionary for; each is one stemmer of its alphabet. */
-export const LANGUAGES = [
-    { name: "russian", code: "ru", label: "Russian", script: "cyrillic" },
-    { name: "english", code: "en", label: "English", script: "latin" },
-    { name: "spanish", code: "es", label: "Spanish", script: "latin" },
-];
 /** Commands that run without first-run questions: they serve agents, help, or open the store themselves. */
 const SKIPPED = new Set(["help", "guide", "completion", "mcp", "serve", "server", "update", "store"]);
 /**

package/dist/cli/index.d.ts

@@ -26,6 +26,7 @@ export { CORE_LOG_EVENTS } from "../runs/log-events.js";
 export { crashOf, type Recording, type RecordingOptions, recorded, startRecording, wasSettled, } from "../runs/recording.js";
 export { findRun, KEEP_RUNS_FOR_DAYS, listRuns, pruneRuns, type RunMetadata, readEvents, runsDirFor, runtime, startRun, } from "../runs/run.js";
 export { currentRun, inRun, type RunScope, useAsProcessRun } from "../runs/scope.js";
+export { LANGUAGES } from "../search/languages.js";
 export { guardedApp, guardedPress, guardedStart, type Pressed } from "../sends/buttons.js";
 export { guardedClose, guardedCreatePoll, guardedVote } from "../sends/polls.js";
 export type { InboxReader } from "../services/inbox.js";
@@ -62,7 +63,7 @@ export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNoth
 export { type CliEntry, type EntryContext, type EntryIo, startCli } from "./entry.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
-export { askSetupQuestions, asksAtStart, type FirstRun, type FirstRunIo, LANGUAGES, setupAtStart, systemLanguage, } from "./first-run.js";
+export { askSetupQuestions, asksAtStart, type FirstRun, type FirstRunIo, setupAtStart, systemLanguage, } from "./first-run.js";
 export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, loadScenarios, MEMO_SCENARIOS, type Scenario, shellProblems, } from "./guide.js";
 export { type CommandHelp, commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, type NextChoice, nextUsually, } from "./help/command-help.js";
 export { commandsText } from "./help/commands-text.js";

package/dist/cli/index.js

@@ -22,6 +22,7 @@ export { CORE_LOG_EVENTS } from "../runs/log-events.js";
 export { crashOf, recorded, startRecording, wasSettled, } from "../runs/recording.js";
 export { findRun, KEEP_RUNS_FOR_DAYS, listRuns, pruneRuns, readEvents, runsDirFor, runtime, startRun, } from "../runs/run.js";
 export { currentRun, inRun, useAsProcessRun } from "../runs/scope.js";
+export { LANGUAGES } from "../search/languages.js";
 export { guardedApp, guardedPress, guardedStart } from "../sends/buttons.js";
 export { guardedClose, guardedCreatePoll, guardedVote } from "../sends/polls.js";
 export { INBOX_CHATS, newIn, REVIEW_CHATS, reviewIn, unreadIn } from "../services/inbox.js";
@@ -55,7 +56,7 @@ export { changesAuthority, changesAuthorityAt, changesAuthorityNow, destroysNoth
 export { startCli } from "./entry.js";
 export { answerSchema, isBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
-export { askSetupQuestions, asksAtStart, LANGUAGES, setupAtStart, systemLanguage, } from "./first-run.js";
+export { askSetupQuestions, asksAtStart, setupAtStart, systemLanguage, } from "./first-run.js";
 export { checkGuide, checkStep, loadScenarios, MEMO_SCENARIOS, shellProblems, } from "./guide.js";
 export { commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, nextUsually, } from "./help/command-help.js";
 export { commandsText } from "./help/commands-text.js";

package/dist/cli/profile.d.ts

@@ -28,3 +28,5 @@ export declare const valuedOptions: (program: Command) => Set<string>;
 export declare const refuseCommandName: (profile: string, words: Set<string>, command: string) => void;
 /** The root of the command tree, from anywhere inside it. */
 export declare const rootOf: (command: Command) => Command;
+/** A command this CLI really has, for an example: the first that takes a profile, down to its first leaf. */
+export declare const sampleCommand: (commands: readonly Command[]) => string | undefined;

package/dist/cli/profile.js

@@ -59,3 +59,13 @@ export const rootOf = (command) => {
         root = root.parent;
     return root;
 };
+/** A command this CLI really has, for an example: the first that takes a profile, down to its first leaf. */
+export const sampleCommand = (commands) => {
+    const words = [];
+    let command = commands.find((one) => !PROFILE_FREE.has(one.name()));
+    while (command) {
+        words.push(command.name());
+        command = command.commands.find((one) => one.name() !== "help");
+    }
+    return words.length ? words.join(" ") : undefined;
+};

package/dist/cli/program.js

@@ -26,7 +26,7 @@ import { showInputFields } from "./input-fields.js";
 import { MAX_BUFFERED_INPUT, provideInputPolicy } from "./input-policy.js";
 import { checkJson, liftJson } from "./json-fields.js";
 import { PreviewComplete, preview } from "./preview.js";
-import { asFirstWord, commandWords, liftProfile, PROFILE_FREE, valuedOptions } from "./profile.js";
+import { asFirstWord, commandWords, liftProfile, PROFILE_FREE, sampleCommand, valuedOptions } from "./profile.js";
 import { absolutePaths, relayTarget } from "./relay-route.js";
 import { settingsFor } from "./settings.js";
 import { assertSharedContracts } from "./shared-contracts.js";
@@ -37,11 +37,15 @@ import { commandAt, lineOf, withLines } from "./steps.js";
  */
 export const createProgram = ({ app, commands, configure, firstScreen }, { out, err } = {}) => {
     const program = new Command();
+    const mounted = commands();
+    const messenger = app.messenger !== false;
+    const found = messenger ? "found messages" : "found items";
+    const content = messenger ? "message content" : "content";
     program
         .name(app.command)
         .usage("[profile] [options] <command>")
         .description(`${app.description}\n\n` +
-        `The first word is the profile whenever it is not a command — \`${app.command} personal chats list\`.\n` +
+        `The first word is the profile whenever it is not a command — \`${app.command} personal ${messenger ? "chats list" : (sampleCommand(mounted) ?? "<command>")}\`.\n` +
         `\`${app.envPrefix}_PROFILE\` says the same thing for a whole shell session.\n` +
         "No profile is assumed: without one, a command that uses an account stops and lists the profiles here.")
         .version(app.version, "-V, --version")
@@ -49,21 +53,21 @@ export const createProgram = ({ app, commands, configure, firstScreen }, { out,
         .option("--json", "machine-readable output: one JSON value on stdout; --json=id,text keeps only those fields")
         .option("--jsonl", "machine-readable output: one JSON object per line, for streaming and jq")
         .option("--quiet", "diagnostics off; a failure is still said")
-        .option("--trace", "the connection's own log lines on stderr — never message content")
+        .option("--trace", `the connection's own log lines on stderr — never ${content}`)
         .option("--debug", "on a failure, its whole record — cause and stack — in place of the short line")
         .option("--timeout <duration>", "give up on the whole command after this — 30s, 2m, 500ms")
         .option("--offline", "answer from what was recorded and never connect; fails if nothing was")
         .option("--no-input", "never prompt or open interactive login; piped input remains available")
         .option("--max-input-bytes <bytes>", "maximum buffered input bytes (default: 16777216)")
         .option("--max-output-bytes <bytes>", "maximum machine output bytes (default: 4194304; 0 disables)")
-        .option("--brief", "found messages as reference, title, time, sender and excerpt only")
-        .option("--full", "found messages with their whole text and every provider field")
+        .option("--brief", `${found} as reference, title, time, ${messenger ? "sender" : "author"} and excerpt only`)
+        .option("--full", `${found} with their whole text and every provider field`)
         .option("--dry-run", "preview parsed arguments and permissions before running the action")
         .option("--yes", "go ahead without the question an ask level puts before a write")
-        .option("--record", "keep this run — ids and timings, never message content")
+        .option("--record", `keep this run — ids and timings, never ${content}`)
         .option("--no-record", "do not keep it, whatever the configuration says")
         .showHelpAfterError();
-    for (const command of commands())
+    for (const command of mounted)
         program.addCommand(command);
     configure?.(program);
     assertSharedContracts(program);

package/dist/mcp/surface.js

@@ -62,10 +62,16 @@ export const registerCommands = (server, prefix, commands, errors,
 /** Throws the refusal of a command left out because the lock or a level stops it, so the agent learns why. */
 withheld) => {
     const byNormal = new Map(Object.keys(commands).map((command) => [normal(command), command]));
+    // No AppIdentity reaches here; only a messenger's catalogue has `messages` commands.
+    const messenger = Object.keys(commands).some((command) => command.split(" ")[0] === "messages");
+    const tasks = messenger ? '"unread", "send message", "chat members"' : '"list", "show", "change a setting"';
+    const sample = messenger
+        ? "messages list"
+        : (Object.entries(commands).find(([, one]) => !one.writes)?.[0] ?? Object.keys(commands)[0] ?? "");
     server.registerTool(`${prefix}_tools_search`, {
         outputSchema: toStandardJsonSchema(v.looseObject({})),
         title: "Find a command",
-        description: `Find the command for a task — "unread", "send message", "chat members" — before calling ` +
+        description: `Find the command for a task — ${tasks} — before calling ` +
             `${prefix}_read or ${prefix}_write with it. Each match gives its command, whether it writes, its arguments and the shape of its answer. ` +
             "With no words, lists every command and title, without arguments.",
         inputSchema: toStandardJsonSchema(v.strictObject({ query: v.optional(v.pipe(v.string(), v.description("words that describe the task"))) })),
@@ -122,7 +128,7 @@ withheld) => {
         }
     };
     const call = v.strictObject({
-        command: v.pipe(v.string(), v.minLength(1), v.description(`a command ${prefix}_tools_search returned: "messages list"`)),
+        command: v.pipe(v.string(), v.minLength(1), v.description(`a command ${prefix}_tools_search returned: "${sample}"`)),
         arguments: v.optional(v.pipe(v.record(v.string(), v.unknown()), v.description("that command's arguments"))),
     });
     server.registerTool(`${prefix}_read`, {
@@ -136,7 +142,7 @@ withheld) => {
         server.registerTool(`${prefix}_write`, {
             outputSchema: toStandardJsonSchema(ANSWER),
             title: "Run a writing command",
-            description: `Run one command that changes something — sends, edits, deletes, joins — with the arguments ${prefix}_tools_search showed. ${UNTRUSTED}`,
+            description: `Run one command that changes something — ${messenger ? "sends, edits, deletes, joins" : "creates, edits, deletes"} — with the arguments ${prefix}_tools_search showed. ${UNTRUSTED}`,
             inputSchema: toStandardJsonSchema(call),
             annotations: WRITE,
         }, runner(true));

package/dist/ports/app.d.ts

@@ -19,6 +19,12 @@ export interface AppIdentity {
      * can stem in place of English and the system's language; the person still confirms, since the choice is shared.
      */
     contentLanguages?: readonly string[];
+    /**
+     * `false` for a CLI that is not a messenger — notes, files, a calendar. The shared help, `config`, `commands info`
+     * and MCP text then name its own commands and leave out chats, messages and senders. Unset means a messenger, so
+     * tg, max and wa print what they always did.
+     */
+    messenger?: boolean;
     /** Error reasons and detail keys of its own — max's `max_code`, tg's `migrated_chat_id` — kept in every error it prints. */
     errors?: AppErrors;
 }

package/dist/search/dictionary.d.ts

@@ -1,10 +1,7 @@
+import { type Language } from "./languages.js";
 /** The Hunspell dictionary that tells a real word from a garbled one, for each language the store stems. */
-export declare const DICTIONARIES: {
-    readonly russian: "dictionary-ru";
-    readonly english: "dictionary-en";
-    readonly spanish: "dictionary-es";
-};
-export type DictionaryLanguage = keyof typeof DICTIONARIES;
+export declare const DICTIONARIES: Record<Language, string>;
+export type DictionaryLanguage = Language;
 /**
  * `known`: whether a folded word the index stores is real in one of `languages` that write in its alphabet.
  * `covers`: whether any of them does; without one, a garbled spelling cannot be told from a real word.

package/dist/search/dictionary.js

@@ -1,7 +1,8 @@
 import { readFileSync } from "node:fs";
 import { fold } from "../store/normalize.js";
+import { LANGUAGES } from "./languages.js";
 /** The Hunspell dictionary that tells a real word from a garbled one, for each language the store stems. */
-export const DICTIONARIES = { russian: "dictionary-ru", english: "dictionary-en", spanish: "dictionary-es" };
+export const DICTIONARIES = Object.fromEntries(LANGUAGES.map(({ name, dictionary }) => [name, dictionary]));
 /** `fold`, without Unicode normalisation for plain Russian letters: it would double the time Russian loads in. */
 const folded = (word) => /^[а-яё'-]*$/.test(word) ? word.replaceAll("ё", "е").replaceAll("й", "и") : fold(word);
 const loaded = new Map();

package/dist/search/languages.d.ts

@@ -0,0 +1,28 @@
+/** The languages search can stem and spell-check. Adding one here needs its Snowball stemmer in `stem.ts`. */
+export declare const LANGUAGES: readonly [{
+    readonly name: "russian";
+    readonly code: "ru";
+    readonly label: "Russian";
+    readonly script: "cyrillic";
+    readonly dictionary: "dictionary-ru";
+}, {
+    readonly name: "english";
+    readonly code: "en";
+    readonly label: "English";
+    readonly script: "latin";
+    readonly dictionary: "dictionary-en";
+}, {
+    readonly name: "spanish";
+    readonly code: "es";
+    readonly label: "Spanish";
+    readonly script: "latin";
+    readonly dictionary: "dictionary-es";
+}];
+type Entry = (typeof LANGUAGES)[number];
+export type Language = Entry["name"];
+export type Script = Entry["script"];
+export type LanguageOf<S extends Script> = Extract<Entry, {
+    script: S;
+}>["name"];
+export declare const languagesOf: <S extends Script>(script: S) => LanguageOf<S>[];
+export {};

package/dist/search/languages.js

@@ -0,0 +1,7 @@
+/** The languages search can stem and spell-check. Adding one here needs its Snowball stemmer in `stem.ts`. */
+export const LANGUAGES = [
+    { name: "russian", code: "ru", label: "Russian", script: "cyrillic", dictionary: "dictionary-ru" },
+    { name: "english", code: "en", label: "English", script: "latin", dictionary: "dictionary-en" },
+    { name: "spanish", code: "es", label: "Spanish", script: "latin", dictionary: "dictionary-es" },
+];
+export const languagesOf = (script) => LANGUAGES.filter((one) => one.script === script).map(({ name }) => name);

package/dist/search/stem.d.ts

@@ -1,9 +1,10 @@
+import { type LanguageOf } from "./languages.js";
 /** The version of the vendored files in `./snowball/`; `bin/snowball-update` regenerates them. */
 export declare const SNOWBALL_VERSION = "3.1.1";
-export declare const CYRILLIC_STEMMERS: readonly ["russian", "none"];
-export declare const LATIN_STEMMERS: readonly ["spanish", "english", "none"];
-export type CyrillicStemmer = (typeof CYRILLIC_STEMMERS)[number];
-export type LatinStemmer = (typeof LATIN_STEMMERS)[number];
+export type CyrillicStemmer = LanguageOf<"cyrillic"> | "none";
+export type LatinStemmer = LanguageOf<"latin"> | "none";
+export declare const CYRILLIC_STEMMERS: readonly CyrillicStemmer[];
+export declare const LATIN_STEMMERS: readonly LatinStemmer[];
 /** `latin` is one stemmer, `none`, or several joined by commas in alphabetical order (`english,spanish`). */
 export type Stemmers = {
     cyrillic: CyrillicStemmer;

package/dist/search/stem.js

@@ -1,12 +1,13 @@
 import { CliError } from "@wirecat/cli-base";
 import { normalize } from "../store/normalize.js";
+import { languagesOf } from "./languages.js";
 import EnglishStemmer from "./snowball/english-stemmer.js";
 import RussianStemmer from "./snowball/russian-stemmer.js";
 import SpanishStemmer from "./snowball/spanish-stemmer.js";
 /** The version of the vendored files in `./snowball/`; `bin/snowball-update` regenerates them. */
 export const SNOWBALL_VERSION = "3.1.1";
-export const CYRILLIC_STEMMERS = ["russian", "none"];
-export const LATIN_STEMMERS = ["spanish", "english", "none"];
+export const CYRILLIC_STEMMERS = [...languagesOf("cyrillic"), "none"];
+export const LATIN_STEMMERS = [...languagesOf("latin"), "none"];
 export const DEFAULT_STEMMERS = { cyrillic: "russian", latin: "english,spanish" };
 /**
  * Raised with every change to `DEFAULT_STEMMERS`. A default saved in the store carries it, so a newer build

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.421.0",
+  "version": "0.422.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",