@wirecat/cli-core 0.518.0 → 0.520.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ shape of this file.
 
 ## Unreleased
 
+## 0.520.0 — 01.11.2026
+
+### Added
+
+- **`@wirecat/cli-core/mail/cli`**: `mailReadCommands({ app, read })` mounts `search messages`, `messages show` and
+  `conversations list|show` on a mail CLI, read only and scoped to the profile's mailbox. `conversations list` takes a
+  query over `subject`, `emails_count` and `last_email_at`; `store.mail.threads({ where })` and `THREAD_COLUMNS`
+  answer it in SQL.
+- **`searchMail`, `showMail`, `hitText`, `attachmentsText`, `withAttachmentText`, `lowerSuspicious`** in
+  `@wirecat/cli-core/mail`, moved from memo: mail search with demoted senders last (now also across pages), and an
+  email with the text of its attachments.
+- **`list:`** in the query language: a mailing list by its List-Id, or by a domain for every list under it
+  (`list:github.com`); mail only.
+
+## 0.519.0 — 01.11.2026
+
+### Added
+
+- **`scheduleCommandFor(host)`** mounts the `schedule` command on a CLI that is not a messenger (mail-cli): the host
+  gives its identity and a context with the environment, the profile and the output. `scheduleCommand(messenger)`
+  is the same command, unchanged.
+
 ## 0.518.0 — 01.11.2026
 
 ### Added

package/dist/cli/index.d.ts

@@ -96,6 +96,7 @@ export { httpTokenFile, type McpEnvironment, type McpHost, serverEntry } from ".
 export { type MessageItem, messageItem, type ReadMessage } from "./messenger/message-items.js";
 export { type ModeProblem, type PrivateFiles, privateFiles, withSqliteSidecars } from "./messenger/private-files.js";
 export { buildReport as buildDoctorReport, type Report as DoctorReport, type ReportContext as DoctorReportContext, reportFileName as doctorReportFileName, } from "./messenger/report.js";
+export type { ScheduleHost } from "./messenger/schedule-command.js";
 export { allAnswer, allHitItem, coverageGaps, type HitItem, type MessageHitItem, messageHitItem, type NoteHitItem, noteHitItem, shownOf, } from "./messenger/search-answers.js";
 export { SEARCHES_QUERY } from "./messenger/searches-command.js";
 export { servingProfiles } from "./messenger/serve-command.js";
@@ -114,7 +115,7 @@ export { fieldsOf, projectFields } from "./result-fields.js";
 export { type Config, type Configuration, count, first, flag, fromFile, type GlobalFlags, NONE_NAMED, namedProfile, type ProfileKind, plain, type ResolveOptions, type Settings, type SettingsExtension, type SettingsExtensionContext, type Source, settingsFor, } from "./settings.js";
 export { type PermissionAnswer, readSetupAnswers, type SetupAnswers, setupPermissionCeiling } from "./setup-answers.js";
 export { AGENTS, type Agent, agentFor, screenFor } from "./setup-screen.js";
-export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, appDoctorCommand, appMcpCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, projectsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
+export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, appDoctorCommand, appMcpCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, projectsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, scheduleCommandFor, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
 export { assertSharedContracts, customizeSharedCommand, hasSharedContract, overrideSharedContract, type SharedContractOverride, sharedContractOverrides, sharedContracts, } from "./shared-contracts.js";
 export { runnable, withSafety } from "./steps.js";
 export { type StoreInfo, sharedStoreCommand, storeInfo, storeInfoCommand } from "./store-info.js";

package/dist/cli/index.js

@@ -104,7 +104,7 @@ export { fieldsOf, projectFields } from "./result-fields.js";
 export { count, first, flag, fromFile, NONE_NAMED, namedProfile, plain, settingsFor, } from "./settings.js";
 export { readSetupAnswers, setupPermissionCeiling } from "./setup-answers.js";
 export { AGENTS, agentFor, screenFor } from "./setup-screen.js";
-export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, appDoctorCommand, appMcpCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, projectsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
+export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, appDoctorCommand, appMcpCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, projectsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, scheduleCommandFor, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
 export { assertSharedContracts, customizeSharedCommand, hasSharedContract, overrideSharedContract, sharedContractOverrides, sharedContracts, } from "./shared-contracts.js";
 export { runnable, withSafety } from "./steps.js";
 export { sharedStoreCommand, storeInfo, storeInfoCommand } from "./store-info.js";

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

@@ -1,8 +1,19 @@
 import { Command } from "commander";
+import { type AppIdentity } from "../../ports/app.js";
+import { type AnswerOutput } from "../envelope.js";
 import { type Messenger } from "./context.js";
+/** What the schedule command needs of a CLI: who it is and, per command, where it prints and which profile runs. */
+export interface ScheduleHost {
+    app: AppIdentity;
+    context(command: Command): AnswerOutput & {
+        env: NodeJS.ProcessEnv;
+        profile: string;
+    };
+}
 /**
  * Runs the CLI's own commands, or an agent, later or on a timer — through systemd (Linux), launchd
  * (macOS) or Task Scheduler (Windows). Every timer runs `schedule exec <file>`; the schedule file holds
  * the rest, so what runs and with which variables is the same on all three.
  */
+export declare const scheduleCommandFor: ({ app, context: contextOf }: ScheduleHost) => Command;
 export declare const scheduleCommand: (messenger: Messenger) => Command;

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

