@wirecat/cli-core 0.398.0 → 0.400.0

package/dist/cli/messenger/statistics-query.js

@@ -0,0 +1,143 @@
+import { annotate } from "@wirecat/cli-base/commands";
+import { defineQuery, fieldsHelp, parseLucene, queryError, validateQuery, walkQuery, } from "@wirecat/cli-base/query";
+import { QUERY_FIELDS } from "../../search/lucene/registry.js";
+import { MESSAGE_PARSING } from "../../search/lucene/types.js";
+import { LIST_QUERY_GUIDE, typedQuery } from "../list-query.js";
+const FIELDS = {
+    "contacts-top": ["message_kind", "min_messages"],
+    "messages-top": ["message_kind"],
+    discussion: ["min_views", "max_replies"],
+    unanswered: ["older_than"],
+    responses: [],
+};
+const PATHS = {
+    "contacts-top": "stats contacts top",
+    "messages-top": "stats messages top",
+    discussion: "stats messages discussion",
+    unanswered: "stats messages unanswered",
+    responses: "stats contacts responses",
+};
+const FIELD_SPECS = [
+    {
+        name: "message_kind",
+        type: "enum",
+        values: ["all", "posts", "comments"],
+        operators: ["term", "phrase"],
+        example: "message_kind:posts",
+        placement: "and",
+        relation: "proven posts or comments selected before ranking",
+    },
+    {
+        name: "min_messages",
+        type: "num",
+        operators: ["term"],
+        example: "min_messages:5",
+        placement: "and",
+        relation: "minimum selected messages per ranked author",
+    },
+    {
+        name: "min_views",
+        type: "num",
+        operators: ["term"],
+        example: "min_views:10",
+        placement: "and",
+        relation: "minimum known cumulative views of a discussion post",
+    },
+    {
+        name: "max_replies",
+        type: "num",
+        operators: ["term"],
+        example: "max_replies:0",
+        placement: "and",
+        relation: "maximum observed discussion replies",
+    },
+    {
+        name: "older_than",
+        type: "kw",
+        operators: ["term", "phrase"],
+        example: "older_than:24h",
+        placement: "and",
+        relation: "minimum age of an unanswered question; positive duration",
+    },
+];
+const fieldsFor = (report) => FIELD_SPECS.filter(({ name }) => FIELDS[report].includes(name));
+export const withStatisticsQuery = (command, report) => {
+    const extra = fieldsFor(report);
+    const query = defineQuery({
+        entity: report.endsWith("top") ? "ranking" : "admin_report",
+        backend: "sql",
+        fields: [
+            ...QUERY_FIELDS.map((field) => ({
+                ...field,
+                example: field.name === "text" ? "text:invoice" : field.name === "topic" ? "topic:42" : field.example,
+            })),
+            ...extra,
+        ],
+    });
+    annotate(command, { query });
+    command.addHelpText("after", `\n${fieldsHelp({ fields: extra }, LIST_QUERY_GUIDE)}\nReport predicates are positive AND terms; the remaining query selects stored messages.\n`);
+    return command;
+};
+export const statisticsQuery = (words, report) => {
+    const source = typedQuery(words);
+    if (!source.trim())
+        return {};
+    const ast = parseLucene(source, MESSAGE_PARSING);
+    const reserved = new Set(FIELD_SPECS.map(({ name }) => name));
+    const hasReport = (node) => walkQuery(node).some(({ field }) => reserved.has(field));
+    if (!hasReport(ast.root))
+        return { text: source };
+    const context = { command: PATHS[report], guide: LIST_QUERY_GUIDE };
+    const values = new Map();
+    const original = (node) => {
+        const piece = source.slice(node.span.start, node.span.end);
+        if (node.kind === "boolean") {
+            const prefix = /(?:^|[\s(])([a-z_][a-z0-9_-]*)\s*:\s*$/i.exec(source.slice(0, node.span.start));
+            return prefix ? `${prefix[1]}:${piece}` : piece;
+        }
+        const named = /^([a-z_][a-z0-9_-]*)\s*[:<>]/i.exec(piece)?.[1];
+        return node.implicit || named?.toLowerCase() === node.field.toLowerCase() ? piece : `${node.field}:${piece}`;
+    };
+    const prune = (node) => {
+        if (!hasReport(node))
+            return original(node);
+        if (node.kind === "boolean") {
+            if (node.clauses.some(({ occur, node: child }) => occur === "should" || (occur === "must_not" && hasReport(child))))
+                queryError("query.unsupported-placement", node.span, "report predicates must be positive AND terms", context);
+            const kept = node.clauses
+                .map(({ occur, node: child }) => {
+                const part = prune(child);
+                return part === undefined ? undefined : occur === "must_not" ? `NOT (${part})` : part;
+            })
+                .filter((part) => part !== undefined);
+            return kept.length ? kept.map((part) => `(${part})`).join(" AND ") : undefined;
+        }
+        if (!FIELDS[report].includes(node.field))
+            queryError("query.unsupported-field", node.span, `${node.field} is not a filter for ${PATHS[report]}`, context);
+        validateQuery({ ...ast, root: node }, { entity: "statistics", backend: "sql", fields: fieldsFor(report) }, context);
+        if (values.has(node.field))
+            queryError("query.unsupported-placement", node.span, `${node.field} only once here`, context);
+        if (["min_messages", "min_views", "max_replies"].includes(node.field)) {
+            const value = Number(node.value);
+            if (!Number.isSafeInteger(value) || value < (node.field === "min_messages" ? 1 : 0))
+                queryError("query.invalid-number", node.span, `${node.field} takes a ${node.field === "min_messages" ? "positive" : "nonnegative"} integer`, context);
+        }
+        if (node.field === "older_than") {
+            const units = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+            const duration = Number(node.value.slice(0, -1)) * (units[node.value.at(-1) ?? ""] ?? 0);
+            if (!/^\d+(?:\.\d+)?[smhdw]$/.test(node.value) || !Number.isSafeInteger(duration) || duration <= 0)
+                queryError("query.invalid-duration", node.span, "older_than takes a positive duration such as 4h or 7d", context);
+        }
+        values.set(node.field, node.value);
+        return undefined;
+    };
+    const text = prune(ast.root);
+    return {
+        ...(text ? { text } : {}),
+        ...(values.has("message_kind") ? { messageKind: values.get("message_kind")?.toLowerCase() } : {}),
+        ...(values.has("min_messages") ? { minMessages: Number(values.get("min_messages")) } : {}),
+        ...(values.has("min_views") ? { minViews: Number(values.get("min_views")) } : {}),
+        ...(values.has("max_replies") ? { maxReplies: Number(values.get("max_replies")) } : {}),
+        ...(values.has("older_than") ? { olderThan: values.get("older_than") } : {}),
+    };
+};

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

@@ -49,7 +49,7 @@ export const statsCommand = (messenger, loadRenderer = chartRenderer) => {
         .description("a chart's data from a chat's statistics, and optionally a dark SVG or PNG image")
         .argument("<chat>", messenger.chatArgument)
         .option("--chart-kind <messages|active|membership>", "what to draw: messages, active authors, or joins and leaves", chartKindOf, "messages")
-        .option("--by <day|week>", "one point per calendar day or week (weeks start on Monday)", chartPeriodOf, "day")
+        .option("--by <group>", "one point per calendar day or week (weeks start on Monday)", chartPeriodOf, "day")
         .option("--since-time <time>", `ISO 8601, or 2h / 1d ago; ${EVENTS_DAYS} days ago if not given`)
         .option("--timezone <zone>", "the IANA timezone for calendar days")
         .option("--output <file>", "write a dark image to a new .svg or .png file")
@@ -91,15 +91,15 @@ export const statsCommand = (messenger, loadRenderer = chartRenderer) => {
         "chats retention": '"Book club"',
         "chats show": '"Book club"',
         "contacts evidence": '101 --selection "$selection" --component messages',
-        "contacts responses": '--chat "Project room"',
-        "contacts top": '--chat "Book club" --limit 10',
+        "contacts responses": 'chat:"Project room"',
+        "contacts top": 'chat:"Book club" --limit 10',
         "messages counters refresh": '--chat "Book club" --dry-run',
         "messages counters show": '--chat "Book club" --limit 10',
-        "messages discussion": '--chat "Book club"',
+        "messages discussion": 'chat:"Book club"',
         "messages evidence": '"$message" --selection "$selection" --component reactions',
         "messages show": '--chat "Book club" --by day',
-        "messages top": '--chat "Book club" --limit 10',
-        "messages unanswered": '--chat "Project room"',
+        "messages top": 'chat:"Book club" --limit 10',
+        "messages unanswered": 'chat:"Project room"',
         "tasks show": '--chat "Project room"',
     };
     for (const [path, args] of Object.entries(examples)) {

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

@@ -92,7 +92,7 @@ const refuseWhileServing = (command, messenger) => {
         throw new CliError("validation_error", `${messenger.app.command} serve is running for ${serving.join(", ")} — ${serving.map((profile) => `\`${messenger.app.command} ${profile} server stop\``).join(", ")} first`);
     }
 };
-const repairCommand = (messenger) => annotate(new Command("repair"), { effects: LOCAL_WRITE, mcp: false })
+const repairCommand = (messenger) => annotate(new Command("repair"), { output: { entity: "store_repair" }, effects: LOCAL_WRITE, mcp: false })
     .summary("repair table shapes while keeping the old tables")
     .description("bring every table to this build's shape, deleting nothing: a table of the wrong shape is kept as a copy beside a new one")
     .option("--dry-run", "say what it would do, and change nothing")
@@ -142,7 +142,7 @@ const notesOf = (report, command) => {
     }
     return notes;
 };
-const copiesCommand = () => new Command("copies").description("the tables `store repair` kept as copies").addCommand(annotate(new Command("delete"), { effects: LOCAL_WRITE, mcp: false })
+const copiesCommand = () => new Command("copies").description("the tables `store repair` kept as copies").addCommand(annotate(new Command("delete"), { output: { entity: "store_copy_removal" }, effects: LOCAL_WRITE, mcp: false })
     .description("delete one copy `store repair` kept, named exactly; refuses any other table")
     .argument("<name>", "the copy's name, as `store repair` printed it")
     .action(async function (name) {
@@ -152,7 +152,7 @@ const copiesCommand = () => new Command("copies").description("the tables `store
     const deleted = await reading(path, (database) => deleteCopy(database, name));
     result(this, { path, deleted });
 }));
