@wirecat/cli-core 0.524.0 → 0.526.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## Unreleased
+
+## 0.526.0 — 01.11.2026
+
+### Added
+
+- **`mailIds` from `@wirecat/cli-core/mail`: one email id for mail and memo.** On every server but Gmail the id is
+  the hash of the Message-ID (the UID with its folder and UIDVALIDITY when there is none) and the thread is the first
+  id of References, else In-Reply-To. OBJECTID's EMAILID is not used, so a server that turns OBJECTID on keeps its
+  ids. Gmail keeps X-GM-MSGID and X-GM-THRID.
+- **`decodedLabelName` for a Gmail label already decoded.** imapflow decodes X-GM-LABELS; `labelName` decodes the
+  modified UTF-7 again and turned `R&D-team` into `Rteam`. `labelName` stays for the wire form.
+- **`storedMailRuleSet`: the stored rules this build cannot read, with why.** A sync reports them instead of dropping
+  them silently; `storedMailRules` still returns only the rules.
+
+### Fixed
+
+- **`conversations list` and `conversations show` no longer read a failing store as "nothing stored".** Only a
+  missing account answers empty or not found; a locked or broken store fails the command.
+- **The messenger `search messages` help sends mail searches to `mail <profile> search messages`**, not to memo.
+
+## 0.525.0 — 01.11.2026
+
+### Added
+
+- **Mail server search.** `mailReadCommands({ app, read, server })` gives `search messages` the shared
+  `--backend archive|server|both` and `--server-time`, as tg has them: the mail server is asked for candidates, the
+  new ones are stored, and the same strict query runs on the store, so each hit says `found_in`. `searchMailServer`
+  does it; `mailCriteriaOf` turns the query into `MailCriteria` (words, `from:` `to:` `cc:` `subject:` `body:`
+  `is:` and `date:`, one per top-level OR) for a `MailSource.query`, which a mail CLI translates into its server's
+  syntax. An owner's skip and envelope rules keep a find out of the store, as in a sync; nothing moves the sync's saved
+  position. The fake mail source answers `query` and records it in `queried`. When the server answers in part,
+  `meta.complete` is false with an issue per reason (`search.offline`, `search.server-timeout`, …; new
+  `search.server-*` reasons).
+- `searchMail` takes `only`, and the store's word search reads `only` over mail as over messages.
+- `serverSearchOptions(command, where)` mounts `--backend` and `--server-time` on any search; `backendOptions` uses it.
+- **`AppIdentity.sends`**: a CLI that is not a messenger yet sends to people (mail) keeps `sends_per_hour`, so the
+  owner can set its hourly limit with `config set sends_per_hour`; the other messenger settings stay hidden.
+
 ## 0.524.0 — 01.11.2026
 
 ### Added

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

@@ -49,7 +49,7 @@ offer \`${messenger.app.command} messages sync <chat>\` and run it only once the
         : `Search reads the local archive: what \`${messenger.app.command} serve\` has kept since the account was linked.
 Keep serve running so new messages are searchable.`} Notes are
 \`${messenger.app.command} search notes\`, messages and notes at once \`${messenger.app.command} search all\`; for mail,
-the separate memo CLI: \`memo search mail\`.
+the mail CLI: \`mail <profile> search messages\`.
 A bare word looks in message text, voice transcripts, file names and file text. text:, transcript:,
 content: (the text of files) and filename: (their names) narrow it to one —
 \`${messenger.app.command} search messages 'content:invoice'\`. chat: narrows it to one chat; has:voice, has:file and

package/dist/cli/messenger/search-backend-options.d.ts

@@ -1,10 +1,12 @@
 import type { Command } from "commander";
 import type { Backend, ServerOptions, ServerSearched } from "../../services/server-search.js";
 import type { Messenger, MessengerContext } from "./context.js";
+/** `--backend` and `--server-time`, for any search whose source has a server that searches: `where` names it. */
+export declare const serverSearchOptions: (command: Command, where: string) => Command;
 /** Mounted only where the messenger's server can search messages. */
 export declare const backendOptions: (command: Command, messenger: Messenger) => Command;
 export declare const backendRequest: (command: Command) => {
     backend?: Backend;
     server?: ServerOptions;
 };
-export declare const noteServer: (context: MessengerContext, server: ServerSearched | undefined) => void;
+export declare const noteServer: (context: Pick<MessengerContext, "renderer">, server: ServerSearched | undefined) => void;

package/dist/cli/messenger/search-backend-options.js

@@ -5,11 +5,13 @@ const backendOf = (value) => {
         throw new CliError("validation_error", "--backend takes archive, server or both");
     return value;
 };
+/** `--backend` and `--server-time`, for any search whose source has a server that searches: `where` names it. */
+export const serverSearchOptions = (command, where) => command
+    .option("--backend <archive|server|both>", `where to search: the local archive, ${where}, or both`, backendOf)
+    .option("--server-time <duration>", "stop waiting for the server after this long (default: 5s)");
 /** Mounted only where the messenger's server can search messages. */
 export const backendOptions = (command, messenger) => messenger.serverSearch
-    ? command
-        .option("--backend <archive|server|both>", "where to search: the local archive, the messenger's server, or both (default: both; message discovery uses archive only)", backendOf)
-        .option("--server-time <duration>", "stop waiting for the server after this long (default: 5s)")
+    ? serverSearchOptions(command, "the messenger's server (default: both; message discovery uses archive only)")
     : command;
 export const backendRequest = (command) => {
     const { backend, serverTime } = command.opts();

package/dist/cli/settings.js

@@ -162,7 +162,9 @@ export const settingsFor = (app, extension = {}) => {
     const schema = strictOf(configEntries);
     const defaultsOnlyKeys = Object.keys(defaultsOnly);
     const botOnlyKeys = Object.keys(BOT_ONLY_ENTRIES);
-    const allSettings = [...Object.keys(profileEntries), ...botOnlyKeys, ...defaultsOnlyKeys].filter((setting) => app.messenger !== false || !MESSENGER_ONLY_SETTINGS.includes(setting));
+    const allSettings = [...Object.keys(profileEntries), ...botOnlyKeys, ...defaultsOnlyKeys].filter((setting) => app.messenger !== false ||
+        !MESSENGER_ONLY_SETTINGS.includes(setting) ||
+        (app.sends === true && setting === "sends_per_hour"));
     const PROFILE = envName(app, "PROFILE");
     const PROFILE_LOCK = envName(app, "PROFILE_LOCK");
     const TIMEOUT = envName(app, "TIMEOUT");

package/dist/errors/reasons.js

@@ -69,6 +69,13 @@ const OTHERS = [
     validation("search.no-calendars", "no calendar of this profile syncs yet, so the provider has nothing to search"),
     validation("search.server-options", "search --backend server takes neither --exact, --cursor nor --newest"),
     validation("search.one-backend", "search answers from one backend at a time: archive or server"),
+    ["search.server-not-allowed", "permission_error", "the profile does not allow messages.server-search"],
+    validation("search.server-no-criteria", "the query has nothing the server can search, so only the store is read"),
+    ["search.server-unsupported", "provider_error", "this source's server cannot search"],
+    ["search.server-rate-limited", "rate_limited", "the server refused a search as too many requests"],
+    ["search.server-failed", "provider_unavailable", "the server did not answer a search"],
+    ["search.server-timeout", "timeout", "the server did not answer within --server-time"],
+    ["search.server-capped", "outcome_unknown", "the server found more than one search reads, or a branch was not sent"],
     validation("store.refused", "the local store refused the document text"),
     ["store.not-writable", "permission_error", "the message store cannot be written from this process"],
     [

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

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { type MailServerAccess } from "../../mail/server-search.js";
 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. */
@@ -9,6 +10,8 @@ export interface MailReads {
      * 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>;
+    /** The mailbox's server, for `search messages --backend`; without it the search reads the store only. */
+    server?: (command: Command) => MailServerAccess;
 }
 export declare const THREAD_QUERY: {
     readonly entity: "mail_thread";

package/dist/mail/cli/index.js

@@ -5,16 +5,25 @@ 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 { LOCAL_READ, REMOTE_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 { backendRequest, noteServer, serverSearchOptions } from "../../cli/messenger/search-backend-options.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 { searchMailServer } from "../../mail/server-search.js";
 import { atDetail } from "../../output-detail.js";
+import { sourceKey } from "../../services/server-search.js";
 import { queryFilter, THREAD_COLUMNS } from "../../store/store.js";
+/** A locked or broken store must fail the command, not read as "nothing stored yet". */
+const absentAccount = (error) => {
+    if (error instanceof CliError && error.code === "not_found")
+        return undefined;
+    throw error;
+};
 const DEFAULT_LIMIT = 20;
 const MAX_LIMIT = 100;
 const limitOf = (value) => {
@@ -41,9 +50,37 @@ const threadOf = (mailbox, given) => {
         throw new CliError("not_found", `${given} is not mail of this profile's mailbox ${mailbox.account}`);
     return place.chat;
 };
