@wirecat/cli-core 0.429.0 → 0.430.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ shape of this file.
 
 ## Unreleased
 
+## 0.430.0 — 25.10.2026
+
+### Added
+
+- **Run records for a CLI with its own commander program** (`/cli`). `recordRuns(program, options)` gives a `startCli` tool WC-LIFE-15 in one call: `--record` and `--no-record`, a failed run for every failed command — a usage error before any action included, named by its command words and never an argument — and a run of every command when the flag or the saved `record` asks. `providerEvent(event)` and `providerRequest(operation)` put a provider call's operation, status and duration into the current command's run from anywhere in the program. `commandRuns(options)` keeps one command's run from a tool's own hooks under `run()`, and `runSettings(flag, saved)` is the rule both follow. zoom-cli, drive-cli and cli-memo replace their own copies with it. A run with no profile now leaves `profile` out rather than writing `""`.
+
 ## 0.429.0 — 25.10.2026
 
 ### Added

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

@@ -0,0 +1,64 @@
+import { type RenderFormat, type Streams } from "@wirecat/cli-base";
+import type { Command } from "commander";
+import type { AppIdentity } from "../ports/app.js";
+import type { RequestEvent } from "../runs/events.js";
+/** What the owner saved: `record` and `keep_runs_for_days`, read from the CLI's own config. */
+export interface SavedRunSettings {
+    record?: boolean | undefined;
+    keepRunsForDays?: number | undefined;
+}
+export interface RunSettings {
+    record: boolean;
+    keepFailedRuns: boolean;
+    keepRunsForDays: number;
+}
+/** `--record`/`--no-record` first, then the config; a failure is kept unless either says no (WC-LIFE-15). */
+export declare const runSettings: (flag: boolean | undefined, saved?: SavedRunSettings) => RunSettings;
+export interface CommandRunOptions {
+    app: AppIdentity;
+    /** The owner's saved choice. One that throws — a config that will not load — leaves the defaults. */
+    settings: () => SavedRunSettings;
+    /**
+     * The profile the command runs for; one that throws or is empty leaves the run without one. Given only by a CLI
+     * whose first word may be a profile, so a failure before any command skips that word when naming the run.
+     */
+    profile?: () => string | undefined;
+    /** An agent's run is named `mcp <command>`. Read from the program's environment when left out. */
+    agent?: boolean;
+    /** The data stream's format, which the warning about an unwritable run follows; `--json`/`--jsonl` when left out. */
+    format?: () => RenderFormat;
+    /** What a failed run keeps of the error: cli-memo turns a Commander or Valibot error into a CLI error first. */
+    recognise?: (error: unknown) => unknown;
+    env?: NodeJS.ProcessEnv;
+    streams?: Streams;
+}
+/** One command's run at a time, for a CLI that starts and ends it from its own hooks (zoom-cli under `run()`). */
+export interface CommandRuns {
+    start(action: Command): void;
+    succeed(): Promise<void>;
+    fail(error: unknown): Promise<void>;
+    /** The id the command's run has, kept or not, so its answer can name it. */
+    runId(): string | undefined;
+    events(event: RequestEvent): void;
+}
+export declare const commandRuns: (options: CommandRunOptions) => CommandRuns;
+/** For a provider client far from the program: the event lands in the current command's run, or nowhere. */
+export declare const providerEvent: (event: RequestEvent) => void;
+/**
+ * Times one provider call under a fixed operation name — nothing the call carries goes into the run. The returned
+ * function ends it; an `error` or an `errorCode` makes it a failed one.
+ */
+export declare const providerRequest: (operation: string, sink?: (event: RequestEvent) => void) => ({ status, error, errorCode }?: {
+    status?: number;
+    error?: unknown;
+    errorCode?: string;
+}) => void;
+/**
+ * WC-LIFE-15 for a CLI with its own commander program (`startCli`, not `run()`): adds `--record` and `--no-record`,
+ * keeps every failed command as a run — a usage error before any action too — and every command when recording is
+ * on. Call it after the program's other `parseAsync` wrappers, so its own is the outermost and sees how the parse
+ * really ended; a refusal in an earlier `preAction` hook is then kept under the words read from the line.
+ */
+export declare const recordRuns: (program: Command, options: CommandRunOptions & {
+    content: string;
+}) => void;

package/dist/cli/command-runs.js

