@wirecat/cli-core 0.563.0 → 0.565.0

package/CHANGELOG.md

@@ -7,6 +7,131 @@ shape of this file.
 
 ## Unreleased
 
+## 0.565.0 — 05.11.2026
+
+### Changed — may break callers
+
+- **The shared calendar commands print their own answers and open the profile per command.**
+  `addCalendarCommands(program, { app, open, freeBusy?, serverSearch?, feeds?, writes?, readFile?, writeFile? })`
+  replaces `CalendarCommandDeps`. `open(command, { readOnly })` returns a `CalendarRun` (event store, shared store,
+  account, profile, `locked`, and `source()`, `writes()`, `feeds()` built on first use); it is closed before the
+  answer prints. Each command answers in the standard envelope (`renderAnswer`) with its `meta` as built, so nothing
+  in between can drop it, and `write`, `note`, `embed`, `store`, `accountId` and the other per-profile fields are gone
+  from the options. The tree is built once with no state per call (WC-ARCH-22). `events export --output` and
+  `events import` read and write files themselves (0600, `file.not-found`, `file.not-a-file`, `file.denied`) unless
+  the app passes `readFile` / `writeFile`. `search all` is always mounted.
+- **`calendars busy` answers and queries `starts_at` / `ends_at`**, as every event answer does, in place of `start`
+  / `end` (WC-OUT-12): `calendars busy starts_at>=2026-11-02 ends_at<=2026-11-06`.
+- **`sync` keeps what the other calendars brought when one fails** (WC-OUT-8). It answers with `meta.complete: false`
+  and an issue per failed calendar (`sync.partial`, source `calendar:<id>`) instead of a `provider_error` with an
+  empty stdout.
+- **`events create --text` takes `--operation-id`.** A quick add whose answer was lost names an id starting with
+  `q`; run again with it, the create looks for the event that attempt made through the writer's new optional
+  `quickAdded(calendar, since)` before it sends the line again (WC-CMD-6). Two candidates are refused
+  (`event.quick-add-ambiguous`).
+- **`EntryContext.openBrowser(url, browser?, command?)` opens nothing where nobody can use a browser** (WC-CMD-15):
+  under `CI`, `--json`, `--jsonl`, `--no-input`, or with no terminal. The caller prints the URL either way.
+- **Shared reasons for CLIs over a provider's API:** `offline.refused`, `api.unknown-method`, `api.disabled`,
+  `provider.usage-limit`, `oauth.scope-missing`, `sign-in.client-rejected`, `file.not-found`, `file.not-a-file` and
+  `file.denied` are in cli-core's list. A CLI that registered one of them itself must drop its copy: two entries of
+  one reason are refused.
+- **`speech_model` and `picture_search` are messenger settings**, and `config show` of a CLI that is not a
+  messenger lists no messenger store setting (`phone_countries`, `task_categories.*`, `task_agent_close*`,
+  `task_first_pass_per_chat`).
+- **cli-core accepts `@wirecat/cli-base` 0.76 and 0.77 (peer range `>=0.75.0 <0.78.0`) and builds with
+  0.77.1**, whose vocabulary has the `schedule` resource, the `agent`, `command` and `exec` verbs and `--trimmed`. The command
+  lint now checks `schedule agent|command|exec` instead of skipping them in `lint/baseline`. A CLI that mounts
+  `schedule` (tg, max, wa, gcal, mail, memo) removes the same entries from its own baseline when it bumps cli-base
+  to 0.77.0: they are stale there and fail its lint. 0.76.0 adds the `conflict` error code; nothing here uses it yet.
+
+### Added
+
+- **`actorOf(command)` is exported from `./cli`:** who acts in this run, the owner or the agent by its name, as a
+  `Decider` for the document knowledge's confirm, stale and reverse needs it.
+- **`checkConfigText(text, { repair: false })` and `settingsFor(app, { configRepair: false })`** for a CLI with its
+  own `config` that has no `repair`: an invalid file's issue then names no `config repair` to run.
+- **`commandPermissions({ alsoChecks })`:** the other keys a command's real run checks. A `--dry-run` preview shows
+  each with its level under `permission.also` and refuses as the run would, so gcal's `api.calendar.*` keys show.
+- **A CLI that is not a messenger previews a `--dry-run` under `<PREFIX>_READ_ONLY`** (WC-PERM-12); it sends nothing.
+  A messenger's preview stays refused under the lock.
+
+## 0.564.0 — 05.11.2026
+
+### Changed — may break callers
+
+- **`search all` ranks its sources as one list** (MEMO-37). Each source's hit at one rank used to get the same score,
+  so the sources took turns in the order they were read (messages, mail, notes, events). Now hits at the same rank
+  are ordered by cosine, since one model scores every source; a hit meaning did not find comes after those it did.
+  Each source's own order is kept. Without the model nothing changes. `search notes` and `search events` hits found
+  by meaning carry `meaning_score`, the cosine.
+- **tg, max and wa `search all` change with the bump, with no code change in them.** Mail is searched by meaning when
+  the store holds mail, a question's message found both by words and by meaning gets one vote, and once vectors
+  exist the hits at one rank are ordered by meaning score.
+- **`search all` searches mail by meaning too** (MEMO-38). Mail was only ever searched by words there, though its
+  threads had vectors. The meaning lane now reads a mail account's thread vectors through the mail store, and
+  `search all` fuses them with the word hits as it does for messages; the answer says how in `mail`. For a question,
+  a mail or message found by words gets no second vote from meaning, as in notes.
+- **`search all` finds records for a question typed as a sentence.** When the text is a question in natural language
+  and not `exact`, messages and mail go through discovery (as `search messages --discover`), and notes and calendar
+  events search any of the question's content words, ranked by the store. Before, every word had to be in one record,
+  so a question found nothing (MEMO-36). tg, max and wa still ask the messenger's server with the question as typed.
+  For a question, a note found by both words and meaning gets one vote, not two, so notes found by words alone are not
+  buried. Plain words, query syntax and `exact` are searched strictly, as before. `searchNotes` and `searchEvents`
+  take `discover`.
+
+### Added
+
+- **The proposal registry reviews meeting findings and task close suggestions.** `proposalRegistry` registers
+  `meeting_findings` (a meeting's staged batch, decided part by part as in `meetings actions confirm`) and
+  `task_close` (an agent's suggested close, id `close:<task key>`; confirming closes the task as suggested, rejecting
+  clears the suggestion). Both are owner only: `isOwnerOnlyKind` now names `task_close` too, so `mayDecide` refuses an
+  agent by the row's kind. `parseProposalIds` takes a task key after a prefix (`close:Q-15`). Moved from cli-memo,
+  which registered both itself; a host that registers a kind of the same name now gets `configuration_error`.
+
+- **A mail CLI's `messages show` can read an email again when a sync's limit left its attachment unread.**
+  `mailReadCommands` takes `whole(command, store, mailbox, emailId)`; with it the command is a fetch, reads such an
+  email from the server before it answers (`readEmailWhole`), and shows the new text. When that read fails it shows
+  the stored email with `meta.complete: false` and an issue `mail.attachments-unread`. Without `whole` nothing changes.
+  `readEmailWhole`'s body and text limits, reader and clock now default as sync's do.
+- **`has:transcript` in the messages query language** finds a voice message that has a transcription, so
+  `stats messages show --by day -- has:transcript date>=30d` counts transcribed voice messages per day. In mail it
+  finds nothing.
+- **`store chats status`** counts the account's searchable chats of every kind, channels included, by how much of each
+  the archive holds: `{ chats, fetched, partial, never, oldest_message_at }`. `fetched` is held back to the first
+  message, up to date and without gaps; `never` has no fetch recorded and no message held; the rest is `partial`,
+  including WhatsApp chats whose history was pushed. One statement over the store, no list of chats. tg, max and wa
+  get it with the bump.
+- **Meeting counts per day, week or series.** `readMeetingCounts` (services) and `store.meetings.meetingCounts`
+  answer meetings, minutes, mean minutes and meetings with a transcript, in total and per row, over the same
+  selection as `readMeetingStats`, reading `meetings` alone through `meetings_by_time`. `meetingCountsItem` and the
+  `meeting_counts` entity are the answer, for zoom-cli's `stats meetings history`. A meeting with no end counts in
+  `meetings`, not in `minutes`. `MeetingStatsStore` gains `meetingCounts`; only cli-core's own store implements it.
+- **`stats tasks show` counts by chat, meeting or project, over a period.** `--by meeting` keys a row by the meeting a
+  task came from (`meeting:<account>/<meeting>`); `--by project` reads the owner's project tasks, every project
+  (`project:<id>`). A query after `--` takes the task query's fields and `created` for the period: `created` counts
+  the tasks opened in it, `closed` those closed in it, `open` is always open now (`-- created>=30d`). The item gains
+  `created`, `closed`, `median_close_ms` and `mean_open_age_ms`; each row gains `key`, `name` (chat title, meeting
+  title, project name), `created`, `closed` and `mean_open_age_ms`. Rows of `--by chat` keep `chat`; the others have
+  none. `--timezone` places calendar days such as `created>=today`.
+- **`created:` in the project task query** (`PROJECT_TASK_FIELDS`), beside `closed:`: `created>=30d`.
+- **`mailStats` from `./mail`**: stored mail received and sent per calendar day, week (by its Monday) or sender, for
+  the `search mail` query, counts only and no search recorded; `mailStatsItem` turns it into the new `mail_counts`
+  entity, `{ by, received, sent, rows: [{ key, name, received, sent }] }`. By sender it counts received mail only.
+- **`mailOwnText(body)` (`@wirecat/cli-core/mail`): what an email says itself, without quoted earlier mail and the
+  signature.** It drops `>` lines, cuts at a reply header ("On … wrote:", "Le … a écrit :", "Am … schrieb …:",
+  "… написал(а):", Gmail's Russian "<address>:") and at an Outlook From/Sent block in English, German, French, Spanish
+  and Russian, and drops the `-- ` signature, sign-offs and mobile footers. A forwarded message stays whole; an email
+  that is only a quote keeps its body.
+
+### Security
+
+- **`review --holder` gives each email's own text** (`mailOwnText`), so an agent's model does not read earlier mail
+  or signatures. The fingerprint a finding cites is still taken over the stored body; other reads show the whole text.
+- **Review and inbox items say which fields others wrote** (WC-SECR-21): `summaryOf` items, and so every catch-up
+  answer and each mail `review` item, carry `untrusted` (`SUMMARY_UNTRUSTED`: chat title, sender name, text,
+  transcript, attachment names); a mail review item adds the email's subject and the names in its headers, as search
+  hits do. The `message.summary` entity takes the field.
+
 ## 0.563.0 — 03.11.2026
 
 ### Changed — may break callers

package/dist/calendar/busy.d.ts

@@ -8,7 +8,7 @@ export interface BusyQuery {
     people: string[];
 }
 /**
- * `calendars busy`'s query: the window by the answer's own `start` and `end`, and whom to ask. `calendar` and
+ * `calendars busy`'s query: the window by the answer's own `starts_at` and `ends_at`, and whom to ask. `calendar` and
  * `person` repeat, and every one named is asked: the free stretches are those they all share.
  */
 export declare const BUSY_QUERY: QueryRegistry;
@@ -47,29 +47,29 @@ export declare const busyAnswer: (source: CalendarSource, query: BusyQuery, opti
         hours: WorkingHours;
     };
 }) => Promise<{
-    start: string;
-    end: string;
+    starts_at: string;
+    ends_at: string;
     timezone: string;
     calendars: ({
         id: string;
         calendar: string;
         busy: {
-            start: string;
-            end: string;
+            starts_at: string;
+            ends_at: string;
         }[];
         error?: string | undefined;
     } | {
         id: string;
         person: string;
         busy: {
-            start: string;
-            end: string;
+            starts_at: string;
+            ends_at: string;
         }[];
         error?: string | undefined;
     })[];
     slots?: {
-        start: string;
-        end: string;
+        starts_at: string;
+        ends_at: string;
     }[] | undefined;
     unknown?: string[] | undefined;
     meta: {
@@ -78,7 +78,7 @@ export declare const busyAnswer: (source: CalendarSource, query: BusyQuery, opti
         timezone: string;
         complete: boolean;
         issues?: {
-            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
             reason?: string | undefined;
             source: string;
         }[] | undefined;

package/dist/calendar/busy.js

@@ -19,14 +19,14 @@ const bound = (field, side, example) => (node) => {
         queryError("query.unsupported-operator", node.span, `${field} takes only ${side === "lower" ? "the window's start" : "the window's end"}, such as ${example}`, { command: BUSY, guide: LIST_QUERY_GUIDE });
 };
 /**
- * `calendars busy`'s query: the window by the answer's own `start` and `end`, and whom to ask. `calendar` and
+ * `calendars busy`'s query: the window by the answer's own `starts_at` and `ends_at`, and whom to ask. `calendar` and
  * `person` repeat, and every one named is asked: the free stretches are those they all share.
  */
 export const BUSY_QUERY = {
     entity: "calendar_busy",
     backend: "native",
     fields: queryFieldsOf(calendarBusy, {
-        native: ["start", "end", "calendar", "person"],
+        native: ["starts_at", "ends_at", "calendar", "person"],
         relations: {
             calendar: {
                 type: "kw",
@@ -35,16 +35,16 @@ export const BUSY_QUERY = {
             },
             person: { type: "kw", example: "person:ana@example.com", relation: "someone else, by address; repeat for more" },
         },
-        examples: { start: "start>=2026-11-02", end: "end<=2026-11-06" },
+        examples: { starts_at: "starts_at>=2026-11-02", ends_at: "ends_at<=2026-11-06" },
         validate: {
-            start: bound("start", "lower", "start>=2026-11-02"),
-            end: bound("end", "upper", "end<=2026-11-06"),
+            starts_at: bound("starts_at", "lower", "starts_at>=2026-11-02"),
+            ends_at: bound("ends_at", "upper", "ends_at<=2026-11-06"),
         },
     }).map((field) => field.native
         ? { ...field, operators: field.type === "time" ? ["range"] : ["term", "phrase"] }
         : field),
 };
-export const BUSY_QUERY_NOTE = "\nWithout start: from the start of today, in your time zone. Without end: seven days after the start. " +
+export const BUSY_QUERY_NOTE = "\nWithout starts_at: from the start of today, in your time zone. Without ends_at: seven days after the start. " +
     "Without calendar: every calendar that syncs.";
 export const busyQuery = async (query, context) => {
     const { zone, now } = context;
@@ -56,9 +56,9 @@ export const busyQuery = async (query, context) => {
     const terms = nativeTermLists(listQuery(typedQuery(query), BUSY_QUERY, BUSY), BUSY, ["calendar", "person"]);
     for (const [field, nodes] of terms)
         for (const node of nodes) {
-            if (field === "start")
+            if (field === "starts_at")
                 from = timeWindow(node, zone, now).lower;
-            else if (field === "end")
+            else if (field === "ends_at")
                 to = timeWindow(node, zone, now).upper;
             else if (field === "calendar") {
                 const calendar = await calendarIn(context.store, context.accountId, node.value);
@@ -135,7 +135,7 @@ export const freeSlots = (busy, window, options) => {
     return slots;
 };
 const iso = (at) => new Date(at).toISOString();
-const times = ({ from, to }) => ({ start: iso(from), end: iso(to) });
+const times = ({ from, to }) => ({ starts_at: iso(from), ends_at: iso(to) });
 /**
  * `calendars busy`: the provider's busy times for the query, and with `slot` the free stretches every calendar and
  * person shares. Nothing is stored, and a person appears only by the address the caller gave.

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

@@ -38,8 +38,8 @@ export declare const calendarFeedRemoval: v.StrictObjectSchema<{
     readonly events: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
 }, undefined>;
 export declare const calendarBusy: v.StrictObjectSchema<{
-    readonly start: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
-    readonly end: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly starts_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly ends_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
     readonly timezone: v.StringSchema<undefined>;
     readonly calendars: v.ArraySchema<v.StrictObjectSchema<{
         /** One of the account's calendars, by its id; or `person`, by the address asked. */
@@ -47,14 +47,14 @@ export declare const calendarBusy: v.StrictObjectSchema<{
         readonly person: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly id: v.StringSchema<undefined>;
         readonly busy: v.ArraySchema<v.StrictObjectSchema<{
-            readonly start: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
-            readonly end: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+            readonly starts_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+            readonly ends_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
         }, undefined>, undefined>;
         readonly error: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>;
     readonly slots: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
-        readonly start: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
-        readonly end: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly starts_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly ends_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
     }, undefined>, undefined>, undefined>;
     readonly unknown: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
 }, undefined>;
@@ -505,8 +505,7 @@ export declare const calendarLinkResolution: v.StrictObjectSchema<{
     readonly chosen: v.NullableSchema<v.StringSchema<undefined>, undefined>;
 }, undefined>;
 /**
- * Each command's answer entity: one item of a list, or the one value. They describe what a host prints, with the
- * keys in snake_case, though a command hands its host some keys in camelCase (`notSynced`, `hasMore`).
+ * Each command's answer entity: one item of a list, or the one value, as the command prints it.
  */
 export declare const declareCalendarAnswers: (program: Command, commands: readonly Command[]) => void;
 export declare const CALENDAR_ANSWER_PATHS: string[];

package/dist/calendar/cli/answers.js

@@ -7,7 +7,7 @@ import { count, id, reference, text, time, untrusted } from "../../entities/fiel
 import { event } from "../../meetings/index.js";
 const nullableText = v.nullable(text);
 const nullableTime = v.nullable(time);
-const stretch = v.strictObject({ start: time, end: time });
+const stretch = v.strictObject({ starts_at: time, ends_at: time });
 const epochWindow = v.strictObject({ from: v.number(), to: v.number() });
 export const calendar = v.strictObject({
     id,
@@ -32,8 +32,8 @@ const busyRow = v.strictObject({
     error: v.optional(text),
 });
 export const calendarBusy = v.strictObject({
-    start: time,
-    end: time,
+    starts_at: time,
+    ends_at: time,
     timezone: text,
     calendars: v.array(busyRow),
     slots: v.optional(v.array(stretch)),
@@ -274,8 +274,7 @@ const ANSWERS = {
     "links resolve": { name: "calendar_link_resolution", schema: calendarLinkResolution },
 };
 /**
- * Each command's answer entity: one item of a list, or the one value. They describe what a host prints, with the
- * keys in snake_case, though a command hands its host some keys in camelCase (`notSynced`, `hasMore`).
+ * Each command's answer entity: one item of a list, or the one value, as the command prints it.
  */
 export const declareCalendarAnswers = (program, commands) => {
     const pathOf = (command) => {

package/dist/calendar/cli/bodies.d.ts

@@ -0,0 +1,33 @@
+import type { NextStep } from "@wirecat/cli-base/standards";
+import type { Command } from "commander";
+import { type Body } from "../../cli/envelope.js";
+import type { MessageStore } from "../../store/store.js";
+import type { CalendarRun } from "./index.js";
+/** The command's words below the program, as `page.next` and `sync`'s next step rerun it. */
+export declare const pathOf: (command: Command) => string[];
+interface Listed {
+    items: object[];
+    page?: number;
+    limit?: number;
+    hasMore?: boolean;
+}
+/** A list the shared reads answer (`listed`), as the envelope: `page.next` reruns the same query one page on. */
+export declare const listBody: (command: Command, { items, page, limit, hasMore }: Listed, meta?: object) => Body;
+export declare const itemBody: (value: object, extra?: {
+    meta?: object;
+    next?: NextStep[];
+}) => Body;
+interface Hits {
+    hits: object[];
+    has_more?: boolean;
+    next_offset?: number;
+    meaning_skipped?: string;
+    untrusted?: string[];
+}
+/**
+ * A search's hits as a list with cursor paging (WC-OUT-4, WC-OUT-5); each hit names its own untrusted fields, as
+ * `events list` does. Without a cursor there is no next page to run: the provider's search pages per calendar.
+ */
+export declare const hitsBody: (command: Command, value: Hits) => Body;
+export declare const messagesOf: (run: CalendarRun, what: string) => MessageStore;
+export {};

package/dist/calendar/cli/bodies.js

@@ -0,0 +1,52 @@
+import { CliError } from "@wirecat/cli-base";
+import { itemOf, listOf, snakeKeys } from "../../cli/envelope.js";
+/** The command's words below the program, as `page.next` and `sync`'s next step rerun it. */
+export const pathOf = (command) => command.parent?.parent ? [...pathOf(command.parent), command.name()] : [command.name()];
+const snakeMeta = (meta) => meta === undefined ? undefined : snakeKeys(meta);
+/** A list the shared reads answer (`listed`), as the envelope: `page.next` reruns the same query one page on. */
+export const listBody = (command, { items, page, limit, hasMore }, meta) => {
+    const query = command.processedArgs[0];
+    const facts = snakeMeta(meta);
+    return listOf(pathOf(command).join(" "), {
+        items: items.map((item) => snakeKeys(item)),
+        limit: Math.max(1, limit ?? items.length),
+        has_more: hasMore === true,
+        ...(page === undefined ? {} : { page }),
+        ...(Array.isArray(query) && query.length > 0 ? { args: { query } } : {}),
+        ...(facts ? { meta: facts } : {}),
+    });
+};
+export const itemBody = (value, extra = {}) => {
+    const meta = snakeMeta(extra.meta);
+    return itemOf(snakeKeys(value), { ...(meta ? { meta } : {}), ...(extra.next ? { next: extra.next } : {}) });
+};
+/**
+ * A search's hits as a list with cursor paging (WC-OUT-4, WC-OUT-5); each hit names its own untrusted fields, as
+ * `events list` does. Without a cursor there is no next page to run: the provider's search pages per calendar.
+ */
+export const hitsBody = (command, value) => {
+    const opts = command.opts();
+    const untrusted = (value.untrusted ?? []).filter((field) => field.startsWith("hits.")).map((f) => f.slice(5));
+    const { next, ...list } = listOf(pathOf(command).join(" "), {
+        items: value.hits.map((hit) => snakeKeys({ ...hit, untrusted })),
+        limit: opts.limit,
+        has_more: value.has_more === true,
+        paging: "cursor",
+        ...(typeof value.next_offset === "number" ? { cursor: String(value.next_offset) } : {}),
+        args: {
+            query: command.processedArgs[0],
+            ...(opts.exact ? { exact: true } : {}),
+            ...(opts.newest ? { newest: true } : {}),
+        },
+        ...(typeof value.meaning_skipped === "string"
+            ? { missing: [{ field: "items", why: `not searched by meaning: ${value.meaning_skipped}` }] }
+            : {}),
+    });
+    const kept = typeof value.next_offset === "number" ? next : next?.filter((one) => one.step !== "page.next");
+    return { ...list, ...(kept?.length ? { next: kept } : {}) };
+};
+export const messagesOf = (run, what) => {
+    if (!run.messages)
+        throw new CliError("configuration_error", `${what} needs the shared store`);
+    return run.messages;
+};

package/dist/calendar/cli/files.d.ts

@@ -0,0 +1,8 @@
+/** The largest .ics file `events import` reads; checked before the file is read whole. */
+export declare const ICS_MAX_BYTES: number;
+export declare const readIcsFile: (path: string) => Promise<string>;
+/**
+ * 0600 even over an existing file, written whole or not at all: an export holds the owner's meetings, attendees and
+ * descriptions. writeSecurely would make a missing folder; an export names one that exists.
+ */
+export declare const writeIcsFile: (path: string, content: string) => Promise<void>;

package/dist/calendar/cli/files.js

@@ -0,0 +1,41 @@
+import { readFile, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { CliError, writeSecurely } from "@wirecat/cli-base";
+/** The largest .ics file `events import` reads; checked before the file is read whole. */
+export const ICS_MAX_BYTES = 10 * 1024 * 1024;
+const FILE_ERRORS = {
+    ENOENT: ["not_found", "file.not-found", "does not exist"],
+    ENOTDIR: ["not_found", "file.not-found", "is not in a folder that exists"],
+    EISDIR: ["validation_error", "file.not-a-file", "is a folder, not a file"],
+    EACCES: ["permission_error", "file.denied", "cannot be opened: permission denied"],
+    EPERM: ["permission_error", "file.denied", "cannot be opened: permission denied"],
+};
+/** A file the owner named that cannot be read or written is their error, named by its path, never a crash. */
+const named = async (path, act) => {
+    try {
+        return await act();
+    }
+    catch (error) {
+        const known = FILE_ERRORS[error.code ?? ""];
+        if (!known)
+            throw error;
+        const [code, reason, words] = known;
+        throw new CliError(code, `${path} ${words}`, { reason });
+    }
+};
+export const readIcsFile = (path) => named(path, async () => {
+    const info = await stat(path);
+    if (!info.isFile())
+        throw new CliError("validation_error", `${path} is not a file`, { reason: "file.not-a-file" });
+    if (info.size > ICS_MAX_BYTES)
+        throw new CliError("validation_error", `${path} is larger than 10 MB`, { reason: "ics.too-large" });
+    return readFile(path, "utf8");
+});
+/**
+ * 0600 even over an existing file, written whole or not at all: an export holds the owner's meetings, attendees and
+ * descriptions. writeSecurely would make a missing folder; an export names one that exists.
+ */
+export const writeIcsFile = (path, content) => named(path, async () => {
+    await stat(dirname(path));
+    writeSecurely(path, content, 0o600);
+});

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

@@ -1,70 +1,77 @@
 import { type Command } from "commander";
+import { type Body } from "../../cli/envelope.js";
 import type { EventStore } from "../../meetings/index.js";
 import type { AppIdentity } from "../../ports/app.js";
 import type { AccountKey, MessageStore } from "../../store/store.js";
 import { type CalendarFeeds } from "../feeds.js";
 import type { CalendarExpander, CalendarSource } from "../source.js";
 import { type CalendarWrites } from "../writes.js";
-export interface CalendarCommandDeps {
-    store: EventStore;
-    /** The selected profile's calendar account: every command reads and syncs only it. */
-    accountId: number;
-    /** The same account as the shared store names it, for search and people. */
+/**
+ * The selected profile's calendar, opened by the app for one command and closed once its answer is built, before
+ * anything is printed (WC-LIFE-4). Nothing of it outlives the command, so concurrent runs share no state (WC-ARCH-22).
+ */
+export interface CalendarRun {
+    /** The profile's name, which `store status` gives as each sync's `profile`. */
+    profile: string;
+    /** The profile's calendar account as the shared store names it: every command reads and syncs only it. */
     account: AccountKey;
-    /** The profile's name, which `status` gives as each sync's `profile`. */
-    profile?: string;
-    /** The shared store: `search`, `people link` and the person of an attendee read it. */
+    accountId: number;
+    store: EventStore;
+    /** The shared store: `search`, `people link`, `--source` and an attendee's person read it. */
     messages?: MessageStore;
-    /** The provider; `sync` and `calendars list` read it. */
-    source?: CalendarSource;
-    /**
-     * The source answers `freeBusy`: mounts `calendars busy`. A flag rather than a look at `source`, which a CLI may
-     * build only once a profile is open.
-     */
-    freeBusy?: boolean;
-    /**
-     * The source answers `search`: `search` takes `--backend server` and asks the provider. A flag, as `freeBusy`, so the
-     * source can stay unbuilt until a profile is open.
-     */
-    serverSearch?: boolean;
+    /** The provider, built on first use: a command that only reads the store never reads the sign-in. */
+    source: () => CalendarSource;
+    /** The provider's writer and the profile's guard, for the write commands. */
+    writes?: () => CalendarWrites;
+    /** The iCalendar feeds the profile follows; `sync` and `calendars list` read them after the provider. */
+    feeds?: () => CalendarFeeds;
     /** For a source with `expands: "local"`. */
     expand?: CalendarExpander;
+    env?: NodeJS.ProcessEnv;
     /**
-     * The iCalendar feeds the profile follows, as read-only calendars of its account: mounts `calendars add|remove`,
-     * and `sync` and `calendars list` read them after the provider. Read only once a profile is open.
-     */
-    feeds?: CalendarFeeds;
-    /** After `sync --embed`: embeds new events for search by meaning (`embedEvents`), as drive's `sync --embed`. */
-    embed?: (max: number) => Promise<{
-        model: string;
-        embedded: number;
-        left: boolean;
-    }>;
-    /**
-     * `view` is the text a person reads in place of the default rendering: the times on the zone's wall clock, and the
-     * zone named. It takes the host's own body (`renderAnswer` passes it) or, without one, renders `value`.
+     * A profile lock pins the process (WC-ACCT-5): `events list --source` may then read only the profile's account, and
+     * `links review` lists only its choices.
      */
-    write: (value: unknown, format: "json" | "jsonl" | "text", view?: (body?: unknown) => string) => void;
-    /** A line for the person beside the answer, never in it: which accounts `search all` read and which it skipped. */
-    note?: (text: string) => void;
+    locked?: boolean;
+    close?: () => Promise<void>;
+}
+/** What the provider can do, known when the commands are built, before any profile is open. */
+export interface CalendarCommandOptions {
+    /** The CLI itself: the first word of examples, the store's command name, and `search all`. */
+    app: AppIdentity;
     /**
-     * The CLI itself. With it and `messages`, `search` also has `all`: messages, notes, events and named meetings in the
-     * shared store, as a messenger's `search all`.
+     * Opens the selected profile's calendar for one command. `readOnly` is true when the command only reads the store, so
+     * parallel reads take no write lock; the app may still open it writable, for a profile's first run say.
      */
-    app?: AppIdentity;
+    open: (command: Command, access: {
+        readOnly: boolean;
+    }) => Promise<CalendarRun>;
+    /** The source answers `freeBusy`: mounts `calendars busy`. */
+    freeBusy?: boolean;
+    /** The source answers `search`: `search events` takes `--backend server|both`. */
+    serverSearch?: boolean;
+    /** The profile may follow iCalendar feeds: mounts `calendars add|remove`. */
+    feeds?: boolean;
+    /** The provider takes writes: mounts `events create|update|delete|respond|remind`, and what its writer adds. */
+    writes?: {
+        quickAdd?: boolean;
+        move?: boolean;
+        importEvent?: boolean;
+    };
+    /** Reads `events import`'s file; a file on disk, at most 10 MB, when absent. */
+    readFile?: (path: string) => Promise<string>;
+    /** Writes `events export --output`'s file; owner-only (0600), whole or not at all, when absent. */
+    writeFile?: (path: string, content: string) => Promise<void>;
     now?: () => number;
     /** The zone `today`, `week` and a bare date are read in; the computer's when absent. */
     timezone?: string;
-    /** The provider's writer and the profile's guard: `events create|update|delete|respond` exist only with it. */
-    writes?: CalendarWrites;
-    /** Writes `events export --output`'s file; without it the export is printed only. */
-    writeFile?: (path: string, content: string) => Promise<void>;
-    /** Reads `events import`'s file; without it, and the writer's `import`, there is no `events import`. */
-    readFile?: (path: string) => Promise<string>;
-    /**
-     * A profile lock pins the process (WC-ACCT-5): `events list --source` may then read only the profile's account, and
-     * `links review` lists only its choices.
-     */
-    locked?: boolean;
 }
-export declare const addCalendarCommands: (program: Command, deps: CalendarCommandDeps) => void;
+/** Opens the profile for one command, builds its answer and prints it once the profile is closed. */
+export type Within = (command: Command, work: (run: CalendarRun) => Promise<Body>, view?: (body: Body) => string) => Promise<void>;
+export interface CommandHelpers {
+    within: Within;
+    now: () => number;
+    zone: () => string;
+    example: (command: Command, ...lines: string[]) => Command;
+}
+export declare const addCalendarCommands: (program: Command, options: CalendarCommandOptions) => void;