@wirecat/cli-core 0.399.0 → 0.401.0

package/dist/cli/messenger/admin-commands.js

@@ -57,7 +57,7 @@ export const readProfilePhoto = (messenger, path, env) => readUpload("photo", pa
 });
 const updateCommand = (messenger) => {
     const keys = messenger.groupSettings ?? GROUP_SETTINGS;
-    const update = annotate(new Command("update"), { effects: REMOTE_WRITE })
+    const update = annotate(new Command("update"), { output: { entity: "chat_group_change" }, effects: REMOTE_WRITE })
         .summary("change a group or channel's profile and settings")
         .description("rename a group or channel, change its description, or turn one of its settings on or off")
         .argument("<chat>", messenger.chatArgument)
@@ -93,7 +93,7 @@ const updateCommand = (messenger) => {
 };
 const linkCommand = (messenger) => {
     const link = new Command("link").description("a group's invite link");
-    annotate(link.command("show"), { effects: REMOTE_READ })
+    annotate(link.command("show"), { output: { entity: "chat_invite" }, effects: REMOTE_READ })
         .description("the invite link, if you may see it")
         .argument("<chat>", messenger.chatArgument)
         .action(async function (chat) {
@@ -101,7 +101,7 @@ const linkCommand = (messenger) => {
         renderItem(this, context, await context.withServices((services) => services.admin.link(chat)));
     });
     if (messenger.inviteLinkCreate !== false)
-        link.addCommand(annotate(new Command("create"), { effects: REMOTE_WRITE })
+        link.addCommand(annotate(new Command("create"), { output: { entity: "chat_invite_change" }, effects: REMOTE_WRITE })
             .description("make another invite link; nobody is told until you share it")
             .argument("<chat>", messenger.chatArgument)
             .option("--approval", "who joins by it asks first, and an admin lets them in; it then has no use limit")
@@ -132,7 +132,7 @@ const linkCommand = (messenger) => {
             ].join("  ")));
         }));
     if (messenger.inviteLinkRevoke !== false)
-        link.addCommand(annotate(new Command("revoke"), { effects: REMOTE_WRITE })
+        link.addCommand(annotate(new Command("revoke"), { output: { entity: "chat_invite_change" }, effects: REMOTE_WRITE })
             .description("stop one link; for the group's own link, the answer is the new one")
             .argument("<chat>", messenger.chatArgument)
             .argument("<link>", "the link, as `chats link list` shows it")
@@ -141,7 +141,7 @@ const linkCommand = (messenger) => {
             renderItem(this, context, await context.withServices((services) => services.admin.revokeLink(chat, link)));
         }));
     if (messenger.inviteLinkUpdate === true)
-        link.addCommand(annotate(new Command("update"), { effects: REMOTE_WRITE })
+        link.addCommand(annotate(new Command("update"), { output: { entity: "chat_invite_change" }, effects: REMOTE_WRITE })
             .description("change one of your invite links, the group's own one too")
             .argument("<chat>", messenger.chatArgument)
             .argument("<link>", "the link, as `chats link list` shows it")
@@ -158,7 +158,7 @@ const linkCommand = (messenger) => {
                 ...(maxUses === undefined ? {} : { maxUses }),
             })));
         }));