@@ -61,11 +61,10 @@ const withWhen = (command) => command
  * (macOS) or Task Scheduler (Windows). Every timer runs `schedule exec <file>`; the schedule file holds
  * the rest, so what runs and with which variables is the same on all three.
  */
-export const scheduleCommand = (messenger) => {
-    const { app } = messenger;
+export const scheduleCommandFor = ({ app, context: contextOf }) => {
     const command = new Command("schedule").description(`run a ${app.command} command or an agent later or on a timer (systemd, launchd, Task Scheduler); an agent cannot send`);
     const prepare = (self) => {
-        const context = messengerContext(self, messenger);
+        const context = contextOf(self);
         const system = environmentOf(self).system ?? thisMachine();
         const state = resolvePaths({ appName: app.appName, prefix: app.envPrefix, env: context.env }).state;
         const say = (value, lines) => renderAnswer(self, context, itemOf(value), () => lines.join("\n"));
@@ -230,3 +229,4 @@ export const scheduleCommand = (messenger) => {
     });
     return command;
 };
+export const scheduleCommand = (messenger) => scheduleCommandFor({ app: messenger.app, context: (command) => messengerContext(command, messenger) });

package/dist/cli/shared-command-exports.d.ts

@@ -764,6 +764,7 @@ export declare const stickersCommand: (messenger: import("./index.js").Messenger
 export declare const repliesCommand: (messenger: import("./index.js").Messenger) => import("commander").Command;
 export declare const reviewCommand: (messenger: import("./index.js").Messenger) => import("commander").Command;
 export declare const scheduleCommand: (messenger: import("./index.js").Messenger) => import("commander").Command;
+export declare const scheduleCommandFor: (args_0: import("./messenger/schedule-command.js").ScheduleHost) => import("commander").Command;
 export declare const searchCommand: (messenger: import("./index.js").Messenger, args_1?: {
     topics?: boolean;
 } | undefined) => import("commander").Command;

package/dist/cli/shared-command-exports.js

@@ -41,7 +41,7 @@ import { reactionsCommand as reactionsCommandDefinition } from "./messenger/reac
 import { callsCommand as callsCommandDefinition, stickersCommand as stickersCommandDefinition, } from "./messenger/records-command.js";
 import { repliesCommand as repliesCommandDefinition } from "./messenger/replies-command.js";
 import { reviewCommand as reviewCommandDefinition } from "./messenger/review.js";
-import { scheduleCommand as scheduleCommandDefinition } from "./messenger/schedule-command.js";
+import { scheduleCommand as scheduleCommandDefinition, scheduleCommandFor as scheduleCommandForDefinition, } from "./messenger/schedule-command.js";
 import { searchCommand as searchCommandDefinition } from "./messenger/search-command.js";
 import { searchesCommand as searchesCommandDefinition } from "./messenger/searches-command.js";
 import { serveCommand as serveCommandDefinition } from "./messenger/serve-command.js";
@@ -104,6 +104,7 @@ export const stickersCommand = sharedCommand(stickersCommandDefinition);
 export const repliesCommand = sharedCommand(repliesCommandDefinition);
 export const reviewCommand = sharedCommand(reviewCommandDefinition);
 export const scheduleCommand = sharedCommand(scheduleCommandDefinition);
+export const scheduleCommandFor = sharedCommand(scheduleCommandForDefinition);
 export const searchCommand = sharedCommand(searchCommandDefinition);
 export const searchesCommand = sharedCommand(searchesCommandDefinition);
 export const serveCommand = sharedCommand(serveCommandDefinition);

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

@@ -0,0 +1,22 @@
+import { Command } from "commander";
+import type { AppIdentity } from "../../ports/app.js";
+import { type AccountKey, type MessageStore } from "../../store/store.js";
+/** What a mail CLI hands the shared commands: how to open the store for one run, and whose mail it reads. */
+export interface MailReads {
+    app: AppIdentity;
+    /**
+     * Runs `work` over the shared store as the selected profile's mailbox, and closes the store after. Every command
+     * reads that mailbox alone; the store must take writes, since a search tops up its word index first.
+     */
+    read: <T>(command: Command, work: (store: MessageStore, mailbox: AccountKey) => Promise<T>) => Promise<T>;
+}
+export declare const THREAD_QUERY: {
+    readonly entity: "mail_thread";
+    readonly backend: "sql";
+    readonly fields: import("@wirecat/cli-base/query").FieldSpec[];
+};
+/**
+ * `search messages`, `messages show` and `conversations list|show` over the mail a mail CLI stored: the same
+ * query language, ranking and answers as memo's mail search, read only, scoped to the profile's mailbox.
+ */
+export declare const mailReadCommands: (mail: MailReads) => Command[];

package/dist/mail/cli/index.js

@@ -0,0 +1,243 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate, sharedCommand } from "@wirecat/cli-base/commands";
+import { queryFieldsOf } from "@wirecat/cli-base/query";
+import { Command, InvalidArgumentError } from "commander";
+import * as v from "valibot";
+import { answerEntity } from "../../cli/answer-entity.js";
+import { outputFor } from "../../cli/context.js";
+import { LOCAL_READ } from "../../cli/effects.js";
+import { itemOf, listOf, renderAnswer, snakeKeys } from "../../cli/envelope.js";
+import { listQuery, typedQuery, withQuery } from "../../cli/list-query.js";
+import { messagesAnswer, offsetOf, shownOf } from "../../cli/messenger/search-answers.js";
+import { positiveCount } from "../../cli/paging.js";
+import { formatReference, parseReference } from "../../domain/references.js";
+import { count, reference, text, time, untrusted } from "../../entities/fields.js";
+import { attachmentsText, hitText, searchMail, showMail, withAttachmentText } from "../../mail/read.js";
+import { atDetail } from "../../output-detail.js";
+import { queryFilter, THREAD_COLUMNS } from "../../store/store.js";
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+const limitOf = (value) => {
+    const limit = positiveCount("--limit")(value);
+    if (limit > MAX_LIMIT)
+        throw new InvalidArgumentError(`at most ${MAX_LIMIT}`);
+    return limit;
+};
+const wholeCount = (value) => {
+    if (!/^\d+$/.test(value.trim()))
+        throw new InvalidArgumentError("expected a whole number from 0");
+    return Number(value);
+};
+const detailOf = (command) => {
+    const { brief, full } = command.optsWithGlobals();
+    return brief ? "brief" : full ? "full" : undefined;
+};
+/** The thread a `chat:email/…` or `msg:email/…` reference names; another mailbox's is refused. */
+const threadOf = (mailbox, given) => {
+    const place = parseReference(given);
+    if (place.type !== "chat" && place.type !== "message")
+        throw new CliError("validation_error", `${given} names no email thread — give chat:email/… or msg:email/…`);
+    if (place.provider !== mailbox.provider || place.account !== mailbox.account)
+        throw new CliError("not_found", `${given} is not mail of this profile's mailbox ${mailbox.account}`);
+    return place.chat;
+};
+const searchCommand = (mail) => {
+    const leaf = annotate(new Command("messages"), {
+        effects: LOCAL_READ,
+        partial: true,
+        output: { entity: "message", view: "hit" },
+        examples: [
+            `${mail.app.command} ya search messages invoice`,
+            `${mail.app.command} ya search messages 'from:ann@example.com has:attachment date>30d'`,
+            `${mail.app.command} ya search messages 'list:github.com is:unread' --newest`,
+        ],
+    })
+        .summary("find stored emails by words and fields")
+        .description("search this profile's mail in the local store — what sync read — by words, people, folders, lists and dates; best match first")
+        .argument("<query...>", 'strict Lucene query: words, "phrases", AND/OR/NOT, field:value and date ranges')
+        .option("--limit <n>", `how many, at most ${MAX_LIMIT}`, limitOf)
+        .option("--page <n>", "which page, starting at 1", positiveCount("--page"))
+        .option("--newest", "newest first instead of best first")
+        .option("--exact", "bare words and quotes match their exact form only, as exact:word does")
+        .option("--plain-order", "best first by the words alone, without moving mail from suspicious senders down")
+        .option("--timezone <zone>", "the IANA timezone for calendar date boundaries")
+        .addHelpText("after", `
+Fields: from: to: cc: bcc: subject: body: mailbox: (or label:) list: (a List-Id or its domain) is:unread|read|starred
+has:attachment, filename:, content: (the text of attachments), size>, date: — \`${mail.app.command} ya search messages 'content:invoice'\`.
+chat: names a thread by its subject. Mail sent to many is in the mailbox bulk; NOT mailbox:bulk leaves it out.
+Mail from senders with signs of fraud comes after the rest of the page; --plain-order keeps it in place.
+--json: the list is items; each hit's reference is ref (msg:email/…), which messages show reads.
+Search guide: https://github.com/WireCatLabs/cli-core/blob/main/docs/search/query-language.md`)
+        .action(async function (words) {
+        const options = this.opts();
+        const limit = options.limit ?? DEFAULT_LIMIT;
+        const page = options.page ?? 1;
+        const query = words.join(" ");
+        const found = await mail.read(this, (store, mailbox) => searchMail(store, mailbox, {
+            text: query,
+            limit,
+            mailAccount: mailbox.account,
+            ...(offsetOf(page, limit) === undefined ? {} : { offset: offsetOf(page, limit) }),
+            ...(options.newest ? { newest: true } : {}),
+            ...(options.exact ? { exact: true } : {}),
+            ...(options.plainOrder ? { plainOrder: true } : {}),
+            ...(options.timezone === undefined ? {} : { timezone: options.timezone }),
+        }, { app: mail.app }));
+        const output = outputFor(this);
+        const again = {
+            query,
+            ...(options.newest ? { newest: true } : {}),
+            ...(options.exact ? { exact: true } : {}),
+            ...(options.plainOrder ? { plain_order: true } : {}),
+            ...(options.timezone === undefined ? {} : { timezone: options.timezone }),
+        };
+        const level = detailOf(this);
+        renderAnswer(this, output, messagesAnswer("search messages", found, { limit, page, again }, query), () => {
+            if (!found.wordsReady)
+                output.renderer.note(`the word index is still being built — \`${mail.app.command} store migrate\` finishes it`);
+            if (found.items.length === 0)
+                output.renderer.note("nothing found — only mail sync stored is searched");
+            const shown = shownOf(found.items.length, (page - 1) * limit, found.total);
+            if (shown)
+                output.renderer.note(shown);
+            return found.items.map((item) => `${hitText(item, level)}\n`).join("");
+        });
+    });
+    return new Command("search").summary("search the stored mail").description("find stored emails").addCommand(leaf);
+};
+const shownText = (emails) => `${emails.map((email) => [hitText(email, "full"), attachmentsText(email)].filter(Boolean).join("\n")).join("\n\n")}\n`;
+const messagesCommand = (mail) => {
+    const messages = new Command("messages").summary("read stored emails").description("read the emails sync stored");
+    annotate(messages.command("show"), {
+        effects: LOCAL_READ,
+        examples: [
+            `${mail.app.command} ya messages show 'msg:email/me%40example.com/thread-1/%3Cid%40example.com%3E'`,
+            `${mail.app.command} ya messages show 'msg:email/me%40example.com/thread-1/%3Cid%40example.com%3E' --before-n 2`,
+        ],
+    })
+        .summary("one stored email whole, with the text of its attachments")
+        .description("one stored email: its people, folders, whole text and the first 4000 characters of each attachment's text; " +
+        "--full gives all of it and the HTML body. The store keeps text, not the original message source")
+        .argument("<message>", "the msg:email/… reference a search gives")
+        .option("--before-n <n>", "also this many earlier emails of its thread", wholeCount, 0)
+        .option("--after-n <n>", "also this many later emails of its thread", wholeCount, 0)
+        .action(async function (reference) {
+        const { beforeN, afterN } = this.opts();
+        const full = detailOf(this) === "full";
+        const emails = await mail.read(this, async (store, mailbox) => {
+            threadOf(mailbox, reference);
+            return showMail(store, reference, { before: beforeN, after: afterN, full });
+        });
+        const output = outputFor(this);
+        const shown = emails.map((email) => snakeKeys(atDetail(email)));
+        renderAnswer(this, output, beforeN || afterN
+            ? listOf("messages show", { items: shown, limit: Math.max(1, shown.length), has_more: false })
+            : itemOf(shown.find((_, at) => emails[at]?.anchor) ?? shown[0]), () => shownText(emails));
+    });
+    return messages;
+};
+const mailThread = v.strictObject({
+    /** The thread as a `chat:email/…` reference, which `conversations show` takes. */
+    ref: reference,
+    subject: v.nullable(text),
+    emails_count: count,
+    last_email_at: v.nullable(time),
+    untrusted,
+});
+export const THREAD_QUERY = {
+    entity: "mail_thread",
+    backend: "sql",
+    fields: queryFieldsOf(mailThread, {
+        exclude: ["ref", "untrusted"],
+        text: ["subject"],
+        examples: { subject: "subject:invoice", emails_count: "emails_count>2", last_email_at: "last_email_at>7d" },
+    }),
+};
+const conversationsCommand = (mail) => {
+    const conversations = new Command("conversations")
+        .summary("email threads")
+        .description("the threads of the stored mail: an email and its replies");
+    const list = withQuery(annotate(conversations.command("list"), {
+        effects: LOCAL_READ,
+        examples: [
+            `${mail.app.command} ya conversations list`,
+            `${mail.app.command} ya conversations list subject:invoice emails_count>1`,
+        ],
+    })
+        .summary("stored email threads, newest first")
+        .description("this profile's email threads, the newest activity first: subject, how many emails, when"), THREAD_QUERY)
+        .option("--limit <n>", `how many, at most ${MAX_LIMIT}`, limitOf)
+        .option("--page <n>", "which page, starting at 1", positiveCount("--page"))
+        .action(async function (words) {
+        const options = this.opts();
+        const limit = options.limit ?? DEFAULT_LIMIT;
+        const page = options.page ?? 1;
+        const typed = typedQuery(words);
+        const query = listQuery(typed, THREAD_QUERY, "conversations list");
+        const { threads, mailbox } = await mail.read(this, async (store, mailbox) => {
+            const account = await store.accounts.storedAccount(mailbox).catch(() => undefined);
+            if (!account)
+                return { threads: [], mailbox };
+            const where = query ? queryFilter(query, THREAD_COLUMNS, { command: "conversations list" }) : undefined;
+            const threads = await store.mail.threads({
+                accountId: account.id,
+                limit: limit + 1,
+                offset: (page - 1) * limit,
+                ...(where ? { where } : {}),
+            });
+            return { threads, mailbox };
+        });
+        const items = threads.slice(0, limit).map((thread) => ({
+            ref: formatReference({ type: "chat", ...mailbox, chat: thread.externalId }),
+            subject: thread.subject,
+            emails_count: thread.emailsCount,
+            last_email_at: thread.lastEmailAt === null ? null : new Date(thread.lastEmailAt).toISOString(),
+            untrusted: ["subject"],
+        }));
+        renderAnswer(this, outputFor(this), listOf("conversations list", {
+            items,
+            limit,
+            has_more: threads.length > limit,
+            page,
+            ...(typed.trim() ? { args: { query: typed } } : {}),
+        }), () => items
+            .map((one) => `${one.ref}\n  ${one.last_email_at ?? "time unknown"}  ${one.emails_count}  ${one.subject ?? ""}\n`)
+            .join(""));
+    });
+    answerEntity(list, "mail_thread", mailThread);
+    annotate(conversations.command("show"), {
+        effects: LOCAL_READ,
+        examples: [
+            `${mail.app.command} ya conversations show 'chat:email/me%40example.com/thread-1'`,
+            `${mail.app.command} ya conversations show 'msg:email/me%40example.com/thread-1/%3Cid%40example.com%3E'`,
+        ],
+    })
+        .summary("one email thread, every email oldest first")
+        .description("every stored email of one thread, oldest first, each with the text of its attachments")
+        .argument("<conversation>", "a chat:email/… thread from conversations list, or a msg:email/… email in it")
+        .action(async function (given) {
+        const full = detailOf(this) === "full";
+        const emails = await mail.read(this, async (store, mailbox) => {
+            const thread = threadOf(mailbox, given);
+            const account = await store.accounts.storedAccount(mailbox).catch(() => undefined);
+            const hits = account ? await store.mail.threadHits(account.id, thread) : [];
+            if (!account || hits.length === 0)
+                throw new CliError("not_found", `no stored thread ${given}`);
+            return Promise.all(hits.map(async (hit) => hit.attachments?.length
+                ? withAttachmentText(hit, (await store.mail.email(account.id, hit.id))?.attachments ?? [], full)
+                : hit));
+        });
+        const items = emails.map((email) => snakeKeys(atDetail(email)));
+        renderAnswer(this, outputFor(this), listOf("conversations show", { items, limit: Math.max(1, items.length), has_more: false }), () => shownText(emails));
+    });
+    return conversations;
+};
+/**
+ * `search messages`, `messages show` and `conversations list|show` over the mail a mail CLI stored: the same
+ * query language, ranking and answers as memo's mail search, read only, scoped to the profile's mailbox.
+ */
+export const mailReadCommands = sharedCommand((mail) => [
+    searchCommand(mail),
+    messagesCommand(mail),
+    conversationsCommand(mail),
+]);

package/dist/mail/index.d.ts

@@ -8,6 +8,7 @@ export { type Address, htmlToText, looksLikeHtml, MAX_BODY_CHARS, type ParsedMai
 export { PRESET_NAMES, PRESETS, type PresetName, presetMatches } from "./presets.js";
 export { domainsToAge, groupKey, type Probe, type ProbeGroup, probeMail, SUGGEST_RULE } from "./probe.js";
 export { type MailFolderProgress, mailProgress } from "./progress.js";
+export { ATTACHMENT_CHARS, attachmentsText, hitText, lowerSuspicious, type MailSearch, type ShownMail, searchMail, showMail, withAttachmentText, } from "./read.js";
 export { type FileStamp, FULL_PASS_MS, MBOX_RESUME, type MboxPoint, mergeRanges, parsePoint, type Ranges, type ResumePoint, rangesOf, resumeKey, rulesKey, within, } from "./resume.js";
 export { ruleInput, STORE_ACTION } from "./rule-input.js";
 export { storedMailRule, storedMailRules } from "./rule-stored.js";

package/dist/mail/index.js

@@ -8,6 +8,7 @@ export { htmlToText, looksLikeHtml, MAX_BODY_CHARS, parseMail, } from "./parse.j
 export { PRESET_NAMES, PRESETS, presetMatches } from "./presets.js";
 export { domainsToAge, groupKey, probeMail, SUGGEST_RULE } from "./probe.js";
 export { mailProgress } from "./progress.js";
+export { ATTACHMENT_CHARS, attachmentsText, hitText, lowerSuspicious, searchMail, showMail, withAttachmentText, } from "./read.js";
 export { FULL_PASS_MS, MBOX_RESUME, mergeRanges, parsePoint, rangesOf, resumeKey, rulesKey, within, } from "./resume.js";
 export { ruleInput, STORE_ACTION } from "./rule-input.js";
 export { storedMailRule, storedMailRules } from "./rule-stored.js";

package/dist/mail/read.d.ts

@@ -0,0 +1,55 @@
+import type { Saved } from "../services/message-resolution.js";
+import type { SearchFound } from "../services/messages.js";
+import type { AccountKey, MessageStore, StoredHit } from "../store/store.js";
+/** Mail from senders with signs of fraud after the rest of the page, each part in the order it had. */
+export declare const lowerSuspicious: <T>(items: readonly T[], suspicious: (item: T) => boolean) => T[];
+export interface MailSearch {
+    text: string;
+    limit: number;
+    offset?: number;
+    /** Only these mailboxes; every stored one when neither this nor `mailAccount` is given. */
+    accounts?: AccountKey[];
+    /** Only this mailbox, by its address. */
+    mailAccount?: string;
+    exact?: boolean;
+    timezone?: string;
+    newest?: boolean;
+    /** Leave mail from suspicious senders where the words put it, instead of after the rest. */
+    plainOrder?: boolean;
+}
+/**
+ * Stored mail by the shared query language, best first. Mail whose sender search demotes comes after the rest,
+ * unless `plainOrder` or `newest` asks for another order. `runAs` is the account the search runs as.
+ */
+export declare const searchMail: (store: MessageStore, runAs: AccountKey, { text, limit, offset, accounts, mailAccount, exact, timezone, newest, plainOrder }: MailSearch, saved?: Saved) => Promise<SearchFound>;
+/** Enough for a bill's amounts and dates; the whole text is asked for separately. */
+export declare const ATTACHMENT_CHARS = 4000;
+export type ShownMail = StoredHit & {
+    anchor?: true;
+};
+interface StoredFile {
+    text: string | null;
+    extraction: string | null;
+    extractionError: string | null;
+}
+/** The extracted text of each attachment, next to the name the email lists; a file without text says why. */
+export declare const withAttachmentText: (hit: ShownMail, files: readonly StoredFile[], full: boolean) => ShownMail;
+/**
+ * One stored email by its `msg:email/…` locator, with up to `before` and `after` emails of its thread, each with
+ * the text of its attachments: the first `ATTACHMENT_CHARS` of each, or all of it and the HTML body with `full`.
+ */
+export declare const showMail: (store: MessageStore, locator: string, { before, after, full }?: {
+    before?: number;
+    after?: number;
+    full?: boolean;
+}) => Promise<ShownMail[]>;
+/**
+ * A found message or email for a reader: its reference first, then when and from whom, who else it went to and
+ * where it is filed, its subject or chat, and an excerpt — the whole text only at `full`.
+ */
+export declare const hitText: (item: StoredHit & {
+    excerpt?: string;
+}, level?: "brief" | "full") => string;
+/** Each attachment of a shown email with its text indented under it, or why it has none. */
+export declare const attachmentsText: (hit: ShownMail) => string;
+export {};

package/dist/mail/read.js

@@ -0,0 +1,114 @@
+import { parseLocator } from "../domain/locator.js";
+import { readMail } from "../services/mail-search.js";
+import { searchStore } from "../services/messages-archive-search.js";
+/** Mail from senders with signs of fraud after the rest of the page, each part in the order it had. */
+export const lowerSuspicious = (items, suspicious) => [
+    ...items.filter((item) => !suspicious(item)),
+    ...items.filter(suspicious),
+];
+/** A few more than asked, so mail moved down makes room for the next best rather than an empty slot. */
+const LOWERED_SPARE = 20;
+/**
+ * Stored mail by the shared query language, best first. Mail whose sender search demotes comes after the rest,
+ * unless `plainOrder` or `newest` asks for another order. `runAs` is the account the search runs as.
+ */
+export const searchMail = async (store, runAs, { text, limit, offset = 0, accounts, mailAccount, exact, timezone, newest, plainOrder }, saved = {}) => {
+    const lower = !plainOrder && !newest;
+    const request = {
+        text,
+        kind: "mail",
+        ...(accounts === undefined ? {} : { accounts }),
+        ...(mailAccount === undefined ? {} : { mailAccount }),
+        ...(exact ? { exact: true } : {}),
+        ...(timezone === undefined ? {} : { timezone }),
+        ...(newest ? { newest: true } : {}),
+    };
+    if (!lower)
+        return searchStore(store, runAs, { ...request, limit, offset }, saved);
+    // Lowered from the first hit on, so a later page never repeats or skips what an earlier one moved.
+    const found = await searchStore(store, runAs, { ...request, limit: offset + limit + LOWERED_SPARE }, saved);
+    const items = lowerSuspicious(found.items, (item) => item.email?.senderScore?.demoted === true);
+    const hasMore = found.hasMore || items.length > offset + limit;
+    const { nextOffset: _, ...rest } = found;
+    return {
+        ...rest,
+        items: items.slice(offset, offset + limit),
+        hasMore,
+        ...(hasMore ? { nextOffset: offset + limit } : {}),
+    };
+};
+/** Enough for a bill's amounts and dates; the whole text is asked for separately. */
+export const ATTACHMENT_CHARS = 4000;
+/** The HTML and AMP alternatives of the body: markup, not attachments, and thousands of characters each. */
+const isBodyAlternative = (attachment) => attachment.mime === "text/html" || attachment.mime === "text/x-amp-html";
+/** The extracted text of each attachment, next to the name the email lists; a file without text says why. */
+export const withAttachmentText = (hit, files, full) => ({
+    ...hit,
+    attachments: (hit.attachments ?? [])
+        .map((attachment, at) => ({ attachment, file: files[at] }))
+        .filter(({ attachment }) => full || !isBodyAlternative(attachment))
+        .map(({ attachment, file }) => {
+        const text = file?.text ?? "";
+        if (!text)
+            return { ...attachment, extraction: file?.extractionError ?? file?.extraction ?? "none" };
+        const cut = !full && text.length > ATTACHMENT_CHARS;
+        return {
+            ...attachment,
+            text: cut ? text.slice(0, ATTACHMENT_CHARS) : text,
+            text_chars: text.length,
+            ...(cut ? { text_cut: true } : {}),
+        };
+    }),
+});
+/**
+ * One stored email by its `msg:email/…` locator, with up to `before` and `after` emails of its thread, each with
+ * the text of its attachments: the first `ATTACHMENT_CHARS` of each, or all of it and the HTML body with `full`.
+ */
+export const showMail = async (store, locator, { before = 0, after = 0, full = false } = {}) => {
+    const shown = await readMail(store, locator, { before, after });
+    const account = await store.accounts.storedAccount({ provider: "email", account: parseLocator(locator).account });
+    if (!account)
+        return shown;
+    return Promise.all(shown.map(async (hit) => {
+        if (!hit.attachments?.length)
+            return hit;
+        const email = await store.mail.email(account.id, hit.id);
+        return withAttachmentText(hit, email?.attachments ?? [], full);
+    }));
+};
+const line = (text) => text.replace(/\s+/g, " ").trim();
+/**
+ * A found message or email for a reader: its reference first, then when and from whom, who else it went to and
+ * where it is filed, its subject or chat, and an excerpt — the whole text only at `full`.
+ */
+export const hitText = (item, level) => {
+    const mail = item.email;
+    const names = (people) => people.map(({ name, address }) => line(name ?? address)).join(", ");
+    const between = mail
+        ? [
+            mail.to.length ? `to ${names(mail.to)}` : "",
+            mail.cc.length ? `cc ${names(mail.cc)}` : "",
+            mail.labels.join(", "),
+        ]
+            .filter(Boolean)
+            .join(" · ")
+        : "";
+    const who = line(item.senderName ?? item.senderId ?? "unknown");
+    return [
+        item.locator,
+        `  ${item.timestamp}  ${who}${level === "brief" || !between ? "" : `  ${between}`}`,
+        ...(level === "brief" || !item.chatTitle ? [] : [`  ${line(item.chatTitle)}`]),
+        `  ${level === "full" ? item.text.replace(/\n/g, "\n  ") : line(item.excerpt ?? item.text)}`,
+    ].join("\n");
+};
+/** Each attachment of a shown email with its text indented under it, or why it has none. */
+export const attachmentsText = (hit) => (hit.attachments ?? [])
+    .map((attachment) => {
+    const file = attachment;
+    const name = file.name ?? file.kind;
+    if (file.text === undefined)
+        return `  ── attachment ${name}: no text (${file.extraction}) ──`;
+    const cut = file.text.length < (file.text_chars ?? 0) ? `, first ${file.text.length} of ${file.text_chars}` : "";
+    return `  ── attachment ${name} (${file.text_chars} characters${cut}) ──\n  ${file.text.replace(/\n/g, "\n  ")}`;
+})
+    .join("\n");

package/dist/search/lucene/registry.js

@@ -125,6 +125,17 @@ export const QUERY_FIELDS = [
         normalization: "the same as mailbox:; mail only",
         support: "A1",
     },
+    {
+        name: "list",
+        example: "list:github.com",
+        index: "emails.headers list-id",
+        aliases: [],
+        type: "kw",
+        operators: terms,
+        normalization: "the List-Id of a mailing list, lower case; a domain matches every list under it; mail only",
+        support: "A1",
+        validate: filled,
+    },
     {
         name: "is",
         example: "is:unread",

package/dist/store/exports.d.ts

@@ -54,6 +54,7 @@ export { savedTaskCategories } from "./sqlite/task-category-settings.js";
 export { DEFAULT_AGENT_CLOSE, savedAgentClose } from "./sqlite/task-close.js";
 export { DEFAULT_FIRST_PASS_PER_CHAT, firstPassPerChatOf, savedFirstPassPerChat } from "./sqlite/task-first-pass.js";
 export { inboxKey } from "./sqlite/tasks.js";
+export { THREAD_COLUMNS } from "./sqlite/thread-columns.js";
 export { dropAllUnusedVectors, vectorIndexCounts } from "./sqlite/vector-index.js";
 export type { MatchPlace, ScoredHit } from "./sqlite/words.js";
 export type { TaskDetails } from "./sqlite/work-tasks.js";

package/dist/store/exports.js

@@ -24,4 +24,5 @@ export { savedTaskCategories } from "./sqlite/task-category-settings.js";
 export { DEFAULT_AGENT_CLOSE, savedAgentClose } from "./sqlite/task-close.js";
 export { DEFAULT_FIRST_PASS_PER_CHAT, firstPassPerChatOf, savedFirstPassPerChat } from "./sqlite/task-first-pass.js";
 export { inboxKey } from "./sqlite/tasks.js";
+export { THREAD_COLUMNS } from "./sqlite/thread-columns.js";
 export { dropAllUnusedVectors, vectorIndexCounts } from "./sqlite/vector-index.js";

package/dist/store/sqlite/emails.d.ts

@@ -8,6 +8,7 @@ import { type MailRulesStore } from "./mail-rules.js";
 import { type AttachmentInput } from "./meetings.js";
 import type { StoreContext } from "./open.js";
 import { type SyncStateSave } from "./sync.js";
+import { type ThreadFilter } from "./thread-columns.js";
 export type { EmailLocationInput, FolderEmail };
 export interface EmailAddress {
     address: string;
@@ -206,8 +207,8 @@ export interface MailStore {
     saveThread(input: ThreadSave): Promise<ThreadDetails>;
     /** Several threads and sync state in one transaction: a slice of mail commits with its resume point, or not at all. */
     saveThreads(inputs: ThreadSave[], states?: SyncStateSave[]): Promise<ThreadDetails[]>;
-    /** Newest activity first. */
-    threads(filter?: MailFilter): Promise<EmailThread[]>;
+    /** Newest activity first; `where` is a list query compiled over `THREAD_COLUMNS`. */
+    threads(filter?: ThreadFilter): Promise<EmailThread[]>;
     thread(id: number): Promise<ThreadDetails | null>;
     email(accountId: number, externalId: string): Promise<Email | null>;
     /** Newest first. */

package/dist/store/sqlite/emails.js

@@ -11,6 +11,7 @@ import { mailRulesOver } from "./mail-rules.js";
 import { attachmentOf, saveAttachment, wordsQuery } from "./meetings.js";
 import { stemmerCache } from "./stems.js";
 import { writeState } from "./sync.js";
+import { threadRows } from "./thread-columns.js";
 import { write } from "./transaction.js";
 import { dropUnusedVectors } from "./vector-index.js";
 import { dot } from "./vectors.js";
@@ -432,12 +433,7 @@ export const mailStoreOver = ({ database, orm, now }, stemmerFor = stemmerCache(
         return ids.map((id) => threadDetails(database, id));
     },
     async threads(filter = {}) {
-        const [limit, offset] = page(filter);
-        return database
-            .prepare(`SELECT * FROM email_threads WHERE (? IS NULL OR account_id = ?) AND (? OR deleted_at IS NULL)
-          ORDER BY coalesce(last_email_at, 0) DESC, id DESC LIMIT ? OFFSET ?`)
-            .all(filter.accountId ?? null, filter.accountId ?? null, filter.includeDeleted ? 1 : 0, limit, offset)
-            .map(threadOf);
+        return threadRows(database, filter).map(threadOf);
     },
     async thread(id) {
         return threadDetails(database, id);

package/dist/store/sqlite/lucene-fields.js

@@ -381,6 +381,14 @@ const mailbox = ({ value }, { mail }) => always(mail
     `m.id IN (SELECT em.email_id FROM email_mailboxes em WHERE em.mailbox_id IN
                (SELECT b.id FROM mailboxes b WHERE lower(b.external_id) = lower(?) OR b.name_folded = ?))`, value, fold(value))
     : bound("0"));
+// Mail stored in full keeps List-Id in its headers; mail only recorded, in its metadata.
+const list = ({ value }, { mail }) => {
+    const wanted = value.trim().toLowerCase();
+    return always(mail
+        ? bound(`m.id IN (SELECT id FROM (SELECT id, coalesce(json_extract(headers, '$."list-id"'),
+             json_extract(metadata, '$.listId')) AS list_id FROM emails) WHERE list_id = ? OR list_id LIKE '%.' || ? ESCAPE '\\')`, wanted, wanted.replace(/[\\%_]/g, "\\$&"))
+        : bound("0"));
+};
 const is = ({ value }, { mail }) => {
     const state = value.toLowerCase();
     return always(state === "starred"
@@ -441,6 +449,7 @@ export const FIELD_COMPILERS = {
     source: notesOnly,
     mailbox,
     label: mailbox,
+    list,
     is,
     subject,
 };

package/dist/store/sqlite/thread-columns.d.ts

@@ -0,0 +1,24 @@
+import type { CacheDatabase } from "../driver.js";
+import type { MailFilter } from "./emails.js";
+import type { Where } from "./query-filter.js";
+/** A thread list query's columns. `subject:` finds a word or phrase at a word's start, `word*` included. */
+export declare const THREAD_COLUMNS: {
+    readonly subject: {
+        readonly where: ({ value }: import("@wirecat/cli-base/query").Predicate) => {
+            sql: string;
+            params: string[];
+        };
+    };
+    readonly emails_count: {
+        readonly type: "num";
+        readonly sql: "email_threads.emails_count";
+    };
+    readonly last_email_at: {
+        readonly type: "time";
+        readonly sql: "email_threads.last_email_at";
+    };
+};
+export type ThreadFilter = MailFilter & {
+    where?: Where;
+};
+export declare const threadRows: (database: CacheDatabase, filter: ThreadFilter) => Record<string, unknown>[];

package/dist/store/sqlite/thread-columns.js

@@ -0,0 +1,20 @@
+import { fold } from "../normalize.js";
+import { page } from "./events.js";
+/** A thread list query's columns. `subject:` finds a word or phrase at a word's start, `word*` included. */
+export const THREAD_COLUMNS = {
+    subject: {
+        where: ({ value }) => ({
+            sql: "instr(' ' || coalesce(email_threads.subject_folded, lower(email_threads.subject)), ' ' || ?) > 0",
+            params: [fold(value).replace(/\*+$/, "")],
+        }),
+    },
+    emails_count: { type: "num", sql: "email_threads.emails_count" },
+    last_email_at: { type: "time", sql: "email_threads.last_email_at" },
+};
+export const threadRows = (database, filter) => {
+    const [limit, offset] = page(filter);
+    return database
+        .prepare(`SELECT * FROM email_threads WHERE (? IS NULL OR account_id = ?) AND (? OR deleted_at IS NULL)
+         AND (${filter.where?.sql ?? "1"}) ORDER BY coalesce(last_email_at, 0) DESC, id DESC LIMIT ? OFFSET ?`)
+        .all(filter.accountId ?? null, filter.accountId ?? null, filter.includeDeleted ? 1 : 0, ...(filter.where?.params ?? []), limit, offset);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.518.0",
+  "version": "0.520.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -129,6 +129,10 @@
       "types": "./dist/mail/index.d.ts",
       "default": "./dist/mail/index.js"
     },
+    "./mail/cli": {
+      "types": "./dist/mail/cli/index.d.ts",
+      "default": "./dist/mail/cli/index.js"
+    },
     "./mail/testing": {
       "types": "./dist/mail/testing/index.d.ts",
       "default": "./dist/mail/testing/index.js"