@wirecat/cli-core 0.496.0 → 0.498.0

package/dist/calendar/cli/index.js

@@ -1,9 +1,10 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate, sharedCommand } from "@wirecat/cli-base/commands";
 import { timezoneOf } from "@wirecat/cli-base/query";
-import { Argument, InvalidArgumentError } from "commander";
+import { Argument, InvalidArgumentError, Option } from "commander";
 import { environmentOf, runBudgetOf } from "../../cli/context.js";
 import { honoursDryRun } from "../../cli/dry-run-guard.js";
+import { queryTerms, withQuery } from "../../cli/list-query.js";
 import { terminalAsker } from "../../cli/messenger/ask.js";
 import { lineOf } from "../../cli/steps.js";
 import { searchEvents } from "../../services/events-search.js";
@@ -11,12 +12,15 @@ import { linkPeople } from "../../services/people.js";
 import { BUSY_QUERY_HELP, busyAnswer, busyQuery, workingHoursOf } from "../busy.js";
 import { CALENDAR_UNTRUSTED_FIELDS, calendarIn, calendarItem, EVENTS_QUERY_HELP, eventAnswer, eventIdOf, eventOf, eventsAnswer, eventsFilter, peopleAnswer, resolveAnswer, reviewsAnswer, } from "../reads.js";
 import { REPEAT_HELP } from "../recurrence.js";
+import { serverSearchAnswer } from "../server-search.js";
 import { calendarStatus, syncCalendars } from "../sync.js";
 import { createEvent, deleteEvent, EVENT_RESPONSES, moveEvent, respondToEvent, updateEvent, } from "../writes.js";
+import { CALENDARS_QUERY, declareCalendarAnswers, PEOPLE_QUERY } from "./answers.js";
 const LOCAL_READ = { remote: "none", local: "read" };
 const LOCAL_WRITE = { remote: "none", local: "write" };
 const FETCH = { remote: "read", local: "write" };
 const REMOTE_READ = { remote: "read", local: "none" };
+const LOCAL_OR_REMOTE_READ = { remote: "read", local: "read" };
 const REMOTE_WRITE = { remote: "write", local: "write" };
 const GROUP = { remote: "none", local: "none" };
 /** How many pieces one `sync --embed` embeds, as drive's. */
@@ -26,6 +30,7 @@ const EVENT_ITEM_UNTRUSTED = ["title", "description", "location"];
 const ATTENDEE_UNTRUSTED = ["name"];
 const REVIEW_UNTRUSTED = ["candidates.title"];
 const SEARCH_UNTRUSTED = ["hits.title", "hits.location", "hits.excerpt"];
