@wirecat/cli-core 0.343.0 → 0.345.0

package/dist/cli/messenger/messages-search-command.js

@@ -46,8 +46,8 @@ export const messagesSearchCommand = (messenger) => {
 coverage says what was searched and coverage.next what would improve it.`
         : `Search reads the local archive: what \`${messenger.app.command} serve\` has kept since the account was linked.
 Keep serve running so new messages are searchable.`} Notes are
-\`${messenger.app.command} search notes\`, messages and notes at once \`${messenger.app.command} search all\`; mail is memo's:
-\`memo search mail\`.
+\`${messenger.app.command} search notes\`, messages and notes at once \`${messenger.app.command} search all\`; for mail,
+the separate memo CLI: \`memo search mail\`.
 A bare word looks in message text, voice transcripts, file names and file text. text:, transcript:,
 content: (the text of files) and filename: (their names) narrow it to one —
 \`${messenger.app.command} search messages 'content:invoice'\`. chat: narrows it to one chat; has:voice, has:file and

package/dist/cli/messenger/observed.js

@@ -32,8 +32,15 @@ export const observed = (messenger, events) => {
             throw error;
         }
     };
+    const counted = async (operation, onEvent, work) => {
+        const counts = {};
+        await timed(operation, {}, () => work((event) => {
+            counts[event.event] = (counts[event.event] ?? 0) + 1;
+            onEvent(event);
+        }), () => ({ counts }));
+    };
     const mint = messenger.newSendId;
-    const { chats, history, contact, around } = messenger;
+    const { chats, history, contact, around, watch, listen } = messenger;
     // A method not listed here is timed under its own name, with no ids until a line here names them.
     return throughWrapper(messenger, {
         self: () => messenger.self(),
@@ -75,15 +82,14 @@ export const observed = (messenger, events) => {
                 ...(options.threadId ? { thread: options.threadId } : {}),
             },
         }, () => messenger.send(chatId, text, options), (sent) => ({ ids: { message_id: sent.message.id } })),
-        ...(messenger.watch
+        ...(watch
+            ? {
+                watch: (onEvent, signal, onReady) => counted("messages.watch", onEvent, (counting) => watch.call(messenger, counting, signal, onReady)),
+            }
+            : {}),
+        ...(listen
             ? {
-                watch: async (onEvent, signal, onReady) => {
-                    const counts = {};
-                    await timed("messages.watch", {}, () => messenger.watch?.((event) => {
-                        counts[event.event] = (counts[event.event] ?? 0) + 1;
-                        onEvent(event);
-                    }, signal, onReady) ?? Promise.resolve(), () => ({ counts }));
-                },
+                listen: (onEvent, signal) => counted("adapter.listen", onEvent, (counting) => listen.call(messenger, counting, signal)),
             }
             : {}),
         logout: () => timed("session.logout", {}, () => messenger.logout()),

package/dist/cli/messenger/private-people-command.js

@@ -15,6 +15,7 @@ const everyNote = (command, items) => listOf(command, { items, limit: Math.max(1
 export const privatePeopleCommands = (messenger) => {
     const alias = new Command("alias").description("a private local display name in the selected account");
     annotate(alias.command("set"), { effects: LOCAL_WRITE })
+        .description("your own name for a person in this account; kept on this machine, never sent")
         .argument("<person>")
         .argument("<alias>")
         .action(async function (person, value) {
@@ -23,6 +24,7 @@ export const privatePeopleCommands = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.privatePeople.alias(person, value)))));
     });
     annotate(alias.command("rm"), { effects: LOCAL_WRITE })
+        .description("drop your local name for a person; their own name shows again")
         .argument("<person>")
         .action(async function (person) {
         const context = messengerContext(this, messenger);
@@ -30,13 +32,16 @@ export const privatePeopleCommands = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.privatePeople.alias(person, null)))));
     });
     const notes = new Command("notes").description("your private notes on a stored contact, the same in every account that sees them");
-    withQuery(annotate(notes.command("list"), { effects: LOCAL_READ }).argument("<person>"), NOTES_QUERY).action(async function (person, words) {
+    withQuery(annotate(notes.command("list"), { effects: LOCAL_READ })
+        .description("every private note you keep on a person, oldest first")
+        .argument("<person>"), NOTES_QUERY).action(async function (person, words) {
         const context = messengerContext(this, messenger);
         listQuery(typedQuery(words), NOTES_QUERY, "contacts notes list");
         const items = await context.withServices((services) => services.privatePeople.notes(person));
         renderAnswer(this, context, everyNote("contacts notes list", items));
     });
     annotate(notes.command("show"), { effects: LOCAL_READ, output: { entity: "contact_note" } })
+        .description("one private note on a person, with its revision for edit")
         .argument("<person>")
         .argument("<id>")
         .action(async function (person, id) {
@@ -48,6 +53,9 @@ export const privatePeopleCommands = (messenger) => {
             effects: LOCAL_WRITE,
             output: { entity: "contact_note" },
         }), { name: "text", description: "the note's text" })
+            .description(name === "add"
+            ? "add a private note on a person from stdin or --file; never sent"
+            : "replace a note's text; --revision must match the one you read")
             .argument("<person>")
             .addOption(ownerOnlyOption("--file <path>", "read note text from a file; omitted or - reads stdin"));
         if (name === "edit")
@@ -67,6 +75,7 @@ export const privatePeopleCommands = (messenger) => {
         });
     }
     annotate(notes.command("remove"), { effects: LOCAL_WRITE })
+        .description("delete one private note on a person")
         .argument("<person>")
         .argument("<id>")
         .action(async function (person, id) {

package/dist/cli/messenger/review.js

@@ -26,7 +26,7 @@ export const unansweredHours = (value, flag = "--unanswered") => value === true
  */
 export const reviewCommand = (messenger) => annotate(new Command("review"), {
     effects: REMOTE_READ,
-    output: { entity: "message", view: "message.summary" },
+    output: { entity: "message", view: "summary" },
     query: REVIEW_QUERY,
 })
     .description("every message, yours too, in chats that changed since a point — for reviewing who owes what")

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

@@ -15,7 +15,7 @@ import { topicsSearchCommand } from "./topics-command.js";
 const onlyOf = (value) => {
     const chosen = value.split(",").map((one) => one.trim());
     if (chosen.includes("mail"))
-        throw new CliError("validation_error", "mail is memo's: install @wirecat/cli-memo, then `memo search mail …`");
+        throw new CliError("validation_error", "mail is searched by the separate memo CLI: install @wirecat/cli-memo, then `memo search mail …`");
     const unknown = chosen.find((one) => !SOURCE_SEARCHED.includes(one));
     if (unknown !== undefined || chosen.length === 0)
         throw new CliError("validation_error", `--only takes ${SOURCE_SEARCHED.join(", ")}, separated by commas; meetings when --source names a meeting account`);
@@ -37,7 +37,7 @@ const allCommand = (messenger) => {
         ? "search messenger messages and notes in the local store, and the messenger's server for messages " +
             "(--backend; notes are local only)"
         : "search messenger messages and notes in the local store") +
-        ", and a meeting account's transcripts when --source names one — best match first; not mail (memo search mail), " +
+        ", and a meeting account's transcripts when --source names one — best match first; not mail (the separate memo CLI searches it: memo search mail), " +
         "tasks, people, memories or projects. Use it when you do not know where something was written; search messages " +
         "or notes reads one kind with all its fields")
         .argument("<query...>", 'strict Lucene query: words, "phrases", AND/OR/NOT, field groups and date ranges')
@@ -149,7 +149,7 @@ const notesCommand = (messenger) => annotate(new Command("notes"), { effects: LO
  * hierarchy"). `topics` only where the CLI has forum topics.
  */
 export const searchCommand = (messenger, { topics = false } = {}) => {
-    const search = new Command("search").description("find things by text: one resource when you know it (messages, notes), or search all across messages and notes; mail is memo search mail");
+    const search = new Command("search").description("find things by text: one resource when you know it (messages, notes), or search all across messages and notes; for mail, the separate memo CLI: memo search mail");
     search
         .addCommand(allCommand(messenger))
         .addCommand(messagesSearchCommand(messenger))

package/dist/cli/messenger/store-maintenance-command.d.ts

@@ -2,9 +2,9 @@ import { Command } from "commander";
 import type { Messenger } from "./context.js";
 /** `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. */
 export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