-    link.addCommand(annotate(new Command("reset"), { effects: REMOTE_WRITE })
+    link.addCommand(annotate(new Command("reset"), { output: { entity: "chat_group_change" }, effects: REMOTE_WRITE })
         .description("replace the invite link; the old one stops working")
         .argument("<chat>", messenger.chatArgument)
         .action(async function (chat) {
@@ -171,7 +171,7 @@ const adminsCommand = (messenger) => {
     const offered = messenger.adminRights ?? ADMIN_RIGHTS;
     const admins = new Command("admins").description("give or take back a member's admin rights");
     const picks = messenger.pickAdminRights !== false;
-    const add = annotate(new Command("add"), { effects: REMOTE_WRITE })
+    const add = annotate(new Command("add"), { output: { entity: "chat_admin_change" }, effects: REMOTE_WRITE })
         .summary(picks ? "make a member an admin with these rights" : "make a member an admin, with every right")
         .description(picks
         ? "make a member an admin with these rights"
@@ -185,7 +185,7 @@ const adminsCommand = (messenger) => {
         const rights = picks ? rightsOf(offered, this.opts().can) : [...offered];
         renderItem(this, context, await context.withServices((services) => services.admin.addAdmin(chat, person, rights)));
     }));
-    admins.addCommand(annotate(new Command("remove"), { effects: REMOTE_WRITE })
+    admins.addCommand(annotate(new Command("remove"), { output: { entity: "chat_admin_change" }, effects: REMOTE_WRITE })
         .description("take an admin's rights back; they stay a member")
         .argument("<chat>", messenger.chatArgument)
         .argument("<person>", "an id, or part of a name")
@@ -223,7 +223,7 @@ const requestsCommand = (messenger) => {
         ["accept", true, "let them in; the group sees them join"],
         ["decline", false, "turn the request away"],
     ]) {
-        const answer = annotate(new Command(verb), { effects: REMOTE_WRITE })
+        const answer = annotate(new Command(verb), { output: { entity: "chat_request_change" }, effects: REMOTE_WRITE })
             .description(help)
             .argument("<chat>", messenger.chatArgument)
             .argument(everyone ? "[person]" : "<person>", "who asked: an id from `chats requests list`");
@@ -247,7 +247,7 @@ const requestsCommand = (messenger) => {
 };
 /** `chats create`, `join`, `leave`, `update` and `link`: the help text is max-cli's, the one both tools say (standard, help rule 2). */
 export const groupCommands = (messenger) => [
-    annotate(new Command("create"), { effects: REMOTE_WRITE })
+    annotate(new Command("create"), { output: { entity: "chat_group_change" }, effects: REMOTE_WRITE })
         .description("create a group or a channel; the people added are told")
         .argument("<title>", "the group's name")
         .argument("[person...]", "people to add: an id, or part of a name")
@@ -257,14 +257,14 @@ export const groupCommands = (messenger) => [
         const { channel } = this.opts();
         renderItem(this, context, await context.withServices((services) => services.admin.create({ title, people, channel: channel === true })));
     }),
-    annotate(new Command("join"), { effects: REMOTE_WRITE })
+    annotate(new Command("join"), { output: { entity: "chat_group_change" }, effects: REMOTE_WRITE })
         .description("join a group or channel by its link; the others in it see that you joined")
         .argument("<link>", `an invite link, or a public one`)
         .action(async function (link) {
         const context = messengerContext(this, messenger);
         renderItem(this, context, await context.withServices((services) => services.admin.join(link)));
     }),
-    annotate(new Command("leave"), { effects: REMOTE_WRITE })
+    annotate(new Command("leave"), { output: { entity: "chat_removal" }, effects: REMOTE_WRITE })
         .description("leave a group or channel; the others in it see that you left")
         .argument("<chat>", messenger.chatArgument)
         .action(async function (chat) {

package/dist/cli/messenger/admin-contacts-command.js

@@ -18,7 +18,10 @@ export const contactWriteCommands = (messenger) => {
         ["remove", "remove a person from your contacts; the chat stays, a name you gave them may not"],
         ["block", "stop a person from writing to you — they need not be a contact"],
         ["unblock", "let a blocked person write to you again"],
-    ].map(([name, description, summary]) => annotate(new Command(name), { effects: REMOTE_WRITE })
+    ].map(([name, description, summary]) => annotate(new Command(name), {
+        effects: REMOTE_WRITE,
+        output: { entity: name === "add" ? "contact_update" : "contact_state_change" },
+    })
         .summary(summary ?? description)
         .description(description)
         .argument("<person>", PERSON)
@@ -27,7 +30,7 @@ export const contactWriteCommands = (messenger) => {
         const done = await context.withServices((services) => services.people[name](person));
         renderAnswer(this, context, itemOf(snakeKeys(done)));
     }));
-    const rename = annotate(new Command("rename"), { effects: REMOTE_WRITE })
+    const rename = annotate(new Command("rename"), { effects: REMOTE_WRITE, output: { entity: "contact_update" } })
         .summary("change a contact's name in the messenger address book")
         .description("rename the contact in the messenger address book; use contacts alias for a private local name")
         .argument("<person>", PERSON)
@@ -39,7 +42,7 @@ export const contactWriteCommands = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(renamed)));
     });
     /** A file rather than argv: these are phone numbers, and argv is read by `ps` and kept by the shell. */
-    const importing = annotate(new Command("import"), { effects: REMOTE_WRITE })
+    const importing = annotate(new Command("import"), { effects: REMOTE_WRITE, output: { entity: "contact_import" } })
         .description("upload phone numbers and add the people the messenger has under them")
         .argument("<file>", "one person per line: number, then a comma, a tab or a semicolon, then the name")
         .action(async function (file) {

package/dist/cli/messenger/admin-folders-command.js

@@ -57,7 +57,7 @@ export const foldersCommand = (messenger) => {
         const found = await context.withServices((services) => services.folders.show(folder));
         renderAnswer(this, context, itemOf(folderAnswer(found)));
     }));
-    folders.addCommand(withRules(annotate(new Command("create"), { effects: REMOTE_WRITE })
+    folders.addCommand(withRules(annotate(new Command("create"), { output: { entity: "chat_folder_change" }, effects: REMOTE_WRITE })
         .description("create a chat folder")
         .argument("<title>", "the folder's name; the app may refuse a long one")
         .option("--chat <chat>", "a chat to put in it, by id or name; repeat it for more", collect), messenger, false).action(async function (title) {
@@ -66,7 +66,7 @@ export const foldersCommand = (messenger) => {
         const rules = rulesOf(this);
         renderItem(this, context, await context.withServices((services) => services.folders.create(title, chat, rules)));
     }));
-    folders.addCommand(withRules(annotate(new Command("update"), { effects: REMOTE_WRITE })
+    folders.addCommand(withRules(annotate(new Command("update"), { output: { entity: "chat_folder_change" }, effects: REMOTE_WRITE })
         .description("rename a folder, or change which chats are in it")
         .argument("<folder>", "folder id, or its title exactly")
         .option("--title <title>", "a new name")
@@ -82,7 +82,7 @@ export const foldersCommand = (messenger) => {
         };
         renderItem(this, context, await context.withServices((services) => services.folders.update(folder, edit)));
     }));
-    folders.addCommand(annotate(new Command("delete"), { effects: REMOTE_WRITE })
+    folders.addCommand(annotate(new Command("delete"), { output: { entity: "chat_folder_removal" }, effects: REMOTE_WRITE })
         .description("delete a folder; the chats in it stay")
         .argument("<folder>", "folder id, or its title exactly")
         .action(async function (folder) {
@@ -90,7 +90,7 @@ export const foldersCommand = (messenger) => {
         renderItem(this, context, await context.withServices((services) => services.folders.delete(folder)));
     }));
     if (messenger.folderOrder !== false)
-        folders.addCommand(annotate(new Command("order"), { effects: REMOTE_WRITE })
+        folders.addCommand(annotate(new Command("order"), { output: { entity: "chat_folder_order" }, effects: REMOTE_WRITE })
             .description("put folders in this order; the ones not named keep theirs after them")
             .argument("<folders...>", "folder ids, or titles exactly, first one first")
             .action(async function (typed) {
@@ -98,7 +98,7 @@ export const foldersCommand = (messenger) => {
             renderItem(this, context, await context.withServices((services) => services.folders.order(typed)));
         }));
     if (messenger.folderJoin !== false)
-        folders.addCommand(annotate(new Command("join"), { effects: REMOTE_WRITE })
+        folders.addCommand(annotate(new Command("join"), { output: { entity: "chat_folder_change" }, effects: REMOTE_WRITE })
             .description("add a folder someone shared by a link; joins every chat in it, and the others there see you joined")
             .argument("<link>", "the folder's link, as t.me/addlist/…")
             .action(async function (link) {

package/dist/cli/messenger/admin-moderation-command.js

@@ -12,14 +12,14 @@ import { messengerContext } from "./context.js";
 /** `chats rules show|set|unset`: the rules live in a file of this profile, and only the chat's id is asked of the messenger. */
 export const rulesCommand = (messenger) => {
     const rules = new Command("rules").description("what `chats moderate` judges a group by, kept in a file of this profile");
-    annotate(rules.command("show"), { effects: LOCAL_READ })
+    annotate(rules.command("show"), { output: { entity: "chat_rules" }, effects: LOCAL_READ })
         .description("the group's rules; the defaults, marked not saved, if it has none yet")
         .argument("<chat>", messenger.chatArgument)
         .action(async function (chat) {
         const context = messengerContext(this, messenger);
         renderItem(this, context, await context.withServices((services) => services.moderation.rules(chat)));
     });
-    rules.addCommand(grantsAuthority(annotate(new Command("set"), { effects: LOCAL_WRITE }))
+    rules.addCommand(grantsAuthority(annotate(new Command("set"), { output: { entity: "chat_rules" }, effects: LOCAL_WRITE }))
         .description("change one rule; the group's first change writes every rule with its default")
         .argument("<chat>", messenger.chatArgument)
         .argument("<key>", `one of: ${RULE_KEYS.join(", ")}`)
@@ -28,7 +28,7 @@ export const rulesCommand = (messenger) => {
         const context = messengerContext(this, messenger);
         renderItem(this, context, await context.withServices((services) => services.moderation.set(chat, key, value)));
     }));
-    rules.addCommand(grantsAuthority(annotate(new Command("unset"), { effects: LOCAL_WRITE }))
+    rules.addCommand(grantsAuthority(annotate(new Command("unset"), { output: { entity: "chat_rules" }, effects: LOCAL_WRITE }))
         .description("put one rule back to its default")
         .argument("<chat>", messenger.chatArgument)
         .argument("<key>", `one of: ${RULE_KEYS.join(", ")}`)
@@ -43,7 +43,7 @@ export const rulesCommand = (messenger) => {
  * for what the rules name, within each action's level in the group's rules. Nothing watches groups
  * in the background.
  */
-export const moderateCommand = (messenger) => annotate(new Command("moderate"), { effects: REMOTE_WRITE })
+export const moderateCommand = (messenger) => annotate(new Command("moderate"), { output: { entity: "chat_moderation" }, effects: REMOTE_WRITE })
     .description("judge a group's new messages and members by its rules, and act as they allow")
     .argument("<chat>", messenger.chatArgument)
     .option("--since-time <time>", "judge what came after this ISO 8601 time, or 2h / 1d ago; the saved point stays")

package/dist/cli/messenger/admin-statistics-command.js

@@ -5,6 +5,7 @@ import { REMOTE_READ } from "../effects.js";
 import { renderAnswer } from "../envelope.js";
 import { positiveCount } from "../paging.js";
 import { messengerContext } from "./context.js";
+import { statisticsQuery, withStatisticsQuery } from "./statistics-query.js";
 import { adminAnswer, refuseJsonl } from "./stats-answers.js";
 const collect = (value, previous = []) => [...previous, value];
 export const adminStatisticsCommand = (messenger, report) => {
@@ -27,22 +28,17 @@ export const adminStatisticsCommand = (messenger, report) => {
     else
         command
             .argument("[query...]", "a strict Lucene query; none selects every stored message")
-            .option("--chat <chat>", `only this chat; ${messenger.chatArgument}`)
-            .option("--source <accounts>", "every held account of this messenger; personal, bots or all")
-            .option("--exact", "bare words match exact forms rather than stems");
+            .option("--source <accounts>", "every held account of this messenger; personal, bots or all");
     command.option("--saved <name|id>", "run a saved report of this kind; typed report options replace stored options");
     command
         .option("--timezone <zone>", "the IANA timezone for calendar date boundaries")
         .option("--limit <n>", "report rows, 1–100; 20 if not given", positiveCount("--limit"));
     if (report !== "discussion")
         command.option("--answerer <person>", "stored name, alias, @username, ID or person:provider/account/id; ambiguous names require a choice; repeat for more", collect);
-    if (report === "unanswered")
-        command.option("--older-than <duration>", "minimum age of a question without an observed qualifying answer");
-    if (report === "discussion")
-        command
-            .option("--min-views <n>", "minimum known cumulative views", Number)
-            .option("--max-replies <n>", "maximum observed discussion replies", Number);
+    if (report !== "newcomers")
+        withStatisticsQuery(command, report);
     command.action(async function (argument) {
+        const filters = report === "newcomers" ? {} : statisticsQuery(argument, report);
         const context = messengerContext(this, messenger);
         refuseJsonl(context.format);
         const { answerer, ...options } = this.opts();
@@ -50,11 +46,7 @@ export const adminStatisticsCommand = (messenger, report) => {
             ...options,
             limit: options.limit ?? 20,
             ...(answerer ? { answerers: answerer } : {}),
-            ...(report === "newcomers"
-                ? { chat: argument }
-                : argument.length
-                    ? { text: argument.join(" ") }
-                    : {}),
+            ...(report === "newcomers" ? { chat: argument } : filters),
             signal: environmentOf(this).commandSignal ?? environmentOf(this).signal,
         }));
         renderAnswer(this, context, adminAnswer(found));

package/dist/cli/messenger/analysis-consents-query.d.ts

@@ -0,0 +1,5 @@
+import { type QueryRegistry } from "@wirecat/cli-base/query";
+import type { AnalysisConsentFilter } from "../../analysis/consents.js";
+import { type QueryWords } from "../list-query.js";
+export declare const ANALYSIS_CONSENTS_QUERY: QueryRegistry;
+export declare const analysisConsentFilter: (words: QueryWords) => AnalysisConsentFilter | undefined;

package/dist/cli/messenger/analysis-consents-query.js

@@ -0,0 +1,20 @@
+import { queryFieldsOf } from "@wirecat/cli-base/query";
+import { analysisConsent } from "../../entities/index.js";
+import { queryTerms } from "../list-query.js";
+export const ANALYSIS_CONSENTS_QUERY = {
+    entity: "analysis_consent",
+    backend: "native",
+    fields: queryFieldsOf(analysisConsent, {
+        native: ["chat", "provider"],
+        examples: { chat: "chat:7", provider: 'provider:"openai:https://example.test/v1"' },
+    }).map((field) => field.native
+        ? { ...field, operators: field.operators.filter((operator) => operator === "term" || operator === "phrase") }
+        : field),
+};
+export const analysisConsentFilter = (words) => {
+    const terms = queryTerms(words, ANALYSIS_CONSENTS_QUERY, "conversations consents list");
+    if (terms.size === 0)
+        return undefined;
+    const chat = terms.get("chat"), provider = terms.get("provider");
+    return { ...(chat === undefined ? {} : { chat }), ...(provider === undefined ? {} : { provider }) };
+};

package/dist/cli/messenger/archive-commands.js

@@ -64,7 +64,7 @@ export const storeCommand = (messenger) => {
  * What the local store holds, per chat — read from the store alone. Whether a fetch reached a
  * chat's very first message is not recorded, so it is not claimed: the stretches held are shown.
  */
-const statusCommand = (messenger) => annotate(new Command("status"), { effects: LOCAL_READ })
+const statusCommand = (messenger) => annotate(new Command("status"), { output: { entity: "store_chat_status" }, effects: LOCAL_READ })
     .summary("what the local archive holds and what is missing")
     .description("per chat: messages stored, the oldest and newest, and the stretches held completely")
     .argument("[chat]", messenger.chatArgument)
@@ -93,7 +93,7 @@ const leftLines = (left) => {
  * store is not offered. The refusal names the chats to a person but keeps them out of its message,
  * which a scheduled run's `last.json` keeps.
  */
-const clearCommand = (messenger) => annotate(new Command("clear"), { effects: LOCAL_WRITE, mcp: false })
+const clearCommand = (messenger) => annotate(new Command("clear"), { output: { entity: "store_clear" }, effects: LOCAL_WRITE })
     .description("delete from the store the chats this account has left, with their messages")
     .option("--left", "the chats this account has left — the only thing this clears")
     .option("--allow-dangerous", "yes, delete — it cannot be undone, and a chat you left cannot be fetched again")
@@ -132,7 +132,7 @@ const clearCommand = (messenger) => annotate(new Command("clear"), { effects: LO
  * `--format markdown` for a transcript a person reads. With `--output-dir`, any number of chats into a
  * folder, and each later run into the same folder adds only what changed.
  */
-const exportCommand = (messenger) => destroysNothing(annotate(new Command("export"), { effects: LOCAL_WRITE }))
+const exportCommand = (messenger) => destroysNothing(annotate(new Command("export"), { output: { entity: "store_export" }, effects: LOCAL_WRITE }))
     .summary("export stored messages to files")
     .description("a chat's stored messages, oldest first: --jsonl one message per line, --json the list envelope of messages; never asks the messenger")
     .argument("[chat...]", `${messenger.chatArgument}; several with --output-dir`)

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

@@ -36,6 +36,7 @@ const summary = (run) => [
     .filter(Boolean)
     .join(", ");
 const extractCommand = (messenger) => annotate(new Command("extract"), {
+    output: { entity: "attachment_extraction" },
     effects: FETCH,
     examples: [`${messenger.app.command} personal attachments extract --chat "Book club" --limit 10`],
 })
@@ -138,6 +139,7 @@ const listCommand = (messenger) => withQuery(withPaging(annotate(new Command("li
     renderAnswer(this, context, pagedList("attachments list", context.settings, found), () => found.items.length === 0 ? "" : `${found.items.map(row).join("\n")}\n`);
 });
 const showCommand = (messenger) => annotate(new Command("show"), {
+    output: { entity: "attachment_bytes" },
     effects: REMOTE_READ,
     examples: [`${messenger.app.command} personal attachments show "Book club" 101 --attachment 1`],
 })
@@ -173,6 +175,7 @@ const showCommand = (messenger) => annotate(new Command("show"), {
 const textCommand = (messenger) => {
     const text = new Command("text").description("the text of one file, as an agent read it");
     readsStdin(annotate(text.command("set"), {
+        output: { entity: "attachment_text_change" },
         effects: LOCAL_WRITE,
         examples: [`${messenger.app.command} personal attachments text set "Book club" 101 --text-file ./transcript.txt`],
     }), {

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

@@ -35,6 +35,7 @@ const ALL_CHATS = "--all";
 export const syncCommand = (messenger) => {
     const fetching = messenger.fetching ?? FETCHING;
     return annotate(new Command("sync"), {
+        output: { entity: "message_sync" },
         examples: [`${messenger.app.command} personal messages sync "Book club" --last 100`],
         effects: FETCH,
         cooperative: true,
@@ -224,7 +225,7 @@ export const jobsCommand = (messenger) => {
         if (jobs.length === 0 && context.format === "pretty")
             context.renderer.note(`no ${query ? "matching " : ""}background sync jobs for this profile`);
     });
-    annotate(command.command("show"), { effects: LOCAL_READ })
+    annotate(command.command("show"), { output: { entity: "store_job_details" }, effects: LOCAL_READ })
         .summary("one archive job's status and log")
         .description("one background job — the newest when none is named — and what the store now holds of its chat")
         .argument("[job]", "the job id `messages sync --background` printed")
@@ -237,7 +238,7 @@ export const jobsCommand = (messenger) => {
             : await context.withServices((services) => services.archive.held(chatId)).catch(() => undefined);
         renderAnswer(this, context, itemOf(snakeKeys({ ...jobDetails(job), ...(held ? { held } : {}), log: job.log })));
     });
-    destroysNothing(annotate(command.command("cancel"), { effects: LOCAL_WRITE }))
+    destroysNothing(annotate(command.command("cancel"), { output: { entity: "store_job_cancel" }, effects: LOCAL_WRITE }))
         .summary("cancel a queued or running archive job")
         .description("stop a running background job after its current page; a later sync resumes where it stopped")
         .argument("<job>", "the job id")
@@ -251,7 +252,7 @@ export const jobsCommand = (messenger) => {
         process.kill(job.pid, "SIGTERM");
         renderAnswer(this, context, itemOf({ job: job.id, cancelled: true }));
     });
-    destroysNothing(annotate(command.command("retry"), { effects: LOCAL_WRITE }))
+    destroysNothing(annotate(command.command("retry"), { output: { entity: "store_job_retry" }, effects: LOCAL_WRITE }))
         .summary("retry an archive job")
         .description("start a partial, failed or died job again, as a new job; the sync resumes where the store stopped")
         .argument("[job]", "the job id")
@@ -292,7 +293,7 @@ export const jobsCommand = (messenger) => {
         if (items.length === 0 && context.format === "pretty")
             context.renderer.note("no partial, failed or died jobs to retry");
     });
-    destroysNothing(annotate(command.command("clear"), { effects: LOCAL_WRITE }))
+    destroysNothing(annotate(command.command("clear"), { output: { entity: "store_job_clear" }, effects: LOCAL_WRITE }))
         .description("forget finished jobs and remove their logs; a running job is kept")
         .action(function () {
         const context = messengerContext(this, messenger);

package/dist/cli/messenger/chat-queries.d.ts

@@ -4,6 +4,7 @@ import { type QueryRegistry } from "@wirecat/cli-base/query";
  * there; `--offline`, or a messenger whose history is the store, answers them.
  */
 export declare const CHATS_QUERY: QueryRegistry;
+export declare const TRACKING_QUERY: QueryRegistry;
 /** The messenger reads a chat's events back to a time; it cannot pick them by type. */
 export declare const EVENTS_QUERY: QueryRegistry;
 /** The store's member history is read back to a time. */

package/dist/cli/messenger/chat-queries.js

@@ -1,8 +1,8 @@
 import { CliError } from "@wirecat/cli-base";
 import { queryError, queryFieldsOf } from "@wirecat/cli-base/query";
-import { chat, chatEvent, inviteLink, joinRequest, member } from "../../entities/index.js";
+import { chat, chatEvent, ENTITIES, inviteLink, joinRequest, member } from "../../entities/index.js";
 import { AUDIT_MIN_SCORE } from "../../services/members-audit.js";
-import { CHAT_COLUMNS, titlePart } from "../../store/store.js";
+import { CHAT_COLUMNS, TRACKED_CHAT_COLUMNS, titlePart } from "../../store/store.js";
 import { unfilteredQuery } from "../list-query.js";
 const titleWords = (node) => {
     const part = titlePart(node.value);
@@ -25,6 +25,16 @@ export const CHATS_QUERY = {
         validate: { title: titleWords },
     }),
 };
+export const TRACKING_QUERY = {
+    entity: "tracked_chat",
+    backend: "sql",
+    fields: queryFieldsOf(ENTITIES.tracked_chat, {
+        exclude: Object.keys(ENTITIES.tracked_chat.entries).filter((name) => !(name in TRACKED_CHAT_COLUMNS)),
+        text: ["title"],
+        examples: { chat_id: "chat_id:7", title: "title:book" },
+        validate: { title: titleWords },
+    }),
+};
 /** The messenger reads a chat's events back to a time; it cannot pick them by type. */
 export const EVENTS_QUERY = {
     entity: "chat_event",

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

@@ -48,7 +48,7 @@ export const chatsCommand = (messenger) => {
         if (body.meta?.truncated)
             context.renderer.note("more history than one run reads; a later time bound reads less");
     }));
-    annotate(chats.command("inspect"), { effects: REMOTE_READ, offline: false })
+    annotate(chats.command("inspect"), { output: { entity: "chat_inspection" }, effects: REMOTE_READ, offline: false })
         .description("what an invite or public link leads to, without joining it")
         .argument("<link>", "an invite link or a public one")
         .action(async function (link) {
@@ -69,7 +69,7 @@ export const chatsCommand = (messenger) => {
             context.renderer.note(`you left this chat; its stored messages are kept — \`${typedCommand(messenger.app.command, "store clear --left --dry-run", context.settings.profile)}\` lists the chats you left and deletes nothing`);
     }));
     if (messenger.sendAs !== false)
-        annotate(chats.command("send-as"), { effects: REMOTE_READ, offline: false })
+        annotate(chats.command("send-as"), { output: { entity: "chat_sender" }, effects: REMOTE_READ, offline: false })
             .description("who this account may post as in a chat; changes no saved choice")
             .argument("<chat>", messenger.chatArgument)
             .action(async function (chat) {

package/dist/cli/messenger/chats-documents-command.js

@@ -2,26 +2,28 @@ import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { REMOTE_READ } from "../effects.js";
 import { listOf, renderAnswer } from "../envelope.js";
+import { queryTerms, typedQuery, withQuery } from "../list-query.js";
 import { positiveCount, window } from "../paging.js";
 import { nextStep } from "../steps.js";
 import { documentLinkAnswer, lines, pageOf } from "./chat-answers.js";
 import { messengerContext } from "./context.js";
+import { DOCUMENT_LINKS_QUERY } from "./document-links-query.js";
 import { syncsFirst } from "./search-sync-options.js";
 /** `chats documents …`: the Google documents linked in a chat's stored messages. */
 export const documentsCommand = (messenger) => {
     const documents = new Command("documents").description("the Google Docs and Drive documents linked in a chat's stored messages");
-    documents.addCommand(annotate(new Command("list"), { effects: REMOTE_READ })
+    documents.addCommand(withQuery(annotate(new Command("list"), { effects: REMOTE_READ })
         .description("every document link in the chat, newest first, and whether the store has it")
         .argument("<chat>", messenger.chatArgument)
         .option("--limit <n>", "how many to show", positiveCount("--limit"))
-        .option("--page <n>", "which page, starting at 1", positiveCount("--page"))
-        .action(async function (chat) {
+        .option("--page <n>", "which page, starting at 1", positiveCount("--page")), DOCUMENT_LINKS_QUERY).action(async function (chat, words) {
+        const ref = queryTerms(words, DOCUMENT_LINKS_QUERY, "chats documents list").get("ref");
         const context = messengerContext(this, messenger);
-        const found = await context.withServices((services) => services.chatDocuments.list(chat, window(context.settings)));
+        const found = await context.withServices((services) => services.chatDocuments.list(chat, { ...window(context.settings), ...(ref === undefined ? {} : { ref }) }));
         renderAnswer(this, context, listOf("chats documents list", {
             items: found.items.map(documentLinkAnswer),
             ...pageOf(context.settings, found),
-            args: { chat },
+            args: { chat, ...(words.length ? { query: typedQuery(words) } : {}) },
             ...(found.empty && syncsFirst(messenger)
                 ? { next: [nextStep("messages.sync", { args: { chat: found.chatId } })] }
                 : {}),

package/dist/cli/messenger/chats-members-command.js

@@ -71,7 +71,11 @@ export const membersCommand = (messenger) => {
             before ? [before.name, before.username ? `@${before.username}` : null].filter(Boolean).join(" ") : "",
         ].join("  ")));
     }));
-    const fetch = annotate(new Command("fetch"), { effects: FETCH, offline: false })
+    const fetch = annotate(new Command("fetch"), {
+        output: { entity: "chat_members_fetch" },
+        effects: FETCH,
+        offline: false,
+    })
         .summary("save the group's current membership")
         .description("read a group's whole member list into the local store's member history: who joined, who left, daily " +
         "counts and profile changes; someone is recorded as gone only when every member was read")
@@ -96,7 +100,7 @@ export const membersCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(fetched)), () => `${fetched.read} members read; ${fetched.joined.length} new, ${fetched.gone.length} gone, ` +
             `${fetched.changed.length} changed their profile${fetched.tracked ? "; tracked daily" : ""}\n`);
     }));
-    const add = annotate(new Command("add"), { effects: REMOTE_WRITE })
+    const add = annotate(new Command("add"), { output: { entity: "chat_members_change" }, effects: REMOTE_WRITE })
         .description("add people; they are told")
         .argument("<chat>", messenger.chatArgument)
         .argument("<person...>", "an id, or part of a name");
@@ -109,7 +113,7 @@ export const membersCommand = (messenger) => {
         const added = await context.withServices((services) => services.admin.addMembers(chat, people, history ? { history } : {}));
         renderAnswer(this, context, itemOf(snakeKeys(added)));
     }));
-    members.addCommand(annotate(new Command("remove"), { effects: REMOTE_WRITE })
+    members.addCommand(annotate(new Command("remove"), { output: { entity: "chat_members_change" }, effects: REMOTE_WRITE })
         .description("remove people; their messages stay")
         .argument("<chat>", messenger.chatArgument)
         .argument("<person...>", "an id, or part of a name")

package/dist/cli/messenger/chats-read-command.js

@@ -4,7 +4,7 @@ import { REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { messengerContext } from "./context.js";
 export const markReadCommand = (messenger) => {
-    const read = annotate(new Command("mark-read"), { effects: REMOTE_WRITE })
+    const read = annotate(new Command("mark-read"), { output: { entity: "chat_read" }, effects: REMOTE_WRITE })
         .description("mark a chat read; the other side sees that you read it")
         .argument("<chat>", messenger.chatArgument)
         .option("--until-id <id>", "only up to this message id; the newest by default");

package/dist/cli/messenger/chats-tracking-command.js

@@ -3,19 +3,27 @@ import { Command } from "commander";
 import { TRACKED_DAYS } from "../../services/chats.js";
 import { LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { listQuery, typedQuery, withQuery } from "../list-query.js";
 import { lines, wholeList } from "./chat-answers.js";
+import { TRACKING_QUERY } from "./chat-queries.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
 /** The chats whose member lists `serve` fetches daily; kept in the local store, never sent. */
 export const trackingCommand = (messenger) => {
     const tracking = new Command("tracking")
         .summary("chats whose member lists are fetched daily")
         .description("the chats whose member lists serve fetches daily into the local store — chats members fetch --track adds one");
-    annotate(tracking.command("list"), { effects: LOCAL_READ })
+    withQuery(annotate(tracking.command("list"), { effects: LOCAL_READ }), TRACKING_QUERY)
         .description("every tracked chat: since when, and its last member count")
-        .action(async function () {
+        .action(async function (words) {
+        const query = listQuery(typedQuery(words), TRACKING_QUERY, "chats tracking list");
         const context = messengerContext(this, messenger);
-        const found = await context.withServices((services) => services.chats.tracked());
-        renderAnswer(this, context, wholeList("chats tracking list", found.map((one) => snakeKeys(one))), lines(({ chat_id, title, tracked_at, last_count }) => [
+        const found = await context.withServices((services) => services.chats.tracked(query));
+        renderAnswer(this, context, wholeList("chats tracking list", found.map(({ chatId, title, trackedAt, lastCount }) => ({
+            chat_id: chatId,
+            title,
+            tracked_at: trackedAt,
+            last_count: lastCount,
+        }))), lines(({ chat_id, title, tracked_at, last_count }) => [
             title ? `${title} (${chat_id})` : chat_id,
             tracked_at.slice(0, 10),
             last_count
@@ -23,7 +31,7 @@ export const trackingCommand = (messenger) => {
                 : "",
         ].join("  ")));
     });
-    annotate(tracking.command("show"), { effects: LOCAL_READ })
+    annotate(tracking.command("show"), { effects: LOCAL_READ, output: { entity: "tracked_chat_history" } })
         .summary("one chat's member tracking and daily counts")
         .description(`one chat: whether it is tracked, and its member count per day for the last ${TRACKED_DAYS} days`)
         .argument("<chat>", messenger.chatArgument)
@@ -35,7 +43,7 @@ export const trackingCommand = (messenger) => {
         ["add", true, "fetch this chat's member list daily while serve runs, from its next run"],
         ["remove", false, "stop fetching it daily; the history already kept stays"],
     ]) {
-        annotate(tracking.command(verb), { effects: LOCAL_WRITE })
+        annotate(tracking.command(verb), { effects: LOCAL_WRITE, output: { entity: "chat_tracking" } })
             .description(description)
             .argument("<chat>", messenger.chatArgument)
             .action(async function (chat) {