+const SERVER_SEARCH_UNTRUSTED = ["hits.title", "hits.location"];
 const eachMarked = (answer, untrusted) => ({
     ...answer,
     items: answer.items.map((item) => ({ ...item, untrusted })),
@@ -42,16 +47,9 @@ const minutes = (text) => {
     return value;
 };
 const addCalendarCommandsDefinition = (program, deps) => {
+    const mounted = new Set(program.commands);
     const now = () => deps.now?.() ?? Date.now();
     const zone = () => timezoneOf(deps.timezone);
-    const output = (command) => command
-        .option("--json", "one JSON value")
-        .option("--jsonl", "one JSON object per item")
-        .hook("preAction", (cmd) => {
-        const opts = cmd.optsWithGlobals();
-        if (opts.json && opts.jsonl)
-            throw new CliError("validation_error", "choose --json or --jsonl");
-    });
     const print = (value, command) => {
         const opts = command.optsWithGlobals();
         deps.write(value, opts.json ? "json" : opts.jsonl ? "jsonl" : "text");
@@ -81,27 +79,31 @@ const addCalendarCommandsDefinition = (program, deps) => {
         return deps.source;
     };
     const calendars = annotate(program.command("calendars").description("the account's calendars"), { effects: GROUP });
-    output(example(annotate(calendars.command("list"), { effects: FETCH, offline: false }).description("list the account's calendars from the provider, and which of them sync"), "calendars list --json")).action(async (_opts, command) => {
+    withQuery(example(annotate(calendars.command("list"), { effects: FETCH, offline: false }).description("list the account's calendars from the provider, and which of them sync"), "calendars list --json", "calendars list synced:true"), CALENDARS_QUERY).action(async (words, _opts, command) => {
+        const terms = [...queryTerms(words, CALENDARS_QUERY, "calendars list")];
         const listed = await deps.store.saveCalendars(deps.accountId, await source().calendars(), now());
-        print({ items: listed.map(calendarItem), page: 1, limit: listed.length, hasMore: false }, command);
+        const items = listed
+            .map(calendarItem)
+            .filter((item) => terms.every(([field, value]) => String(item[field]) === value));
+        print({ items, page: 1, limit: items.length, hasMore: false }, command);
     });
     for (const [name, synced] of [
         ["sync", true],
         ["unsync", false],
     ])
-        output(example(annotate(calendars.command(name), { effects: LOCAL_WRITE })
+        example(annotate(calendars.command(name), { effects: LOCAL_WRITE })
             .description(synced ? "sync this calendar from now on" : "stop syncing this calendar; what is stored stays")
-            .argument("<calendar>", "the calendar's id, or the provider's id"), `calendars ${name} 3`)).action(async (reference, _opts, command) => {
+            .argument("<calendar>", "the calendar's id, or the provider's id"), `calendars ${name} 3`).action(async (reference, _opts, command) => {
             const calendar = await calendarIn(deps.store, deps.accountId, reference);
             await deps.store.setCalendarSynced(calendar.id, synced, now());
             print(calendarItem({ ...calendar, synced }), command);
         });
     if (deps.freeBusy)
-        output(example(annotate(calendars.command("busy"), { effects: REMOTE_READ, offline: false })
+        example(annotate(calendars.command("busy"), { effects: REMOTE_READ, offline: false })
             .description("when calendars and people are taken, asked of the provider and not stored; with --duration-minutes, " +
             "the free stretches they share")
             .argument("[words...]", "today, week, from:<date>, to:<date>, calendar:<id>, person:<email>")
-            .addHelpText("after", BUSY_QUERY_HELP), "calendars busy week person:ana@example.com --json", "calendars busy from:2026-11-02 to:2026-11-06 person:ana@example.com --duration-minutes 30 --hours 10:00-16:00"))
+            .addHelpText("after", BUSY_QUERY_HELP), "calendars busy week person:ana@example.com --json", "calendars busy from:2026-11-02 to:2026-11-06 person:ana@example.com --duration-minutes 30 --hours 10:00-16:00")
             .option("--duration-minutes <minutes>", "find free stretches at least this long, 5–1440", minutes)
             .option("--hours <from-to>", "working hours in your time zone, Monday to Friday, with --duration-minutes", "09:00-17:00")
             .action(async (words, opts, command) => {
@@ -117,13 +119,13 @@ const addCalendarCommandsDefinition = (program, deps) => {
                 ...(opts.durationMinutes === undefined ? {} : { slot: { minutes: opts.durationMinutes, hours } }),
             }), command);
         });
-    output(example(annotate(program.command("sync"), {
+    example(annotate(program.command("sync"), {
         effects: FETCH,
         offline: false,
         cooperative: true,
         partial: true,
     }).description("bring the synced calendars up to date: what changed since the last sync, or everything with --rescan; a run " +
-        "stops before its deadline or --max-pages and the next one goes on from there"), "sync", "sync --rescan --embed", "sync --timeout 2m"))
+        "stops before its deadline or --max-pages and the next one goes on from there"), "sync", "sync --rescan --embed", "sync --timeout 2m")
         .option("--rescan", "list every synced calendar's window again, dropping a round in progress")
         .option("--max-pages <pages>", "at most this many requests to the provider in this run; as many as fit the deadline if not given", integer)
         .option("--embed", "also index new events for meaning search, with a model already downloaded")
@@ -191,17 +193,17 @@ const addCalendarCommandsDefinition = (program, deps) => {
             });
         print({ ...report, ...(embeddings === undefined ? {} : { embeddings }), ...(next ? { next } : {}) }, command);
     });
-    output(example(annotate(program.command("status"), { effects: LOCAL_READ }).description("how far each synced calendar's sync is: entries done, partial or complete, and when it last moved"), "status --json")).action(async (_opts, command) => {
+    example(annotate(program.command("status"), { effects: LOCAL_READ }).description("how far each synced calendar's sync is: entries done, partial or complete, and when it last moved"), "status --json").action(async (_opts, command) => {
         print(await calendarStatus(deps.store, deps.accountId, {
             profile: deps.profile ?? `account ${deps.accountId}`,
             now: now(),
         }), command);
     });
     const events = annotate(program.command("events").description("the account's stored events"), { effects: GROUP });
-    output(example(annotate(events.command("list"), { effects: LOCAL_READ, output: { entity: "event" } })
+    example(annotate(events.command("list"), { effects: LOCAL_READ })
         .description("list stored events, earliest first")
         .argument("[words...]", "today, week, from:<date>, to:<date>, person:<who>, calendar:<id>")
-        .addHelpText("after", EVENTS_QUERY_HELP), "events list week --json", "events list from:2026-11-02 to:2026-11-06 person:ana@example.com"))
+        .addHelpText("after", EVENTS_QUERY_HELP), "events list week --json", "events list from:2026-11-02 to:2026-11-06 person:ana@example.com")
         .option("--limit <n>", "events at most, 1–1000", integer, 100)
         .action(async (words, opts, command) => {
         const filter = await eventsFilter(words, {
@@ -213,20 +215,48 @@ const addCalendarCommandsDefinition = (program, deps) => {
         });
         print(eachMarked(await eventsAnswer(deps.store, filter && { ...filter, limit: opts.limit }), EVENT_ITEM_UNTRUSTED), command);
     });
-    output(example(annotate(events.command("show"), { effects: LOCAL_READ })
+    example(annotate(events.command("show"), { effects: LOCAL_READ })
         .description("one event: its calendar copies, attendees with their person, Drive files and history")
-        .argument("<event>", "the event's id, or event:<id>"), "events show event:42 --json")).action(async (reference, _opts, command) => {
+        .argument("<event>", "the event's id, or event:<id>"), "events show event:42 --json").action(async (reference, _opts, command) => {
         const shown = await eventAnswer(await eventOf(deps.store, deps.accountId, eventIdOf(reference)), personOfEmail);
         print({ ...shown, untrusted: CALENDAR_UNTRUSTED_FIELDS }, command);
     });
-    output(example(annotate(program.command("search"), { effects: LOCAL_READ })
-        .description("find stored events by words, and by meaning when its model is downloaded")
-        .argument("<words...>", "what to find in titles, descriptions, places and attendees"), "search roadmap planning --json"))
+    const search = example(annotate(program.command("search"), { effects: deps.serverSearch ? LOCAL_OR_REMOTE_READ : LOCAL_READ })
+        .description(deps.serverSearch
+        ? "find stored events by words, and by meaning when its model is downloaded; with --backend server, ask " +
+            "the provider instead"
+        : "find stored events by words, and by meaning when its model is downloaded")
+        .argument("<words...>", "what to find in titles, descriptions, places and attendees"), "search roadmap planning --json", ...(deps.serverSearch ? ["search --backend server quarterly review"] : []))
         .option("--limit <n>", "events per page", integer, 20)
         .option("--cursor <cursor>", "continue from a page's next_offset", (text) => (text === "0" ? 0 : integer(text)), 0)
         .option("--exact", "every word as written, no word stems")
-        .option("--newest", "latest start first instead of best first")
-        .action(async (words, opts, command) => {
+        .option("--newest", "latest start first instead of best first");
+    if (deps.serverSearch)
+        search.addOption(new Option("--backend <archive|server|both>", "where to search: archive, the local store, or server, the provider's own search over the synced calendars, " +
+            "earliest first")
+            .choices(["archive", "server", "both"])
+            .default("archive"));
+    search.action(async (words, opts, command) => {
+        if (opts.backend === "both")
+            throw new CliError("validation_error", "search --backend both is not offered: the store's search and the provider's rank and page events " +
+                "differently, so one merged list would have no single order or next page; run --backend archive and " +
+                "--backend server", { reason: "search.one-backend" });
+        if (opts.backend === "server") {
+            if (command.optsWithGlobals().offline)
+                throw new CliError("permission_error", "search --backend server asks the provider; leave out --offline", {
+                    reason: "search.offline",
+                });
+            if (opts.exact || opts.cursor || opts.newest)
+                throw new CliError("validation_error", "search --backend server takes neither --exact, --cursor nor --newest: the provider ranks and pages it", { reason: "search.server-options" });
+            const found = await serverSearchAnswer(source(), deps.store, {
+                accountId: deps.accountId,
+                account: deps.account,
+                query: words.join(" "),
+                limit: opts.limit,
+            });
+            print({ ...found, untrusted: SERVER_SEARCH_UNTRUSTED }, command);
+            return;
+        }
         const found = await searchEvents(messages("search"), words.join(" "), {
             accounts: [deps.account],
             limit: opts.limit,
@@ -239,13 +269,12 @@ const addCalendarCommandsDefinition = (program, deps) => {
         print({ ...found, untrusted: SEARCH_UNTRUSTED }, command);
     });
     if (deps.writes)
-        addEventWrites(events, deps.writes, { deps, now, zone, output, print, example });
+        addEventWrites(events, deps.writes, { deps, now, zone, print, example });
     const people = annotate(program.command("people").description("the people in the account's events"), {
         effects: GROUP,
     });
-    output(example(annotate(people.command("list"), { effects: LOCAL_READ })
-        .description("one event's attendees, or everyone attending this week's events")
-        .argument("[event]", "the event's id, or event:<id>"), "people list --json", "people list event:42")).action(async (reference, _opts, command) => {
+    withQuery(example(annotate(people.command("list"), { effects: LOCAL_READ }).description("one event's attendees, or everyone attending this week's events"), "people list --json", "people list event:42"), PEOPLE_QUERY).action(async (words, _opts, command) => {
+        const reference = queryTerms(words, PEOPLE_QUERY, "people list").get("event");
         const event = reference === undefined ? undefined : eventIdOf(reference);
         const filter = event === undefined
             ? await eventsFilter(["week"], { store: deps.store, accountId: deps.accountId, zone: zone(), now: now() })
@@ -257,10 +286,10 @@ const addCalendarCommandsDefinition = (program, deps) => {
         });
         print(eachMarked(people, ATTENDEE_UNTRUSTED), command);
     });
-    output(example(annotate(people.command("link"), { effects: LOCAL_WRITE })
+    example(annotate(people.command("link"), { effects: LOCAL_WRITE })
         .description("join an attendee to a person the owner knows elsewhere")
         .argument("<person>", "an attendee's address as email:<address>, or a person:<id>")
-        .argument("<other>", "the same person in another tool, as <provider>:<person>, or me"), "people link email:ana@example.com telegram:12345")).action(async (person, other, _opts, command) => {
+        .argument("<other>", "the same person in another tool, as <provider>:<person>, or me"), "people link email:ana@example.com telegram:12345").action(async (person, other, _opts, command) => {
         const linked = await linkPeople(messages("people link"), deps.account, person, other);
         print({
             person: `person:${linked.uid}`,
@@ -271,18 +300,20 @@ const addCalendarCommandsDefinition = (program, deps) => {
     const links = annotate(program.command("links").description("calendar copies the rules could not join alone"), {
         effects: GROUP,
     });
-    output(example(annotate(links.command("review"), { effects: LOCAL_READ }).description("copies that fit two or more events equally well, waiting for the owner's choice"), "links review --json")).action(async (_opts, command) => {
+    example(annotate(links.command("review"), { effects: LOCAL_READ }).description("copies that fit two or more events equally well, waiting for the owner's choice"), "links review --json").action(async (_opts, command) => {
         print(eachMarked(await reviewsAnswer(deps.store), REVIEW_UNTRUSTED), command);
     });
-    output(example(annotate(links.command("resolve"), { effects: LOCAL_WRITE })
+    example(annotate(links.command("resolve"), { effects: LOCAL_WRITE })
         .description("join a copy to the event you choose, or keep it apart")
         .argument("<review>", "the review's id from links review")
-        .argument("<choice>", "one of its candidates, as event:<id>, or apart"), "links resolve 7 event:42")).action(async (review, choice, _opts, command) => {
+        .argument("<choice>", "one of its candidates, as event:<id>, or apart"), "links resolve 7 event:42").action(async (review, choice, _opts, command) => {
         print(await resolveAnswer(deps.store, deps.accountId, review, choice, now()), command);
     });
+    const leaves = (command) => command.commands.length ? command.commands.flatMap(leaves) : [command];
+    declareCalendarAnswers(program, program.commands.filter((one) => !mounted.has(one)).flatMap(leaves));
 };
 const collect = (value, previous = []) => [...previous, value];
-const addEventWrites = (events, writes, { deps, now, zone, output, print, example }) => {
+const addEventWrites = (events, writes, { deps, now, zone, print, example }) => {
     const context = (command) => ({
         store: deps.store,
         accountId: deps.accountId,
@@ -330,48 +361,48 @@ const addEventWrites = (events, writes, { deps, now, zone, output, print, exampl
     const target = (command) => command
         .argument("<event>", "the event's id, or event:<id>")
         .option("--calendar <id>", "the calendar, when the event is on more than one of the account's");
-    output(example(notify(fields(write("create"), false)
+    example(notify(fields(write("create"), false)
         .description("add an event to a calendar; with --repeat, one that repeats")
         .argument("<calendar>", "the calendar's id, or the provider's id")).option("--id <id>", "the id a create that ended in outcome_unknown named: a retry finds that event"), "events create 3 --title 'Example planning' --start-time 2026-11-02T10:00 --end-time 2026-11-02T11:00", "events create 3 --title 'Example review' --start-date 2026-11-03 --end-date 2026-11-03 " +
         "--attendee ana@example.com --no-notify", "events create 3 --title 'Example standup' --start-time 2026-11-02T09:30 --end-time 2026-11-02T09:45 " +
-        "--repeat 'FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=12'")).action(async (calendar, opts, command) => {
+        "--repeat 'FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=12'").action(async (calendar, opts, command) => {
         const { notify: choice, id, ...rest } = opts;
         printWritten(await createEvent(context(command), calendar, fieldsOf(rest), {
             ...(choice === undefined ? {} : { notify: choice }),
             ...(id === undefined ? {} : { id }),
         }), command);
     });
-    output(example(notify(target(fields(write("update"), true))
+    example(notify(target(fields(write("update"), true))
         .description("change an event; with --series every occurrence of the repeating event, with --following this " +
         "occurrence and every later one; new times or dates switch it between timed and all-day")
         .option("--series", "change the whole repeating event, not only this occurrence")
         .option("--following", "change this occurrence and every later one: the repeating event ends before it and a new one starts " +
         "with the change")
-        .option("--id <id>", "with --following, the id an outcome_unknown named: a retry finds that new series")), "events update event:42 --start-time 2026-11-02T14:00 --end-time 2026-11-02T15:00 --notify", "events update event:42 --series --repeat 'FREQ=WEEKLY;BYDAY=TU;UNTIL=20261231T230000Z' --no-notify", "events update event:42 --following --start-time 2026-11-09T10:00 --end-time 2026-11-09T10:30 --no-notify")).action(async (reference, opts, command) => {
+        .option("--id <id>", "with --following, the id an outcome_unknown named: a retry finds that new series")), "events update event:42 --start-time 2026-11-02T14:00 --end-time 2026-11-02T15:00 --notify", "events update event:42 --series --repeat 'FREQ=WEEKLY;BYDAY=TU;UNTIL=20261231T230000Z' --no-notify", "events update event:42 --following --start-time 2026-11-09T10:00 --end-time 2026-11-09T10:30 --no-notify").action(async (reference, opts, command) => {
         const { calendar: _calendar, series: _series, following: _following, notify: _notify, id, ...rest } = opts;
         printWritten(await updateEvent(context(command), reference, fieldsOf(rest), {
             ...choicesOf(opts),
             ...(id === undefined ? {} : { id }),
         }), command);
     });
-    output(example(notify(target(write("delete"))
+    example(notify(target(write("delete"))
         .description("delete an event; a whole repeating event, or every later occurrence, needs events.delete.series " +
         "allowed first")
         .option("--series", "delete the whole repeating event, not only this occurrence")
-        .option("--following", "delete this occurrence and every later one: the repeating event ends before it")), "events delete event:42 --no-notify", "events delete event:42 --following --no-notify")).action(async (reference, opts, command) => {
+        .option("--following", "delete this occurrence and every later one: the repeating event ends before it")), "events delete event:42 --no-notify", "events delete event:42 --following --no-notify").action(async (reference, opts, command) => {
         printWritten(await deleteEvent(context(command), reference, choicesOf(opts)), command);
     });
     if (writes.writer.move)
-        output(example(notify(target(write("move"))
+        example(notify(target(write("move"))
             .description("move an event, with its id, to another calendar of the account; a repeating one moves whole")
             .requiredOption("--to-calendar <id>", "the calendar to move it to: its id, or the provider's id")
-            .option("--series", "move the whole repeating event an occurrence belongs to")), "events move event:42 --to-calendar 4 --no-notify")).action(async (reference, opts, command) => {
+            .option("--series", "move the whole repeating event an occurrence belongs to")), "events move event:42 --to-calendar 4 --no-notify").action(async (reference, opts, command) => {
             const { series, calendar, notify } = opts;
             printWritten(await moveEvent(context(command), reference, opts.toCalendar, choicesOf({ series, calendar, notify })), command);
         });
-    output(example(notify(target(write("respond"))
+    example(notify(target(write("respond"))
         .description("answer an invitation; the organiser is told only with --notify")
-        .addArgument(new Argument("<response>", "the answer").choices(EVENT_RESPONSES))), "events respond event:42 accepted --notify")).action(async (reference, response, opts, command) => {
+        .addArgument(new Argument("<response>", "the answer").choices(EVENT_RESPONSES))), "events respond event:42 accepted --notify").action(async (reference, response, opts, command) => {
         printWritten(await respondToEvent(context(command), reference, response, choicesOf(opts)), command);
     });
 };

package/dist/calendar/index.d.ts

@@ -1,6 +1,6 @@
 export type { CalendarAccessRole, CalendarInput, EntryAttachment, EntryAttachmentInput, EntryEventType, EntryInput, EntryKind, EntryParticipantInput, EntryRevision, EntryStatus, EntryTransparency, EntryVisibility, EventDetails, EventFilter, EventStore, LinkReview, ParticipantResponse, ReviewDecision, StoredCalendar, StoredEntry, StoredParticipant, } from "../meetings/index.js";
 export { repeatRule } from "./recurrence.js";
-export type { BusyTimes, CalendarExpander, CalendarSource, CalendarSourceTraits, ChangePage, ChangeResult, FreeBusyRequest, SyncWindow, } from "./source.js";
+export type { BusyTimes, CalendarExpander, CalendarSource, CalendarSourceTraits, ChangePage, ChangeResult, FreeBusyRequest, SearchPage, SyncWindow, } from "./source.js";
 export { type CalendarCursor, type CalendarSyncOptions, type CalendarSyncReport, type CalendarSyncResult, calendarStatus, calendarSyncWindow, type PendingRound, parseCalendarCursor, syncCalendars, } from "./sync.js";
 export { CALENDAR_WRITE_DEFAULTS, CALENDAR_WRITE_KEYS, type CalendarWrite, type CalendarWriter, calendarConflict, EVENTS_DELETE_SERIES_KEY, EVENTS_NOTIFY_KEY, type EventDraft, type EventPatch, type EventResponse, type FollowingScope, type WriteScope, } from "./writer.js";
 export type { CalendarWrites } from "./writes.js";

package/dist/calendar/reads.d.ts

@@ -63,6 +63,13 @@ export declare const eventAnswer: (details: EventDetails, personOf?: PersonOfEma
     created_at: string;
     updated_at: string;
     untrusted?: string[] | undefined;
+    change?: "cancelled" | "moved" | "new" | undefined;
+    changed_at?: string | null | undefined;
+    was?: {
+        starts_at: string | null;
+        ends_at: string | null;
+    } | undefined;
+    overlaps?: string[] | undefined;
     ref: string;
     entries: {
         id: string;

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

@@ -0,0 +1,31 @@
+import type { EventStore } from "../meetings/index.js";
+import type { AccountKey } from "../store/store.js";
+import type { CalendarSource } from "./source.js";
+/**
+ * The provider's own search over the calendars the account syncs, earliest first, stored nowhere. A calendar the owner
+ * does not sync stays out: he chose which calendars the CLI reads.
+ */
+export declare const serverSearchAnswer: (source: CalendarSource, store: EventStore, { accountId, account, query, limit }: {
+    accountId: number;
+    account: AccountKey;
+    query: string;
+    limit: number;
+}) => Promise<{
+    query: string;
+    by: "server";
+    hits: {
+        provider: string;
+        account: string;
+        calendar: string;
+        external_id: string;
+        title: string | null;
+        starts_at: string | null;
+        ends_at: string | null;
+        all_day: boolean;
+        status: "confirmed" | "tentative";
+        location: string | null;
+        url?: string | undefined;
+        found_by: "server"[];
+    }[];
+    has_more: boolean;
+}>;

package/dist/calendar/server-search.js

@@ -0,0 +1,41 @@
+import { CliError } from "@wirecat/cli-base";
+const iso = (at) => (at == null ? null : new Date(at).toISOString());
+/**
+ * The provider's own search over the calendars the account syncs, earliest first, stored nowhere. A calendar the owner
+ * does not sync stays out: he chose which calendars the CLI reads.
+ */
+export const serverSearchAnswer = async (source, store, { accountId, account, query, limit }) => {
+    if (!source.search)
+        throw new CliError("configuration_error", "this calendar provider has no search of its own");
+    const calendars = (await store.calendars(accountId)).filter(({ synced, deletedAt }) => synced && deletedAt === null);
+    if (calendars.length === 0)
+        throw new CliError("validation_error", "no calendar syncs yet; run sync, or calendars sync <calendar>", {
+            reason: "search.no-calendars",
+        });
+    const hits = [];
+    let more = false;
+    for (const calendar of calendars) {
+        const page = await source.search(calendar, { query, limit });
+        more ||= page.more;
+        for (const entry of page.entries) {
+            if (entry.status === "cancelled")
+                continue;
+            hits.push({
+                provider: source.provider,
+                account: account.account,
+                calendar: calendar.externalId,
+                external_id: entry.externalId,
+                title: entry.title ?? null,
+                starts_at: iso(entry.startsAt),
+                ends_at: iso(entry.endsAt),
+                all_day: entry.allDay === true,
+                status: entry.status,
+                location: entry.location ?? null,
+                ...(entry.url ? { url: entry.url } : {}),
+                found_by: ["server"],
+            });
+        }
+    }
+    hits.sort((a, b) => (a.starts_at ?? "").localeCompare(b.starts_at ?? ""));
+    return { query, by: "server", hits: hits.slice(0, limit), has_more: more || hits.length > limit };
+};

package/dist/calendar/source.d.ts

@@ -49,6 +49,12 @@ export interface BusyTimes {
     /** The provider's reason (`notFound`, `groupTooBig`): its busy times are unknown, not free. */
     error?: string;
 }
+/** What the provider's own text search found on one calendar: one page, read and never stored. */
+export interface SearchPage {
+    entries: EntryInput[];
+    /** The provider has more matches on this calendar than it returned. */
+    more: boolean;
+}
 /** One provider's calendars, as an adapter reads them. The engine never sees a provider word. */
 export interface CalendarSource {
     /** The registry name: `google-calendar`, `outlook-calendar`, `caldav`, `ics`. */
@@ -65,6 +71,14 @@ export interface CalendarSource {
     occurrences?(calendar: StoredCalendar, seriesExternalId: string, window: SyncWindow): Promise<EntryInput[]>;
     /** When calendars and people are taken, read from the provider and never stored. Absent: no `calendars busy`. */
     freeBusy?(request: FreeBusyRequest): Promise<BusyTimes[]>;
+    /**
+     * The provider's own text search over one calendar, at most `limit` entries; it also finds events outside the sync
+     * window. Absent: no `search --backend server`.
+     */
+    search?(calendar: StoredCalendar, request: {
+        query: string;
+        limit: number;
+    }): Promise<SearchPage>;
 }
 /**
  * Core expansion for `expands: "local"`: a series' slots inside the window, as occurrences. A slot its EXDATE lines

package/dist/calendar/testing/answers.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+/**
+ * Parses what a shared calendar command handed its host against the command's entity, as a host prints it: keys in
+ * snake_case, a list's items one by one, a search's hits each with the search's `untrusted`, and no `next`.
+ */
+export declare const checkCalendarAnswer: (root: Command, argv: readonly string[], value: unknown) => void;

package/dist/calendar/testing/answers.js

@@ -0,0 +1,37 @@
+import * as v from "valibot";
+import { answerEntitySchema } from "../../cli/answer-entity.js";
+import { snakeKeys } from "../../cli/envelope.js";
+const commandAt = (root, argv) => {
+    let at = root;
+    for (const word of argv) {
+        const next = at.commands.find((one) => one.name() === word);
+        if (!next)
+            break;
+        at = next;
+    }
+    return at;
+};
+/**
+ * Parses what a shared calendar command handed its host against the command's entity, as a host prints it: keys in
+ * snake_case, a list's items one by one, a search's hits each with the search's `untrusted`, and no `next`.
+ */
+export const checkCalendarAnswer = (root, argv, value) => {
+    const command = commandAt(root, argv);
+    const schema = answerEntitySchema(command);
+    if (!schema)
+        throw new Error(`${argv.join(" ")} declares no answer entity`);
+    const { next: _next, ...body } = snakeKeys(value);
+    const marker = body.untrusted
+        ?.filter((field) => field.startsWith("hits."))
+        .map((field) => field.slice("hits.".length));
+    const items = Array.isArray(body.items)
+        ? body.items
+        : Array.isArray(body.hits)
+            ? body.hits.map((hit) => ({ ...hit, untrusted: marker }))
+            : [body];
+    for (const item of items) {
+        const parsed = v.safeParse(schema, item);
+        if (!parsed.success)
+            throw new Error(`${argv.join(" ")}: ${parsed.issues.map((issue) => `${v.getDotPath(issue) ?? ""} ${issue.message}`).join("; ")}`);
+    }
+};

package/dist/calendar/testing/source.d.ts

@@ -6,6 +6,8 @@ export interface FakeCalendarSourceOptions {
     calendars?: CalendarInput[];
     /** Entries per page of `changes()`. */
     pageSize?: number;
+    /** Answer `search()`: an entry whose title, description or place holds the query, case aside, in any window. */
+    search?: boolean;
 }
 /**
  * A provider held in memory. Every `put` and `remove` is one change; the cursor names the last change it saw, so a

package/dist/calendar/testing/source.js

@@ -86,6 +86,15 @@ export const fakeCalendarSource = (options = {}) => {
                 },
             }
             : {}),
+        ...(options.search
+            ? {
+                async search(calendar, { query, limit }) {
+                    const words = query.toLowerCase();
+                    const found = [...of(calendar.externalId).values()].filter((entry) => [entry.title, entry.description, entry.location].some((text) => text?.toLowerCase().includes(words)));
+                    return { entries: found.slice(0, limit).map((entry) => structuredClone(entry)), more: found.length > limit };
+                },
+            }
+            : {}),
         async freeBusy({ calendars: asked, people: persons, window }) {
             const taken = (busy) => busy
                 .filter(({ from, to }) => from < window.to && to > window.from)

package/dist/cli/commands-command.js

@@ -96,10 +96,18 @@ const scopeOf = (root, all, path) => {
         if (!child || !described) {
             const prefix = selected?.path ?? [];
             const choices = available.map(({ name }) => name);
+            const groups = all
+                .filter(({ name, commands }) => commands.length > 0 && name !== "commands")
+                .map(({ name }) => name);
+            // The groups the caller named come first: they are the list of groups this answer is most likely about.
+            const [one, two] = [...new Set([...path.filter((each) => groups.includes(each)), ...groups])].map((group) => `\`${root.name()} commands ${group} --json\``);
             throw new CliError("validation_error", `unknown command path "${path.join(" ")}" — inspect \`${[root.name(), "commands", ...prefix, "--json"].join(" ")}\`; ` +
                 (choices.length ? `available here: ${choices.join(", ")}. ` : "this command has no subcommands. ") +
-                `Give one command path per call, not a list of groups: \`${root.name()} commands messages --json\` ` +
-                `and \`${root.name()} commands chats --json\` are separate calls`, { path, at: word, available: choices });
+                (two
+                    ? `Give one command path per call, not a list of groups: ${one} and ${two} are separate calls`
+                    : one
+                        ? `Give one command path per call, such as ${one}`
+                        : "Give one command path per call"), { path, at: word, available: choices });
         }
         if (selected && selected.options.length > 0) {
             inheritedOptions.push({ path: selected.path, options: [...selected.options] });

package/dist/cli/config-command.js

@@ -1,6 +1,6 @@
 import { CliError, pathsAreOverridden } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { envName } from "../ports/app.js";
 import { AUTHORITY_KEY, BOT_API_KEY } from "../sends/permissions.js";
 import { baseContext, environmentOf } from "./context.js";
@@ -16,10 +16,16 @@ import { changeStoreSetting, isStoreSetting, offersStoreSetting, storeSettings,
  */
 export const configCommand = (app, config, { permissionKey = config.permissions } = {}) => {
     const command = new Command("config").description("the settings in force, and where each one came from");
-    annotate(command.command("show"), { effects: LOCAL_READ, examples: [`${app.command} personal config show`] })
-        .description("the profile, the profiles that exist, and each setting with where it came from")
-        .option("--bot", "the settings a bot command on this profile gets, rather than the personal account's")
-        .action(async function () {
+    // Only a messenger has bots, and with them the personal and bot sections of the file. Elsewhere the options stay
+    // accepted, so a script that passes one still runs, but help, `commands --json` and MCP leave them out.
+    const bots = app.messenger !== false;
+    const kindOption = (flags, description) => new Option(flags, description).hideHelp(!bots);
+    const show = annotate(command.command("show"), {
+        effects: LOCAL_READ,
+        examples: [`${app.command} personal config show`],
+    }).description("the profile, the profiles that exist, and each setting with where it came from");
+    show.addOption(kindOption("--bot", "the settings a bot command on this profile gets, rather than the personal account's"));
+    show.action(async function () {
         const bot = this.opts().bot === true;
         const context = baseContext(this, (flags, options) => config.resolveSettings(flags, {
             ...options,
@@ -32,6 +38,9 @@ export const configCommand = (app, config, { permissionKey = config.permissions
         renderAnswer(this, context, itemOf({
             profile: settings.sources.profile === NONE_NAMED ? null : settings.profile,
             profile_from: settings.sources.profile,
+            kind: settings.kind,
+            permissions: settings.permissions,
+            permission_sources: settings.permissionSources,
             profiles: settings.profilesHere,
             config_file: settings.configPath,
             config_found: settings.configFound,
@@ -48,7 +57,8 @@ export const configCommand = (app, config, { permissionKey = config.permissions
             renderer.warn(`${issue.what}, so it is left out${issue.fix ? ` — \`${issue.fix}\` removes it` : ""}`);
         if (overridden) {
             renderer.note(`${envName(app, "CONFIG_DIR")}, ${envName(app, "STATE_DIR")} or ${envName(app, "CACHE_DIR")} is set — ` +
-                "a profile's keyring entry is not the usual one, so a session made without them reads as none");
+                "a session is still read from the usual keyring entry, but a sign-in made with them is kept apart, in a " +
+                "temporary entry that session end removes");
         }
     });
     for (const action of ["set", "unset"]) {
@@ -58,8 +68,8 @@ export const configCommand = (app, config, { permissionKey = config.permissions
         }))
             .argument("<setting>", `one of: ${[...config.allSettings, ...storeSettingsOf(app)].join(", ")}`)
             .option("--defaults", "change what every profile gets, rather than this profile")
-            .option("--personal", "only for personal accounts — the personal section of the file")
-            .option("--bot", "only for bots — the bot section of the file");
+            .addOption(kindOption("--personal", "only for personal accounts — the personal section of the file"))
+            .addOption(kindOption("--bot", "only for bots — the bot section of the file"));
         if (action === "set")
             sub
                 .argument("<value>", "a number, true or false; for a group tg:work,max:Alice,email:me@x")

package/dist/cli/index.d.ts

@@ -96,7 +96,7 @@ export { httpTokenFile, type McpEnvironment, type McpHost, serverEntry } from ".
 export { type MessageItem, messageItem, type ReadMessage } from "./messenger/message-items.js";
 export { type ModeProblem, type PrivateFiles, privateFiles, withSqliteSidecars } from "./messenger/private-files.js";
 export { buildReport as buildDoctorReport, type Report as DoctorReport, type ReportContext as DoctorReportContext, reportFileName as doctorReportFileName, } from "./messenger/report.js";
-export { allAnswer, allHitItem, type HitItem, type MessageHitItem, messageHitItem, type NoteHitItem, noteHitItem, } from "./messenger/search-answers.js";
+export { allAnswer, allHitItem, coverageGaps, type HitItem, type MessageHitItem, messageHitItem, type NoteHitItem, noteHitItem, } from "./messenger/search-answers.js";
 export { SEARCHES_QUERY } from "./messenger/searches-command.js";
 export { servingProfiles } from "./messenger/serve-command.js";
 export { DAY_MS, FIRST_FETCH_MS, type MemberFetches, memberFetches } from "./messenger/serve-members.js";

package/dist/cli/index.js

@@ -87,7 +87,7 @@ export { httpTokenFile, serverEntry } from "./messenger/mcp-command.js";
 export { messageItem } from "./messenger/message-items.js";
 export { privateFiles, withSqliteSidecars } from "./messenger/private-files.js";
 export { buildReport as buildDoctorReport, reportFileName as doctorReportFileName, } from "./messenger/report.js";
-export { allAnswer, allHitItem, messageHitItem, noteHitItem, } from "./messenger/search-answers.js";
+export { allAnswer, allHitItem, coverageGaps, messageHitItem, noteHitItem, } from "./messenger/search-answers.js";
 export { SEARCHES_QUERY } from "./messenger/searches-command.js";
 export { servingProfiles } from "./messenger/serve-command.js";
 export { DAY_MS, FIRST_FETCH_MS, memberFetches } from "./messenger/serve-members.js";

package/dist/cli/messenger/store-maintenance-command.d.ts

@@ -3,9 +3,9 @@ import type { CacheDatabase } from "../../store/driver.js";
 import type { Messenger } from "./context.js";
 /** `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. */
 export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
-    error?: undefined;
     path: string;
     exists: boolean;
+    error?: undefined;
 } | {
     path: string;
     exists: boolean;