-const infoCommand = () => annotate(new Command("info"), { effects: LOCAL_READ })
+const infoCommand = () => annotate(new Command("info"), { output: { entity: "store_info" }, effects: LOCAL_READ })
     .summary("the local archive's format, size and contents")
     .description("the store file: where it is, its size, its schema and how many rows it holds; changes nothing")
     .action(async function () {
@@ -182,7 +182,7 @@ const infoCommand = () => annotate(new Command("info"), { effects: LOCAL_READ })
  * fetched" (NEED-399 A). Times are the chat's newest message by the messenger's list against the
  * newest message held, not `sync_ranges`: those are in message ids, which a chat list does not give.
  */
-const checkCommand = (messenger) => annotate(new Command("check"), { effects: LOCAL_READ })
+const checkCommand = (messenger) => annotate(new Command("check"), { output: { entity: "store_check" }, effects: LOCAL_READ })
     .summary("check the local archive for problems")
     .description("whether the store is healthy — integrity, search indexes, disk, and which chats are behind")
     .action(async function () {
@@ -362,7 +362,7 @@ const chatsBehind = (database) => database
     held: row.held === null ? null : isoOf(row.held),
     refreshed: isoOf(row.refreshed),
 }));
-const migrateCommand = (messenger) => annotate(new Command("migrate"), { effects: LOCAL_WRITE, mcp: false })
+const migrateCommand = (messenger) => annotate(new Command("migrate"), { output: { entity: "store_migration" }, effects: LOCAL_WRITE, mcp: false })
     .summary("migrate an older local archive")
     .description("bring the store up to this build's schema, then normalize, index and stem the messages and notes stored before it")
     .action(async function () {
@@ -431,7 +431,7 @@ const buildNoteIndex = (database, note, { reset = false } = {}) => {
         note(`indexing ${pending} notes`);
     return { notesIndexed: drainNoteIndex(database, stemmerCache()) };
 };
-const reindexCommand = (messenger) => destroysNothing(annotate(new Command("reindex"), { effects: LOCAL_WRITE }))
+const reindexCommand = (messenger) => destroysNothing(annotate(new Command("reindex"), { output: { entity: "store_reindex" }, effects: LOCAL_WRITE }))
     .summary("rebuild the local archive's search indexes")
     .description("rebuild the word index, its typo vocabulary, the stems, the files' word index, the notes' indexes and who took part in what, from what is stored; loses nothing")
     .action(async function () {
@@ -478,7 +478,7 @@ const vacuumInto = async (path, target) => {
     }
 };
 const stampNow = () => new Date().toISOString().replace(/[:.]/g, "-");
-const backupCommand = () => destroysNothing(annotate(new Command("backup"), { effects: LOCAL_WRITE, mcp: false }))
+const backupCommand = () => destroysNothing(annotate(new Command("backup"), { output: { entity: "store_backup" }, effects: LOCAL_WRITE, mcp: false }))
     .description("copy the store into a new file, while it is in use; never overwrites a file")
     .argument("<file>", "the new file")
     .option(...ENCRYPT_OPTION)
@@ -522,7 +522,7 @@ const backupCommand = () => destroysNothing(annotate(new Command("backup"), { ef
     }
 });
 /** The only way back into a sealed file: the format is this tool's own. */
-const decryptCommand = () => annotate(new Command("decrypt"), { effects: LOCAL_WRITE, mcp: false })
+const decryptCommand = () => annotate(new Command("decrypt"), { output: { entity: "store_decrypt" }, effects: LOCAL_WRITE, mcp: false })
     .description("open a file written with --encrypt into a new file; asks for its password")
     .argument("<file>", "a file `store backup --encrypt` or `store export --encrypt` wrote")
     .requiredOption("--output <file>", "the new file, readable only by you")
@@ -544,7 +544,7 @@ const decryptCommand = () => annotate(new Command("decrypt"), { effects: LOCAL_W
  * process has the file open — it would go on writing to the file set aside — or while this CLI's
  * `serve` runs: that opens the store on its first write, so until then it holds nothing to see.
  */
-const restoreCommand = (messenger) => annotate(new Command("restore"), { effects: LOCAL_WRITE, mcp: false })
+const restoreCommand = (messenger) => annotate(new Command("restore"), { output: { entity: "store_restore" }, effects: LOCAL_WRITE, mcp: false })
     .summary("restore a backup while keeping the current store")
     .description("put a backup in place of the store; the store it replaces is kept beside it, never deleted")
     .argument("<file>", "a file `store backup` wrote; one written with --encrypt asks for its password")
@@ -661,7 +661,7 @@ const quiesce = async (path, messenger, then, warn, waitMs = STORE_LOCK_WAIT_MS)
  * For a store this build cannot migrate: a backup beside it, then an empty store at this build's
  * schema. The backup is made before anything is deleted, and its path is said before the delete.
  */
-const resetCommand = (messenger) => annotate(new Command("reset"), { effects: LOCAL_WRITE, mcp: false })
+const resetCommand = (messenger) => annotate(new Command("reset"), { output: { entity: "store_reset" }, effects: LOCAL_WRITE, mcp: false })
     .summary("back up the local archive and replace it with an empty one")
     .description("back the store up beside itself, then delete it and start an empty one at this build's schema; asks first, or --yes")
     .option("--no-backup", "delete the store without backing it up first")

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

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { TAGGING_QUERY } from "../../services/tags.js";
 import { changesStore, FETCH, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
@@ -23,7 +23,7 @@ const describe = ({ type, chatId, personId, messageId, taskId }) => type === "ch
 const line = (one) => `${one.tag}  ${one.type}  ${one.name ?? ""} (${one.target})`;
 const sourceOf = (value) => {
     if (value !== "manual" && value !== "auto")
-        throw new CliError("validation_error", "--source takes manual or auto");
+        throw new CliError("validation_error", "--claim takes manual or auto");
     return value;
 };
 /** The owner's labels, in the local store only: `tag:` in a search finds what they label. */
@@ -32,10 +32,14 @@ export const tagsCommand = (messenger) => {
     const tags = new Command("tags")
         .summary("tags on stored messages and other records")
         .description("your own labels on chats, people, messages and tasks, kept in the local store and never sent; tag: in a search finds them");
-    changesStore(annotate(tags.command("auto"), { effects: FETCH, examples: [`${tool} tags auto --chat "Book club" --dry-run`] }))
+    changesStore(annotate(tags.command("auto"), {
+        output: { entity: "automatic_tags" },
+        effects: FETCH,
+        examples: [`${tool} tags auto --chat "Book club" --dry-run`],
+    }))
         .description("derive local group/channel tags from cached metadata using keyword rules")
         .option("--chat <chat>", "a stored group/channel; repeat to select several", (value, previous) => [...previous, value], [])
-        .option("--limit <number>", "process at most 1–500 chats", positiveCount("--limit"), 50)
+        .option("--limit <n>", "process at most 1–500 chats", positiveCount("--limit"), 50)
         .option("--sync-first", "read current descriptions from the messenger before classifying")
         .option("--dry-run", "preview cached classification without changing the store")
         .action(async function () {
@@ -47,6 +51,7 @@ export const tagsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(done)));
     });
     targetOptions(annotate(tags.command("add"), {
+        output: { entity: "tag_change" },
         effects: LOCAL_WRITE,
         examples: [`${tool} tags add reading --chat "Book club"`],
     }).description("put tags on one chat, person, message or task"), messenger, "tag").action(async function (given) {
@@ -59,15 +64,22 @@ export const tagsCommand = (messenger) => {
             context.renderer.note(`already there: ${done.unchanged.join(", ")}`);
     });
     targetOptions(annotate(tags.command("remove"), {
+        output: { entity: "tag_change" },
         effects: LOCAL_WRITE,
         examples: [`${tool} tags remove reading --chat "Book club"`],
     }).description("take tags off one chat, person, message or task"), messenger, "untag")
-        .option("--source <manual|auto>", "remove only this ownership claim", sourceOf)
+        .addOption(new Option("--claim <claim>", "remove only this ownership claim: manual or auto")
+        .argParser(sourceOf)
+        .conflicts("source"))
+        .addOption(new Option("--source <manual|auto>", "compatibility alias for --claim")
+        .argParser(sourceOf)
+        .hideHelp()
+        .conflicts("claim"))
         .action(async function (given) {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "tags.remove");
         const target = this.opts();
-        const done = await context.withServices((services) => services.tags.remove(target, given, this.opts().source));
+        const done = await context.withServices((services) => services.tags.remove(target, given, this.opts().claim ?? this.opts().source));
         renderAnswer(this, context, itemOf(snakeKeys(done)), () => done.removed.length ? `${describe(done.target)}: ${done.removed.join(", ")} removed\n` : "");
         if (done.unchanged.length && context.format === "pretty")
             context.renderer.note(`not there: ${done.unchanged.join(", ")}`);

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

@@ -152,6 +152,7 @@ export const tasksCommand = (messenger) => {
             context.renderer.note("no tasks — review, inbox and messages sync add them as questions arrive");
     });
     planOptions(destroysNothing(annotate(tasks.command("add"), {
+        output: { entity: "task_created" },
         effects: LOCAL_WRITE,
         examples: [`${tool} personal tasks add note:101 --type promise --category documents --title "Review draft"`],
     }))
@@ -185,6 +186,7 @@ export const tasksCommand = (messenger) => {
             context.renderer.note(`${task.key ?? task.id} follows up ${followUpOf.key} (${followUpOf.status}), which stays closed: linked follow-up-of`);
     });
     planOptions(destroysNothing(annotate(tasks.command("plan"), {
+        output: { entity: "task_card" },
         effects: LOCAL_WRITE,
         examples: [`${tool} personal tasks plan DOC-12 --title "Review draft"`],
     }))
@@ -201,6 +203,7 @@ export const tasksCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(planned)), () => `${card(planned)}\n`);
     });
     destroysNothing(annotate(tasks.command("link"), {
+        output: { entity: "task_links" },
         effects: LOCAL_WRITE,
         examples: [`${tool} personal tasks link DOC-12 https://example.com/draft`],
     }))
@@ -223,7 +226,11 @@ export const tasksCommand = (messenger) => {
         if (!("relations" in linked) && linked.review && context.format === "pretty")
             context.renderer.note(`${linked.review} possible duplicate pair(s) went to tasks duplicates`);
     });
-    annotate(tasks.command("show"), { effects: LOCAL_READ, examples: [`${tool} personal tasks show DOC-12`] })
+    annotate(tasks.command("show"), {
+        output: { entity: "task_card" },
+        effects: LOCAL_READ,
+        examples: [`${tool} personal tasks show DOC-12`],
+    })
         .description("one task: its plan and everything linked to it")
         .argument("<task>", "the task's id or key, as tasks list shows it")
         .action(async function (id) {
@@ -231,7 +238,11 @@ export const tasksCommand = (messenger) => {
         const shown = await context.withServices((services) => services.tasks.show(id));
         renderAnswer(this, context, itemOf(snakeKeys(shown)), () => `${card(shown)}\n`);
     });
-    annotate(tasks.command("related"), { effects: LOCAL_READ, examples: [`${tool} tasks related PR-12`] })
+    annotate(tasks.command("related"), {
+        output: { entity: "task_similar" },
+        effects: LOCAL_READ,
+        examples: [`${tool} tasks related PR-12`],
+    })
         .summary("tasks that may be the same job as this one, best first; merges nothing")
         .description("tasks that may be the same job as this one, best first, each with a band — likely, maybe, different — and the " +
         "reasons; merges nothing")
@@ -280,6 +291,7 @@ export const tasksCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(pair)), () => `${pair.decision}  ${pairLine(pair)}\n`);
     };
     destroysNothing(annotate(duplicates.command("reject"), {
+        output: { entity: "task_pair" },
         effects: LOCAL_WRITE,
         examples: [`${tool} tasks duplicates reject PR-14 PR-12`],
     }))
@@ -289,6 +301,7 @@ export const tasksCommand = (messenger) => {
         .argument("<other-task>", "the task it was paired with")
         .action(decided("rejected", "tasks.duplicates.reject"));
     destroysNothing(annotate(duplicates.command("defer"), {
+        output: { entity: "task_pair" },
         effects: LOCAL_WRITE,
         examples: [`${tool} tasks duplicates defer PR-14 PR-12`],
     }))
@@ -297,7 +310,11 @@ export const tasksCommand = (messenger) => {
         .argument("<task>", "the task listed as the duplicate, by its id or key")
         .argument("<other-task>", "the task it was paired with")
         .action(decided("unsure", "tasks.duplicates.defer"));
-    destroysNothing(annotate(tasks.command("merge"), { effects: LOCAL_WRITE, examples: [`${tool} tasks merge PR-14 --into PR-12`] }))
+    destroysNothing(annotate(tasks.command("merge"), {
+        output: { entity: "task_merge" },
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tasks merge PR-14 --into PR-12`],
+    }))
         .summary("one job seen twice: fold the duplicate into the task that stays")
         .description("one job seen twice: link every message of the duplicate to the task and close the duplicate dismissed, " +
         "duplicate-of the task; nothing is deleted, and tasks unmerge undoes it")
@@ -311,7 +328,11 @@ export const tasksCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(merged)), () => `${dup} merged into ${merged.task.key}; ${merged.linked} message(s) linked${toReview(merged.review)}\n` +
             `${card(merged.task)}\n`);
     });
-    destroysNothing(annotate(tasks.command("unmerge"), { effects: LOCAL_WRITE, examples: [`${tool} tasks unmerge PR-14`] }))
+    destroysNothing(annotate(tasks.command("unmerge"), {
+        output: { entity: "task_unmerge" },
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tasks unmerge PR-14`],
+    }))
         .summary("undo a merge: reopen the task and remove its duplicate-of relation")
         .description("undo a merge: reopen the task and remove its duplicate-of relation; messages the merge linked stay linked")
         .argument("<task>", "the merged task, by its id or key")
@@ -344,7 +365,11 @@ export const tasksCommand = (messenger) => {
         }));
         renderAnswer(this, context, itemOf(agendaItem(agenda)), () => `${agendaText(agenda)}\n`);
     });
