@wirecat/cli-core 0.524.0 → 0.525.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.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/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,15 +5,18 @@ 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";
 const DEFAULT_LIMIT = 20;
 const MAX_LIMIT = 100;
@@ -41,9 +44,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 +83,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 +100,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 +162,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);

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/index.d.ts

@@ -16,6 +16,8 @@ export { mapProposedTags, ruleTagger, settleRuleTags, type TagOutcome } from "./
 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

@@ -16,5 +16,7 @@ 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/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/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.525.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",