@@ -0,0 +1,171 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { isCliError } from "@wirecat/cli-base";
+import { startRecording, wasSettled } from "../runs/recording.js";
+import { KEEP_RUNS_FOR_DAYS } from "../runs/run.js";
+import { environmentOf } from "./context.js";
+/** `--record`/`--no-record` first, then the config; a failure is kept unless either says no (WC-LIFE-15). */
+export const runSettings = (flag, saved = {}) => {
+    const record = flag ?? saved.record ?? false;
+    return {
+        record,
+        keepFailedRuns: record || (flag !== false && saved.record !== false),
+        keepRunsForDays: saved.keepRunsForDays ?? KEEP_RUNS_FOR_DAYS,
+    };
+};
+const SKIPPED = new Set(["runs", "help"]);
+const pathOf = (command) => {
+    const words = [];
+    for (let at = command; at?.parent; at = at.parent)
+        words.unshift(at.name());
+    return words;
+};
+const tracker = (options) => {
+    let recording;
+    const open = (program, words, flag, format) => {
+        recording = undefined;
+        // Reading the log is not worth a run of its own.
+        if (SKIPPED.has(words[0] ?? ""))
+            return;
+        const environment = environmentOf(program);
+        let saved = {};
+        try {
+            saved = options.settings();
+        }
+        catch { }
+        let profile;
+        try {
+            profile = options.profile?.() || undefined;
+        }
+        catch { }
+        const settings = runSettings(flag, saved);
+        const agent = options.agent ?? environment.agent !== undefined;
+        const streams = options.streams ?? environment.streams;
+        const env = options.env ?? environment.env;
+        recording = startRecording({
+            app: options.app,
+            command: `${agent ? "mcp " : ""}${words.join(" ") || options.app.command}`,
+            ...(profile === undefined ? {} : { profile }),
+            record: settings.record,
+            keepFailed: settings.keepFailedRuns,
+            keepDays: settings.keepRunsForDays,
+            trace: false,
+            format,
+            ...(streams ? { streams } : {}),
+            ...(env ? { env } : {}),
+        });
+    };
+    const finish = () => {
+        const done = recording;
+        recording = undefined;
+        return done;
+    };
+    return {
+        start(action) {
+            const flags = action.optsWithGlobals();
+            const json = (flags.json !== undefined && flags.json !== false) || Boolean(flags.jsonl);
+            open(action, pathOf(action), flags.record, options.format?.() ?? (json ? "json" : "pretty"));
+        },
+        async succeed() {
+            await finish()?.succeed();
+        },
+        async fail(error) {
+            await finish()?.fail(options.recognise ? options.recognise(error) : error);
+        },
+        runId: () => recording?.runId,
+        events: (event) => recording?.events(event),
+        open,
+    };
+};
+export const commandRuns = (options) => tracker(options);
+const parses = new AsyncLocalStorage();
+/** For a provider client far from the program: the event lands in the current command's run, or nowhere. */
+export const providerEvent = (event) => parses.getStore()?.runs.events(event);
+/**
+ * Times one provider call under a fixed operation name — nothing the call carries goes into the run. The returned
+ * function ends it; an `error` or an `errorCode` makes it a failed one.
+ */
+export const providerRequest = (operation, sink = providerEvent) => {
+    sink({ event: "request", operation });
+    const started = performance.now();
+    return ({ status, error, errorCode } = {}) => {
+        const failed = error !== undefined || errorCode !== undefined;
+        sink({
+            event: "response",
+            operation,
+            ...(status === undefined ? {} : { status }),
+            durationMs: Math.round(performance.now() - started),
+            outcome: failed ? "error" : "ok",
+            ...(failed ? { errorCode: errorCode ?? (isCliError(error) ? error.code : "provider_error") } : {}),
+        });
+    };
+};
+/** `files list` from `files list abc --limit 5`: command words only, never an argument. */
+const pathFromArgs = (program, args, profileWord) => {
+    const words = [];
+    let at = program;
+    let skipped = !profileWord;
+    for (const arg of args) {
+        if (arg.startsWith("-"))
+            continue;
+        const next = at.commands.find((one) => one.name() === arg || one.aliases().includes(arg));
+        if (next) {
+            words.push(arg);
+            at = next;
+        }
+        else if (words.length === 0 && !skipped)
+            skipped = true;
+        else
+            break;
+    }
+    return words;
+};
+const isHelpExit = (error) => {
+    const { code, exitCode } = (error ?? {});
+    return typeof code === "string" && code.startsWith("commander.") && (exitCode === 0 || code === "commander.help");
+};
+/**
+ * WC-LIFE-15 for a CLI with its own commander program (`startCli`, not `run()`): adds `--record` and `--no-record`,
+ * keeps every failed command as a run — a usage error before any action too — and every command when recording is
+ * on. Call it after the program's other `parseAsync` wrappers, so its own is the outermost and sees how the parse
+ * really ended; a refusal in an earlier `preAction` hook is then kept under the words read from the line.
+ */
+export const recordRuns = (program, options) => {
+    program
+        .option("--record", `keep this run — ids and timings, never ${options.content}`)
+        .option("--no-record", "do not keep this run, even if it fails");
+    program.hook("preAction", (_root, action) => {
+        const parse = parses.getStore();
+        if (!parse)
+            return;
+        parse.started = true;
+        parse.runs.start(action);
+    });
+    const parseAsync = program.parseAsync.bind(program);
+    program.parseAsync = (argv, settings) => {
+        const parse = { runs: tracker(options), started: false };
+        return parses.run(parse, async () => {
+            try {
+                const parsed = await parseAsync(argv, settings);
+                await parse.runs.succeed();
+                return parsed;
+            }
+            catch (error) {
+                if (!isHelpExit(error) && !wasSettled(error)) {
+                    try {
+                        if (!parse.started) {
+                            const args = settings?.from === "user" ? (argv ?? []) : (argv ?? process.argv).slice(2);
+                            const flag = args.includes("--no-record") ? false : args.includes("--record") ? true : undefined;
+                            const json = args.some((arg) => arg === "--json" || arg.startsWith("--json=") || arg === "--jsonl");
+                            const words = pathFromArgs(program, args, options.profile !== undefined);
+                            const format = options.format?.() ?? (json ? "json" : "pretty");
+                            parse.runs.open(program, words, flag, format);
+                        }
+                        await parse.runs.fail(error);
+                    }
+                    catch { }
+                }
+                throw error;
+            }
+        });
+    };
+};