-    annotate(tasks.command("categories"), { effects: LOCAL_READ, examples: [`${tool} tasks categories`] })
+    annotate(tasks.command("categories"), {
+        output: { entity: "task_categories" },
+        effects: LOCAL_READ,
+        examples: [`${tool} tasks categories`],
+    })
         .summary("the categories a task takes, with what each means")
         .description("the categories a task takes, with what each means and the words a rule picks it by")
         .action(async function () {
@@ -365,6 +390,7 @@ export const tasksCommand = (messenger) => {
         ].join("\n"));
     });
     destroysNothing(annotate(tasks.command("scan"), {
+        output: { entity: "task_scan" },
         effects: LOCAL_WRITE,
         examples: [`${tool} tasks scan <chat>`, `${tool} tasks scan <chat> --last 300 --yes`],
     }))
@@ -389,7 +415,11 @@ export const tasksCommand = (messenger) => {
         }, { name: "tasks scan" });
         renderAnswer(this, context, listOf("tasks scan", { items: passes.map(snakeKeys), limit: passes.length, has_more: false }), () => `${passes.map((pass) => applyText(pass, yes, tool)).join("\n")}\n`);
     });
-    destroysNothing(annotate(tasks.command("claim"), { effects: LOCAL_WRITE, examples: [`${tool} tasks claim PR-12 --lease 2h`] }))
+    destroysNothing(annotate(tasks.command("claim"), {
+        output: { entity: "task_card" },
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tasks claim PR-12 --lease 2h`],
+    }))
         .description("take an open task so no other agent works it at once; the claim lapses by itself")
         .argument("<task>", "the task's id or key, as tasks list shows it")
         .option("--lease <duration>", "how long the claim lasts: 30m, 2h (default 30m); claiming again extends it", durationOf("--lease"))
@@ -401,7 +431,11 @@ export const tasksCommand = (messenger) => {
         const claimed = await context.withServices((services) => services.tasks.claim(id, holderOf(this), lease));
         renderAnswer(this, context, itemOf(snakeKeys(claimed)), () => `${card(claimed)}\n`);
     });
-    destroysNothing(annotate(tasks.command("release"), { effects: LOCAL_WRITE, examples: [`${tool} tasks release PR-12`] }))
+    destroysNothing(annotate(tasks.command("release"), {
+        output: { entity: "task_card" },
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tasks release PR-12`],
+    }))
         .description("give back a task you claimed, before the claim lapses; the owner may release any")
         .argument("<task>", "the task's id or key, as tasks list shows it")
         .option("--holder <name>", HOLDER_HELP)