-    error?: undefined;
     path: string;
     exists: boolean;
+    error?: undefined;
 } | {
     path: string;
     exists: boolean;

package/dist/cli/messenger/store-maintenance-command.js

@@ -569,8 +569,10 @@ const restoreFrom = async (command, messenger, backup, given) => {
     const schema = await backupSchema(backup);
     const stamp = stampNow();
     const kept = existsSync(path) ? `${path}.before-restore-${stamp}` : null;
-    if (kept)
-        await quiesce(path, messenger, "restore", (message) => renderer.warn(message));
+    if (kept) {
+        const waitMs = environmentOf(command).storeLockWaitMs;
+        await quiesce(path, messenger, "restore", (message) => renderer.warn(message), waitMs);
+    }
     else
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     const incoming = `${path}.restoring-${stamp}`;
@@ -614,12 +616,13 @@ const backupSchema = async (backup) => {
     }
     return schema;
 };
+const STORE_LOCK_WAIT_MS = 1_000;
 /**
  * No other process has the file open, no write is under way, and the write-ahead log is folded in,
  * so the file set aside is whole on its own. In WAL mode SQLite cannot say who has the file open —
  * `EXCLUSIVE` behaves as `IMMEDIATE` — so that is asked of the system.
  */
-const quiesce = async (path, messenger, then, warn) => {
+const quiesce = async (path, messenger, then, warn, waitMs = STORE_LOCK_WAIT_MS) => {
     const { command } = messenger.app;
     const files = [path, `${path}-wal`, `${path}-shm`]
         .filter((file) => existsSync(file))
@@ -634,7 +637,7 @@ const quiesce = async (path, messenger, then, warn) => {
     }
     const database = await openCache(path);
     try {
-        database.exec("PRAGMA busy_timeout = 1000");
+        database.exec(`PRAGMA busy_timeout = ${waitMs}`);
         database.exec("PRAGMA wal_checkpoint(TRUNCATE)");
         try {
             database.exec("BEGIN IMMEDIATE");
@@ -673,7 +676,7 @@ const resetCommand = (messenger) => annotate(new Command("reset"), { effects: LO
         if (!/^\s*y(es)?\s*$/i.test(answer))
             throw new CliError("cancelled", "cancelled — the store is unchanged");
     }
-    await quiesce(path, messenger, "reset", (message) => renderer.warn(message));
+    await quiesce(path, messenger, "reset", (message) => renderer.warn(message), environmentOf(this).storeLockWaitMs);
     const backup = keep ? `${path}.backup-${stampNow()}` : null;
     let backedUp = null;
     if (backup) {

package/dist/cli/moved.js

@@ -4,7 +4,7 @@
  * "unknown command"; a path the program still mounts never reaches it.
  */
 export const MOVED_TO_MEMO = {
-    "search mail": { what: "mail is memo's", memo: "memo search mail …" },
+    "search mail": { what: "mail is searched by the separate memo CLI", memo: "memo search mail …" },
 };
 export const movedPointer = (path) => {
     const moved = MOVED_TO_MEMO[path];

package/dist/cli/profile.d.ts

@@ -2,6 +2,8 @@ import type { Command } from "commander";
 /** How the command line names this profile: always the first word, since none is assumed. */
 export declare const asFirstWord: (profile: string) => string;
 export declare const usableProfileName: (profile: string) => string;
+/** The top-level commands that never read a profile; every other one is `<tool> <profile> …`. */
+export declare const PROFILE_FREE: ReadonlySet<string>;
 /**
  * Every word that means a command at the top level. Taken off the built program rather than
  * written out, because a list written out goes stale the day a command is added — and `help` is in
@@ -13,10 +15,12 @@ export declare const commandWords: (program: Command) => Set<string>;
  * `TG_PROFILE=personal tg chats list`, with no flag in either. An option is never a profile, so
  * `tg --json chats list` still works.
  */
-export declare const liftProfile: (argv: string[], words: Set<string>) => {
+export declare const liftProfile: (argv: string[], words: Set<string>, valued?: ReadonlySet<string>) => {
     profile?: string;
     rest: string[];
 };
+/** The root's options that take the next word as their value: `--timeout 30s`. */
+export declare const valuedOptions: (program: Command) => Set<string>;
 /**
  * Refused at creation, which is the only moment it can still be explained: a profile named after a
  * command could never be selected, because `tg chats` has to mean the command.

package/dist/cli/profile.js

@@ -14,6 +14,8 @@ export const usableProfileName = (profile) => {
     }
     return profile;
 };
+/** The top-level commands that never read a profile; every other one is `<tool> <profile> …`. */
+export const PROFILE_FREE = new Set(["commands", "complete", "guide", "help", "skill", "upgrade"]);
 /**
  * Every word that means a command at the top level. Taken off the built program rather than
  * written out, because a list written out goes stale the day a command is added — and `help` is in
@@ -25,12 +27,20 @@ export const commandWords = (program) => new Set(["help", ...program.commands.fl
  * `TG_PROFILE=personal tg chats list`, with no flag in either. An option is never a profile, so
  * `tg --json chats list` still works.
  */
-export const liftProfile = (argv, words) => {
-    const [first, ...rest] = argv;
+export const liftProfile = (argv, words, valued = new Set()) => {
+    // `tg --json personal chats list`: options before the profile are skipped over, with the value an option takes.
+    let at = 0;
+    while (argv[at]?.startsWith("-") && argv[at] !== "--")
+        at += valued.has(argv[at]) ? 2 : 1;
+    const first = argv[at];
     if (first === undefined || first.startsWith("-") || words.has(first))
         return { rest: argv };
-    return { profile: first, rest };
+    return { profile: first, rest: [...argv.slice(0, at), ...argv.slice(at + 1)] };
 };
+/** The root's options that take the next word as their value: `--timeout 30s`. */
+export const valuedOptions = (program) => new Set(program.options
+    .filter((option) => option.required)
+    .flatMap((option) => [option.long, option.short].filter((flag) => flag !== undefined)));
 /**
  * Refused at creation, which is the only moment it can still be explained: a profile named after a
  * command could never be selected, because `tg chats` has to mean the command.

package/dist/cli/program.d.ts

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { type AppIdentity } from "../ports/app.js";
 import { type BaseEnvironment } from "./context.js";
+import { type FirstScreen } from "./help/first-screen.js";
 import { type GlobalFlags, type ResolveOptions, type Settings } from "./settings.js";
 export interface ProgramDefinition {
     app: AppIdentity;
@@ -11,6 +12,8 @@ export interface ProgramDefinition {
         resolveSettings: (flags?: GlobalFlags, options?: ResolveOptions) => Pick<Settings, "profile" | "keepFailedRuns" | "keepRunsForDays" | "skillHint">;
     };
     configure?: (program: Command) => void;
+    /** The tool's pitch and "what you can do" lines on `--help` and a bare run. */
+    firstScreen?: FirstScreen;
     prepare?: (program: Command, environment: RunOptions) => void | Promise<void>;
     onFailure?: (error: unknown, program: Command) => void | Promise<void>;
 }
@@ -23,7 +26,7 @@ export interface ProgramOptions {
  * The command tree, built fresh on each call. Commander is global state by default —
  * `exitOverride` and the write hooks turn it into a value a test can drive.
  */
-export declare const createProgram: ({ app, commands, configure }: ProgramDefinition, { out, err }?: ProgramOptions) => Command;
+export declare const createProgram: ({ app, commands, configure, firstScreen }: ProgramDefinition, { out, err }?: ProgramOptions) => Command;
 export type RunOptions = BaseEnvironment & Record<string, unknown>;
 /**
  * An interactive command run without a terminal — an agent's `session start --qr-file` — waits on a person scanning a

package/dist/cli/program.js

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { CliError, errorObjectOf, errorRecordOf, exitCodeFor, exitCodeOfError, processStreams, renderError, resolvePaths, } from "@wirecat/cli-base";
 import { metaOf, refuseJoinedPath } from "@wirecat/cli-base/commands";
 import { skillHint } from "@wirecat/cli-base/skill";
-import { Command } from "commander";
+import { Command, Help } from "commander";
 import { relayCommand } from "../background/relay.js";
 import { failingNotice, scheduledRuns } from "../background/schedules.js";
 import { parseDuration } from "../domain/duration.js";
@@ -18,11 +18,13 @@ import { refuseWriteBeforeConnecting } from "./early-refusal.js";
 import { changesAuthorityNow, isLogin, isStoreChange, judgedEffects, judgedTargets, STORE_CHANGE_REFUSAL, } from "./effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "./envelope.js";
 import { byteCount, DEFAULT_COMMAND_MS, DEFAULT_OUTPUT_BYTES, execution } from "./execution.js";
+import { installHelp } from "./help/first-screen.js";
+import { sectionCoreGroups } from "./help/sections.js";
 import { MAX_BUFFERED_INPUT, provideInputPolicy } from "./input-policy.js";
 import { checkJson, liftJson } from "./json-fields.js";
 import { movedPath, movedPointer } from "./moved.js";
 import { PreviewComplete, preview } from "./preview.js";
-import { commandWords, liftProfile } from "./profile.js";
+import { commandWords, liftProfile, PROFILE_FREE, valuedOptions } from "./profile.js";
 import { absolutePaths, relayTarget } from "./relay-route.js";
 import { settingsFor } from "./settings.js";
 import { commandAt } from "./steps.js";
@@ -30,7 +32,7 @@ import { commandAt } from "./steps.js";
  * The command tree, built fresh on each call. Commander is global state by default —
  * `exitOverride` and the write hooks turn it into a value a test can drive.
  */
-export const createProgram = ({ app, commands, configure }, { out, err } = {}) => {
+export const createProgram = ({ app, commands, configure, firstScreen }, { out, err } = {}) => {
     const program = new Command();
     program
         .name(app.command)
@@ -51,8 +53,8 @@ export const createProgram = ({ app, commands, configure }, { out, err } = {}) =
         .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 and mail as reference, title, time, sender and excerpt only")
-        .option("--full", "found messages and mail with their whole text and every provider field")
+        .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("--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")
@@ -61,6 +63,16 @@ export const createProgram = ({ app, commands, configure }, { out, err } = {}) =
     for (const command of commands())
         program.addCommand(command);
     configure?.(program);
+    sectionCoreGroups(program);
+    installHelp(program, { pitch: app.description, ...firstScreen });
+    // Commander builds a usage line from the command tree, where the profile is not a word.
+    for (const top of program.commands) {
+        if (PROFILE_FREE.has(top.name()))
+            continue;
+        forEachCommand(top, (command) => command.configureHelp({
+            commandUsage: (shown) => `${app.command} <profile>${new Help().commandUsage(shown).slice(app.command.length)}`,
+        }));
+    }
     // Depth-first: Commander does not pass `configureOutput` down to a command added with
     // `addCommand`, so `tg messages --help` would write to the real terminal.
     if (out || err) {
@@ -327,7 +339,7 @@ export const run = async (argv, definition, options = {}) => {
     forEachCommand(program, (child) => child.exitOverride());
     // Before commander, not inside it: commander has no hook that runs before it decides which
     // subcommand it is looking at.
-    const { profile, rest: lifted } = liftProfile(argv, commandWords(program));
+    const { profile, rest: lifted } = liftProfile(argv, commandWords(program), valuedOptions(program));
     // `wa 'chats list' --help` reads "chats list" as a profile and prints the root help with exit 0.
     try {
         // Only before `--`: what follows is a positional, an agent's text among them, never a command word.
@@ -364,7 +376,9 @@ export const run = async (argv, definition, options = {}) => {
     try {
         await control.race(() => program.parseAsync(rest, { from: "user" }));
         const code = exit.code ?? (process.exitCode === undefined ? 0 : Number(process.exitCode));
-        const hint = code === 0 && rest[0] !== "commands" && !rest.includes("--quiet") ? hintFor(definition, rest, options) : undefined;
+        const hint = code === 0 && rest[0] !== "commands" && rest[0] !== "help" && !rest.includes("--quiet")
+            ? hintFor(definition, rest, options)
+            : undefined;
         if (hint)
             streams.diagnostic(hint);
         return code;
@@ -384,7 +398,8 @@ export const run = async (argv, definition, options = {}) => {
                 logVersion(argvLog);
             if (error.exitCode === 0)
                 return 0;
-            let message = error.message.replace(/^error: /, "");
+            // Commander puts its "(Did you mean …?)" on a line of its own; an error is one line.
+            let message = error.message.replace(/^error: /, "").replace(/\s*\n\s*/g, " ");
             if (error.code === "commander.help") {
                 if (reporting.tty ?? process.stdout.isTTY === true) {
                     streams.diagnostic(help.replace(/\n$/, ""));

package/dist/mcp/index.d.ts

@@ -2,3 +2,4 @@ export { type AgentAnswer, type AgentContext, type AgentProgram, type AgentTool,
 export { type BotServerOptions, createBotServer, type RunBotCommand } from "./bot/server.js";
 export { revokeAll } from "./http/oauth.js";
 export { type HttpOptions, MCP_PATH, serveOverHttp } from "./http/serve.js";
+export { type McpCommand, registerCommands } from "./surface.js";

package/dist/mcp/index.js

@@ -3,3 +3,4 @@ export { runCommandForAgent, toolsFromCommands, } from "./agent.js";
 export { createBotServer } from "./bot/server.js";
 export { revokeAll } from "./http/oauth.js";
 export { MCP_PATH, serveOverHttp } from "./http/serve.js";
+export { registerCommands } from "./surface.js";

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

@@ -14,4 +14,5 @@ export interface MeetingCommandDeps {
 export declare const addMeetingCommands: (program: Command, deps: MeetingCommandDeps) => void;
 export { addMeetingPassageCommand, createMeetingPassageCommand, type MeetingPassageFlags, meetingPassageRequest, } from "./passage.js";
 export { addMeetingProjectEvidenceCommand } from "./project-evidence.js";
+export { queryWordsAfterOptions } from "./query-options.js";
 export { addMeetingSearchCommand, createMeetingSearchCommand, type MeetingHitSearch, type MeetingHitSearchOptions, type MeetingSearchFlags, meetingHitSearchRequest, meetingSearchArguments, validateMeetingHitSearch, } from "./search.js";

package/dist/meetings/cli/index.js

@@ -7,6 +7,7 @@ import { MEETING_QUERY } from "../item.js";
 import { pull } from "../pull.js";
 import { listed, MEETING_QUERY_GUIDE, MeetingError, meetingDetailsAnswer, meetingPeople, meetingSummaryAnswer, meetingsList, meetingsQuery, meetingTranscriptAnswer, } from "../reads.js";
 import { SAVE_HELP } from "../save-hints.js";
+import { queryWordsAfterOptions } from "./query-options.js";
 const integer = (text) => {
     if (!/^[1-9]\d*$/.test(text) || !Number.isSafeInteger(Number(text)))
         throw new InvalidArgumentError("expected a positive integer");
@@ -39,10 +40,7 @@ export const addMeetingCommands = (program, deps) => {
         const opts = command.optsWithGlobals();
         deps.write(value, opts.json ? "json" : opts.jsonl ? "jsonl" : "text");
     };
-    const list = group
-        .command("list")
-        .description("stored meetings, newest first")
-        .allowUnknownOption()
+    const list = queryWordsAfterOptions(group.command("list").description("stored meetings, newest first"))
         .argument("[query...]", "field:value terms that narrow the list — the fields are below")
         .addHelpText("after", `\n${fieldsHelp(MEETING_QUERY, MEETING_QUERY_GUIDE)}`);
     annotate(list, { effects: LOCAL_READ, query: defineQuery(MEETING_QUERY), output: { entity: "meeting" } });
@@ -139,4 +137,5 @@ export const addMeetingCommands = (program, deps) => {
 };
 export { addMeetingPassageCommand, createMeetingPassageCommand, meetingPassageRequest, } from "./passage.js";
 export { addMeetingProjectEvidenceCommand } from "./project-evidence.js";
+export { queryWordsAfterOptions } from "./query-options.js";
 export { addMeetingSearchCommand, createMeetingSearchCommand, meetingHitSearchRequest, meetingSearchArguments, validateMeetingHitSearch, } from "./search.js";

package/dist/meetings/cli/project-evidence.js

@@ -3,6 +3,7 @@ import { annotate } from "@wirecat/cli-base/commands";
 import { fieldsHelp } from "@wirecat/cli-base/query";
 import { readMeetingProjectEvidence } from "../project-evidence.js";
 import { MEETING_PROJECT_EVIDENCE_QUERY } from "../project-evidence-query.js";
+import { queryWordsAfterOptions } from "./query-options.js";
 const integer = (value) => {
     if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value)))
         throw new CliError("validation_error", "expected a positive safe integer");
@@ -14,12 +15,11 @@ export const addMeetingProjectEvidenceCommand = (program, deps) => {
         throw new CliError("configuration_error", "meeting command group is unavailable");
     const projects = group.commands.find((command) => command.name() === "projects") ??
         group.command("projects").description("project-name evidence in stored meetings");
-    return annotate(projects
+    return annotate(queryWordsAfterOptions(projects
         .command("evidence")
-        .description("find cited project-name and alias evidence in the local meeting index; does not refresh it or confirm membership")
+        .description("find cited project-name and alias evidence in the local meeting index; does not refresh it or confirm membership"))
         .argument("<project>", "existing project name, key or explicit alias")
         .argument("[query...]", "exact ID fields and a UTC started_at range, joined by AND")
-        .allowUnknownOption()
         .addHelpText("after", `\n${fieldsHelp(MEETING_PROJECT_EVIDENCE_QUERY)}`)
         .option("--limit <n>", "hits in one name page, 1 through 1000 (default 100)", integer)
         .option("--cursor <cursor>", "continue with the same project and frozen selection from next")

package/dist/meetings/cli/query-options.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+/**
+ * Lets a query's `-kind:channel` through as a negated term while a mistyped `--limt` still fails as an unknown
+ * option, with commander's suggestion; after `--` every word is query.
+ */
+export declare const queryWordsAfterOptions: (command: Command) => Command;

package/dist/meetings/cli/query-options.js

@@ -0,0 +1,21 @@
+/**
+ * Lets a query's `-kind:channel` through as a negated term while a mistyped `--limt` still fails as an unknown
+ * option, with commander's suggestion; after `--` every word is query.
+ */
+export const queryWordsAfterOptions = (command) => {
+    command.allowUnknownOption();
+    const parse = command.parseOptions.bind(command);
+    command.parseOptions = (args) => {
+        const parsed = parse(args);
+        const end = parsed.unknown.indexOf("--");
+        const typo = parsed.unknown.slice(0, end < 0 ? undefined : end).find((word) => word.startsWith("--"));
+        if (typo !== undefined) {
+            command.allowUnknownOption(false);
+            command.unknownOption(typo);
+        }
+        if (end >= 0)
+            parsed.unknown.splice(end, 1);
+        return parsed;
+    };
+    return command;
+};