+const SKIPPED = {
+    unsupported: { code: "provider_error", reason: "search.server-unsupported" },
+    pushed_history: { code: "provider_error", reason: "search.server-unsupported" },
+    offline: { code: "permission_error", reason: "search.offline" },
+    not_allowed: { code: "permission_error", reason: "search.server-not-allowed" },
+    other_accounts: { code: "validation_error", reason: "search.server-no-criteria" },
+    no_words: { code: "validation_error", reason: "search.server-no-criteria" },
+    needs_chat: { code: "validation_error", reason: "search.server-no-criteria" },
+};
+const FAILED = {
+    rate_limited: { code: "rate_limited", reason: "search.server-rate-limited" },
+    search_failed: { code: "provider_unavailable", reason: "search.server-failed" },
+    time_or_abort_bound: { code: "timeout", reason: "search.server-timeout" },
+};
+/** What the server search left out, so `meta.complete` is false whenever any of it is (WC-OUT-7). */
+const serverIssues = (server) => {
+    if (!server || server.complete)
+        return [];
+    if (server.skipped)
+        return [{ ...SKIPPED[server.skipped], source: "server" }];
+    const failed = [...new Set(server.failed.map(({ reason }) => reason))].map((reason) => ({
+        ...FAILED[reason],
+        source: "server",
+    }));
+    return failed.length
+        ? failed
+        : [{ code: "outcome_unknown", reason: "search.server-capped", source: "server" }];
+};
 const searchCommand = (mail) => {
     const leaf = annotate(new Command("messages"), {
-        effects: LOCAL_READ,
+        effects: mail.server ? REMOTE_READ : LOCAL_READ,
         partial: true,
         output: { entity: "message", view: "hit" },
         examples: [
@@ -52,8 +89,11 @@ const searchCommand = (mail) => {
             `${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")
+        .summary(mail.server ? "find emails by words and fields" : "find stored emails by words and fields")
+        .description(mail.server
+        ? "search this profile's mail in the local store and, by default, on the mail server for mail sync has not read " +
+            "yet (--backend); the server's finds are stored, then one strict query decides; best match first"
+        : "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"))
@@ -66,23 +106,59 @@ Fields: from: to: cc: bcc: subject: body: mailbox: (or label:) list: (a List-Id
 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) {
+--json: the list is items; each hit's reference is ref (msg:email/…), which messages show reads.${mail.server
+        ? `
+--backend: the server is asked for words, from: to: cc: subject: body: is: and date:, in INBOX, Sent and Archive or
+all of Gmail; the rest stays with the strict query on the store. Permission key: messages.server-search.
+found_in says archive, server (new from the server) or both; meta.complete is false when the server answered in part.`
+        : ""}
+Search guide: https://github.com/WireCatLabs/cli-core/blob/main/docs/search/query-language.md`);
+    if (mail.server)
+        serverSearchOptions(leaf, "the mail server (default: both)");
+    leaf.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 { backend, server: bounds } = mail.server ? backendRequest(this) : {};
+        const found = await mail.read(this, async (store, mailbox) => {
+            const step = mail.server
+                ? await searchMailServer(store, mailbox, mail.server(this), {
+                    text: query,
+                    ...(backend === undefined ? {} : { backend }),
+                    ...(bounds?.timeMs === undefined ? {} : { timeMs: bounds.timeMs }),
+                    ...(options.exact ? { exact: true } : {}),
+                    ...(options.timezone === undefined ? {} : { timezone: options.timezone }),
+                })
+                : undefined;
+            const only = backend === "server" && step
+                ? [...step.sources.keys()].map((key) => {
+                    const [chatId, id] = JSON.parse(key);
+                    return { ...mailbox, chatId, id };
+                })
+                : undefined;
+            const found = await 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 }),
+                ...(only ? { only } : {}),
+            }, { app: mail.app });
+            if (!step)
+                return found;
+            return {
+                ...found,
+                server: step.report,
+                items: found.items.map((hit) => ({
+                    ...hit,
+                    source: step.sources.get(sourceKey(hit.chatId, hit.id)) ?? "archive",
+                })),
+            };
+        });
         const output = outputFor(this);
         const again = {
             query,
@@ -92,11 +168,18 @@ Search guide: https://github.com/WireCatLabs/cli-core/blob/main/docs/search/quer
             ...(options.timezone === undefined ? {} : { timezone: options.timezone }),
         };
         const level = detailOf(this);