package/dist/cli/index.d.ts

@@ -50,6 +50,7 @@ export { BotTokenStore, type BotTokenStoreOptions } from "./bot/token.js";
 export { PressLog, UpdatesCursor } from "./bot/updates.js";
 export type { CommandAvailability, DiscoveredCommand } from "./command-availability.js";
 export { commandContract, type JsonSchema, SCHEMA_DIALECT } from "./command-contract.js";
+export { type CommandRunOptions, type CommandRuns, commandRuns, providerEvent, providerRequest, type RunSettings, recordRuns, runSettings, type SavedRunSettings, } from "./command-runs.js";
 export { CONTRACT } from "./commands-command.js";
 export { refuseUnknownKey } from "./config-command.js";
 export { type ConfigIssue, type ConfigIssueKind, checkConfigText, issueMessage } from "./config-issues.js";

package/dist/cli/index.js

@@ -43,6 +43,7 @@ export { botFiles, botsDirectory, ChatRegistry, registryProfiles } from "./bot/r
 export { BotTokenStore } from "./bot/token.js";
 export { PressLog, UpdatesCursor } from "./bot/updates.js";
 export { commandContract, SCHEMA_DIALECT } from "./command-contract.js";
+export { commandRuns, providerEvent, providerRequest, recordRuns, runSettings, } from "./command-runs.js";
 export { CONTRACT } from "./commands-command.js";
 export { refuseUnknownKey } from "./config-command.js";
 export { checkConfigText, issueMessage } from "./config-issues.js";

package/dist/meetings/mcp/index.d.ts

@@ -38,7 +38,6 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -54,11 +53,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -76,11 +75,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -102,6 +101,7 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -188,7 +188,6 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -204,11 +203,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -226,11 +225,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -252,6 +251,7 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -338,7 +338,6 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -354,11 +353,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -376,11 +375,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -402,6 +401,7 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -488,7 +488,6 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -504,11 +503,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -526,11 +525,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -552,6 +551,7 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -638,7 +638,6 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -654,11 +653,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -676,11 +675,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
-            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -702,6 +701,7 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
+            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.429.0",
+  "version": "0.430.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",