@@ -412,6 +446,7 @@ export const tasksCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(released)), () => `${card(released)}\n`);
     });
     destroysNothing(annotate(tasks.command("close"), {
+        output: { entity: "task_closed" },
         effects: LOCAL_WRITE,
         examples: [
             `${tool} tasks close Q-15 --as done --certainty 0.9 --reason answered-in-chat`,
@@ -452,7 +487,11 @@ export const tasksCommand = (messenger) => {
             context.renderer.note(`${closed.key ?? id} stays open: the close waits on the owner — ${tool} tasks close ${closed.key ?? id} ` +
                 `confirms it, ${tool} tasks reject ${closed.key ?? id} refuses it`);
     });
-    annotate(tasks.command("reject"), { effects: LOCAL_WRITE, examples: [`${tool} tasks reject Q-15`] })
+    annotate(tasks.command("reject"), {
+        output: { entity: "task_card" },
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tasks reject Q-15`],
+    })
         .summary("refuse an agent's close of a task: it stays open and the suggestion goes")
         .description("refuse the close an agent suggested: the task stays open and leaves close:suggested; the agent may close it again")
         .argument("<task>", "the task's id or key, as tasks list shows it")

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

@@ -9,6 +9,7 @@ import { heardAnswer } from "./message-answers.js";
 import { keepRefreshedRefs } from "./refreshed-refs.js";
 /** `messages transcribe`: a voice message as text, by the messenger or by a model on this machine. */
 export const transcribeSubcommand = (messages, messenger) => annotate(messages.command("transcribe"), {
+    output: { entity: "message_transcript" },
     examples: [`${messenger.app.command} personal messages transcribe "Book club" 101`],
     effects: REMOTE_READ,
 })
@@ -17,7 +18,7 @@ export const transcribeSubcommand = (messages, messenger) => annotate(messages.c
     .argument("<chat>", messenger.chatArgument)
     .argument("<message>", "the id of a voice message")
     .option("--local", "use the model on this machine, never the messenger")
-    .option("--model <id>", "which downloaded model; implies --local (`models audio list`)")
+    .option("--model <model>", "which downloaded model; implies --local (`models audio list`)")
     .action(async function (chat, messageId) {
     const context = messengerContext(this, messenger);
     const choice = {

package/dist/cli/messenger/watch-answers.d.ts

@@ -0,0 +1,6 @@
+import type * as v from "valibot";
+import type { MessageEvent, MessageHit } from "../../domain/models.js";
+import type { messageEvent, watchedMessage } from "../../entities/listener.js";
+import type { AccountKey } from "../../store/store.js";
+export declare const watchedMessageItem: (value: MessageHit, account: AccountKey) => v.InferOutput<typeof watchedMessage>;
+export declare const watchEventItem: (value: MessageEvent, account: AccountKey) => v.InferOutput<typeof messageEvent>;

package/dist/cli/messenger/watch-answers.js

@@ -0,0 +1,69 @@
+import { chatEventAnswer, memberAnswer, pollVoteAnswer } from "./chat-answers.js";
+import { messageItem } from "./message-items.js";
+const observed = (value) => ({
+    value: value.value,
+    observed_at: value.observedAt,
+    source: value.source,
+    ...(value.reactions === undefined ? {} : { reactions: value.reactions }),
+});
+export const watchedMessageItem = (value, account) => {
+    const counters = value.counterObservations;
+    return {
+        ...messageItem(value, account),
+        ...(value.starred === undefined ? {} : { starred: value.starred }),
+        ...(counters === undefined
+            ? {}
+            : {
+                counter_observations: {
+                    ...(counters.views === undefined ? {} : { views: observed(counters.views) }),
+                    ...(counters.reactions === undefined ? {} : { reactions: observed(counters.reactions) }),
+                    ...(counters.comments === undefined ? {} : { comments: observed(counters.comments) }),
+                },
+            }),
+    };
+};
+const affected = (value) => ({
+    chat_id: value.chatId,
+    chat_title: value.chatTitle,
+    message_id: value.messageId,
+});
+export const watchEventItem = (value, account) => {
+    switch (value.event) {
+        case "message":
+        case "edit":
+            return { event: value.event, message: watchedMessageItem(value.message, account) };
+        case "delete":
+            return { event: value.event, chat_id: value.chatId, chat_title: value.chatTitle, message_id: value.messageId };
+        case "reaction":
+            return {
+                event: value.event,
+                ...affected(value),
+                reactions: value.reactions,
+                ...(value.counterObservation === undefined ? {} : { counter_observation: observed(value.counterObservation) }),
+            };
+        case "vote":
+            return { event: value.event, ...affected(value), vote: pollVoteAnswer(value.vote) };
+        case "person_reaction":
+            return {
+                event: value.event,
+                ...affected(value),
+                reaction: {
+                    person: memberAnswer(value.reaction.person),
+                    own: value.reaction.own,
+                    reaction: value.reaction.reaction,
+                    reacted_at: value.reaction.reactedAt,
+                },
+            };
+        case "star":
+            return { event: value.event, ...affected(value), starred: value.starred };
+        case "delivery":
+            return { event: value.event, ...affected(value), delivery: value.delivery, at: value.at };
+        case "chat_event":
+            return {
+                event: value.event,
+                chat_id: value.chatId,
+                chat_title: value.chatTitle,
+                change: chatEventAnswer(value.chatId, value.change),
+            };
+    }
+};

package/dist/cli/messenger/watch-command.d.ts

@@ -4,7 +4,7 @@ import type { MessengerAdapter } from "../../ports/messenger.js";
 import { type Messenger, type MessengerContext } from "./context.js";
 /**
  * New messages as they arrive, until Ctrl-C or `--timeout` — both a normal end, exit 0: listening
- * for a minute is a complete answer. One `MessageHit` per line with `--jsonl`; `--json` is refused,
+ * for a minute is a complete answer. Canonical item records and one end record with `--jsonl`; `--json` is refused,
  * because a stream is not one value. Nothing is marked read.
  */
 export declare const watchCommand: (messenger: Messenger) => Command;