-        renderAnswer(this, output, messagesAnswer("search messages", found, { limit, page, again }, query), () => {
+        const answer = messagesAnswer("search messages", found, { limit, page, again }, query);
+        const issues = serverIssues(found.server);
+        if (issues.length)
+            answer.meta = { ...answer.meta, complete: false, issues: [...(answer.meta?.issues ?? []), ...issues] };
+        renderAnswer(this, output, answer, () => {
             if (!found.wordsReady)
                 output.renderer.note(`the word index is still being built — \`${mail.app.command} store migrate\` finishes it`);
+            noteServer(output, found.server);
             if (found.items.length === 0)
-                output.renderer.note("nothing found — only mail sync stored is searched");
+                output.renderer.note(found.server && !found.server.skipped
+                    ? "nothing found in the local store or on the mail server"
+                    : "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);
@@ -175,7 +258,7 @@ const conversationsCommand = (mail) => {
         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);
+            const account = await store.accounts.storedAccount(mailbox).catch(absentAccount);
             if (!account)
                 return { threads: [], mailbox };
             const where = query ? queryFilter(query, THREAD_COLUMNS, { command: "conversations list" }) : undefined;
@@ -219,7 +302,7 @@ const conversationsCommand = (mail) => {
         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 account = await store.accounts.storedAccount(mailbox).catch(absentAccount);
             const hits = account ? await store.mail.threadHits(account.id, thread) : [];
             if (!account || hits.length === 0)
                 throw new CliError("not_found", `no stored thread ${given}`);

package/dist/mail/email-input.d.ts

@@ -0,0 +1,5 @@
+import type { EmailInput } from "../store/index.js";
+import type { ParsedMail } from "./parse.js";
+import type { Listed } from "./source.js";
+/** What one read email stores of itself, whichever run read it; where it is filed is the caller's. */
+export declare const parsedEmail: (mail: ParsedMail, item: Listed, header: Record<string, string | boolean>, address: string) => Omit<EmailInput, "mailboxes">;

package/dist/mail/email-input.js

@@ -0,0 +1,16 @@
+import { addressOf } from "./attachments.js";
+/** What one read email stores of itself, whichever run read it; where it is filed is the caller's. */
+export const parsedEmail = (mail, item, header, address) => ({
+    externalId: item.messageId,
+    subject: mail.subject,
+    from: mail.from === null ? null : addressOf(mail.from),
+    to: mail.to.map(addressOf),
+    cc: mail.cc.map(addressOf),
+    bcc: mail.bcc.map(addressOf),
+    sentAt: null,
+    receivedAt: Date.parse(item.receivedAt),
+    bodyText: mail.text || null,
+    size: item.size ?? null,
+    ...(Object.keys(header).length ? { headers: header } : {}),
+    outgoing: mail.from === null ? null : mail.from.email === address,
+});

package/dist/mail/ids.d.ts

@@ -0,0 +1,20 @@
+export interface MailIdsInput {
+    /** As the server's envelope gives it; read from `head` when absent. */
+    messageId?: string | undefined;
+    /** Header text holding at least References and In-Reply-To. */
+    head: string;
+    folder: string;
+    validity: string;
+    uid: string;
+}
+/**
+ * The ids of an email on any server but Gmail, whose X-GM-MSGID and X-GM-THRID are used as they are. OBJECTID's
+ * EMAILID is not used: mail and memo must give one email one id, and a server that turns OBJECTID on later must not
+ * store its mail again. The Message-ID is the identity; without one, the UID, which means nothing without
+ * UIDVALIDITY. The thread is the first Message-ID of References, the thread's first email (RFC 5322 §3.6.4), else
+ * In-Reply-To's parent, so a server without thread ids (Yandex, Mail.ru) still keeps a conversation together.
+ */
+export declare const mailIds: ({ messageId, head, folder, validity, uid }: MailIdsInput) => {
+    messageId: string;
+    threadId: string;
+};

package/dist/mail/ids.js

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+import { field, unfold } from "./headers.js";
+const digest = (id) => `imap:${createHash("sha256").update(id).digest("hex")}`;
+const firstId = (value) => /<[^<>\s]+>/.exec(value ?? "")?.[0];
+/**
+ * The ids of an email on any server but Gmail, whose X-GM-MSGID and X-GM-THRID are used as they are. OBJECTID's
+ * EMAILID is not used: mail and memo must give one email one id, and a server that turns OBJECTID on later must not
+ * store its mail again. The Message-ID is the identity; without one, the UID, which means nothing without
+ * UIDVALIDITY. The thread is the first Message-ID of References, the thread's first email (RFC 5322 §3.6.4), else
+ * In-Reply-To's parent, so a server without thread ids (Yandex, Mail.ru) still keeps a conversation together.
+ */
+export const mailIds = ({ messageId, head, folder, validity, uid }) => {
+    const unfolded = unfold(head);
+    const identity = (messageId ?? field(unfolded, "message-id"))?.trim() || `uid:${folder}:${validity}:${uid}`;
+    const root = firstId(field(unfolded, "references")) ?? firstId(field(unfolded, "in-reply-to"));
+    return { messageId: digest(identity), threadId: digest(root ?? identity) };
+};

package/dist/mail/index.d.ts

@@ -3,7 +3,8 @@ export { factsOf } from "./facts.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 export { dropMissing, type Gone, tooManyGone } from "./gone.js";
 export { type AuthVerdicts, HEADER_FIELDS, headersOf, type MailHeaders, mailHeadersOf } from "./headers.js";
-export { decodeMailboxName, labelName, systemLabel } from "./labels.js";
+export { type MailIdsInput, mailIds } from "./ids.js";
+export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
 export { type Address, htmlToText, looksLikeHtml, MAX_BODY_CHARS, type ParsedMail, parseMail, } from "./parse.js";
 export { PRESET_NAMES, PRESETS, type PresetName, presetMatches } from "./presets.js";
 export { domainsToAge, groupKey, type Probe, type ProbeGroup, probeMail, SUGGEST_RULE } from "./probe.js";
@@ -11,11 +12,13 @@ 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";
+export { type MailRuleSet, storedMailRule, storedMailRuleSet, storedMailRules } from "./rule-stored.js";
 export { mapProposedTags, ruleTagger, settleRuleTags, type TagOutcome } from "./rule-tags.js";
 export { conditionKeys, decide, describeMatch, ENVELOPE, envelopeBox, envelopeBoxOf, type MailAction, type MailFacts, type MailRule, type MailRuleMatch, matches, sameMatch, tagsOf, } from "./rules.js";
 export { type DomainAge, FRAUD_SIGNALS, FREE_MAIL, registrableOf, SCORE_RULE, type Scored, type Signal, scoreGroup, WEIGHTS, } from "./score.js";
 export { DEMOTE_AT, type DomainAges, demotedSenders, type LookupResult, SCORE_VERSION, scoreSenders, } from "./sender-scores.js";
+export { type MailCriteria, mailCriteriaOf, narrows } from "./server-query.js";
+export { type MailServerAccess, type MailServerRequest, searchMailServer } from "./server-search.js";
 export type { Listed, MailSource, Quick, Searched } from "./source.js";
 export { listedOf, type StoredMail } from "./stored.js";
 export { MAX_ATTACHMENT_CHARS, type MailAccount, type MailIndexed, type MailSyncOptions, type MailSyncResult, RETRYABLE_ATTACHMENTS, syncMail, } from "./sync.js";

package/dist/mail/index.js

@@ -3,7 +3,8 @@ export { factsOf } from "./facts.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 export { dropMissing, tooManyGone } from "./gone.js";
 export { HEADER_FIELDS, headersOf, mailHeadersOf } from "./headers.js";
-export { decodeMailboxName, labelName, systemLabel } from "./labels.js";
+export { mailIds } from "./ids.js";
+export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
 export { htmlToText, looksLikeHtml, MAX_BODY_CHARS, parseMail, } from "./parse.js";
 export { PRESET_NAMES, PRESETS, presetMatches } from "./presets.js";
 export { domainsToAge, groupKey, probeMail, SUGGEST_RULE } from "./probe.js";
@@ -11,10 +12,12 @@ 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";
+export { storedMailRule, storedMailRuleSet, storedMailRules } from "./rule-stored.js";
 export { mapProposedTags, ruleTagger, settleRuleTags } from "./rule-tags.js";
 export { conditionKeys, decide, describeMatch, ENVELOPE, envelopeBox, envelopeBoxOf, matches, sameMatch, tagsOf, } from "./rules.js";
 export { FRAUD_SIGNALS, FREE_MAIL, registrableOf, SCORE_RULE, scoreGroup, WEIGHTS, } from "./score.js";
 export { DEMOTE_AT, demotedSenders, SCORE_VERSION, scoreSenders, } from "./sender-scores.js";
+export { mailCriteriaOf, narrows } from "./server-query.js";
+export { searchMailServer } from "./server-search.js";
 export { listedOf } from "./stored.js";
 export { MAX_ATTACHMENT_CHARS, RETRYABLE_ATTACHMENTS, syncMail, } from "./sync.js";

package/dist/mail/labels.d.ts

@@ -1,5 +1,10 @@
 /** IMAP's modified UTF-7 (RFC 3501 §5.1.3): `&` opens base64 of UTF-16BE, `,` stands for `/`, `-` closes. */
 export declare const decodeMailboxName: (name: string) => string;
 export declare const systemLabel: (name: string) => string;
-/** A label as people read it: `\\Important` and `Important` are one label, and names are decoded. */
+/**
+ * A label as people read it, from a name already decoded (imapflow decodes X-GM-LABELS): `\\Important` and
+ * `Important` are one label. Decoding twice would turn `R&D-team` into `Rteam`.
+ */
+export declare const decodedLabelName: (name: string) => string;
+/** The same from X-GM-LABELS as the server sends it, in modified UTF-7. */
 export declare const labelName: (raw: string) => string;

package/dist/mail/labels.js

@@ -20,8 +20,13 @@ export const decodeMailboxName = (name) => name.replace(/&([^-]*)-/g, (_, run) =
     return text;
 });
 export const systemLabel = (name) => SYSTEM_LABELS[name.toLowerCase()] ?? name;
-/** A label as people read it: `\\Important` and `Important` are one label, and names are decoded. */
-export const labelName = (raw) => {
-    const system = raw.startsWith("\\") ? raw.slice(1) : raw;
-    return SYSTEM_LABELS[system.toLowerCase()] ?? decodeMailboxName(system);
+/**
+ * A label as people read it, from a name already decoded (imapflow decodes X-GM-LABELS): `\\Important` and
+ * `Important` are one label. Decoding twice would turn `R&D-team` into `Rteam`.
+ */
+export const decodedLabelName = (name) => {
+    const system = name.startsWith("\\") ? name.slice(1) : name;
+    return SYSTEM_LABELS[system.toLowerCase()] ?? system;
 };
+/** The same from X-GM-LABELS as the server sends it, in modified UTF-7. */
+export const labelName = (raw) => decodedLabelName(decodeMailboxName(raw));

package/dist/mail/read.d.ts

@@ -16,12 +16,17 @@ export interface MailSearch {
     newest?: boolean;
     /** Leave mail from suspicious senders where the words put it, instead of after the rest. */
     plainOrder?: boolean;
+    /** Only these emails, by thread and email id: `--backend server` reads what the server returned. */
+    only?: (AccountKey & {
+        chatId: string;
+        id: string;
+    })[];
 }
 /**
  * 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>;
+export declare const searchMail: (store: MessageStore, runAs: AccountKey, { text, limit, offset, accounts, mailAccount, exact, timezone, newest, plainOrder, only }: 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 & {

package/dist/mail/read.js

@@ -12,7 +12,7 @@ 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 = {}) => {
+export const searchMail = async (store, runAs, { text, limit, offset = 0, accounts, mailAccount, exact, timezone, newest, plainOrder, only }, saved = {}) => {
     const lower = !plainOrder && !newest;
     const request = {
         text,
@@ -22,6 +22,7 @@ export const searchMail = async (store, runAs, { text, limit, offset = 0, accoun
         ...(exact ? { exact: true } : {}),
         ...(timezone === undefined ? {} : { timezone }),
         ...(newest ? { newest: true } : {}),
+        ...(only === undefined ? {} : { only }),
     };
     if (!lower)
         return searchStore(store, runAs, { ...request, limit, offset }, saved);

package/dist/mail/rule-stored.d.ts

@@ -3,7 +3,21 @@ import type { MessageStore, MailRule as StoredRule } from "../store/index.js";
 import type { MailRule } from "./rules.js";
 /** A stored rule as the sync reads it; `undefined` for one this build cannot read, so it is left to the build that can. */
 export declare const storedMailRule: (stored: StoredRule) => MailRule | undefined;
+export interface MailRuleSet {
+    rules: MailRule[];
+    /**
+     * Stored rules this build cannot read, each with what it does not know. The sync leaves them out, and a build that
+     * reads them decides mail differently, so a sync reports them rather than drop them silently.
+     */
+    unreadable: {
+        id: number;
+        why: string;
+    }[];
+}
 /** One account's rules from the store, for `account.rules` of the sync; none when the store has not seen the account. */
+export declare const storedMailRuleSet: (store: MessageStore, account: {
+    address: string;
+}, query?: QueryAst) => Promise<MailRuleSet>;
 export declare const storedMailRules: (store: MessageStore, account: {
     address: string;
 }, query?: QueryAst) => Promise<MailRule[]>;

package/dist/mail/rule-stored.js

@@ -17,15 +17,24 @@ const KINDS = {
     score_at_least: "number",
     preset: "string",
 };
+/** Why this build cannot read a stored rule, or undefined when it can. */
+const unreadable = (stored) => {
+    if (ACTION_OF[String(stored.actions.store)] === undefined)
+        return `action ${String(stored.actions.store)}`;
+    const entries = Object.entries(stored.conditions);
+    if (entries.length === 0)
+        return "no condition";
+    const unknown = entries.find(([key, value]) => !(key in KINDS) ||
+        typeof value !== KINDS[key] ||
+        (key === "preset" && !PRESET_NAMES.includes(value)));
+    return unknown && `condition ${unknown[0]}`;
+};
 /** A stored rule as the sync reads it; `undefined` for one this build cannot read, so it is left to the build that can. */
 export const storedMailRule = (stored) => {
+    if (unreadable(stored) !== undefined)
+        return undefined;
     const action = ACTION_OF[String(stored.actions.store)];
     const entries = Object.entries(stored.conditions);
-    const known = entries.every(([key, value]) => key in KINDS &&
-        typeof value === KINDS[key] &&
-        !(key === "preset" && !PRESET_NAMES.includes(value)));
-    if (action === undefined || !known || entries.length === 0)
-        return undefined;
     const tags = Array.isArray(stored.actions.tags) ? stored.actions.tags.filter((tag) => typeof tag === "string") : [];
     const skipped = stored.actions.tags_skipped;
     const tagsSkipped = skipped !== null && typeof skipped === "object" && !Array.isArray(skipped)
@@ -44,14 +53,25 @@ export const storedMailRule = (stored) => {
     };
 };
 /** One account's rules from the store, for `account.rules` of the sync; none when the store has not seen the account. */
-export const storedMailRules = async (store, account, query) => {
+export const storedMailRuleSet = async (store, account, query) => {
+    let stored;
     try {
         const { id } = await store.accounts.storedAccount({ provider: "email", account: account.address.toLowerCase() });
-        return (await store.mail.rules.list(id, query)).flatMap((stored) => storedMailRule(stored) ?? []);
+        stored = await store.mail.rules.list(id, query);
     }
     catch (error) {
         if (error instanceof CliError && error.code === "not_found")
-            return [];
+            return { rules: [], unreadable: [] };
         throw error;
     }
+    const set = { rules: [], unreadable: [] };
+    for (const one of stored) {
+        const why = unreadable(one);
+        if (why === undefined)
+            set.rules.push(storedMailRule(one));
+        else
+            set.unreadable.push({ id: one.id, why });
+    }
+    return set;
 };
+export const storedMailRules = async (store, account, query) => (await storedMailRuleSet(store, account, query)).rules;

package/dist/mail/server-query.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a mail server is asked, in no server's syntax: every part must hold. Each list is AND-ed; a part the server
+ * cannot read is left out, which only widens the candidates, since the strict query on the store decides.
+ */
+export interface MailCriteria {
+    /** Words and phrases anywhere in the email. */
+    words: string[];
+    from: string[];
+    to: string[];
+    cc: string[];
+    subject: string[];
+    body: string[];
+    /** Received at or after this time, in ms. */
+    since?: number;
+    /** Received before this time, in ms. */
+    before?: number;
+    seen?: boolean;
+    flagged?: boolean;
+}
+/** Whether the criteria narrow at all: a server asked for everything would only return the newest mail. */
+export declare const narrows: (criteria: MailCriteria) => boolean;
+/**
+ * The shared query as mail server searches, one per top-level OR branch. Negations, patterns, `has:`, `list:`,
+ * `mailbox:` and the rest stay with the strict query on the store. A branch that narrows nothing is not sent, since a
+ * server asked for everything would only answer the newest mail; `partial` says one was left out.
+ */
+export declare const mailCriteriaOf: (text: string, { exact, timezone }?: {
+    exact?: boolean;
+    timezone?: string;
+}) => {
+    branches: MailCriteria[];
+    partial: boolean;
+};

package/dist/mail/server-query.js

@@ -0,0 +1,92 @@
+import { dateRange, parseLucene, timezoneOf } from "@wirecat/cli-base/query";
+import { validateFields } from "../search/lucene/registry.js";
+import { MESSAGE_PARSING } from "../search/lucene/types.js";
+const DAY = 86_400_000;
+const empty = () => ({ words: [], from: [], to: [], cc: [], subject: [], body: [] });
+/** Whether the criteria narrow at all: a server asked for everything would only return the newest mail. */
+export const narrows = (criteria) => criteria.words.length +
+    criteria.from.length +
+    criteria.to.length +
+    criteria.cc.length +
+    criteria.subject.length +
+    criteria.body.length >
+    0 ||
+    criteria.since !== undefined ||
+    criteria.before !== undefined ||
+    criteria.seen !== undefined ||
+    criteria.flagged !== undefined;
+const merge = (one, other) => {
+    if (one.seen !== undefined && other.seen !== undefined && one.seen !== other.seen)
+        return undefined;
+    if (one.flagged !== undefined && other.flagged !== undefined && one.flagged !== other.flagged)
+        return undefined;
+    const since = Math.max(one.since ?? -Infinity, other.since ?? -Infinity);
+    const before = Math.min(one.before ?? Infinity, other.before ?? Infinity);
+    const seen = one.seen ?? other.seen;
+    const flagged = one.flagged ?? other.flagged;
+    return {
+        words: [...one.words, ...other.words],
+        from: [...one.from, ...other.from],
+        to: [...one.to, ...other.to],
+        cc: [...one.cc, ...other.cc],
+        subject: [...one.subject, ...other.subject],
+        body: [...one.body, ...other.body],
+        ...(Number.isFinite(since) ? { since } : {}),
+        ...(Number.isFinite(before) ? { before } : {}),
+        ...(seen === undefined ? {} : { seen }),
+        ...(flagged === undefined ? {} : { flagged }),
+    };
+};
+const TEXT_FIELDS = { from: "from", to: "to", cc: "cc", subject: "subject", body: "body" };
+const leafOf = (node, timezone) => {
+    const criteria = empty();
+    const plain = node.operator === "term" || node.operator === "phrase";
+    if ((node.field === "text" || node.field === "exact") && plain && node.value !== "")
+        return { ...criteria, words: [node.value] };
+    const field = TEXT_FIELDS[node.field];
+    // `from:me` is the mailbox's own address, which the store knows and the server's FROM does not.
+    if (field && plain && node.value !== "" && !(field === "from" && node.value.toLowerCase() === "me"))
+        return { ...criteria, [field]: [node.value] };
+    if (node.field === "is" && node.operator === "term") {
+        const state = node.value.toLowerCase();
+        if (state === "unread")
+            return { ...criteria, seen: false };
+        if (state === "read")
+            return { ...criteria, seen: true };
+        if (state === "starred")
+            return { ...criteria, flagged: true };
+    }
+    if (node.field === "date") {
+        const range = dateRange(node.value, node.operator === "range" ? (node.upper ?? "*") : node.value, node.operator === "range" ? node.lower_inclusive === true : true, node.operator === "range" ? node.upper_inclusive === true : true, timezone, node.span);
+        // A server reads whole days in its own zone: a day more each side, and the store cuts to the exact moment.
+        return {
+            ...criteria,
+            ...(range.lower === undefined ? {} : { since: range.lower - DAY }),
+            ...(range.upper === undefined ? {} : { before: range.upper + DAY }),
+        };
+    }
+    return criteria;
+};
+const branchesOf = (node, timezone) => {
+    if (node.kind === "predicate")
+        return [leafOf(node, timezone)];
+    const must = node.clauses.filter(({ occur }) => occur === "must");
+    if (must.length)
+        return must.reduce((product, { node }) => product.flatMap((one) => branchesOf(node, timezone).flatMap((other) => merge(one, other) ?? [])), [empty()]);
+    const should = node.clauses.filter(({ occur }) => occur === "should");
+    return should.length ? should.flatMap(({ node }) => branchesOf(node, timezone)) : [empty()];
+};
+/**
+ * The shared query as mail server searches, one per top-level OR branch. Negations, patterns, `has:`, `list:`,
+ * `mailbox:` and the rest stay with the strict query on the store. A branch that narrows nothing is not sent, since a
+ * server asked for everything would only answer the newest mail; `partial` says one was left out.
+ */
+export const mailCriteriaOf = (text, { exact, timezone } = {}) => {
+    const ast = validateFields(parseLucene(text, { ...MESSAGE_PARSING, defaultField: exact ? "exact" : "text" }));
+    const all = branchesOf(ast.root, timezoneOf(timezone));
+    const sent = all.filter(narrows);
+    return {
+        branches: [...new Map(sent.map((branch) => [JSON.stringify(branch), branch])).values()],
+        partial: sent.length < all.length,
+    };
+};

package/dist/mail/server-search.d.ts

@@ -0,0 +1,33 @@
+import { type Level, type PermissionKey } from "../sends/permissions.js";
+import { type Backend, type ServerStep } from "../services/server-search.js";
+import type { AccountKey, MessageStore } from "../store/index.js";
+import type { MailSource } from "./source.js";
+/** What a run lets the server search do, read from the profile before anything is opened. */
+export interface MailServerAccess {
+    offline: boolean;
+    permissions: Readonly<Record<PermissionKey, Level>>;
+    defaults?: Readonly<Record<PermissionKey, Level>>;
+    /** `<PREFIX>_READ_ONLY`: the search writes what the server finds into the store, so it stays the archive's. */
+    readOnly?: boolean;
+    /** The mailbox and the folders a search reads, closed after the search. */
+    open: () => Promise<{
+        source: MailSource;
+        folders: string[];
+        close?: () => Promise<void>;
+    }>;
+}
+export interface MailServerRequest {
+    text: string;
+    exact?: boolean;
+    timezone?: string;
+    backend?: Backend;
+    timeMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Asks the mailbox's server for candidates and saves the new ones, so the strict query that runs next on the store
+ * sees them: the messenger rule (cli-core docs/search/query-language.md, "Поиск на сервере мессенджера"). Each source
+ * key is `sourceKey(thread, email)`. Mail a skip or envelope rule keeps out of the store is not saved. Nothing moves the
+ * sync's saved position or coverage, and a reply after the time bound is dropped unsaved.
+ */
+export declare const searchMailServer: (store: MessageStore, mailbox: AccountKey, access: MailServerAccess, request: MailServerRequest) => Promise<ServerStep | undefined>;

package/dist/mail/server-search.js

@@ -0,0 +1,215 @@
+import { CliError } from "@wirecat/cli-base";
+import { importEngine } from "../attachments/extract.js";
+import { levelFor } from "../sends/permissions.js";
+import { DEFAULT_BACKEND, SERVER_BOUNDS, SERVER_SEARCH_KEY, sourceKey, } from "../services/server-search.js";
+import { MAX_ATTACHMENT_CHARS, readAttachments } from "./attachments.js";
+import { bulkBox } from "./bulk.js";
+import { parsedEmail } from "./email-input.js";
+import { factsOf } from "./facts.js";
+import { mailHeadersOf } from "./headers.js";
+import { parseMail } from "./parse.js";
+import { storedMailRules } from "./rule-stored.js";
+import { decide } from "./rules.js";
+import { mailCriteriaOf } from "./server-query.js";
+const refusal = {
+    unsupported: "this mailbox's server cannot be searched — use --backend archive",
+    offline: "--backend server needs the network — not with --offline",
+    not_allowed: "the server search is not allowed by this profile",
+    no_words: "--backend server needs words, people, a subject, a date or a state to send to the server",
+};
+const BOUND = Symbol("bound");
+/** The newest first: a server's UIDs grow as mail arrives in the folder. */
+const newest = (uids, count) => [...uids].sort((one, other) => Number(other) - Number(one)).slice(0, count);
+/**
+ * Asks the mailbox's server for candidates and saves the new ones, so the strict query that runs next on the store
+ * sees them: the messenger rule (cli-core docs/search/query-language.md, "Поиск на сервере мессенджера"). Each source
+ * key is `sourceKey(thread, email)`. Mail a skip or envelope rule keeps out of the store is not saved. Nothing moves the
+ * sync's saved position or coverage, and a reply after the time bound is dropped unsaved.
+ */
+export const searchMailServer = async (store, mailbox, access, request) => {
+    const backend = request.backend ?? DEFAULT_BACKEND;
+    if (backend === "archive")
+        return undefined;
+    const quiet = request.backend === undefined;
+    const timeMs = request.timeMs ?? SERVER_BOUNDS.timeMs;
+    if (!Number.isSafeInteger(timeMs) || timeMs < 1 || timeMs > 60_000)
+        throw new CliError("validation_error", "the server time takes a whole number of milliseconds from 1 to 60000");
+    const report = { backend, skipped: null, calls: 0, returned: 0, new: 0, failed: [], complete: true };
+    const sources = new Map();
+    const skip = (reason) => {
+        if (quiet)
+            return undefined;
+        if (backend === "server")
+            throw new CliError(reason === "not_allowed" ? "permission_error" : "validation_error", refusal[reason], {
+                reason,
+            });
+        return { report: { ...report, skipped: reason, complete: false }, sources };
+    };
+    if (access.offline)
+        return skip("offline");
+    // As tg's: `ask` and `readonly` give the archive's answer, since nobody is asked before a search.
+    if (access.readOnly || levelFor(access.permissions, SERVER_SEARCH_KEY, access.defaults).level !== "allow")
+        return skip("not_allowed");
+    const { branches, partial } = mailCriteriaOf(request.text, {
+        ...(request.exact ? { exact: true } : {}),
+        ...(request.timezone === undefined ? {} : { timezone: request.timezone }),
+    });
+    if (!branches.length)
+        return skip("no_words");
+    if (partial)
+        report.complete = false;
+    const pending = new Set();
+    const listed = [];
+    const validities = new Map();
+    let open = true;
+    const fail = (call, reason) => {
+        report.complete = false;
+        report.failed.push({ chat: call?.folder ?? null, reason });
+    };
+    const accountId = await store.accounts.saveAccount(mailbox, { name: mailbox.account });
+    const fresh = [];
+    let raws;
+    let opening;
+    let openFailure;
+    let unsupported = false;
+    // Opening lists the folders, a call to the server, so it runs inside the time bound too.
+    const run = async () => {
+        opening = access.open();
+        const { source, folders } = await opening.catch((error) => {
+            openFailure = error;
+            throw error;
+        });
+        const query = source.query?.bind(source);
+        if (!query) {
+            unsupported = true;
+            return;
+        }
+        const asked = branches.flatMap((criteria) => folders.map((folder) => ({ criteria, folder })));
+        if (asked.length > SERVER_BOUNDS.maxCalls)
+            report.complete = false;
+        const calls = asked.slice(0, SERVER_BOUNDS.maxCalls);
+        for (const call of calls)
+            pending.add(call);
+        await Promise.all(calls.map(async (call) => {
+            report.calls += 1;
+            try {
+                const found = await query(call.criteria, call.folder);
+                const uids = newest(found.uids, SERVER_BOUNDS.perCall);
+                if (uids.length < found.uids.length)
+                    report.complete = false;
+                const items = uids.length
+                    ? await source.list(new Date(0), call.folder, { headers: true, searched: { ...found, uids } })
+                    : [];
+                if (!open)
+                    return;
+                pending.delete(call);
+                listed.push(...items);
+                if (found.validity)
+                    for (const item of items)
+                        validities.set(item, found.validity);
+            }
+            catch (error) {
+                if (!open)
+                    return;
+                pending.delete(call);
+                fail(call, error instanceof CliError && error.code === "rate_limited" ? "rate_limited" : "search_failed");
+            }
+        }));
+        if (!open)
+            return;
+        const unique = [...new Map(listed.map((item) => [item.messageId, item])).values()];
+        const rules = await storedMailRules(store, { address: mailbox.account });
+        const facts = factsOf(unique, rules);
+        for (const item of unique) {
+            const held = (await store.mail.email(accountId, item.messageId)) !== null;
+            const rule = decide(rules, facts(item));
+            if (!held && (rule?.action === "skip" || rule?.action === "envelope"))
+                continue;
+            report.returned += 1;
+            sources.set(sourceKey(item.threadId, item.messageId), held ? "both" : "server");
+            if (!held)
+                fresh.push(item);
+        }
+        if (fresh.length)
+            raws = await source.fetchRaw(fresh);
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeMs);
+    const stop = request.signal ? AbortSignal.any([request.signal, controller.signal]) : controller.signal;
+    const bound = new Promise((resolve) => {
+        if (stop.aborted)
+            resolve(BOUND);
+        stop.addEventListener("abort", () => resolve(BOUND), { once: true });
+    });
+    let outcome;
+    try {
+        outcome = await Promise.race([
+            run().then(() => "done", () => "failed"),
+            bound,
+        ]);
+    }
+    finally {
+        open = false;
+        clearTimeout(timer);
+        // A late open is closed too, once it lands, so no connection outlives the answer.
+        void opening?.then((one) => one.close?.(), () => undefined);
+    }
+    if (openFailure !== undefined && backend === "server")
+        throw openFailure;
+    if (unsupported)
+        return skip("unsupported");
+    for (const call of pending)
+        fail(call, outcome === "failed" ? "search_failed" : "time_or_abort_bound");
+    if (outcome !== "done" || (fresh.length > 0 && raws === undefined)) {
+        // What was found but not read in time is the archive's to answer: none of it is claimed as the server's.
+        if (pending.size === 0)
+            fail(null, outcome === "failed" ? "search_failed" : "time_or_abort_bound");
+        for (const item of fresh)
+            sources.delete(sourceKey(item.threadId, item.messageId));
+        report.returned = sources.size;
+        return { report, sources };
+    }
+    const now = Date.now();
+    const inputs = [];
+    for (const [index, item] of fresh.entries()) {
+        const raw = raws?.[index];
+        try {
+            if (raw === undefined || raw instanceof Error)
+                throw raw ?? new Error("not read");
+            const mail = await parseMail(raw);
+            const files = await readAttachments(mail, item.messageId, { loadEngine: importEngine, maxAttachmentChars: MAX_ATTACHMENT_CHARS, at: now }, []);
+            const folder = item.folder;
+            const validity = validities.get(item);
+            inputs.push({
+                accountId,
+                externalId: item.threadId,
+                now,
+                emails: [
+                    {
+                        ...parsedEmail(mail, item, mailHeadersOf(raw), mailbox.account),
+                        mailboxes: [
+                            { externalId: folder, name: folder, kind: null },
+                            ...(item.labels ?? []).map((name) => ({ externalId: `label:${name}`, name, kind: "label" })),
+                            ...(item.headers?.bulk ? [bulkBox] : []),
+                        ],
+                        ...(validity === undefined
+                            ? {}
+                            : { locations: [{ folder, uidvalidity: validity, uid: Number(item.uid) }] }),
+                        ...(item.seen === undefined ? {} : { read: item.seen }),
+                        ...(item.flagged === undefined ? {} : { flagged: item.flagged }),
+                        attachments: files,
+                    },
+                ],
+            });
+        }
+        catch {
+            sources.delete(sourceKey(item.threadId, item.messageId));
+            report.complete = false;
+        }
+    }
+    if (inputs.length)
+        await store.mail.saveThreads(inputs);
+    report.new = inputs.length;
+    report.returned = sources.size;
+    return { report, sources };
+};

package/dist/mail/source.d.ts

@@ -1,5 +1,6 @@
 import type { MailHeaders } from "./headers.js";
 import type { FileStamp } from "./resume.js";
+import type { MailCriteria } from "./server-query.js";
 export interface Listed {
     uid: string;
     /** Gmail's own ids: the same in every folder, and they survive a UID reset. */
@@ -62,6 +63,11 @@ export interface MailSource {
         messageId: string;
         threadId: string;
     };
+    /**
+     * The UIDs of `folder` the server's own search finds for `criteria`, and its UIDVALIDITY; `list` given them reads
+     * them. Absent where nothing can be asked: a file. A server reads only the parts its syntax has.
+     */
+    query?(criteria: MailCriteria, folder: string): Promise<Searched>;
     /** A file's size and modification time, so an unchanged file read to the end is not read again. */
     stamp?(): Promise<FileStamp>;
     /**

package/dist/mail/sync.js

@@ -2,8 +2,9 @@ import { setTimeout } from "node:timers/promises";
 import { CliError } from "@wirecat/cli-base";
 import { importEngine } from "../attachments/extract.js";
 import { isBusy } from "../store/sqlite/transaction.js";
-import { addressOf, FETCH_CHUNK, MAX_ATTACHMENT_CHARS, readAttachments } from "./attachments.js";
+import { FETCH_CHUNK, MAX_ATTACHMENT_CHARS, readAttachments } from "./attachments.js";
 import { BULK, bulkBox } from "./bulk.js";
+import { parsedEmail } from "./email-input.js";
 import { factsOf } from "./facts.js";
 import { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 import { dropMissing, tooManyGone } from "./gone.js";
@@ -717,18 +718,7 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                 now: startedAt,
                 emails: [
                     {
-                        externalId: item.messageId,
-                        subject: mail.subject,
-                        from: mail.from === null ? null : addressOf(mail.from),
-                        to: mail.to.map(addressOf),
-                        cc: mail.cc.map(addressOf),
-                        bcc: mail.bcc.map(addressOf),
-                        sentAt: null,
-                        receivedAt: Date.parse(item.receivedAt),
-                        bodyText: mail.text || null,
-                        size: item.size ?? null,
-                        ...(Object.keys(header).length ? { headers: header } : {}),
-                        outgoing: mail.from === null ? null : mail.from.email === key.account,
+                        ...parsedEmail(mail, item, header, key.account),
                         mailboxes: inMailboxes(item),
                         ...locationOf(item),
                         ...flagsOf(item),

package/dist/mail/testing/fake.d.ts

@@ -1,4 +1,5 @@
 import type { FileStamp } from "../resume.js";
+import type { MailCriteria } from "../server-query.js";
 import type { MailSource } from "../source.js";
 export type FakePerson = [name: string | null, address: string];
 /** One message of a fake Gmail-like mailbox: its ids, envelope and the parts `rawOf` writes as RFC 5322. */
@@ -61,6 +62,11 @@ export interface FakeMailbox {
     fetchBatch?: number;
     /** What the source was asked: the UIDs of each listing, and `msgid:<id>` for each `find`. */
     asked?: string[];
+    /** Each server search `query` was given, with its folder, so a test sees what was sent. */
+    queried?: {
+        criteria: MailCriteria;
+        folder: string;
+    }[];
 }
 /** The RFC 5322 bytes of a fake message, CRLF line ends, the body and attachment in base64. */
 export declare const rawOf: (m: FakeMail) => Uint8Array;

package/dist/mail/testing/fake.js

@@ -1,6 +1,23 @@
 import { CliError } from "@wirecat/cli-base";
 import { GMAIL_ALL_MAIL } from "../folders.js";
 import { headersOf } from "../headers.js";
+/** As IMAP SEARCH matches: a case-blind substring of the field, every part required. */
+const matches = (m, criteria) => {
+    const has = (field, value) => field.toLowerCase().includes(value.toLowerCase());
+    const people = (list) => list.map(person).join(", ");
+    const text = `${m.subject}\n${m.text ?? m.html ?? ""}`;
+    const at = Date.parse(m.receivedAt);
+    return (criteria.words.every((word) => has(`${people([m.from])}\n${people(m.to)}\n${text}`, word)) &&
+        criteria.from.every((value) => has(person(m.from), value)) &&
+        criteria.to.every((value) => has(people(m.to), value)) &&
+        criteria.cc.every((value) => has(people(m.cc ?? []), value)) &&
+        criteria.subject.every((value) => has(m.subject, value)) &&
+        criteria.body.every((value) => has(m.text ?? m.html ?? "", value)) &&
+        (criteria.since === undefined || at >= criteria.since) &&
+        (criteria.before === undefined || at < criteria.before) &&
+        (criteria.seen === undefined || (m.seen ?? false) === criteria.seen) &&
+        (criteria.flagged === undefined || (m.flagged ?? false) === criteria.flagged));
+};
 const TRASH = "[Gmail]/Bin";
 const person = ([name, address]) => (name ? `"${name}" <${address}>` : address);
 /** The RFC 5322 bytes of a fake message, CRLF line ends, the body and attachment in base64. */
@@ -116,6 +133,18 @@ export const fakeMailSource = (mailbox) => {
                 },
             }
             : {}),
+        query: async (criteria, folder) => {
+            count("search");
+            if (mailbox.searchFails)
+                throw failure(mailbox.searchFails);
+            mailbox.queried?.push({ criteria, folder });
+            return {
+                validity: String(mailbox.validity ?? 12),
+                uids: inFolder(folder)
+                    .filter((m) => matches(m, criteria))
+                    .map((m) => m.uid),
+            };
+        },
         find: async (messageIds, folder, options) => {
             for (const id of messageIds)
                 mailbox.asked?.push(`msgid:${id}`);

package/dist/ports/app.d.ts

@@ -25,6 +25,8 @@ export interface AppIdentity {
      * tg, max and wa print what they always did.
      */
     messenger?: boolean;
+    /** A CLI that is not a messenger yet sends to people, as mail does: it keeps the hourly limit, `sends_per_hour`. */
+    sends?: true;
     /**
      * How long one request to the provider usually takes, in ms: a sync's budget is the deadline, less its margin,
      * divided by it (`requestsFor`). 2 s when unset.

package/dist/store/sqlite/lucene.js

@@ -71,8 +71,8 @@ const compileQuery = (context, execution, boundedAttachments = false) => {
     const { database } = context;
     const corpus = execution.corpus === "mail" ? MAIL : MESSAGES;
     const mail = corpus === MAIL;
-    if (mail && (execution.only || execution.conversationIds || execution.conversationSince !== undefined))
-        throw new CliError("validation_error", "mail has no server search or conversations");
+    if (mail && (execution.conversationIds || execution.conversationSince !== undefined))
+        throw new CliError("validation_error", "mail has no conversations to search within");
     const started = context.now();
     const budget = { work: 0 };
     let states = 0, expansions = 0;
@@ -216,11 +216,11 @@ const compileQuery = (context, execution, boundedAttachments = false) => {
         where = combine([
             where,
             {
-                sql: `m.id IN (SELECT picked.id FROM json_each(?) j CROSS JOIN accounts allowed CROSS JOIN chats scoped CROSS JOIN messages picked
+                sql: `m.id IN (SELECT picked.id FROM json_each(?) j CROSS JOIN accounts allowed CROSS JOIN ${mail ? "email_threads" : "chats"} scoped CROSS JOIN ${mail ? "emails" : "messages"} picked
             WHERE (${execution.accounts.map(() => "(allowed.provider=? AND allowed.external_id=?)").join(" OR ") || "0"})
               AND allowed.provider=json_extract(j.value,'$.provider') AND allowed.external_id=json_extract(j.value,'$.account')
               AND scoped.account_id=allowed.id AND scoped.external_id=json_extract(j.value,'$.chatId')
-              AND picked.chat_id=scoped.id AND picked.external_id=json_extract(j.value,'$.id'))`,
+              AND picked.${mail ? "email_thread_id" : "chat_id"}=scoped.id AND picked.external_id=json_extract(j.value,'$.id'))`,
                 params: [JSON.stringify(execution.only), ...execution.accounts.flatMap((key) => [key.provider, key.account])],
                 exact: true,
             },

package/package.json

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